@gesslar/toolkit 0.5.0 → 0.7.0

package/src/types/lib/Util.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Utility class providing common helper functions for string manipulation,
+ * timing, hashing, and option parsing.
+ */
+export default class Util {
+    /**
+     * Capitalizes the first letter of a string.
+     *
+     * @param {string} text - The text to capitalize
+     * @returns {string} Text with first letter capitalized
+     */
+    static capitalize(text: string): string;
+    /**
+     * Measure wall-clock time for an async function.
+     *
+     * @template T
+     * @param {() => Promise<T>} fn - Thunk returning a promise.
+     * @returns {Promise<{result: T, cost: number}>} Object containing result and elapsed ms (number, 1 decimal).
+     */
+    static time<T>(fn: () => Promise<T>): Promise<{
+        result: T;
+        cost: number;
+    }>;
+    /**
+     * Right-align a string inside a fixed width (left pad with spaces).
+     * If the string exceeds width it is returned unchanged.
+     *
+     * @param {string|number} text - Text to align.
+     * @param {number} width - Target field width (default 80).
+     * @returns {string} Padded string.
+     */
+    static rightAlignText(text: string | number, width?: number): string;
+    /**
+     * Centre-align a string inside a fixed width (pad with spaces on left).
+     * If the string exceeds width it is returned unchanged.
+     *
+     * @param {string|number} text - Text to align.
+     * @param {number} width - Target field width (default 80).
+     * @returns {string} Padded string with text centred.
+     */
+    static centreAlignText(text: string | number, width?: number): string;
+    /**
+     * Compute sha256 hash (hex) of the provided string.
+     *
+     * @param {string} s - Input string.
+     * @returns {string} 64-char hexadecimal digest.
+     */
+    static hashOf(s: string): string;
+    /**
+     * Extracts canonical option names from a Commander-style options object.
+     *
+     * Each key in the input object is a string containing one or more option
+     * forms, separated by commas (e.g. "-w, --watch"). This function splits each
+     * key, trims whitespace, and parses out the long option name (e.g. "watch")
+     * for each entry. If no long option ("--") is present, the short option (e.g.
+     * "v" from "-v") will be included in the result array. If both are present,
+     * the long option is preferred.
+     *
+     * Example:
+     *   generateOptionNames({"-w, --watch": "desc", "-v": "desc"})
+     *   → ["watch", "v"]
+     *
+     * Edge cases:
+     *   - If a key contains only a short option ("-v"), that short name will be
+     *     included in the result.
+     *   - If multiple long options are present, only the first is used.
+     *   - If the option string is malformed, may return undefined for that entry
+     *     (filtered out).
+     *
+     * @param {object} object - Mapping of option strings to descriptions.
+     * @returns {Array<string>} Array of canonical option names (long preferred, short if no long present).
+     */
+    static generateOptionNames(object: object): Array<string>;
+    /**
+     * Asynchronously awaits all promises in parallel.
+     * Wrapper around Promise.all for consistency with other utility methods.
+     *
+     * @param {Array<Promise<unknown>>} promises - Array of promises to await
+     * @returns {Promise<Array<unknown>>} Results of all promises
+     */
+    static awaitAll(promises: Array<Promise<unknown>>): Promise<Array<unknown>>;
+    /**
+     * Settles all promises (both fulfilled and rejected) in parallel.
+     * Wrapper around Promise.allSettled for consistency with other utility methods.
+     *
+     * @param {Array<Promise<unknown>>} promises - Array of promises to settle
+     * @returns {Promise<Array<object>>} Results of all settled promises with status and value/reason
+     */
+    static settleAll(promises: Array<Promise<unknown>>): Promise<Array<object>>;
+    /**
+     * Checks if any result in the settled promise array is rejected.
+     *
+     * @param {Array<object>} result - Array of settled promise results.
+     * @returns {boolean} True if any result is rejected, false otherwise.
+     */
+    static anyRejected(result: Array<object>): boolean;
+    /**
+     * Filters and returns all rejected results from a settled promise array.
+     *
+     * @param {Array<object>} result - Array of settled promise results.
+     * @returns {Array<object>} Array of rejected results.
+     */
+    static settledAndRejected(result: Array<object>): Array<object>;
+    /**
+     * Extracts the rejection reasons from an array of rejected promise results.
+     *
+     * @param {Array<object>} rejected - Array of rejected results.
+     * @returns {Array<unknown>} Array of rejection reasons.
+     */
+    static rejectedReasons(rejected: Array<object>): Array<unknown>;
+    /**
+     * Throws a Sass error containing all rejection reasons from settled promises.
+     *
+     * @param {string} [_message] - Optional error message. Defaults to "GIGO"
+     * @param {Array<object>} rejected - Array of rejected results.
+     * @throws {Error} Throws a Sass error with rejection reasons.
+     */
+    static throwRejected(_message?: string, rejected: Array<object>): void;
+    /**
+     * Filters and returns all fulfilled results from a settled promise array.
+     *
+     * @param {Array<object>} result - Array of settled promise results.
+     * @returns {Array<object>} Array of fulfilled results.
+     */
+    static settledAndFulfilled(result: Array<object>): Array<object>;
+    /**
+     * Extracts the values from all fulfilled results in a settled promise array.
+     *
+     * @param {Array<object>} result - Array of settled promise results.
+     * @returns {Array<unknown>} Array of fulfilled values.
+     */
+    static fulfilledValues(result: Array<object>): Array<unknown>;
+    /**
+     * Returns the first promise to resolve or reject from an array of promises.
+     * Wrapper around Promise.race for consistency with other utility methods.
+     *
+     * @param {Array<Promise<unknown>>} promises - Array of promises to race
+     * @returns {Promise<unknown>} Result of the first settled promise
+     */
+    static race(promises: Array<Promise<unknown>>): Promise<unknown>;
+    /**
+     * Private method that performs the actual async emission logic.
+     * Handles listener execution, error aggregation, and result processing.
+     *
+     * @param {object} emitter - The emitter object (already validated)
+     * @param {string} event - The event name to emit
+     * @param {...unknown} args - Arguments to pass to event listeners
+     * @returns {Promise<void>} Resolves when all listeners have completed
+     */
+    static "__#private@#performAsyncEmit"(emitter: object, event: string, ...args: unknown[]): Promise<void>;
+    /**
+     * Emits an event asynchronously and waits for all listeners to complete.
+     * Unlike the standard EventEmitter.emit() which is synchronous, this method
+     * properly handles async event listeners by waiting for all of them to
+     * resolve or reject using Promise.allSettled().
+     *
+     * Uses strict instanceof checking to ensure the emitter is a genuine EventEmitter.
+     *
+     * @param {EventEmitter} emitter - The EventEmitter instance to emit on
+     * @param {string} event - The event name to emit
+     * @param {...unknown} args - Arguments to pass to event listeners
+     * @returns {Promise<void>} Resolves when all listeners have completed
+     */
+    static asyncEmit(emitter: EventEmitter, event: string, ...args: unknown[]): Promise<void>;
+    /**
+     * Emits an event asynchronously and waits for all listeners to complete.
+     * Like asyncEmit, but uses duck typing for more flexible emitter validation.
+     * Accepts any object that has the required EventEmitter-like methods.
+     *
+     * @param {object} emitter - Any object with EventEmitter-like interface
+     * @param {string} event - The event name to emit
+     * @param {...unknown} args - Arguments to pass to event listeners
+     * @returns {Promise<void>} Resolves when all listeners have completed
+     */
+    static asyncEmitAnon(emitter: object, event: string, ...args: unknown[]): Promise<void>;
+    /**
+     * Determine the Levenshtein distance between two string values
+     *
+     * @param {string} a The first value for comparison.
+     * @param {string} b The second value for comparison.
+     * @returns {number} The Levenshtein distance
+     */
+    static levenshteinDistance(a: string, b: string): number;
+    /**
+     * Determine the closest match between a string and allowed values
+     * from the Levenshtein distance.
+     *
+     * @param {string} input The input string to resolve
+     * @param {Array<string>} allowedValues The values which are permitted
+     * @param {number} [threshold] Max edit distance for a "close match"
+     * @returns {string} Suggested, probable match.
+     */
+    static findClosestMatch(input: string, allowedValues: Array<string>, threshold?: number): string;
+    static regexify(input: any, trim?: boolean, flags?: any[]): RegExp;
+}
+import { EventEmitter } from "node:events";
+//# sourceMappingURL=Util.d.ts.map

