@zintrust/core 2.4.5 → 2.4.7

package/package.json

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

package/src/cache/Cache.d.ts

@@ -6,6 +6,7 @@
 import type { CacheDriver } from './CacheDriver';
 type CacheStore = Readonly<{
     get: <T>(key: string) => Promise<T | null>;
+    many: <T>(keys: string[]) => Promise<(T | null)[]>;
     set: <T>(key: string, value: T, ttl?: number) => Promise<void>;
     delete: (key: string) => Promise<void>;
     clear: () => Promise<void>;
@@ -16,6 +17,7 @@ type CacheStore = Readonly<{
 }>;
 export declare const Cache: Readonly<{
     get: <T>(key: string) => Promise<T | null>;
+    many: <T>(keys: string[]) => Promise<(T | null)[]>;
     set: <T>(key: string, value: T, ttl?: number) => Promise<void>;
     delete: (key: string) => Promise<void>;
     clear: () => Promise<void>;
@@ -32,6 +34,7 @@ export declare const Cache: Readonly<{
  */
 export declare const cache: Readonly<{
     get: <T>(key: string) => Promise<T | null>;
+    many: <T>(keys: string[]) => Promise<(T | null)[]>;
     set: <T>(key: string, value: T, ttl?: number) => Promise<void>;
     delete: (key: string) => Promise<void>;
     clear: () => Promise<void>;

package/src/cache/Cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Cache.d.ts","sourceRoot":"","sources":["../../../src/cache/Cache.ts"],"names":[],"mappings":"AACA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAiOtD,KAAK,UAAU,GAAG,QAAQ,CAAC;IACzB,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3C,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,SAAS,EAAE,MAAM,WAAW,CAAC;CAC9B,CAAC,CAAC;AAsIH,eAAO,MAAM,KAAK;UApQC,CAAC,OAAO,MAAM,KAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;UAkBlC,CAAC,OAAO,MAAM,SAAS,CAAC,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;kBAkBjD,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;iBAiBtB,OAAO,CAAC,IAAI,CAAC;eAgBb,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;qBAenB,MAAM,sBAAe,OAAO,CAAC,MAAM,CAAC;qBAapC,MAAM,sBAAe,OAAO,CAAC,MAAM,CAAC;qBAgB5C,WAAW;iCAwIG,MAAM,KAAG,OAAO;mBAvH9B,MAAM,KAAG,UAAU;iBAmHvB,IAAI;EA2BpB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,KAAK;UArRC,CAAC,OAAO,MAAM,KAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;UAkBlC,CAAC,OAAO,MAAM,SAAS,CAAC,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;kBAkBjD,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;iBAiBtB,OAAO,CAAC,IAAI,CAAC;eAgBb,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;qBAenB,MAAM,sBAAe,OAAO,CAAC,MAAM,CAAC;qBAapC,MAAM,sBAAe,OAAO,CAAC,MAAM,CAAC;qBAgB5C,WAAW;iCAwIG,MAAM,KAAG,OAAO;mBAvH9B,MAAM,KAAG,UAAU;iBAmHvB,IAAI;EAgCI,CAAC"}
+{"version":3,"file":"Cache.d.ts","sourceRoot":"","sources":["../../../src/cache/Cache.ts"],"names":[],"mappings":"AACA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA2QtD,KAAK,UAAU,GAAG,QAAQ,CAAC;IACzB,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3C,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;IACnD,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,SAAS,EAAE,MAAM,WAAW,CAAC;CAC9B,CAAC,CAAC;AA0IH,eAAO,MAAM,KAAK;UAnTC,CAAC,OAAO,MAAM,KAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;WAsDjC,CAAC,QAAQ,MAAM,EAAE,KAAG,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;UAM1C,CAAC,OAAO,MAAM,SAAS,CAAC,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;kBAkBjD,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;iBAiBtB,OAAO,CAAC,IAAI,CAAC;eAgBb,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;qBAenB,MAAM,sBAAe,OAAO,CAAC,MAAM,CAAC;qBAapC,MAAM,sBAAe,OAAO,CAAC,MAAM,CAAC;qBAgB5C,WAAW;iCA6IG,MAAM,KAAG,OAAO;mBA3H9B,MAAM,KAAG,UAAU;iBAuHvB,IAAI;EA4BpB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,KAAK;UArUC,CAAC,OAAO,MAAM,KAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;WAsDjC,CAAC,QAAQ,MAAM,EAAE,KAAG,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;UAM1C,CAAC,OAAO,MAAM,SAAS,CAAC,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;kBAkBjD,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;iBAiBtB,OAAO,CAAC,IAAI,CAAC;eAgBb,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;qBAenB,MAAM,sBAAe,OAAO,CAAC,MAAM,CAAC;qBAapC,MAAM,sBAAe,OAAO,CAAC,MAAM,CAAC;qBAgB5C,WAAW;iCA6IG,MAAM,KAAG,OAAO;mBA3H9B,MAAM,KAAG,UAAU;iBAuHvB,IAAI;EAiCI,CAAC"}

package/src/cache/Cache.js

@@ -95,6 +95,33 @@ const get = async (key) => {
     SystemTraceBridge.emitCache('get', prefixedKey, Date.now() - startedAt, value !== null, value, DEFAULT_STORE_NAME);
     return value;
 };
+// Batched read: one round-trip via driver.many() (e.g. Redis MGET) when supported,
+// otherwise individual gets. Results stay aligned to the requested key order.
+const runMany = async (driver, keys, storeName) => {
+    if (keys.length === 0)
+        return [];
+    const prefixedKeys = keys.map((key) => autoPrefixKey(key));
+    const startedAt = Date.now();
+    const many = driver.many;
+    let values;
+    const batched = typeof many === 'function';
+    if (batched) {
+        values = await many(prefixedKeys);
+    }
+    else {
+        values = await Promise.all(prefixedKeys.map(async (prefixedKey) => driver.get(prefixedKey)));
+    }
+    const elapsed = Date.now() - startedAt;
+    const normalized = prefixedKeys.map((_prefixedKey, index) => values[index] ?? null);
+    const hitCount = normalized.filter((value) => value !== null).length;
+    // One trace record per round-trip: a driver-level `many` (e.g. Redis MGET) is a single
+    // network call, so it must not look like N separate gets. Drivers without `many` fall back
+    // to N gets, which is reflected with the `gets` label.
+    const label = batched ? 'mget' : 'gets';
+    SystemTraceBridge.emitCache('get', `${label}(${prefixedKeys.length}/${hitCount} hit) ${prefixedKeys.join(',')}`, elapsed, hitCount > 0, undefined, storeName);
+    return normalized;
+};
+const many = async (keys) => runMany(getDriverInstance(), keys, DEFAULT_STORE_NAME);
 /**
  * Store an item in the cache
  */
@@ -169,6 +196,7 @@ const store = (name) => {
         SystemTraceBridge.emitCache('get', prefixedKey, Date.now() - startedAt, value !== null, value, String(name ?? DEFAULT_STORE_NAME));
         return value;
     };
+    const manyFromStore = async (keys) => runMany(getDriverInstance(name), keys, String(name ?? DEFAULT_STORE_NAME));
     const setInStore = async (key, value, ttl) => {
         const prefixedKey = autoPrefixKey(key);
         const startedAt = Date.now();
@@ -220,6 +248,7 @@ const store = (name) => {
     };
     return Object.freeze({
         get: getFromStore,
+        many: manyFromStore,
         set: setInStore,
         delete: delFromStore,
         clear: clearStore,
@@ -242,6 +271,7 @@ const getRedisClient = (storeName) => {
 // Sealed namespace with cache functionality
 export const Cache = Object.freeze({
     get,
+    many,
     set,
     delete: del,
     clear,

package/src/cache/CacheDriver.d.ts

@@ -7,6 +7,13 @@ export interface CacheDriver {
      * Get an item from the cache
      */
     get<T>(key: string): Promise<T | null>;
+    /**
+     * Get many items from the cache in a single round-trip when the driver
+     * supports it (e.g. Redis MGET). Results are returned in the same order as
+     * the requested keys, with `null` for misses. Optional: callers fall back to
+     * issuing individual `get` calls when a driver does not implement it.
+     */
+    many?<T>(keys: string[]): Promise<(T | null)[]>;
     /**
      * Store an item in the cache
      */

package/src/cache/CacheDriver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CacheDriver.d.ts","sourceRoot":"","sources":["../../../src/cache/CacheDriver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEvC;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3D;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnC;;OAEG;IACH,SAAS,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1D;;OAEG;IACH,SAAS,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1D;;OAEG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;;OAGG;IACH,cAAc,CAAC,IAAI,OAAO,CAAC;CAC5B;AAGD,eAAO,MAAM,sBAAsB,gBAAgB,CAAC"}
+{"version":3,"file":"CacheDriver.d.ts","sourceRoot":"","sources":["../../../src/cache/CacheDriver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEvC;;;;;OAKG;IACH,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;IAEhD;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3D;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnC;;OAEG;IACH,SAAS,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1D;;OAEG;IACH,SAAS,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1D;;OAEG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;;OAGG;IACH,cAAc,CAAC,IAAI,OAAO,CAAC;CAC5B;AAGD,eAAO,MAAM,sBAAsB,gBAAgB,CAAC"}

package/src/cache/drivers/RedisDriver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RedisDriver.d.ts","sourceRoot":"","sources":["../../../../src/cache/drivers/RedisDriver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA+btD;;GAEG;AACH,eAAO,MAAM,WAAW;kBAbL,WAAW;EAe5B,CAAC"}
+{"version":3,"file":"RedisDriver.d.ts","sourceRoot":"","sources":["../../../../src/cache/drivers/RedisDriver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAsdtD;;GAEG;AACH,eAAO,MAAM,WAAW;kBAbL,WAAW;EAe5B,CAAC"}

package/src/cache/drivers/RedisDriver.js

@@ -69,6 +69,30 @@ const createCacheDriverFromIoredisClient = (client) => ({
             return null;
         }
     },
+    async many(keys) {
+        if (keys.length === 0)
+            return [];
+        try {
+            const prefixedKeys = keys.map((key) => RedisKeys.createCacheKey(key));
+            const values = typeof client.mget === 'function'
+                ? await client.mget(...prefixedKeys)
+                : await Promise.all(prefixedKeys.map(async (prefixedKey) => client.get(prefixedKey)));
+            return values.map((value) => {
+                if (value === null || value === undefined)
+                    return null;
+                try {
+                    return JSON.parse(value);
+                }
+                catch {
+                    return null;
+                }
+            });
+        }
+        catch (error) {
+            Logger.error('Redis MGET failed', error);
+            return keys.map(() => null);
+        }
+    },
     async set(key, value, ttl) {
         try {
             const prefixedKey = RedisKeys.createCacheKey(key);

package/src/index.js

@@ -1,11 +1,11 @@
 /**
- * @zintrust/core v2.4.5
+ * @zintrust/core v2.4.7
  *
  * 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-01T22:49:09.622Z
  *   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-01T22:49:09.586Z'; // 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;