@zintrust/core 2.4.5 → 2.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/core",
-  "version": "2.4.5",
+  "version": "2.4.6",
   "description": "Production-grade TypeScript backend framework for JavaScript",
   "homepage": "https://zintrust.com",
   "repository": {

package/src/index.js

@@ -1,11 +1,11 @@
 /**
- * @zintrust/core v2.4.5
+ * @zintrust/core v2.4.6
  *
  * ZinTrust Framework - Production-Grade TypeScript Backend
  * Built for performance, type safety, and exceptional developer experience
  *
  * Build Information:
- *   Built: 2026-06-01T13:37:05.393Z
+ *   Built: 2026-06-01T16:53:34.785Z
  *   Node: >=20.0.0
  *   License: MIT
  *
@@ -21,7 +21,7 @@
  * Available at runtime for debugging and health checks
  */
 export const ZINTRUST_VERSION = '0.1.41';
-export const ZINTRUST_BUILD_DATE = '2026-06-01T13:37:05.359Z'; // Replaced during build
+export const ZINTRUST_BUILD_DATE = '2026-06-01T16:53:34.743Z'; // Replaced during build
 export { Application } from './boot/Application.js';
 export { AwsSigV4 } from './common/index.js';
 export { SignedRequest } from './security/SignedRequest.js';

package/src/scheduler/ScheduleRunner.d.ts

@@ -2,23 +2,37 @@
  * ScheduleRunner
  * Lightweight, zero-dependency schedule runner for long-running runtimes
  */
-import { type ScheduleRunState } from './state/ScheduleStateStore';
+import { type IScheduleStateStore, type ScheduleRunState } from './state/ScheduleStateStore';
 import type { ISchedule, IScheduleKernel } from './types';
+/**
+ * Result of a `runIfDue` invocation.
+ * - `ran: true` → the handler was invoked this call.
+ * - `ran: false` → skipped; `reason` explains why and `nextRunAt` (when present)
+ *   is the epoch-ms timestamp at which the schedule next becomes due.
+ */
+export type RunIfDueResult = Readonly<{
+    ran: boolean;
+    reason?: 'disabled' | 'not-due' | 'no-cadence';
+    nextRunAt?: number;
+    outcome?: 'success' | 'failure';
+}>;
 type ScheduleRunner = {
     register: (schedule: ISchedule) => void;
     start: (kernel?: IScheduleKernel) => void;
     stop: (timeoutMs?: number) => Promise<void>;
     list: () => ISchedule[];
     runOnce: (name: string, kernel?: IScheduleKernel) => Promise<void>;
+    runIfDue: (name: string, kernel?: IScheduleKernel) => Promise<RunIfDueResult>;
     getState: (name: string) => Promise<ScheduleRunState | null>;
     listStates: () => Promise<Array<{
         name: string;
         state: ScheduleRunState;
     }>>;
+    setStore: (store: IScheduleStateStore) => void;
 };
-export declare const create: () => Readonly<ScheduleRunner>;
+export declare const create: (store?: IScheduleStateStore) => Readonly<ScheduleRunner>;
 declare const _default: {
-    create: () => Readonly<ScheduleRunner>;
+    create: (store?: IScheduleStateStore) => Readonly<ScheduleRunner>;
 };
 export default _default;
 //# sourceMappingURL=ScheduleRunner.d.ts.map

package/src/scheduler/ScheduleRunner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScheduleRunner.d.ts","sourceRoot":"","sources":["../../../src/scheduler/ScheduleRunner.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAkBnE,KAAK,cAAc,GAAG;IACpB,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI,CAAC;IACxC,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;IAC1C,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,EAAE,MAAM,SAAS,EAAE,CAAC;IACxB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAC7D,UAAU,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,gBAAgB,CAAA;KAAE,CAAC,CAAC,CAAC;CAC7E,CAAC;AA6VF,eAAO,MAAM,MAAM,QAAO,QAAQ,CAAC,cAAc,CA6BhD,CAAC;;kBA7BwB,QAAQ,CAAC,cAAc,CAAC;;AA+BlD,wBAA0B"}
+{"version":3,"file":"ScheduleRunner.d.ts","sourceRoot":"","sources":["../../../src/scheduler/ScheduleRunner.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACtB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAkBnE;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,YAAY,CAAC;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CACjC,CAAC,CAAC;AAEH,KAAK,cAAc,GAAG;IACpB,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI,CAAC;IACxC,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;IAC1C,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,EAAE,MAAM,SAAS,EAAE,CAAC;IACxB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAC9E,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAC7D,UAAU,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,gBAAgB,CAAA;KAAE,CAAC,CAAC,CAAC;IAC5E,QAAQ,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;CAChD,CAAC;AAwZF,eAAO,MAAM,MAAM,GAAI,QAAQ,mBAAmB,KAAG,QAAQ,CAAC,cAAc,CAmC3E,CAAC;;qBAnC6B,mBAAmB,KAAG,QAAQ,CAAC,cAAc,CAAC;;AAqC7E,wBAA0B"}

package/src/scheduler/ScheduleRunner.js

@@ -146,7 +146,8 @@ const createRegister = (runner, invokeHandler) => (schedule) => {
         scheduleNext(state, runner.kernel, invokeHandler, 'success', runner.store);
     }
 };
-const createInvokeHandler = (store) => async (state, kernel) => {
+const createInvokeHandler = (runner) => async (state, kernel) => {
+    const store = runner.store;
     if (state.isRunning) {
         Logger.info(`Skipping overlapping run for schedule: ${state.schedule.name}`);
         return 'failure';
@@ -263,30 +264,79 @@ const createRunOnce = (runner, invokeHandler) => async (name, kernel) => {
         return;
     await invokeHandler(state, kernel ?? runner.kernel);
 };
-export const create = () => {
+/**
+ * Computes the epoch-ms timestamp at which a schedule next becomes due,
+ * measured from its last successful run. Cron takes precedence over interval.
+ * Returns `null` when the schedule has neither a cron nor a positive interval
+ * (i.e. it has no cadence of its own and is always considered due).
+ */
+const computeDueAtMs = (schedule, lastRunAt) => {
+    if (typeof schedule.cron === 'string' && schedule.cron.trim().length > 0) {
+        const tz = typeof schedule.timezone === 'string' && schedule.timezone.trim().length > 0
+            ? schedule.timezone
+            : undefined;
+        return Cron.nextRunAtMs(lastRunAt, schedule.cron, tz);
+    }
+    if (typeof schedule.intervalMs === 'number' && schedule.intervalMs > 0) {
+        return lastRunAt + Math.floor(schedule.intervalMs);
+    }
+    return null;
+};
+const createRunIfDue = (runner, invokeHandler) => async (name, kernel) => {
+    const state = runner.schedules.get(name);
+    if (state === undefined)
+        throw ErrorFactory.createNotFoundError(`Schedule not found: ${name}`);
+    if (state.schedule.enabled === false)
+        return { ran: false, reason: 'disabled' };
+    // Prefer the durable, persisted last-run time over the in-memory mirror so
+    // this works across stateless invocations (e.g. Cloudflare Worker cron ticks)
+    // when a persistent store has been wired via setStore().
+    const persisted = await runner.store.get(name);
+    const lastRunAt = persisted?.lastSuccessAt ?? persisted?.lastRunAt ?? state.lastRunAt ?? undefined;
+    if (typeof lastRunAt === 'number') {
+        const dueAt = computeDueAtMs(state.schedule, lastRunAt);
+        if (dueAt === null) {
+            // No cadence configured: nothing to gate on, run it.
+            const outcome = await invokeHandler(state, kernel ?? runner.kernel);
+            return { ran: true, outcome, reason: 'no-cadence' };
+        }
+        if (nowMs() < dueAt) {
+            return { ran: false, reason: 'not-due', nextRunAt: dueAt };
+        }
+    }
+    const outcome = await invokeHandler(state, kernel ?? runner.kernel);
+    return { ran: true, outcome };
+};
+export const create = (store) => {
     const runner = {
         schedules: new Map(),
         started: false,
         kernel: undefined,
-        store: InMemoryScheduleStateStore.create(),
+        store: store ?? InMemoryScheduleStateStore.create(),
     };
-    const invokeHandler = createInvokeHandler(runner.store);
+    const invokeHandler = createInvokeHandler(runner);
     const register = createRegister(runner, invokeHandler);
     const start = createStart(runner, invokeHandler);
     const stopRaw = createStop(runner);
     const stop = createStopWithTimeout(stopRaw);
     const list = createList(runner);
     const runOnce = createRunOnce(runner, invokeHandler);
+    const runIfDue = createRunIfDue(runner, invokeHandler);
     const getState = async (name) => runner.store.get(name);
     const listStates = async () => runner.store.list();
+    const setStore = (next) => {
+        runner.store = next;
+    };
     return Object.freeze({
         register,
         start,
         stop,
         list,
         runOnce,
+        runIfDue,
         getState,
         listStates,
+        setStore,
     });
 };
 export default { create };

package/src/scheduler/SchedulerRuntime.d.ts

@@ -1,4 +1,5 @@
-import type { ScheduleRunState } from './state/ScheduleStateStore';
+import type { RunIfDueResult } from './ScheduleRunner';
+import type { IScheduleStateStore, ScheduleRunState } from './state/ScheduleStateStore';
 import type { ISchedule, IScheduleKernel } from './types';
 export declare const SchedulerRuntime: Readonly<{
     registerMany: (schedules: ReadonlyArray<ISchedule>, source?: "core" | "app") => void;
@@ -10,6 +11,20 @@ export declare const SchedulerRuntime: Readonly<{
         state: ScheduleRunState | null;
     }>>;
     runOnce(name: string, kernel?: IScheduleKernel): Promise<void>;
+    /**
+     * Runs a schedule only if it is due, based on its persisted last-run time and
+     * its configured cron/interval cadence. Intended for stateless cron triggers
+     * (e.g. a Cloudflare Worker `scheduled` handler) where the timer-based
+     * `start()` loop cannot run. For the due check to survive cold starts, wire a
+     * persistent state store via {@link useStateStore} first.
+     */
+    runIfDue(name: string, kernel?: IScheduleKernel): Promise<RunIfDueResult>;
+    /**
+     * Swaps the schedule state store (default is in-memory). Provide a durable
+     * implementation (Redis/KV/D1-backed) so `runIfDue` can read `lastRunAt`
+     * across stateless invocations. Call this before `registerMany`/`runIfDue`.
+     */
+    useStateStore(store: IScheduleStateStore): void;
 }>;
 export default SchedulerRuntime;
 //# sourceMappingURL=SchedulerRuntime.d.ts.map

package/src/scheduler/SchedulerRuntime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SchedulerRuntime.d.ts","sourceRoot":"","sources":["../../../src/scheduler/SchedulerRuntime.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAmDnE,eAAO,MAAM,gBAAgB;8BAzBhB,aAAa,CAAC,SAAS,CAAC,WAC3B,MAAM,GAAG,KAAK,KACrB,IAAI;mBAyBU,eAAe,GAAG,IAAI;qBAqBd,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAOrC,SAAS,EAAE;qBAGI,OAAO,CAAC,KAAK,CAAC;QAAE,QAAQ,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;kBAkB1E,MAAM,WAAW,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;EAGtC,CAAC;AAEjC,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"SchedulerRuntime.d.ts","sourceRoot":"","sources":["../../../src/scheduler/SchedulerRuntime.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AACjG,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAgEnE,eAAO,MAAM,gBAAgB;8BAzBhB,aAAa,CAAC,SAAS,CAAC,WAC3B,MAAM,GAAG,KAAK,KACrB,IAAI;mBAyBU,eAAe,GAAG,IAAI;qBAqBd,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAOrC,SAAS,EAAE;qBAGI,OAAO,CAAC,KAAK,CAAC;QAAE,QAAQ,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;kBAkB1E,MAAM,WAAW,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAGpE;;;;;;OAMG;mBACkB,MAAM,WAAW,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAG/E;;;;OAIG;yBACkB,mBAAmB,GAAG,IAAI;EAGjB,CAAC;AAEjC,eAAe,gBAAgB,CAAC"}

package/src/scheduler/SchedulerRuntime.js

@@ -75,5 +75,23 @@ export const SchedulerRuntime = Object.freeze({
     async runOnce(name, kernel) {
         await state.runner.runOnce(name, kernel);
     },
+    /**
+     * Runs a schedule only if it is due, based on its persisted last-run time and
+     * its configured cron/interval cadence. Intended for stateless cron triggers
+     * (e.g. a Cloudflare Worker `scheduled` handler) where the timer-based
+     * `start()` loop cannot run. For the due check to survive cold starts, wire a
+     * persistent state store via {@link useStateStore} first.
+     */
+    async runIfDue(name, kernel) {
+        return state.runner.runIfDue(name, kernel);
+    },
+    /**
+     * Swaps the schedule state store (default is in-memory). Provide a durable
+     * implementation (Redis/KV/D1-backed) so `runIfDue` can read `lastRunAt`
+     * across stateless invocations. Call this before `registerMany`/`runIfDue`.
+     */
+    useStateStore(store) {
+        state.runner.setStore(store);
+    },
 });
 export default SchedulerRuntime;