package/src/types/lib/Util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Util.d.ts","sourceRoot":"","sources":["../../lib/Util.js"],"names":[],"mappings":"AAOA;;;GAGG;AACH;IACE;;;;;OAKG;IACH,wBAHW,MAAM,GACJ,MAAM,CAYlB;IAED;;;;;;OAMG;IACH,YAJa,CAAC,MACH,MAAM,OAAO,CAAC,CAAC,CAAC,GACd,OAAO,CAAC;QAAC,MAAM,EAAE,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,CAAC,CAQ9C;IAED;;;;;;;OAOG;IACH,4BAJW,MAAM,GAAC,MAAM,UACb,MAAM,GACJ,MAAM,CAWlB;IAED;;;;;;;OAOG;IACH,6BAJW,MAAM,GAAC,MAAM,UACb,MAAM,GACJ,MAAM,CAalB;IAED;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,mCAHW,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CAazB;IAED;;;;;;OAMG;IACH,0BAHW,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GACrB,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAInC;IAED;;;;;;OAMG;IACH,2BAHW,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GACrB,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAIlC;IAED;;;;;OAKG;IACH,2BAHW,KAAK,CAAC,MAAM,CAAC,GACX,OAAO,CAInB;IAED;;;;;OAKG;IACH,kCAHW,KAAK,CAAC,MAAM,CAAC,GACX,KAAK,CAAC,MAAM,CAAC,CAIzB;IAED;;;;;OAKG;IACH,iCAHW,KAAK,CAAC,MAAM,CAAC,GACX,KAAK,CAAC,OAAO,CAAC,CAI1B;IAED;;;;;;OAMG;IACH,gCAJW,MAAM,YACN,KAAK,CAAC,MAAM,CAAC,QAKvB;IAED;;;;;OAKG;IACH,mCAHW,KAAK,CAAC,MAAM,CAAC,GACX,KAAK,CAAC,MAAM,CAAC,CAIzB;IAED;;;;;OAKG;IACH,+BAHW,KAAK,CAAC,MAAM,CAAC,GACX,KAAK,CAAC,OAAO,CAAC,CAI1B;IAED;;;;;;OAMG;IACH,sBAHW,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GACrB,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;;;;;OAQG;IACH,+CALW,MAAM,SACN,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,IAAI,CAAC,CAmBzB;IAED;;;;;;;;;;;;OAYG;IACH,0BALW,YAAY,SACZ,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,IAAI,CAAC,CAqBzB;IAED;;;;;;;;;OASG;IACH,8BALW,MAAM,SACN,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,IAAI,CAAC,CAyBzB;IAED;;;;;;OAMG;IACH,8BAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAsBlB;IAED;;;;;;;;OAQG;IACH,+BALW,MAAM,iBACN,KAAK,CAAC,MAAM,CAAC,cACb,MAAM,GACJ,MAAM,CAwBlB;IAED,mEAiBC;CACF;6BAjZ0B,aAAa"}

