@cli-forge/parser 0.10.1 → 0.12.0

package/LICENSE.md

@@ -0,0 +1,5 @@
+Copyright 2024 Craigory Coppola
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,11 +1,207 @@
-# parser
+# @cli-forge/parser
 
-This library was generated with [Nx](https://nx.dev).
+**A type-safe argument parser for Node.js with full TypeScript inference.**
 
-## Building
+This is the low-level parsing engine that powers [cli-forge](https://www.npmjs.com/package/cli-forge). Use this package directly if you need fine-grained control over argument parsing without the higher-level command management features.
 
-Run `nx build parser` to build the library.
+## Installation
 
-## Running unit tests
+```bash
+npm install @cli-forge/parser
+```
 
-Run `nx test parser` to execute the unit tests via [Vitest](https://vitest.dev/).
+## Quick Start
+
+```typescript
+import { parser } from '@cli-forge/parser';
+
+const args = parser()
+  .option('name', { type: 'string', required: true })
+  .option('port', { type: 'number', default: 3000 })
+  .option('verbose', { type: 'boolean', alias: ['v'] })
+  .parse(['--name', 'my-app', '--port', '8080', '-v']);
+
+// args is fully typed:
+// { name: string; port: number; verbose: boolean }
+console.log(args.name);    // 'my-app'
+console.log(args.port);    // 8080
+console.log(args.verbose); // true
+```
+
+## Features
+
+- **Full TypeScript inference** - Types accumulate as you chain `.option()` calls
+- **Multiple option types** - `string`, `number`, `boolean`, `array`, `object`
+- **Value sources** - CLI args, environment variables, config files, defaults
+- **Validation** - `choices`, `validate`, `required`, `conflicts`, `implies`
+- **Config file support** - JSON/YAML with inheritance via `extends`
+- **Coercion** - Transform values during parsing
+
+## Option Types
+
+### String
+
+```typescript
+parser().option('name', {
+  type: 'string',
+  description: 'User name',
+  default: 'anonymous',
+});
+```
+
+### Number
+
+```typescript
+parser().option('port', {
+  type: 'number',
+  description: 'Port number',
+  default: 3000,
+});
+```
+
+### Boolean
+
+```typescript
+parser().option('verbose', {
+  type: 'boolean',
+  alias: ['v'],
+  description: 'Enable verbose output',
+});
+// Supports: --verbose, --verbose true, --no-verbose
+```
+
+### Array
+
+```typescript
+parser().option('files', {
+  type: 'array',
+  items: 'string',
+  description: 'Input files',
+});
+// Supports: --files a b c, --files a,b,c, --files a --files b
+```
+
+### Object
+
+```typescript
+parser().option('config', {
+  type: 'object',
+  properties: {
+    host: { type: 'string', default: 'localhost' },
+    port: { type: 'number', required: true },
+    ssl: { type: 'boolean' },
+  },
+});
+// Supports: --config.host example.com --config.port 443 --config.ssl
+```
+
+## Positional Arguments
+
+```typescript
+parser()
+  .positional('input', { type: 'string', required: true })
+  .positional('output', { type: 'string' })
+  .parse(['input.txt', 'output.txt']);
+```
+
+## Validation
+
+### Choices
+
+```typescript
+parser().option('level', {
+  type: 'string',
+  choices: ['debug', 'info', 'warn', 'error'],
+});
+```
+
+### Custom Validation
+
+```typescript
+parser().option('port', {
+  type: 'number',
+  validate: (value) => {
+    if (value < 1 || value > 65535) {
+      throw new Error('Port must be between 1 and 65535');
+    }
+    return true;
+  },
+});
+```
+
+### Conflicts and Implies
+
+```typescript
+parser()
+  .option('quiet', { type: 'boolean' })
+  .option('verbose', {
+    type: 'boolean',
+    conflicts: ['quiet'],
+  })
+  .option('output', {
+    type: 'string',
+    implies: { format: 'json' },
+  });
+```
+
+## Environment Variables
+
+```typescript
+parser().option('apiKey', {
+  type: 'string',
+  env: 'API_KEY',
+});
+// Will read from process.env.API_KEY if --apiKey not provided
+```
+
+## Configuration Files
+
+```typescript
+parser()
+  .configFile('myapp.config.json')
+  .option('port', { type: 'number' })
+  .parse([]);
+```
+
+Config files support inheritance:
+
+```json
+{
+  "extends": "./base-config.json",
+  "port": 8080
+}
+```
+
+## Coercion
+
+Transform values during parsing:
+
+```typescript
+parser().option('date', {
+  type: 'string',
+  coerce: (value) => new Date(value),
+});
+```
+
+## Type Inference
+
+The parser tracks types as options are added:
+
+```typescript
+const p = parser()
+  .option('name', { type: 'string' })        // { name?: string }
+  .option('port', { type: 'number' })        // { name?: string; port?: number }
+  .option('required', { type: 'string', required: true }); // { name?: string; port?: number; required: string }
+```
+
+## Related Packages
+
+- [`cli-forge`](https://www.npmjs.com/package/cli-forge) - High-level CLI builder with commands, middleware, and documentation generation
+
+## Documentation
+
+Full documentation available at: https://craigory.dev/cli-forge/
+
+## License
+
+ISC

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;AAAA,uDAA6B;AAC7B,2EAAiD;AACjD,wDAA8B;AAC9B,6DAAmC;AACnC,yEAA+C;AAC/C,4DAAkC;AAElC;;GAEG;AACH,iFAAyD"}

package/dist/lib/config-files/configuration-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration-loader.js","sourceRoot":"","sources":["../../../src/lib/config-files/configuration-loader.ts"],"names":[],"mappings":";;AAwBA,oDAgCC;AAxDD,+BAA4B;AAsB5B,iFAAiF;AACjF,yEAAyE;AACzE,SAAgB,oBAAoB,CAClC,iBAAyB,EACzB,OAAmC;IAEnC,SAAS,iBAAiB,CACxB,QAAgB,EAChB,QAAkC;QAElC,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACvC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,MAAM,QAAQ,GAAG,oBAAoB,CACnC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;gBAC5B,CAAC,CAAC,IAAA,WAAI,EAAC,iBAAiB,EAAE,MAAM,CAAC,OAAO,CAAC;gBACzC,CAAC,CAAC,MAAM,CAAC,OAAO,EAClB,OAAO,CACR,CAAC;YACF,OAAO,EAAE,GAAG,QAAQ,EAAE,GAAG,MAAM,EAAE,CAAC;QACpC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,QAAQ,GAAM,EAAO,CAAC;IAC1B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;QACnD,IAAI,QAAQ,EAAE,CAAC;YACb,QAAQ,GAAG;gBACT,GAAG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC;gBACtC,GAAG,QAAQ;aACZ,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/lib/config-files/index.d.ts

@@ -0,0 +1,3 @@
+export * from './configuration-loader.js';
+export * from './json-file-loader.js';
+export * from './package-json-loader.js';

package/dist/lib/config-files/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./configuration-loader.js"), exports);
+tslib_1.__exportStar(require("./json-file-loader.js"), exports);
+tslib_1.__exportStar(require("./package-json-loader.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/lib/config-files/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/config-files/index.ts"],"names":[],"mappings":";;;AAAA,oEAA0C;AAC1C,gEAAsC;AACtC,mEAAyC"}

package/{src → dist}/lib/config-files/json-file-loader.d.ts

@@ -1,4 +1,4 @@
-import { ConfigurationProvider } from './configuration-loader';
+import { ConfigurationProvider } from './configuration-loader.js';
 /**
  * A factory function to create simple configuration providers that load configuration from a JSON file.
  * @param filename The filename of the JSON file to load.

package/{src → dist}/lib/config-files/json-file-loader.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getJsonFileConfigLoader = getJsonFileConfigLoader;
 const fs_1 = require("fs");
 const util_1 = require("util");
-const utils_1 = require("./utils");
+const utils_js_1 = require("./utils.js");
 /**
  * A factory function to create simple configuration providers that load configuration from a JSON file.
  * @param filename The filename of the JSON file to load.
@@ -17,7 +17,7 @@ function getJsonFileConfigLoader(filename, transform) {
     class JsonFileConfigLoader {
         seen = new Set();
         resolve(configurationRoot) {
-            const nearestFile = (0, utils_1.traverseForFile)(filename, configurationRoot);
+            const nearestFile = (0, utils_js_1.traverseForFile)(filename, configurationRoot);
             if (!nearestFile || !nearestFile.endsWith('.json')) {
                 return undefined;
             }

package/dist/lib/config-files/json-file-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-file-loader.js","sourceRoot":"","sources":["../../../src/lib/config-files/json-file-loader.ts"],"names":[],"mappings":";;AAYA,0DAuCC;AAnDD,2BAAkC;AAClC,+BAA+B;AAG/B,yCAA6C;AAE7C;;;;;GAKG;AACH,SAAgB,uBAAuB,CACrC,QAAgB,EAChB,SAA4B;IAE5B,SAAS,YAAY,CAAC,QAAgB;QACpC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAA,iBAAY,EAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,MAAM,oBAAoB;QAChB,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAEjC,OAAO,CAAC,iBAAyB;YAC/B,MAAM,WAAW,GAAG,IAAA,0BAAe,EAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC;YACjE,IAAI,CAAC,WAAW,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBACnD,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;gBAC/B,MAAM,IAAI,KAAK,CACb,sDAAsD,WAAW,sHAAsH,CACxL,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YAC3B,OAAO,WAAW,CAAC;QACrB,CAAC;QAED,IAAI,CAAC,QAAgB;YACnB,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;YACpC,IAAI,SAAS,EAAE,CAAC;gBACd,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;YACzB,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,CAAC,cAAO,CAAC,MAAM,CAAC;YACd,OAAO,wBAAwB,GAAG,QAAQ,CAAC;QAC7C,CAAC;KACF;IAED,OAAO,IAAI,oBAAoB,EAAE,CAAC;AACpC,CAAC"}

package/{src → dist}/lib/config-files/package-json-loader.d.ts

@@ -1,4 +1,4 @@
-import { ConfigurationProvider } from './configuration-loader';
+import { ConfigurationProvider } from './configuration-loader.js';
 /**
  * A factory function to create a configuration provider that loads configuration from a package.json file.
  * @param key The key in the package.json file to load as configuration.

package/{src → dist}/lib/config-files/package-json-loader.js

@@ -2,14 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getPackageJsonConfigurationLoader = getPackageJsonConfigurationLoader;
 const node_util_1 = require("node:util");
-const json_file_loader_1 = require("./json-file-loader");
+const json_file_loader_js_1 = require("./json-file-loader.js");
 /**
  * A factory function to create a configuration provider that loads configuration from a package.json file.
  * @param key The key in the package.json file to load as configuration.
  * @returns A `{@link ConfigurationProvider}` that loads configuration from the specified package.json file.
  */
 function getPackageJsonConfigurationLoader(key) {
-    const loader = (0, json_file_loader_1.getJsonFileConfigLoader)('package.json', (json) => json[key]);
+    const loader = (0, json_file_loader_js_1.getJsonFileConfigLoader)('package.json', (json) => json[key]);
     loader[node_util_1.inspect.custom] = () => 'PackageJsonConfigurationLoader: ' + key;
     return loader;
 }

package/dist/lib/config-files/package-json-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-json-loader.js","sourceRoot":"","sources":["../../../src/lib/config-files/package-json-loader.ts"],"names":[],"mappings":";;AAUA,8EAUC;AApBD,yCAAoC;AAGpC,+DAAgE;AAEhE;;;;GAIG;AACH,SAAgB,iCAAiC,CAC/C,GAAW;IAEX,MAAM,MAAM,GAAG,IAAA,6CAAuB,EACpC,cAAc,EACd,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CACpB,CAAC;IACD,MAAc,CAAC,mBAAO,CAAC,MAAM,CAAC,GAAG,GAAG,EAAE,CACrC,kCAAkC,GAAG,GAAG,CAAC;IAC3C,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/lib/config-files/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/lib/config-files/utils.ts"],"names":[],"mappings":";;AAGA,0CAiBC;AApBD,qCAAqC;AACrC,yCAA0C;AAE1C,SAAgB,eAAe,CAC7B,cAAsB,EACtB,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE;IAEzB,4CAA4C;IAC5C,IAAI,IAAwB,CAAC;IAC7B,IAAI,OAAO,GAAG,SAAS,CAAC;IACxB,OAAO,IAAI,KAAK,OAAO,EAAE,CAAC;QACxB,IAAI,GAAG,OAAO,CAAC;QACf,MAAM,QAAQ,GAAG,IAAA,gBAAI,EAAC,OAAO,EAAE,cAAc,CAAC,CAAC;QAC/C,IAAI,IAAA,oBAAU,EAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,OAAO,QAAQ,CAAC;QAClB,CAAC;aAAM,CAAC;YACN,OAAO,GAAG,IAAA,mBAAO,EAAC,OAAO,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/lib/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/lib/helpers.ts"],"names":[],"mappings":";AAAA,iFAAiF;;AAwBjF,0BAEC;AAED,wBAEC;AA5BD,SAAS,sBAAsB;IAC7B,0DAA0D;IAC1D,qDAAqD;IACrD,IAAI,oBAAoB,EAAE;QAAE,OAAO,CAAC,CAAC;IACrC,mCAAmC;IACnC,0DAA0D;IAC1D,kEAAkE;IAClE,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,oBAAoB;IAC3B,0FAA0F;IAC1F,oGAAoG;IACpG,OAAO,aAAa,EAAE,IAAI,CAAE,OAA2B,CAAC,UAAU,CAAC;AACrE,CAAC;AAED,SAAS,aAAa;IACpB,oEAAoE;IACpE,0GAA0G;IAC1G,OAAO,CAAC,CAAE,OAA2B,CAAC,QAAQ,CAAC,QAAQ,CAAC;AAC1D,CAAC;AAED,SAAgB,OAAO,CAAC,IAAc;IACpC,OAAO,IAAI,CAAC,KAAK,CAAC,sBAAsB,EAAE,GAAG,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,SAAgB,MAAM,CAAC,IAAc;IACnC,OAAO,IAAI,CAAC,sBAAsB,EAAE,CAAC,CAAC;AACxC,CAAC"}

package/dist/lib/option-types/array.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"array.js","sourceRoot":"","sources":["../../../src/lib/option-types/array.ts"],"names":[],"mappings":""}

package/dist/lib/option-types/boolean.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boolean.js","sourceRoot":"","sources":["../../../src/lib/option-types/boolean.ts"],"names":[],"mappings":""}

package/{src → dist}/lib/option-types/common.d.ts

@@ -26,7 +26,7 @@ export type CommonOptionConfig<T, TCoerce = T, TChoices = T[]> = {
      *
      * If the default value is a tuple, the first value will be used as the default value, and the second value will be used as the description.
      */
-    default?: Default<T>;
+    default?: Default<NoInfer<T>>;
     /**
      * Provide a description for the option.
      */

package/dist/lib/option-types/common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../../src/lib/option-types/common.ts"],"names":[],"mappings":""}

package/dist/lib/option-types/index.d.ts

@@ -0,0 +1,15 @@
+import { OptionConfig, UnknownOptionConfig } from './option-config';
+export * from './option-config-to-type';
+export * from './type-resolution';
+export * from './common';
+export * from './array';
+export * from './boolean';
+export * from './number';
+export * from './object';
+export * from './string';
+export type { OptionConfig, UnknownOptionConfig };
+export type Internal<T extends UnknownOptionConfig> = T & InternalOptionConfig;
+export type InternalOptionConfig = UnknownOptionConfig & {
+    key: string;
+    position?: number;
+};

package/{src → dist}/lib/option-types/index.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./option-config-to-type"), exports);
+tslib_1.__exportStar(require("./type-resolution"), exports);
 tslib_1.__exportStar(require("./common"), exports);
 tslib_1.__exportStar(require("./array"), exports);
 tslib_1.__exportStar(require("./boolean"), exports);

package/dist/lib/option-types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/option-types/index.ts"],"names":[],"mappings":";;;AAEA,kEAAwC;AACxC,4DAAkC;AAClC,mDAAyB;AACzB,kDAAwB;AACxB,oDAA0B;AAC1B,mDAAyB;AACzB,mDAAyB;AACzB,mDAAyB"}

package/dist/lib/option-types/number.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"number.js","sourceRoot":"","sources":["../../../src/lib/option-types/number.ts"],"names":[],"mappings":""}

package/dist/lib/option-types/object.d.ts

@@ -0,0 +1,75 @@
+import { CommonOptionConfig, Default } from './common';
+import { ResolveProperties, WithAdditionalProperties } from './type-resolution';
+/**
+ * Compute the full value type for an object option.
+ * Resolves each property to its final type (respecting optional/required)
+ * and adds an index signature if additionalProperties is set.
+ *
+ * Uses WithAdditionalProperties when additionalProperties is specified,
+ * which creates a compatible index signature that doesn't conflict with
+ * explicit property types.
+ */
+type ObjectValue<TProperties extends Record<string, {
+    type: string;
+}>, TAdditionalProperties extends false | 'string' | 'number' | 'boolean'> = [TAdditionalProperties] extends [false] ? ResolveProperties<TProperties> : WithAdditionalProperties<ResolveProperties<TProperties>, TAdditionalProperties>;
+/**
+ * Configuration for object options. Objects are parsed from dot notation
+ * or JSON strings.
+ *
+ * e.g. `--config.host localhost --config.port 3000` or `--config '{"host":"localhost"}'`
+ *
+ * Note: This type explicitly lists all fields from CommonOptionConfig instead of using
+ * Omit<CommonOptionConfig<TValue>, ...> to avoid circular type inference issues.
+ * When Omit is used, TypeScript must fully evaluate CommonOptionConfig<TValue> first,
+ * which requires computing TValue from TProperties, creating a circular dependency
+ * when callbacks reference nested properties.
+ */
+/**
+ * Configuration for object options. Objects are parsed from dot notation
+ * or JSON strings.
+ *
+ * e.g. `--config.host localhost --config.port 3000` or `--config '{"host":"localhost"}'`
+ *
+ * Note: This type explicitly lists all fields from CommonOptionConfig instead of using
+ * Omit<CommonOptionConfig<TValue>, ...> to avoid circular type inference issues.
+ * When Omit is used, TypeScript must fully evaluate CommonOptionConfig<TValue> first,
+ * which requires computing TValue from TProperties, creating a circular dependency
+ * when callbacks reference nested properties.
+ */
+/**
+ * Compute the validate parameter type for object options.
+ * When coerce is provided, validate receives the coerced type (TCoerce).
+ * When coerce is not provided, validate receives the computed ObjectValue type.
+ *
+ * Uses `unknown extends TCoerce` to detect if TCoerce was not explicitly provided,
+ * since it defaults to `unknown` when no coerce function is given.
+ */
+type ObjectValidateType<TCoerce, TProperties extends Record<string, {
+    type: string;
+}>, TAdditionalProperties extends false | 'string' | 'number' | 'boolean'> = unknown extends TCoerce ? ObjectValue<TProperties, TAdditionalProperties> : TCoerce;
+export type ObjectOptionConfig<TCoerce, TProperties extends Record<string, {
+    type: string;
+}>, TAdditionalProperties extends false | 'string' | 'number' | 'boolean' = false> = {
+    [key in keyof Omit<CommonOptionConfig<ObjectValue<NoInfer<TProperties>, NoInfer<TAdditionalProperties>>, NoInfer<TCoerce>>, 'choices' | 'coerce' | 'validate' | 'default'>]: CommonOptionConfig<ObjectValue<NoInfer<TProperties>, NoInfer<TAdditionalProperties>>, NoInfer<TCoerce>>[key];
+} & {
+    type: 'object';
+    properties: TProperties;
+    additionalProperties?: TAdditionalProperties;
+    /**
+     * Provide a default value for the entire object.
+     * Uses a permissive type (object) to avoid interfering with TProperties inference.
+     * The actual type checking happens at runtime.
+     */
+    default?: Default<object>;
+    /**
+     * Coerce transforms the parsed object value.
+     * The return type becomes the final type for this option.
+     */
+    coerce?: (value: ObjectValue<TProperties, NoInfer<TAdditionalProperties>>) => TCoerce;
+    /**
+     * Validate the object value after coercion (or the raw value if no coerce).
+     * Receives the coerced type if coerce is provided, otherwise the computed ObjectValue type.
+     */
+    validate?: (value: ObjectValidateType<TCoerce, TProperties, TAdditionalProperties>) => boolean | string;
+};
+export {};

package/dist/lib/option-types/object.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"object.js","sourceRoot":"","sources":["../../../src/lib/option-types/object.ts"],"names":[],"mappings":""}

package/dist/lib/option-types/option-config-to-type.d.ts

@@ -0,0 +1,9 @@
+import { ResolveOptionType, WithOptional, ResolveProperties, WithAdditionalProperties } from './type-resolution';
+/**
+ * Converts an OptionConfig to the TypeScript type for the parsed value.
+ * Uses shared type resolution logic from type-resolution.ts.
+ */
+export type OptionConfigToType<TOptionConfig extends {
+    type: string;
+}> = WithOptional<ResolveOptionType<TOptionConfig>, TOptionConfig>;
+export type { ResolveProperties, WithAdditionalProperties };

package/dist/lib/option-types/option-config-to-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"option-config-to-type.js","sourceRoot":"","sources":["../../../src/lib/option-types/option-config-to-type.ts"],"names":[],"mappings":""}

package/dist/lib/option-types/option-config.d.ts

@@ -0,0 +1,24 @@
+import { ArrayOptionConfig } from './array';
+import { BooleanOptionConfig } from './boolean';
+import { NumberOptionConfig } from './number';
+import { ObjectOptionConfig } from './object';
+import { StringOptionConfig } from './string';
+/**
+ * Configures an option for the parser. See subtypes for more information.
+ * - {@link StringOptionConfig}
+ * - {@link NumberOptionConfig}
+ * - {@link ArrayOptionConfig}
+ * - {@link BooleanOptionConfig}
+ *
+ * @typeParam TCoerce The return type of the `coerce` function if provided.
+ */
+export type OptionConfig<TCoerce = any, TChoices = any[], TObjectProps extends Record<string, {
+    type: string;
+}> = Record<string, any>, TAdditionalProps extends false | 'string' | 'number' | 'boolean' = false> = StringOptionConfig<TCoerce, TChoices> | NumberOptionConfig<TCoerce, TChoices> | ArrayOptionConfig<TCoerce, TChoices> | BooleanOptionConfig<TCoerce, TChoices> | ObjectOptionConfig<TCoerce, TObjectProps, TAdditionalProps>;
+/**
+ * An OptionConfig with generic parameters set for maximum compatibility.
+ * Uses `any` for all type parameters to allow maximum assignability.
+ * The IsAny check in AdditionalPropertiesType handles the case where
+ * TAdditionalProps is `any` by returning `unknown` instead of an index signature.
+ */
+export type UnknownOptionConfig = OptionConfig<any, any, any, any>;

package/dist/lib/option-types/option-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"option-config.js","sourceRoot":"","sources":["../../../src/lib/option-types/option-config.ts"],"names":[],"mappings":""}

