@adonis-agora/durable 0.1.0

package/dist/src/dashboard/html.js

@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+/**
+ * The dashboard HTML, loaded once from the bundled asset. The build copies
+ * `assets/dashboard.html` into `dist/assets/`, so this resolves relative to the
+ * compiled `dist/src/dashboard/html.js`.
+ */
+let template;
+function load() {
+    if (template === undefined) {
+        const assetUrl = new URL('../../assets/dashboard.html', import.meta.url);
+        template = readFileSync(fileURLToPath(assetUrl), 'utf8');
+    }
+    return template;
+}
+/**
+ * Render the dashboard HTML with the JSON API base path injected, so the
+ * single-page client knows where to fetch from regardless of the configured
+ * mount prefix.
+ */
+export function renderDashboard(apiBase) {
+    return load().replaceAll('__API_BASE__', apiBase);
+}
+//# sourceMappingURL=html.js.map

package/dist/src/dashboard/html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.js","sourceRoot":"","sources":["../../../src/dashboard/html.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;GAIG;AACH,IAAI,QAA4B,CAAC;AAEjC,SAAS,IAAI;IACX,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,6BAA6B,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzE,QAAQ,GAAG,YAAY,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,OAAO,IAAI,EAAE,CAAC,UAAU,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;AACpD,CAAC"}

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

@@ -0,0 +1,8 @@
+/** Keep in sync with this package's `version` in package.json. */
+export declare const VERSION = "0.1.0";
+export { defineConfig, defaultAuthorize, resolveConfig } from './define_config.js';
+export type { AuthorizeHook, DurableDashboardConfig, ResolvedDurableDashboardConfig, } from './define_config.js';
+export { listRuns, getRun, retryRun, cancelRun, health, } from './handlers.js';
+export type { ApiRequest, ApiResponse, Deps } from './handlers.js';
+export { renderDashboard } from './html.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/dashboard/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,eAAO,MAAM,OAAO,UAAU,CAAC;AAE/B,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnF,YAAY,EACV,aAAa,EACb,sBAAsB,EACtB,8BAA8B,GAC/B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,SAAS,EACT,MAAM,GACP,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC"}

package/dist/src/dashboard/index.js

@@ -0,0 +1,6 @@
+/** Keep in sync with this package's `version` in package.json. */
+export const VERSION = '0.1.0';
+export { defineConfig, defaultAuthorize, resolveConfig } from './define_config.js';
+export { listRuns, getRun, retryRun, cancelRun, health, } from './handlers.js';
+export { renderDashboard } from './html.js';
+//# sourceMappingURL=index.js.map

package/dist/src/dashboard/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/dashboard/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAMnF,OAAO,EACL,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,SAAS,EACT,MAAM,GACP,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC"}

package/dist/src/define_config.d.ts

@@ -0,0 +1,72 @@
+import type { ControlPlane, RunDispatcher } from './interfaces.js';
+import type { ScheduledWorkflow } from './scheduler.js';
+import { stores } from './stores/factory.js';
+import type { LucidStoreConfig, StoreContext, StoreFactory } from './stores/factory.js';
+import { transports } from './transports/factory.js';
+import type { DbTransportConfig, MemoryTransportConfig, QueueTransportConfig, TransportContext, TransportFactory } from './transports/factory.js';
+/**
+ * Shape of `config/durable.ts`. Everything is optional — by default the engine uses an in-process
+ * state store + transport (single-process, no extra infra). Pick a `transport`/`store` by name from
+ * the `transports`/`stores` maps to run cross-process or persist durably; build the entries with the
+ * {@link transports} / {@link stores} factories so each peer dependency (`@adonisjs/queue`,
+ * `@adonisjs/lucid`) is imported lazily, only when that driver is actually selected.
+ *
+ * ```ts
+ * import { defineConfig, transports, stores } from '@adonis-agora/durable'
+ * import { redis } from '@adonisjs/queue'
+ *
+ * export default defineConfig({
+ *   transport: 'queue',
+ *   transports: {
+ *     memory: transports.memory(),
+ *     queue: transports.queue({ adapter: redis({ host: '127.0.0.1' }), group: 'durable' }),
+ *     db: transports.db({ connection: 'pg' }),
+ *   },
+ *   store: 'lucid',
+ *   stores: {
+ *     lucid: stores.lucid({ connection: 'pg' }),
+ *   },
+ * })
+ * ```
+ */
+export interface DurableConfig {
+    /**
+     * Name of the transport (a key of {@link transports}) the engine dispatches over. Omit for the
+     * in-process transport (single-process, no extra infra).
+     */
+    transport?: string;
+    /** Named transports, built with the {@link transports} factory. */
+    transports?: Record<string, TransportFactory>;
+    /**
+     * Name of the state store (a key of {@link stores}) for runs/checkpoints/timers. Omit for the
+     * in-memory store (single-process).
+     */
+    store?: string;
+    /** Named state stores, built with the {@link stores} factory. */
+    stores?: Record<string, StoreFactory>;
+    /** Cross-instance broadcast for lifecycle events + cancellation. Omit for single-instance. */
+    controlPlane?: ControlPlane;
+    /** Recovery lease duration in ms. Default 30s. */
+    leaseMs?: number;
+    /** Unique id for this engine instance. Defaults to a random id. */
+    instanceId?: string;
+    /** Cap crash-recovery pickups before dead-lettering a poison run. Omit for unlimited. */
+    maxRecoveryAttempts?: number;
+    /** Attempts per saga compensation on run failure. Default 1. */
+    compensationRetries?: number;
+    /** Where a freshly-started run executes. Defaults to in-process (microtask). */
+    runDispatcher?: RunDispatcher;
+    /**
+     * Recurring workflows to start on a schedule (fixed interval via `everyMs`, or cron via `cron` +
+     * `timezone`). The `durable:work` worker loop fires any due windows on every tick (the 5th phase,
+     * after timeouts are swept). `engine.start` is idempotent by each schedule's time-bucket run id, so
+     * racing worker instances start every window **exactly once**. Cron schedules need the optional
+     * `cron-parser` peer dependency. Omit (or leave empty) to register no schedules.
+     */
+    schedules?: ScheduledWorkflow[];
+}
+/** Identity helper giving `config/durable.ts` full type-checking. */
+export declare function defineConfig(config?: DurableConfig): DurableConfig;
+export { transports, stores };
+export type { TransportContext, TransportFactory, MemoryTransportConfig, QueueTransportConfig, DbTransportConfig, StoreContext, StoreFactory, LucidStoreConfig, };
+//# sourceMappingURL=define_config.d.ts.map

