@spooky-sync/core 0.0.1-canary.16 → 0.0.1-canary.160

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (123) hide show
  1. package/AGENTS.md +56 -0
  2. package/dist/index.d.ts +1406 -364
  3. package/dist/index.js +7754 -1390
  4. package/dist/otel/index.d.ts +21 -0
  5. package/dist/otel/index.js +86 -0
  6. package/dist/sqlite-open.js +276 -0
  7. package/dist/sqlite-worker.d.ts +1 -0
  8. package/dist/sqlite-worker.js +420 -0
  9. package/dist/tabs-broker-worker.d.ts +8 -0
  10. package/dist/tabs-broker-worker.js +434 -0
  11. package/dist/types.d.ts +874 -0
  12. package/package.json +20 -7
  13. package/scripts/check-broker-bundle.mjs +33 -0
  14. package/skills/sp00ky-core/SKILL.md +258 -0
  15. package/skills/sp00ky-core/references/auth.md +98 -0
  16. package/skills/sp00ky-core/references/config.md +76 -0
  17. package/src/build-globals.d.ts +12 -0
  18. package/src/events/events.test.ts +2 -1
  19. package/src/events/index.ts +3 -0
  20. package/src/index.ts +16 -2
  21. package/src/modules/app-release/index.test.ts +125 -0
  22. package/src/modules/app-release/index.ts +201 -0
  23. package/src/modules/auth/events/index.ts +2 -1
  24. package/src/modules/auth/index.ts +59 -20
  25. package/src/modules/cache/index.ts +112 -32
  26. package/src/modules/cache/types.ts +2 -2
  27. package/src/modules/crdt/crdt-field.ts +294 -0
  28. package/src/modules/crdt/crdt-hydration.test.ts +206 -0
  29. package/src/modules/crdt/index.ts +361 -0
  30. package/src/modules/crdt/loro-loader.ts +25 -0
  31. package/src/modules/data/data.hydration.test.ts +142 -0
  32. package/src/modules/data/data.rebind.test.ts +147 -0
  33. package/src/modules/data/data.run.test.ts +113 -0
  34. package/src/modules/data/data.status.test.ts +249 -0
  35. package/src/modules/data/index.ts +1151 -129
  36. package/src/modules/data/mutation-id.test.ts +25 -0
  37. package/src/modules/data/mutation-id.ts +35 -0
  38. package/src/modules/data/window-query.test.ts +52 -0
  39. package/src/modules/data/window-query.ts +154 -0
  40. package/src/modules/devtools/index.ts +325 -37
  41. package/src/modules/devtools/notify-throttle.test.ts +149 -0
  42. package/src/modules/devtools/storage-info.test.ts +79 -0
  43. package/src/modules/devtools/storage-info.ts +143 -0
  44. package/src/modules/devtools/versions.test.ts +74 -0
  45. package/src/modules/devtools/versions.ts +81 -0
  46. package/src/modules/feature-flag/index.test.ts +120 -0
  47. package/src/modules/feature-flag/index.ts +209 -0
  48. package/src/modules/ref-tables.test.ts +91 -0
  49. package/src/modules/ref-tables.ts +88 -0
  50. package/src/modules/sync/engine.ts +101 -37
  51. package/src/modules/sync/events/index.ts +9 -2
  52. package/src/modules/sync/queue/queue-down.ts +12 -5
  53. package/src/modules/sync/queue/queue-up.forwarded.test.ts +137 -0
  54. package/src/modules/sync/queue/queue-up.ts +198 -57
  55. package/src/modules/sync/scheduler.pause.test.ts +109 -0
  56. package/src/modules/sync/scheduler.ts +77 -9
  57. package/src/modules/sync/sync.health.test.ts +149 -0
  58. package/src/modules/sync/sync.subquery.test.ts +82 -0
  59. package/src/modules/sync/sync.ts +1333 -92
  60. package/src/modules/sync/utils.test.ts +269 -2
  61. package/src/modules/sync/utils.ts +182 -17
  62. package/src/otel/index.ts +127 -0
  63. package/src/services/database/cache-engine.ts +160 -0
  64. package/src/services/database/database.ts +11 -11
  65. package/src/services/database/engine-factory.ts +33 -0
  66. package/src/services/database/events/index.ts +2 -1
  67. package/src/services/database/index.ts +6 -0
  68. package/src/services/database/local-migrator.ts +28 -27
  69. package/src/services/database/local.test.ts +64 -0
  70. package/src/services/database/local.ts +478 -67
  71. package/src/services/database/plan-render.test.ts +159 -0
  72. package/src/services/database/plan-render.ts +108 -0
  73. package/src/services/database/relation-resolver.test.ts +413 -0
  74. package/src/services/database/relation-resolver.ts +0 -0
  75. package/src/services/database/remote.ts +13 -13
  76. package/src/services/database/sqlite-cache-engine.test.ts +464 -0
  77. package/src/services/database/sqlite-cache-engine.ts +1154 -0
  78. package/src/services/database/sqlite-open.test.ts +150 -0
  79. package/src/services/database/sqlite-open.ts +164 -0
  80. package/src/services/database/sqlite-plan-sql.test.ts +104 -0
  81. package/src/services/database/sqlite-plan-sql.ts +106 -0
  82. package/src/services/database/sqlite-select.integration.test.ts +185 -0
  83. package/src/services/database/sqlite-select.test.ts +246 -0
  84. package/src/services/database/sqlite-select.ts +113 -0
  85. package/src/services/database/sqlite-transport.fixture.ts +30 -0
  86. package/src/services/database/sqlite-transport.ts +219 -0
  87. package/src/services/database/sqlite-worker.ts +437 -0
  88. package/src/services/database/surql-translate.ts +291 -0
  89. package/src/services/database/surreal-cache-engine.ts +141 -0
  90. package/src/services/logger/index.ts +6 -109
  91. package/src/services/persistence/localstorage.ts +2 -2
  92. package/src/services/persistence/resilient.ts +11 -4
  93. package/src/services/persistence/surrealdb.ts +10 -10
  94. package/src/services/stream-processor/index.ts +444 -52
  95. package/src/services/stream-processor/permissions.test.ts +47 -0
  96. package/src/services/stream-processor/permissions.ts +53 -0
  97. package/src/services/stream-processor/stream-processor.batch.test.ts +136 -0
  98. package/src/services/stream-processor/stream-processor.reset.test.ts +216 -0
  99. package/src/services/stream-processor/stream-processor.test.ts +1 -1
  100. package/src/services/stream-processor/wasm-types.ts +23 -2
  101. package/src/services/tabs/broker-client.ts +283 -0
  102. package/src/services/tabs/broker.test.ts +278 -0
  103. package/src/services/tabs/coordinator.test.ts +192 -0
  104. package/src/services/tabs/coordinator.ts +567 -0
  105. package/src/services/tabs/fake-ports.fixture.ts +70 -0
  106. package/src/services/tabs/leader-locks.ts +75 -0
  107. package/src/services/tabs/protocol.ts +239 -0
  108. package/src/services/tabs/support.ts +36 -0
  109. package/src/services/tabs/tabs-broker-worker.ts +581 -0
  110. package/src/sp00ky.auth-order.test.ts +92 -0
  111. package/src/sp00ky.init-query.test.ts +183 -0
  112. package/src/sp00ky.ts +1225 -0
  113. package/src/types.ts +342 -15
  114. package/src/utils/error-classification.test.ts +44 -0
  115. package/src/utils/error-classification.ts +7 -0
  116. package/src/utils/index.ts +35 -13
  117. package/src/utils/parser.ts +3 -2
  118. package/src/utils/semver.test.ts +32 -0
  119. package/src/utils/semver.ts +30 -0
  120. package/src/utils/surql.ts +30 -18
  121. package/src/utils/withRetry.test.ts +1 -1
  122. package/tsdown.config.ts +86 -1
  123. package/src/spooky.ts +0 -395
