define positional arguments via .meta (#132)

Allow defining positional arguments via `z.string().meta({positional:
true})` as an alternative to awkward `z.tuple(...)` setups

Author: mmkal

README.md

@@ -295,7 +295,31 @@ const router = t.router({
 
 #### Both
 
-To use positional arguments _and_ options, use a tuple with an object at the end:
+To use positional arguments _and_ options, the preferred way is to use input schema metadata (e.g. `z.string().meta({positional: true})`. This is available on zod v4, and arktype via `type('string').configure({positional: true})`):
+
+```ts
+t.router({
+  copy: t.procedure
+    .input(
+      z.object({
+        source: z.string().meta({positional: true}),
+        target: z.string().meta({positional: true}),
+        mkdirp: z
+          .boolean()
+          .optional()
+          .describe("Ensure target's parent directory exists before copying"),
+      }),
+    )
+    .mutation(async ({input: [source, target, opts]}) => {
+      if (opts.mkdirp) {
+        await fs.mkdir(path.dirname(target, {recursive: true}))
+      }
+      await fs.copyFile(source, target)
+    }),
+})
+```
+
+2) use a tuple with an object at the end (use this if you're on an old version of zod, or using a library which doesn't support `meta`):
 
 ```ts
 t.router({
@@ -327,7 +351,7 @@ You might use the above with a command like:
 path/to/cli copy a.txt b.txt --mkdirp
 ```
 
->Note: object types for options must appear _last_ in the `.input(...)` tuple, when being used with positional arguments. So `z.tuple([z.string(), z.object({mkdirp: z.boolean()}), z.string()])` would not be allowed.
+>Note: when using a tuple, object types for options must appear _last_ in the `.input(...)` tuple, when being used with positional arguments. So `z.tuple([z.string(), z.object({mkdirp: z.boolean()}), z.string()])` would not be allowed (inputs would have to be passed as JSON).
 
 >You can pass an existing tRPC router that's primarily designed to be deployed as a server, in order to invoke your procedures directly in development.
 
@@ -427,7 +451,7 @@ const router = t.router({
 ### API docs
 
 <!-- codegen:start {preset: markdownFromJsdoc, source: src/index.ts, export: createCli} -->
-#### [createCli](./src/index.ts#L168)
+#### [createCli](./src/index.ts#L186)
 
 Run a trpc router as a CLI.
 

src/index.ts

@@ -38,6 +38,24 @@ export * as zod from 'zod'
 
 export * as trpcServer from '@trpc/server'
 
+declare module 'zod/v4' {
+  interface GlobalMeta {
+    /**
+     * If true, this property will be mapped to a positional CLI argument by trpc-cli. Only valid for string, number, or boolean types (or arrays of these types).
+     * Note: the order of positional arguments is determined by the order of properties in the schema.
+     * For example, the following are different:
+     * - `z.object({abc: z.string().meta({positional: true}), xyz: z.string().meta({positional: true})})`
+     * - `z.object({xyz: z.string().meta({positional: true}), abc: z.string().meta({positional: true})})`
+     */
+    positional?: boolean
+    /**
+     * If set, this value will be used an alias for the option.
+     * Note: this is only valid for options, not positional arguments.
+     */
+    alias?: string
+  }
+}
+
 export class Command extends BaseCommand {
   /** @internal track the commands that have been run, so that we can find the `__result` of the last command */
   __ran: Command[] = []

src/parse-procedure.ts

@@ -42,6 +42,60 @@ function looksLikeJsonSchema(value: unknown): value is JSONSchema7 & {type: stri
 }
 
 export function parseProcedureInputs(inputs: unknown[], dependencies: Dependencies): Result<ParsedProcedure> {
+  const inner = parseProcedureInputsInner(inputs, dependencies)
+  if (inner.success && inner.value.positionalParameters.some((param, i, {length}) => param.array && i < length - 1)) {
+    return {success: false, error: `Array positional parameters must be at the end of the input.`}
+  }
+
+  if (inner.success) {
+    const optionsProps = schemaDefPropValue(inner.value.optionsJsonSchema as JSONSchema7, 'properties')
+    if (optionsProps) {
+      const optionishPositionals = Object.entries(optionsProps).flatMap(([key, schema]) => {
+        if (typeof schema === 'object' && 'positional' in schema && schema.positional === true) {
+          return [{key, schema}]
+        }
+        return []
+      })
+
+      if (optionishPositionals.length > 0) {
+        return {
+          success: true,
+          value: {
+            positionalParameters: [
+              ...inner.value.positionalParameters,
+              ...optionishPositionals.map(({key, schema}): (typeof inner.value.positionalParameters)[number] => ({
+                name: key,
+                array: looksLikeArray(schema),
+                description: schema.description ?? '',
+                required: !isOptional(schema),
+                type: getSchemaTypes(schema).join(' | '),
+              })),
+            ],
+            optionsJsonSchema: {
+              ...inner.value.optionsJsonSchema,
+              properties: Object.fromEntries(
+                Object.entries(optionsProps).filter(([key]) => !optionishPositionals.some(x => x.key === key)),
+              ),
+            } as JSONSchema7,
+            getPojoInput: params => {
+              const positionalValues = [...params.positionalValues]
+              const options = {...params.options}
+              for (const {key, schema} of optionishPositionals) {
+                options[key] = convertPositional(schema, positionalValues.shift() as string)
+              }
+
+              return inner.value.getPojoInput({positionalValues, options})
+            },
+          },
+        }
+      }
+    }
+  }
+
+  return inner
+}
+
+function parseProcedureInputsInner(inputs: unknown[], dependencies: Dependencies): Result<ParsedProcedure> {
   if (inputs.length === 0) {
     return {
       success: true,
@@ -83,25 +137,6 @@ function handleMergedSchema(mergedSchema: JSONSchema7): Result<ParsedProcedure>
     return {success: false, error: `Inputs with additional properties are not currently supported`}
   }
 
-  if (mergedSchema.type === 'string') {
-    return {
-      success: true,
-      value: {
-        positionalParameters: [
-          {
-            type: 'string',
-            array: false,
-            description: mergedSchema.description || '',
-            name: mergedSchema.title || 'string',
-            required: !isOptional(mergedSchema),
-          },
-        ],
-        optionsJsonSchema: {},
-        getPojoInput: argv => argv.positionalValues[0] as string,
-      },
-    }
-  }
-
   if (acceptedPrimitiveTypes(mergedSchema).length > 0) {
     return parsePrimitiveInput(mergedSchema)
   }
@@ -202,8 +237,26 @@ function acceptedPrimitiveTypes(schema: JSONSchema7Definition): Array<(typeof pr
   return primitiveCandidateTypes.filter(c => acceptedJsonSchemaTypes.has(c))
 }
 
+/**
+ * From a list of schemas, if they are all record-style schemas, return a single schema with all properties (an intersection).
+ * Returns `null` if the schemas are not all record-style schemas.
+ */
+function maybeMergeObjectSchemas(schemas: JSONSchema7[]): JSONSchema7 | null {
+  const required: string[] = []
+  const properties: Record<string, JSONSchema7> = {}
+  for (const schema of schemas) {
+    if (!schema) return null
+    const {required: schemaRequired, properties: schemaProperties, type, $schema, ...rest} = schema
+    if (type && type !== 'object') return null
+    if (Object.keys(rest).length) return null
+    if (schemaRequired) required.push(...schemaRequired)
+    if (schemaProperties) Object.assign(properties, schemaProperties)
+  }
+  return {type: 'object', required, properties}
+}
+
 function parseMultiInputs(inputs: unknown[], dependencies: Dependencies): Result<ParsedProcedure> {
-  const parsedIndividually = inputs.map(input => parseProcedureInputs([input], dependencies))
+  const parsedIndividually = inputs.map(input => parseProcedureInputsInner([input], dependencies))
 
   const failures = parsedIndividually.flatMap(p => (p.success ? [] : [p.error]))
   if (failures.length > 0) {
@@ -218,6 +271,20 @@ function parseMultiInputs(inputs: unknown[], dependencies: Dependencies): Result
     }
   }
 
+  const merged = maybeMergeObjectSchemas(
+    parsedIndividually.map(p => (p.success ? (p.value.optionsJsonSchema as JSONSchema7) : {})),
+  )
+  if (merged) {
+    return {
+      success: true,
+      value: {
+        positionalParameters: [],
+        optionsJsonSchema: merged,
+        getPojoInput: argv => argv.options,
+      },
+    }
+  }
+
   return {
     success: true,
     value: {

test/arktype.test.ts

@@ -22,11 +22,11 @@ test('merging input types', async () => {
       .input(type({bar: 'string'}))
       .input(type({baz: 'number'}))
       .input(type({qux: 'boolean'}))
-      .query(({input}) => Object.entries(input).join(', ')),
+      .query(({input}) => JSON.stringify({bar: input.bar, baz: input.baz, qux: input.qux})),
   })
 
   expect(await run(router, ['foo', '--bar', 'hello', '--baz', '42', '--qux'])).toMatchInlineSnapshot(
-    `"bar,hello, baz,42, qux,true"`,
+    `"{"bar":"hello","baz":42,"qux":true}"`,
   )
 })
 
@@ -390,6 +390,38 @@ test('mixed array input', async () => {
   expect(result).toMatchInlineSnapshot(`"list: [12,true,3.14,"null","undefined","hello"]"`)
 })
 
+test('number then string array input', async () => {
+  const router = t.router({
+    test: t.procedure
+      .input(type(['number', 'string[]'])) //
+      .query(({input}) => `list: ${JSON.stringify(input)}`),
+  })
+
+  expect(await run(router, ['test', '123', 'hello', 'world'])).toMatchInlineSnapshot(`"list: [123,["hello","world"]]"`)
+})
+
+test('string array then number input (downgrades to json input)', async () => {
+  const router = t.router({
+    test: t.procedure
+      .input(type(['string[]', 'number'])) //
+      .query(({input}) => `list: ${JSON.stringify(input)}`),
+  })
+
+  expect(await run(router, ['test', '--help'], {expectJsonInput: true})).toMatchInlineSnapshot(`
+    "Usage: program test [options]
+
+    Options:
+      --input [json]  Input formatted as JSON (procedure's schema couldn't be
+                      converted to CLI arguments: Array positional parameters must
+                      be at the end of the input.)
+      -h, --help      display help for command
+    "
+  `)
+  expect(
+    await run(router, ['test', '--input', '[["hello","world"], 123]'], {expectJsonInput: true}),
+  ).toMatchInlineSnapshot(`"list: [["hello","world"],123]"`)
+})
+
 test('record input', async () => {
   const router = t.router({
     test: t.procedure

test/json.test.ts

@@ -1,7 +1,7 @@
 import {expect, test} from 'vitest'
 
 import {createCli, trpcServer, z} from '../src'
-import {router} from './fixtures/migrations'
+import {router as migrationsRouter} from './fixtures/migrations'
 
 expect.addSnapshotSerializer({
   test: () => true,
@@ -83,7 +83,7 @@ test('simple toJSON', async () => {
 })
 
 test('migrations toJSON', async () => {
-  const json = createCli({router}).toJSON()
+  const json = createCli({router: migrationsRouter}).toJSON()
   expect(json).toMatchInlineSnapshot(`
     {
       "description": "Available subcommands: up, create, list, search",
@@ -201,11 +201,11 @@ test('migrations toJSON', async () => {
                 },
                 {
                   "name": "name",
-                  "required": false,
-                  "optional": true,
+                  "required": true,
+                  "optional": false,
                   "negate": false,
                   "variadic": false,
-                  "flags": "--name [string]",
+                  "flags": "--name <string>",
                   "attributeName": "name"
                 }
               ],
@@ -233,11 +233,11 @@ test('migrations toJSON', async () => {
                 },
                 {
                   "name": "search-term",
-                  "required": false,
-                  "optional": true,
+                  "required": true,
+                  "optional": false,
                   "negate": false,
                   "variadic": false,
-                  "flags": "-q, --search-term [string]",
+                  "flags": "-q, --search-term <string>",
                   "short": "-q",
                   "description": "Only show migrations whose \`content\` value contains this string",
                   "attributeName": "searchTerm"

test/valibot.test.ts

@@ -19,11 +19,11 @@ test('merging input types', async () => {
       .input(v.object({bar: v.string()}))
       .input(v.object({baz: v.number()}))
       .input(v.object({qux: v.boolean()}))
-      .query(({input}) => Object.entries(input).join(', ')),
+      .query(({input}) => JSON.stringify({bar: input.bar, baz: input.baz, qux: input.qux})),
   })
 
   expect(await run(router, ['foo', '--bar', 'hello', '--baz', '42', '--qux'])).toMatchInlineSnapshot(
-    `"bar,hello, baz,42, qux,true"`,
+    `"{"bar":"hello","baz":42,"qux":true}"`,
   )
 })
 
@@ -398,6 +398,38 @@ test('mixed array input', async () => {
   expect(result).toMatchInlineSnapshot(`"list: [12,true,3.14,"null","undefined","hello"]"`)
 })
 
+test('number then string array input', async () => {
+  const router = t.router({
+    test: t.procedure
+      .input(v.tuple([v.number(), v.array(v.string())])) //
+      .query(({input}) => `list: ${JSON.stringify(input)}`),
+  })
+
+  expect(await run(router, ['test', '123', 'hello', 'world'])).toMatchInlineSnapshot(`"list: [123,["hello","world"]]"`)
+})
+
+test('string array then number input (downgrades to json input)', async () => {
+  const router = t.router({
+    test: t.procedure
+      .input(v.tuple([v.array(v.string()), v.number()])) //
+      .query(({input}) => `list: ${JSON.stringify(input)}`),
+  })
+
+  expect(await run(router, ['test', '--help'], {expectJsonInput: true})).toMatchInlineSnapshot(`
+    "Usage: program test [options]
+
+    Options:
+      --input [json]  Input formatted as JSON (procedure's schema couldn't be
+                      converted to CLI arguments: Array positional parameters must
+                      be at the end of the input.)
+      -h, --help      display help for command
+    "
+  `)
+  expect(
+    await run(router, ['test', '--input', '[["hello","world"], 123]'], {expectJsonInput: true}),
+  ).toMatchInlineSnapshot(`"list: [["hello","world"],123]"`)
+})
+
 test('record input', async () => {
   const router = t.router({
     test: t.procedure