package/dist/src/define_config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.d.ts","sourceRoot":"","sources":["../../src/define_config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxF,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC9C;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACtC,8FAA8F;IAC9F,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,gEAAgE;IAChE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,gFAAgF;IAChF,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACjC;AAED,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,MAAM,GAAE,aAAkB,GAAG,aAAa,CAEtE;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AAC9B,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,gBAAgB,GACjB,CAAC"}

package/dist/src/define_config.js

@@ -0,0 +1,8 @@
+import { stores } from './stores/factory.js';
+import { transports } from './transports/factory.js';
+/** Identity helper giving `config/durable.ts` full type-checking. */
+export function defineConfig(config = {}) {
+    return config;
+}
+export { transports, stores };
+//# sourceMappingURL=define_config.js.map

package/dist/src/define_config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.js","sourceRoot":"","sources":["../../src/define_config.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAuErD,qEAAqE;AACrE,MAAM,UAAU,YAAY,CAAC,SAAwB,EAAE;IACrD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC"}

package/dist/src/diagnostics-bridge.d.ts

@@ -0,0 +1,22 @@
+import type { EngineEvent } from './interfaces.js';
+/** The minimal engine surface the bridge needs: a lifecycle-event subscription. */
+export interface DurableEventSource {
+    subscribe(listener: (event: EngineEvent) => void): () => void;
+}
+/**
+ * Bridge every engine lifecycle event onto the `@adonis-agora/diagnostics` bus as `agora:durable:<type>`
+ * (e.g. `agora:durable:run.failed`); the whole {@link EngineEvent} is the payload. The emit
+ * capability is read STRUCTURALLY from its global slot per event — durable never imports or depends
+ * on `@adonis-agora/diagnostics`, and when diagnostics isn't installed the slot is empty and this is an
+ * inert subscription.
+ *
+ * One bridge lights up everything downstream of the diagnostics hub at once: `onDiagnostic('durable')`
+ * subscribers, the Telescope generic watcher (which auto-captures every channel), the cross-process
+ * relays, and the OTel bridge (each event recorded on the active span). `emit` short-circuits on
+ * `hasSubscribers`, so an unsubscribed channel costs nothing, and it never throws back into the
+ * engine. All event types are forwarded verbatim — filtering is the subscriber's job.
+ *
+ * @returns an unsubscribe function that detaches the bridge from the engine.
+ */
+export declare function attachDurableDiagnostics(engine: DurableEventSource): () => void;
+//# sourceMappingURL=diagnostics-bridge.d.ts.map

package/dist/src/diagnostics-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics-bridge.d.ts","sourceRoot":"","sources":["../../src/diagnostics-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC/D;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAK/E"}

package/dist/src/diagnostics-bridge.js