@@ -0,0 +1,142 @@
1
+ import { describe, it, expect } from 'vitest';
2
+ import { RecordId } from 'surrealdb';
3
+ import { DataModule } from './index';
4
+ import type { QueryState } from '../../types';
5
+
6
+ /**
7
+ * Tests for instant-hydrate's DataModule half: `applyHydration` — run-once,
8
+ * remoteArray priming, subscriber notify, and the epoch guard added when the
9
+ * hydrate fetch moved off the paint path into a background chain.
10
+ */
11
+
12
+ function makeLogger(): any {
13
+ const noop = () => {};
14
+ const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
15
+ logger.child = () => logger;
16
+ return logger;
17
+ }
18
+
19
+ function makeQueryState(hash: string): QueryState {
20
+ return {
21
+ config: {
22
+ id: new RecordId('_00_query', hash),
23
+ surql: 'SELECT * FROM user',
24
+ params: {},
25
+ localArray: [],
26
+ remoteArray: [],
27
+ ttl: '10m',
28
+ lastActiveAt: new Date(),
29
+ tableName: 'user',
30
+ },
31
+ records: [],
32
+ ttlTimer: null,
33
+ ttlDurationMs: 0,
34
+ updateCount: 0,
35
+ lastUpdatedAt: null,
36
+ materializationSamples: [],
37
+ lastIngestLatencyMs: null,
38
+ errorCount: 0,
39
+ status: 'fetching',
40
+ phaseSamples: {},
41
+ phaseLast: {},
42
+ registrationTimings: { parseMs: null, planMs: null, snapshotMs: null, wallMs: null },
43
+ };
44
+ }
45
+
46
+ const schema = { tables: [{ name: 'user', columns: {} }] } as any;
47
+
48
+ function makeRow(id: string, rv = 1) {
49
+ return { id: new RecordId('user', id), name: id, _00_rv: rv };
50
+ }
51
+
52
+ describe('DataModule.applyHydration', () => {
53
+ const hash = 'h1';
54
+
55
+ function setup({ epochFlipsOnSave = false } = {}) {
56
+ let epoch = 1;
57
+ const saved: any[] = [];
58
+ const cache: any = {
59
+ saveBatch: async (batch: any[]) => {
60
+ saved.push(...batch);
61
+ if (epochFlipsOnSave) epoch = 2;
62
+ },
63
+ };
64
+ const local: any = {
65
+ get epoch() {
66
+ return epoch;
67
+ },
68
+ query: async () => [[makeRow('a')]],
69
+ };
70
+ const dm = new DataModule(cache, local, schema, makeLogger(), 100);
71
+ const state = makeQueryState(hash);
72
+ (dm as any).activeQueries.set(hash, state);
73
+ return { dm, state, saved };
74
+ }
75
+
76
+ it('primes remoteArray, materializes and notifies subscribers', async () => {
77
+ const { dm, state, saved } = setup();
78
+ const emissions: any[] = [];
79
+ dm.subscribe(hash, (records) => emissions.push(records));
80
+
81
+ await dm.applyHydration(hash, [makeRow('a', 3)]);
82
+
83
+ expect(state.hydrated).toBe(true);
84
+ expect(state.config.remoteArray).toEqual([['user:a', 3]]);
85
+ expect(saved.length).toBe(1);
86
+ expect(emissions.length).toBe(1);
87
+ expect(dm.isCold(hash)).toBe(false);
88
+ });
89
+
90
+ it('runs once even when the remote returns nothing (hydrated flag)', async () => {
91
+ const { dm, state, saved } = setup();
92
+ await dm.applyHydration(hash, []);
93
+ expect(state.hydrated).toBe(true);
94
+ expect(saved).toEqual([]);
95
+ expect(dm.isCold(hash)).toBe(false); // hydrated → no longer cold
96
+ });
97
+
98
+ it('is a no-op for an unknown query', async () => {
99
+ const { dm, saved } = setup();
100
+ await dm.applyHydration('nope', [makeRow('a')]);
101
+ expect(saved).toEqual([]);
102
+ });
103
+
104
+ it('bails before mutating state when the bucket epoch moves mid-persist', async () => {
105
+ const { dm, state } = setup({ epochFlipsOnSave: true });
106
+ const emissions: any[] = [];
107
+ dm.subscribe(hash, (records) => emissions.push(records));
108
+
109
+ await dm.applyHydration(hash, [makeRow('a', 3)]);
110
+
111
+ // Rows fetched under the previous auth context must not prime the new
112
+ // bucket's query state — the rebind's re-registration refills it.
113
+ expect(state.config.remoteArray).toEqual([]);
114
+ expect(state.records).toEqual([]);
115
+ expect(emissions).toEqual([]);
116
+ });
117
+ });
118
+
119
+ describe('DataModule.getPreloadMarker', () => {
120
+ function makeDm(getById: (table: string, id: unknown) => Promise<any>) {
121
+ const local: any = { getById };
122
+ return new DataModule({} as any, local, schema, makeLogger(), 100);
123
+ }
124
+
125
+ it('returns the marker fields for a real row', async () => {
126
+ const dm = makeDm(async () => ({ fetchedAt: 123, rowCount: 5 }));
127
+ expect(await dm.getPreloadMarker('h')).toEqual({ fetchedAt: 123, rowCount: 5 });
128
+ });
129
+
130
+ it('returns null on a miss and on a non-object echo (SurrealDB string quirk)', async () => {
131
+ expect(await makeDm(async () => null).getPreloadMarker('h')).toBeNull();
132
+ // `FROM ONLY <string>` used to echo the id string back — must not read as warm.
133
+ expect(await makeDm(async () => 'h' as any).getPreloadMarker('h')).toBeNull();
134
+ });
135
+
136
+ it('returns null when the read throws', async () => {
137
+ const dm = makeDm(async () => {
138
+ throw new Error('boom');
139
+ });
140
+ expect(await dm.getPreloadMarker('h')).toBeNull();
141
+ });
142
+ });
@@ -0,0 +1,147 @@
1
+ import { describe, it, expect, beforeEach, vi } from 'vitest';
2
+ import { RecordId } from 'surrealdb';
3
+ import { DataModule } from './index';
4
+ import type { QueryState } from '../../types';
5
+
6
+ /**
7
+ * Tests for the local-bucket-switch surface of DataModule:
8
+ * - `quiesce()` disarms every debounce + TTL timer;
9
+ * - `rebindAfterBucketSwitch()` keeps query hashes (subscriptions stay
10
+ * attached), resets sync state, notifies subscribers with the emptied
11
+ * records so the previous user's rows leave the UI, re-registers the SSP
12
+ * view, and returns the hashes for remote re-registration;
13
+ * - stale-epoch stream updates are dropped instead of applied.
14
+ */
15
+
16
+ function makeLogger(): any {
17
+ const noop = () => {};
18
+ const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
19
+ logger.child = () => logger;
20
+ return logger;
21
+ }
22
+
23
+ function makeQueryState(hash: string, records: Record<string, any>[]): QueryState {
24
+ return {
25
+ config: {
26
+ id: new RecordId('_00_query', hash),
27
+ surql: 'SELECT * FROM user',
28
+ params: {},
29
+ localArray: [['user:a', 1]],
30
+ remoteArray: [['user:a', 1]],
31
+ ttl: '10m',
32
+ lastActiveAt: new Date(),
33
+ tableName: 'user',
34
+ },
35
+ records,
36
+ hydrated: true,
37
+ ttlTimer: null,
38
+ ttlDurationMs: 600_000,
39
+ updateCount: 3,
40
+ lastUpdatedAt: null,
41
+ materializationSamples: [],
42
+ lastIngestLatencyMs: null,
43
+ errorCount: 0,
44
+ status: 'idle',
45
+ phaseSamples: {},
46
+ phaseLast: {},
47
+ registrationTimings: { parseMs: null, planMs: null, snapshotMs: null, wallMs: null },
48
+ };
49
+ }
50
+
51
+ function makeHarness(epoch = 0) {
52
+ const localQueries: Array<{ query: unknown; vars: unknown; opts: unknown }> = [];
53
+ const local: any = {
54
+ epoch,
55
+ query: vi.fn(async (query: unknown, vars?: unknown, opts?: unknown) => {
56
+ localQueries.push({ query, vars, opts });
57
+ return [[]];
58
+ }),
59
+ };
60
+ const cache: any = {
61
+ registerQuery: vi.fn(() => ({ localArray: [] })),
62
+ };
63
+ const dm = new DataModule(cache, local, { tables: [] } as any, makeLogger(), 100);
64
+ return { dm, local, cache, localQueries };
65
+ }
66
+
67
+ describe('DataModule.quiesce', () => {
68
+ it('clears debounce and TTL timers', () => {
69
+ vi.useFakeTimers();
70
+ try {
71
+ const { dm } = makeHarness();
72
+ const qs = makeQueryState('h1', []);
73
+ qs.ttlTimer = setTimeout(() => {}, 60_000);
74
+ (dm as any).activeQueries.set('h1', qs);
75
+ (dm as any).debounceTimers.set('h1', setTimeout(() => {}, 60_000));
76
+
77
+ dm.quiesce();
78
+
79
+ expect(qs.ttlTimer).toBeNull();
80
+ expect((dm as any).debounceTimers.size).toBe(0);
81
+ expect(vi.getTimerCount()).toBe(0);
82
+ } finally {
83
+ vi.useRealTimers();
84
+ }
85
+ });
86
+ });
87
+
88
+ describe('DataModule.rebindAfterBucketSwitch', () => {
89
+ let harness: ReturnType<typeof makeHarness>;
90
+
91
+ beforeEach(() => {
92
+ harness = makeHarness();
93
+ (harness.dm as any).activeQueries.set(
94
+ 'h1',
95
+ makeQueryState('h1', [{ id: 'user:a', name: 'Previous User Row' }])
96
+ );
97
+ });
98
+
99
+ it('keeps the hash, resets sync state, and notifies subscribers with empty records', async () => {
100
+ const { dm, cache } = harness;
101
+ const emissions: unknown[][] = [];
102
+ dm.subscribe('h1', (records) => emissions.push(records as unknown[]));
103
+
104
+ const hashes = await dm.rebindAfterBucketSwitch();
105
+
106
+ expect(hashes).toEqual(['h1']);
107
+ const qs = (dm as any).activeQueries.get('h1') as QueryState;
108
+ expect(qs.records).toEqual([]);
109
+ expect(qs.config.localArray).toEqual([]);
110
+ expect(qs.config.remoteArray).toEqual([]);
111
+ expect(qs.hydrated).toBe(false);
112
+ expect(qs.status).toBe('fetching');
113
+ // Subscribers saw the previous user's rows drop out.
114
+ expect(emissions).toEqual([[]]);
115
+ // The SSP view was re-registered (on the fresh, post-reset processor).
116
+ expect(cache.registerQuery).toHaveBeenCalledWith(
117
+ expect.objectContaining({ queryHash: 'h1', surql: 'SELECT * FROM user' })
118
+ );
119
+ // The TTL heartbeat is re-armed.
120
+ expect(qs.ttlTimer).not.toBeNull();
121
+ if (qs.ttlTimer) clearTimeout(qs.ttlTimer);
122
+ });
123
+ });
124
+
125
+ describe('stale-epoch stream updates', () => {
126
+ it('drops an update whose chain started before a bucket switch', async () => {
127
+ const { dm, local } = makeHarness();
128
+ const qs = makeQueryState('h1', [{ id: 'user:a' }]);
129
+ (dm as any).activeQueries.set('h1', qs);
130
+
131
+ // The materialize read happens, then the epoch moves (bucket switched).
132
+ local.query.mockImplementation(async () => {
133
+ local.epoch = 1;
134
+ return [[{ id: 'user:b', name: 'other user row' }]];
135
+ });
136
+
137
+ await (dm as any).processStreamUpdate({
138
+ queryHash: 'h1',
139
+ localArray: [['user:b', 1]],
140
+ op: 'CREATE',
141
+ });
142
+
143
+ // Neither the records nor the persisted arrays moved.
144
+ expect(qs.records).toEqual([{ id: 'user:a' }]);
145
+ expect(qs.config.localArray).toEqual([['user:a', 1]]);
146
+ });
147
+ });
@@ -0,0 +1,113 @@
1
+ import { describe, it, expect, vi } from 'vitest';
2
+ import { DataModule } from './index';
3
+
4
+ /**
5
+ * Tests for `DataModule.run`, the one-shot outbox API.
6
+ *
7
+ * Recurring jobs used to live here too (`runRecurring` / `pokeRecurring` /
8
+ * `cancelRecurring`, which wrote a single durable row the runner re-armed
9
+ * forever). They are gone: schedules are now declared server-side under
10
+ * `schedules:` in sp00ky.yml, and the scheduler creates a fresh job row per
11
+ * cycle — so every row this API writes is exactly one execution.
12
+ *
13
+ * The create/update pipeline is spied, so these assert the orchestration
14
+ * (table resolution, argument validation, field building) without a real engine.
15
+ */
16
+
17
+ function makeLogger(): any {
18
+ const noop = () => {};
19
+ const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
20
+ logger.child = () => logger;
21
+ return logger;
22
+ }
23
+
24
+ const schema = {
25
+ tables: [{ name: 'job', columns: {} }],
26
+ backends: {
27
+ gamesync: {
28
+ outboxTable: 'job',
29
+ routes: {
30
+ '/syncGames': {
31
+ args: { connection: { optional: false }, since: { optional: true } },
32
+ },
33
+ },
34
+ },
35
+ noOutbox: {
36
+ routes: { '/whatever': { args: {} } },
37
+ },
38
+ },
39
+ };
40
+
41
+ const CONN = 'connection:CONN_abc';
42
+
43
+ function makeDm() {
44
+ const local = { query: vi.fn().mockResolvedValue([]) };
45
+ const dm = new DataModule({} as any, local as any, schema as any, makeLogger(), 100);
46
+ const create = vi.spyOn(dm, 'create').mockResolvedValue(undefined as any);
47
+ return { dm, local, create };
48
+ }
49
+
50
+ describe('DataModule.run', () => {
51
+ it('creates the one-shot job with status pending so the optimistic row reads in-flight', async () => {
52
+ const { dm, create } = makeDm();
53
+ await dm.run('gamesync' as any, '/syncGames' as any, { connection: CONN } as any, {
54
+ assignedTo: CONN,
55
+ });
56
+
57
+ expect(create).toHaveBeenCalledTimes(1);
58
+ const [id, record] = create.mock.calls[0] as [string, any];
59
+ expect(id.startsWith('job:')).toBe(true);
60
+ // The schema's DEFAULT ALWAYS "pending" only runs server-side; without the
61
+ // explicit field the local optimistic row has status undefined and
62
+ // in-flight indicators miss it until the first server echo.
63
+ expect(record.status).toBe('pending');
64
+ });
65
+
66
+ it('gives each call its own row', async () => {
67
+ const { dm, create } = makeDm();
68
+ await dm.run('gamesync' as any, '/syncGames' as any, { connection: CONN } as any);
69
+ await dm.run('gamesync' as any, '/syncGames' as any, { connection: CONN } as any);
70
+
71
+ const [firstId] = create.mock.calls[0] as [string, any];
72
+ const [secondId] = create.mock.calls[1] as [string, any];
73
+ expect(firstId).not.toBe(secondId);
74
+ });
75
+
76
+ it('carries the retry, timeout and delay options onto the row', async () => {
77
+ const { dm, create } = makeDm();
78
+ await dm.run('gamesync' as any, '/syncGames' as any, { connection: CONN } as any, {
79
+ assignedTo: CONN,
80
+ max_retries: 5,
81
+ retry_strategy: 'exponential',
82
+ timeout: 30,
83
+ delay: 60_000,
84
+ });
85
+
86
+ const [, record] = create.mock.calls[0] as [string, any];
87
+ expect(record.max_retries).toBe(5);
88
+ expect(record.retry_strategy).toBe('exponential');
89
+ expect(record.timeout).toBe(30);
90
+ expect(record.delay).toBe(60_000);
91
+ });
92
+
93
+ it('serializes the payload and rejects a missing required argument', async () => {
94
+ const { dm, create } = makeDm();
95
+ await dm.run('gamesync' as any, '/syncGames' as any, { connection: CONN } as any);
96
+ const [, record] = create.mock.calls[0] as [string, any];
97
+ expect(JSON.parse(record.payload)).toEqual({ connection: CONN });
98
+
99
+ await expect(
100
+ dm.run('gamesync' as any, '/syncGames' as any, {} as any)
101
+ ).rejects.toThrow(/connection/);
102
+ });
103
+
104
+ it('rejects an unknown route and a backend with no outbox table', async () => {
105
+ const { dm } = makeDm();
106
+ await expect(
107
+ dm.run('gamesync' as any, '/nope' as any, {} as any)
108
+ ).rejects.toThrow(/not found/);
109
+ await expect(
110
+ dm.run('noOutbox' as any, '/whatever' as any, {} as any)
111
+ ).rejects.toThrow(/Outbox table/);
112
+ });
113
+ });
@@ -0,0 +1,249 @@
1
+ import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
2
+ import { RecordId } from 'surrealdb';
3
+ import { DataModule } from './index';
4
+ import type { QueryState, QueryStatus } from '../../types';
5
+
6
+ /**
7
+ * Tests for the per-query fetch status (idle/fetching) added to DataModule:
8
+ * setQueryStatus updates the query object and notifies both the DevTools
9
+ * observer hook and subscribeStatus listeners; beginFetching/endFetching
10
+ * refcount overlapping fetch cycles; flushPendingStreamUpdate lands the
11
+ * debounced result before a query flips back to idle.
12
+ */
13
+
14
+ function makeLogger(): any {
15
+ const noop = () => {};
16
+ const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
17
+ logger.child = () => logger;
18
+ return logger;
19
+ }
20
+
21
+ function makeDataModule(): DataModule<any> {
22
+ return new DataModule(
23
+ {} as any, // cache — unused by status methods
24
+ {} as any, // local — unused by status methods
25
+ { tables: [] } as any, // schema — unused by status methods
26
+ makeLogger(),
27
+ 100
28
+ );
29
+ }
30
+
31
+ function makeQueryState(hash: string): QueryState {
32
+ return {
33
+ config: {
34
+ id: new RecordId('_00_query', hash),
35
+ surql: 'SELECT * FROM user',
36
+ params: {},
37
+ localArray: [],
38
+ remoteArray: [],
39
+ ttl: '10m',
40
+ lastActiveAt: new Date(),
41
+ tableName: 'user',
42
+ },
43
+ records: [],
44
+ ttlTimer: null,
45
+ ttlDurationMs: 0,
46
+ updateCount: 0,
47
+ lastUpdatedAt: null,
48
+ materializationSamples: [],
49
+ lastIngestLatencyMs: null,
50
+ errorCount: 0,
51
+ status: 'idle',
52
+ phaseSamples: {},
53
+ phaseLast: {},
54
+ registrationTimings: { parseMs: null, planMs: null, snapshotMs: null, wallMs: null },
55
+ };
56
+ }
57
+
58
+ describe('DataModule query fetch status', () => {
59
+ let dm: DataModule<any>;
60
+ const hash = 'h1';
61
+
62
+ beforeEach(() => {
63
+ dm = makeDataModule();
64
+ (dm as any).activeQueries.set(hash, makeQueryState(hash));
65
+ });
66
+
67
+ it('subscribeStatus with immediate reports the current status', () => {
68
+ const seen: QueryStatus[] = [];
69
+ dm.subscribeStatus(hash, (s) => seen.push(s), { immediate: true });
70
+ expect(seen).toEqual(['idle']);
71
+ });
72
+
73
+ it('setQueryStatus updates the query object and notifies subscribers + observer', () => {
74
+ const observed: Array<[string, QueryStatus]> = [];
75
+ dm.onQueryStatusChange = (h, s) => observed.push([h, s]);
76
+
77
+ const seen: QueryStatus[] = [];
78
+ dm.subscribeStatus(hash, (s) => seen.push(s));
79
+
80
+ dm.setQueryStatus(hash, 'fetching');
81
+ expect((dm as any).activeQueries.get(hash).status).toBe('fetching');
82
+ expect(seen).toEqual(['fetching']);
83
+ expect(observed).toEqual([[hash, 'fetching']]);
84
+
85
+ dm.setQueryStatus(hash, 'idle');
86
+ expect(seen).toEqual(['fetching', 'idle']);
87
+ expect(observed).toEqual([[hash, 'fetching'], [hash, 'idle']]);
88
+ });
89
+
90
+ it('setQueryStatus is a no-op when the status is unchanged', () => {
91
+ const seen: QueryStatus[] = [];
92
+ dm.subscribeStatus(hash, (s) => seen.push(s));
93
+ dm.setQueryStatus(hash, 'idle'); // already idle
94
+ expect(seen).toEqual([]);
95
+ });
96
+
97
+ it('setQueryStatus is a no-op for an unknown query', () => {
98
+ let called = false;
99
+ dm.onQueryStatusChange = () => {
100
+ called = true;
101
+ };
102
+ dm.setQueryStatus('does-not-exist', 'fetching');
103
+ expect(called).toBe(false);
104
+ });
105
+
106
+ it('unsubscribe stops further status notifications', () => {
107
+ const seen: QueryStatus[] = [];
108
+ const unsub = dm.subscribeStatus(hash, (s) => seen.push(s));
109
+ dm.setQueryStatus(hash, 'fetching');
110
+ unsub();
111
+ dm.setQueryStatus(hash, 'idle');
112
+ expect(seen).toEqual(['fetching']);
113
+ });
114
+ });
115
+
116
+ describe('DataModule beginFetching/endFetching refcount', () => {
117
+ let dm: DataModule<any>;
118
+ const hash = 'h1';
119
+ let seen: QueryStatus[];
120
+
121
+ beforeEach(() => {
122
+ dm = makeDataModule();
123
+ (dm as any).activeQueries.set(hash, makeQueryState(hash));
124
+ seen = [];
125
+ dm.subscribeStatus(hash, (s) => seen.push(s));
126
+ });
127
+
128
+ it('emits fetching on 0→1 and idle only on the last exit', () => {
129
+ dm.beginFetching(hash); // registration
130
+ dm.beginFetching(hash); // overlapping poll round
131
+ expect(seen).toEqual(['fetching']);
132
+
133
+ dm.endFetching(hash); // inner cycle finishes — must NOT emit idle
134
+ expect(seen).toEqual(['fetching']);
135
+ expect((dm as any).activeQueries.get(hash).status).toBe('fetching');
136
+
137
+ dm.endFetching(hash);
138
+ expect(seen).toEqual(['fetching', 'idle']);
139
+ });
140
+
141
+ it('unbalanced endFetching settles to idle without going negative', () => {
142
+ dm.endFetching(hash); // already idle → no-op notification
143
+ expect(seen).toEqual([]);
144
+ dm.beginFetching(hash);
145
+ dm.endFetching(hash);
146
+ expect(seen).toEqual(['fetching', 'idle']);
147
+ expect((dm as any).fetchDepth.has(hash)).toBe(false);
148
+ });
149
+ });
150
+
151
+ describe('DataModule pending stream-update flush', () => {
152
+ let dm: DataModule<any>;
153
+ const hash = 'h1';
154
+ let processed: any[];
155
+
156
+ const makeUpdate = (op: 'CREATE' | 'UPDATE' | 'DELETE') =>
157
+ ({ queryHash: hash, op, localArray: [] }) as any;
158
+
159
+ beforeEach(() => {
160
+ vi.useFakeTimers();
161
+ dm = makeDataModule();
162
+ (dm as any).activeQueries.set(hash, makeQueryState(hash));
163
+ processed = [];
164
+ (dm as any).processStreamUpdate = async (u: any) => {
165
+ processed.push(u);
166
+ };
167
+ });
168
+
169
+ afterEach(() => {
170
+ vi.useRealTimers();
171
+ });
172
+
173
+ it('flushPendingStreamUpdate processes the debounced update exactly once', async () => {
174
+ const update = makeUpdate('CREATE');
175
+ await dm.onStreamUpdate(update);
176
+ expect(processed).toEqual([]); // still debounced
177
+
178
+ await dm.flushPendingStreamUpdate(hash);
179
+ expect(processed).toEqual([update]);
180
+ expect((dm as any).debounceTimers.has(hash)).toBe(false);
181
+ expect((dm as any).pendingStreamUpdates.has(hash)).toBe(false);
182
+
183
+ // The cancelled timer must not process it a second time.
184
+ await vi.runAllTimersAsync();
185
+ expect(processed).toEqual([update]);
186
+
187
+ // Nothing pending → flush is a no-op.
188
+ await dm.flushPendingStreamUpdate(hash);
189
+ expect(processed).toEqual([update]);
190
+ });
191
+
192
+ it('the trailing-edge timer clears the pending entry itself', async () => {
193
+ const update = makeUpdate('UPDATE');
194
+ await dm.onStreamUpdate(update);
195
+ await vi.runAllTimersAsync();
196
+ expect(processed).toEqual([update]);
197
+ expect((dm as any).pendingStreamUpdates.has(hash)).toBe(false);
198
+ });
199
+
200
+ it('a DELETE supersedes and drops the pending coalesced update', async () => {
201
+ const create = makeUpdate('CREATE');
202
+ const del = makeUpdate('DELETE');
203
+ await dm.onStreamUpdate(create);
204
+ await dm.onStreamUpdate(del); // immediate, drops the pending CREATE
205
+ expect(processed).toEqual([del]);
206
+ expect((dm as any).pendingStreamUpdates.has(hash)).toBe(false);
207
+ await vi.runAllTimersAsync();
208
+ expect(processed).toEqual([del]);
209
+ });
210
+
211
+ it('finalizeDeregister clears pending update and fetch depth', async () => {
212
+ (dm as any).cache = { unregisterQuery: () => {} };
213
+ await dm.onStreamUpdate(makeUpdate('CREATE'));
214
+ dm.beginFetching(hash);
215
+ dm.finalizeDeregister(hash);
216
+ expect((dm as any).pendingStreamUpdates.has(hash)).toBe(false);
217
+ expect((dm as any).debounceTimers.has(hash)).toBe(false);
218
+ expect((dm as any).fetchDepth.has(hash)).toBe(false);
219
+ await vi.runAllTimersAsync();
220
+ expect(processed).toEqual([]);
221
+ });
222
+ });
223
+
224
+ describe('DataModule notifyQuerySynced', () => {
225
+ const hash = 'h1';
226
+
227
+ function makeDmWithLocal(rows: any[]): DataModule<any> {
228
+ const local: any = { query: async () => [rows] };
229
+ return new DataModule({} as any, local, { tables: [] } as any, makeLogger(), 100);
230
+ }
231
+
232
+ it('notifies once per registration lifetime even when records are unchanged and updateCount > 0', async () => {
233
+ const dm = makeDmWithLocal([]);
234
+ const state = makeQueryState(hash);
235
+ state.updateCount = 7; // persisted from a previous registration
236
+ (dm as any).activeQueries.set(hash, state);
237
+
238
+ let notified = 0;
239
+ dm.subscribe(hash, () => {
240
+ notified++;
241
+ });
242
+
243
+ await dm.notifyQuerySynced(hash); // empty result, unchanged — must still emit
244
+ expect(notified).toBe(1);
245
+
246
+ await dm.notifyQuerySynced(hash); // already notified this lifetime → silent
247
+ expect(notified).toBe(1);
248
+ });
249
+ });