@spooky-sync/core 0.0.1-canary.15 → 0.0.1-canary.151

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

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi } from 'vitest';
+import { DataModule } from './index';
+
+/**
+ * Tests for `DataModule.run`, the one-shot outbox API.
+ *
+ * Recurring jobs used to live here too (`runRecurring` / `pokeRecurring` /
+ * `cancelRecurring`, which wrote a single durable row the runner re-armed
+ * forever). They are gone: schedules are now declared server-side under
+ * `schedules:` in sp00ky.yml, and the scheduler creates a fresh job row per
+ * cycle — so every row this API writes is exactly one execution.
+ *
+ * The create/update pipeline is spied, so these assert the orchestration
+ * (table resolution, argument validation, field building) 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 }, since: { optional: true } },
+        },
+      },
+    },
+    noOutbox: {
+      routes: { '/whatever': { args: {} } },
+    },
+  },
+};
+
+const CONN = 'connection:CONN_abc';
+
+function makeDm() {
+  const local = { query: vi.fn().mockResolvedValue([]) };
+  const dm = new DataModule({} as any, local as any, schema as any, makeLogger(), 100);
+  const create = vi.spyOn(dm, 'create').mockResolvedValue(undefined as any);
+  return { dm, local, create };
+}
+
+describe('DataModule.run', () => {
+  it('creates the one-shot job with status pending so the optimistic row reads in-flight', async () => {
+    const { dm, create } = makeDm();
+    await dm.run('gamesync' as any, '/syncGames' as any, { connection: CONN } as any, {
+      assignedTo: CONN,
+    });
+
+    expect(create).toHaveBeenCalledTimes(1);
+    const [id, record] = create.mock.calls[0] as [string, any];
+    expect(id.startsWith('job:')).toBe(true);
+    // The schema's DEFAULT ALWAYS "pending" only runs server-side; without the
+    // explicit field the local optimistic row has status undefined and
+    // in-flight indicators miss it until the first server echo.
+    expect(record.status).toBe('pending');
+  });
+
+  it('gives each call its own row', async () => {
+    const { dm, create } = makeDm();
+    await dm.run('gamesync' as any, '/syncGames' as any, { connection: CONN } as any);
+    await dm.run('gamesync' as any, '/syncGames' as any, { connection: CONN } as any);
+
+    const [firstId] = create.mock.calls[0] as [string, any];
+    const [secondId] = create.mock.calls[1] as [string, any];
+    expect(firstId).not.toBe(secondId);
+  });
+
+  it('carries the retry, timeout and delay options onto the row', async () => {
+    const { dm, create } = makeDm();
+    await dm.run('gamesync' as any, '/syncGames' as any, { connection: CONN } as any, {
+      assignedTo: CONN,
+      max_retries: 5,
+      retry_strategy: 'exponential',
+      timeout: 30,
+      delay: 60_000,
+    });
+
+    const [, record] = create.mock.calls[0] as [string, any];
+    expect(record.max_retries).toBe(5);
+    expect(record.retry_strategy).toBe('exponential');
+    expect(record.timeout).toBe(30);
+    expect(record.delay).toBe(60_000);
+  });
+
+  it('serializes the payload and rejects a missing required argument', async () => {
+    const { dm, create } = makeDm();
+    await dm.run('gamesync' as any, '/syncGames' as any, { connection: CONN } as any);
+    const [, record] = create.mock.calls[0] as [string, any];
+    expect(JSON.parse(record.payload)).toEqual({ connection: CONN });
+
+    await expect(
+      dm.run('gamesync' as any, '/syncGames' as any, {} as any)
+    ).rejects.toThrow(/connection/);
+  });
+
+  it('rejects an unknown route and a backend with no outbox table', async () => {
+    const { dm } = makeDm();
+    await expect(
+      dm.run('gamesync' as any, '/nope' as any, {} as any)
+    ).rejects.toThrow(/not found/);
+    await expect(
+      dm.run('noOutbox' as any, '/whatever' as any, {} as any)
+    ).rejects.toThrow(/Outbox table/);
+  });
+});

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);
+  });
+});