@cli-forge/parser 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cli-forge/parser",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "dependencies": {
     "tslib": "^2.3.0"
   },

package/src/index.d.ts

@@ -1,3 +1,6 @@
 export * from './lib/parser';
-export * from './lib/utils';
+export * from './lib/utils/case-transformations';
 export * from './lib/helpers';
+export * from './lib/option-types';
+export * from './lib/utils/read-default-value';
+export * from './lib/utils/chain';

package/src/index.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./lib/parser"), exports);
-tslib_1.__exportStar(require("./lib/utils"), exports);
+tslib_1.__exportStar(require("./lib/utils/case-transformations"), exports);
 tslib_1.__exportStar(require("./lib/helpers"), exports);
+tslib_1.__exportStar(require("./lib/option-types"), exports);
+tslib_1.__exportStar(require("./lib/utils/read-default-value"), exports);
+tslib_1.__exportStar(require("./lib/utils/chain"), exports);
 //# sourceMappingURL=index.js.map

package/src/index.js.map

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

package/src/lib/option-types/array.d.ts

@@ -0,0 +1,16 @@
+import { CommonOptionConfig } from './common';
+/**
+ * Configuration for array options. Arrays are parsed from
+ * comma separated, space separated, or multiple values.
+ *
+ * e.g. `--foo a b c`, `--foo a,b,c`, or `--foo a --foo b --foo c`
+ */
+export type ArrayOptionConfig<TCoerce = string | number, TChoices = TCoerce[]> = StringArrayOptionConfig<TCoerce, TChoices> | NumberArrayOptionConfig<TCoerce, TChoices>;
+export type NumberArrayOptionConfig<TCoerce = number, TChoices = number[]> = {
+    type: 'array';
+    items: 'number';
+} & CommonOptionConfig<number[], TCoerce, TChoices>;
+export type StringArrayOptionConfig<TCoerce = string, TChoices = TCoerce[]> = {
+    type: 'array';
+    items: 'string';
+} & CommonOptionConfig<string[], TCoerce, TChoices>;

package/src/lib/option-types/array.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=array.js.map

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

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

package/src/lib/option-types/boolean.d.ts

@@ -0,0 +1,4 @@
+import { CommonOptionConfig } from './common';
+export type BooleanOptionConfig<TCoerce = boolean, TChoices = TCoerce[]> = {
+    type: 'boolean';
+} & CommonOptionConfig<boolean, TCoerce, TChoices>;

package/src/lib/option-types/boolean.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=boolean.js.map

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

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

package/src/lib/option-types/common.d.ts

@@ -0,0 +1,78 @@
+export type PlainDefaultValue<T> = T;
+export type DefaultValueWithDescription<T> = {
+    value: PlainDefaultValue<T>;
+    description: string;
+};
+export type DefaultValueWithFactory<T> = {
+    factory: () => PlainDefaultValue<T>;
+    description: string;
+};
+export type Default<T> = PlainDefaultValue<T> | DefaultValueWithDescription<T> | DefaultValueWithFactory<T>;
+export type CommonOptionConfig<T, TCoerce = T, TChoices = T[]> = {
+    /**
+     * If set to true, the option will be treated as a positional argument.
+     */
+    positional?: boolean;
+    /**
+     * Provide an array of aliases for the option.
+     */
+    alias?: string[];
+    /**
+     * Provide an array of choices for the option. Values not in the array will throw an error.
+     */
+    choices?: TChoices | (() => TChoices);
+    /**
+     * Provide a default value for the option.
+     *
+     * 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>;
+    /**
+     * Provide a description for the option.
+     */
+    description?: string;
+    /**
+     * Provide a function to coerce the value of the option.
+     * @param value Value of the option
+     * @returns Coerced value of the option
+     */
+    coerce?: (value: T) => TCoerce;
+    /**
+     * Provide a function to validate the value of the option.
+     * @param value Coerced value of the option
+     * @returns If the value is valid, return true. If the value is invalid, return false or a string with an error message.
+     */
+    validate?: (value: TCoerce) => boolean | string;
+    /**
+     * If true, the option is required.
+     */
+    required?: boolean;
+    /**
+     * If set, the option will be populated from the environment variable `${env}_${optionName}`.
+     * If set to true, the environment variable will be `${optionName}`.
+     * If explicitly set to false, environment variable population will be disabled for this option.
+     */
+    env?: string | boolean | {
+        /**
+         * What key should the value be read from in process.env
+         */
+        key: string;
+        /**
+         * If set to false, ignore prefix provided by .env() call.
+         */
+        prefix?: boolean;
+    };
+    /**
+     * If set, the option will be marked as deprecated, with the provided message. This will not effect runtime behavior,
+     * but will be displayed in help output and generated docs.
+     */
+    deprecated?: string;
+    /**
+     * If true, the option will not be displayed in help output or generated docs.
+     */
+    hidden?: boolean;
+    /**
+     * Can be set to group options in help output and generated docs.
+     */
+    group?: string;
+};

