icore 1.0.3 → 1.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icore",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Declarative command line interface mechanics for Node.js",
   "keywords": [
     "command-line",

package/readme.md

@@ -7,28 +7,9 @@
 
 Small dependency-free command line interface mechanics for [Node.js®](https://nodejs.org) applications.
 
-[API](#api) | [Option Schemas](#option-schemas) | [Type Inference](#type-inference)
-
-### How it works?
-
-![yuml diagram](http://yuml.me/diagram/scruffy;dir:LR;/class/[*argv*%20{bg:gray}|External;users%20get%20--limit%2010%20--json]->[*matches*%20{bg:lavender}|System;parse,%20resolve,%20validate,%20infer]->[*typed%20result*%20{bg:honeydew}|Container;command=users/get;%20limit=10;%20json=true]->[*your%20app*%20{bg:cornsilk}|System;business%20logic%20and%20output])
-
-Use `icore` when you need more than raw argument parsing:
-
-- typed command definitions;
-- command registry resolution;
-- required options;
-- string choices;
-- number parsing with integer, minimum, and maximum constraints;
-- option presence metadata;
-- typed command handler input.
-
-Use [`node:util.parseArgs`](https://nodejs.org/api/util.html#utilparseargsconfig)
-directly when you only need low-level argument parsing.
-
 ### Installation
 
-To use `icores` in your project, run:
+To use `icore` in your project, run:
 
 ```sh
 npm install icore
@@ -36,141 +17,27 @@ npm install icore
 
 ### Table of Contents
 
-- [`parseArgv(args, schema?)`](#parseargvargs-schema)
-- [`parseOptions(schema, values)`](#parseoptionsschema-values)
-- [`parseOptionsDetailed(schema, values)`](#parseoptionsdetailedschema-values)
-- [`defineCommand(command)`](#definecommandcommand)
-- [`defineCommandRegistry(commands)`](#definecommandregistrycommands)
-- [`isCommandName(registry, value)`](#iscommandnameregistry-value)
-- [`resolveCommand(registry, positionals)`](#resolvecommandregistry-positionals)
-- [`resolveCommandFromArgs(registry, args)`](#resolvecommandfromargsregistry-args)
-- [`runCommandFromRegistry(registry, args, context)`](#runcommandfromregistryregistry-args-context)
-- [`mergeOptionsSchema(...schemas)`](#mergeoptionsschemaschemas)
-- [`runCommand(command, args, context)`](#runcommandcommand-args-context)
-
-### Design Goals
-
-- describe CLI mechanics declaratively;
-- use literal option types: `type: 'string' | 'boolean' | 'number'`;
-- keep handlers free from repetitive option parsing;
-- keep domain and API semantics outside the framework;
-- provide predictable user-facing errors;
-- avoid runtime dependencies.
-
-#### Basic Usage
-
-```ts
-import { defineCommand, runCommand } from 'icore';
-
-const helloCommand = defineCommand({
-  path: ['hello'],
-  options: {
-    name: {
-      type: 'string',
-      default: 'world'
-    },
-    upper: {
-      type: 'boolean'
-    }
-  },
-  async handle({ options }) {
-    const message = `Hello, ${options.name}!`;
-
-    return options.upper ? message.toUpperCase() : message;
-  }
-});
-
-const output = await runCommand(
-  helloCommand,
-  ['hello', '--name', 'Stanislav', '--upper'],
-  {}
-);
-
-console.log(output);
-```
-
-The command handler receives parsed options, user-provided option metadata,
-remaining positionals, and caller provided context.
-
-CommonJS is supported:
-
-```js
-const {
-  defineCommand,
-  runCommand
-} = require('icore');
-```
-
-## Option Schemas
-
-Options are described as plain objects.
-
-Option names are exact. `icore` does not normalize camelCase to kebab-case or
-kebab-case to camelCase. Use quoted object keys when your public CLI option
-contains `-`.
-
-### String Options
-
-```ts
-const schema = {
-  token: {
-    type: 'string',
-    required: true
-  },
-  format: {
-    type: 'string',
-    choices: ['json', 'table'],
-    default: 'table'
-  }
-} as const;
-```
-
-String options reject missing required values, blank strings, boolean flag form,
-and values outside `choices`.
-
-### Boolean Options
-
-```ts
-const schema = {
-  insecure: {
-    type: 'boolean'
-  }
-} as const;
-```
-
-Boolean options accept flag form only:
-
-```sh
---insecure
-```
-
-Explicit values are rejected:
-
-```sh
---insecure true
---insecure=true
-```
-
-### Number Options
-
-```ts
-const schema = {
-  limit: {
-    type: 'number',
-    integer: true,
-    min: 1,
-    max: 1000,
-    default: 100
-  }
-} as const;
-```
-
-Number options parse decimal numeric values and can validate integer and range
-constraints. Defaults are validated with the same rules as user-provided values.
+* [API](#api)
+  * [`parseArgv(args, schema?)`](#parseargvargs-schema)
+  * [`parseOptions(schema, values)`](#parseoptionsschema-values)
+  * [`parseOptionsDetailed(schema, values)`](#parseoptionsdetailedschema-values)
+  * [`defineCommand(command)`](#definecommandcommand)
+  * [`defineCommandRegistry(commands)`](#definecommandregistrycommands)
+  * [`isCommandName(registry, value)`](#iscommandnameregistry-value)
+  * [`resolveCommand(registry, positionals)`](#resolvecommandregistry-positionals)
+  * [`resolveCommandFromArgs(registry, args)`](#resolvecommandfromargsregistry-args)
+  * [`runCommandFromRegistry(registry, args, context)`](#runcommandfromregistryregistry-args-context)
+  * [`mergeOptionsSchema(...schemas)`](#mergeoptionsschemaschemas)
+  * [`runCommand(command, args, context)`](#runcommandcommand-args-context)
+* [Example](#example)
+* [Option Schemas](#option-schemas)
+* [Type Inference](#type-inference)
+* [Facade of arguments](#facade-of-arguments)
+* [Error Messages](#error-messages)
 
 ### API
 
-### `parseArgv(args, schema?)`
+#### `parseArgv(args, schema?)`
 
 Parses raw CLI arguments into positionals and raw option values.
 
@@ -178,10 +45,10 @@ Parses raw CLI arguments into positionals and raw option values.
 import { parseArgv } from 'icore';
 
 const argv = parseArgv([
-  'users',
-  'get-accounts',
-  '--format=json',
-  '--insecure'
+  'hello',
+  '--name',
+  'User',
+  '--upper'
 ]);
 ```
 
@@ -189,10 +56,10 @@ Result:
 
 ```ts
 {
-  positionals: ['users', 'get-accounts'],
+  positionals: ['hello'],
   options: {
-    format: 'json',
-    insecure: true
+    name: 'User',
+    upper: true
   }
 }
 ```
@@ -202,12 +69,11 @@ options without consuming the following positional argument:
 
 ```ts
 const argv = parseArgv([
-  'users',
-  'get-accounts',
-  '--insecure',
-  'extra'
+  'hello',
+  '--upper',
+  'User'
 ], {
-  insecure: {
+  upper: {
     type: 'boolean'
   }
 });
@@ -217,14 +83,14 @@ Result:
 
 ```ts
 {
-  positionals: ['users', 'get-accounts', 'extra'],
+  positionals: ['hello', 'User'],
   options: {
-    insecure: true
+    upper: true
   }
 }
 ```
 
-### `parseOptions(schema, values)`
+#### `parseOptions(schema, values)`
 
 Validates raw option values using an option schema and returns typed options.
 
@@ -232,19 +98,16 @@ Validates raw option values using an option schema and returns typed options.
 import { parseOptions } from 'icore';
 
 const options = parseOptions({
-  format: {
+  name: {
     type: 'string',
-    choices: ['json', 'table'],
-    default: 'table'
+    default: 'world'
   },
-  depth: {
-    type: 'number',
-    integer: true,
-    min: 1,
-    required: true
+  upper: {
+    type: 'boolean'
   }
 } as const, {
-  depth: '10'
+  name: 'User',
+  upper: true
 });
 ```
 
@@ -252,12 +115,12 @@ Result:
 
 ```ts
 {
-  format: 'table',
-  depth: 10
+  name: 'User',
+  upper: true
 }
 ```
 
-### `parseOptionsDetailed(schema, values)`
+#### `parseOptionsDetailed(schema, values)`
 
 Validates raw option values and returns parsed options together with
 user-provided metadata.
@@ -266,17 +129,15 @@ user-provided metadata.
 import { parseOptionsDetailed } from 'icore';
 
 const result = parseOptionsDetailed({
-  token: {
+  name: {
     type: 'string',
-    required: true
+    default: 'world'
   },
-  format: {
-    type: 'string',
-    choices: ['json', 'table'],
-    default: 'table'
+  upper: {
+    type: 'boolean'
   }
 } as const, {
-  token: 'secret'
+  upper: true
 });
 ```
 
@@ -285,12 +146,12 @@ Result:
 ```ts
 {
   options: {
-    token: 'secret',
-    format: 'table'
+    name: 'world',
+    upper: true
   },
   provided: {
-    token: true,
-    format: false
+    name: false,
+    upper: true
   }
 }
 ```
@@ -298,7 +159,7 @@ Result:
 `provided` is useful when a default value and an omitted option have different
 application-level meaning.
 
-### `defineCommand(command)`
+#### `defineCommand(command)`
 
 Defines a command while preserving its option schema types.
 
@@ -306,36 +167,25 @@ Defines a command while preserving its option schema types.
 import { defineCommand } from 'icore';
 
 const command = defineCommand({
-  path: ['marketdata', 'get-order-book'],
+  path: ['hello'],
   options: {
-    'instrument-id': {
+    name: {
       type: 'string',
-      required: true
-    },
-    depth: {
-      type: 'number',
-      integer: true,
-      min: 1,
-      required: true
+      default: 'world'
     },
-    format: {
-      type: 'string',
-      choices: ['json', 'table'],
-      default: 'table'
+    upper: {
+      type: 'boolean'
     }
   },
-  async handle({ options, context }) {
-    const response = await context.sdk.marketdata.getOrderBook({
-      instrumentId: options['instrument-id'],
-      depth: options.depth
-    });
+  async handle({ options }) {
+    const message = `Hello, ${options.name}!`;
 
-    return context.formatOrderBook(response, options.format);
+    return options.upper ? message.toUpperCase() : message;
   }
 });
 ```
 
-### `defineCommandRegistry(commands)`
+#### `defineCommandRegistry(commands)`
 
 Defines a command registry while preserving literal command path types.
 
@@ -343,8 +193,8 @@ Defines a command registry while preserving literal command path types.
 import { defineCommandRegistry } from 'icore';
 
 const registry = defineCommandRegistry([
-  usersGetAccountsCommand,
-  marketdataGetOrderBookCommand
+  helloCommand,
+  helloFormalCommand
 ] as const);
 ```
 
@@ -358,14 +208,14 @@ Result:
 
 ```ts
 [
-  'users get-accounts',
-  'marketdata get-order-book'
+  'hello',
+  'hello formal'
 ]
 ```
 
 Duplicate command paths are rejected.
 
-### `isCommandName(registry, value)`
+#### `isCommandName(registry, value)`
 
 Checks whether an unknown value is a command name registered in the registry.
 
@@ -375,7 +225,7 @@ if (isCommandName(registry, value)) {
 }
 ```
 
-### `resolveCommand(registry, positionals)`
+#### `resolveCommand(registry, positionals)`
 
 Resolves a command from already parsed positional arguments.
 
@@ -383,9 +233,9 @@ Resolves a command from already parsed positional arguments.
 import { resolveCommand } from 'icore';
 
 const resolved = resolveCommand(registry, [
-  'users',
-  'get-accounts',
-  'extra'
+  'hello',
+  'formal',
+  'User'
 ]);
 ```
 
@@ -393,17 +243,17 @@ Result:
 
 ```ts
 {
-  name: 'users get-accounts',
-  path: ['users', 'get-accounts'],
-  command: usersGetAccountsCommand,
-  positionals: ['extra']
+  name: 'hello formal',
+  path: ['hello', 'formal'],
+  command: helloFormalCommand,
+  positionals: ['User']
 }
 ```
 
 When several command paths match, the most specific command wins. For example,
-`users get-accounts` is preferred over `users`.
+`hello formal` is preferred over `hello`.
 
-### `resolveCommandFromArgs(registry, args)`
+#### `resolveCommandFromArgs(registry, args)`
 
 Resolves a command from raw CLI arguments. Each candidate command is parsed with
 its own option schema, so boolean flags do not accidentally consume command path
@@ -411,28 +261,29 @@ segments.
 
 ```ts
 const resolved = resolveCommandFromArgs(registry, [
-  '--verbose',
-  'users',
-  'get-accounts'
+  'hello',
+  '--name',
+  'User',
+  '--upper'
 ]);
 ```
 
-### `runCommandFromRegistry(registry, args, context)`
+#### `runCommandFromRegistry(registry, args, context)`
 
 Resolves a command from a registry and runs its handler.
 
 ```ts
 const output = await runCommandFromRegistry(
   registry,
-  ['users', 'get-accounts', '--format', 'json'],
+  ['hello', '--name', 'User', '--upper'],
   context
 );
 ```
 
-This is registry-level mechanics only. Application-specific setup, API request
-building, and output formatting still belong outside `icore`.
+This is **registry-level mechanics only**. Application-specific setup, side
+effects, and output formatting still belong outside `icore`.
 
-### `mergeOptionsSchema(...schemas)`
+#### `mergeOptionsSchema(...schemas)`
 
 Merges multiple option schemas while preserving literal option definition types.
 Later schemas override earlier schemas with the same option name.
@@ -440,25 +291,23 @@ Later schemas override earlier schemas with the same option name.
 ```ts
 import { mergeOptionsSchema } from 'icore';
 
-const sdkOptions = {
-  token: {
+const nameOptions = {
+  name: {
     type: 'string',
-    required: true
+    default: 'world'
   }
 } as const;
 
-const formatOptions = {
-  format: {
-    type: 'string',
-    choices: ['json', 'table'],
-    default: 'table'
+const greetingOptions = {
+  upper: {
+    type: 'boolean'
   }
 } as const;
 
-const options = mergeOptionsSchema(sdkOptions, formatOptions);
+const options = mergeOptionsSchema(nameOptions, greetingOptions);
 ```
 
-### `runCommand(command, args, context)`
+#### `runCommand(command, args, context)`
 
 Parses arguments, validates options, checks command positionals, and runs the
 handler.
@@ -466,21 +315,128 @@ handler.
 ```ts
 const output = await runCommand(
   command,
-  [
-    'marketdata',
-    'get-order-book',
-    '--instrument-id',
-    'instrument-id',
-    '--depth',
-    '10'
-  ],
+  ['hello', '--name', 'User', '--upper'],
   context
 );
 ```
 
-By default, extra positionals are rejected. A command can opt in to extra
+**By default**, extra positionals are rejected. A command can opt in to extra
 positionals with `allowExtraPositionals: true`.
 
+### How It Works
+
+![yuml diagram](http://yuml.me/diagram/scruffy;dir:LR;/class/[*argv*%20{bg:gray}|External;hello%20--name%20User%20--upper]->[*matches*%20{bg:lavender}|System;parse,%20resolve,%20validate,%20infer]->[*typed%20result*%20{bg:honeydew}|Container;command=hello;%20name=User;%20upper=true]->[*your%20app*%20{bg:cornsilk}|System;business%20logic%20and%20output])
+
+
+### Example
+
+```ts
+import { defineCommand, runCommand } from 'icore';
+
+const exampleCommand = defineCommand({
+  path: ['hello'],
+  options: {
+    name: {
+      type: 'string',
+      default: 'world'
+    },
+    upper: {
+      type: 'boolean'
+    }
+  },
+  async handle({ options }) {
+    const message = `Hello, ${options.name}!`;
+
+    return options.upper ? message.toUpperCase() : message;
+  }
+});
+
+const output = await runCommand(
+  exampleCommand,
+  ['hello', '--name', 'User', '--upper'],
+  {}
+);
+
+console.log(output);
+```
+
+Terminal output:
+
+```console
+$ node cli.js hello --name User --upper
+HELLO, USER!
+```
+
+The command handler receives parsed options, user-provided option metadata,
+remaining positionals, and caller provided context.
+
+### Option Schemas
+
+Options are described as plain objects.
+
+**Option names are exact.** `icore` does not normalize `camelCase` to
+`kebab-case`. Use quoted object keys when your public CLI option contains
+`-`.
+
+#### `type: 'string'`
+
+```ts
+const schema = {
+  name: {
+    type: 'string',
+    required: true
+  },
+  style: {
+    type: 'string',
+    choices: ['short', 'long'],
+    default: 'short'
+  }
+} as const;
+```
+
+String options reject missing required values, blank strings, boolean flag form,
+and values outside `choices`.
+
+#### `type: 'boolean'`
+
+```ts
+const schema = {
+  upper: {
+    type: 'boolean'
+  }
+} as const;
+```
+
+Boolean options accept **flag form only**:
+
+```sh
+--upper
+```
+
+Explicit values are rejected:
+
+```sh
+--upper true
+--upper=true
+```
+
+#### `type: 'number'`
+
+```ts
+const schema = {
+  limit: {
+    type: 'number',
+    integer: true,
+    min: 1,
+    max: 1000,
+    default: 100
+  }
+} as const;
+```
+
+Number options parse decimal numeric values and can validate integer and range
+constraints. Defaults are validated with the same rules as user-provided values.
+
 ### Type Inference
 
 Use `InferOptions` when you need the parsed option type explicitly.
@@ -489,12 +445,11 @@ Use `InferOptions` when you need the parsed option type explicitly.
 import type { InferOptions } from 'icore';
 
 const schema = {
-  format: {
+  name: {
     type: 'string',
-    choices: ['json', 'table'],
-    default: 'table'
+    default: 'world'
   },
-  dryRun: {
+  upper: {
     type: 'boolean'
   }
 } as const;
@@ -506,13 +461,13 @@ type Options = InferOptions<typeof schema>;
 
 ```ts
 type Options = {
-  format: 'json' | 'table';
-  dryRun: boolean | undefined;
+  name: string;
+  upper: boolean | undefined;
 };
 ```
 
-Required options and options with defaults are always present. Optional options
-without defaults are returned as `T | undefined`.
+**Required options and options with defaults are always present.** Optional
+options without defaults are returned as `T | undefined`.
 
 Use `InferProvidedOptions` when you need the option presence type explicitly.
 
@@ -530,7 +485,7 @@ Use `MergeOptionsSchemas` when you need the merged schema type explicitly.
 ```ts
 import type { MergeOptionsSchemas } from 'icore';
 
-type Schema = MergeOptionsSchemas<[typeof sdkOptions, typeof formatOptions]>;
+type Schema = MergeOptionsSchemas<[typeof nameOptions, typeof greetingOptions]>;
 ```
 
 Use `CommandName` when you need the inferred command name type explicitly.
@@ -538,55 +493,49 @@ Use `CommandName` when you need the inferred command name type explicitly.
 ```ts
 import type { CommandName } from 'icore';
 
-type Name = CommandName<typeof usersGetAccountsCommand>;
+type Name = CommandName<typeof helloFormalCommand>;
 ```
 
 `Name` is equivalent to:
 
 ```ts
-type Name = 'users get-accounts';
+type Name = 'hello formal';
 ```
 
 ### Facade of arguments
 
 The table below provides examples of how to specify the syntax.
 
-| Syntax | Supported | Notes |
-|---|---:|---|
-| `--name value` | yes | string and number options |
-| `--name=value` | yes | string and number options |
-| `--flag` | yes | boolean options |
-| `--flag=true` | no | boolean options are flag-only |
-| `-f` | no | short aliases are not supported |
-| `--no-cache` | no | negative boolean flags are not supported |
-| repeated options | no | duplicates are rejected |
-| multiple values | no | arrays are not supported |
+| Syntax | Supported |
+|---|---:|
+| `--name value` | yes |
+| `--name=value` | yes |
+| `--flag` | yes |
+| `--flag=true` | no |
+| `-f` | no |
+| `--no-cache` | no |
 
 ### Error Messages
 
 `icore` throws regular `Error` objects with predictable user-facing messages.
-Applications should treat these messages as display text, not as a
-machine-readable API.
+Applications should treat these messages as **display text**, not as a
+**machine-readable API**.
 
-Examples:
+Applications can catch these errors and decide how to print them. For example,
+after printing `error.message`, terminal output can look like this:
 
-```txt
+```console
+$ node cli.js hello --unknown
 Unexpected argument '--unknown'
-Unexpected duplicate argument '--format'
-Unexpected duplicate command 'users get-accounts'
-Unknown command: users get-unknown
-Expected required argument '--token'
-Expected '--format' as one of: json, table
-Expected '--depth' as integer
-Expected '--depth' to be greater than or equal to 1
-```
 
-Applications can catch these errors and decide how to print them.
+$ node cli.js hello --upper=true
+Expected '--upper' as boolean flag
+```
 
 ### Project Boundary
 
-`icore` is intended to be a small CLI mechanics module. It should not grow into a
-domain-specific framework for a particular SDK or API.
+`icore` is intended to be a **small CLI mechanics module**. It should **not**
+grow into a domain-specific framework for a particular SDK or API.
 
 Good responsibilities for `icore`: