@flowscripter/dynamic-cli-framework-api 4.0.3 → 4.0.5

package/dist/src/argument/Argument.d.ts

@@ -47,6 +47,22 @@ export default interface Argument {
      * validation error. The error string is associated with
      * {@link InvalidArgumentReason.CUSTOM_VALIDATION}.
      *
+     * Validators declared on properties nested inside {@link ComplexOption.properties} are also
+     * invoked, at any depth:
+     *
+     * * Validation is bottom-up and depth-first, in `properties` declaration order. A property's
+     *   validator is invoked after the validators of its own child properties, and only if they all
+     *   passed. A parent therefore always receives a fully converted and child-validated value.
+     * * Validation stops at the first failure, so later validators are not invoked.
+     * * For an argument with `isArray`, the validator is invoked once with the whole converted
+     *   array. For an array of {@link ComplexOption} values, the child property validators are
+     *   invoked for each element.
+     * * An absent nested property with a `defaultValue` is validated using the default value. An
+     *   absent nested property with `isOptional` and no default is skipped and its validator is not
+     *   invoked.
+     * * A nested failure is reported with the full property path as the invalid argument name,
+     *   e.g. `opt.sub[2].field`.
+     *
      * Example: ensure array values are unique:
      * ```typescript
      * validate: (value) => {

package/dist/src/argument/Argument.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Argument.d.ts","sourceRoot":"","sources":["../../../src/argument/Argument.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAErF;;GAEG;AACH,MAAM,CAAC,OAAO,WAAW,QAAQ;IAC/B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAE1D;;OAEG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAErC;;OAEG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAEpC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAEnC;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;CACvF"}
+{"version":3,"file":"Argument.d.ts","sourceRoot":"","sources":["../../../src/argument/Argument.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAErF;;GAEG;AACH,MAAM,CAAC,OAAO,WAAW,QAAQ;IAC/B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAE1D;;OAEG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAErC;;OAEG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAEpC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;CACvF"}

package/dist/src/argument/ComplexOption.d.ts

@@ -11,6 +11,11 @@ export default interface ComplexOption extends Omit<Option, "type" | "defaultVal
     readonly type: ComplexValueTypeName;
     /**
      * List of child {@link Option} properties.
+     *
+     * Each property is validated in declaration order, including its own
+     * {@link Argument.validate} function if one is defined. Property validators run before the
+     * validator of this complex option. A property's `defaultValue` is used when it is absent,
+     * and an absent property with `isOptional` is skipped.
      */
     readonly properties: ReadonlyArray<Option | ComplexOption>;
     /**

package/dist/src/argument/ComplexOption.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ComplexOption.d.ts","sourceRoot":"","sources":["../../../src/argument/ComplexOption.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEhE,eAAO,MAAM,oCAAoC,KAAK,CAAC;AAEvD;;GAEG;AACH,MAAM,CAAC,OAAO,WAAW,aAAc,SAAQ,IAAI,CACjD,MAAM,EACN,MAAM,GAAG,cAAc,GAAG,iBAAiB,CAC5C;IACC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,MAAM,GAAG,aAAa,CAAC,CAAC;IAE3D;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;CAChD"}
+{"version":3,"file":"ComplexOption.d.ts","sourceRoot":"","sources":["../../../src/argument/ComplexOption.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEhE,eAAO,MAAM,oCAAoC,KAAK,CAAC;AAEvD;;GAEG;AACH,MAAM,CAAC,OAAO,WAAW,aAAc,SAAQ,IAAI,CACjD,MAAM,EACN,MAAM,GAAG,cAAc,GAAG,iBAAiB,CAC5C;IACC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IAEpC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,MAAM,GAAG,aAAa,CAAC,CAAC;IAE3D;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;CAChD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowscripter/dynamic-cli-framework-api",
-  "version": "4.0.3",
+  "version": "4.0.5",
   "description": "API for https://github.com/flowscripter/dynamic-cli-framework",
   "keywords": [
     "bun",
@@ -43,7 +43,7 @@
     "prepare": "tsc -p tsconfig.build.json"
   },
   "devDependencies": {
-    "@flowscripter/dynamic-plugin-framework": "2.2.11",
+    "@flowscripter/dynamic-plugin-framework": "2.2.12",
     "@types/bun": "^1.4.2",
     "highlight.js": "^11.12.0",
     "oxfmt": "0.70.0",

package/src/argument/Argument.ts

@@ -54,6 +54,22 @@ export default interface Argument {
    * validation error. The error string is associated with
    * {@link InvalidArgumentReason.CUSTOM_VALIDATION}.
    *
+   * Validators declared on properties nested inside {@link ComplexOption.properties} are also
+   * invoked, at any depth:
+   *
+   * * Validation is bottom-up and depth-first, in `properties` declaration order. A property's
+   *   validator is invoked after the validators of its own child properties, and only if they all
+   *   passed. A parent therefore always receives a fully converted and child-validated value.
+   * * Validation stops at the first failure, so later validators are not invoked.
+   * * For an argument with `isArray`, the validator is invoked once with the whole converted
+   *   array. For an array of {@link ComplexOption} values, the child property validators are
+   *   invoked for each element.
+   * * An absent nested property with a `defaultValue` is validated using the default value. An
+   *   absent nested property with `isOptional` and no default is skipped and its validator is not
+   *   invoked.
+   * * A nested failure is reported with the full property path as the invalid argument name,
+   *   e.g. `opt.sub[2].field`.
+   *
    * Example: ensure array values are unique:
    * ```typescript
    * validate: (value) => {

package/src/argument/ComplexOption.ts

@@ -17,6 +17,11 @@ export default interface ComplexOption extends Omit<
 
   /**
    * List of child {@link Option} properties.
+   *
+   * Each property is validated in declaration order, including its own
+   * {@link Argument.validate} function if one is defined. Property validators run before the
+   * validator of this complex option. A property's `defaultValue` is used when it is absent,
+   * and an absent property with `isOptional` is skipped.
    */
   readonly properties: ReadonlyArray<Option | ComplexOption>;