package/src/lib/option-types/common.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=common.js.map

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

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

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

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

package/src/lib/option-types/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./option-config-to-type"), exports);
+tslib_1.__exportStar(require("./common"), exports);
+tslib_1.__exportStar(require("./array"), exports);
+tslib_1.__exportStar(require("./boolean"), exports);
+tslib_1.__exportStar(require("./number"), exports);
+tslib_1.__exportStar(require("./object"), exports);
+tslib_1.__exportStar(require("./string"), exports);
+//# sourceMappingURL=index.js.map

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

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

package/src/lib/option-types/number.d.ts

@@ -0,0 +1,4 @@
+import { CommonOptionConfig } from './common';
+export type NumberOptionConfig<TCoerce = number, TChoices = TCoerce[]> = {
+    type: 'number';
+} & CommonOptionConfig<number, TCoerce, TChoices>;

package/src/lib/option-types/number.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=number.js.map

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

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

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

@@ -0,0 +1,10 @@
+import { CommonOptionConfig } from './common';
+import { OptionConfig } from './option-config';
+export interface ObjectOptionConfig<TCoerce = Record<string, string>, TProperties extends {
+    [key: string]: Readonly<OptionConfig>;
+} = Record<string, any>> extends Omit<CommonOptionConfig<Record<string, string>, TCoerce>, 'choices'> {
+    type: 'object';
+    /** */
+    properties: TProperties;
+    additionalProperties?: false | 'string' | 'number' | 'boolean';
+}

package/src/lib/option-types/object.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=object.js.map

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

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

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

@@ -0,0 +1,20 @@
+import { OptionConfig } from './option-config';
+import { ArrayOptionConfig } from './array';
+import { ObjectOptionConfig } from './object';
+/**
+ * Converts an OptionConfig to the TypeScript type for the parsed value.
+ */
+export type OptionConfigToType<TOptionConfig extends OptionConfig> = InferTChoice<TOptionConfig> extends [never] ? TOptionConfig['coerce'] extends (s: any) => any ? ReturnType<TOptionConfig['coerce']> : {
+    string: string;
+    number: number;
+    boolean: boolean;
+    array: ArrayItems<TOptionConfig>[];
+    object: TOptionConfig extends ObjectOptionConfig ? ResolveTProperties<TOptionConfig['properties']> & AdditionalProperties<TOptionConfig> : never;
+}[TOptionConfig['type']] : InferTChoice<TOptionConfig>;
+type ArrayItems<TOptionConfig extends OptionConfig> = TOptionConfig extends ArrayOptionConfig<string | number> ? TOptionConfig['items'] extends 'string' ? string : number : never;
+type AdditionalProperties<TOptionConfig extends ObjectOptionConfig> = TOptionConfig['additionalProperties'] extends 'string' ? Record<string, string> : TOptionConfig['additionalProperties'] extends 'number' ? Record<string, number> : TOptionConfig['additionalProperties'] extends 'boolean' ? Record<string, boolean> : Record<string, never>;
+type ResolveTProperties<TProperties extends Record<string, OptionConfig>> = {
+    [key in keyof TProperties]: OptionConfigToType<TProperties[key]>;
+};
+type InferTChoice<TOptionConfig> = 'choices' extends keyof TOptionConfig ? TOptionConfig['choices'] extends Array<infer TChoice> ? TChoice : TOptionConfig['choices'] extends () => Array<infer TChoice> ? TChoice : never : never;
+export {};

package/src/lib/option-types/option-config-to-type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=option-config-to-type.js.map

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

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

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

@@ -0,0 +1,15 @@
+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, OptionConfig> = Record<string, any>> = StringOptionConfig<TCoerce, TChoices> | NumberOptionConfig<TCoerce, TChoices> | ArrayOptionConfig<TCoerce, TChoices> | BooleanOptionConfig<TCoerce, TChoices> | ObjectOptionConfig<TCoerce, TObjectProps>;

package/src/lib/option-types/option-config.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=option-config.js.map

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

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

package/src/lib/option-types/string.d.ts

@@ -0,0 +1,4 @@
+import { CommonOptionConfig } from './common';
+export type StringOptionConfig<TCoerce = string, TChoices = TCoerce[]> = {
+    type: 'string';
+} & CommonOptionConfig<string, TCoerce, TChoices>;

package/src/lib/option-types/string.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=string.js.map

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

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

package/src/lib/parser.d.ts

