@gesslar/actioneer 0.1.3 → 0.2.1

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

@@ -1,31 +1,46 @@
 /**
- * Activity bit flags recognised by the builder. The flag decides
- * loop semantics for an activity.
+ *
  */
 export type ACTIVITY = number
+/** @typedef {import("./ActionHooks.js").default} ActionHooks */
 /**
  * Activity bit flags recognised by the builder. The flag decides
  * loop semantics for an activity.
  *
  * @readonly
  * @enum {number}
+ * @property {number} WHILE - Execute activity while predicate returns true (2)
+ * @property {number} UNTIL - Execute activity until predicate returns false (4)
+ * @property {number} SPLIT - Execute activity with split/rejoin pattern for parallel execution (8)
  */
 export const ACTIVITY: Readonly<{
   WHILE: number;
   UNTIL: number;
+  SPLIT: number;
 }>
 export default class Activity {
   /**
    * Construct an Activity definition wrapper.
    *
-   * @param {{action: unknown, name: string, op: (context: unknown) => unknown|Promise<unknown>|unknown, kind?: number, pred?: (context: unknown) => boolean|Promise<boolean>}} init - Initial properties describing the activity operation, loop semantics, and predicate
+   * @param {object} init - Initial properties describing the activity operation, loop semantics, and predicate
+   * @param {unknown} init.action - Parent action instance
+   * @param {string|symbol} init.name - Activity identifier
+   * @param {(context: unknown) => unknown|Promise<unknown>|import("./ActionBuilder.js").default} init.op - Operation to execute
+   * @param {number} [init.kind] - Optional loop semantics flags
+   * @param {(context: unknown) => boolean|Promise<boolean>} [init.pred] - Optional predicate for WHILE/UNTIL
+   * @param {ActionHooks} [init.hooks] - Optional hooks instance
+   * @param {(context: unknown) => unknown} [init.splitter] - Optional splitter function for SPLIT activities
+   * @param {(originalContext: unknown, splitResults: unknown) => unknown} [init.rejoiner] - Optional rejoiner function for SPLIT activities
    */
-  constructor({ action, name, op, kind, pred }: {
+  constructor({ action, name, op, kind, pred, hooks, splitter, rejoiner }: {
     action: unknown;
-    name: string;
-    op: (context: unknown) => unknown | Promise<unknown> | unknown;
-    kind?: number;
-    pred?: (context: unknown) => boolean | Promise<boolean>;
+    name: string | symbol;
+    op: (context: unknown) => unknown | Promise<unknown> | import('./ActionBuilder.js').default;
+    kind?: number | undefined;
+    pred?: ((context: unknown) => boolean | Promise<boolean>) | undefined;
+    hooks?: import('./ActionHooks.js').default | undefined;
+    splitter?: ((context: unknown) => unknown) | undefined;
+    rejoiner?: ((originalContext: unknown, splitResults: unknown) => unknown) | undefined;
   })
   /**
    * The activity name.
@@ -46,17 +61,35 @@ export default class Activity {
    */
   get pred(): (context: unknown) => boolean | Promise<boolean> | undefined
   /**
-   * The operator kind name (Function or ActionWrapper).
+   * The current context (if set).
+   *
+   * @returns {unknown} Current context value
+   */
+  get context(): unknown
+  /**
+   * The operator kind name (Function or ActionBuilder).
    *
    * @returns {string} - Kind name extracted via Data.typeOf
    */
   get opKind(): string
   /**
-   * The operator to execute (function or nested wrapper).
+   * The operator to execute (function or nested ActionBuilder).
    *
-   * @returns {unknown} - Activity operation
+   * @returns {(context: unknown) => unknown|Promise<unknown>|import("./ActionBuilder.js").default} - Activity operation
    */
-  get op(): unknown
+  get op(): (context: unknown) => unknown | Promise<unknown> | import('./ActionBuilder.js').default
+  /**
+   * The splitter function for SPLIT activities.
+   *
+   * @returns {((context: unknown) => unknown)|null} Splitter function or null
+   */
+  get splitter(): ((context: unknown) => unknown) | null
+  /**
+   * The rejoiner function for SPLIT activities.
+   *
+   * @returns {((originalContext: unknown, splitResults: unknown) => unknown)|null} Rejoiner function or null
+   */
+  get rejoiner(): ((originalContext: unknown, splitResults: unknown) => unknown) | null
   /**
    * The action instance this activity belongs to.
    *
@@ -67,18 +100,23 @@ export default class Activity {
    * Execute the activity with before/after hooks.
    *
    * @param {unknown} context - Mutable context flowing through the pipeline
-   * @returns {Promise<{activityResult: unknown}>} - Activity result wrapper with new context
+   * @returns {Promise<unknown>} - Activity result
    */
-  run(context: unknown): Promise<{
-    activityResult: unknown;
-  }>
+  run(context: unknown): Promise<unknown>
   /**
    * Attach hooks to this activity instance.
    *
-   * @param {unknown} hooks - Hooks instance with optional before$/after$ methods
+   * @param {ActionHooks} hooks - Hooks instance with optional before$/after$ methods
    * @returns {this} - This activity for chaining
    */
-  setActionHooks(hooks: unknown): this
+  setActionHooks(hooks: ActionHooks): this
+  /**
+   * Get the hooks instance attached to this activity.
+   *
+   * @returns {ActionHooks|null} The hooks instance or null
+   */
+  get hooks(): ActionHooks | null
   #private
 }
+export type ActionHooks = import('./ActionHooks.js').default
 //# sourceMappingURL=Activity.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Activity.d.ts","sourceRoot":"","sources":["../../lib/Activity.js"],"names":[],"mappings":";;;;uBAOU,MAAM;AALhB;;;;;;GAMG;AACH;;;GAGE;AAEF;IAQE;;;;OAIG;IACH,8CAFW;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,CAAA;KAAC,EAQ3K;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,GAAC,IAAI,CAIvB;IAED;;;;OAIG;IACH,YAFa,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,SAAS,CAIpE;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,UAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;;OAKG;IACH,aAHW,OAAO,GACL,OAAO,CAAC;QAAC,cAAc,EAAE,OAAO,CAAA;KAAC,CAAC,CAkB9C;IAED;;;;;OAKG;IACH,sBAHW,OAAO,GACL,IAAI,CAOhB;;CACF"}
+{"version":3,"file":"Activity.d.ts","sourceRoot":"","sources":["../../lib/Activity.js"],"names":[],"mappings":";;;uBASU,MAAM;AAPhB,gEAAgE;AAEhE;;;;;;;;;GASG;AACH;;;;GAIE;AAEF;IAoBE;;;;;;;;;;;;OAYG;IACH,yEATG;QAAsB,MAAM,EAApB,OAAO;QACa,IAAI,EAAxB,MAAM,GAAC,MAAM;QAC6E,EAAE,EAA5F,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,OAAO,oBAAoB,EAAE,OAAO;QACrE,IAAI;QACoC,IAAI,cAAhD,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;QAC3B,KAAK;QACa,QAAQ,cAAnC,OAAO,KAAK,OAAO;QACuC,QAAQ,sBAA1D,OAAO,gBAAgB,OAAO,KAAK,OAAO;KACtE,EAUA;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,GAAC,IAAI,CAIvB;IAED;;;;OAIG;IACH,YAFa,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,SAAS,CAIpE;IAED;;;;OAIG;IACH,eAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,UAFa,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,OAAO,oBAAoB,EAAE,OAAO,CAI/F;IAED;;;;OAIG;IACH,gBAFa,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,GAAC,IAAI,CAIhD;IAED;;;;OAIG;IACH,gBAFa,CAAC,CAAC,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,KAAK,OAAO,CAAC,GAAC,IAAI,CAI/E;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;;OAKG;IACH,aAHW,OAAO,GACL,OAAO,CAAC,OAAO,CAAC,CAa5B;IAED;;;;;OAKG;IACH,sBAHW,WAAW,GACT,IAAI,CAOhB;IAED;;;;OAIG;IACH,aAFa,WAAW,GAAC,IAAI,CAI5B;;CACF;0BAvLa,OAAO,kBAAkB,EAAE,OAAO"}

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

@@ -8,15 +8,17 @@ export default class Piper {
     debug?: (message: string, level?: number, ...args: Array<unknown>) => void;
   })
   /**
-   * Add a processing step to the pipeline
+   * Add a processing step to the pipeline.
+   * Each step is executed sequentially per item.
    *
    * @param {(context: unknown) => Promise<unknown>|unknown} fn Function that processes an item
-   * @param {{name?: string, required?: boolean}} [options] Step options
+   * @param {{name: string, required?: boolean}} options Step options (name is required)
    * @param {unknown} [newThis] Optional this binding
    * @returns {Piper} The pipeline instance (for chaining)
+   * @throws {Sass} If name is not provided in options
    */
   addStep(fn: (context: unknown) => Promise<unknown> | unknown, options?: {
-    name?: string;
+    name: string;
     required?: boolean;
   }, newThis?: unknown): Piper
   /**
@@ -36,13 +38,28 @@ export default class Piper {
    */
   addCleanup(fn: () => Promise<void> | void, thisArg?: unknown): Piper
   /**
-   * Process items through the pipeline with concurrency control
+   * Process items through the pipeline with concurrency control using a worker pool pattern.
+   * Workers are spawned up to maxConcurrent limit, and as workers complete, new workers
+   * are spawned to maintain concurrency until all items are processed.
+   *
+   * This implementation uses dynamic worker spawning to maintain concurrency:
+   * - Initial workers are spawned up to maxConcurrent limit
+   * - As each worker completes (success OR failure), a replacement worker is spawned if items remain
+   * - Worker spawning occurs in finally block to ensure resilience to individual worker failures
+   * - All results are collected with {ok, value} or {ok: false, error} structure
+   * - Processing continues even if individual workers fail, collecting all errors
    *
    * @param {Array<unknown>|unknown} items - Items to process
-   * @param {number} maxConcurrent - Maximum concurrent items to process
-   * @returns {Promise<Array<unknown>>} - Collected results from steps
+   * @param {number} [maxConcurrent] - Maximum concurrent items to process (default: 10)
+   * @returns {Promise<Array<{ok: boolean, value?: unknown, error?: Sass}>>} - Results with success/failure status
+   * @throws {Sass} If setup or teardown fails
    */
-  pipe(items: Array<unknown> | unknown, maxConcurrent?: number): Promise<Array<unknown>>
+  pipe(items: Array<unknown> | unknown, maxConcurrent?: number): Promise<Array<{
+    ok: boolean;
+    value?: unknown;
+    error?: Sass;
+  }>>
   #private
 }
