@gesslar/actioneer 1.6.0 → 2.0.2

package/README.md

@@ -1,18 +1,97 @@
 # Actioneer
 
-Actioneer is a small, focused Node.js action orchestration library. It provides a fluent builder for composing activities and a concurrent runner with lifecycle hooks and simple loop semantics (while/until). The project is written as ES modules and targets Node 20+.
+Actioneer is a small, focused action orchestration library for Node.js and browser environments. It provides a fluent builder for composing activities and a concurrent runner with lifecycle hooks and simple loop semantics (while/until). The project is written as ES modules and targets Node 20+ and modern browsers.
 
 This repository extracts the action orchestration pieces from a larger codebase and exposes a compact API for building pipelines of work that can run concurrently with hook support and nested pipelines.
 
-## Install
+## Included Classes
 
-From npm:
+### Browser
+
+These classes work in browsers, Node.js, and browser-like environments such as Tauri, Electron, and Deno.
+
+| Name | Description |
+| ---- | ----------- |
+| ActionBuilder | Fluent builder for composing activities into pipelines |
+| ActionHooks | Lifecycle hook management (requires pre-instantiated hooks in browser) |
+| ActionRunner | Concurrent pipeline executor with configurable concurrency |
+| ActionWrapper | Activity container and iterator |
+| Activity | Activity definitions with WHILE, UNTIL, and SPLIT modes |
+| Piper | Base concurrent processing with worker pools |
+
+### Node.js
+
+Includes all browser functionality plus Node.js-specific features for file-based hook loading.
+
+| Name | Description |
+| ---- | ----------- |
+| ActionHooks | Enhanced version with file-based hook loading via `withHooksFile()` |
+
+## Installation
 
 ```bash
 npm install @gesslar/actioneer
 ```
 
-## Quick start
+## Usage
+
+Actioneer is environment-aware and automatically detects whether it is being used in a browser or Node.js. You can optionally specify the `node` or `browser` variant explicitly.
+
+### Browser
+
+#### jsDelivr (runtime only)
+
+```html
+https://cdn.jsdelivr.net/npm/@gesslar/actioneer
+```
+
+#### esm.sh (runtime with types)
+
+```html
+https://esm.sh/@gesslar/actioneer
+https://esm.sh/@gesslar/actioneer?dts  (serves .d.ts for editors)
+```
+
+#### Browser Import Example
+
+```javascript
+import {ActionBuilder, ActionRunner} from "https://esm.sh/@gesslar/actioneer"
+
+class MyAction {
+  setup(builder) {
+    builder
+      .do("step1", ctx => { ctx.result = ctx.input * 2 })
+      .do("step2", ctx => { return ctx.result })
+  }
+}
+
+const builder = new ActionBuilder(new MyAction())
+const runner = new ActionRunner(builder)
+const results = await runner.run({input: 5})
+console.log(results) // 10
+```
+
+### Node.js
+
+#### Auto-detected (recommended)
+
+```javascript
+import {ActionBuilder, ActionRunner} from "@gesslar/actioneer"
+```
+
+#### Explicit variants
+
+```javascript
+// Explicitly use Node.js version (with file-based hooks)
+import {ActionBuilder, ActionRunner, ActionHooks} from "@gesslar/actioneer/node"
+
+// Explicitly use browser version
+import {ActionBuilder, ActionRunner} from "@gesslar/actioneer/browser"
+```
+
+**Note:** The browser version is fully functional in Node.js but lacks file-based hook loading. Use `withHooks()` with pre-instantiated hooks instead of `withHooksFile()`.
+
+## Quick Start
 
 Import the builder and runner, define an action and run it:
 
@@ -299,7 +378,7 @@ This design ensures error handling responsibility stays at the call site - you d
 
 ## ActionHooks
 
-Actioneer supports lifecycle hooks that can execute before and after each activity in your pipeline. Hooks are loaded from a module and can be configured either by file path or by providing a pre-instantiated hooks object.
+Actioneer supports lifecycle hooks that can execute before and after each activity in your pipeline. Hooks can be configured by file path (Node.js only) or by providing a pre-instantiated hooks object (Node.js and browser).
 
 ### Hook System Overview
 
@@ -312,12 +391,49 @@ The hook system allows you to:
 
 ### Configuring Hooks
 
-You can attach hooks to an ActionBuilder in two ways:
+#### Browser: Pre-instantiated Hooks
 
