@spooky-sync/client-solid 0.0.1-canary.37 → 0.0.1-canary.371

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.
package/src/index.ts CHANGED
@@ -6,9 +6,18 @@ import {
6
6
  type BucketHandle,
7
7
  type UpdateOptions,
8
8
  type RunOptions,
9
+ type SyncHealth,
10
+ type StorageHealth,
11
+ type PreloadOptions,
12
+ type PreloadRefresh,
13
+ type WebPushModule,
14
+ type Sp00kyChannel,
15
+ type ChannelQuery,
9
16
  } from '@spooky-sync/core';
10
17
 
11
18
  import type {
19
+ ChannelPeer,
20
+ ChannelTableNames,
12
21
  GetTable,
13
22
  QueryBuilder,
14
23
  SchemaStructure,
@@ -19,6 +28,7 @@ import type {
19
28
  RelationshipFieldsFromSchema,
20
29
  GetRelationship,
21
30
  RelatedFieldMapEntry,
31
+ FinalQuery,
22
32
  InnerQuery,
23
33
  BackendNames,
24
34
  BackendRoutes,
@@ -38,14 +48,72 @@ import { RecordId, Uuid, type Surreal } from 'surrealdb';
38
48
  export { RecordId, Uuid };
39
49
  export type { Model, GenericModel, GenericSchema, ModelPayload } from './lib/models';
40
50
  export { useQuery } from './lib/use-query';
51
+ export { createPreload } from './lib/create-preload';
52
+ export type { PreloadOptions, PreloadRefresh } from '@spooky-sync/core';
53
+ export { useSyncStatus, type UseSyncStatus } from './lib/use-sync-status';
54
+ export {
55
+ useImpersonation,
56
+ type UseImpersonation,
57
+ type UseImpersonationOptions,
58
+ } from './lib/use-impersonation';
59
+ export type {
60
+ SyncHealth,
61
+ SyncHealthStatus,
62
+ SyncHealthConfig,
63
+ ConnectionState,
64
+ ReconnectConfig,
65
+ } from '@spooky-sync/core';
66
+ export { useStorageStatus, type UseStorageStatus } from './lib/use-storage-status';
67
+ export type { StorageHealth, StorageHealthStatus } from '@spooky-sync/core';
68
+ export {
69
+ WebPushError,
70
+ type WebPushModule,
71
+ type WebPushConfig,
72
+ type WebPushSupport,
73
+ type WebPushUnsupportedReason,
74
+ type WebPushInfo,
75
+ type WebPushDevice,
76
+ type PushDeviceKind,
77
+ type WebPushSubscribeOptions,
78
+ type WebPushUnsubscribeOptions,
79
+ type WebPushSyncOptions,
80
+ type WebPushSyncStatus,
81
+ type WebPushUpdateOptions,
82
+ type WebPushMessageInput,
83
+ type WebPushMessage,
84
+ type WebPushErrorCode,
85
+ type WebPushClientMessage,
86
+ type PushPayload,
87
+ type PushNotification,
88
+ } from '@spooky-sync/core';
89
+ export { useCrdtField } from './lib/use-crdt-field';
90
+ export { useChannel, type UseChannel, type ChannelPeers, type ChannelQueries } from './lib/use-channel';
91
+ export type { ChannelState, ChannelStatus, ChannelOp, ChannelsConfig, Sp00kyChannel } from '@spooky-sync/core';
92
+ export { useFeatureFlag, type UseFeatureFlag } from './lib/use-feature-flag';
93
+ export {
94
+ useAppRelease,
95
+ type UseAppRelease,
96
+ type UseAppReleaseOptions,
97
+ } from './lib/use-app-release';
41
98
  export { useFileUpload, type FileUploadResult } from './lib/use-file-upload';
42
- export { useDownloadFile, type UseDownloadFileOptions, type UseDownloadFileResult } from './lib/use-download-file';
99
+ export {
100
+ useDownloadFile,
101
+ type UseDownloadFileOptions,
102
+ type UseDownloadFileResult,
103
+ } from './lib/use-download-file';
104
+ export { useBlurhash, type UseBlurhashResult } from './lib/use-blurhash';
105
+ export {
106
+ useBucketImage,
107
+ type UseBucketImageOptions,
108
+ type UseBucketImageResult,
109
+ } from './lib/use-bucket-image';
110
+ export { Blurhash, type BlurhashProps } from './lib/Blurhash';
111
+ export { BucketImage, type BucketImageProps } from './lib/BucketImage';
43
112
  export { Sp00kyProvider, type Sp00kyProviderProps } from './lib/Sp00kyProvider';
44
113
  export { useDb } from './lib/context';
45
114
 
46
115
  // export { AuthEventTypes } from "@spooky-sync/core"; // TODO: Verify if AuthEventTypes exists in core
47
116
 
48
-
49
117
  // Re-export query builder types for convenience
50
118
  export type {
51
119
  QueryModifier,
@@ -128,6 +196,19 @@ export class SyncedDb<S extends SchemaStructure> {
128
196
  this._initialized = true;
129
197
  }
130
198
 
199
+ /**
200
+ * Tear down the client: leaves the tabs broker, closes the local store and
201
+ * remote socket, and frees the wasm circuit. Without this a remounted provider
202
+ * (or an HMR reload) strands a whole client, and the abandoned wasm heaps stay
203
+ * resident because V8 cannot see how much wasm memory a dropped wrapper holds.
204
+ */
205
+ async close(): Promise<void> {
206
+ const instance = this.sp00ky;
207
+ this.sp00ky = null;
208
+ this._initialized = false;
209
+ if (instance) await instance.close();
210
+ }
211
+
131
212
  /**
132
213
  * Create a new record in the database
133
214
  */
@@ -159,12 +240,39 @@ export class SyncedDb<S extends SchemaStructure> {
159
240
  */
160
241
  async delete<TName extends TableNames<S>>(
161
242
  tableName: TName,
162
- selector: string | InnerQuery<GetTable<S, TName>, boolean>
243
+ selector: string | RecordId | InnerQuery<GetTable<S, TName>, boolean>
244
+ ): Promise<void> {
245
+ if (!this.sp00ky) throw new Error('SyncedDb not initialized');
246
+ // Accept a `"table:id"` string OR a RecordId — live-query rows carry their
247
+ // `id` as a RecordId, so callers can pass `db.delete('game', row.id)`
248
+ // directly. Build the canonical string from the raw id part (not
249
+ // `RecordId.toString()`, which escapes special chars) so it round-trips
250
+ // through the engine's `parseRecordIdString`. InnerQuery selectors are not
251
+ // supported yet. (cross-package RecordId instances → match by constructor name.)
252
+ const isRecordId =
253
+ selector instanceof RecordId || (selector as any)?.constructor?.name === 'RecordId';
254
+ let id: string;
255
+ if (typeof selector === 'string') {
256
+ id = selector;
257
+ } else if (isRecordId) {
258
+ id = `${tableName as string}:${(selector as RecordId).id}`;
259
+ } else {
260
+ throw new Error('Only string ID or RecordId selectors are supported currently with core');
261
+ }
262
+ await this.sp00ky.delete(tableName as string, id);
263
+ }
264
+
265
+ /**
266
+ * Preload/prewarm a built query into the local cache without registering a
267
+ * live view. Fetches once and stores the rows (+ embedded related children)
268
+ * locally so a later `useQuery` for the same data paints instantly. Best-effort.
269
+ */
270
+ public async preload(
271
+ finalQuery: FinalQuery<S, any, any, any, any, Sp00kyQueryResultPromise>,
272
+ options?: PreloadOptions
163
273
  ): Promise<void> {
164
274
  if (!this.sp00ky) throw new Error('SyncedDb not initialized');
165
- if (typeof selector !== 'string')
166
- throw new Error('Only string ID selectors are supported currently with core');
167
- await this.sp00ky.delete(tableName as string, selector);
275
+ await this.sp00ky.preload(finalQuery, options);
168
276
  }
169
277
 
170
278
  /**
@@ -177,17 +285,27 @@ export class SyncedDb<S extends SchemaStructure> {
177
285
  return this.sp00ky.query(table, {});
178
286
  }
179
287
 
288
+ /**
289
+ * Open a peer to peer channel to `peers` for the rows `query` matches (a
290
+ * query on a `-- @channel` table; only its `where` counts). Prefer the
291
+ * `useChannel` hook, which closes it with the component.
292
+ */
293
+ public channel<T extends ChannelTableNames<S>>(
294
+ query: ChannelQuery<S, T> | ReadonlyArray<ChannelQuery<S, T>>,
295
+ peers: Iterable<ChannelPeer>
296
+ ): Sp00kyChannel<S, T> {
297
+ if (!this.sp00ky) throw new Error('SyncedDb not initialized');
298
+ return this.sp00ky.channel(query, peers);
299
+ }
300
+
180
301
  /**
181
302
  * Run a backend operation
182
303
  */
183
- public async run<
184
- B extends BackendNames<S>,
185
- R extends BackendRoutes<S, B>,
186
- >(
304
+ public async run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(
187
305
  backend: B,
188
306
  path: R,
189
307
  payload: RoutePayload<S, B, R>,
190
- options?: RunOptions,
308
+ options?: RunOptions
191
309
  ): Promise<void> {
192
310
  if (!this.sp00ky) throw new Error('SyncedDb not initialized');
193
311
  await this.sp00ky.run(backend, path, payload, options);
@@ -213,6 +331,16 @@ export class SyncedDb<S extends SchemaStructure> {
213
331
  await this.signOut();
214
332
  }
215
333
 
334
+ /**
335
+ * Tell the client that this app's own impersonation banner is on screen.
336
+ * Only needed with `impersonationBanner: { mode: 'custom' }`; the
337
+ * `useImpersonation({ rendersBanner: true })` hook calls it for you.
338
+ */
339
+ public acknowledgeImpersonationBanner(): void {
340
+ if (!this.sp00ky) throw new Error('SyncedDb not initialized');
341
+ this.sp00ky.acknowledgeImpersonationBanner();
342
+ }
343
+
216
344
  /**
217
345
  * Sign out, clear session and local storage
218
346
  */
@@ -228,6 +356,23 @@ export class SyncedDb<S extends SchemaStructure> {
228
356
  if (!this.sp00ky) throw new Error('SyncedDb not initialized');
229
357
  return await this.sp00ky.useRemote(fn);
230
358
  }
359
+
360
+ /**
361
+ * Run one SurrealQL statement on the server and return its result array.
362
+ * Nothing is cached locally. Prefer this over `useRemote(s => s.query(...))`
363
+ * for a plain read or write: the bare SDK client that callback receives
364
+ * skips the connect gate, so a statement issued while the socket is being
365
+ * rebuilt fails with "Specify a namespace to use" instead of waiting for
366
+ * the session. This one is also bounded by the remote service's
367
+ * concurrency limit and query timeout.
368
+ */
369
+ public async remoteQuery<T extends unknown[] = unknown[]>(
370
+ sql: string,
371
+ vars?: Record<string, unknown>
372
+ ): Promise<T> {
373
+ if (!this.sp00ky) throw new Error('SyncedDb not initialized');
374
+ return await this.sp00ky.remoteQuery<T>(sql, vars);
375
+ }
231
376
  /**
232
377
  * Access the remote database service directly
233
378
  */
@@ -257,11 +402,59 @@ export class SyncedDb<S extends SchemaStructure> {
257
402
  return this.sp00ky.pendingMutationCount;
258
403
  }
259
404
 
405
+ /** Diagnostic — see `Sp00kyClient.liveRetryCount`. */
406
+ get liveRetryCount(): number {
407
+ if (!this.sp00ky) throw new Error('SyncedDb not initialized');
408
+ return this.sp00ky.liveRetryCount;
409
+ }
410
+
260
411
  subscribeToPendingMutations(cb: (count: number) => void): () => void {
261
412
  if (!this.sp00ky) throw new Error('SyncedDb not initialized');
262
413
  return this.sp00ky.subscribeToPendingMutations(cb);
263
414
  }
264
415
 
416
+ /** Current sync-health snapshot. See {@link useSyncStatus}. */
417
+ get syncHealth(): SyncHealth {
418
+ if (!this.sp00ky) throw new Error('SyncedDb not initialized');
419
+ return this.sp00ky.syncHealth;
420
+ }
421
+
422
+ /**
423
+ * Observe sync health. Fires immediately with the current status and again
424
+ * on every healthy↔degraded transition. Prefer the `useSyncStatus` hook in
425
+ * components; this is the imperative escape hatch.
426
+ */
427
+ subscribeToSyncHealth(cb: (health: SyncHealth) => void): () => void {
428
+ if (!this.sp00ky) throw new Error('SyncedDb not initialized');
429
+ return this.sp00ky.subscribeToSyncHealth(cb);
430
+ }
431
+
432
+ /** Current local-store durability snapshot. See {@link useStorageStatus}. */
433
+ get storageHealth(): StorageHealth {
434
+ if (!this.sp00ky) throw new Error('SyncedDb not initialized');
435
+ return this.sp00ky.storageHealth;
436
+ }
437
+
438
+ /**
439
+ * Observe local-store durability. Fires immediately with the current snapshot
440
+ * and again on change. Prefer the `useStorageStatus` hook in components; this
441
+ * is the imperative escape hatch.
442
+ */
443
+ subscribeToStorageHealth(cb: (health: StorageHealth) => void): () => void {
444
+ if (!this.sp00ky) throw new Error('SyncedDb not initialized');
445
+ return this.sp00ky.subscribeToStorageHealth(cb);
446
+ }
447
+
448
+ /**
449
+ * Web Push for this browser: `support()`, `subscribe()` (from a click),
450
+ * `devices()`, `notify()` / `test()` (push to yourself), `bridge()` for the
451
+ * service worker. See the push-notifications docs page.
452
+ */
453
+ get webPush(): WebPushModule {
454
+ if (!this.sp00ky) throw new Error('SyncedDb not initialized');
455
+ return this.sp00ky.webPush;
456
+ }
457
+
265
458
  bucket<B extends BucketNames<S>>(name: B): BucketHandle {
266
459
  if (!this.sp00ky) throw new Error('SyncedDb not initialized');
267
460
  return this.sp00ky.bucket(name);
@@ -0,0 +1,54 @@
1
+ import { createEffect } from 'solid-js';
2
+ import type { JSX } from 'solid-js';
3
+ import { decodeBlurhash } from '@spooky-sync/core';
4
+
5
+ export interface BlurhashProps {
6
+ /** The blurhash string. Nullish paints nothing (transparent canvas). */
7
+ hash: string | null | undefined;
8
+ /** Decode resolution. 32x32 is plenty: blurhash carries at most 9x9 DCT
9
+ * components, the canvas is meant to be CSS-scaled to fill. */
10
+ width?: number;
11
+ height?: number;
12
+ /** Contrast punch, see the blurhash reference decoder. Defaults to 1. */
13
+ punch?: number;
14
+ class?: string;
15
+ style?: string;
16
+ }
17
+
18
+ /**
19
+ * A blurhash painted onto a canvas, once per hash change. Size the canvas via
20
+ * `class`/`style` (e.g. `absolute inset-0 w-full h-full`); the internal decode
21
+ * resolution stays tiny regardless of the displayed size.
22
+ */
23
+ export function Blurhash(props: BlurhashProps): JSX.Element {
24
+ if (typeof document === 'undefined') return null;
25
+ const canvas = document.createElement('canvas');
26
+
27
+ createEffect(() => {
28
+ canvas.className = props.class ?? '';
29
+ });
30
+ createEffect(() => {
31
+ canvas.style.cssText = props.style ?? '';
32
+ });
33
+
34
+ createEffect(() => {
35
+ const width = props.width ?? 32;
36
+ const height = props.height ?? 32;
37
+ canvas.width = width;
38
+ canvas.height = height;
39
+ const hash = props.hash;
40
+ if (!hash) return;
41
+ try {
42
+ const pixels = decodeBlurhash(hash, width, height, props.punch ?? 1);
43
+ const ctx = canvas.getContext('2d');
44
+ if (!ctx) return;
45
+ const imageData = ctx.createImageData(width, height);
46
+ imageData.data.set(pixels);
47
+ ctx.putImageData(imageData, 0, 0);
48
+ } catch {
49
+ // An invalid hash paints nothing; the layer below stays visible.
50
+ }
51
+ });
52
+
53
+ return canvas;
54
+ }
@@ -0,0 +1,141 @@
1
+ import { createSignal, createEffect, onMount, onCleanup, children } from 'solid-js';
2
+ import type { JSX } from 'solid-js';
3
+ import type { BucketNames, SchemaStructure } from '@spooky-sync/query-builder';
4
+ import { useBucketImage, type UseBucketImageOptions } from './use-bucket-image';
5
+ import { Blurhash } from './Blurhash';
6
+
7
+ export interface BucketImageProps {
8
+ /** Bucket name from the schema. */
9
+ bucket: string;
10
+ /** Path within the bucket. Nullish renders only the fallback layers. */
11
+ path: string | null | undefined;
12
+ alt?: string;
13
+ /** Classes for the container element (sizing/positioning). */
14
+ class?: string;
15
+ /** Classes for the inner `<img>` (the layout styles are inline). */
16
+ imgClass?: string;
17
+ /** `object-fit` for the image. Defaults to `cover`. */
18
+ fit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
19
+ /**
20
+ * Bottom placeholder layer (your own plate/skeleton), shown until the image
21
+ * settles. The blurhash layer paints on top of it once the sidecar resolves.
22
+ */
23
+ fallback?: JSX.Element;
24
+ /** Crossfade duration in ms. Defaults to 300. */
25
+ transition?: number;
26
+ /** Crossfade easing. Defaults to an ease-out-expo curve. */
27
+ easing?: string;
28
+ /** Resolve the blurhash sidecar. Defaults to true. */
29
+ blurhash?: boolean;
30
+ /** Download tuning, forwarded to the underlying `useDownloadFile`. */
31
+ options?: UseBucketImageOptions;
32
+ }
33
+
34
+ const LAYER_STYLE = 'position:absolute;inset:0;width:100%;height:100%;';
35
+
36
+ /**
37
+ * A bucket image that never pops in: it layers (bottom to top) your `fallback`
38
+ * plate, the automatically stored blurhash, and the real image, which stays
39
+ * transparent until the bitmap is DECODED and then crossfades over the
40
+ * placeholders. Placeholder layers unmount once the fade settles. Respects
41
+ * prefers-reduced-motion (instant swap). The container is made
42
+ * `position: relative` unless your `class` positions it already.
43
+ *
44
+ * ```tsx
45
+ * <BucketImage bucket="covers" path={row.cover_key} class="absolute inset-0"
46
+ * fallback={<MyPlate />} alt="" />
47
+ * ```
48
+ */
49
+ export function BucketImage(props: BucketImageProps): JSX.Element {
50
+ if (typeof document === 'undefined') return null;
51
+
52
+ const image = useBucketImage(
53
+ props.bucket as BucketNames<SchemaStructure>,
54
+ () => props.path,
55
+ { ...props.options, blurhash: props.blurhash !== false }
56
+ );
57
+
58
+ const reducedMotion =
59
+ typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
60
+
61
+ const root = document.createElement('div');
62
+ createEffect(() => {
63
+ root.className = props.class ?? '';
64
+ });
65
+ // Layers are absolutely positioned; give them an anchor without stomping on
66
+ // a caller class that already positions the container (inline would win).
67
+ onMount(() => {
68
+ if (getComputedStyle(root).position === 'static') root.style.position = 'relative';
69
+ });
70
+
71
+ const placeholder = document.createElement('div');
72
+ placeholder.style.cssText = LAYER_STYLE;
73
+ // Solid hands JSX props over as lazy thunks; `children` resolves them (and
74
+ // nested arrays/functions) to real nodes and keeps them alive reactively.
75
+ const fallbackHolder = document.createElement('div');
76
+ fallbackHolder.style.cssText = LAYER_STYLE;
77
+ placeholder.append(fallbackHolder);
78
+ const resolvedFallback = children(() => props.fallback);
79
+ createEffect(() => {
80
+ const nodes = resolvedFallback.toArray().filter((node) => node instanceof Node) as Node[];
81
+ fallbackHolder.replaceChildren(...nodes);
82
+ });
83
+ const hashCanvas = Blurhash({
84
+ get hash() {
85
+ return image.blurhash();
86
+ },
87
+ style: LAYER_STYLE,
88
+ });
89
+ if (hashCanvas instanceof Node) placeholder.append(hashCanvas);
90
+
91
+ const img = document.createElement('img');
92
+ img.decoding = 'async';
93
+ img.style.cssText = `${LAYER_STYLE}opacity:0;`;
94
+ createEffect(() => {
95
+ img.className = props.imgClass ?? '';
96
+ });
97
+ createEffect(() => {
98
+ img.style.objectFit = props.fit ?? 'cover';
99
+ });
100
+ createEffect(() => {
101
+ img.alt = props.alt ?? '';
102
+ });
103
+ createEffect(() => {
104
+ img.style.transition = reducedMotion
105
+ ? 'none'
106
+ : `opacity ${props.transition ?? 300}ms ${props.easing ?? 'cubic-bezier(0.16, 1, 0.3, 1)'}`;
107
+ });
108
+ createEffect(() => {
109
+ const url = image.url();
110
+ if (!url) {
111
+ img.removeAttribute('src');
112
+ return;
113
+ }
114
+ img.src = url;
115
+ image.gate(img);
116
+ });
117
+ createEffect(() => {
118
+ img.style.opacity = image.ready() ? '1' : '0';
119
+ });
120
+
121
+ // Placeholders leave the DOM once the fade is over (a shelf of covers should
122
+ // not composite three layers each forever) and come back when the path
123
+ // changes mid-life (`ready` re-arms via the hook).
124
+ const [settled, setSettled] = createSignal(false);
125
+ createEffect(() => {
126
+ if (!image.ready()) {
127
+ setSettled(false);
128
+ return;
129
+ }
130
+ const wait = (reducedMotion ? 0 : (props.transition ?? 300)) + 120;
131
+ const timer = setTimeout(() => setSettled(true), wait);
132
+ onCleanup(() => clearTimeout(timer));
133
+ });
134
+ createEffect(() => {
135
+ if (settled()) placeholder.remove();
136
+ else if (!placeholder.isConnected) root.insertBefore(placeholder, img);
137
+ });
138
+
139
+ root.append(placeholder, img);
140
+ return root;
141
+ }
@@ -1,5 +1,12 @@
1
- import type { JSX} from 'solid-js';
2
- import { createSignal, onMount, createComponent, createMemo, mergeProps } from 'solid-js';
1
+ import type { JSX } from 'solid-js';
2
+ import {
3
+ createSignal,
4
+ onMount,
5
+ onCleanup,
6
+ createComponent,
7
+ createMemo,
8
+ mergeProps,
9
+ } from 'solid-js';
3
10
  import type { SchemaStructure } from '@spooky/query-builder';
4
11
  import type { SyncedDbConfig } from '../types';
5
12
  import { SyncedDb } from '../index';
@@ -10,6 +17,15 @@ export interface Sp00kyProviderProps<S extends SchemaStructure> {
10
17
  fallback?: JSX.Element;
11
18
  onError?: (error: Error) => void;
12
19
  onReady?: (db: SyncedDb<S>) => void;
20
+ /**
21
+ * Prewarm data into the local cache before revealing the UI. Runs after
22
+ * `init()`; the `fallback` stays visible until it resolves. Use awaitable
23
+ * `db.preload(...)` calls here to gate first-load on essential data (e.g.
24
+ * config). On warm loads preload returns instantly, so there's no perceptible
25
+ * gate after the first run. Best-effort: a rejection is caught and the UI is
26
+ * revealed anyway.
27
+ */
28
+ preload?: (db: SyncedDb<S>) => Promise<void>;
13
29
  children: JSX.Element;
14
30
  }
15
31
 
@@ -25,10 +41,41 @@ export function Sp00kyProvider<S extends SchemaStructure>(
25
41
 
26
42
  const [db, setDb] = createSignal<SyncedDb<S> | undefined>(undefined);
27
43
 
44
+ // `onMount` is async, so a dispose can land mid-init. Only that narrow race is
45
+ // handled here: an instance whose init finished AFTER the provider was already
46
+ // gone is closed, because nothing will ever reference it.
47
+ //
48
+ // A live, mounted client is deliberately NOT closed on cleanup. Doing that
49
+ // nulls `SyncedDb.sp00ky`, so every later `create`/`update`/`delete` throws
50
+ // "SyncedDb not initialized" while reads keep rendering from state that is
51
+ // already subscribed — i.e. mutations die silently and the app looks fine. In
52
+ // a host app the provider wraps the whole tree and only unmounts with the
53
+ // page, where the browser reclaims the worker anyway, so the leak this was
54
+ // meant to fix is worth far less than that risk.
55
+ let disposed = false;
56
+
57
+ onCleanup(() => {
58
+ disposed = true;
59
+ });
60
+
28
61
  onMount(async () => {
29
62
  try {
30
63
  const instance = new SyncedDb<S>(merged.config);
31
64
  await instance.init();
65
+ if (disposed) {
66
+ await instance.close();
67
+ return;
68
+ }
69
+ // Gate first-load UI on prewarmed data. Best-effort: never let a preload
70
+ // failure keep the app stuck on the fallback.
71
+ if (merged.preload) {
72
+ try {
73
+ await merged.preload(instance);
74
+ } catch (e) {
75
+ // oxlint-disable-next-line no-console
76
+ console.error('Sp00kyProvider: preload failed; revealing UI anyway', e);
77
+ }
78
+ }
32
79
  setDb(() => instance);
33
80
  merged.onReady?.(instance);
34
81
  } catch (e) {
@@ -0,0 +1,112 @@
1
+ import type {
2
+ ColumnSchema,
3
+ FinalQuery,
4
+ SchemaStructure,
5
+ TableNames,
6
+ } from '@spooky-sync/query-builder';
7
+ import { createEffect, useContext } from 'solid-js';
8
+ import { SyncedDb } from '..';
9
+ import type { Sp00kyQueryResultPromise, PreloadOptions as CorePreloadOptions } from '@spooky-sync/core';
10
+ import { Sp00kyContext } from './context';
11
+
12
+ type PreloadArg<
13
+ S extends SchemaStructure,
14
+ TableName extends TableNames<S>,
15
+ T extends { columns: Record<string, ColumnSchema> },
16
+ RelatedFields extends Record<string, any>,
17
+ IsOne extends boolean,
18
+ > =
19
+ | FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise>
20
+ | (() =>
21
+ | FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise>
22
+ | null
23
+ | undefined);
24
+
25
+ type PreloadOptions = CorePreloadOptions & {
26
+ /** Only preload while this returns true (defaults to always). */
27
+ enabled?: () => boolean;
28
+ };
29
+
30
+ // Overload: context-based (no explicit db)
31
+ export function createPreload<
32
+ S extends SchemaStructure,
33
+ TableName extends TableNames<S>,
34
+ T extends { columns: Record<string, ColumnSchema> },
35
+ RelatedFields extends Record<string, any>,
36
+ IsOne extends boolean,
37
+ >(
38
+ finalQuery: PreloadArg<S, TableName, T, RelatedFields, IsOne>,
39
+ options?: PreloadOptions,
40
+ ): void;
41
+
42
+ // Overload: explicit db
43
+ export function createPreload<
44
+ S extends SchemaStructure,
45
+ TableName extends TableNames<S>,
46
+ T extends { columns: Record<string, ColumnSchema> },
47
+ RelatedFields extends Record<string, any>,
48
+ IsOne extends boolean,
49
+ >(
50
+ db: SyncedDb<S>,
51
+ finalQuery: PreloadArg<S, TableName, T, RelatedFields, IsOne>,
52
+ options?: PreloadOptions,
53
+ ): void;
54
+
55
+ /**
56
+ * Reactive, fire-and-forget prewarm. Resolves the query (calling it if it's a
57
+ * function so it tracks reactive deps), dedupes on the query's stable identity
58
+ * hash, and registers it via `db.preload`: a live query nobody subscribes to,
59
+ * evicted a ttl after it was registered unless a view mounts it first. Nothing
60
+ * to clean up here.
61
+ *
62
+ * Typical use: inside a list row, preload the detail query the user is likely
63
+ * to open next, so navigation paints from cache instead of the network.
64
+ */
65
+ export function createPreload<
66
+ S extends SchemaStructure,
67
+ TableName extends TableNames<S>,
68
+ T extends { columns: Record<string, ColumnSchema> },
69
+ RelatedFields extends Record<string, any>,
70
+ IsOne extends boolean,
71
+ >(
72
+ dbOrQuery: SyncedDb<S> | PreloadArg<S, TableName, T, RelatedFields, IsOne>,
73
+ queryOrOptions?: PreloadArg<S, TableName, T, RelatedFields, IsOne> | PreloadOptions,
74
+ maybeOptions?: PreloadOptions,
75
+ ): void {
76
+ let db: SyncedDb<S>;
77
+ let finalQuery: PreloadArg<S, TableName, T, RelatedFields, IsOne>;
78
+ let options: PreloadOptions | undefined;
79
+
80
+ if (dbOrQuery instanceof SyncedDb) {
81
+ db = dbOrQuery;
82
+ finalQuery = queryOrOptions as PreloadArg<S, TableName, T, RelatedFields, IsOne>;
83
+ options = maybeOptions;
84
+ } else {
85
+ const contextDb = useContext(Sp00kyContext);
86
+ if (!contextDb) {
87
+ throw new Error(
88
+ 'createPreload: No db argument provided and no Sp00kyContext found. ' +
89
+ 'Either pass a SyncedDb instance or wrap your app in <Sp00kyProvider>.',
90
+ );
91
+ }
92
+ db = contextDb as SyncedDb<S>;
93
+ finalQuery = dbOrQuery;
94
+ options = queryOrOptions as PreloadOptions | undefined;
95
+ }
96
+
97
+ let prevHash: number | undefined;
98
+
99
+ createEffect(() => {
100
+ if (!(options?.enabled?.() ?? true)) return;
101
+
102
+ const query = typeof finalQuery === 'function' ? finalQuery() : finalQuery;
103
+ if (!query) return;
104
+
105
+ // Dedupe on the query's stable identity hash so a reactive re-run with an
106
+ // unchanged query doesn't refetch (the core also dedupes per session).
107
+ if (query.hash === prevHash) return;
108
+ prevHash = query.hash;
109
+
110
+ void db.getSp00ky().preload(query, { signal: options?.signal });
111
+ });
112
+ }