+import { Sass } from '@gesslar/toolkit'
 //# sourceMappingURL=Piper.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Piper.d.ts","sourceRoot":"","sources":["../../lib/Piper.js"],"names":[],"mappings":"AAaA;IASE;;;;OAIG;IACH,wBAFW;QAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAA;KAAC,EAItF;IAED;;;;;;;OAOG;IACH,YALW,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAC,OAAO,YAC9C;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAC,YACnC,OAAO,GACL,KAAK,CAWjB;IAED;;;;;;OAMG;IACH,aAJW,MAAM,OAAO,CAAC,IAAI,CAAC,GAAC,IAAI,YACxB,OAAO,GACL,KAAK,CAMjB;IAED;;;;;;OAMG;IACH,eAJW,MAAM,OAAO,CAAC,IAAI,CAAC,GAAC,IAAI,YACxB,OAAO,GACL,KAAK,CAMjB;IAED;;;;;;OAMG;IACH,YAJW,KAAK,CAAC,OAAO,CAAC,GAAC,OAAO,kBACtB,MAAM,GACJ,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAiDnC;;CAyCF"}
+{"version":3,"file":"Piper.d.ts","sourceRoot":"","sources":["../../lib/Piper.js"],"names":[],"mappings":"AAaA;IAWE;;;;OAIG;IACH,wBAFW;QAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAA;KAAC,EAItF;IAED;;;;;;;;;OASG;IACH,YANW,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAC,OAAO,YAC9C;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAC,YAClC,OAAO,GACL,KAAK,CAejB;IAED;;;;;;OAMG;IACH,aAJW,MAAM,OAAO,CAAC,IAAI,CAAC,GAAC,IAAI,YACxB,OAAO,GACL,KAAK,CAMjB;IAED;;;;;;OAMG;IACH,eAJW,MAAM,OAAO,CAAC,IAAI,CAAC,GAAC,IAAI,YACxB,OAAO,GACL,KAAK,CAMjB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,YALW,KAAK,CAAC,OAAO,CAAC,GAAC,OAAO,kBACtB,MAAM,GACJ,OAAO,CAAC,KAAK,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,IAAI,CAAA;KAAC,CAAC,CAAC,CAqFxE;;CAwCF;qBAnNiC,kBAAkB"}