@gesslar/actioneer 2.2.0 → 2.4.0

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "2.2.0",
+  "version": "2.4.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {
@@ -22,7 +22,6 @@
     "composition",
     "lasagna"
   ],
-  "main": "./src/index.js",
   "type": "module",
   "exports": {
     ".": {
@@ -46,28 +45,28 @@
   ],
   "sideEffects": false,
   "engines": {
-    "node": ">=22"
-  },
-  "dependencies": {
-    "@gesslar/toolkit": "^3.24.0"
-  },
-  "devDependencies": {
-    "@gesslar/uglier": "^1.2.0",
-    "eslint": "^9.39.2",
-    "typescript": "^5.9.3"
+    "node": ">=24.13.0"
   },
   "scripts": {
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "types": "node -e \"require('fs').rmSync('types',{recursive:true,force:true});\" && tsc -p tsconfig.types.json",
-    "submit": "pnpm publish --access public --//registry.npmjs.org/:_authToken=\"${NPM_ACCESS_TOKEN}\"",
-    "update": "pnpm self-update && pnpx npm-check-updates -u && pnpm install",
+    "submit": "npm publish --access public --//registry.npmjs.org/:_authToken=\"${NPM_ACCESS_TOKEN}\"",
+    "update": "npx npm-check-updates -u && npm install",
     "test": "node --test tests/**/*.test.js",
     "test:browser": "node --test tests/browser/*.test.js",
     "test:node": "node --test tests/node/*.test.js",
     "pr": "gt submit -p --ai",
-    "patch": "pnpm version patch",
-    "minor": "pnpm version minor",
-    "major": "pnpm version major"
+    "patch": "npm version patch",
+    "minor": "npm version minor",
+    "major": "npm version major"
+  },
+  "dependencies": {
+    "@gesslar/toolkit": "^3.37.0"
+  },
+  "devDependencies": {
+    "@gesslar/uglier": "^1.6.2",
+    "eslint": "^10.0.0",
+    "typescript": "^5.9.3"
   }
-}
+}

package/src/browser/lib/ActionBuilder.js

@@ -4,36 +4,29 @@ import ActionWrapper from "./ActionWrapper.js"
 import ActionHooks from "./ActionHooks.js"
 import {ACTIVITY} from "./Activity.js"
 
-/** @typedef {import("./ActionRunner.js").default} ActionRunner */
-/** @typedef {typeof import("./Activity.js").ACTIVITY} ActivityFlags */
-
 /**
+ * Type imports and definitions.
+ *
+ * @import {default as ActionRunner} from "./ActionRunner.js"
+ *
  * @typedef {(message: string, level?: number, ...args: Array<unknown>) => void} DebugFn
- */
-
-/**
+ *
  * @typedef {object} ActionBuilderAction
- * @property {(builder: ActionBuilder) => void} setup Function invoked during {@link ActionBuilder#build} to register activities.
- * @property {symbol} [tag] Optional tag to reuse when reconstructing builders.
- */
-
-/**
+ * @property {(builder: ActionBuilder) => void} setup - Function invoked during {@link ActionBuilder} to register activities.
+ * @property {symbol} [tag] - Optional tag to reuse when reconstructing builders.
+ *
  * @typedef {object} ActionBuilderConfig
- * @property {symbol} [tag] Optional tag for the builder instance.
- * @property {DebugFn} [debug] Logger used by the pipeline internals.
- */
-
-/**
+ * @property {symbol} [tag] - Optional tag for the builder instance.
+ * @property {DebugFn} [debug] - Logger used by the pipeline internals.
+ *
  * @typedef {object} ActivityDefinition
- * @property {ActionBuilderAction|null} action Parent action instance when available.
- * @property {DebugFn|null} debug Logger function.
- * @property {string|symbol} name Activity identifier.
- * @property {ActionFunction|import("./ActionWrapper.js").default} op Operation to execute.
- * @property {number} [kind] Optional kind flags from {@link ActivityFlags}.
- * @property {(context: unknown) => boolean|Promise<boolean>} [pred] Loop predicate.
- */
-
-/**
+ * @property {ActionBuilderAction|null} action - Parent action instance when available.
+ * @property {DebugFn|null} debug - Logger function.
+ * @property {string|symbol} name - Activity identifier.
+ * @property {ActionFunction|import("./ActionWrapper.js").default} op - Operation to execute.
+ * @property {number} [kind] - Optional kind flags from {@link ACTIVITY}.
+ * @property {(context: unknown) => boolean|Promise<boolean>} [pred] - Loop predicate.
+ *
  * @typedef {(context: unknown) => unknown|Promise<unknown>} ActionFunction
  */
 
