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