@adonis-agora/durable 0.3.0 → 0.5.0

package/dist/src/workflow-ref.js

@@ -6,20 +6,51 @@
  * string stays available for the cross-runtime case.
  */
 /**
- * The symbol the `@Workflow` decorator stamps a workflow's registered name onto, so a class ref can
- * be resolved back to its name. A global-registry symbol (`Symbol.for`) so it survives duplicate
+ * The symbol the `@Workflow` decorator stamps the full options onto (name + version + tags …), so
+ * auto-discovery can register the class against the engine and a class ref can be resolved back to
+ * its name via {@link workflowName}. A global-registry symbol (`Symbol.for`) so it survives duplicate
  * copies of this package in a dependency tree.
  */
-export const WORKFLOW_NAME_KEY = Symbol.for('@agora/durable:workflow-name');
+export const WORKFLOW_META_KEY = Symbol.for('@agora/durable:workflow-meta');
+/**
+ * Class decorator marking a class as a durable workflow. Stamps the full options (name + version +
+ * tags …) so a class ref resolves via {@link workflowName} and the provider's `app/workflows`
+ * auto-discovery can register it on the engine — no manual `engine.register(...)`. The class must
+ * expose `run(ctx, input)`; that method becomes the workflow body.
+ *
+ * ```ts
+ * @Workflow({ name: 'order', version: '1' })
+ * export default class OrderWorkflow {
+ *   async run(ctx: WorkflowCtx, input: { id: string }) { ... }
+ * }
+ * ```
+ */
+export function Workflow(options) {
+    return (target) => {
+        const meta = { ...options, version: options.version ?? '1' };
+        Object.defineProperty(target, WORKFLOW_META_KEY, {
+            value: meta,
+            enumerable: false,
+            configurable: true,
+        });
+        return target;
+    };
+}
+/** Read the {@link WorkflowMeta} a `@Workflow` decorator stamped on a class, or `undefined`. */
+export function workflowMeta(target) {
+    if (typeof target !== 'function')
+        return undefined;
+    return target[WORKFLOW_META_KEY];
+}
 /**
  * Resolve a {@link WorkflowRef} to its registered workflow name: a string is returned as-is; a
- * `@Workflow` class is resolved via the name the decorator stamped on it. Throws if a class was
- * never decorated (so it carries no registered name).
+ * `@Workflow` class is resolved via the name the decorator stamped in its metadata. Throws if a
+ * class was never decorated (so it carries no registered name).
  */
 export function workflowName(ref) {
     if (typeof ref === 'string')
         return ref;
-    const name = ref[WORKFLOW_NAME_KEY];
+    const name = workflowMeta(ref)?.name;
     if (!name) {
         throw new Error(`workflow class ${ref.name} has no registered name — is it decorated with @Workflow({ name })?`);
     }

package/dist/src/workflow-ref.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-ref.js","sourceRoot":"","sources":["../../src/workflow-ref.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAkB,MAAM,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;AAgC3F;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,GAAgB;IAC3C,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC;IACxC,MAAM,IAAI,GAAI,GAAwC,CAAC,iBAAiB,CAAC,CAAC;IAC1E,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CACb,kBAAkB,GAAG,CAAC,IAAI,qEAAqE,CAChG,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"workflow-ref.js","sourceRoot":"","sources":["../../src/workflow-ref.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAkB,MAAM,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;AAqB3F;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAwB;IAC/C,OAAO,CACL,MAAS,EACN,EAAE;QACL,MAAM,IAAI,GAAiB,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,GAAG,EAAE,CAAC;QAC3E,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,iBAAiB,EAAE;YAC/C,KAAK,EAAE,IAAI;YACX,UAAU,EAAE,KAAK;YACjB,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,YAAY,CAAC,MAAe;IAC1C,IAAI,OAAO,MAAM,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC;IACnD,OAAQ,MAAiD,CAAC,iBAAiB,CAAC,CAAC;AAC/E,CAAC;AAgCD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,GAAgB;IAC3C,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC;IACxC,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;IACrC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CACb,kBAAkB,GAAG,CAAC,IAAI,qEAAqE,CAChG,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/stubs/config/durable.stub

@@ -8,6 +8,10 @@ import { defineConfig, transports } from '@adonis-agora/durable'
  * maps below; each driver's peer dependency is imported lazily, only when selected. The default is
  * the in-process `memory` transport + the in-memory store — single-process, no extra infrastructure.
  *
+ * For a single-process PRODUCTION app with NO external infra, select the `event-emitter` transport:
+ * step handlers run in this same process over a Node EventEmitter (no DB, no Redis, no broker). The
+ * `memory` transport is test-only.
+ *
  * For cross-process / production, select the `queue` (@adonisjs/queue) or `db` (@adonisjs/lucid)
  * transport, and the `lucid` store, then run `node ace migration:run`:
  *
@@ -17,7 +21,8 @@ import { defineConfig, transports } from '@adonis-agora/durable'
  * export default defineConfig({
  *   transport: 'queue',
  *   transports: {
- *     memory: transports.memory(),
+ *     // single-process production, no external infra:
+ *     'event-emitter': transports.eventEmitter(),
  *     // `connection` names an adapter from config/queue.ts (configure @adonisjs/queue first):
  *     queue: transports.queue({ connection: 'redis', group: 'durable' }),
  *     db: transports.db(),

package/dist/stubs/make/workflow/main.stub

@@ -0,0 +1,22 @@
+{{#var workflowName = string(entity.name).pascalCase().toString()}}
+{{#var workflowFileName = string(entity.name).snakeCase().removeSuffix('workflow').toString() + '_workflow'}}
+{{#var registeredName = string(entity.name).snakeCase().removeSuffix('workflow').toString()}}
+{{{
+  exports({
+    to: app.makePath('app/workflows', entity.path, workflowFileName + '.ts')
+  })
+}}}
+import { Workflow } from '@adonis-agora/durable'
+import type { WorkflowCtx } from '@adonis-agora/durable'
+
+interface {{ workflowName }}Input {
+  // Define your workflow input here
+}
+
+@Workflow({ name: '{{ registeredName }}', version: '1' })
+export default class {{ workflowName }}Workflow {
+  async run(ctx: WorkflowCtx, input: {{ workflowName }}Input) {
+    // Your workflow logic here — compose ctx.step / ctx.call / ctx.child / ctx.sleep …
+    return input
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/durable",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Durable cross-app workflows for AdonisJS — deterministic replay engine, AdonisJS binding, ace commands, dashboard, OpenTelemetry, Telescope, testing harness and Redis admission, all in one package. Part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {
@@ -53,6 +53,11 @@
       "import": "./dist/src/testing-kit/index.js",
       "default": "./dist/src/testing-kit/index.js"
     },
+    "./hooks/workflows": {
+      "types": "./dist/src/hooks/workflows.d.ts",
+      "import": "./dist/src/hooks/workflows.js",
+      "default": "./dist/src/hooks/workflows.js"
+    },
     "./admission-redis": {
       "types": "./dist/src/admission-redis/index.d.ts",
       "import": "./dist/src/admission-redis/index.js",
@@ -84,6 +89,7 @@
     "zod": "^3.23.0"
   },
   "peerDependencies": {
+    "@adonisjs/assembler": "^8.4.0",
     "@adonisjs/core": "^7.3.0",
     "@adonisjs/lucid": "^22.4.0",
     "@adonisjs/queue": "^0.6.0",
@@ -94,6 +100,9 @@
     "vitest": "^3.0.0"
   },
   "peerDependenciesMeta": {
+    "@adonisjs/assembler": {
+      "optional": true
+    },
     "@adonisjs/lucid": {
       "optional": true
     },
@@ -151,7 +160,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json && pnpm run copy:stubs",
-    "copy:stubs": "mkdir -p dist/stubs/config dist/stubs/database/migrations dist/assets && cp stubs/config/durable.stub dist/stubs/config/durable.stub && cp stubs/config/durable_dashboard.stub dist/stubs/config/durable_dashboard.stub && cp -r stubs/database/migrations/. dist/stubs/database/migrations/ && cp assets/dashboard.html dist/assets/dashboard.html",
+    "copy:stubs": "mkdir -p dist/stubs/config dist/stubs/database/migrations dist/stubs/make/workflow dist/assets && cp stubs/config/durable.stub dist/stubs/config/durable.stub && cp stubs/config/durable_dashboard.stub dist/stubs/config/durable_dashboard.stub && cp -r stubs/database/migrations/. dist/stubs/database/migrations/ && cp stubs/make/workflow/main.stub dist/stubs/make/workflow/main.stub && cp assets/dashboard.html dist/assets/dashboard.html",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest",
     "typecheck": "tsc -p tsconfig.json --noEmit"