@gesslar/actioneer 3.0.2 → 3.1.0

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "3.0.2",
+  "version": "3.1.0",
   "license": "0BSD",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {

package/src/browser/lib/ActionBuilder.js

@@ -51,6 +51,16 @@ import {ACTIVITY} from "./Activity.js"
  * @class ActionBuilder
  */
 export default class ActionBuilder {
+  /**
+   * The ActionHooks class used to resolve hooks. Defaults to the
+   * browser-compatible implementation (pre-instantiated hooks only). The Node
+   * entry point overrides this with the file-loading subclass so that
+   * {@link ActionBuilder#withHooksFile} works.
+   *
+   * @type {typeof ActionHooks}
+   */
+  static HooksClass = ActionHooks
+
   /** @type {ActionBuilderAction?} */
   #action = null
   /** @type {Map<string|symbol, ActivityDefinition>} */
@@ -334,23 +344,29 @@ export default class ActionBuilder {
   }
 
   async #getHooks() {
-    const newHooks = ActionHooks.new
+    const HooksClass = ActionBuilder.HooksClass
 
     const hooks = this.#hooks
     if(hooks) {
-      // If hooks is already an ActionHooks instance, use it directly
+      // If hooks is already an ActionHooks instance, use it directly.
+      // The base class catches subclass instances too.
       if(hooks instanceof ActionHooks)
         return hooks
 
       // Otherwise, wrap it in a new ActionHooks instance
-      return await newHooks({hooks}, this.#debug)
+      return await HooksClass.new({hooks}, this.#debug)
     }
 
     const hooksFile = this.#hooksFile
     const hooksKind = this.#hooksKind
 
+    // File loading is only available on the Node HooksClass; the loader keys the
+    // class to instantiate off `actionKind`.
     if(hooksFile && hooksKind)
-      return await newHooks({hooksFile,hooksKind}, this.#debug)
+      return await HooksClass.new(
+        {hooksFile, actionKind: hooksKind},
+        this.#debug,
+      )
   }
 
   /**

package/src/browser/lib/ActionRunner.js

@@ -63,7 +63,25 @@ export default class ActionRunner extends Piper {
   }
 
   /**
-   * Invokes the `setup` lifecycle hook on the raw hooks object, if defined.
+   * Builds the ActionWrapper on first use and caches it for subsequent calls.
+   *
+   * Hooks are configured by the action's `setup()`, which only runs during
+   * `build()`. The setup/cleanup lifecycle hooks fire from {@link Piper#pipe}
+   * before any item is processed, so the wrapper must be built here too —
+   * otherwise the resolved hooks would not yet exist when setup runs.
+   *
+   * @returns {Promise<import("./ActionWrapper.js").default>} The built wrapper.
+   * @private
+   */
+  async #ensureBuilt() {
+    if(!this.#actionWrapper)
+      this.#actionWrapper = await this.#actionBuilder.build(this)
+
+    return this.#actionWrapper
+  }
+
+  /**
+   * Invokes the `setup` lifecycle hook on the resolved hooks object, if defined.
    * Registered as a Piper setup step so it fires before any items are processed.
    *
    * @param {unknown} ctx - Value passed by {@link Piper#pipe} (the items array).
@@ -71,29 +89,30 @@ export default class ActionRunner extends Piper {
    * @private
    */
   async #setupHooks(ctx) {
-    const ab = this.#actionBuilder
-    const ah = ab?.hooks
+    const wrapper = await this.#ensureBuilt()
+    const ah = wrapper.hooks
     const setup = ah?.setup
 
     if(setup)
-      await setup.call(ah, ctx)
+      await setup.call(ah.hooks, ctx)
   }
 
   /**
-   * Invokes the `cleanup` lifecycle hook on the raw hooks object, if defined.
-   * Registered as a Piper teardown step so it fires after all items are processed.
+   * Invokes the `cleanup` lifecycle hook on the resolved hooks object, if
+   * defined. Registered as a Piper teardown step so it fires after all items
+   * are processed.
    *
    * @param {unknown} ctx - Value passed by {@link Piper#pipe} (the items array).
    * @returns {Promise<void>}
    * @private
    */
   async #cleanupHooks(ctx) {
-    const ab = this.#actionBuilder
-    const ah = ab?.hooks
+    const wrapper = await this.#ensureBuilt()
+    const ah = wrapper.hooks
     const cleanup = ah?.cleanup
 
     if(cleanup)
-      await cleanup.call(ah, ctx)
+      await cleanup.call(ah.hooks, ctx)
   }
 
   /**
@@ -108,10 +127,7 @@ export default class ActionRunner extends Piper {
    * @throws {Tantrum} When both an activity and the done callback fail.
    */
   async run(context, parentWrapper=null) {
-    if(!this.#actionWrapper)
-      this.#actionWrapper = await this.#actionBuilder.build(this)
-
-    const actionWrapper = this.#actionWrapper
+    const actionWrapper = await this.#ensureBuilt()
     const activities = Array.from(actionWrapper.activities)
 
     let caughtError = null

package/src/browser/lib/ActionWrapper.js

@@ -113,4 +113,13 @@ export default class ActionWrapper {
   get action() {
     return this.#action
   }
+
+  /**
+   * Get the resolved hooks manager.
+   *
+   * @returns {import("./ActionHooks.js").default?} Hooks manager or null.
+   */
+  get hooks() {
+    return this.#hooks
+  }
 }

package/src/browser/lib/Piper.js

@@ -170,9 +170,9 @@ export default class Piper extends NotifyClass {
    * @param {Array<unknown>} settled - Results from settleAll
    * @throws {Tantrum} - If any settled result was rejected
    */
-  #processResult(_message, settled) {
+  #processResult(message, settled) {
     if(Promised.hasRejected(settled))
-      Promised.throw(settled)
+      Promised.throw(message, settled)
   }
 
   /**

package/src/index.js

@@ -1,9 +1,14 @@
 // Browser-compatible base classes
-export {default as ActionBuilder} from "./browser/lib/ActionBuilder.js"
+import ActionBuilder from "./browser/lib/ActionBuilder.js"
+import ActionHooks from "./lib/ActionHooks.js"
+
+// Node-enhanced ActionHooks (extends browser, adds FileObject support). Wiring
+// it into the builder makes withHooksFile() load hooks from disk under the Node
+// entry point, while the browser entry keeps the pre-instantiated-only default.
+ActionBuilder.HooksClass = ActionHooks
+
+export {ActionBuilder, ActionHooks}
 export {default as ActionRunner} from "./browser/lib/ActionRunner.js"
 export {default as ActionWrapper} from "./browser/lib/ActionWrapper.js"
 export {default as Activity, ACTIVITY} from "./browser/lib/Activity.js"
 export {default as Piper} from "./browser/lib/Piper.js"
-
-// Node-enhanced version (extends browser, adds FileObject support)
-export {default as ActionHooks} from "./lib/ActionHooks.js"

package/src/lib/ActionHooks.js

@@ -75,11 +75,11 @@ export default class ActionHooks extends BrowserActionHooks {
 
     const hooksFile = new FileObject(config.hooksFile)
 
-    debug("Loading hooks from %o", 2, hooksFile.uri)
-    debug("Checking hooks file exists: %o", 2, hooksFile.uri)
+    debug("Loading hooks from %o", 2, hooksFile.path)
+    debug("Checking hooks file exists: %o", 2, hooksFile.path)
 
     if(!await hooksFile.exists)
-      throw Sass.new(`No such hooks file, ${hooksFile.uri}`)
+      throw Sass.new(`No such hooks file, ${hooksFile.path}`)
 
     try {
       const hooksImport = await hooksFile.import()
@@ -100,7 +100,7 @@ export default class ActionHooks extends BrowserActionHooks {
       // Create instance with loaded hooks
       return new ActionHooks({...config, hooks, debug})
     } catch(error) {
-      debug("Failed to load hooks %o: %o", 1, hooksFile.uri, error.message)
+      debug("Failed to load hooks %o: %o", 1, hooksFile.path, error.message)
 
       return null
     }

package/src/types/browser/lib/ActionBuilder.d.ts

@@ -44,6 +44,15 @@
  * @class ActionBuilder
  */
 export default class ActionBuilder {
+    /**
+     * The ActionHooks class used to resolve hooks. Defaults to the
+     * browser-compatible implementation (pre-instantiated hooks only). The Node
+     * entry point overrides this with the file-loading subclass so that
+     * {@link ActionBuilder#withHooksFile} works.
+     *
+     * @type {typeof ActionHooks}
+     */
+    static HooksClass: typeof ActionHooks;
     /**
      * Creates a new ActionBuilder instance with the provided action callback.
      *

package/src/types/browser/lib/ActionBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActionBuilder.d.ts","sourceRoot":"","sources":["../../../browser/lib/ActionBuilder.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAkBE;;;;;OAKG;IACH,qBAHW,mBAAmB,mBACnB,mBAAmB,EAkB7B;IAED,yBAEC;;;;;;;;;;;;;;;IAWE,SACQ,MAAM,GAAC,MAAM,MACb,cAAc,GACZ,aAAa,CACzB;;;;;;;;IAGE,SACQ,MAAM,GAAC,MAAM,QACb,MAAM,QACN,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAC5C,aAAa,CACzB;;;;;;;;;IAGE,SACQ,MAAM,GAAC,MAAM,QACb,MAAM,QACN,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,MAC9C,cAAc,GAAC,aAAa,GAC1B,aAAa,CACzB;;;;;;;;;;IAGE,SACQ,MAAM,GAAC,MAAM,QACb,MAAM,YACN,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,YAC7B,CAAC,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,KAAK,OAAO,MAC5D,cAAc,GAAC,aAAa,GAC1B,aAAa,CACzB;IAkED;;;;;;;OAOG;IACH,yBALW,MAAM,aACN,MAAM,GACJ,aAAa,CAYzB;IAED;;;;;;OAMG;IACH,iBAJW,WAAW,GACT,aAAa,CAgBzB;IAED;;;;;;OAMG;IACH,mBAHW,mBAAmB,GACjB,aAAa,CAczB;IAED;;;;;OAKG;IACH,eAHW,cAAc,GACZ,aAAa,CAOzB;IAeD;;;;;;OAMG;IACH,cAHW,YAAY,GACV,OAAO,CAAC,aAAa,CAAC,CAoClC;IAsBD;;;;;OAKG;IACH,aAFa,MAAM,cAAU,IAAI,CAIhC;;CACF;;;;sBAjWY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;;;;;;;WAGjE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;YAQhC,mBAAmB,GAAC,IAAI;;;;WACxB,OAAO,GAAC,IAAI;;;;UACZ,MAAM,GAAC,MAAM;;;;QACb,cAAc,GAAC,OAAO,oBAAoB,EAAE,OAAO;;;;;;;;sBAEzC,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;;;;;6BAE/C,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;wBA1BnC,kBAAkB;6CAMA,mBAAmB;0BAPnC,oBAAoB"}
+{"version":3,"file":"ActionBuilder.d.ts","sourceRoot":"","sources":["../../../browser/lib/ActionBuilder.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IACE;;;;;;;OAOG;IACH,mBAFU,OAAO,WAAW,CAEG;IAmB/B;;;;;OAKG;IACH,qBAHW,mBAAmB,mBACnB,mBAAmB,EAkB7B;IAED,yBAEC;;;;;;;;;;;;;;;IAWE,SACQ,MAAM,GAAC,MAAM,MACb,cAAc,GACZ,aAAa,CACzB;;;;;;;;IAGE,SACQ,MAAM,GAAC,MAAM,QACb,MAAM,QACN,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAC5C,aAAa,CACzB;;;;;;;;;IAGE,SACQ,MAAM,GAAC,MAAM,QACb,MAAM,QACN,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,MAC9C,cAAc,GAAC,aAAa,GAC1B,aAAa,CACzB;;;;;;;;;;IAGE,SACQ,MAAM,GAAC,MAAM,QACb,MAAM,YACN,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,YAC7B,CAAC,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,KAAK,OAAO,MAC5D,cAAc,GAAC,aAAa,GAC1B,aAAa,CACzB;IAkED;;;;;;;OAOG;IACH,yBALW,MAAM,aACN,MAAM,GACJ,aAAa,CAYzB;IAED;;;;;;OAMG;IACH,iBAJW,WAAW,GACT,aAAa,CAgBzB;IAED;;;;;;OAMG;IACH,mBAHW,mBAAmB,GACjB,aAAa,CAczB;IAED;;;;;OAKG;IACH,eAHW,cAAc,GACZ,aAAa,CAOzB;IAeD;;;;;;OAMG;IACH,cAHW,YAAY,GACV,OAAO,CAAC,aAAa,CAAC,CAoClC;IA4BD;;;;;OAKG;IACH,aAFa,MAAM,cAAU,IAAI,CAIhC;;CACF;;;;sBAjXY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;;;;;;;WAGjE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;YAQhC,mBAAmB,GAAC,IAAI;;;;WACxB,OAAO,GAAC,IAAI;;;;UACZ,MAAM,GAAC,MAAM;;;;QACb,cAAc,GAAC,OAAO,oBAAoB,EAAE,OAAO;;;;;;;;sBAEzC,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;;;;;6BAE/C,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;wBA1BnC,kBAAkB;6CAMA,mBAAmB;0BAPnC,oBAAoB"}

package/src/types/browser/lib/ActionRunner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActionRunner.d.ts","sourceRoot":"","sources":["../../../browser/lib/ActionRunner.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH;;;;;GAKG;AAEH;;;;;;GAMG;AACH;IAaE;;;;;OAKG;IACH,2BAHW,OAAO,oBAAoB,EAAE,OAAO,GAAC,IAAI,cACzC,mBAAmB,EAoB7B;IAoCD;;;;;;;;;;OAUG;IACH,aANW,OAAO,kBACP,OAAO,oBAAoB,EAAE,OAAO,GAAC,IAAI,GACvC,OAAO,CAAC,OAAO,CAAC,CAoJ5B;;CAiGF;sBAlVY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;;;;;;kBAT7D,YAAY"}
+{"version":3,"file":"ActionRunner.d.ts","sourceRoot":"","sources":["../../../browser/lib/ActionRunner.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH;;;;;GAKG;AAEH;;;;;;GAMG;AACH;IAaE;;;;;OAKG;IACH,2BAHW,OAAO,oBAAoB,EAAE,OAAO,GAAC,IAAI,cACzC,mBAAmB,EAoB7B;IAuDD;;;;;;;;;;OAUG;IACH,aANW,OAAO,kBACP,OAAO,oBAAoB,EAAE,OAAO,GAAC,IAAI,GACvC,OAAO,CAAC,OAAO,CAAC,CAiJ5B;;CAiGF;sBAlWY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;;;;;;kBAT7D,YAAY"}

package/src/types/browser/lib/ActionWrapper.d.ts

@@ -58,6 +58,12 @@ export default class ActionWrapper {
      * @returns {unknown|null} Action instance or null.
      */
     get action(): unknown | null;
+    /**
+     * Get the resolved hooks manager.
+     *
+     * @returns {import("./ActionHooks.js").default?} Hooks manager or null.
+     */
+    get hooks(): import("./ActionHooks.js").default | null;
     #private;
 }
 export type WrappedActivityConfig = {

package/src/types/browser/lib/ActionWrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActionWrapper.d.ts","sourceRoot":"","sources":["../../../browser/lib/ActionWrapper.js"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH;;;;;;;;GAQG;AAEH;;GAEG;AACH;IAwBE;;;;;;;;;OASG;IACH,sEANG;QAAwD,UAAU,EAA1D,GAAG,CAAC,MAAM,GAAC,MAAM,EAAE,qBAAqB,CAAC;QACgC,KAAK,EAA9E,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;QACxB,KAAK,EAA/C,OAAO,kBAAkB,EAAE,OAAO,OAAC;QAC0B,IAAI,cAAtD,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;QAChC,MAAM,GAArB,OAAO;KACjB,EAuBA;IAED;;;;;OAKG;IACH,UAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,kBAFa,QAAQ,CAAC,QAAQ,CAAC,CAI9B;IAED;;;;OAIG;IACH,YAFa,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAC,IAAI,CAIjE;IAED;;;;OAIG;IACH,cAFa,OAAO,GAAC,IAAI,CAIxB;;CACF;;;;;UAzGa,MAAM,GAAC,MAAM;;;;QACb,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,aAAa;;;;;;;;sBAElD,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;;;;aAC9C,OAAO;;;;uBACG,MAAM,UAAU,MAAM,WAAW,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;qBAf3D,eAAe"}
+{"version":3,"file":"ActionWrapper.d.ts","sourceRoot":"","sources":["../../../browser/lib/ActionWrapper.js"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH;;;;;;;;GAQG;AAEH;;GAEG;AACH;IAwBE;;;;;;;;;OASG;IACH,sEANG;QAAwD,UAAU,EAA1D,GAAG,CAAC,MAAM,GAAC,MAAM,EAAE,qBAAqB,CAAC;QACgC,KAAK,EAA9E,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;QACxB,KAAK,EAA/C,OAAO,kBAAkB,EAAE,OAAO,OAAC;QAC0B,IAAI,cAAtD,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;QAChC,MAAM,GAArB,OAAO;KACjB,EAuBA;IAED;;;;;OAKG;IACH,UAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,kBAFa,QAAQ,CAAC,QAAQ,CAAC,CAI9B;IAED;;;;OAIG;IACH,YAFa,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAC,IAAI,CAIjE;IAED;;;;OAIG;IACH,cAFa,OAAO,GAAC,IAAI,CAIxB;IAED;;;;OAIG;IACH,aAFa,OAAO,kBAAkB,EAAE,OAAO,OAAC,CAI/C;;CACF;;;;;UAlHa,MAAM,GAAC,MAAM;;;;QACb,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,aAAa;;;;;;;;sBAElD,OAAO,KAAK,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC;;;;aAC9C,OAAO;;;;uBACG,MAAM,UAAU,MAAM,WAAW,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI;;qBAf3D,eAAe"}

package/src/types/index.d.ts

@@ -1,7 +1,8 @@
-export { default as ActionBuilder } from "./browser/lib/ActionBuilder.js";
 export { default as ActionRunner } from "./browser/lib/ActionRunner.js";
 export { default as ActionWrapper } from "./browser/lib/ActionWrapper.js";
 export { default as Piper } from "./browser/lib/Piper.js";
-export { default as ActionHooks } from "./lib/ActionHooks.js";
+import ActionBuilder from "./browser/lib/ActionBuilder.js";
+import ActionHooks from "./lib/ActionHooks.js";
+export { ActionBuilder, ActionHooks };
 export { default as Activity, ACTIVITY } from "./browser/lib/Activity.js";
 //# sourceMappingURL=index.d.ts.map

package/src/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.js"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.js"],"names":[],"mappings":";;;0BAC0B,gCAAgC;wBAClC,sBAAsB"}