• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1import { inspect } from 'node:util';
2import { parseArgs } from './parse-args.js';
3// it's a tiny API, just cast it inline, it's fine
4//@ts-ignore
5import cliui from '@isaacs/cliui';
6import { basename } from 'node:path';
7const width = Math.min((process && process.stdout && process.stdout.columns) || 80, 80);
8// indentation spaces from heading level
9const indent = (n) => (n - 1) * 2;
10const toEnvKey = (pref, key) => {
11    return [pref, key.replace(/[^a-zA-Z0-9]+/g, ' ')]
12        .join(' ')
13        .trim()
14        .toUpperCase()
15        .replace(/ /g, '_');
16};
17const toEnvVal = (value, delim = '\n') => {
18    const str = typeof value === 'string'
19        ? value
20        : typeof value === 'boolean'
21            ? value
22                ? '1'
23                : '0'
24            : typeof value === 'number'
25                ? String(value)
26                : Array.isArray(value)
27                    ? value
28                        .map((v) => toEnvVal(v))
29                        .join(delim)
30                    : /* c8 ignore start */
31                        undefined;
32    if (typeof str !== 'string') {
33        throw new Error(`could not serialize value to environment: ${JSON.stringify(value)}`);
34    }
35    /* c8 ignore stop */
36    return str;
37};
38const fromEnvVal = (env, type, multiple, delim = '\n') => (multiple
39    ? env.split(delim).map(v => fromEnvVal(v, type, false))
40    : type === 'string'
41        ? env
42        : type === 'boolean'
43            ? env === '1'
44            : +env.trim());
45export const isConfigType = (t) => typeof t === 'string' &&
46    (t === 'string' || t === 'number' || t === 'boolean');
47const undefOrType = (v, t) => v === undefined || typeof v === t;
48// print the value type, for error message reporting
49const valueType = (v) => typeof v === 'string'
50    ? 'string'
51    : typeof v === 'boolean'
52        ? 'boolean'
53        : typeof v === 'number'
54            ? 'number'
55            : Array.isArray(v)
56                ? joinTypes([...new Set(v.map(v => valueType(v)))]) + '[]'
57                : `${v.type}${v.multiple ? '[]' : ''}`;
58const joinTypes = (types) => types.length === 1 ? types[0] : `(${types.join('|')})`;
59const isValidValue = (v, type, multi) => {
60    if (multi) {
61        if (!Array.isArray(v))
62            return false;
63        return !v.some((v) => !isValidValue(v, type, false));
64    }
65    if (Array.isArray(v))
66        return false;
67    return typeof v === type;
68};
69export const isConfigOption = (o, type, multi) => !!o &&
70    typeof o === 'object' &&
71    isConfigType(o.type) &&
72    o.type === type &&
73    undefOrType(o.short, 'string') &&
74    undefOrType(o.description, 'string') &&
75    undefOrType(o.hint, 'string') &&
76    undefOrType(o.validate, 'function') &&
77    (o.default === undefined || isValidValue(o.default, type, multi)) &&
78    !!o.multiple === multi;
79function num(o = {}) {
80    const { default: def, validate: val, ...rest } = o;
81    if (def !== undefined && !isValidValue(def, 'number', false)) {
82        throw new TypeError('invalid default value');
83    }
84    const validate = val
85        ? val
86        : undefined;
87    return {
88        ...rest,
89        default: def,
90        validate,
91        type: 'number',
92        multiple: false,
93    };
94}
95function numList(o = {}) {
96    const { default: def, validate: val, ...rest } = o;
97    if (def !== undefined && !isValidValue(def, 'number', true)) {
98        throw new TypeError('invalid default value');
99    }
100    const validate = val
101        ? val
102        : undefined;
103    return {
104        ...rest,
105        default: def,
106        validate,
107        type: 'number',
108        multiple: true,
109    };
110}
111function opt(o = {}) {
112    const { default: def, validate: val, ...rest } = o;
113    if (def !== undefined && !isValidValue(def, 'string', false)) {
114        throw new TypeError('invalid default value');
115    }
116    const validate = val
117        ? val
118        : undefined;
119    return {
120        ...rest,
121        default: def,
122        validate,
123        type: 'string',
124        multiple: false,
125    };
126}
127function optList(o = {}) {
128    const { default: def, validate: val, ...rest } = o;
129    if (def !== undefined && !isValidValue(def, 'string', true)) {
130        throw new TypeError('invalid default value');
131    }
132    const validate = val
133        ? val
134        : undefined;
135    return {
136        ...rest,
137        default: def,
138        validate,
139        type: 'string',
140        multiple: true,
141    };
142}
143function flag(o = {}) {
144    const { hint, default: def, validate: val, ...rest } = o;
145    if (def !== undefined && !isValidValue(def, 'boolean', false)) {
146        throw new TypeError('invalid default value');
147    }
148    const validate = val
149        ? val
150        : undefined;
151    if (hint !== undefined) {
152        throw new TypeError('cannot provide hint for flag');
153    }
154    return {
155        ...rest,
156        default: def,
157        validate,
158        type: 'boolean',
159        multiple: false,
160    };
161}
162function flagList(o = {}) {
163    const { hint, default: def, validate: val, ...rest } = o;
164    if (def !== undefined && !isValidValue(def, 'boolean', true)) {
165        throw new TypeError('invalid default value');
166    }
167    const validate = val
168        ? val
169        : undefined;
170    if (hint !== undefined) {
171        throw new TypeError('cannot provide hint for flag list');
172    }
173    return {
174        ...rest,
175        default: def,
176        validate,
177        type: 'boolean',
178        multiple: true,
179    };
180}
181const toParseArgsOptionsConfig = (options) => {
182    const c = {};
183    for (const longOption in options) {
184        const config = options[longOption];
185        if (isConfigOption(config, 'number', true)) {
186            c[longOption] = {
187                type: 'string',
188                multiple: true,
189                default: config.default?.map(c => String(c)),
190            };
191        }
192        else if (isConfigOption(config, 'number', false)) {
193            c[longOption] = {
194                type: 'string',
195                multiple: false,
196                default: config.default === undefined
197                    ? undefined
198                    : String(config.default),
199            };
200        }
201        else {
202            const conf = config;
203            c[longOption] = {
204                type: conf.type,
205                multiple: conf.multiple,
206                default: conf.default,
207            };
208        }
209        if (typeof config.short === 'string') {
210            c[longOption].short = config.short;
211        }
212        if (config.type === 'boolean' &&
213            !longOption.startsWith('no-') &&
214            !options[`no-${longOption}`]) {
215            c[`no-${longOption}`] = {
216                type: 'boolean',
217                multiple: config.multiple,
218            };
219        }
220    }
221    return c;
222};
223const isHeading = (r) => r.type === 'heading';
224const isDescription = (r) => r.type === 'description';
225/**
226 * Class returned by the {@link jack} function and all configuration
227 * definition methods.  This is what gets chained together.
228 */
229export class Jack {
230    #configSet;
231    #shorts;
232    #options;
233    #fields = [];
234    #env;
235    #envPrefix;
236    #allowPositionals;
237    #usage;
238    constructor(options = {}) {
239        this.#options = options;
240        this.#allowPositionals = options.allowPositionals !== false;
241        this.#env =
242            this.#options.env === undefined ? process.env : this.#options.env;
243        this.#envPrefix = options.envPrefix;
244        // We need to fib a little, because it's always the same object, but it
245        // starts out as having an empty config set.  Then each method that adds
246        // fields returns `this as Jack<C & { ...newConfigs }>`
247        this.#configSet = Object.create(null);
248        this.#shorts = Object.create(null);
249    }
250    /**
251     * Set the default value (which will still be overridden by env or cli)
252     * as if from a parsed config file. The optional `source` param, if
253     * provided, will be included in error messages if a value is invalid or
254     * unknown.
255     */
256    setConfigValues(values, source = '') {
257        try {
258            this.validate(values);
259        }
260        catch (er) {
261            throw Object.assign(er, source ? { source } : {});
262        }
263        for (const [field, value] of Object.entries(values)) {
264            const my = this.#configSet[field];
265            my.default = value;
266        }
267        return this;
268    }
269    /**
270     * Parse a string of arguments, and return the resulting
271     * `{ values, positionals }` object.
272     *
273     * If an {@link JackOptions#envPrefix} is set, then it will read default
274     * values from the environment, and write the resulting values back
275     * to the environment as well.
276     *
277     * Environment values always take precedence over any other value, except
278     * an explicit CLI setting.
279     */
280    parse(args = process.argv) {
281        if (args === process.argv) {
282            args = args.slice(process._eval !== undefined ? 1 : 2);
283        }
284        if (this.#envPrefix) {
285            for (const [field, my] of Object.entries(this.#configSet)) {
286                const ek = toEnvKey(this.#envPrefix, field);
287                const env = this.#env[ek];
288                if (env !== undefined) {
289                    my.default = fromEnvVal(env, my.type, !!my.multiple, my.delim);
290                }
291            }
292        }
293        const options = toParseArgsOptionsConfig(this.#configSet);
294        const result = parseArgs({
295            args,
296            options,
297            // always strict, but using our own logic
298            strict: false,
299            allowPositionals: this.#allowPositionals,
300            tokens: true,
301        });
302        const p = {
303            values: {},
304            positionals: [],
305        };
306        for (const token of result.tokens) {
307            if (token.kind === 'positional') {
308                p.positionals.push(token.value);
309                if (this.#options.stopAtPositional) {
310                    p.positionals.push(...args.slice(token.index + 1));
311                    return p;
312                }
313            }
314            else if (token.kind === 'option') {
315                let value = undefined;
316                if (token.name.startsWith('no-')) {
317                    const my = this.#configSet[token.name];
318                    const pname = token.name.substring('no-'.length);
319                    const pos = this.#configSet[pname];
320                    if (pos &&
321                        pos.type === 'boolean' &&
322                        (!my ||
323                            (my.type === 'boolean' && !!my.multiple === !!pos.multiple))) {
324                        value = false;
325                        token.name = pname;
326                    }
327                }
328                const my = this.#configSet[token.name];
329                if (!my) {
330                    throw new Error(`Unknown option '${token.rawName}'. ` +
331                        `To specify a positional argument starting with a '-', ` +
332                        `place it at the end of the command after '--', as in ` +
333                        `'-- ${token.rawName}'`);
334                }
335                if (value === undefined) {
336                    if (token.value === undefined) {
337                        if (my.type !== 'boolean') {
338                            throw new Error(`No value provided for ${token.rawName}, expected ${my.type}`);
339                        }
340                        value = true;
341                    }
342                    else {
343                        if (my.type === 'boolean') {
344                            throw new Error(`Flag ${token.rawName} does not take a value, received '${token.value}'`);
345                        }
346                        if (my.type === 'string') {
347                            value = token.value;
348                        }
349                        else {
350                            value = +token.value;
351                            if (value !== value) {
352                                throw new Error(`Invalid value '${token.value}' provided for ` +
353                                    `'${token.rawName}' option, expected number`);
354                            }
355                        }
356                    }
357                }
358                if (my.multiple) {
359                    const pv = p.values;
360                    pv[token.name] = pv[token.name] ?? [];
361                    pv[token.name].push(value);
362                }
363                else {
364                    const pv = p.values;
365                    pv[token.name] = value;
366                }
367            }
368        }
369        for (const [field, c] of Object.entries(this.#configSet)) {
370            if (c.default !== undefined && !(field in p.values)) {
371                //@ts-ignore
372                p.values[field] = c.default;
373            }
374        }
375        for (const [field, value] of Object.entries(p.values)) {
376            const valid = this.#configSet[field].validate;
377            if (valid && !valid(value)) {
378                throw new Error(`Invalid value provided for --${field}: ${JSON.stringify(value)}`);
379            }
380        }
381        this.#writeEnv(p);
382        return p;
383    }
384    /**
385     * Validate that any arbitrary object is a valid configuration `values`
386     * object.  Useful when loading config files or other sources.
387     */
388    validate(o) {
389        if (!o || typeof o !== 'object') {
390            throw new Error('Invalid config: not an object');
391        }
392        for (const field in o) {
393            const config = this.#configSet[field];
394            if (!config) {
395                throw new Error(`Unknown config option: ${field}`);
396            }
397            if (!isValidValue(o[field], config.type, !!config.multiple)) {
398                throw Object.assign(new Error(`Invalid value ${valueType(o[field])} for ${field}, expected ${valueType(config)}`), {
399                    field,
400                    value: o[field],
401                });
402            }
403            if (config.validate && !config.validate(o[field])) {
404                throw new Error(`Invalid config value for ${field}: ${o[field]}`);
405            }
406        }
407    }
408    #writeEnv(p) {
409        if (!this.#env || !this.#envPrefix)
410            return;
411        for (const [field, value] of Object.entries(p.values)) {
412            const my = this.#configSet[field];
413            this.#env[toEnvKey(this.#envPrefix, field)] = toEnvVal(value, my.delim);
414        }
415    }
416    /**
417     * Add a heading to the usage output banner
418     */
419    heading(text, level) {
420        if (level === undefined) {
421            level = this.#fields.some(r => isHeading(r)) ? 2 : 1;
422        }
423        this.#fields.push({ type: 'heading', text, level });
424        return this;
425    }
426    /**
427     * Add a long-form description to the usage output at this position.
428     */
429    description(text, { pre } = {}) {
430        this.#fields.push({ type: 'description', text, pre });
431        return this;
432    }
433    /**
434     * Add one or more number fields.
435     */
436    num(fields) {
437        return this.#addFields(fields, num);
438    }
439    /**
440     * Add one or more multiple number fields.
441     */
442    numList(fields) {
443        return this.#addFields(fields, numList);
444    }
445    /**
446     * Add one or more string option fields.
447     */
448    opt(fields) {
449        return this.#addFields(fields, opt);
450    }
451    /**
452     * Add one or more multiple string option fields.
453     */
454    optList(fields) {
455        return this.#addFields(fields, optList);
456    }
457    /**
458     * Add one or more flag fields.
459     */
460    flag(fields) {
461        return this.#addFields(fields, flag);
462    }
463    /**
464     * Add one or more multiple flag fields.
465     */
466    flagList(fields) {
467        return this.#addFields(fields, flagList);
468    }
469    /**
470     * Generic field definition method. Similar to flag/flagList/number/etc,
471     * but you must specify the `type` (and optionally `multiple` and `delim`)
472     * fields on each one, or Jack won't know how to define them.
473     */
474    addFields(fields) {
475        const next = this;
476        for (const [name, field] of Object.entries(fields)) {
477            this.#validateName(name, field);
478            next.#fields.push({
479                type: 'config',
480                name,
481                value: field,
482            });
483        }
484        Object.assign(next.#configSet, fields);
485        return next;
486    }
487    #addFields(fields, fn) {
488        const next = this;
489        Object.assign(next.#configSet, Object.fromEntries(Object.entries(fields).map(([name, field]) => {
490            this.#validateName(name, field);
491            const option = fn(field);
492            next.#fields.push({
493                type: 'config',
494                name,
495                value: option,
496            });
497            return [name, option];
498        })));
499        return next;
500    }
501    #validateName(name, field) {
502        if (!/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/.test(name)) {
503            throw new TypeError(`Invalid option name: ${name}, ` +
504                `must be '-' delimited ASCII alphanumeric`);
505        }
506        if (this.#configSet[name]) {
507            throw new TypeError(`Cannot redefine option ${field}`);
508        }
509        if (this.#shorts[name]) {
510            throw new TypeError(`Cannot redefine option ${name}, already ` +
511                `in use for ${this.#shorts[name]}`);
512        }
513        if (field.short) {
514            if (!/^[a-zA-Z0-9]$/.test(field.short)) {
515                throw new TypeError(`Invalid ${name} short option: ${field.short}, ` +
516                    'must be 1 ASCII alphanumeric character');
517            }
518            if (this.#shorts[field.short]) {
519                throw new TypeError(`Invalid ${name} short option: ${field.short}, ` +
520                    `already in use for ${this.#shorts[field.short]}`);
521            }
522            this.#shorts[field.short] = name;
523            this.#shorts[name] = name;
524        }
525    }
526    /**
527     * Return the usage banner for the given configuration
528     */
529    usage() {
530        if (this.#usage)
531            return this.#usage;
532        let headingLevel = 1;
533        const ui = cliui({ width });
534        const first = this.#fields[0];
535        let start = first?.type === 'heading' ? 1 : 0;
536        if (first?.type === 'heading') {
537            ui.div({
538                padding: [0, 0, 0, 0],
539                text: normalize(first.text),
540            });
541        }
542        ui.div({ padding: [0, 0, 0, 0], text: 'Usage:' });
543        if (this.#options.usage) {
544            ui.div({
545                text: this.#options.usage,
546                padding: [0, 0, 0, 2],
547            });
548        }
549        else {
550            const cmd = basename(process.argv[1]);
551            const shortFlags = [];
552            const shorts = [];
553            const flags = [];
554            const opts = [];
555            for (const [field, config] of Object.entries(this.#configSet)) {
556                if (config.short) {
557                    if (config.type === 'boolean')
558                        shortFlags.push(config.short);
559                    else
560                        shorts.push([config.short, config.hint || field]);
561                }
562                else {
563                    if (config.type === 'boolean')
564                        flags.push(field);
565                    else
566                        opts.push([field, config.hint || field]);
567                }
568            }
569            const sf = shortFlags.length ? ' -' + shortFlags.join('') : '';
570            const so = shorts.map(([k, v]) => ` --${k}=<${v}>`).join('');
571            const lf = flags.map(k => ` --${k}`).join('');
572            const lo = opts.map(([k, v]) => ` --${k}=<${v}>`).join('');
573            const usage = `${cmd}${sf}${so}${lf}${lo}`.trim();
574            ui.div({
575                text: usage,
576                padding: [0, 0, 0, 2],
577            });
578        }
579        ui.div({ padding: [0, 0, 0, 0], text: '' });
580        const maybeDesc = this.#fields[start];
581        if (isDescription(maybeDesc)) {
582            const print = normalize(maybeDesc.text, maybeDesc.pre);
583            start++;
584            ui.div({ padding: [0, 0, 0, 0], text: print });
585            ui.div({ padding: [0, 0, 0, 0], text: '' });
586        }
587        // turn each config type into a row, and figure out the width of the
588        // left hand indentation for the option descriptions.
589        let maxMax = Math.max(12, Math.min(26, Math.floor(width / 3)));
590        let maxWidth = 8;
591        let prev = undefined;
592        const rows = [];
593        for (const field of this.#fields.slice(start)) {
594            if (field.type !== 'config') {
595                if (prev?.type === 'config')
596                    prev.skipLine = true;
597                prev = undefined;
598                field.text = normalize(field.text, !!field.pre);
599                rows.push(field);
600                continue;
601            }
602            const { value } = field;
603            const desc = value.description || '';
604            const mult = value.multiple ? 'Can be set multiple times' : '';
605            const dmDelim = mult && (desc.includes('\n') ? '\n\n' : '\n');
606            const text = normalize(desc + dmDelim + mult);
607            const hint = value.hint ||
608                (value.type === 'number'
609                    ? 'n'
610                    : value.type === 'string'
611                        ? field.name
612                        : undefined);
613            const short = !value.short
614                ? ''
615                : value.type === 'boolean'
616                    ? `-${value.short} `
617                    : `-${value.short}<${hint}> `;
618            const left = value.type === 'boolean'
619                ? `${short}--${field.name}`
620                : `${short}--${field.name}=<${hint}>`;
621            const row = { text, left, type: 'config' };
622            if (text.length > width - maxMax) {
623                row.skipLine = true;
624            }
625            if (prev && left.length > maxMax)
626                prev.skipLine = true;
627            prev = row;
628            const len = left.length + 4;
629            if (len > maxWidth && len < maxMax) {
630                maxWidth = len;
631            }
632            rows.push(row);
633        }
634        // every heading/description after the first gets indented by 2
635        // extra spaces.
636        for (const row of rows) {
637            if (row.left) {
638                // If the row is too long, don't wrap it
639                // Bump the right-hand side down a line to make room
640                const configIndent = indent(Math.max(headingLevel, 2));
641                if (row.left.length > maxWidth - 2) {
642                    ui.div({ text: row.left, padding: [0, 0, 0, configIndent] });
643                    ui.div({ text: row.text, padding: [0, 0, 0, maxWidth] });
644                }
645                else {
646                    ui.div({
647                        text: row.left,
648                        padding: [0, 1, 0, configIndent],
649                        width: maxWidth,
650                    }, { padding: [0, 0, 0, 0], text: row.text });
651                }
652                if (row.skipLine) {
653                    ui.div({ padding: [0, 0, 0, 0], text: '' });
654                }
655            }
656            else {
657                if (isHeading(row)) {
658                    const { level } = row;
659                    headingLevel = level;
660                    // only h1 and h2 have bottom padding
661                    // h3-h6 do not
662                    const b = level <= 2 ? 1 : 0;
663                    ui.div({ ...row, padding: [0, 0, b, indent(level)] });
664                }
665                else {
666                    ui.div({ ...row, padding: [0, 0, 1, indent(headingLevel + 1)] });
667                }
668            }
669        }
670        return (this.#usage = ui.toString());
671    }
672    /**
673     * Return the configuration options as a plain object
674     */
675    toJSON() {
676        return Object.fromEntries(Object.entries(this.#configSet).map(([field, def]) => [
677            field,
678            {
679                type: def.type,
680                ...(def.multiple ? { multiple: true } : {}),
681                ...(def.delim ? { delim: def.delim } : {}),
682                ...(def.short ? { short: def.short } : {}),
683                ...(def.description ? { description: def.description } : {}),
684                ...(def.validate ? { validate: def.validate } : {}),
685                ...(def.default !== undefined ? { default: def.default } : {}),
686            },
687        ]));
688    }
689    /**
690     * Custom printer for `util.inspect`
691     */
692    [inspect.custom](_, options) {
693        return `Jack ${inspect(this.toJSON(), options)}`;
694    }
695}
696// Unwrap and un-indent, so we can wrap description
697// strings however makes them look nice in the code.
698const normalize = (s, pre = false) => pre
699    // prepend a ZWSP to each line so cliui doesn't strip it.
700    ? s.split('\n').map(l => `\u200b${l}`).join('\n')
701    : s
702        // remove single line breaks, except for lists
703        .replace(/([^\n])\n[ \t]*([^\n])/g, (_, $1, $2) => !/^[-*]/.test($2) ? `${$1} ${$2}` : `${$1}\n${$2}`)
704        // normalize mid-line whitespace
705        .replace(/([^\n])[ \t]+([^\n])/g, '$1 $2')
706        // two line breaks are enough
707        .replace(/\n{3,}/g, '\n\n')
708        .trim();
709/**
710 * Main entry point. Create and return a {@link Jack} object.
711 */
712export const jack = (options = {}) => new Jack(options);
713//# sourceMappingURL=index.js.map