jackspeak 1.4.2 → 2.0.0

package/dist/cjs/index.d.ts

@@ -0,0 +1,150 @@
+/// <reference types="node" />
+export type ConfigType = 'number' | 'string' | 'boolean';
+import { inspect, InspectOptions } from 'node:util';
+type ValidValue<T extends ConfigType, M extends boolean> = [T, M] extends [
+    'number',
+    true
+] ? number[] : [T, M] extends ['string', true] ? string[] : [T, M] extends ['boolean', true] ? boolean[] : [T, M] extends ['number', false] ? number : [T, M] extends ['string', false] ? string : [T, M] extends ['boolean', false] ? boolean : [T, M] extends ['string', boolean] ? string | string[] : [T, M] extends ['boolean', boolean] ? boolean | boolean[] : [T, M] extends ['number', boolean] ? number | number[] : [T, M] extends [ConfigType, false] ? string | number | boolean : [T, M] extends [ConfigType, true] ? string[] | number[] | boolean[] : string | number | boolean | string[] | number[] | boolean[];
+export type ConfigOptionMeta<T extends ConfigType, M extends boolean> = {
+    default?: ValidValue<T, M> | undefined;
+    description?: string;
+    validate?: ((v: any) => v is ValidValue<T, M>) | ((v: any) => boolean);
+    short?: string | undefined;
+    type?: T;
+} & (T extends 'boolean' ? {} : {
+    hint?: string | undefined;
+}) & (M extends false ? {} : {
+    multiple?: M | undefined;
+    delim?: string | undefined;
+});
+export type ConfigMetaSet<T extends ConfigType, M extends boolean> = {
+    [longOption: string]: ConfigOptionMeta<T, M>;
+};
+type ConfigSetFromMetaSet<T extends ConfigType, M extends boolean, S extends ConfigMetaSet<T, M>> = {
+    [longOption in keyof S]: ConfigOptionBase<T, M>;
+};
+type MultiType<M extends boolean> = M extends true ? {
+    multiple: true;
+    delim?: string | undefined;
+} : M extends false ? {
+    multiple?: false | undefined;
+    delim?: undefined;
+} : {
+    multiple?: boolean | undefined;
+    delim?: string | undefined;
+};
+type ConfigOptionBase<T extends ConfigType, M extends boolean> = {
+    type: T;
+    short?: string | undefined;
+    default?: ValidValue<T, M> | undefined;
+    description?: string;
+    hint?: T extends 'boolean' ? undefined : string | undefined;
+    validate?: (v: any) => v is ValidValue<T, M>;
+} & MultiType<M>;
+type ConfigSet = {
+    [longOption: string]: ConfigOptionBase<ConfigType, boolean>;
+};
+type OptionsResults<T extends ConfigSet> = {
+    [k in keyof T]?: T[k] extends ConfigOptionBase<'string', false> ? string : T[k] extends ConfigOptionBase<'string', true> ? string[] : T[k] extends ConfigOptionBase<'number', false> ? number : T[k] extends ConfigOptionBase<'number', true> ? number[] : T[k] extends ConfigOptionBase<'boolean', false> ? boolean : T[k] extends ConfigOptionBase<'boolean', true> ? boolean[] : never;
+};
+type Parsed<T extends ConfigSet> = {
+    values: OptionsResults<T>;
+    positionals: string[];
+};
+export interface JackOptions {
+    /**
+     * Whether to allow positional arguments
+     *
+     * @default true
+     */
+    allowPositionals?: boolean;
+    /**
+     * Prefix to use when reading/writing the environment variables
+     *
+     * If not specified, environment behavior will not be available.
+     */
+    envPrefix?: string;
+    /**
+     * Environment object to read/write. Defaults `process.env`.
+     * No effect if `envPrefix` is not set.
+     */
+    env?: {
+        [k: string]: string | undefined;
+    };
+    /**
+     * A short usage string. If not provided, will be generated from the
+     * options provided, but that can of course be rather verbose if
+     * there are a lot of options.
+     */
+    usage?: string;
+    /**
+     * Stop parsing flags and opts at the first positional argument.
+     * This is to support cases like `cmd [flags] <subcmd> [options]`, where
+     * each subcommand may have different options.  This effectively treats
+     * any positional as a `--` argument.  Only relevant if `allowPositionals`
+     * is true.
+     *
+     * To do subcommands, set this option, look at the first positional, and
+     * parse the remaining positionals as appropriate.
+     *
+     * @default false
+     */
+    stopAtPositional?: boolean;
+}
+export declare class Jack<C extends ConfigSet = {}> {
+    #private;
+    constructor(options?: JackOptions);
+    parse(args?: string[]): Parsed<C>;
+    validate(o: any): asserts o is Parsed<C>['values'];
+    heading(text: string): Jack<C>;
+    /**
+     * Add a long-form description to the usage output at this position.
+     */
+    description(text: string): Jack<C>;
+    /**
+     * Add one or more number fields.
+     */
+    num<F extends ConfigMetaSet<'number', false>>(fields: F): Jack<C & ConfigSetFromMetaSet<'number', false, F>>;
+    /**
+     * Add one or more multiple number fields.
+     */
+    numList<F extends ConfigMetaSet<'number', true>>(fields: F): Jack<C & ConfigSetFromMetaSet<'number', true, F>>;
+    /**
+     * Add one or more string option fields.
+     */
+    opt<F extends ConfigMetaSet<'string', false>>(fields: F): Jack<C & ConfigSetFromMetaSet<'string', false, F>>;
+    /**
+     * Add one or more multiple string option fields.
+     */
+    optList<F extends ConfigMetaSet<'string', true>>(fields: F): Jack<C & ConfigSetFromMetaSet<'string', true, F>>;
+    /**
+     * Add one or more flag fields.
+     */
+    flag<F extends ConfigMetaSet<'boolean', false>>(fields: F): Jack<C & ConfigSetFromMetaSet<'boolean', false, F>>;
+    /**
+     * Add one or more multiple flag fields.
+     */
+    flagList<F extends ConfigMetaSet<'boolean', true>>(fields: F): Jack<C & ConfigSetFromMetaSet<'boolean', true, F>>;
+    /**
+     * Generic field definition method. Similar to flag/flagList/number/etc,
+     * but you must specify the `type` (and optionally `multiple` and `delim`)
+     * fields on each one, or Jack won't know how to define them.
+     */
+    addFields<F extends ConfigSet>(fields: F): Jack<C & F>;
+    usage(): string;
+    toJSON(): {
+        [k: string]: {
+            default?: string | number | boolean | number[] | string[] | boolean[] | undefined;
+            validate?: ((v: any) => v is string | number | boolean | number[] | string[] | boolean[]) | undefined;
+            description?: string | undefined;
+            short?: string | undefined;
+            delim?: string | undefined;
+            multiple?: boolean | undefined;
+            type: ConfigType;
+        };
+    };
+    [inspect.custom](_: number, options: InspectOptions): string;
+}
+export declare const jack: (options?: JackOptions) => Jack<{}>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}