@@ -1,100 +1,6 @@
-type Flatten<T> = T extends Array<infer U> ? U : T;
-export type CommonOptionConfig<T, TCoerce = T> = {
-    /**
-     * If set to true, the option will be treated as a positional argument.
-     */
-    positional?: boolean;
-    /**
-     * Provide an array of aliases for the option.
-     */
-    alias?: string[];
-    /**
-     * Provide an array of choices for the option. Values not in the array will throw an error.
-     */
-    choices?: Flatten<T>[] | (() => Flatten<T>[]);
-    /**
-     * Provide a default value for the option.
-     */
-    default?: T;
-    /**
-     * Provide a description for the option.
-     */
-    description?: string;
-    /**
-     * Provide a function to coerce the value of the option.
-     * @param value Value of the option
-     * @returns Coerced value of the option
-     */
-    coerce?: (value: T) => TCoerce;
-    /**
-     * Provide a function to validate the value of the option.
-     * @param value Coerced value of the option
-     * @returns If the value is valid, return true. If the value is invalid, return false or a string with an error message.
-     */
-    validate?: (value: TCoerce) => boolean | string;
-    /**
-     * If true, the option is required.
-     */
-    required?: boolean;
-    /**
-     * If set, the option will be populated from the environment variable `${env}_${optionName}`.
-     * If set to true, the environment variable will be `${optionName}`.
-     * If explicitly set to false, environment variable population will be disabled for this option.
-     */
-    env?: string | boolean | {
-        /**
-         * What key should the value be read from in process.env
-         */
-        key: string;
-        /**
-         * If set to false, ignore prefix provided by .env() call.
-         */
-        prefix?: boolean;
-    };
-    /**
-     * If set, the option will be marked as deprecated, with the provided message. This will not effect runtime behavior,
-     * but will be displayed in help output and generated docs.
-     */
-    deprecated?: string;
-};
-export type StringOptionConfig<TCoerce = string> = {
-    type: 'string';
-} & CommonOptionConfig<string, TCoerce>;
-export type NumberOptionConfig<TCoerce = number> = {
-    type: 'number';
-} & CommonOptionConfig<number, TCoerce>;
-export type BooleanOptionConfig<TCoerce = boolean> = {
-    type: 'boolean';
-} & CommonOptionConfig<boolean, TCoerce>;
-export type StringArrayOptionConfig<TCoerce = string> = {
-    type: 'array';
-    items: 'string';
-} & CommonOptionConfig<string[], TCoerce>;
-export type NumberArrayOptionConfig<TCoerce = number> = {
-    type: 'array';
-    items: 'number';
-} & CommonOptionConfig<number[], TCoerce>;
-/**
- * Configuration for array options. Arrays are parsed from
- * comma separated, space separated, or multiple values.
- *
- * e.g. `--foo a b c`, `--foo a,b,c`, or `--foo a --foo b --foo c`
- */
-export type ArrayOptionConfig<TCoerce = string | number> = StringArrayOptionConfig<TCoerce> | NumberArrayOptionConfig<TCoerce>;
-/**
- * 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> = StringOptionConfig<TCoerce> | NumberOptionConfig<TCoerce> | ArrayOptionConfig<TCoerce> | BooleanOptionConfig<TCoerce>;
-type InternalOptionConfig = OptionConfig & {
-    key: string;
-    position?: number;
-};
+import { OptionConfigToType } from './option-types/option-config-to-type';
+import { InternalOptionConfig, OptionConfig } from './option-types';
+import { Parser, ParserContext } from './parsers/typings';
 /**
  * Base type for parsed arguments.
  */
@@ -188,19 +94,16 @@ export declare class ArgvParser<TArgs extends ParsedArgs = {
      * @param config The configuration for the option. See {@link OptionConfig}
      * @returns Updated parser instance with the new option registered.
      */
-    option<TOption extends string, TOptionConfig extends OptionConfig>(name: TOption, config: TOptionConfig): ArgvParser<TArgs & { [key in TOption]: TOptionConfig["coerce"] extends (s: any) => any ? ReturnType<TOptionConfig["coerce"]> : {
-        string: string;
-        number: number;
-        boolean: boolean;
-        array: (TOptionConfig extends ArrayOptionConfig ? TOptionConfig["items"] extends "string" ? string : number : never)[];
-    }[TOptionConfig["type"]]; }>;
+    option<TOption extends string, const TOptionConfig extends OptionConfig<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 OptionConfig}
      * @returns Updated parser instance with the new positional argument registered.
      */
-    positional<TOption extends string>(name: TOption, config: OptionConfig): ArgvParser<TArgs & { [key in TOption]: string | number | boolean | (string | number)[]; }>;
+    positional<TOption extends string, const TOptionConfig extends OptionConfig<any>>(name: TOption, config: TOptionConfig): ArgvParser<TArgs & { [key in TOption]: OptionConfigToType<TOptionConfig & {
+        readonly positional: true;
+    }>; }>;
     /**
      * Enables environment variable population for options.
      * @param envPrefix Prefix for environment variables. The full environment variable name will be `${envPrefix}_${optionName}`.
@@ -244,12 +147,8 @@ export declare class ArgvParser<TArgs extends ParsedArgs = {
 export declare function parser(opts?: ParserOptions): ArgvParser<{
     unmatched: string[];
 }>;
-export declare class NoValueError extends Error {
-    constructor();
-}
-type Parser<TConfig extends OptionConfig, T = any> = (config: TConfig, tokens: string[], current?: T) => T;
+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>);
 }
-export {};