@@ -0,0 +1,25 @@
+/** The `@adonis-agora/diagnostics` emit capability, published on this slot at that package's module load. */
+const EMIT_SLOT = Symbol.for('@agora/diagnostics:emit');
+/**
+ * Bridge every engine lifecycle event onto the `@adonis-agora/diagnostics` bus as `agora:durable:<type>`
+ * (e.g. `agora:durable:run.failed`); the whole {@link EngineEvent} is the payload. The emit
+ * capability is read STRUCTURALLY from its global slot per event — durable never imports or depends
+ * on `@adonis-agora/diagnostics`, and when diagnostics isn't installed the slot is empty and this is an
+ * inert subscription.
+ *
+ * One bridge lights up everything downstream of the diagnostics hub at once: `onDiagnostic('durable')`
+ * subscribers, the Telescope generic watcher (which auto-captures every channel), the cross-process
+ * relays, and the OTel bridge (each event recorded on the active span). `emit` short-circuits on
+ * `hasSubscribers`, so an unsubscribed channel costs nothing, and it never throws back into the
+ * engine. All event types are forwarded verbatim — filtering is the subscriber's job.
+ *
+ * @returns an unsubscribe function that detaches the bridge from the engine.
+ */
+export function attachDurableDiagnostics(engine) {
+    return engine.subscribe((event) => {
+        const emit = globalThis[EMIT_SLOT];
+        if (typeof emit === 'function')
+            emit('durable', event.type, event);
+    });
+}
+//# sourceMappingURL=diagnostics-bridge.js.map

package/dist/src/diagnostics-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics-bridge.js","sourceRoot":"","sources":["../../src/diagnostics-bridge.ts"],"names":[],"mappings":"AAOA,6GAA6G;AAC7G,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAGxD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAA0B;IACjE,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,KAAkB,EAAE,EAAE;QAC7C,MAAM,IAAI,GAAI,UAAsC,CAAC,SAAS,CAAuB,CAAC;QACtF,IAAI,OAAO,IAAI,KAAK,UAAU;YAAE,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/duration.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Parse a human duration to milliseconds. Accepts a number (already ms) or a string like
+ * `'500ms'`, `'30s'`, `'15m'`, `'2h'`, `'7d'`, `'7 days'`.
+ */
+export declare function parseDuration(duration: string | number): number;
+//# sourceMappingURL=duration.d.ts.map

package/dist/src/duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../../src/duration.ts"],"names":[],"mappings":"AAsBA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAS/D"}

package/dist/src/duration.js

@@ -0,0 +1,39 @@
+const UNIT_MS = {
+    ms: 1,
+    s: 1_000,
+    sec: 1_000,
+    second: 1_000,
+    seconds: 1_000,
+    m: 60_000,
+    min: 60_000,
+    minute: 60_000,
+    minutes: 60_000,
+    h: 3_600_000,
+    hr: 3_600_000,
+    hour: 3_600_000,
+    hours: 3_600_000,
+    d: 86_400_000,
+    day: 86_400_000,
+    days: 86_400_000,
+    w: 604_800_000,
+    week: 604_800_000,
+    weeks: 604_800_000,
+};
+/**
+ * Parse a human duration to milliseconds. Accepts a number (already ms) or a string like
+ * `'500ms'`, `'30s'`, `'15m'`, `'2h'`, `'7d'`, `'7 days'`.
+ */
+export function parseDuration(duration) {
+    if (typeof duration === 'number')
+        return duration;
+    const match = duration.trim().match(/^(\d+(?:\.\d+)?)\s*([a-z]+)$/i);
+    if (!match)
+        throw new Error(`invalid duration: ${duration}`);
+    const value = Number(match[1]);
+    const unit = (match[2] ?? '').toLowerCase();
+    const factor = UNIT_MS[unit];
+    if (factor === undefined)
+        throw new Error(`unknown duration unit: ${unit}`);
+    return value * factor;
+}
+//# sourceMappingURL=duration.js.map

package/dist/src/duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.js","sourceRoot":"","sources":["../../src/duration.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,GAA2B;IACtC,EAAE,EAAE,CAAC;IACL,CAAC,EAAE,KAAK;IACR,GAAG,EAAE,KAAK;IACV,MAAM,EAAE,KAAK;IACb,OAAO,EAAE,KAAK;IACd,CAAC,EAAE,MAAM;IACT,GAAG,EAAE,MAAM;IACX,MAAM,EAAE,MAAM;IACd,OAAO,EAAE,MAAM;IACf,CAAC,EAAE,SAAS;IACZ,EAAE,EAAE,SAAS;IACb,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,SAAS;IAChB,CAAC,EAAE,UAAU;IACb,GAAG,EAAE,UAAU;IACf,IAAI,EAAE,UAAU;IAChB,CAAC,EAAE,WAAW;IACd,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,WAAW;CACnB,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,QAAyB;IACrD,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAClD,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACrE,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,QAAQ,EAAE,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,MAAM,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,EAAE,CAAC,CAAC;IAC5E,OAAO,KAAK,GAAG,MAAM,CAAC;AACxB,CAAC"}