@xeplr/actions 1.3.1 → 1.4.0

package/README.md

@@ -64,7 +64,7 @@ var moved = await actions.runAction(actions.builtins.dbMove, {
 |---|---|
 | `register(def)` / `register(name, def)` | Add an action. Throws without `name` or `execute`, or with a `requires` module that is not installed (`ActionMissingDependencyError`). Re-registering a name replaces it. |
 | `get(name)` / `has(name)` | Look one up. |
-| `list()` | `[{ name, description, inputSchema, outputSchema, requires }]` — serializable, for an actions endpoint. |
+| `list()` | `[{ name, description, inputSchema, outputSchema, requires, event }]` — serializable, for an actions endpoint. `event` is `null` for an ordinary action. |
 | `clear()` | Empty the registry. |
 | `runAction({ name, input, system?, timeoutMs? })` | Run a registered action. Never throws. |
 | `runAction(nameOrDef, input, { system, timeoutMs, metaStore }?)` | Same, by name or with an action module directly. |
@@ -91,6 +91,7 @@ var moved = await actions.runAction(actions.builtins.dbMove, {
 | `outputSchema` | Optional documentation of the return value. |
 | `requires` | Module names checked with `require.resolve` at `register()`. |
 | `execute({ input, system, metaStore })` | Returns (or resolves to) the output. |
+| `event` | Optional. Makes this a **screen function** rather than a step: the event it is written for — `beforeLoad`, `beforeSave`, `afterSave`, `beforeDelete`, `onError` (run by `@xeplr/factory` around a screen's records) or `decide` (run by `@xeplr/workflow-engine` to choose a flow's next step). A screen names one per event and pickers offer only the functions for that event. It is called with the event's context — `execute(ctx)`, not `{ input, system }` — and never as a workflow step. |
 
 ### `runAction` result
 

package/lib/registry.js

@@ -9,8 +9,17 @@
 //     outputSchema : array?     — optional; documents what the action returns
 //     requires     : string[]?  — peer-dep module names checked at register time
 //     execute      : function   — async ({ input, system }) => output
+//     event        : string?    — a SCREEN FUNCTION, not a step: the event it
+//                                 is written for ('beforeSave', 'decide', …).
+//                                 Called with that event's own context instead
+//                                 of { input, system } — see the README.
 //   }
 //
+// One registry for both, because one app registers both and the two readers
+// (a screen's events, a workflow's arrows and steps) live in one process. What
+// an `event` means is the reader's business: this package only keeps it, and
+// lists it, so a picker can offer each event only the functions written for it.
+//
 // Two call forms:
 //   register(name, def)      → traditional
 //   register(def)            → module-export style: `def.name` is used
@@ -33,6 +42,9 @@ function register(nameOrDef, def) {
   if (typeof action.execute !== 'function') {
     throw new Error('register: action "' + action.name + '" must have an `execute` function');
   }
+  if (action.event !== undefined && (typeof action.event !== 'string' || !action.event.trim())) {
+    throw new Error('register: action "' + action.name + '" has an `event` that is not a name — e.g. "beforeSave"');
+  }
 
   // Sanity-check peer deps.
   if (Array.isArray(action.requires)) {
@@ -48,6 +60,7 @@ function register(nameOrDef, def) {
     inputSchema:  Array.isArray(action.inputSchema) ? action.inputSchema : [],
     outputSchema: action.outputSchema || null,
     requires:     Array.isArray(action.requires) ? action.requires.slice() : [],
+    event:        action.event || null,
     execute:      action.execute
   });
 }
@@ -64,7 +77,8 @@ function list() {
       description: def.description,
       inputSchema: def.inputSchema,
       outputSchema: def.outputSchema,
-      requires: def.requires
+      requires: def.requires,
+      event: def.event
     });
   });
   return out;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/actions",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Named-action registry with typed inputs and safe invocation — plus built-in actions for HTTP, DB, files, email, spawn",
   "main": "index.js",
   "files": [