icore 1.0.6 → 1.0.8

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 Stanislav Woodger
+Copyright (c) 2017 Stanislav Potemkin
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icore",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Declarative command line interface mechanics for Node.js",
   "keywords": [
     "command-line",
@@ -14,7 +14,7 @@
   ],
   "license": "MIT",
   "author": {
-    "name": "Stanislav Woodger",
+    "name": "Stanislav Potemkin",
     "email": "woodger@ya.ru"
   },
   "repository": {

package/readme.md

@@ -7,7 +7,14 @@
 
 Small dependency-free command line interface mechanics for [Node.js®](https://nodejs.org) applications.
 
-### Installation
+Supports a practical GNU-style option syntax:
+
+- long options: `--name value`, `--name=value`;
+- boolean flags: `--flag`, `--flag=true`, `--flag=false`, `--no-flag`;
+- short aliases: `-f`, `-n value`;
+- option terminator: `--`.
+
+## Installation
 
 To use `icore` in your project, run:
 
@@ -15,29 +22,32 @@ To use `icore` in your project, run:
 npm install icore
 ```
 
-### Table of Contents
-
-* [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?)`
+## Table of Contents
+
+- [Installation](#installation)
+- [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)
+- [How It Works](#how-it-works)
+- [Example](#example)
+- [Option Schemas](#option-schemas)
+- [Type Inference](#type-inference)
+- [Facade of arguments](#facade-of-arguments)
+- [Error Messages](#error-messages)
+- [Project Boundary](#project-boundary)
+
+## API
+
+### `parseArgv(args, schema?)`
 
 Parses raw CLI arguments into positionals and raw option values.
 
@@ -47,8 +57,8 @@ import { parseArgv } from 'icore';
 const argv = parseArgv([
   'hello',
   '--name',
-  'User',
-  '--upper'
+  'Alice',
+  '--uppercase'
 ]);
 ```
 
@@ -58,8 +68,8 @@ Result:
 {
   positionals: ['hello'],
   options: {
-    name: 'User',
-    upper: true
+    name: 'Alice',
+    uppercase: true
   }
 }
 ```
@@ -70,10 +80,10 @@ options without consuming the following positional argument:
 ```ts
 const argv = parseArgv([
   'hello',
-  '--upper',
-  'User'
+  '--uppercase',
+  'Alice'
 ], {
-  upper: {
+  uppercase: {
     type: 'boolean'
   }
 });
@@ -83,14 +93,14 @@ Result:
 
 ```ts
 {
-  positionals: ['hello', 'User'],
+  positionals: ['hello', 'Alice'],
   options: {
-    upper: true
+    uppercase: true
   }
 }
 ```
 
-#### `parseOptions(schema, values)`
+### `parseOptions(schema, values)`
 
 Validates raw option values using an option schema and returns typed options.
 
@@ -102,12 +112,12 @@ const options = parseOptions({
     type: 'string',
     default: 'world'
   },
-  upper: {
+  uppercase: {
     type: 'boolean'
   }
 } as const, {
-  name: 'User',
-  upper: true
+  name: 'Alice',
+  uppercase: true
 });
 ```
 
@@ -115,12 +125,12 @@ Result:
 
 ```ts
 {
-  name: 'User',
-  upper: true
+  name: 'Alice',
+  uppercase: true
 }
 ```
 
-#### `parseOptionsDetailed(schema, values)`
+### `parseOptionsDetailed(schema, values)`
 
 Validates raw option values and returns parsed options together with
 user-provided metadata.
@@ -133,11 +143,11 @@ const result = parseOptionsDetailed({
     type: 'string',
     default: 'world'
   },
-  upper: {
+  uppercase: {
     type: 'boolean'
   }
 } as const, {
-  upper: true
+  uppercase: true
 });
 ```
 
@@ -147,11 +157,11 @@ Result:
 {
   options: {
     name: 'world',
-    upper: true
+    uppercase: true
   },
   provided: {
     name: false,
-    upper: true
+    uppercase: true
   }
 }
 ```
@@ -159,7 +169,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.
 
@@ -173,19 +183,19 @@ const command = defineCommand({
       type: 'string',
       default: 'world'
     },
-    upper: {
+    uppercase: {
       type: 'boolean'
     }
   },
   async handle({ options }) {
     const message = `Hello, ${options.name}!`;
 
-    return options.upper ? message.toUpperCase() : message;
+    return options.uppercase ? message.toUpperCase() : message;
   }
 });
 ```
 
-#### `defineCommandRegistry(commands)`
+### `defineCommandRegistry(commands)`
 
 Defines a command registry while preserving literal command path types.
 
@@ -215,7 +225,7 @@ Result:
 
 Duplicate command paths are rejected.
 
-#### `isCommandName(registry, value)`
+### `isCommandName(registry, value)`
 
 Checks whether an unknown value is a command name registered in the registry.
 
@@ -225,7 +235,7 @@ if (isCommandName(registry, value)) {
 }
 ```
 
-#### `resolveCommand(registry, positionals)`
+### `resolveCommand(registry, positionals)`
 
 Resolves a command from already parsed positional arguments.
 
@@ -235,7 +245,7 @@ import { resolveCommand } from 'icore';
 const resolved = resolveCommand(registry, [
   'hello',
   'formal',
-  'User'
+  'Alice'
 ]);
 ```
 
@@ -246,14 +256,14 @@ Result:
   name: 'hello formal',
   path: ['hello', 'formal'],
   command: helloFormalCommand,
-  positionals: ['User']
+  positionals: ['Alice']
 }
 ```
 
 When several command paths match, the most specific command wins. For example,
 `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
@@ -263,19 +273,19 @@ segments.
 const resolved = resolveCommandFromArgs(registry, [
   'hello',
   '--name',
-  'User',
-  '--upper'
+  'Alice',
+  '--uppercase'
 ]);
 ```
 
-#### `runCommandFromRegistry(registry, args, context)`
+### `runCommandFromRegistry(registry, args, context)`
 
 Resolves a command from a registry and runs its handler.
 
 ```ts
 const output = await runCommandFromRegistry(
   registry,
-  ['hello', '--name', 'User', '--upper'],
+  ['hello', '--name', 'Alice', '--uppercase'],
   context
 );
 ```
@@ -283,7 +293,7 @@ const output = await runCommandFromRegistry(
 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.
@@ -299,7 +309,7 @@ const nameOptions = {
 } as const;
 
 const greetingOptions = {
-  upper: {
+  uppercase: {
     type: 'boolean'
   }
 } as const;
@@ -307,7 +317,7 @@ const greetingOptions = {
 const options = mergeOptionsSchema(nameOptions, greetingOptions);
 ```
 
-#### `runCommand(command, args, context)`
+### `runCommand(command, args, context)`
 
 Parses arguments, validates options, checks command positionals, and runs the
 handler.
@@ -315,7 +325,7 @@ handler.
 ```ts
 const output = await runCommand(
   command,
-  ['hello', '--name', 'User', '--upper'],
+  ['hello', '--name', 'Alice', '--uppercase'],
   context
 );
 ```
@@ -323,12 +333,12 @@ const output = await runCommand(
 **By default**, extra positionals are rejected. A command can opt in to extra
 positionals with `allowExtraPositionals: true`.
 
-### How It Works
+## 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])
+![yuml diagram](http://yuml.me/diagram/scruffy;dir:LR;/class/[*argv*%20{bg:gray}|External;hello%20--name%20Alice%20--uppercase]->[*matches*%20{bg:lavender}|System;parse,%20resolve,%20validate,%20infer]->[*typed%20result*%20{bg:honeydew}|Container;command=hello;%20name=Alice;%20uppercase=true]->[*your%20app*%20{bg:cornsilk}|System;business%20logic%20and%20output])
 
 
-### Example
+## Example
 
 ```ts
 import { defineCommand, runCommand } from 'icore';
@@ -340,20 +350,20 @@ const exampleCommand = defineCommand({
       type: 'string',
       default: 'world'
     },
-    upper: {
+    uppercase: {
       type: 'boolean'
     }
   },
   async handle({ options }) {
     const message = `Hello, ${options.name}!`;
 
-    return options.upper ? message.toUpperCase() : message;
+    return options.uppercase ? message.toUpperCase() : message;
   }
 });
 
 const output = await runCommand(
   exampleCommand,
-  ['hello', '--name', 'User', '--upper'],
+  ['hello', '--name', 'Alice', '--uppercase'],
   {}
 );
 
@@ -363,14 +373,14 @@ console.log(output);
 Terminal output:
 
 ```console
-$ node cli.js hello --name User --upper
-HELLO, USER!
+$ node cli.js hello --name Alice --uppercase
+HELLO, ALICE!
 ```
 
 The command handler receives parsed options, user-provided option metadata,
 remaining positionals, and caller provided context.
 
-### Option Schemas
+## Option Schemas
 
 Options are described as plain objects.
 
@@ -386,7 +396,7 @@ const schema = {
     type: 'string',
     alias: 'n'
   },
-  upper: {
+  uppercase: {
     type: 'boolean',
     alias: 'u'
   }
@@ -396,7 +406,7 @@ const schema = {
 Aliases must be a single ASCII letter and unique within the schema. Parsed
 values are always returned by long option name.
 
-#### `type: 'string'`
+### `type: 'string'`
 
 ```ts
 const schema = {
@@ -415,11 +425,11 @@ const schema = {
 String options reject missing required values, blank strings such as `--name=`,
 boolean flag form, and values outside `choices`.
 
-#### `type: 'boolean'`
+### `type: 'boolean'`
 
 ```ts
 const schema = {
-  upper: {
+  uppercase: {
     type: 'boolean'
   }
 } as const;
@@ -429,23 +439,23 @@ Boolean options accept **flag form**, explicit `true` / `false` values, and
 schema-known negation:
 
 ```sh
---upper
---upper=true
---upper=false
---no-upper
+--uppercase
+--uppercase=true
+--uppercase=false
+--no-uppercase
 ```
 
 Invalid explicit values are rejected:
 
 ```sh
---upper=yes
---upper=
+--uppercase=yes
+--uppercase=
 ```
 
-`--upper false` keeps `--upper` as `true` and leaves `false` as a positional
+`--uppercase false` keeps `--uppercase` as `true` and leaves `false` as a positional
 argument.
 
-#### `type: 'number'`
+### `type: 'number'`
 
 ```ts
 const schema = {
@@ -462,7 +472,7 @@ const schema = {
 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
+## Type Inference
 
 Use `InferOptions` when you need the parsed option type explicitly.
 
@@ -474,7 +484,7 @@ const schema = {
     type: 'string',
     default: 'world'
   },
-  upper: {
+  uppercase: {
     type: 'boolean'
   }
 } as const;
@@ -487,7 +497,7 @@ type Options = InferOptions<typeof schema>;
 ```ts
 type Options = {
   name: string;
-  upper: boolean | undefined;
+  uppercase: boolean | undefined;
 };
 ```
 
@@ -527,14 +537,7 @@ type Name = CommandName<typeof helloFormalCommand>;
 type Name = 'hello formal';
 ```
 
-### Facade of arguments
-
-Supports a practical GNU-style option syntax:
-
-- long options: `--name value`, `--name=value`;
-- boolean flags: `--flag`, `--flag=true`, `--flag=false`, `--no-flag`;
-- short aliases: `-f`, `-n value`;
-- option terminator: `--`.
+## Facade of arguments
 
 Use `--` to stop option parsing. The terminator itself is not included in
 positionals; every following token is treated as positional, even when it starts
@@ -552,7 +555,7 @@ Negated syntax such as `--no-cache` is interpreted as `cache: false` when
 `cache` is a known boolean option. Unknown negated options and negation for
 string or number options are rejected.
 
-### Error Messages
+## Error Messages
 
 `icore` throws regular `Error` objects with predictable user-facing messages.
 Applications should treat these messages as **display text**, not as a
@@ -565,14 +568,14 @@ after printing `error.message`, terminal output can look like this:
 $ node cli.js hello --unknown
 Unexpected argument '--unknown'
 
-$ node cli.js hello --upper=yes
-Expected '--upper' as boolean flag
+$ node cli.js hello --uppercase=yes
+Expected '--uppercase' as boolean flag
 
 $ node cli.js hello --name=
 Expected '--name' as string
 ```
 
-### Project Boundary
+## 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.