package/src/types/lib/Valid.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Validation utility class providing type checking and assertion methods.
+ */
+export default class Valid {
+    /**
+     * Validates a value against a type. Uses Data.isType.
+     *
+     * @param {unknown} value - The value to validate
+     * @param {string} type - The expected type in the form of "object", "object[]", "object|object[]"
+     * @param {object} [options] - Additional options for validation.
+     */
+    static type(value: unknown, type: string, options?: object): void;
+    /**
+     * Asserts a condition
+     *
+     * @param {boolean} condition - The condition to assert
+     * @param {string} message - The message to display if the condition is not
+     *                           met
+     * @param {number} [arg] - The argument to display if the condition is not
+     *                         met (optional)
+     */
+    static assert(condition: boolean, message: string, arg?: number): void;
+    static "__#private@#restrictedProto": string[];
+    /**
+     * Protects against prototype pollution by checking keys for dangerous property names.
+     * Throws if any restricted prototype properties are found in the keys array.
+     *
+     * @param {Array<string>} keys - Array of property keys to validate
+     * @throws {Sass} If any key matches restricted prototype properties (__proto__, constructor, prototype)
+     */
+    static prototypePollutionProtection(keys: Array<string>): void;
+}
+//# sourceMappingURL=Valid.d.ts.map

