@adonis-agora/durable 0.19.2 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @adonis-agora/durable
 
+## 0.20.0
+
+### Minor Changes
+
+- [#43](https://github.com/DavideCarvalho/adonis-durable/pull/43) [`b4ba291`](https://github.com/DavideCarvalho/adonis-durable/commit/b4ba2916c3e8cdb198e86c60b7aac403df4df3d2) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - New `@Scheduled(...)` class decorator — the decorator form of the colocated `static schedule`. It only stamps `static schedule` on the class; normalization (key defaults, `workflow` fill-in, the `static workflow` requirement) stays in `workflowSchedules`, so both authoring forms behave identically:
+
+  ```ts
+  @Scheduled({ cron: '0 4 * * *', timezone: 'America/Sao_Paulo' })
+  export default class CrawlWorkflow extends BaseWorkflow {
+    static workflow = { name: 'crawl' }
+    async run(ctx: WorkflowCtx) { … }
+  }
+  ```
+
+  Repeated applications and an existing `static schedule` literal compose, accumulating in source order (top decorator first, then the literal). With several schedules on one class, prefer explicit `key`s over the positional `${name}:${i}` defaults — the key is part of the deterministic run id, and reordering declarations would silently re-key them.
+
 ## 0.19.2
 
 ### Patch Changes

package/dist/src/dashboard/index.d.ts

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export declare const VERSION = "0.19.2";
+export declare const VERSION = "0.20.0";
 export { defineConfig, defaultAuthorize, resolveConfig } from './define_config.js';
 export type { AuthorizeHook, DurableDashboardConfig, ResolvedDurableDashboardConfig, } from './define_config.js';
 export { listRuns, getRun, retryRun, redispatchPendingRun, cancelRun, health, ok, } from './handlers.js';

package/dist/src/dashboard/index.js

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export const VERSION = '0.19.2';
+export const VERSION = '0.20.0';
 export { defineConfig, defaultAuthorize, resolveConfig } from './define_config.js';
 export { listRuns, getRun, retryRun, redispatchPendingRun, cancelRun, health, ok, } from './handlers.js';
 export { renderDashboard } from './html.js';

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export declare const VERSION = "0.19.2";
+export declare const VERSION = "0.20.0";
 export * from './admission.js';
 export * from './control-flow-signal.js';
 export * from './duration.js';

package/dist/src/index.js

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export const VERSION = '0.19.2';
+export const VERSION = '0.20.0';
 // --- engine + core primitives -----------------------------------------------
 export * from './admission.js';
 export * from './control-flow-signal.js';

package/dist/src/workflow-ref.d.ts

@@ -6,7 +6,7 @@
  * string stays available for the cross-runtime case.
  */
 import type { SingletonConfig } from './engine.js';
-import type { ScheduledWorkflow } from './scheduler.js';
+import type { ScheduledWorkflow, WorkflowScheduleConfig } from './scheduler.js';
 /** Options for a workflow's `static workflow = { name, version, … }` config (see {@link BaseWorkflow}). */
 export interface WorkflowOptions {
     /** The registered workflow name (the cross-runtime identity, e.g. `order`). */
@@ -54,6 +54,30 @@ export declare function workflowMeta(target: unknown): WorkflowMeta | undefined;
  * (not a registrable workflow) or no `static schedule`.
  */
 export declare function workflowSchedules(target: unknown): ScheduledWorkflow[];
+/**
+ * Class-decorator form of the colocated schedule — the same declaration `static schedule = {...}`
+ * makes, for codebases that prefer decorators:
+ *
+ * ```ts
+ * @Scheduled({ cron: '0 4 * * *', timezone: 'America/Sao_Paulo' })
+ * export default class CrawlWorkflow extends BaseWorkflow {
+ *   static workflow = { name: 'crawl' }
+ *   async run(ctx: WorkflowCtx) { … }
+ * }
+ * ```
+ *
+ * It only stamps `static schedule` on the class — normalization (key defaults, `workflow` fill-in)
+ * stays in {@link workflowSchedules}, so both authoring forms behave identically, including the
+ * requirement of a `static workflow` config (a decorated class without one is not registrable and
+ * its schedules are ignored, same as a bare `static schedule`).
+ *
+ * Composes: repeated `@Scheduled(...)` applications and an existing `static schedule` accumulate.
+ * Decorators apply bottom-up, so each application PREPENDS — the final array reads in **source
+ * order** (top decorator first, then lower ones, then the `static schedule` literal). With several
+ * schedules on one class, prefer explicit `key`s over the positional `${name}:${i}` defaults: the
+ * key is part of the deterministic run id, and reordering declarations would silently re-key them.
+ */
+export declare function Scheduled(config: WorkflowScheduleConfig | WorkflowScheduleConfig[]): ClassDecorator;
 /** Structural shape of a workflow class — its `run(ctx, input)` carries the input/output types. */
 export type WorkflowClass<TInput = unknown, TOutput = unknown> = abstract new (...args: never[]) => {
     run(ctx: never, input: TInput): Promise<TOutput> | TOutput;

package/dist/src/workflow-ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-ref.d.ts","sourceRoot":"","sources":["../../src/workflow-ref.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAA0B,MAAM,gBAAgB,CAAC;AAEhF,2GAA2G;AAC3G,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED,sGAAsG;AACtG,MAAM,WAAW,YAAa,SAAQ,eAAe;IACnD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAOtE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,iBAAiB,EAAE,CAWtE;AAED,mGAAmG;AACnG,MAAM,MAAM,aAAa,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,QAAQ,MACvE,GAAG,IAAI,EAAE,KAAK,EAAE,KACb;IACH,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CAC5D,CAAC;AAEF,yGAAyG;AACzG,MAAM,MAAM,WAAW,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IACvD,MAAM,GACN,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnC,uDAAuD;AACvD,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,SAAS,QAAQ,MACjD,GAAG,IAAI,EAAE,KAAK,EAAE,KACb;IACH,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC;CAC1C,GACG,CAAC,GACD,OAAO,CAAC;AAEZ,gFAAgF;AAChF,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS,QAAQ,MAClD,GAAG,IAAI,EAAE,KAAK,EAAE,KACb;IACH,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC,CAAC;CACxC,GACG,OAAO,CAAC,CAAC,CAAC,GACV,OAAO,CAAC;AAEZ;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CASrD"}
+{"version":3,"file":"workflow-ref.d.ts","sourceRoot":"","sources":["../../src/workflow-ref.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAEhF,2GAA2G;AAC3G,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED,sGAAsG;AACtG,MAAM,WAAW,YAAa,SAAQ,eAAe;IACnD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAOtE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,iBAAiB,EAAE,CAWtE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,sBAAsB,GAAG,sBAAsB,EAAE,GACxD,cAAc,CAUhB;AAED,mGAAmG;AACnG,MAAM,MAAM,aAAa,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,QAAQ,MACvE,GAAG,IAAI,EAAE,KAAK,EAAE,KACb;IACH,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CAC5D,CAAC;AAEF,yGAAyG;AACzG,MAAM,MAAM,WAAW,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IACvD,MAAM,GACN,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnC,uDAAuD;AACvD,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,SAAS,QAAQ,MACjD,GAAG,IAAI,EAAE,KAAK,EAAE,KACb;IACH,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC;CAC1C,GACG,CAAC,GACD,OAAO,CAAC;AAEZ,gFAAgF;AAChF,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS,QAAQ,MAClD,GAAG,IAAI,EAAE,KAAK,EAAE,KACb;IACH,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC,CAAC;CACxC,GACG,OAAO,CAAC,CAAC,CAAC,GACV,OAAO,CAAC;AAEZ;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CASrD"}

package/dist/src/workflow-ref.js

@@ -46,6 +46,37 @@ export function workflowSchedules(target) {
         key: s.key ?? (arr.length > 1 ? `${meta.name}:${i}` : meta.name),
     }));
 }
+/**
+ * Class-decorator form of the colocated schedule — the same declaration `static schedule = {...}`
+ * makes, for codebases that prefer decorators:
+ *
+ * ```ts
+ * @Scheduled({ cron: '0 4 * * *', timezone: 'America/Sao_Paulo' })
+ * export default class CrawlWorkflow extends BaseWorkflow {
+ *   static workflow = { name: 'crawl' }
+ *   async run(ctx: WorkflowCtx) { … }
+ * }
+ * ```
+ *
+ * It only stamps `static schedule` on the class — normalization (key defaults, `workflow` fill-in)
+ * stays in {@link workflowSchedules}, so both authoring forms behave identically, including the
+ * requirement of a `static workflow` config (a decorated class without one is not registrable and
+ * its schedules are ignored, same as a bare `static schedule`).
+ *
+ * Composes: repeated `@Scheduled(...)` applications and an existing `static schedule` accumulate.
+ * Decorators apply bottom-up, so each application PREPENDS — the final array reads in **source
+ * order** (top decorator first, then lower ones, then the `static schedule` literal). With several
+ * schedules on one class, prefer explicit `key`s over the positional `${name}:${i}` defaults: the
+ * key is part of the deterministic run id, and reordering declarations would silently re-key them.
+ */
+export function Scheduled(config) {
+    return (target) => {
+        const cls = target;
+        const existing = cls.schedule === undefined ? [] : Array.isArray(cls.schedule) ? cls.schedule : [cls.schedule];
+        const added = Array.isArray(config) ? config : [config];
+        cls.schedule = [...added, ...existing];
+    };
+}
 /**
  * Resolve a {@link WorkflowRef} to its registered workflow name: a string is returned as-is; a
  * workflow class is resolved via the name on its `static workflow` config. Throws if a class carries

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;AAkCH;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAAe;IAC1C,IAAI,OAAO,MAAM,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC;IACnD,MAAM,MAAM,GAAI,MAAyC,CAAC,QAAQ,CAAC;IACnE,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC5E,OAAO,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,GAAG,EAAE,CAAC;IACvD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAe;IAC/C,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,GAAG,GAAI,MAA2E,CAAC,QAAQ,CAAC;IAClG,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IACpB,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7C,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QACxB,GAAG,CAAC;QACJ,QAAQ,EAAE,IAAI,CAAC,IAAI;QACnB,GAAG,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;KACjE,CAAC,CAAC,CAAC;AACN,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,2EAA2E,CACtG,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;AAkCH;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAAe;IAC1C,IAAI,OAAO,MAAM,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC;IACnD,MAAM,MAAM,GAAI,MAAyC,CAAC,QAAQ,CAAC;IACnE,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC5E,OAAO,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,GAAG,EAAE,CAAC;IACvD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAe;IAC/C,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,GAAG,GAAI,MAA2E,CAAC,QAAQ,CAAC;IAClG,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IACpB,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7C,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QACxB,GAAG,CAAC;QACJ,QAAQ,EAAE,IAAI,CAAC,IAAI;QACnB,GAAG,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;KACjE,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,SAAS,CACvB,MAAyD;IAEzD,OAAO,CAAC,MAAM,EAAE,EAAE;QAChB,MAAM,GAAG,GAAG,MAEX,CAAC;QACF,MAAM,QAAQ,GACZ,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAChG,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACxD,GAAG,CAAC,QAAQ,GAAG,CAAC,GAAG,KAAK,EAAE,GAAG,QAAQ,CAAC,CAAC;IACzC,CAAC,CAAC;AACJ,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,2EAA2E,CACtG,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/durable",
-  "version": "0.19.2",
+  "version": "0.20.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": {