@spooky-sync/client-solid 0.0.1-canary.98 → 1.0.0-beta.2

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
@@ -7,9 +7,17 @@ import {
7
7
  type UpdateOptions,
8
8
  type RunOptions,
9
9
  type SyncHealth,
10
+ type StorageHealth,
11
+ type PreloadOptions,
12
+ type PreloadRefresh,
13
+ type WebPushModule,
14
+ type Sp00kyChannel,
15
+ type ChannelQuery,
10
16
  } from '@spooky-sync/core';
11
17
 
12
18
  import type {
19
+ ChannelPeer,
20
+ ChannelTableNames,
13
21
  GetTable,
14
22
  QueryBuilder,
15
23
  SchemaStructure,
@@ -20,6 +28,7 @@ import type {
20
28
  RelationshipFieldsFromSchema,
21
29
  GetRelationship,
22
30
  RelatedFieldMapEntry,
31
+ FinalQuery,
23
32
  InnerQuery,
24
33
  BackendNames,
25
34
  BackendRoutes,
@@ -39,18 +48,72 @@ import { RecordId, Uuid, type Surreal } from 'surrealdb';
39
48
  export { RecordId, Uuid };
40
49
  export type { Model, GenericModel, GenericSchema, ModelPayload } from './lib/models';
41
50
  export { useQuery } from './lib/use-query';
51
+ export { createPreload } from './lib/create-preload';
52
+ export type { PreloadOptions, PreloadRefresh } from '@spooky-sync/core';
42
53
  export { useSyncStatus, type UseSyncStatus } from './lib/use-sync-status';
43
- export type { SyncHealth, SyncHealthStatus, SyncHealthConfig } from '@spooky-sync/core';
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';
44
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';
45
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';
46
98
  export { useFileUpload, type FileUploadResult } from './lib/use-file-upload';
47
- 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';
48
112
  export { Sp00kyProvider, type Sp00kyProviderProps } from './lib/Sp00kyProvider';
49
113
  export { useDb } from './lib/context';
50
114
 
51
115
  // export { AuthEventTypes } from "@spooky-sync/core"; // TODO: Verify if AuthEventTypes exists in core
52
116
 
53
-
54
117
  // Re-export query builder types for convenience
55
118
  export type {
56
119
  QueryModifier,
@@ -133,6 +196,19 @@ export class SyncedDb<S extends SchemaStructure> {
133
196
  this._initialized = true;
134
197
  }
135
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
+
136
212
  /**
137
213
  * Create a new record in the database
138
214
  */
@@ -186,6 +262,19 @@ export class SyncedDb<S extends SchemaStructure> {
186
262
  await this.sp00ky.delete(tableName as string, id);
187
263
  }
188
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
273
+ ): Promise<void> {
274
+ if (!this.sp00ky) throw new Error('SyncedDb not initialized');
275
+ await this.sp00ky.preload(finalQuery, options);
276
+ }
277
+
189
278
  /**
190
279
  * Query data from the database
191
280
  */
@@ -196,17 +285,27 @@ export class SyncedDb<S extends SchemaStructure> {
196
285
  return this.sp00ky.query(table, {});
197
286
  }
198
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
+
199
301
  /**
200
302
  * Run a backend operation
201
303
  */
202
- public async run<
203
- B extends BackendNames<S>,
204
- R extends BackendRoutes<S, B>,
205
- >(
304
+ public async run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(
206
305
  backend: B,
207
306
  path: R,
208
307
  payload: RoutePayload<S, B, R>,
209
- options?: RunOptions,
308
+ options?: RunOptions
210
309
  ): Promise<void> {
211
310
  if (!this.sp00ky) throw new Error('SyncedDb not initialized');
212
311
  await this.sp00ky.run(backend, path, payload, options);
@@ -232,6 +331,16 @@ export class SyncedDb<S extends SchemaStructure> {
232
331
  await this.signOut();
233
332
  }
234
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
+
235
344
  /**
236
345
  * Sign out, clear session and local storage
237
346
  */
@@ -247,6 +356,23 @@ export class SyncedDb<S extends SchemaStructure> {
247
356
  if (!this.sp00ky) throw new Error('SyncedDb not initialized');
248
357
  return await this.sp00ky.useRemote(fn);
249
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
+ }
250
376
  /**
251
377
  * Access the remote database service directly
252
378
  */
@@ -303,6 +429,32 @@ export class SyncedDb<S extends SchemaStructure> {
303
429
  return this.sp00ky.subscribeToSyncHealth(cb);
304
430
  }
305
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
+
306
458
  bucket<B extends BucketNames<S>>(name: B): BucketHandle {
307
459
  if (!this.sp00ky) throw new Error('SyncedDb not initialized');
308
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
+ }