package/src/types/lib/Valid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Valid.d.ts","sourceRoot":"","sources":["../../lib/Valid.js"],"names":[],"mappings":"AAaA;;GAEG;AACH;IACE;;;;;;OAMG;IACH,mBAJW,OAAO,QACP,MAAM,YACN,MAAM,QAQhB;IAED;;;;;;;;OAQG;IACH,yBANW,OAAO,WACP,MAAM,QAEN,MAAM,QAmBhB;IAED,+CAAmE;IAEnE;;;;;;OAMG;IACH,0CAHW,KAAK,CAAC,MAAM,CAAC,QAYvB;CACF"}

package/src/lib/Action.js

@@ -1,283 +0,0 @@
-import ActionBuilder from "./ActionBuilder.js"
-import ActionRunner from "./ActionRunner.js"
-import Data from "./Data.js"
-import FileObject from "./FileObject.js"
-import Hooks from "./Hooks.js"
-import Sass from "./Sass.js"
-import Terms from "./Terms.js"
-
-/**
- * Generic base class for managing actions with lifecycle hooks.
- * Provides common functionality for action setup, execution, and cleanup.
- * Designed to be extended by specific implementations.
- */
-export default class Action {
-  #action = null
-  #hooks = null
-  #file = null
-  #variables = null
-  #runner = null
-  #id = null
-  #debug
-
-  /**
-   * Creates a new BaseActionManager instance.
-   *
-   * @param {object} config - Configuration object
-   * @param {object} config.actionDefinition - Action definition containing action class and file info
-   * @param {object} [config.variables] - Variables to pass to action during setup
-   * @param {import('../types.js').DebugFunction} config.debug - The logger's debug function
-   */
-  constructor({actionDefinition, variables, debug}) {
-    this.#id = Symbol(performance.now())
-    this.#variables = variables || {}
-    this.#debug = debug
-
-    const {action,file} = actionDefinition
-    this.#action = action
-    this.#file = file
-  }
-  /**
-   * Gets the unique identifier for this action manager instance.
-   *
-   * @returns {symbol} Unique symbol identifier
-   */
-  get id() {
-    return this.#id
-  }
-
-  /**
-   * Gets the action class constructor.
-   *
-   * @returns {new () => object} Action class constructor
-   */
-  get action() {
-    return this.#action
-  }
-
-  /**
-   * Gets the current hook manager instance.
-   *
-   * @returns {Hooks|null} Hook manager instance or null if not set
-   */
-  get hooks() {
-    return this.#hooks
-  }
-
-  /**
-   * Sets the hook manager and attaches hooks to the action.
-   *
-   * @param {Hooks} hooks - Hook manager instance with hooks and on method.
-   * @returns {Promise<this>} Promise of this instance.
-   * @throws {Sass} If hook manager is already set.
-   */
-  setHooks(hooks) {
-    if(this.#hooks)
-      throw Sass.new("Hook manager already set")
-
-    this.#hooks = hooks
-
-    return this
-  }
-
-  // async callHook(kind, activity, action, context) {
-  //   const hooks = this.#hooks
-
-  // }
-
-  /**
-   * Gets the action metadata.
-   *
-   * @returns {object|undefined} Action metadata object
-   */
-  get meta() {
-    return this.#action?.meta
-  }
-
-  /**
-   * Gets the variables passed to the action.
-   *
-   * @returns {object} Variables object
-   */
-  get variables() {
-    return this.#variables
-  }
-
-  /**
-   * Gets the action runner instance.
-   *
-   * @returns {ActionRunner?} ActionRunner instance or null if not set up
-   */
-  get runner() {
-    return this.#runner
-  }
-
-  /**
-   * Gets the file information object.
-   *
-   * @returns {FileObject?} File information object
-   */
-  get file() {
-    return this.#file
-  }
-
-  /**
-   * Setup the action by creating and configuring the runner.
-   * This is the main public method to initialize the action for use.
-   *
-   * @returns {Promise<this>} Promise of this instance.
-   * @throws {Sass} If action setup fails
-   */
-  async setupAction() {
-    this.#debug("Setting up action for %o on %o", 2, this.#action.meta?.kind, this.id)
-
-    await this.#setupHooks()
-    await this.#setupAction()
-
-    return this
-  }
-
-  /**
-   * Setup the action instance and create the runner.
-   * Creates a new action instance, calls its setup method with an
-   * ActionBuilder, and creates an ActionRunner from the result.
-   *
-   * Can be overridden in subclasses to customize action setup.
-   *
-   * @returns {Promise<void>}
-   * @throws {Sass} If action setup method is not a function
-   * @protected
-   */
-  async #setupAction() {
-    const actionInstance = new this.#action()
-    const setup = actionInstance?.setup
-
-    // Setup is required for actions.
-    if(Data.typeOf(setup) === "Function") {
-      const builder = new ActionBuilder(actionInstance)
-      const configuredBuilder = setup(builder)
-      const buildResult = configuredBuilder.build()
-      const runner = new ActionRunner({
-        action: buildResult.action,
-        build: buildResult.build
-      }, this.#hooks)
-
-      this.#runner = runner
-    } else {
-      throw Sass.new("Action setup must be a function.")
-    }
-  }
-
-  /**
-   * Run the action with the provided input.
-   * The action must be set up via setupAction() before calling this method.
-   *
-   * @param {unknown} context - Input data to pass to the action runner
-   * @returns {Promise<unknown>} Result from the action execution
-   * @throws {Sass} If action is not set up
-   */
-  async runAction(context) {
-    if(!this.#runner)
-      throw Sass.new("Action not set up. Call setupAction() first.")
-
-    return await this.#runner.run(context)
-  }
-
-  /**
-   * Cleanup the action and hooks.
-   * This should be called when the action is no longer needed to free
-   * resources.
-   *
-   * Calls cleanupHooks() and cleanupActionInstance() which can be overridden.
-   *
-   * @returns {Promise<this>} Promise of this instance.
-   */
-  async cleanupAction() {
-    this.#debug("Cleaning up action for %o on %o", 2, this.#action.meta?.kind, this.id)
-
-    await this.#cleanupHooks()
-    await this.#cleanupAction()
-
-    return this
-  }
-
-  /**
-   * Setup hooks if hook manager is present.
-   * Calls the hook manager's setup function with action context.
-   * Override in subclasses to customize hook setup.
-   *
-   * @returns {Promise<void>}
-   * @throws {Sass} If hook setup is not a function
-   * @private
-   */
-  async #setupHooks() {
-    const setup = this.#hooks?.setup
-    const type = Data.typeOf(setup)
-
-    // No hooks attached.
-    if(type === "Null" || type === "Undefined")
-      return
-
-    if(type !== "Function")
-      throw Sass.new("Hook setup must be a function.")
-
-    await setup.call(
-      this.hooks.hooks, {
-        action: this.#action,
-        variables: this.#variables,
-      }
-    )
-  }
-
-  /**
-   * Cleanup hooks if hook manager is present.
-   * Calls the hook manager's cleanup function.
-   * Override in subclasses to customize hook cleanup.
-   *
-   * @returns {Promise<void>}
-   * @protected
-   */
-  async #cleanupHooks() {
-    const cleanup = this.hooks?.cleanup
-
-    if(!cleanup)
-      return
-
-    await cleanup.call(this.hooks.hooks)
-  }
-
-  /**
-   * Cleanup the action instance.
-   * Calls the action's cleanup method if it exists.
-   * Override in subclasses to add custom cleanup logic.
-   *
-   * @returns {Promise<void>}
-   * @protected
-   */
-  async #cleanupAction() {
-    const cleanup = this.#action?.cleanup
-
-    if(!cleanup)
-      return
-
-    await cleanup.call(this.#action)
-  }
-
-  /**
-   * Returns a string representation of this action manager.
-   *
-   * @returns {string} String representation with module and action info
-   */
-  toString() {
-    return `${this.#file?.module || "UNDEFINED"} (${this.meta?.action || "UNDEFINED"})`
-  }
-
-  /**
-   * Get contract/terms for this action (override in subclasses)
-   *
-   * @returns {Terms?} Contract terms or null if not implemented
-   */
-  get terms() {
-    return null
-  }
-}

