@spooky-sync/core 0.0.1-canary.13 → 0.0.1-canary.131

package/src/modules/data/data.recurring.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { DataModule } from './index';
+
+/**
+ * Tests for the recurring-outbox API added to DataModule: runRecurring builds a
+ * single deterministic schedule row (idempotent, swallows a duplicate CREATE);
+ * pokeRecurring bumps next_run_at only when the schedule exists; cancelRecurring
+ * deletes it. The heavy create/update/delete pipeline is spied so these assert
+ * the orchestration (deterministic id, field-building, existence gating) without
+ * a real engine.
+ */
+
+function makeLogger(): any {
+  const noop = () => {};
+  const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  logger.child = () => logger;
+  return logger;
+}
+
+const schema = {
+  tables: [{ name: 'job', columns: {} }],
+  backends: {
+    gamesync: {
+      outboxTable: 'job',
+      routes: { '/syncGames': { args: { connection: { optional: false } } } },
+    },
+  },
+};
+
+const CONN = 'connection:CONN_abc';
+
+// localQueryResult drives the existence check ([] = absent, [row] = present).
+function makeDm(localQueryResult: unknown[]) {
+  const local = { query: vi.fn().mockResolvedValue(localQueryResult) };
+  const dm = new DataModule({} as any, local as any, schema as any, makeLogger(), 100);
+  const create = vi.spyOn(dm, 'create').mockResolvedValue(undefined as any);
+  const update = vi.spyOn(dm, 'update').mockResolvedValue(undefined as any);
+  const del = vi.spyOn(dm, 'delete').mockResolvedValue(undefined as any);
+  return { dm, local, create, update, del };
+}
+
+describe('DataModule.runRecurring', () => {
+  it('creates a single deterministic schedule row with the recurring fields', async () => {
+    const { dm, create } = makeDm([]); // no existing row
+    await dm.runRecurring(
+      'gamesync' as any,
+      '/syncGames' as any,
+      { connection: CONN } as any,
+      { assignedTo: CONN, interval: 300000 }
+    );
+
+    expect(create).toHaveBeenCalledTimes(1);
+    const [id, record] = create.mock.calls[0] as [string, any];
+    expect(id.startsWith('job:')).toBe(true);
+    expect(record.recurring).toBe(true);
+    expect(record.interval).toBe(300000);
+    expect(record.next_run_at).toBeInstanceOf(Date);
+    expect(record.assigned_to).toBe(CONN);
+    expect(record.path).toBe('/syncGames');
+    expect(JSON.parse(record.payload)).toEqual({ connection: CONN });
+  });
+
+  it('is idempotent: does nothing when a schedule already exists', async () => {
+    const { dm, create } = makeDm([{ id: 'job:x' }]); // existing row
+    await dm.runRecurring(
+      'gamesync' as any,
+      '/syncGames' as any,
+      { connection: CONN } as any,
+      { assignedTo: CONN, interval: 300000 }
+    );
+    expect(create).not.toHaveBeenCalled();
+  });
+
+  it('swallows a duplicate CREATE (row exists on server but not yet synced locally)', async () => {
+    const { dm, create } = makeDm([]); // local says absent
+    create.mockRejectedValueOnce(new Error('record already exists'));
+    await expect(
+      dm.runRecurring(
+        'gamesync' as any,
+        '/syncGames' as any,
+        { connection: CONN } as any,
+        { assignedTo: CONN, interval: 300000 }
+      )
+    ).resolves.toBeUndefined();
+  });
+
+  it('uses a stable id per (assignedTo, path)', async () => {
+    const a = makeDm([]);
+    await a.dm.runRecurring('gamesync' as any, '/syncGames' as any, { connection: CONN } as any, { assignedTo: CONN, interval: 300000 });
+    const b = makeDm([]);
+    await b.dm.runRecurring('gamesync' as any, '/syncGames' as any, { connection: CONN } as any, { assignedTo: CONN, interval: 300000 });
+    expect(a.create.mock.calls[0][0]).toBe(b.create.mock.calls[0][0]);
+  });
+
+  it('validates required options', async () => {
+    const { dm } = makeDm([]);
+    await expect(
+      dm.runRecurring('gamesync' as any, '/syncGames' as any, { connection: CONN } as any, { assignedTo: CONN } as any)
+    ).rejects.toThrow(/interval/);
+    await expect(
+      dm.runRecurring('gamesync' as any, '/syncGames' as any, { connection: CONN } as any, { interval: 300000 } as any)
+    ).rejects.toThrow(/assignedTo/);
+  });
+});
+
+describe('DataModule.pokeRecurring', () => {
+  it('bumps next_run_at on the existing schedule row', async () => {
+    const { dm, update } = makeDm([{ id: 'job:x' }]);
+    await dm.pokeRecurring('gamesync' as any, '/syncGames' as any, { assignedTo: CONN });
+    expect(update).toHaveBeenCalledTimes(1);
+    const [table, id, data] = update.mock.calls[0] as [string, string, any];
+    expect(table).toBe('job');
+    expect(id.startsWith('job:')).toBe(true);
+    expect(data.next_run_at).toBeInstanceOf(Date);
+  });
+
+  it('is a no-op when no schedule exists', async () => {
+    const { dm, update } = makeDm([]);
+    await dm.pokeRecurring('gamesync' as any, '/syncGames' as any, { assignedTo: CONN });
+    expect(update).not.toHaveBeenCalled();
+  });
+});
+
+describe('DataModule.cancelRecurring', () => {
+  it('deletes the deterministic schedule row', async () => {
+    const { dm, del, create } = makeDm([]);
+    // Capture the id runRecurring would create, to prove cancel targets the same.
+    await dm.runRecurring('gamesync' as any, '/syncGames' as any, { connection: CONN } as any, { assignedTo: CONN, interval: 300000 });
+    const createdId = create.mock.calls[0][0];
+
+    await dm.cancelRecurring('gamesync' as any, '/syncGames' as any, { assignedTo: CONN });
+    expect(del).toHaveBeenCalledTimes(1);
+    const [table, id] = del.mock.calls[0] as [string, string];
+    expect(table).toBe('job');
+    expect(id).toBe(createdId);
+  });
+});

