@gobing-ai/ts-infra 0.3.1 → 0.3.2

package/dist/logger.js

@@ -1,99 +1,102 @@
 /**
- * Structured JSON logger with levels (trace/debug/info/warn/error/fatal).
+ * Structured logger for ts-infra, backed by LogTape.
  *
- * No external dependencies — console-based implementation.
+ * LogTape owns level filtering, sink routing, and formatting; this module
+ * adapts LogTape's template-string logger to the ts-infra `Logger` contract
+ * (`method(msg, data?)` + `child(context)`) so call-sites stay backend-agnostic.
+ *
+ * ADR-011: ts-infra must not touch `node:fs`/`process.stderr`. The console sink
+ * is LogTape's own (`getConsoleSink`); the file sink is supplied by the caller
+ * (typically `@gobing-ai/ts-runtime`, which owns FileSystem) via
+ * {@link InitLoggerOptions.fileSink}.
  */
-const LEVEL_ORDER = {
-    trace: 0,
-    debug: 1,
-    info: 2,
-    warn: 3,
-    error: 4,
-    fatal: 5,
-};
-class ConsoleLogger {
-    category;
-    context;
-    constructor(category, context = {}) {
-        this.category = category;
-        this.context = { category, ...context };
-    }
-    log(level, msg, data) {
-        // Read the level dynamically so re-initialization affects cached loggers too.
-        if (LEVEL_ORDER[level] < LEVEL_ORDER[globalLevel])
-            return;
-        if (globalMuted)
-            return;
-        const entry = {
-            level,
-            message: msg,
-            timestamp: new Date().toISOString(),
-            ...this.context,
-            ...data,
-        };
-        const json = JSON.stringify(entry);
-        switch (level) {
-            case 'error':
-            case 'fatal':
-                console.error(json);
-                break;
-            case 'warn':
-                console.warn(json);
-                break;
-            case 'debug':
-            case 'trace':
-                console.debug(json);
-                break;
-            default:
-                console.log(json);
-        }
+import { ConfigError, configure, getConsoleSink, getJsonLinesFormatter, getTextFormatter, getLogger as ltGetLogger, reset, } from '@logtape/logtape';
+/** Root category every ts-infra logger lives under, so one config rule covers them all. */
+const ROOT_CATEGORY = 'app';
+/** Map the ts-infra level name to LogTape's (`warn` → `warning`). */
+function toLogTapeLevel(level) {
+    return level === 'warn' ? 'warning' : level;
+}
+/** Module-level mute flag — LogTape has no global mute, so the adapter gates on it. */
+let muted = false;
+/**
+ * Mute or unmute all logger output. Useful for tests. Gating happens in the
+ * adapter before delegating to LogTape, so muting is synchronous and global.
+ */
+export function setLoggerMuted(value) {
+    muted = value;
+}
+/** Adapter: ts-infra `Logger` over a LogTape logger. */
+class LogTapeLogger {
+    inner;
+    constructor(inner) {
+        this.inner = inner;
     }
     trace(msg, data) {
-        this.log('trace', msg, data);
+        if (!muted)
+            this.inner.trace(msg, data ?? {});
     }
     debug(msg, data) {
-        this.log('debug', msg, data);
+        if (!muted)
+            this.inner.debug(msg, data ?? {});
     }
     info(msg, data) {
-        this.log('info', msg, data);
+        if (!muted)
+            this.inner.info(msg, data ?? {});
     }
     warn(msg, data) {
-        this.log('warn', msg, data);
+        if (!muted)
+            this.inner.warn(msg, data ?? {});
     }
     error(msg, data) {
-        this.log('error', msg, data);
+        if (!muted)
+            this.inner.error(msg, data ?? {});
     }
     fatal(msg, data) {
-        this.log('fatal', msg, data);
+        if (!muted)
+            this.inner.fatal(msg, data ?? {});
     }
     child(context) {
-        return new ConsoleLogger(this.category, { ...this.context, ...context });
+        return new LogTapeLogger(this.inner.with(context));
     }
 }
-const loggers = new Map();
-let globalLevel = 'info';
-let globalMuted = false;
 /**
- * Mute or unmute all logger console output. Useful for tests.
- */
-export function setLoggerMuted(muted) {
-    globalMuted = muted;
-}
-/**
- * Get or create a logger for the given category.
+ * Get a logger for the given category. Categories are nested under the
+ * `app` root so a single `initializeLogger` rule configures them all.
  */
 export function getLogger(category) {
-    const existing = loggers.get(category);
-    if (existing)
-        return existing;
-    const logger = new ConsoleLogger(category);
-    loggers.set(category, logger);
-    return logger;
+    return new LogTapeLogger(ltGetLogger([ROOT_CATEGORY, category]));
 }
 /**
- * Initialize the logger subsystem with a minimum log level.
+ * Configure LogTape with console and/or file sinks. Call once at startup;
+ * safe to call again to reconfigure — the prior config is reset first so the
+ * latest call wins (LogTape throws `ConfigError` on double-configure otherwise).
  */
-export function initializeLogger(level = 'info') {
-    globalLevel = level;
-    loggers.clear();
+export async function initializeLogger(options = {}) {
+    const { level = 'info', console: enableConsole = true, fileSink, json = true } = options;
+    const lowestLevel = toLogTapeLevel(level);
+    const formatter = json ? getJsonLinesFormatter() : getTextFormatter();
+    const sinks = {};
+    if (enableConsole) {
+        sinks.console = getConsoleSink({ formatter });
+    }
+    if (fileSink) {
+        sinks.file = (record) => {
+            fileSink(formatter(record));
+        };
+    }
+    await reset();
+    try {
+        await configure({
+            sinks,
+            loggers: [
+                { category: [ROOT_CATEGORY], lowestLevel, sinks: Object.keys(sinks) },
+                { category: ['logtape', 'meta'], lowestLevel: 'warning', sinks: [] },
+            ],
+        });
+    }
+    catch (error) {
+        if (!(error instanceof ConfigError))
+            throw error;
+    }
 }

package/dist/scheduler/action.d.ts

@@ -1,5 +1,101 @@
 /**
- * Scheduler action type re-export.
+ * Named scheduler actions and a registry, plus built-in actions.
+ *
+ * Opt-in by design: `createDefaultRegistry` only auto-registers the side-effect-
+ * free `LogAction`. Actions with side effects (`QueueStatsAction` needs a DAO
+ * provider, `HealthPingAction` needs a file writer) are included only when their
+ * dependency is supplied — downstream code decides what to enable.
  */
+import type { EventBus } from '../event-bus/event-bus';
+import type { QueueEvents } from '../events';
+import type { QueueStats } from '../job-queue/types';
+import type { ScheduledAction } from './types';
+/** Lazily provides a DAO with `getStats()`, deferred to execution time. */
+export type QueueStatsDaoProvider = () => Promise<{
+    getStats(): Promise<QueueStats>;
+}>;
+/**
+ * Minimal writer for {@link HealthPingAction}. ADR-011: ts-infra does not touch
+ * `node:fs`; the caller injects a writer (e.g. ts-runtime `FileSystem`).
+ */
+export interface HealthPingWriter {
+    /** Write `content` to `path`, replacing any existing file. */
+    writeFile(path: string, content: string): void | Promise<void>;
+}
+/**
+ * A named action invokable by the scheduler. Registered in an
+ * {@link ActionRegistry} and resolved by name; `execute()` matches the
+ * adapter's no-arg {@link ScheduledAction} signature.
+ */
+export interface SchedulerAction {
+    /** Unique action name registered in the registry. */
+    readonly name: string;
+    /** Execute the action. */
+    execute(): Promise<void>;
+}
+/** Bridge a {@link SchedulerAction} to a plain {@link ScheduledAction} for adapter registration. */
+export declare function toScheduledAction(action: SchedulerAction): ScheduledAction;
+/**
+ * Registry of named {@link SchedulerAction} instances, resolved at scheduler
+ * startup. Duplicate names are rejected.
+ */
+export declare class ActionRegistry {
+    private readonly map;
+    constructor(actions?: SchedulerAction[]);
+    /** Register an action. @throws if the name is already registered. */
+    register(action: SchedulerAction): void;
+    /** Look up an action by name. */
+    get(name: string): SchedulerAction | undefined;
+    /** Whether an action with the given name exists. */
+    has(name: string): boolean;
+    /** All registered action names. */
+    names(): string[];
+}
+/** Logs a structured info message on every invocation. Registered as `"log"`. */
+export declare class LogAction implements SchedulerAction {
+    readonly name: string;
+    constructor(name?: string);
+    execute(): Promise<void>;
+}
+/**
+ * Queries the queue DAO for stats and logs them; emits `queue.stats` when a
+ * system bus is provided. Registered as `"queue-stats"`.
+ */
+export declare class QueueStatsAction implements SchedulerAction {
+    private readonly daoProvider;
+    private readonly systemBus;
+    readonly name = "queue-stats";
+    constructor(daoProvider: QueueStatsDaoProvider, systemBus?: EventBus<QueueEvents> | null);
+    execute(): Promise<void>;
+}
+/**
+ * Writes a timestamped heartbeat file on every invocation. Registered as
+ * `"health-ping"`. File I/O is delegated to an injected {@link HealthPingWriter}.
+ */
+export declare class HealthPingAction implements SchedulerAction {
+    private readonly writer;
+    private readonly filePath;
+    readonly name = "health-ping";
+    constructor(writer: HealthPingWriter, filePath?: string);
+    execute(): Promise<void>;
+}
+/** Options for {@link createDefaultRegistry}. */
+export interface CreateDefaultRegistryOptions {
+    /** DAO provider for `QueueStatsAction`. Omit to exclude that action. */
+    queueStatsDaoProvider?: QueueStatsDaoProvider;
+    /** Writer for `HealthPingAction`. Omit to exclude that action. */
+    healthPingWriter?: HealthPingWriter;
+    /** File path for `HealthPingAction`. Default `"data/scheduler-heartbeat.json"`. */
+    healthPingPath?: string;
+    /** System bus forwarded to `QueueStatsAction` for `queue.stats` events. */
+    systemBus?: EventBus<QueueEvents> | null;
+}
+/**
+ * Create an {@link ActionRegistry} with the built-in actions. Only `LogAction`
+ * is always present (no side effects); `QueueStatsAction` and `HealthPingAction`
+ * are included only when their dependency (`queueStatsDaoProvider` /
+ * `healthPingWriter`) is supplied — so nothing with side effects is auto-wired.
+ */
+export declare function createDefaultRegistry(options?: CreateDefaultRegistryOptions): ActionRegistry;
 export type { ScheduledAction } from './types';
 //# sourceMappingURL=action.d.ts.map

package/dist/scheduler/action.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../../src/scheduler/action.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../../src/scheduler/action.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAI/C,2EAA2E;AAC3E,MAAM,MAAM,qBAAqB,GAAG,MAAM,OAAO,CAAC;IAAE,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC,CAAA;CAAE,CAAC,CAAC;AAEvF;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B,8DAA8D;IAC9D,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,oGAAoG;AACpG,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAE1E;AAED;;;GAGG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAsC;gBAE9C,OAAO,CAAC,EAAE,eAAe,EAAE;IAMvC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAOvC,iCAAiC;IACjC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAI9C,oDAAoD;IACpD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,mCAAmC;IACnC,KAAK,IAAI,MAAM,EAAE;CAGpB;AAED,iFAAiF;AACjF,qBAAa,SAAU,YAAW,eAAe;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,SAAQ;IAIlB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAGjC;AAED;;;GAGG;AACH,qBAAa,gBAAiB,YAAW,eAAe;IAIhD,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ9B,QAAQ,CAAC,IAAI,iBAAiB;gBAGT,WAAW,EAAE,qBAAqB,EAClC,SAAS,GAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,IAAW;IAG7D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAMjC;AAED;;;GAGG;AACH,qBAAa,gBAAiB,YAAW,eAAe;IAIhD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJ7B,QAAQ,CAAC,IAAI,iBAAiB;gBAGT,MAAM,EAAE,gBAAgB,EACxB,QAAQ,SAAkC;IAGzD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAOjC;AAED,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IACzC,wEAAwE;IACxE,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC;CAC5C;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,4BAAiC,GAAG,cAAc,CAShG;AAED,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC"}

package/dist/scheduler/action.js

@@ -0,0 +1,111 @@
+/**
+ * Named scheduler actions and a registry, plus built-in actions.
+ *
+ * Opt-in by design: `createDefaultRegistry` only auto-registers the side-effect-
+ * free `LogAction`. Actions with side effects (`QueueStatsAction` needs a DAO
+ * provider, `HealthPingAction` needs a file writer) are included only when their
+ * dependency is supplied — downstream code decides what to enable.
+ */
+import { getLogger } from '../logger.js';
+const logger = getLogger('scheduler.action');
+/** Bridge a {@link SchedulerAction} to a plain {@link ScheduledAction} for adapter registration. */
+export function toScheduledAction(action) {
+    return () => action.execute();
+}
+/**
+ * Registry of named {@link SchedulerAction} instances, resolved at scheduler
+ * startup. Duplicate names are rejected.
+ */
+export class ActionRegistry {
+    map = new Map();
+    constructor(actions) {
+        if (actions) {
+            for (const action of actions)
+                this.register(action);
+        }
+    }
+    /** Register an action. @throws if the name is already registered. */
+    register(action) {
+        if (this.map.has(action.name)) {
+            throw new Error(`Duplicate scheduler action name: "${action.name}"`);
+        }
+        this.map.set(action.name, action);
+    }
+    /** Look up an action by name. */
+    get(name) {
+        return this.map.get(name);
+    }
+    /** Whether an action with the given name exists. */
+    has(name) {
+        return this.map.has(name);
+    }
+    /** All registered action names. */
+    names() {
+        return [...this.map.keys()];
+    }
+}
+/** Logs a structured info message on every invocation. Registered as `"log"`. */
+export class LogAction {
+    name;
+    constructor(name = 'log') {
+        this.name = name;
+    }
+    async execute() {
+        logger.info('Scheduled action executed', { action: this.name });
+    }
+}
+/**
+ * Queries the queue DAO for stats and logs them; emits `queue.stats` when a
+ * system bus is provided. Registered as `"queue-stats"`.
+ */
+export class QueueStatsAction {
+    daoProvider;
+    systemBus;
+    name = 'queue-stats';
+    constructor(daoProvider, systemBus = null) {
+        this.daoProvider = daoProvider;
+        this.systemBus = systemBus;
+    }
+    async execute() {
+        const dao = await this.daoProvider();
+        const stats = await dao.getStats();
+        logger.info('Queue stats snapshot', { action: this.name, ...stats });
+        this.systemBus?.emit('queue.stats', stats);
+    }
+}
+/**
+ * Writes a timestamped heartbeat file on every invocation. Registered as
+ * `"health-ping"`. File I/O is delegated to an injected {@link HealthPingWriter}.
+ */
+export class HealthPingAction {
+    writer;
+    filePath;
+    name = 'health-ping';
+    constructor(writer, filePath = 'data/scheduler-heartbeat.json') {
+        this.writer = writer;
+        this.filePath = filePath;
+    }
+    async execute() {
+        const content = JSON.stringify({
+            lastRun: new Date().toISOString(),
+            jobName: this.name,
+        });
+        await this.writer.writeFile(this.filePath, content);
+    }
+}
+/**
+ * Create an {@link ActionRegistry} with the built-in actions. Only `LogAction`
+ * is always present (no side effects); `QueueStatsAction` and `HealthPingAction`
+ * are included only when their dependency (`queueStatsDaoProvider` /
+ * `healthPingWriter`) is supplied — so nothing with side effects is auto-wired.
+ */
+export function createDefaultRegistry(options = {}) {
+    const actions = [new LogAction()];
+    if (options.queueStatsDaoProvider) {
+        actions.push(new QueueStatsAction(options.queueStatsDaoProvider, options.systemBus ?? null));
+    }
+    if (options.healthPingWriter) {
+        actions.push(new HealthPingAction(options.healthPingWriter, options.healthPingPath));
+    }
+    return new ActionRegistry(actions);
+}

package/dist/scheduler/cloudflare.d.ts

@@ -7,6 +7,12 @@ interface CfScheduledEvent {
 interface CfEventContext {
     waitUntil(promise: Promise<unknown>): void;
 }
+/**
+ * Scheduler adapter for Cloudflare Workers Cron Triggers.
+ *
+ * Register cron→action pairs, then call {@link CloudflareSchedulerAdapter.handleScheduledEvent}
+ * from the Worker's `scheduled()` export.
+ */
 export declare class CloudflareSchedulerAdapter implements SchedulerAdapter {
     private readonly entries;
     constructor();

package/dist/scheduler/cloudflare.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../../src/scheduler/cloudflare.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEjE,UAAU,gBAAgB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED,UAAU,cAAc;IACpB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED,qBAAa,0BAA2B,YAAW,gBAAgB;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;;IAI9D,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IAI/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;OAGG;IACH,oBAAoB,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI;CAY3E"}
+{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../../src/scheduler/cloudflare.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEjE,UAAU,gBAAgB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED,UAAU,cAAc;IACpB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED;;;;;GAKG;AACH,qBAAa,0BAA2B,YAAW,gBAAgB;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;;IAI9D,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IAI/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;OAGG;IACH,oBAAoB,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI;CAY3E"}

package/dist/scheduler/cloudflare.js

@@ -3,6 +3,12 @@
  * Uses minimal local type declarations — no @cloudflare/workers-types dependency.
  */
 import { getSchedulerJobExecutedTotal, getSchedulerJobFailedTotal } from '../telemetry/metrics.js';
+/**
+ * Scheduler adapter for Cloudflare Workers Cron Triggers.
+ *
+ * Register cron→action pairs, then call {@link CloudflareSchedulerAdapter.handleScheduledEvent}
+ * from the Worker's `scheduled()` export.
+ */
 export class CloudflareSchedulerAdapter {
     entries = new Map();
     constructor() { }

package/dist/scheduler/factory.d.ts

@@ -1,7 +1,9 @@
 import type { ScheduledAction, SchedulerAdapter } from './types';
+/** Set the runtime scheduler adapter. Call before {@link initScheduler}. */
 export declare function setSchedulerAdapter(adapter: SchedulerAdapter): void;
 /** Reset the scheduler adapter singleton. For testing. */
 export declare function resetSchedulerAdapter(): void;
+/** Get the currently configured scheduler adapter, or `undefined` if not set. */
 export declare function getSchedulerAdapter(): SchedulerAdapter | undefined;
 /**
  * Initialize the scheduler adapter and register cron entries.

package/dist/scheduler/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/scheduler/factory.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAIjE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAEnE;AAED,0DAA0D;AAC1D,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,SAAS,CAElE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,GAAG,gBAAgB,CAa9F"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/scheduler/factory.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAIjE,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAEnE;AAED,0DAA0D;AAC1D,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,SAAS,CAElE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,GAAG,gBAAgB,CAa9F"}

package/dist/scheduler/factory.js

@@ -3,6 +3,7 @@
  */
 import { NoopSchedulerAdapter } from './noop.js';
 let runtimeAdapter;
+/** Set the runtime scheduler adapter. Call before {@link initScheduler}. */
 export function setSchedulerAdapter(adapter) {
     runtimeAdapter = adapter;
 }
@@ -10,6 +11,7 @@ export function setSchedulerAdapter(adapter) {
 export function resetSchedulerAdapter() {
     runtimeAdapter = undefined;
 }
+/** Get the currently configured scheduler adapter, or `undefined` if not set. */
 export function getSchedulerAdapter() {
     return runtimeAdapter;
 }

package/dist/scheduler/index.d.ts

@@ -1,6 +1,6 @@
-export { CloudflareSchedulerAdapter } from './cloudflare';
+export { ActionRegistry, type CreateDefaultRegistryOptions, createDefaultRegistry, HealthPingAction, type HealthPingWriter, LogAction, QueueStatsAction, type QueueStatsDaoProvider, type SchedulerAction, toScheduledAction, } from './action';
 export { getSchedulerAdapter, initScheduler, resetSchedulerAdapter, setSchedulerAdapter } from './factory';
-export { NodeSchedulerAdapter } from './node';
 export { NoopSchedulerAdapter } from './noop';
 export type { ScheduledAction, SchedulerAdapter } from './types';
+export { wrapScheduledHandler } from './wrap-handler';
 //# sourceMappingURL=index.d.ts.map

package/dist/scheduler/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scheduler/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC3G,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scheduler/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,cAAc,EACd,KAAK,4BAA4B,EACjC,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,SAAS,EACT,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,iBAAiB,GACpB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC3G,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/scheduler/index.js

@@ -1,4 +1,4 @@
-export { CloudflareSchedulerAdapter } from './cloudflare.js';
+export { ActionRegistry, createDefaultRegistry, HealthPingAction, LogAction, QueueStatsAction, toScheduledAction, } from './action.js';
 export { getSchedulerAdapter, initScheduler, resetSchedulerAdapter, setSchedulerAdapter } from './factory.js';
-export { NodeSchedulerAdapter } from './node.js';
 export { NoopSchedulerAdapter } from './noop.js';
+export { wrapScheduledHandler } from './wrap-handler.js';

package/dist/scheduler/node.d.ts

@@ -1,4 +1,8 @@
 import type { ScheduledAction, SchedulerAdapter } from './types';
+/**
+ * Scheduler adapter for Node.js using a setInterval-based approach.
+ * No external cron library dependency — cron expressions are parsed minimally.
+ */
 export declare class NodeSchedulerAdapter implements SchedulerAdapter {
     private readonly entries;
     private running;

package/dist/scheduler/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/scheduler/node.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AA6BjE,qBAAa,oBAAqB,YAAW,gBAAgB;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,OAAO,CAAS;;IAIxB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IAU/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B,OAAO,CAAC,UAAU;YAOJ,gBAAgB;CAYjC"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/scheduler/node.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AA6BjE;;;GAGG;AACH,qBAAa,oBAAqB,YAAW,gBAAgB;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,OAAO,CAAS;;IAIxB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IAU/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B,OAAO,CAAC,UAAU;YAOJ,gBAAgB;CAYjC"}

package/dist/scheduler/node.js

@@ -21,6 +21,10 @@ function parseInterval(cron) {
     }
     return 60_000; // fallback: every minute
 }
+/**
+ * Scheduler adapter for Node.js using a setInterval-based approach.
+ * No external cron library dependency — cron expressions are parsed minimally.
+ */
 export class NodeSchedulerAdapter {
     entries = [];
     running = false;

package/dist/scheduler/noop.d.ts

@@ -2,6 +2,7 @@
  * No-op scheduler adapter for testing and environments without scheduling.
  */
 import type { ScheduledAction, SchedulerAdapter } from './types';
+/** Scheduler adapter that discards all registrations — for testing and environments without scheduling. */
 export declare class NoopSchedulerAdapter implements SchedulerAdapter {
     constructor();
     register(_cron: string, _action: ScheduledAction): void;

package/dist/scheduler/noop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"noop.d.ts","sourceRoot":"","sources":["../../src/scheduler/noop.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEjE,qBAAa,oBAAqB,YAAW,gBAAgB;;IAGzD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI;IAIjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG9B"}
+{"version":3,"file":"noop.d.ts","sourceRoot":"","sources":["../../src/scheduler/noop.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEjE,2GAA2G;AAC3G,qBAAa,oBAAqB,YAAW,gBAAgB;;IAGzD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI;IAIjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG9B"}

package/dist/scheduler/noop.js

@@ -1,3 +1,4 @@
+/** Scheduler adapter that discards all registrations — for testing and environments without scheduling. */
 export class NoopSchedulerAdapter {
     constructor() { }
     register(_cron, _action) {

package/dist/scheduler/wrap-handler.d.ts

@@ -0,0 +1,18 @@
+import type { EventBus } from '../event-bus/event-bus';
+import type { SchedulerEvents } from '../events';
+import type { ScheduledAction } from './types';
+/**
+ * Wrap a scheduled action with OTel tracing, duration measurement, and
+ * `scheduler.job.executed` event emission.
+ *
+ * Composes *on top of* the adapter's inline metrics (executed/failed/duration
+ * counters live in the Node/Cloudflare adapters) — this wrapper adds the named
+ * tracing span and the lifecycle event, neither of which the adapters provide.
+ * Opt-in: wrap an action before registering it when you want that visibility.
+ *
+ * @param name - Job name, surfaced as `scheduler.job_name` on the span/event.
+ * @param action - The action to wrap (new no-arg `ScheduledAction` signature).
+ * @param systemBus - Optional bus to emit `scheduler.job.executed` on.
+ */
+export declare function wrapScheduledHandler(name: string, action: ScheduledAction, systemBus?: EventBus<SchedulerEvents> | null): ScheduledAction;
+//# sourceMappingURL=wrap-handler.d.ts.map

package/dist/scheduler/wrap-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-handler.d.ts","sourceRoot":"","sources":["../../src/scheduler/wrap-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAChC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,eAAe,EACvB,SAAS,CAAC,EAAE,QAAQ,CAAC,eAAe,CAAC,GAAG,IAAI,GAC7C,eAAe,CA2BjB"}

package/dist/scheduler/wrap-handler.js

@@ -0,0 +1,41 @@
+import { addSpanAttributes, addSpanEvent, traceAsync } from '../telemetry/tracing.js';
+/**
+ * Wrap a scheduled action with OTel tracing, duration measurement, and
+ * `scheduler.job.executed` event emission.
+ *
+ * Composes *on top of* the adapter's inline metrics (executed/failed/duration
+ * counters live in the Node/Cloudflare adapters) — this wrapper adds the named
+ * tracing span and the lifecycle event, neither of which the adapters provide.
+ * Opt-in: wrap an action before registering it when you want that visibility.
+ *
+ * @param name - Job name, surfaced as `scheduler.job_name` on the span/event.
+ * @param action - The action to wrap (new no-arg `ScheduledAction` signature).
+ * @param systemBus - Optional bus to emit `scheduler.job.executed` on.
+ */
+export function wrapScheduledHandler(name, action, systemBus) {
+    return async () => {
+        const startTime = performance.now();
+        return traceAsync('scheduler.job', async (span) => {
+            addSpanAttributes({ 'scheduler.job_name': name });
+            let execError;
+            try {
+                await action();
+            }
+            catch (error) {
+                execError = error instanceof Error ? error.message : String(error);
+                addSpanEvent('scheduler.job.error', { 'scheduler.error': execError });
+                span.setStatus({ code: 2, message: execError }); // ERROR
+                throw error;
+            }
+            finally {
+                const durationMs = Math.round(performance.now() - startTime);
+                addSpanAttributes({ 'scheduler.duration_ms': durationMs });
+                systemBus?.emit('scheduler.job.executed', {
+                    name,
+                    durationMs,
+                    ...(execError !== undefined ? { error: execError } : {}),
+                });
+            }
+        });
+    };
+}

package/dist/scheduler-cloudflare.d.ts

@@ -0,0 +1,2 @@
+export { CloudflareSchedulerAdapter } from './scheduler/cloudflare';
+//# sourceMappingURL=scheduler-cloudflare.d.ts.map

package/dist/scheduler-cloudflare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler-cloudflare.d.ts","sourceRoot":"","sources":["../src/scheduler-cloudflare.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/scheduler-cloudflare.js

@@ -0,0 +1 @@
+export { CloudflareSchedulerAdapter } from './scheduler/cloudflare.js';

package/dist/scheduler-node.d.ts

@@ -0,0 +1,2 @@
+export { NodeSchedulerAdapter } from './scheduler/node';
+//# sourceMappingURL=scheduler-node.d.ts.map

package/dist/scheduler-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler-node.d.ts","sourceRoot":"","sources":["../src/scheduler-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/scheduler-node.js

@@ -0,0 +1 @@
+export { NodeSchedulerAdapter } from './scheduler/node.js';

package/dist/telemetry/config.d.ts

@@ -1,6 +1,10 @@
 /**
  * Telemetry configuration interface.
  */
+/**
+ * Full telemetry configuration: master enable switch, service name,
+ * environment, and debug-level DB statement capture.
+ */
 export interface TelemetryConfig {
     /** Master switch — when false, all tracing degrades to no-ops. */
     enabled: boolean;

package/dist/telemetry/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/telemetry/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,eAAe;IAC5B,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;OAQG;IACH,gBAAgB,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACnC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAQD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,GAAE,sBAA2B,GAAG,eAAe,CAU9F"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/telemetry/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC5B,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;OAQG;IACH,gBAAgB,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACnC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAQD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,GAAE,sBAA2B,GAAG,eAAe,CAU9F"}