nucleus-core-ts 0.9.853 → 0.9.855

package/dist/src/Services/Integrations/types.d.ts

@@ -146,7 +146,18 @@ export type RunStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancell
  */
 export type RunIssue = {
     sourceIndex: number;
-    kind: 'missing_required' | 'missing_dedup_key' | 'duplicate_in_batch' | 'duplicate_value' | 'invalid_value' | 'unmapped' | 'missing_reference' | 'account_unmatched';
+    kind: 'missing_required' | 'missing_dedup_key' | 'duplicate_in_batch' | 'duplicate_value' | 'invalid_value' | 'unmapped' | 'missing_reference' | 'account_unmatched'
+    /**
+     * An account was made, but the row that gives it a ROLE was not.
+     *
+     * The two are written separately — the account first, its membership after
+     * — and the membership was dropped without a word whenever the table it
+     * points at could not be resolved, or the account it belongs to could not
+     * be found again. Both leave a person who can sign in and do nothing, and
+     * the only evidence is a table nobody thinks to open. Reported so the run
+     * says it out loud instead.
+     */
+     | 'account_role_missing';
     message: string;
     dedupKey?: string | null;
     /**

package/dist/src/Services/Integrations/writer.d.ts

@@ -121,6 +121,14 @@ export type ApplyResult = {
     deleted: number;
     deactivated: number;
     preImages: PreImage[];
+    /**
+     * What was written INCOMPLETELY, rather than not at all.
+     *
+     * A role membership that could not be written leaves an account that can
+     * sign in and do nothing. It used to be skipped in silence — the run
+     * reported success and the only evidence was a join table nobody opens.
+     */
+    issues: RunIssue[];
 } | {
     ok: false;
     failure: RunFailure;

package/dist/src/Shared/cron.d.ts

@@ -41,10 +41,25 @@ export declare function matchesCron(fields: CronFields, when: Date, timeZone: st
 /**
  * Is this schedule due, given when it last ran?
  *
- * Answers for the minute `now` falls in, and refuses to answer twice for the
- * same minute — a scheduler that ticks more often than once a minute would
- * otherwise start the same import several times, and the run lock would be the
- * only thing between that and two imports writing the same rows.
+ * ## Why this looks at more than the current minute
+ *
+ * It used to ask one question — "does the minute `now` falls in match?" — and
+ * the scheduler asks it once a minute from a `setInterval`. `setInterval` drifts:
+ * a tick at 09:00:59.8 and the next at 09:02:00.1 never samples 09:01, so a
+ * schedule of `1 9 * * *` simply did not run that day. Nothing was logged,
+ * because from the scheduler's point of view nothing was due. The same hole
+ * swallows any minute lost to a busy event loop, a slow query on the tick before,
+ * or a container restarting across the boundary.
+ *
+ * So the question is now "has a matching minute passed that we have not run
+ * for?" — every minute after `lastRunAt`, up to and including this one, bounded
+ * by {@link CATCH_UP_MINUTES}. A schedule that has never run keeps the old,
+ * stricter rule: firing on the exact minute only, so turning one on does not
+ * replay a history it was never part of.
+ *
+ * It still refuses to answer twice for the same minute, which is what keeps a
+ * scheduler that ticks more often than once a minute from starting the same
+ * import several times.
  */
 export declare function isDue(input: {
     expression: string;

package/dist/src/Shared/cron.js

@@ -149,13 +149,36 @@ export function parseCron(expression) {
     if (fields.anyDayOfWeek) return dayOfMonthMatches;
     return dayOfMonthMatches || dayOfWeekMatches;
 }
+/**
+ * How far back a missed schedule is still worth catching up.
+ *
+ * A day and an hour: long enough to cover a night's outage or a deploy, short
+ * enough that a mapping paused for a month does not fire the moment it is turned
+ * back on. Counted in minutes because that is the resolution cron has.
+ */ const CATCH_UP_MINUTES = 25 * 60;
+const MINUTE_MS = 60000;
 /**
  * Is this schedule due, given when it last ran?
  *
- * Answers for the minute `now` falls in, and refuses to answer twice for the
- * same minute — a scheduler that ticks more often than once a minute would
- * otherwise start the same import several times, and the run lock would be the
- * only thing between that and two imports writing the same rows.
+ * ## Why this looks at more than the current minute
+ *
+ * It used to ask one question — "does the minute `now` falls in match?" — and
+ * the scheduler asks it once a minute from a `setInterval`. `setInterval` drifts:
+ * a tick at 09:00:59.8 and the next at 09:02:00.1 never samples 09:01, so a
+ * schedule of `1 9 * * *` simply did not run that day. Nothing was logged,
+ * because from the scheduler's point of view nothing was due. The same hole
+ * swallows any minute lost to a busy event loop, a slow query on the tick before,
+ * or a container restarting across the boundary.
+ *
+ * So the question is now "has a matching minute passed that we have not run
+ * for?" — every minute after `lastRunAt`, up to and including this one, bounded
+ * by {@link CATCH_UP_MINUTES}. A schedule that has never run keeps the old,
+ * stricter rule: firing on the exact minute only, so turning one on does not
+ * replay a history it was never part of.
+ *
+ * It still refuses to answer twice for the same minute, which is what keeps a
+ * scheduler that ticks more often than once a minute from starting the same
+ * import several times.
  */ export function isDue(input) {
     const parsed = parseCron(input.expression);
     if (!parsed.ok) return {
@@ -163,26 +186,32 @@ export function parseCron(expression) {
         error: parsed.error
     };
     const zone = input.timeZone?.trim() || 'UTC';
-    let matches;
+    const nowMinute = Math.floor(input.now.getTime() / MINUTE_MS);
+    /** How many minutes back to look, inclusive of this one. */ let lookBack = 0;
+    if (input.lastRunAt) {
+        const lastMinute = Math.floor(input.lastRunAt.getTime() / MINUTE_MS);
+        // Already answered for this minute — or the clock moved backwards, which is
+        // not a reason to fire.
+        if (lastMinute >= nowMinute) return {
+            due: false
+        };
+        lookBack = Math.min(nowMinute - lastMinute - 1, CATCH_UP_MINUTES);
+    }
     try {
-        matches = matchesCron(parsed.fields, input.now, zone);
+        for(let back = 0; back <= lookBack; back++){
+            const at = new Date((nowMinute - back) * MINUTE_MS);
+            if (matchesCron(parsed.fields, at, zone)) return {
+                due: true
+            };
+        }
     } catch  {
         return {
             due: false,
             error: `"${zone}" is not a timezone this system knows.`
         };
     }
-    if (!matches) return {
-        due: false
-    };
-    if (input.lastRunAt) {
-        const sameMinute = Math.floor(input.lastRunAt.getTime() / 60000) === Math.floor(input.now.getTime() / 60000);
-        if (sameMinute) return {
-            due: false
-        };
-    }
     return {
-        due: true
+        due: false
     };
 }
 /** Plain words for a schedule, so nobody has to read cron to know what they set. */ export function describeCron(expression, timeZone) {

package/dist/src/Shared/cron.test.js

@@ -139,3 +139,85 @@ describe('saying it in plain words', ()=>{
         expect(describeCron('nope')).toContain('five parts');
     });
 });
+/**
+ * The scheduler ticks once a minute from a `setInterval`, and `setInterval`
+ * drifts. A tick at 09:00:59.8 followed by one at 09:02:00.1 never samples
+ * 09:01 — so a daily `1 9 * * *` did not run that day, and nothing was logged,
+ * because nothing was ever asked about that minute.
+ */ describe('isDue — a minute the scheduler never sampled', ()=>{
+    const daily = '1 9 * * *';
+    const at = (iso)=>new Date(iso);
+    it('fires for a matching minute that was skipped between two ticks', ()=>{
+        expect(isDue({
+            expression: daily,
+            now: at('2026-03-04T09:02:00.100Z'),
+            lastRunAt: at('2026-03-03T09:01:00.000Z')
+        }).due).toBe(true);
+    });
+    it('still fires on the exact minute, as before', ()=>{
+        expect(isDue({
+            expression: daily,
+            now: at('2026-03-04T09:01:00.000Z'),
+            lastRunAt: at('2026-03-03T09:01:00.000Z')
+        }).due).toBe(true);
+    });
+    it('does not fire twice for the same minute', ()=>{
+        expect(isDue({
+            expression: daily,
+            now: at('2026-03-04T09:01:30.000Z'),
+            lastRunAt: at('2026-03-04T09:01:02.000Z')
+        }).due).toBe(false);
+    });
+    it('does not fire for a minute that does not match', ()=>{
+        expect(isDue({
+            expression: daily,
+            now: at('2026-03-04T10:30:00.000Z'),
+            lastRunAt: at('2026-03-04T09:01:00.000Z')
+        }).due).toBe(false);
+    });
+    /**
+   * A schedule that has never run must not replay a history it was not part of:
+   * turning one on should not fire immediately for yesterday's slot.
+   */ it('does not backfill for a schedule that has never run', ()=>{
+        expect(isDue({
+            expression: daily,
+            now: at('2026-03-04T09:02:00.000Z')
+        }).due).toBe(false);
+        expect(isDue({
+            expression: daily,
+            now: at('2026-03-04T09:01:00.000Z')
+        }).due).toBe(true);
+    });
+    /**
+   * Paused for a month, then looked at again: it catches up the most recent
+   * missed slot, not thirty of them. The window is what bounds it — a daily
+   * schedule always has one inside a day, so this fires once and then the
+   * `lastRunAt` it writes keeps it from firing again.
+   */ it('catches up the recent slot after a long pause, not the whole backlog', ()=>{
+        expect(isDue({
+            expression: daily,
+            now: at('2026-04-04T12:00:00.000Z'),
+            lastRunAt: at('2026-03-01T09:01:00.000Z')
+        }).due).toBe(true);
+    });
+    /**
+   * And a slot that fell OUTSIDE the window stays missed. A weekly schedule
+   * whose Monday came and went three days ago is not started on Thursday: by
+   * then it is not late, it is wrong.
+   */ it('leaves a slot older than the window alone', ()=>{
+        const mondayMorning = '0 9 * * 1';
+        expect(isDue({
+            expression: mondayMorning,
+            // Thursday noon; the Monday slot is three days back, the window is 25h.
+            now: at('2026-03-05T12:00:00.000Z'),
+            lastRunAt: at('2026-02-23T09:00:00.000Z')
+        }).due).toBe(false);
+    });
+    it('ignores a clock that moved backwards rather than firing', ()=>{
+        expect(isDue({
+            expression: daily,
+            now: at('2026-03-04T09:01:00.000Z'),
+            lastRunAt: at('2026-03-04T09:05:00.000Z')
+        }).due).toBe(false);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nucleus-core-ts",
-	"version": "0.9.853",
+	"version": "0.9.855",
 	"description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
 	"author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
 	"license": "SEE LICENSE IN LICENSE",