package/src/lib/ActionBuilder.js

@@ -1,144 +0,0 @@
-import Valid from "./Valid.js"
-
-/** @typedef {import("./ActionRunner.js").default} ActionRunner */
-
-/**
- * Activity bit flags recognised by {@link ActionBuilder#act}. The flag decides
- * how results are accumulated for each activity.
- *
- * @readonly
- * @enum {number}
- */
-export const ACTIVITY = Object.freeze({
-  ONCE: 1<<1,
-  MANY: 1<<2,
-  PARALLEL: 1<<3,
-})
-
-/**
- * Fluent builder for describing how an action should process the context that
- * flows through the {@link ActionRunner}. Consumers register named activities,
- * optional hook pairs, and nested parallel pipelines before handing the
- * builder back to the runner for execution.
- *
- * Typical usage:
- *
- * ```js
- * const pipeline = new ActionBuilder(myAction)
- *   .act("prepare", ACTIVITY.ONCE, ctx => ctx.initialise())
- *   .parallel(parallel => parallel
- *     .act("step", ACTIVITY.MANY, ctx => ctx.consume())
- *   )
- *   .act("finalise", ACTIVITY.ONCE, ctx => ctx.complete())
- *   .build()
- * ```
- *
- * @class ActionBuilder
- */
-export default class ActionBuilder {
-  #action = null
-  #activities = new Map([])
-
-  /**
-   * Creates a new ActionBuilder instance with the provided action callback.
-   *
-   * @param {(ctx: object) => void} action Base action invoked by the runner when a block
-   *   satisfies the configured structure.
-   */
-  constructor(action) {
-    this.#action = action
-  }
-
-  /**
-   * Returns the underlying action that will receive the extracted context.
-   *
-   * @returns {(ctx: object) => void} The action callback function that processes the extracted context.
-   */
-  get action() {
-    return this.#action
-  }
-
-  /**
-   * Returns the registered activities keyed by their name.
-   *
-   * @returns {Map<string | symbol, {op: (context: object) => unknown, kind: number, hooks: {before: ((context: object) => void)|null, after: ((context: object) => void)|null}}>} Map of registered activities and their metadata.
-   */
-  get activities() {
-    return this.#activities
-  }
-
-  /**
-   * Registers a named activity that will run for each matching block.
-   *
-   * @param {string} name Unique activity identifier.
-   * @param {number} kind Activity accumulation strategy (see {@link ACTIVITY}).
-   * @param {(context: object) => unknown} op Work function executed with the runner context.
-   * @param {{before?: (context: object) => void, after?: (context: object) => void}} [hooks] Optional hooks to run before or after the activity operation.
-   * @returns {ActionBuilder} Builder instance for chaining.
-   */
-  act(name, kind, op, hooks={}) {
-    this.#validActivityKind(kind)
-    this.#dupeActivityCheck(name)
-
-    hooks = this.#normalizeHooks(hooks)
-
-    this.#activities.set(name, {op, kind, hooks})
-
-    return this
-  }
-
-  #normalizeHooks({before=null, after=null}) {
-    return {before, after}
-  }
-
-  /**
-   * Defines a nested pipeline that will run with the {@link ACTIVITY} flag PARALLEL.
-   *
-   * The callback receives a fresh {@link ActionBuilder} scoped to the current
-   * action. The callback must return the configured builder so the runner can
-   * execute the nested pipeline.
-   *
-   * @param {(builder: ActionBuilder) => ActionBuilder} func Callback configuring a nested builder.
-   * @returns {ActionBuilder} Builder instance for chaining.
-   */
-  parallel(func) {
-    const activityName = Symbol(performance.now())
-
-    this.#activities.set(activityName, {
-      op: func.call(this.action, new ActionBuilder(this.action)),
-      kind: ACTIVITY.PARALLEL
-    })
-
-    return this
-  }
-
-  #validActivityKind(kind) {
-    Valid.assert(
-      Object.values(ACTIVITY).includes(kind),
-      "Invalid activity kind."
-    )
-  }
-
-  /**
-   * Validates that an activity name has not been reused.
-   *
-   * @private
-   * @param {string|symbol} name Activity identifier.
-   */
-  #dupeActivityCheck(name) {
-    Valid.assert(
-      !this.#activities.has(name),
-      `Activity '${String(name)}' has already been registered.`
-    )
-  }
-
-  /**
-   * Finalises the builder and returns a payload that can be consumed by the
-   * runner.
-   *
-   * @returns {{action: (context: object) => unknown, build: ActionBuilder}} Payload consumed by the {@link ActionRunner} constructor.
-   */
-  build() {
-    return {action: this.#action, build: this}
-  }
-}