-#### 1. Load hooks from a file
+In browser environments, you must provide pre-instantiated hooks objects:
 
 ```js
-import { ActionBuilder, ActionRunner } from "@gesslar/actioneer"
+import {ActionBuilder, ActionRunner} from "@gesslar/actioneer"
+
+class MyActionHooks {
+  constructor({debug}) {
+    this.debug = debug
+  }
+
+  async before$prepare(context) {
+    this.debug("About to prepare", context)
+  }
+
+  async after$prepare(context) {
+    this.debug("Finished preparing", context)
+  }
+}
+
+const hooks = new MyActionHooks({debug: console.log})
+
+class MyAction {
+  setup(builder) {
+    builder
+      .withHooks(hooks)
+      .do("prepare", ctx => { ctx.count = 0 })
+      .do("work", ctx => { ctx.count += 1 })
+  }
+}
+
+const builder = new ActionBuilder(new MyAction())
+const runner = new ActionRunner(builder)
+const result = await runner.pipe([{}], 4)
+```
+
+#### Node.js: File-based or Pre-instantiated
+
+**Option 1: Load hooks from a file** (Node.js only)
+
+```js
+import {ActionBuilder, ActionRunner} from "@gesslar/actioneer"
 
 class MyAction {
   setup(builder) {
@@ -333,13 +449,13 @@ const runner = new ActionRunner(builder)
 const result = await runner.pipe([{}], 4)
 ```
 
