@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/AGENTS.md +10 -5
- package/README.md +20 -0
- package/dist/index.cjs +630 -120
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +378 -5
- package/dist/index.d.cts.map +1 -1
- package/dist/index.d.ts +378 -5
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +618 -123
- package/dist/index.js.map +1 -1
- package/package.json +6 -5
- package/skills/sp00ky-solid/SKILL.md +90 -1
- package/skills/sp00ky-solid/references/file-hooks.md +33 -4
- package/src/index.ts +160 -8
- package/src/lib/Blurhash.ts +54 -0
- package/src/lib/BucketImage.ts +141 -0
- package/src/lib/Sp00kyProvider.ts +49 -2
- package/src/lib/create-preload.ts +112 -0
- package/src/lib/use-app-release.ts +89 -0
- package/src/lib/use-blurhash.ts +77 -0
- package/src/lib/use-bucket-image.ts +100 -0
- package/src/lib/use-channel.ts +105 -0
- package/src/lib/use-crdt-field.ts +46 -49
- package/src/lib/use-download-file.ts +65 -109
- package/src/lib/use-file-upload.ts +8 -3
- package/src/lib/use-impersonation.ts +44 -0
- package/src/lib/use-query.ts +65 -2
- package/src/lib/use-storage-status.ts +44 -0
- package/src/lib/use-sync-status.ts +26 -1
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
|
|
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 {
|
|
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 {
|
|
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
|
+
}
|