package/src/modules/data/data.status.test.ts

@@ -0,0 +1,249 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { DataModule } from './index';
+import type { QueryState, QueryStatus } from '../../types';
+
+/**
+ * Tests for the per-query fetch status (idle/fetching) added to DataModule:
+ * setQueryStatus updates the query object and notifies both the DevTools
+ * observer hook and subscribeStatus listeners; beginFetching/endFetching
+ * refcount overlapping fetch cycles; flushPendingStreamUpdate lands the
+ * debounced result before a query flips back to idle.
+ */
+
+function makeLogger(): any {
+  const noop = () => {};
+  const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  logger.child = () => logger;
+  return logger;
+}
+
+function makeDataModule(): DataModule<any> {
+  return new DataModule(
+    {} as any, // cache — unused by status methods
+    {} as any, // local — unused by status methods
+    { tables: [] } as any, // schema — unused by status methods
+    makeLogger(),
+    100
+  );
+}
+
+function makeQueryState(hash: string): QueryState {
+  return {
+    config: {
+      id: new RecordId('_00_query', hash),
+      surql: 'SELECT * FROM user',
+      params: {},
+      localArray: [],
+      remoteArray: [],
+      ttl: '10m',
+      lastActiveAt: new Date(),
+      tableName: 'user',
+    },
+    records: [],
+    ttlTimer: null,
+    ttlDurationMs: 0,
+    updateCount: 0,
+    lastUpdatedAt: null,
+    materializationSamples: [],
+    lastIngestLatencyMs: null,
+    errorCount: 0,
+    status: 'idle',
+    phaseSamples: {},
+    phaseLast: {},
+    registrationTimings: { parseMs: null, planMs: null, snapshotMs: null, wallMs: null },
+  };
+}
+
+describe('DataModule query fetch status', () => {
+  let dm: DataModule<any>;
+  const hash = 'h1';
+
+  beforeEach(() => {
+    dm = makeDataModule();
+    (dm as any).activeQueries.set(hash, makeQueryState(hash));
+  });
+
+  it('subscribeStatus with immediate reports the current status', () => {
+    const seen: QueryStatus[] = [];
+    dm.subscribeStatus(hash, (s) => seen.push(s), { immediate: true });
+    expect(seen).toEqual(['idle']);
+  });
+
+  it('setQueryStatus updates the query object and notifies subscribers + observer', () => {
+    const observed: Array<[string, QueryStatus]> = [];
+    dm.onQueryStatusChange = (h, s) => observed.push([h, s]);
+
+    const seen: QueryStatus[] = [];
+    dm.subscribeStatus(hash, (s) => seen.push(s));
+
+    dm.setQueryStatus(hash, 'fetching');
+    expect((dm as any).activeQueries.get(hash).status).toBe('fetching');
+    expect(seen).toEqual(['fetching']);
+    expect(observed).toEqual([[hash, 'fetching']]);
+
+    dm.setQueryStatus(hash, 'idle');
+    expect(seen).toEqual(['fetching', 'idle']);
+    expect(observed).toEqual([[hash, 'fetching'], [hash, 'idle']]);
+  });
+
+  it('setQueryStatus is a no-op when the status is unchanged', () => {
+    const seen: QueryStatus[] = [];
+    dm.subscribeStatus(hash, (s) => seen.push(s));
+    dm.setQueryStatus(hash, 'idle'); // already idle
+    expect(seen).toEqual([]);
+  });
+
+  it('setQueryStatus is a no-op for an unknown query', () => {
+    let called = false;
+    dm.onQueryStatusChange = () => {
+      called = true;
+    };
+    dm.setQueryStatus('does-not-exist', 'fetching');
+    expect(called).toBe(false);
+  });
+
+  it('unsubscribe stops further status notifications', () => {
+    const seen: QueryStatus[] = [];
+    const unsub = dm.subscribeStatus(hash, (s) => seen.push(s));
+    dm.setQueryStatus(hash, 'fetching');
+    unsub();
+    dm.setQueryStatus(hash, 'idle');
+    expect(seen).toEqual(['fetching']);
+  });
+});
+
+describe('DataModule beginFetching/endFetching refcount', () => {
+  let dm: DataModule<any>;
+  const hash = 'h1';
+  let seen: QueryStatus[];
+
+  beforeEach(() => {
+    dm = makeDataModule();
+    (dm as any).activeQueries.set(hash, makeQueryState(hash));
+    seen = [];
+    dm.subscribeStatus(hash, (s) => seen.push(s));
+  });
+
+  it('emits fetching on 0→1 and idle only on the last exit', () => {
+    dm.beginFetching(hash); // registration
+    dm.beginFetching(hash); // overlapping poll round
+    expect(seen).toEqual(['fetching']);
+
+    dm.endFetching(hash); // inner cycle finishes — must NOT emit idle
+    expect(seen).toEqual(['fetching']);
+    expect((dm as any).activeQueries.get(hash).status).toBe('fetching');
+
+    dm.endFetching(hash);
+    expect(seen).toEqual(['fetching', 'idle']);
+  });
+
+  it('unbalanced endFetching settles to idle without going negative', () => {
+    dm.endFetching(hash); // already idle → no-op notification
+    expect(seen).toEqual([]);
+    dm.beginFetching(hash);
+    dm.endFetching(hash);
+    expect(seen).toEqual(['fetching', 'idle']);
+    expect((dm as any).fetchDepth.has(hash)).toBe(false);
+  });
+});
+
+describe('DataModule pending stream-update flush', () => {
+  let dm: DataModule<any>;
+  const hash = 'h1';
+  let processed: any[];
+
+  const makeUpdate = (op: 'CREATE' | 'UPDATE' | 'DELETE') =>
+    ({ queryHash: hash, op, localArray: [] }) as any;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    dm = makeDataModule();
+    (dm as any).activeQueries.set(hash, makeQueryState(hash));
+    processed = [];
+    (dm as any).processStreamUpdate = async (u: any) => {
+      processed.push(u);
+    };
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('flushPendingStreamUpdate processes the debounced update exactly once', async () => {
+    const update = makeUpdate('CREATE');
+    await dm.onStreamUpdate(update);
+    expect(processed).toEqual([]); // still debounced
+
+    await dm.flushPendingStreamUpdate(hash);
+    expect(processed).toEqual([update]);
+    expect((dm as any).debounceTimers.has(hash)).toBe(false);
+    expect((dm as any).pendingStreamUpdates.has(hash)).toBe(false);
+
+    // The cancelled timer must not process it a second time.
+    await vi.runAllTimersAsync();
+    expect(processed).toEqual([update]);
+
+    // Nothing pending → flush is a no-op.
+    await dm.flushPendingStreamUpdate(hash);
+    expect(processed).toEqual([update]);
+  });
+
+  it('the trailing-edge timer clears the pending entry itself', async () => {
+    const update = makeUpdate('UPDATE');
+    await dm.onStreamUpdate(update);
+    await vi.runAllTimersAsync();
+    expect(processed).toEqual([update]);
+    expect((dm as any).pendingStreamUpdates.has(hash)).toBe(false);
+  });
+
+  it('a DELETE supersedes and drops the pending coalesced update', async () => {
+    const create = makeUpdate('CREATE');
+    const del = makeUpdate('DELETE');
+    await dm.onStreamUpdate(create);
+    await dm.onStreamUpdate(del); // immediate, drops the pending CREATE
+    expect(processed).toEqual([del]);
+    expect((dm as any).pendingStreamUpdates.has(hash)).toBe(false);
+    await vi.runAllTimersAsync();
+    expect(processed).toEqual([del]);
+  });
+
+  it('finalizeDeregister clears pending update and fetch depth', async () => {
+    (dm as any).cache = { unregisterQuery: () => {} };
+    await dm.onStreamUpdate(makeUpdate('CREATE'));
+    dm.beginFetching(hash);
+    dm.finalizeDeregister(hash);
+    expect((dm as any).pendingStreamUpdates.has(hash)).toBe(false);
+    expect((dm as any).debounceTimers.has(hash)).toBe(false);
+    expect((dm as any).fetchDepth.has(hash)).toBe(false);
+    await vi.runAllTimersAsync();
+    expect(processed).toEqual([]);
+  });
+});
+
+describe('DataModule notifyQuerySynced', () => {
+  const hash = 'h1';
+
+  function makeDmWithLocal(rows: any[]): DataModule<any> {
+    const local: any = { query: async () => [rows] };
+    return new DataModule({} as any, local, { tables: [] } as any, makeLogger(), 100);
+  }
+
+  it('notifies once per registration lifetime even when records are unchanged and updateCount > 0', async () => {
+    const dm = makeDmWithLocal([]);
+    const state = makeQueryState(hash);
+    state.updateCount = 7; // persisted from a previous registration
+    (dm as any).activeQueries.set(hash, state);
+
+    let notified = 0;
+    dm.subscribe(hash, () => {
+      notified++;
+    });
+
+    await dm.notifyQuerySynced(hash); // empty result, unchanged — must still emit
+    expect(notified).toBe(1);
+
+    await dm.notifyQuerySynced(hash); // already notified this lifetime → silent
+    expect(notified).toBe(1);
+  });
+});