-#### 2. Provide a pre-instantiated hooks object
+**Option 2: Provide a pre-instantiated hooks object** (Node.js and browser)
 
 ```js
-import { ActionBuilder, ActionRunner } from "@gesslar/actioneer"
-import { MyActionHooks } from "./hooks/MyActionHooks.js"
+import {ActionBuilder, ActionRunner} from "@gesslar/actioneer"
+import {MyActionHooks} from "./hooks/MyActionHooks.js"
 
-const hooks = new MyActionHooks({ debug: console.log })
+const hooks = new MyActionHooks({debug: console.log})
 
 class MyAction {
   setup(builder) {

package/package.json

@@ -3,10 +3,9 @@
   "description": "The best action pipeline thingie this side of Tatooine, or your money back.",
   "author": {
     "name": "gesslar",
-    "email": "bmw@gesslar.dev",
     "url": "https://gesslar.dev"
   },
-  "version": "1.6.0",
+  "version": "2.0.2",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {
@@ -27,6 +26,16 @@
   "type": "module",
   "exports": {
     ".": {
+      "types": "./src/types/index.d.ts",
+      "browser": "./src/browser/index.js",
+      "node": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./browser": {
+      "types": "./src/types/index.d.ts",
+      "default": "./src/browser/index.js"
+    },
+    "./node": {
       "types": "./src/types/index.d.ts",
       "default": "./src/index.js"
     }
@@ -40,7 +49,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@gesslar/toolkit": "^3.6.0"
+    "@gesslar/toolkit": "^3.6.2"
   },
   "devDependencies": {
     "@gesslar/uglier": "^0.5.0",
@@ -50,11 +59,12 @@
   "scripts": {
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
-    "types:build": "tsc -p tsconfig.types.json && eslint --fix \"src/types/**/*.d.ts\"",
+    "types:build": "tsc -p tsconfig.types.json",
     "submit": "pnpm publish --access public --//registry.npmjs.org/:_authToken=\"${NPM_ACCESS_TOKEN}\"",
     "update": "pnpm up --latest --recursive",
-    "test": "node --test tests/unit/*.test.js",
-    "test:unit": "node --test tests/unit/*.test.js",
+    "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",

package/src/browser/index.js

@@ -0,0 +1,9 @@
+// Browser-compatible exports
+// Pure JavaScript modules that work in browsers and Node.js
+
+export {default as ActionBuilder} from "./lib/ActionBuilder.js"
+export {default as ActionHooks} from "./lib/ActionHooks.js"
+export {default as ActionRunner} from "./lib/ActionRunner.js"
+export {default as ActionWrapper} from "./lib/ActionWrapper.js"
+export {default as Activity, ACTIVITY} from "./lib/Activity.js"
+export {default as Piper} from "./lib/Piper.js"

package/src/browser/lib/ActionHooks.js

@@ -0,0 +1,198 @@
+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
+ */
+
+/**
+ * Generic base class for managing hooks with configurable event types.
+ * Provides common functionality for hook registration, execution, and lifecycle management.
+ * Designed to be extended by specific implementations.
+ *
+ * Browser version: Requires pre-instantiated hooks. File-based loading is not supported.
+ */
+export default class ActionHooks {
+  /** @type {HookModule|null} */
+  #hooks = null
+  /** @type {string|null} */
+  #actionKind = null
+  /** @type {number} */
+  #timeout = 1_000 // Default 1 second timeout
+  /** @type {DebugFn|null} */
+  #debug = null
+
+  /**
+   * Creates a new ActionHook instance.
+   *
+   * @param {ActionHooksConfig} config Configuration values describing how to load the hooks.
+   */
+  constructor({actionKind, hooks, hookTimeout = 1_000, debug}) {
+    this.#actionKind = actionKind
+    this.#hooks = hooks
+    this.#timeout = hookTimeout
+    this.#debug = debug
+  }
+
+  /**
+   * Gets the action identifier.
+   *
+   * @returns {string} Action identifier or instance
+   */
+  get actionKind() {
+    return this.#actionKind
+  }
+
+  /**
+   * Gets the loaded hooks object.
+   *
+   * @returns {object|null} Hooks object or null if not loaded
+   */
+  get hooks() {
+    return this.#hooks
+  }
+
+  /**
+   * Gets the hook execution timeout in milliseconds.
+   *
+   * @returns {number} Timeout in milliseconds
+   */
+  get timeout() {
+    return this.#timeout
+  }
+
+  /**
+   * Gets the setup hook function if available.
+   *
+   * @returns {(args: object) => unknown|null} Setup hook function or null
+   */
+  get setup() {
+    return this.hooks?.setup || null
+  }
+
+  /**
+   * Gets the cleanup hook function if available.
+   *
+   * @returns {(args: object) => unknown|null} Cleanup hook function or null
+   */
+  get cleanup() {
+    return this.hooks?.cleanup || null
+  }
+
+  /**
+   * 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
+   */
+  static async new(config, debug) {
+    debug("Creating new HookManager instance with args: %o", 2, config)
+
+    if(!config.hooks) {
+      debug("No hooks provided (browser mode requires pre-instantiated hooks)", 2)
+
+      return null
+    }
+
+    const instance = new ActionHooks({...config, debug})
+
+    debug("Hooks loaded successfully for %o", 2, instance.actionKind)
+
+    return instance
+  }
+
+  /**
+   * 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.
+   * @returns {Promise<void>}
+   */
+  async callHook(kind, activityName, context) {
+    try {
+      const debug = this.#debug
+      const hooks = this.#hooks
+
+      if(!hooks)
+        return
+
+      const stringActivityName = Data.isType(activityName, "Symbol")
+        ? activityName.description
+        : activityName
+
+      const hookName = this.#getActivityHookName(kind, stringActivityName)
+
+      debug("Looking for hook: %o", 4, hookName)
+
+      const hook = hooks[hookName]
+      if(!hook)
+        return
+
+      debug("Triggering hook: %o", 4, hookName)
+      Valid.type(hook, "Function", `Hook "${hookName}" is not a function`)
+
+      const hookFunction = async() => {
+        debug("Hook function starting execution: %o", 4, hookName)
+
+        const duration = (
+          await Util.time(() => hook.call(this.#hooks, context))
+        ).cost
+
+        debug("Hook function completed successfully: %o, after %oms", 4, hookName, duration)
+      }
+
+      const hookTimeout = this.timeout
+      const expireAsync = (async() => {
+        await Time.after(hookTimeout)
+        throw Sass.new(`Hook ${hookName} execution exceeded timeout of ${hookTimeout}ms`)
+      })()
+
+      try {
+        debug("Starting Promise race for hook: %o", 4, hookName)
+        await Promised.race([
+          hookFunction(),
+          expireAsync
+        ])
+      } 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)
+    }
+  }
+
+  #getActivityHookName(event, activityName) {
+    const name = activityName
+      .split(" ")
+      .map(a => a.trim())
+      .filter(Boolean)
+      .map(a => a
+        .split("")
+        .filter(b => /[\w]/.test(b))
+        .filter(Boolean)
+        .join("")
+      )
+      .map(a => a.toLowerCase())
+      .map((a, i) => i === 0 ? a : Util.capitalize(a))
+      .join("")
+
+    return `${event}$${name}`
+  }
+}

package/src/index.js

@@ -1,6 +1,9 @@
-export {default as ActionBuilder} from "./lib/ActionBuilder.js"
+// Browser-compatible base classes
+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 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"
-export {default as ActionRunner} from "./lib/ActionRunner.js"
-export {default as ActionWrapper} from "./lib/ActionWrapper.js"
-export {default as Activity, ACTIVITY} from "./lib/Activity.js"
-export {default as Piper} from "./lib/Piper.js"