find/replace Task -> Command

Author: trvswgnr

README.md

@@ -35,7 +35,7 @@ git clone https://github.com/trvswgnr/cmdctr.git
 
 ## Usage
 
-Command Center provides three main functions: `CmdCtr`, `Data`, and `Task`.
+Command Center provides three main functions: `CmdCtr`, `Data`, and `Command`.
 
 ### CmdCtr
 
@@ -73,13 +73,13 @@ const task1Data = Data({
 });
 ```
 
-### Task
+### Command
 
-`Task` creates a new task. It takes a data object and an action function as arguments. The action
+`Command` creates a new task. It takes a data object and an action function as arguments. The action
 function is what will be executed when the task is run.
 
 ```ts
-const task1 = Task(task1Data, (opts) => {
+const task1 = Command(task1Data, (opts) => {
     const { input, output } = opts;
     console.log(`input: ${input}`);
     console.log(`output: ${output}`);
@@ -88,7 +88,7 @@ const task1 = Task(task1Data, (opts) => {
 
 A nice feature here is the options passed to the action function (`opts` here) are validated from the CLI and their types are known at compile-time. This means you get meaningfull type hints and code completion in your editor and can be sure that the arguments are the types you're expecting.
 
-### Registering and Running Tasks
+### Registering and Running Commands
 
 After creating tasks, you can register them to the command center using the `register` method. Then,
 you can run the tasks using the `run` method.
@@ -116,7 +116,7 @@ Here is a complete example of how to use Command Center:
 
 ```ts
 // @ts-check
-import { CmdCtr, Data, Task } from "cmdctr";
+import { CmdCtr, Data, Command } from "cmdctr";
 import ora from "ora"; // loading spinner (for funzies)
 
 const cmdCtr = CmdCtr("example"); // or new CmdCtr(), if that's your thing
@@ -140,7 +140,7 @@ const task1Data = Data({
     },
 });
 
-const task1 = Task(task1Data, (opts) => {
+const task1 = Command(task1Data, (opts) => {
     const { input, output } = opts;
     console.log(`input: ${input}`);
     console.log(`output: ${output}`);
@@ -165,7 +165,7 @@ const task2Data = Data({
     },
 });
 
-const task2 = Task(task2Data, async (opts) => {
+const task2 = Command(task2Data, async (opts) => {
     const { message, loud } = opts;
     const loadingMsg = "...what was i saying again?";
     const spinner = ora(loadingMsg).start();

cmdctr.ts

@@ -1,32 +1,32 @@
 import type {
     CmdCtrInstance,
     DataInstance,
-    TaskInstance,
+    CommandInstance,
     CmdCtrConstructor,
     DataConstructor,
-    TaskConstructor,
+    CommandConstructor,
     Strict,
     Action,
     CmdCtrFn,
-    RegisteredTasks,
+    RegisteredCommands,
     DataFn,
-    TaskFn,
+    CommandFn,
 } from "./types";
 import { errExit, getCliArgs, getValidatedOpts } from "./lib";
 import { DEFAULT_TASK, TASK_NAME } from "./constants";
 
 const _CmdCtr: CmdCtrFn = (baseCommand) => {
-    const tasks: RegisteredTasks = new Map();
+    const tasks: RegisteredCommands = new Map();
     let data = typeof baseCommand === "string" ? tasks.get(baseCommand) : baseCommand;
     if (!data) return errExit`unknown task "${baseCommand}"`;
     tasks.set(DEFAULT_TASK, { ...data, isDefault: true });
     const name = typeof baseCommand === "string" ? baseCommand : data.name;
     const self: CmdCtrInstance = {
-        register: (task: TaskInstance) => tasks.set(task.name, task),
+        register: (task: CommandInstance) => tasks.set(task.name, task),
         run: (_args?: string[]) => {
             if (tasks.size === 0) return errExit`no tasks registered`;
             const args = getCliArgs(tasks, name, _args);
-            const taskName = args.usingDefaultTask ? DEFAULT_TASK : args[TASK_NAME];
+            const taskName = args.usingDefaultCommand ? DEFAULT_TASK : args[TASK_NAME];
             const data = tasks.get(taskName);
             if (!data) return errExit`unknown task "${taskName}"`;
             data.action(getValidatedOpts(data, args));
@@ -37,11 +37,16 @@ const _CmdCtr: CmdCtrFn = (baseCommand) => {
 
 const _Data: DataFn = <const D extends DataInstance>(data: Strict<D, DataInstance>) => data as D;
 
-const _Task: TaskFn = <const D extends DataInstance>(data: D, action: Action<D>) => ({
-    ...data,
-    action: (validatedOpts: any) => action(validatedOpts),
-});
+const _Command: CommandFn = <const D extends DataInstance>(data: D, action: Action<D>) => {
+    const registeredCommands: RegisteredCommands = new Map();
+    return {
+        ...data,
+        action: (validatedOpts: any) => action(validatedOpts),
+        register: (cmd: CommandInstance) => registeredCommands.set(cmd.name, cmd),
+        registeredCommands,
+    };
+};
 
 export const CmdCtr = _CmdCtr as CmdCtrConstructor;
 export const Data = _Data as DataConstructor;
-export const Task = _Task as TaskConstructor;
+export const Command = _Command as CommandConstructor;

examples/basic.js

@@ -1,5 +1,5 @@
 // @ts-check
-import { CmdCtr, Data, Task } from "cmdctr";
+import { CmdCtr, Data, Command } from "cmdctr";
 import ora from "ora"; // loading spinner (for funzies)
 
 const cmdCtr = CmdCtr("example"); // or new CmdCtr(), if that's your thing
@@ -23,7 +23,7 @@ const task1Data = Data({
     },
 });
 
-const task1 = Task(task1Data, (opts) => {
+const task1 = Command(task1Data, (opts) => {
     const { input, output } = opts;
     console.log(`input: ${input}`);
     console.log(`output: ${output}`);
@@ -48,7 +48,7 @@ const task2Data = Data({
     },
 });
 
-const task2 = Task(task2Data, async (opts) => {
+const task2 = Command(task2Data, async (opts) => {
     const { message, loud } = opts;
     const loadingMsg = "...what was i saying again?";
     const spinner = ora(loadingMsg).start();

index.ts

@@ -2,10 +2,10 @@ export type {
     CmdCtrConstructor,
     DataInstance,
     DataConstructor,
-    TaskInstance,
-    TaskConstructor,
+    CommandInstance,
+    CommandConstructor,
     Action,
-    RegisteredTasks,
-    TaskOption,
+    RegisteredCommands,
+    CommandOption,
 } from "./types";
 export * from "./cmdctr";

lib.ts

@@ -1,38 +1,38 @@
 import { parseArgs } from "node:util";
-import type { CliArgs, RegisteredTasks, TaskOption } from "./types";
+import type { CliArgs, RegisteredCommands, CommandOption } from "./types";
 import { DEFAULT_TASK, ParseError, TASK_NAME } from "./constants";
 
-export function getCliArgs(tasks: RegisteredTasks, name: string, _args?: string[]): CliArgs {
+export function getCliArgs(tasks: RegisteredCommands, name: string, _args?: string[]): CliArgs {
     const rawArgs = _args ?? process.argv.slice(2);
-    let usageBase = `\nUsage: ${name} <task> <options>\nTasks:\n`;
+    let usageBase = `\nUsage: ${name} <task> <options>\nCommands:\n`;
     const tasksList = [...tasks.values()]
         .map((task) => `  ${task.name}: ${task.description}`)
         .join("\n");
     let usage = usageBase + tasksList;
-    let taskNameRaw = rawArgs[0];
-    let usingDefaultTask = false;
+    let taskNameRaw = tryToGetTaskName(rawArgs, tasks);
+    let usingDefaultCommand = false;
     if (!taskNameRaw) {
         if (!tasks.has(DEFAULT_TASK)) {
             return errExit`missing task\n${usage}`;
         }
         taskNameRaw = tasks.get(DEFAULT_TASK)!.name;
-        usingDefaultTask = true;
+        usingDefaultCommand = true;
     }
     let taskName = taskNameRaw ?? "";
     if (!tasks.has(taskName)) {
         if (!tasks.has(DEFAULT_TASK)) {
             return errExit`missing task\n${usage}`;
         }
         taskName = tasks.get(DEFAULT_TASK)!.name;
-        usingDefaultTask = true;
+        usingDefaultCommand = true;
     }
     let task = tasks.get(taskName);
     if (!task) {
         if (!tasks.has(DEFAULT_TASK)) {
             return errExit`missing task\n${usage}`;
         }
         task = tasks.get(DEFAULT_TASK);
-        usingDefaultTask = true;
+        usingDefaultCommand = true;
     }
     if (!task) {
         return errExit`missing task\n${usage}`;
@@ -51,11 +51,11 @@ export function getCliArgs(tasks: RegisteredTasks, name: string, _args?: string[
             return usageOption;
         })
         .join("\n");
-    const nameAndTaskName = usingDefaultTask ? name : `${name} ${taskName}`;
-    usage = `\nUsage: ${nameAndTaskName} <options>\nOptions:\n`;
+    const nameAndCommandName = usingDefaultCommand ? name : `${name} ${taskName}`;
+    usage = `\nUsage: ${nameAndCommandName} <options>\nOptions:\n`;
     usage += usageOptions;
 
-    const taskArgs = usingDefaultTask ? rawArgs : rawArgs.slice(1);
+    const taskArgs = usingDefaultCommand ? rawArgs : rawArgs.slice(1);
     const taskConfig = {
         options,
         args: taskArgs,
@@ -64,14 +64,14 @@ export function getCliArgs(tasks: RegisteredTasks, name: string, _args?: string[
     try {
         parsed = parseArgs(taskConfig);
     } catch (e) {
-        const err = ParseError.from(e, usingDefaultTask ? name : taskName);
+        const err = ParseError.from(e, usingDefaultCommand ? name : taskName);
         return errExit`${err.message}\n${usage}`;
     }
     const args = parsed.values as Record<PropertyKey, unknown>;
     const errors: string[] = [];
     for (const _key in options) {
         const key = _key as keyof typeof options;
-        const option = options[key] ?? ({} as TaskOption);
+        const option = options[key] ?? ({} as CommandOption);
         if (!("required" in option) || !option.required) {
             args[key] ??= option.default;
         }
@@ -84,7 +84,23 @@ export function getCliArgs(tasks: RegisteredTasks, name: string, _args?: string[
         return errExit`missing required option${s} ${listify(errors)}\n${usage}`;
     }
 
-    return Object.assign(args, { [TASK_NAME]: taskName, usingDefaultTask });
+    return Object.assign(args, { [TASK_NAME]: taskName, usingDefaultCommand });
+}
+
+// task name could be the first argument, or it could be a series of commands and subcommands
+function tryToGetTaskName(args: string[], tasks: RegisteredCommands) {
+    if (args.length === 0) return null;
+    const firstArg = args[0] ?? "";
+    if (tasks.has(firstArg)) return firstArg;
+    const taskNames = [...tasks.keys()];
+    let taskName = "";
+    for (const arg of args) {
+        taskName += arg;
+        if (taskNames.includes(taskName)) return taskName;
+        taskName += " ";
+    }
+
+    return null;
 }
 
 /** validates the options passed to a task */

types.ts

@@ -1,19 +1,19 @@
-import { TASK_NAME } from "./constants";
+import { DEFAULT_TASK, TASK_NAME } from "./constants";
 
 export type CmdCtrInstance = {
-    register: (task: TaskInstance) => RegisteredTasks;
+    register: (task: CommandInstance) => RegisteredCommands;
     run: (args?: string[]) => void | Promise<void>;
 };
 
 export type CmdCtrConstructor = CmdCtrFn & CmdCtrClass;
-export type CmdCtrFn = (baseCommand?: TaskInstance | string) => CmdCtrInstance;
-type CmdCtrClass = new (baseCommand?: TaskInstance | string) => CmdCtrInstance;
+export type CmdCtrFn = (baseCommand?: CommandInstance | string) => CmdCtrInstance;
+type CmdCtrClass = new (baseCommand?: CommandInstance | string) => CmdCtrInstance;
 
 /** data for a task including its options and information about it */
 export type DataInstance = {
     name: StartsWithAlpha;
     description: string;
-    options: TaskOptions;
+    options: CommandOptions;
 };
 
 /** the constructor of a data object, which can be called with `new` or without */
@@ -34,22 +34,32 @@ type Alpha = AlphaLower | AlphaUpper;
 type StartsWithAlpha = Explicit<`${Alpha}${string}`>;
 
 /** a task that can be registered and run */
-export type TaskInstance = DataInstance & { action: (validatedOpts: any) => void };
+export type CommandInstance = DataInstance & {
+    action: (validatedOpts: any) => void;
+    register: (cmd: CommandInstance) => RegisteredCommands;
+};
 
 /** the constructor of a task, which can be called with `new` or without */
-export type TaskConstructor = TaskFn & TaskClass;
-export type TaskFn = <const D extends DataInstance>(data: D, action: Action<D>) => TaskInstance;
-type TaskClass = new <const D extends DataInstance>(data: D, action: Action<D>) => TaskInstance;
+export type CommandConstructor = CommandFn & CommandClass;
+export type CommandFn = <const D extends DataInstance>(
+    data: D,
+    action: Action<D>,
+) => CommandInstance;
+type CommandClass = new <const D extends DataInstance>(
+    data: D,
+    action: Action<D>,
+) => CommandInstance;
 
 /** the action function of a task */
 export type Action<T extends DataInstance> = (
     args: MaskOpts<ValidatedOpts<T>>,
 ) => void | Promise<void>;
 
-export type RegisteredTasks = Map<string | symbol, TaskInstance & { isDefault?: boolean }>;
+type CommandInstanceWithDefault = CommandInstance & { isDefault?: boolean };
+export type RegisteredCommands = Map<string | DEFAULT_TASK, CommandInstanceWithDefault>;
 
 /** the possible options for a task */
-export type TaskOptions = { [long: string]: TaskOption };
+export type CommandOptions = { [long: string]: CommandOption };
 
 type TypeLiteral = "string" | "boolean";
 type TypeLiteralToNative<T extends TypeLiteral> = {
@@ -64,14 +74,14 @@ type OptionItemDescriptor<T extends TypeLiteral> = {
     short?: Alpha;
     description: string;
 };
-type TaskOptionItem<T extends TypeLiteral, R extends boolean> = OptionItemDescriptor<T> &
+type CommandOptionItem<T extends TypeLiteral, R extends boolean> = OptionItemDescriptor<T> &
     OptionItemRequirement<T, R>;
 
-export type TaskOption =
-    | TaskOptionItem<"string", false>
-    | TaskOptionItem<"boolean", false>
-    | TaskOptionItem<"string", true>
-    | TaskOptionItem<"boolean", true>;
+export type CommandOption =
+    | CommandOptionItem<"string", false>
+    | CommandOptionItem<"boolean", false>
+    | CommandOptionItem<"string", true>
+    | CommandOptionItem<"boolean", true>;
 
 /** the validated options passed to the task action */
 type ValidatedOpts<T extends DataInstance> = OptionsFromData<T>;
@@ -83,7 +93,7 @@ type OptionsFromData<T extends DataInstance> = {
 
 /** the arguments passed to the CLI */
 export type CliArgs = Record<PropertyKey, unknown> & { [K in TASK_NAME]: string } & {
-    usingDefaultTask: boolean;
+    usingDefaultCommand: boolean;
 };
 
 /** widens the type `T` to be compatible with the type `U` if it has the same keys */
@@ -93,7 +103,7 @@ type Widen<T, U> = { [K in keyof T]: K extends keyof U ? U[K] : T[K] };
 export type Strict<T, U> = StrictHelper<T, U> & StrictHelper<U, T>;
 type StrictHelper<T, U> = U extends Widen<T, U> ? T : `ERROR: only known properties are allowed`;
 
-/** removes the `TaskNameKey` property from the type `T` */
+/** removes the `CommandNameKey` property from the type `T` */
 type MaskOpts<T> = T extends infer U
     ? { [K in keyof U as K extends TASK_NAME ? never : K]: U[K] }
     : never;