feat: add support for multiPositional

playground/hello.ts

@@ -29,6 +29,11 @@ const command = defineCommand({
       default: "awesome",
       required: false,
     },
+    likes: {
+      type: "multiPositional",
+      description: "Most liked things",
+      default: ["orange", "strawberry"],
+    }
   },
   run({ args }) {
     consola.log(args);
@@ -37,6 +42,7 @@ const command = defineCommand({
       args.adj || "",
       args.name,
       args.age ? `You are ${args.age} years old.` : "",
+      args.likes?.length ? `You like ${args.likes.join(", ")}.` : "",
     ]
       .filter(Boolean)
       .join(" ");

src/args.ts

@@ -14,7 +14,7 @@ export function parseArgs<T extends ArgsDef = ArgsDef>(
     enum: [] as (number | string)[],
     mixed: [] as string[],
     alias: {} as Record<string, string | string[]>,
-    default: {} as Record<string, boolean | number | string>,
+    default: {} as Record<string, boolean | number | string | string[]>,
   };
 
   const args = resolveArgs(argsDef);
@@ -51,7 +51,19 @@ export function parseArgs<T extends ArgsDef = ArgsDef>(
 
   for (const [, arg] of args.entries()) {
     // eslint-disable-next-line unicorn/prefer-switch
-    if (arg.type === "positional") {
+    if (arg.type === "multiPositional") {
+      if (positionalArguments.length > 0) {
+        parsedArgsProxy[arg.name] = [...positionalArguments];
+        positionalArguments.length = 0;
+      } else if (arg.default === undefined && arg.required !== false) {
+        throw new CLIError(
+          `Missing required multiPositional argument: ${arg.name.toUpperCase()}`,
+          "EARG",
+        );
+      } else {
+        parsedArgsProxy[arg.name] = arg.default;
+      }
+    } else if (arg.type === "positional") {
       const nextPositionalArgument = positionalArguments.shift();
       if (nextPositionalArgument !== undefined) {
         parsedArgsProxy[arg.name] = nextPositionalArgument;

src/types.ts

@@ -6,11 +6,15 @@ export type ArgType =
   | "number"
   | "enum"
   | "positional"
+  | "multiPositional"
   | undefined;
 
 // Args: Definition
 
-export type _ArgDef<T extends ArgType, VT extends boolean | number | string> = {
+export type _ArgDef<
+  T extends ArgType,
+  VT extends boolean | number | string | string[],
+> = {
   type?: T;
   description?: string;
   valueHint?: string;
@@ -30,12 +34,17 @@ export type PositionalArgDef = Omit<
   _ArgDef<"positional", string>,
   "alias" | "options"
 >;
+export type MultiPositionalArgDef = Omit<
+  _ArgDef<"multiPositional", string[]>,
+  "alias" | "options"
+>;
 
 export type ArgDef =
   | BooleanArgDef
   | StringArgDef
   | NumberArgDef
   | PositionalArgDef
+  | MultiPositionalArgDef
   | EnumArgDef;
 
 export type ArgsDef = Record<string, ArgDef>;
@@ -59,6 +68,12 @@ type ParsedPositionalArg<T extends ArgDef> = T extends { type: "positional" }
   ? ResolveParsedArgType<T, string>
   : never;
 
+type ParsedMultiPositionalArg<T extends ArgDef> = T extends {
+  type: "multiPositional";
+}
+  ? ResolveParsedArgType<T, string[]>
+  : never;
+
 type ParsedStringArg<T extends ArgDef> = T extends { type: "string" }
   ? ResolveParsedArgType<T, string>
   : never;
@@ -87,6 +102,7 @@ type RawArgs = {
 // prettier-ignore
 type ParsedArg<T extends ArgDef> =
   T["type"] extends "positional" ? ParsedPositionalArg<T> :
+  T["type"] extends "multiPositional" ? ParsedMultiPositionalArg<T> :
   T["type"] extends "boolean" ? ParsedBooleanArg<T> :
   T["type"] extends "string" ? ParsedStringArg<T> :
   T["type"] extends "number" ? ParsedNumberArg<T> :

src/usage.ts

@@ -36,7 +36,18 @@ export async function renderUsage<T extends ArgsDef = ArgsDef>(
   const usageLine = [];
 
   for (const arg of cmdArgs) {
-    if (arg.type === "positional") {
+    if (arg.type === "multiPositional") {
+      const name = arg.name.toUpperCase();
+      const isRequired = arg.required !== false && arg.default === undefined;
+      // (isRequired ? " (required)" : " (optional)"
+      const defaultHint = arg.default ? `=[${arg.default}]` : "";
+      posLines.push([
+        "`" + name + defaultHint + "`",
+        arg.description || "",
+        arg.valueHint ? `<${arg.valueHint}>` : "",
+      ]);
+      usageLine.push(isRequired ? `<...${name}>` : `[...${name}]`);
+    } else if (arg.type === "positional") {
       const name = arg.name.toUpperCase();
       const isRequired = arg.required !== false && arg.default === undefined;
       // (isRequired ? " (required)" : " (optional)"

test/args.test.ts

@@ -68,6 +68,28 @@ describe("args", () => {
       { _: [], command: "subCommand" },
     ],
     [[], { command: { type: "positional", required: false } }, { _: [] }],
+    /**
+     * MultiPositional
+     */
+    [
+      ["subCommand1", "subCommand2"],
+      { command: { type: "multiPositional" } },
+      {
+        _: ["subCommand1", "subCommand2"],
+        command: ["subCommand1", "subCommand2"],
+      },
+    ],
+    [
+      [],
+      {
+        command: {
+          type: "multiPositional",
+          default: ["subCommand1", "subCommand2"],
+        },
+      },
+      { _: [], command: ["subCommand1", "subCommand2"] },
+    ],
+    [[], { command: { type: "multiPositional", required: false } }, { _: [] }],
     /**
      * Enum
      */
@@ -100,6 +122,13 @@ describe("args", () => {
       },
       "Missing required positional argument: NAME",
     ],
+    [
+      [],
+      {
+        name: { type: "multiPositional" },
+      },
+      "Missing required multiPositional argument: NAME",
+    ],
     [
       ["--value", "three"],
       { value: { type: "enum", options: ["one", "two"] } },

test/usage.test.ts

@@ -39,6 +39,11 @@ describe("usage", () => {
           name: "pos",
           description: "A pos",
         },
+        multiPositional: {
+          type: "multiPositional",
+          name: "pos",
+          description: "Multi positional",
+        },
         enum: {
           type: "enum",
           name: "enum",
@@ -58,11 +63,12 @@ describe("usage", () => {
     expect(usage).toMatchInlineSnapshot(`
       "A command (Commander)
 
-      USAGE \`Commander [OPTIONS] --foo <POS>\`
+      USAGE \`Commander [OPTIONS] --foo <POS> <...MULTIPOSITIONAL>\`
 
       ARGUMENTS
 
-        \`POS\`    A pos    
+                    \`POS\`    A pos               
+        \`MULTIPOSITIONAL\`    Multi positional    
 
       OPTIONS