package/dist/lib/option-types/string.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.js","sourceRoot":"","sources":["../../../src/lib/option-types/string.ts"],"names":[],"mappings":""}

package/dist/lib/option-types/type-resolution.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Core type resolution utilities for option configs.
+ * Uses structural typing to avoid circular imports.
+ */
+/**
+ * Check if a type is `any`.
+ * Uses the property that `1 & any` is `any`, and `0 extends any` is true.
+ */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/**
+ * Force TypeScript to fully expand a type.
+ * This helps with deferred type evaluation in recursive types.
+ */
+export type Expand<T> = T extends infer O ? {
+    [K in keyof O]: O[K];
+} : never;
+/**
+ * Deeply expand a type, including nested objects.
+ */
+export type ExpandDeep<T> = T extends object ? T extends infer O ? {
+    [K in keyof O]: ExpandDeep<O[K]>;
+} : never : T;
+/**
+ * Infer the choice type from an option config.
+ * Choices can be an array (including readonly) or a function returning an array.
+ */
+export type InferChoice<T> = T extends {
+    choices: readonly (infer C)[];
+} ? C : T extends {
+    choices: () => readonly (infer C)[];
+} ? C : never;
+/**
+ * Infer the coerced type. If coerce function exists, use its return type.
+ * Otherwise fall back to the provided fallback type.
+ *
+ * Uses optional property matching `coerce?:` to handle configs where coerce
+ * is defined as optional (like ObjectOptionConfig).
+ *
+ * Special handling:
+ * - [R] extends [never]: When coerce is missing/undefined, R infers as never
+ * - R extends undefined: When coerce explicitly returns undefined
+ */
+export type InferCoerce<T, TFallback> = T extends {
+    coerce?: (v: any) => infer R;
+} ? [R] extends [never] ? TFallback : R extends undefined ? TFallback : R : TFallback;
+/**
+ * Map an option config to its base TypeScript type.
+ * Uses structural typing to avoid circular imports.
+ */
+export type BaseType<T> = T extends {
+    type: 'string';
+} ? string : T extends {
+    type: 'number';
+} ? number : T extends {
+    type: 'boolean';
+} ? boolean : T extends {
+    type: 'array';
+    items: 'string';
+} ? string[] : T extends {
+    type: 'array';
+    items: 'number';
+} ? number[] : T extends {
+    type: 'object';
+    properties: infer P;
+    additionalProperties: infer A;
+} ? P extends Record<string, unknown> ? WithAdditionalProperties<ResolveProperties<P>, A> : never : T extends {
+    type: 'object';
+    properties: infer P;
+} ? P extends Record<string, unknown> ? ResolveProperties<P> : never : never;
+/**
+ * Resolve a single option config to its final type.
+ * Priority: choices > coerce > base type
+ */
+export type ResolveOptionType<T> = InferChoice<T> extends never ? InferCoerce<T, BaseType<T>> : InferChoice<T>;
+/**
+ * Wrap a resolved type with undefined if the option is optional.
+ * Required options or options with defaults are never undefined.
+ *
+ * Uses `'key' extends keyof TConfig` instead of `TConfig extends { key: unknown }`
+ * to properly detect OPTIONAL properties. The latter check fails for optional
+ * properties because `{ default?: X }` doesn't guarantee `default` exists.
+ */
+export type WithOptional<TResolved, TConfig> = TConfig extends {
+    required: true;
+} ? TResolved : 'default' extends keyof TConfig ? TResolved : TResolved | undefined;
+/**
+ * Resolve all properties of an object option to their types.
+ * Each property becomes its resolved type, wrapped with optional handling.
+ *
+ * Special case: when TProperties is `any` (from `OptionConfig<any, any, any, any>`),
+ * we return `unknown` to avoid creating an index signature that would hide
+ * the actual properties inferred from the value.
+ */
+export type ResolveProperties<TProperties> = IsAny<TProperties> extends true ? unknown : {
+    [K in keyof TProperties]: WithOptional<ResolveOptionType<TProperties[K]>, TProperties[K]>;
+};
+type BaseLevelAdditionalProperties<TAdditional> = IsAny<TAdditional> extends true ? unknown : [TAdditional] extends [false] ? never : [TAdditional] extends ['string'] ? string : [TAdditional] extends ['number'] ? number : [TAdditional] extends ['boolean'] ? boolean : never;
+/**
+ * Combines explicit properties with an index signature for additional properties.
+ *
+ * The index signature value is a union of all possible values (explicit + additional)
+ * to satisfy TypeScript's constraint that index signatures must be compatible with
+ * all explicit properties.
+ *
+ * This allows:
+ * - Explicit properties to keep their exact types via the intersection
+ * - Additional string keys to be added with the additionalProperties type
+ * - Bracket notation access returns the union of all possible types
+ */
+export type WithAdditionalProperties<TProperties, TAdditionalProperties> = TProperties & {
+    [key: string]: // | TProperties[keyof TProperties]
+    BaseLevelAdditionalProperties<TAdditionalProperties> | undefined;
+};
+/**
+ * Compute the full value type for an object option.
+ * Uses WithAdditionalProperties when additionalProperties is specified,
+ * which creates a compatible index signature.
+ */
+export type ObjectValueType<TProperties, TAdditionalProperties> = IsAny<TAdditionalProperties> extends true ? ResolveProperties<TProperties> : [TAdditionalProperties] extends [false] ? ResolveProperties<TProperties> : WithAdditionalProperties<ResolveProperties<TProperties>, TAdditionalProperties>;
+/**
+ * Makes properties whose type includes `undefined` optional.
+ * This allows omitting properties like `{ foo?: string | undefined }` from object literals
+ * instead of requiring `{ foo: undefined }`.
+ *
+ * Uses a simpler mapped type approach that works better with generic keys in .d.ts generation.
+ */
+export type MakeUndefinedPropertiesOptional<T> = {
+    [K in keyof T as undefined extends T[K] ? K : never]?: T[K];
+} & {
+    [K in keyof T as undefined extends T[K] ? never : K]: T[K];
+};
+export {};

package/dist/lib/option-types/type-resolution.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Core type resolution utilities for option configs.
+ * Uses structural typing to avoid circular imports.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=type-resolution.js.map

package/dist/lib/option-types/type-resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-resolution.js","sourceRoot":"","sources":["../../../src/lib/option-types/type-resolution.ts"],"names":[],"mappings":";AAAA;;;GAGG"}