@cli-forge/parser 0.10.0 → 0.11.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/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.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/config-files/index.ts"],"names":[],"mappings":";;;AAAA,iEAAuC;AACvC,6DAAmC;AACnC,gEAAsC"}

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,mCAA0C;AAE1C;;;;;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,uBAAe,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/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,yDAA6D;AAE7D;;;;GAIG;AACH,SAAgB,iCAAiC,CAC/C,GAAW;IAEX,MAAM,MAAM,GAAG,IAAA,0CAAuB,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,74 @@
+import { CommonOptionConfig, Default } from './common';
+import { ResolveProperties, AdditionalPropertiesType } 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 a structural constraint for TProperties to avoid circular imports
+ * with option-config.ts.
+ */
+type ObjectValue<TProperties extends Record<string, {
+    type: string;
+}>, TAdditionalProperties extends false | 'string' | 'number' | 'boolean'> = ResolveProperties<TProperties> & AdditionalPropertiesType<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, AdditionalPropertiesType } 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, AdditionalPropertiesType };

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,126 @@
+/**
+ * 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> ? ResolveProperties<P> & AdditionalPropertiesType<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]>;
+};
+/**
+ * Map the additionalProperties field to an index signature type.
+ * If false, undefined, or any, contributes nothing to the type.
+ *
+ * IMPORTANT: We use `unknown` in the index signature instead of the strict
+ * primitive type (e.g., `Record<string, string>`) to avoid conflicts with
+ * explicit nested properties. TypeScript's index signatures require ALL values
+ * (including explicit properties) to be assignable to the index type. Using
+ * `Record<string, string>` would make `{ server: {...} } & Record<string, string>`
+ * impossible since the nested object isn't a string.
+ *
+ * By using `{ [K: string]: unknown }`, the type is "open" - explicit properties
+ * retain their types while additional dynamic keys are allowed. Type safety
+ * for additional properties is enforced at runtime during parsing.
+ *
+ * Uses tuple wrapping to prevent distribution over unions.
+ */
+export type AdditionalPropertiesType<T> = IsAny<T> extends true ? unknown : [T] extends [false] ? unknown : [T] extends ['string'] ? {
+    [K: string]: string;
+} : [T] extends ['number'] ? {
+    [K: string]: number;
+} : [T] extends ['boolean'] ? {
+    [K: string]: boolean;
+} : unknown;
+/**
+ * Compute the full value type for an object option.
+ * Combines resolved properties with additional properties index signature.
+ */
+export type ObjectValueType<TProperties, TAdditionalProperties> = ResolveProperties<TProperties> & AdditionalPropertiesType<TAdditionalProperties>;
+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"}

package/dist/lib/parser.d.ts

