optionDefinition.output is now async

Author: 75lb

LICENCE

@@ -1,6 +1,6 @@
 The MIT Licence (MIT)
 
-Copyright (c) 2014-25 Lloyd Brookes <opensource@75lb.com>
+Copyright (c) 2014-26 Lloyd Brookes <opensource@75lb.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

index.js

@@ -1,6 +1,6 @@
 import { fromTo, single, positional } from './lib/from-to.js'
 
-function defaultOutput (val) { return val }
+async function defaultOutput (val) { return val }
 
 const toPresets = {
   singleOptionValue (arg, index, argv, valueIndex) {
@@ -22,10 +22,7 @@ class CommandLineArgs {
     this.origArgv = this.argv.slice()
   }
 
-  /**
-   * @param {OptionDefinition[]}
-   */
-  parse (optionDefinitions) {
+  async parse (optionDefinitions) {
     const result = {}
 
     const notPositionals = optionDefinitions.filter(d => d.extractor !== 'positional')
@@ -41,7 +38,7 @@ class CommandLineArgs {
         throw new Error('Extractor not found: ' + def.extractor)
       }
       if (extraction.length) {
-        result[def.name] = def.output(extraction)
+        result[def.name] = await def.output(extraction)
       }
     }
 
@@ -54,7 +51,7 @@ class CommandLineArgs {
         def.output ||= defaultOutput
         const extraction = positional(this.argv, def.position - 1, { remove: true })
         if (extraction.length) {
-          result[def.name] = def.output(extraction)
+          result[def.name] = await def.output(extraction)
         }
       }
     }

lib/from-to.js

@@ -1,20 +1,36 @@
 import arrayBack from 'array-back'
 
-/**
- * Similar to find-replace with two exceptions:
- * - fromTo finds multiple items, find-replace finds single items
- * - fromTo offers the option to remove, find-replace offers option to remove and/or replace.
- *
- * Scenarios you can perform
- * - Find one or more items and return (all return values are arrays)
- * - Find one or more items, return them, remove them from the input array
- *
- * arr {string[]} - Input array. Only mutated if `options.remove` is set.
- * [options.remove] {boolean} - Remove from source array
- * [options.from] {string[]|function[]} - String literal or a [findIndex](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex) callback function.
- * [options.to] {string[]|function[]} - A "Stop Here" function. Set one or more strings as the terminating arg. Or, from the function `fn(arg, index, argv, valueIndex)`, return true for the first arg that is out of range. Set `inclusive` to also include it. To will always search to the end of the input array.
- * @returns string[]
- */
+/*☭
+## from-to
+
+Similar to find-replace with two exceptions:
+
+- fromTo finds multiple items, find-replace finds single items
+- fromTo offers the option to remove, find-replace offers option to remove and/or replace.
+
+Scenarios you can perform
+
+- Find one or more items and return (all return values are arrays)
+- Find one or more items, return them, remove them from the input array
+
+- **Type:** `function`
+- **Returns:** `string[]`
+
+arr {string[]} - Input array. Only mutated if `options.remove` is set.
+[options.remove] {boolean} - Remove from source array
+[options.from] {string[]|function[]} - String literal or a [findIndex](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex) callback function.
+[options.to] {string[]|function[]} - A "Stop Here" function. Set one or more strings as the terminating arg. Or, from the function `fn(arg, index, argv, valueIndex)`, return true for the first arg that is out of range. Set `inclusive` to also include it. To will always search to the end of the input array.
+
+¬
+  Param
+  Type
+  Description
+¬
+  [options]
+  `object`
+  Description
+¬
+*/
 
 function fromTo (arr, options = {}) {
   /* step 1: compute from and to index */
@@ -84,8 +100,8 @@ function convertToFunction (fn) {
 /**
  * Find the first value which matches the supplied `find` definition (one or more string or functions).
  */
-function getFromIndex (arr, find) {
-  const fromFns = arrayBack(find).map(convertToFunction)
+function getFromIndex (arr, itemsToFind) {
+  const fromFns = arrayBack(itemsToFind).map(convertToFunction)
 
   if (fromFns.length === 0) {
     throw new Error('from/single required')
@@ -109,6 +125,7 @@ function getFromIndex (arr, find) {
 function single (arr, item, options = {}) {
   const fromIndex = getFromIndex(arr, item)
 
+  /* TODO: could this use array.find? */
   const output = arr.slice(fromIndex, fromIndex + 1)
   if (options.remove && fromIndex > -1) {
     arr.splice(fromIndex, 1)

lib/option-definition.js

@@ -1,18 +1,40 @@
-/**
- * @property name
- * @property extractor - from-to, single or positional.
- * @property from - used by extractor 'from-to'
- * @property to - used by extractor 'from-to'
- * @property single - used by extractor 'single'
- * @property position - used by extractor 'positional', not zero-indexed, starts with 1.
- * @property output - a function to run on the final value
- */
+/*☭
+## OptionDefinition
+
+- **Type:** `class`
+
+¬
+  Property
+  Description
+¬
+  name
+  property name on the result
+¬
+  extractor
+  from-to, single or positional.
+¬
+  from
+  used by extractor 'from-to'
+¬
+  toPreset
+  used by extractor 'from-to'
+¬
+  single
+  used by extractor 'single'
+¬
+  position
+  used by extractor 'positional', not zero-indexed, starts with 1.
+¬
+  output
+  a function to cherry-pick the output value
+¬
+*/
 class OptionDefinition {
   name
   from
   to
   single
-  output
+  output // TODO: should this be named `value` as it is the output value.
 }
 
 export default OptionDefinition

package-lock.json

@@ -58,6 +58,6 @@
     ]
   },
   "dependencies": {
-    "array-back": "^6.2.2"
+    "array-back": "^6.2.3"
   }
 }