gem-hunter

zodest

Highlights

Installation

npm install zodest zod
# or
yarn add zodest zod
# or
pnpm add zodest zod
# or
bun add zodest zod

Quick Example

import { z } from 'zod';
import { defineCommand, defineConfig, defineOptions } from 'zodest/config';
import { processConfig } from 'zodest';

const globalOptions = defineOptions(
  z.object({
    verbose: z.boolean().default(false),
  }),
);

const config = defineConfig({
  globalOptions,
  commands: {
    serve: defineCommand({
      description: 'Start development server',
      options: defineOptions(
        z.object({
          port: z.coerce.number().min(1024).default(3000),
        }),
        { p: 'port' }, // aliases, type-safe with the schema
      ),
      args: z.array(z.string()),
      action(options, args) {
        console.log('Server starting on port', options.port);
      },
    }),
  },
});

// Process CLI arguments, returns the matching command
const result = processConfig(config, process.argv.slice(2));

console.log('result:', result._kind, result);
// => result._kind == 'serve', the matching command's name
// in `result` there's also `result.globalOptions`, and so on, all type-safe

// call the command
result.command.action(result.options, result.args);

Core Concepts

Commands

const myCommand = defineCommand({
  description: 'My command description',
  options: defineOptions(
    z.object({
      force: z.boolean().default(false),
    }),
  ),
  args: z.string().min(3),
  aliases: ['mc', 'mycmd'],
  action(options, args) {
    // Fully typed options and args
  },
});

Global Options

const globalOptions = defineOptions(
  z.object({
    debug: z.boolean().default(false),
    config: z.string().optional(),
  }),
  {
    d: 'debug', // aliases
    c: 'config',
  },
);

Nested Commands

const config = defineConfig({
  commands: {
    'user add': defineCommand({...}),
    'user remove': defineCommand({...}),
    'user list': defineCommand({...}),
  }
});

Shareable Command Presets

import { withGlobalOptions } from 'zodest/config';

const userCommands = withGlobalOptions(globalOptions, (gopts) => ({
  userAdd: defineCommand({...}),
  userRemove: defineCommand({...}),
}));

// Use in any CLI
const config = defineConfig({
  globalOptions,
  commands: (gopts) => ({
    ...userCommands(gopts),
    // Add more commands
  })
});

API Reference

defineConfig(config)

defineCommand(command)

defineOptions(schema, aliases?)

processConfig(config, argv)

withGlobalOptions(globalOptions, commands)

getCommands(config)

Advanced Examples

Command with Complex Arguments

const command = defineCommand({
  description: 'Complex command',
  options: defineOptions(
    z.object({
      mode: z.enum(['development', 'production']),
      port: z.coerce.number().min(1024),
    }),
  ),
  args: z.tuple([z.string(), z.coerce.number()]),
  action(options, [path, num]) {
    // path is string, num is number
  },
});

Default Commands

const config = defineConfig({
  defaultCommand: 'serve',
  commands: {
    serve: defineCommand({...})
    dev: defineCommand({...})
  }
});

Command Groups

const devCommands = withGlobalOptions(globalOptions, (gopts) => ({
  serve: defineCommand({...}),
  build: defineCommand({...}),
}));

const dbCommands = withGlobalOptions(globalOptions, (gopts) => ({
  'db migrate': defineCommand({...}),
  'db seed': defineCommand({...}),
}));

const config = defineConfig({
  globalOptions,
  commands: (gopts) => ({
    ...devCommands(gopts),
    ...dbCommands(gopts),
  })
});

License