@@ -0,0 +1,218 @@
+import { OptionConfigToType, ResolveProperties, AdditionalPropertiesType } from './option-types/option-config-to-type';
+import { WithOptional } from './option-types/type-resolution';
+import { InternalOptionConfig, ObjectOptionConfig, StringOptionConfig, NumberOptionConfig, BooleanOptionConfig, ArrayOptionConfig, OptionConfig } from './option-types';
+import { Parser, ParserContext } from './parsers/typings';
+import { ConfigurationProvider } from './config-files/configuration-loader';
+/**
+ * Defines the option configuration passed to {@link ArgvParser.env}.
+ */
+export type EnvOptionConfig = {
+    prefix?: string;
+    reflect?: boolean;
+    populate?: boolean;
+};
+/**
+ * Base type for parsed arguments.
+ */
+export type ParsedArgs<T = never> = [T] extends [never] ? {
+    /**
+     * Contains any unmatched arguments as originally passed to the parser.
+     */
+    unmatched: string[];
+    /**
+     * Contains any arguments passed after `--`, which halts parsing of flags.
+     */
+    '--'?: string[];
+} : {
+    /**
+     * Contains any unmatched arguments as originally passed to the parser.
+     */
+    unmatched: string[];
+    /**
+     * Contains any arguments passed after `--`, which halts parsing of flags.
+     */
+    '--'?: string[];
+} & T;
+/**
+ * Extra options for the parser
+ */
+export type ParserOptions<T extends ParsedArgs = ParsedArgs> = {
+    /**
+     * Can be used to implement custom parser types.
+     */
+    extraParsers?: Record<string, Parser<any>>;
+    /**
+     * Can be used to implement custom handling for unmatched arguments.
+     * @returns true if the argument was handled, false if it was not
+     */
+    unmatchedParser?: (arg: string, tokens: string[], parser: ArgvParser<T>) => boolean;
+};
+export interface ReadonlyArgvParser<TArgs extends ParsedArgs> {
+    configuredOptions: Readonly<{
+        [key in keyof TArgs]: InternalOptionConfig;
+    }>;
+    configuredPositionals: readonly Readonly<InternalOptionConfig>[];
+    options: Readonly<Required<ParserOptions<TArgs>>>;
+}
+/**
+ * The main parser class. This class is used to configure and parse arguments.
+ *
+ * {@link parser} is a small helper function to create a new parser instance.
+ */
+export declare class ArgvParser<TArgs extends ParsedArgs = {
+    unmatched: string[];
+}> implements ReadonlyArgvParser<TArgs> {
+    /**
+     * The configured options for the parser.
+     */
+    configuredOptions: {
+        [key in keyof TArgs]: InternalOptionConfig;
+    };
+    /**
+     * The configured positional arguments for the parser
+     */
+    configuredPositionals: InternalOptionConfig[];
+    /**
+     * The configured conflicts for the parser. If an option is set, and a conflicting option is also set, an error will be thrown.
+     */
+    configuredConflicts: Record<string, Set<string>>;
+    /**
+     * The configured implies for the parser. If an option is set, the implied option must also be set.
+     */
+    configuredImplies: Record<string, Set<string>>;
+    /**
+     * The configuration for the parser itself
+     */
+    options: Required<ParserOptions<TArgs>>;
+    /**
+     * The parsers used to parse individual option types.
+     */
+    parserMap: Record<string, Parser<any>>;
+    private configuredConfigurationProviders;
+    /**
+     * If set, options can be populated from environment variables of the form `${envPrefix}_${optionName}`.
+     */
+    private envPrefix?;
+    private shouldReadFromEnv?;
+    private shouldReflectEnv?;
+    /**
+     * Creates a new parser. Normally using {@link parser} is preferred.
+     * @param options
+     */
+    constructor(options?: ParserOptions<TArgs>);
+    /**
+     * Registers a new option with the parser.
+     * @param name The name of the option
+     * @param config The configuration for the option. See {@link UnknownOptionConfig}
+     * @returns Updated parser instance with the new option registered.
+     */
+    option<TOption extends string, TCoerce, const TProps extends Record<string, {
+        type: string;
+    }>, TAdditionalProps extends false | 'string' | 'number' | 'boolean' = false>(name: TOption, config: ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>): ArgvParser<TArgs & {
+        [key in TOption]: WithOptional<unknown extends TCoerce ? ResolveProperties<TProps> & AdditionalPropertiesType<TAdditionalProps> : TCoerce, ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>>;
+    }>;
+    option<TOption extends string, const TConfig extends StringOptionConfig<any, any>>(name: TOption, config: TConfig): ArgvParser<TArgs & {
+        [key in TOption]: OptionConfigToType<TConfig>;
+    }>;
+    option<TOption extends string, const TConfig extends NumberOptionConfig<any, any>>(name: TOption, config: TConfig): ArgvParser<TArgs & {
+        [key in TOption]: OptionConfigToType<TConfig>;
+    }>;
+    option<TOption extends string, const TConfig extends BooleanOptionConfig<any, any>>(name: TOption, config: TConfig): ArgvParser<TArgs & {
+        [key in TOption]: OptionConfigToType<TConfig>;
+    }>;
+    option<TOption extends string, const TConfig extends ArrayOptionConfig<any, any>>(name: TOption, config: TConfig): ArgvParser<TArgs & {
+        [key in TOption]: OptionConfigToType<TConfig>;
+    }>;
+    option<TOption extends string, const TOptionConfig extends OptionConfig<any, any, any, any>>(name: TOption, config: TOptionConfig): ArgvParser<TArgs & {
+        [key in TOption]: OptionConfigToType<TOptionConfig>;
+    }>;
+    /**
+     * Registers a new positional argument with the parser.
+     * @param name The name of the positional argument
+     * @param config The configuration for the positional argument. See {@link UnknownOptionConfig}
+     * @returns Updated parser instance with the new positional argument registered.
+     */
+    positional<TOption extends string, TCoerce, const TProps extends Record<string, {
+        type: string;
+    }>, TAdditionalProps extends false | 'string' | 'number' | 'boolean' = false>(name: TOption, config: ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>): ArgvParser<TArgs & {
+        [key in TOption]: WithOptional<unknown extends TCoerce ? ResolveProperties<TProps> & AdditionalPropertiesType<TAdditionalProps> : TCoerce, ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>>;
+    }>;
+    positional<TOption extends string, const TConfig extends StringOptionConfig<any, any>>(name: TOption, config: TConfig): ArgvParser<TArgs & {
+        [key in TOption]: OptionConfigToType<TConfig>;
+    }>;
+    positional<TOption extends string, const TConfig extends NumberOptionConfig<any, any>>(name: TOption, config: TConfig): ArgvParser<TArgs & {
+        [key in TOption]: OptionConfigToType<TConfig>;
+    }>;
+    positional<TOption extends string, const TConfig extends BooleanOptionConfig<any, any>>(name: TOption, config: TConfig): ArgvParser<TArgs & {
+        [key in TOption]: OptionConfigToType<TConfig>;
+    }>;
+    positional<TOption extends string, const TConfig extends ArrayOptionConfig<any, any>>(name: TOption, config: TConfig): ArgvParser<TArgs & {
+        [key in TOption]: OptionConfigToType<TConfig>;
+    }>;
+    positional<TOption extends string, const TOptionConfig extends OptionConfig<any, any, any, any>>(name: TOption, config: TOptionConfig): ArgvParser<TArgs & {
+        [key in TOption]: OptionConfigToType<TOptionConfig>;
+    }>;
+    /**
+     * Enables environment variable population for options.
+     * @param envPrefix Prefix for environment variables. The full environment variable name will be `${envPrefix}_${optionName}`.
+     */
+    env(envPrefix?: string): typeof this;
+    env(options: EnvOptionConfig): typeof this;
+    /**
+     * Registers a configuration provider to read configuration from.
+     * @param provider The configuration provider to register.
+     */
+    config(provider: ConfigurationProvider<TArgs>): this;
+    /**
+     * Parses an array of arguments into a structured object.
+     * @param argv The array of arguments to parse
+     * @returns The parsed arguments
+     */
+    parse(argv?: string[]): TArgs;
+    private normalizeOptions;
+    private validateAndNormalizeResults;
+    private readFromEnv;
+    private reflectEnv;
+    private cachedConfigKey;
+    private cachedConfig;
+    private getEnvKey;
+    private readFromConfig;
+    /**
+     * Registers that a set of options cannot be provided at the same time.
+     * @param options The options that cannot be provided together.
+     */
+    conflicts(...options: [string, string, ...string[]]): this;
+    /**
+     * Registers that the presence of one option implies the presence of one or more other options.
+     * @param options The options that imply the other option.
+     */
+    implies(option: string, ...options: string[]): this;
+    /**
+     * Used to combine two parsers into a single parser. Mutates `this`, but returns with updated typings
+     * @param parser The parser to augment the current parser with.
+     * @returns The updated parser instance.
+     */
+    augment<TAugment extends ParsedArgs>(parser: ArgvParser<TAugment>): ArgvParser<TArgs & TAugment>;
+    clone(parserOptions?: ParserOptions<TArgs>): ArgvParser<TArgs>;
+    asReadonly(): ReadonlyArgvParser<TArgs>;
+}
+/**
+ * Small helper function to create a new parser instance.
+ * @param opts see {@link ParserOptions}
+ * @returns new parser, see {@link ArgvParser}
+ */
+export declare function parser(opts?: ParserOptions): ArgvParser<{
+    /**
+     * Contains any unmatched arguments as originally passed to the parser.
+     */
+    unmatched: string[];
+    /**
+     * Contains any arguments passed after `--`, which halts parsing of flags.
+     */
+    '--'?: string[];
+}>;
+export declare function tryParseValue(parser: Parser<InternalOptionConfig>, input: ParserContext<InternalOptionConfig>): any;
+export declare class ValidationFailedError<T> extends AggregateError {
+    partialArgV: Partial<T>;
+    constructor(errors: Error[], message: string, partialArgV: Partial<T>);
+}