@@ -58,28 +51,28 @@ import {ACTIVITY} from "./Activity.js"
  * @class ActionBuilder
  */
 export default class ActionBuilder {
-  /** @type {ActionBuilderAction|null} */
+  /** @type {ActionBuilderAction?} */
   #action = null
   /** @type {Map<string|symbol, ActivityDefinition>} */
   #activities = new Map([])
-  /** @type {DebugFn|null} */
+  /** @type {DebugFn?} */
   #debug = null
-  /** @type {symbol|null} */
+  /** @type {symbol?} */
   #tag = null
-  /** @type {string|null} */
+  /** @type {string?} */
   #hooksFile = null
-  /** @type {string|null} */
+  /** @type {string?} */
   #hooksKind = null
-  /** @type {import("./ActionHooks.js").default|null} */
+  /** @type {ActionHooks?} */
   #hooks = null
-  /** @type {ActionFunction|null} */
+  /** @type {ActionFunction?} */
   #done = null
 
   /**
    * Creates a new ActionBuilder instance with the provided action callback.
    *
-   * @param {ActionBuilderAction} [action] Base action invoked by the runner when a block satisfies the configured structure.
-   * @param {ActionBuilderConfig} [config] Options
+   * @param {ActionBuilderAction} [action] - Base action invoked by the runner when a block satisfies the configured structure.
+   * @param {ActionBuilderConfig} [config] - Options
    */
   constructor(
     action,
@@ -89,6 +82,9 @@ export default class ActionBuilder {
     this.#tag = this.#tag || tag
 
     if(action) {
+      if(action.tag)
+        throw Sass.new("Action has already been consumed by a builder and cannot be reused.")
+
       if(Data.typeOf(action.setup) !== "Function")
         throw Sass.new("Setup must be a function.")
 
@@ -110,44 +106,44 @@ export default class ActionBuilder {
    * - do(name, kind, splitter, rejoiner, opOrWrapper) - SPLIT with parallel execution
    *
    * @overload
-   * @param {string|symbol} name Activity name
-   * @param {ActionFunction} op Operation to execute once.
+   * @param {string|symbol} name - Activity name
+   * @param {ActionFunction} op - Operation to execute once.
    * @returns {ActionBuilder}
    */
 
   /**
    * @overload
-   * @param {string|symbol} name Activity name
-   * @param {number} kind ACTIVITY.BREAK or ACTIVITY.CONTINUE flag.
-   * @param {(context: unknown) => boolean|Promise<boolean>} pred Predicate to evaluate for control flow.
+   * @param {string|symbol} name - Activity name
+   * @param {number} kind - ACTIVITY.BREAK or ACTIVITY.CONTINUE flag.
+   * @param {(context: unknown) => boolean|Promise<boolean>} pred - Predicate to evaluate for control flow.
    * @returns {ActionBuilder}
    */
 
   /**
    * @overload
-   * @param {string|symbol} name Activity name
-   * @param {number} kind Activity kind (WHILE, UNTIL, or IF) from {@link ActivityFlags}.
-   * @param {(context: unknown) => boolean|Promise<boolean>} pred Predicate executed before/after the op.
-   * @param {ActionFunction|ActionBuilder} op Operation or nested builder to execute.
+   * @param {string|symbol} name - Activity name
+   * @param {number} kind - Activity kind (WHILE, UNTIL, or IF) from {@link ACTIVITY}.
+   * @param {(context: unknown) => boolean|Promise<boolean>} pred - Predicate executed before/after the op.
+   * @param {ActionFunction|ActionBuilder} op - Operation or nested builder to execute.
    * @returns {ActionBuilder}
    */
 
   /**
    * @overload
-   * @param {string|symbol} name Activity name
-   * @param {number} kind ACTIVITY.SPLIT flag.
-   * @param {(context: unknown) => unknown} splitter Splitter function for SPLIT mode.
-   * @param {(originalContext: unknown, splitResults: unknown) => unknown} rejoiner Rejoiner function for SPLIT mode.
-   * @param {ActionFunction|ActionBuilder} op Operation or nested builder to execute.
+   * @param {string|symbol} name - Activity name
+   * @param {number} kind - ACTIVITY.SPLIT flag.
+   * @param {(context: unknown) => unknown} splitter - Splitter function for SPLIT mode.
+   * @param {(originalContext: unknown, splitResults: unknown) => unknown} rejoiner - Rejoiner function for SPLIT mode.
+   * @param {ActionFunction|ActionBuilder} op - Operation or nested builder to execute.
    * @returns {ActionBuilder}
    */
 
   /**
    * Handles runtime dispatch across the documented overloads.
    *
-   * @param {string|symbol} name Activity name
-   * @param {...unknown} args See overloads
-   * @returns {ActionBuilder} The builder instance for chaining
+   * @param {string|symbol} name - Activity name
+   * @param {...unknown} args - See overloads
+   * @returns {ActionBuilder} - The builder instance for chaining
    */
   do(name, ...args) {
     this.#dupeActivityCheck(name)
@@ -209,9 +205,9 @@ export default class ActionBuilder {
   /**
    * Configure hooks to be loaded from a file when the action is built.
    *
-   * @param {string} hooksFile Path to the hooks module file.
-   * @param {string} hooksKind Name of the exported hooks class to instantiate.
-   * @returns {ActionBuilder} The builder instance for chaining.
+   * @param {string} hooksFile - Path to the hooks module file.
+   * @param {string} hooksKind - Name of the exported hooks class to instantiate.
+   * @returns {ActionBuilder} - The builder instance for chaining.
    * @throws {Sass} If hooks have already been configured.
    */
   withHooksFile(hooksFile, hooksKind) {
@@ -228,15 +224,15 @@ export default class ActionBuilder {
   /**
    * Configure hooks using a pre-instantiated hooks object.
    *
-   * @param {import("./ActionHooks.js").default} hooks An already-instantiated hooks instance.
-   * @returns {ActionBuilder} The builder instance for chaining.
+   * @param {ActionHooks} hooks - An already-instantiated hooks instance.
+   * @returns {ActionBuilder} - The builder instance for chaining.
    * @throws {Sass} If hooks have already been configured with a different instance.
    */
   withHooks(hooks) {
-    // If the same hooks instance is already set, this is idempotent - just return
-    if(this.#hooks === hooks) {
+    // If the same hooks instance is already set, this is idempotent -just
+    // return.
+    if(this.#hooks === hooks)
       return this
-    }
 
     Valid.assert(this.#hooksFile === null, "Hooks have already been configured.")
     Valid.assert(this.#hooksKind === null, "Hooks have already been configured.")
@@ -251,7 +247,7 @@ export default class ActionBuilder {
    * Configure the action instance if not already set.
    * Used to propagate parent action context to nested builders.
    *
-   * @param {ActionBuilderAction} action The action instance to inherit.
+   * @param {ActionBuilderAction} action - The action instance to inherit.
    * @returns {ActionBuilder} The builder instance for chaining.
    */
   withAction(action) {
@@ -271,7 +267,7 @@ export default class ActionBuilder {
   /**
    * Register a callback to be executed after all activities complete.
    *
-   * @param {ActionFunction} callback Function to execute at the end of the pipeline.
+   * @param {ActionFunction} callback - Function to execute at the end of the pipeline.
    * @returns {ActionBuilder} The builder instance for chaining.
    */
   done(callback) {
@@ -285,7 +281,7 @@ export default class ActionBuilder {
    * Validates that an activity name has not been reused.
    *
    * @private
-   * @param {string | symbol} name Activity identifier.
+   * @param {string|symbol} name Activity identifier.
    */
   #dupeActivityCheck(name) {
     Valid.assert(
@@ -298,9 +294,10 @@ export default class ActionBuilder {
    * Finalises the builder and returns a payload that can be consumed by the
    * runner.
    *
-   * @returns {Promise<import("./ActionWrapper.js").default>} Payload consumed by the {@link ActionRunner} constructor.
+   * @param {ActionRunner} runner - The runner invoking the build.
+   * @returns {Promise<ActionWrapper>} Payload consumed by the {@link ActionRunner} constructor.
    */
-  async build() {
+  async build(runner) {
     const action = this.#action
 
     if(action && !action.tag) {
@@ -309,6 +306,20 @@ export default class ActionBuilder {
       await Promise.resolve(action.setup.call(action, this))
     }
 
+    if(action) {
+    // Inject a method to the action for emission, but only if it's undefined.
+      if(Data.isType(action.emit, "Undefined"))
+        action.emit = (...args) => runner.emit(...args)
+
+      // Inject a method to the action for onission, but only if it's undefined.
+      if(Data.isType(action.on, "Undefined"))
+        action.on = (event, cb) => runner.on(event, cb)
+
+      // Inject a method to the action for offission, but only if it's undefined.
+      if(Data.isType(action.off, "Undefined"))
+        action.off = (event, cb) => runner.off(event, cb)
+    }
+
     // All children in a branch also get the same hooks.
     const hooks = await this.#getHooks()
 
@@ -317,7 +328,8 @@ export default class ActionBuilder {
       debug: this.#debug,
       hooks,
       done: this.#done,
-      action: this.#action,
+      action,
+      runner: runner,
     })
   }
 
@@ -340,4 +352,14 @@ export default class ActionBuilder {
     if(hooksFile && hooksKind)
       return await newHooks({hooksFile,hooksKind}, this.#debug)
   }
+
+  /**
+   * Returns the raw hooks value configured on this builder.
+   * Used by {@link ActionRunner} to access setup/cleanup lifecycle hooks.
+   *
+   * @returns {object|Function|null} Raw hooks value, or null if not configured.
+   */
+  get hooks() {
+    return this.#hooks
+  }
 }

package/src/browser/lib/ActionHooks.js

@@ -4,16 +4,14 @@ import {Data, Sass, Promised, Time, Util, Valid} from "@gesslar/toolkit"
  * @typedef {(message: string, level?: number, ...args: Array<unknown>) => void} DebugFn
  */
 
-/**
- * @typedef {object} ActionHooksConfig
- * @property {string} actionKind Action identifier shared between runner and hooks.
- * @property {unknown} hooks Already-instantiated hooks implementation.
- * @property {number} [hookTimeout] Timeout applied to hook execution in milliseconds.
- * @property {DebugFn} debug Logger to emit diagnostics.
- */
-
 /**
  * @typedef {Record<string, (context: unknown) => Promise<unknown>|unknown>} HookModule
+ *
+ * @typedef {object} ActionHooksConfig
+ * @property {string} actionKind - Action identifier shared between runner and hooks.
+ * @property {object|Function|null} hooks - Pre-instantiated hooks object, a constructor to instantiate, or null.
+ * @property {number} [hookTimeout] - Timeout applied to hook execution in milliseconds.
+ * @property {DebugFn} debug - Logger to emit diagnostics.
  */
 
 /**
@@ -24,19 +22,19 @@ import {Data, Sass, Promised, Time, Util, Valid} from "@gesslar/toolkit"
  * Browser version: Requires pre-instantiated hooks. File-based loading is not supported.
  */
 export default class ActionHooks {
-  /** @type {HookModule|null} */
+  /** @type {HookModule?} */
   #hooks = null
-  /** @type {string|null} */
+  /** @type {string?} */
   #actionKind = null
   /** @type {number} */
   #timeout = 1_000 // Default 1 second timeout
-  /** @type {DebugFn|null} */
+  /** @type {DebugFn?} */
   #debug = null
 
   /**
    * Creates a new ActionHook instance.
    *
-   * @param {ActionHooksConfig} config Configuration values describing how to load the hooks.
+   * @param {ActionHooksConfig} config - Configuration values describing how to load the hooks.
    */
   constructor({actionKind, hooks, hookTimeout = 1_000, debug}) {
     this.#actionKind = actionKind
@@ -56,10 +54,18 @@ export default class ActionHooks {
 
   /**
    * Gets the loaded hooks object.
+   * If the stored value is a plain object it is returned as-is.
+   * If it is a constructor function a new instance is created and returned.
    *
-   * @returns {object|null} Hooks object or null if not loaded
+   * @returns {object?} Hooks object or null if not loaded
    */
   get hooks() {
+    if(Data.isType(this.#hooks, "Object"))
+      return this.#hooks
+
+    else if(Data.isType(this.#hooks, "Function"))
+      return new this.#hooks()
+
     return this.#hooks
   }
 
@@ -75,7 +81,7 @@ export default class ActionHooks {
   /**
    * Gets the setup hook function if available.
    *
-   * @returns {(args: object) => unknown|null} Setup hook function or null
+   * @returns {(args: object) => unknown} Setup hook function or null
    */
   get setup() {
     return this.hooks?.setup || null
@@ -84,7 +90,7 @@ export default class ActionHooks {
   /**
    * Gets the cleanup hook function if available.
    *
-   * @returns {(args: object) => unknown|null} Cleanup hook function or null
+   * @returns {(args: object) => unknown} Cleanup hook function or null
    */
   get cleanup() {
     return this.hooks?.cleanup || null
@@ -94,12 +100,12 @@ export default class ActionHooks {
    * Static factory method to create and initialize a hook manager.
    * Browser version: Only works with pre-instantiated hooks passed via config.hooks.
    *
-   * @param {ActionHooksConfig} config Configuration object with hooks property
-   * @param {DebugFn} debug The debug function.
-   * @returns {Promise<ActionHooks|null>} Initialized hook manager or null if no hooks provided
+   * @param {ActionHooksConfig} config - Configuration object with hooks property
+   * @param {DebugFn} debug - The debug function.
+   * @returns {Promise<ActionHooks?>} Initialized hook manager or null if no hooks provided
    */
   static async new(config, debug) {
-    debug("Creating new HookManager instance with args: %o", 2, config)
+    debug("Creating new ActionHooks instance with args: %o", 2, config)
 
     if(!config.hooks) {
       debug("No hooks provided (browser mode requires pre-instantiated hooks)", 2)
@@ -117,12 +123,13 @@ export default class ActionHooks {
   /**
    * Invoke a dynamically-named hook such as `before$foo`.
    *
-   * @param {'before'|'after'|'setup'|'cleanup'|string} kind Hook namespace.
-   * @param {string|symbol} activityName Activity identifier.
-   * @param {unknown} context Pipeline context supplied to the hook.
+   * @param {string} kind - Hook namespace.
+   * @param {string|symbol} activityName - Activity identifier.
+   * @param {unknown} oldContext - Pipeline context supplied to the hook.
+   * @param {unknown} newContext - For after$ hooks, the result of the op
    * @returns {Promise<void>}
    */
-  async callHook(kind, activityName, context) {
+  async callHook(kind, activityName, oldContext, newContext) {
     try {
       const debug = this.#debug
       const hooks = this.#hooks
@@ -149,7 +156,11 @@ export default class ActionHooks {
         debug("Hook function starting execution: %o", 4, hookName)
 
         const duration = (
-          await Util.time(() => hook.call(this.#hooks, context))
+          newContext
+            ? await Util.time(
+              () => hook.call(this.#hooks, newContext, oldContext)
+            )
+            : await Util.time(() => hook.call(this.#hooks, oldContext))
         ).cost
 
         debug("Hook function completed successfully: %o, after %oms", 4, hookName, duration)
@@ -170,9 +181,6 @@ export default class ActionHooks {
       } catch(error) {
         throw Sass.new(`Processing hook ${kind}$${activityName}`, error)
       }
-
-      debug("We made it throoough the wildernessss", 4)
-
     } catch(error) {
       throw Sass.new(`Processing hook ${kind}$${activityName}`, error)
     }