@spooky-sync/client-solid 0.0.1-canary.38 → 0.0.1-canary.380

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.
@@ -0,0 +1,89 @@
1
+ import { createSignal, onCleanup, type Accessor } from 'solid-js';
2
+ import { useDb } from './context';
3
+ import { semverGt, type AppReleaseOptions, type AppReleaseSnapshot } from '@spooky-sync/core';
4
+
5
+ export interface UseAppReleaseOptions extends AppReleaseOptions {
6
+ /** App name from sp00ky.yml, e.g. `web`. */
7
+ app: string;
8
+ /**
9
+ * The running build's version (X.Y.Z), typically baked in at build time
10
+ * (e.g. a vite `define` from package.json). `updateAvailable()` is true when
11
+ * the announced release is semver-newer than this.
12
+ */
13
+ currentVersion: string;
14
+ }
15
+
16
+ export interface UseAppRelease {
17
+ /** Latest announced version for the app, or undefined when no row exists. */
18
+ latestVersion: Accessor<string | undefined>;
19
+ /** Announced version is semver-newer than the running build. */
20
+ updateAvailable: Accessor<boolean>;
21
+ /** The newer release asks clients to update/reload without prompting. */
22
+ mandatory: Accessor<boolean>;
23
+ /** The newer release asks reloads to clear service-worker caches first. */
24
+ cacheBust: Accessor<boolean>;
25
+ /**
26
+ * Reload onto the announced release. Plain `location.reload()` normally;
27
+ * when the release is flagged cache-bust, CacheStorage is cleared, the
28
+ * service-worker registration is nudged to update, and navigation carries a
29
+ * `?cb=` token to punch through intermediary caches. The service worker is
30
+ * deliberately NOT unregistered: navigating while still controlled by a
31
+ * just-unregistered worker strands subresource fetches on the dead worker
32
+ * and the page hangs until a manual reload.
33
+ */
34
+ reload: () => Promise<void>;
35
+ }
36
+
37
+ async function reloadForSnapshot(snapshot: AppReleaseSnapshot): Promise<void> {
38
+ if (typeof window === 'undefined') return;
39
+ if (snapshot.cacheBust) {
40
+ try {
41
+ if (window.caches) {
42
+ const keys = await window.caches.keys();
43
+ await Promise.all(keys.map((k) => window.caches.delete(k)));
44
+ }
45
+ if (navigator.serviceWorker) {
46
+ const regs = await navigator.serviceWorker.getRegistrations();
47
+ for (const r of regs) r.update().catch(() => {});
48
+ }
49
+ window.location.href = window.location.pathname + '?cb=' + Date.now();
50
+ return;
51
+ } catch {
52
+ /* fall through to a plain reload */
53
+ }
54
+ }
55
+ window.location.reload();
56
+ }
57
+
58
+ /**
59
+ * Observe the app's announced release (`_00_app_release:<app>`, written by
60
+ * `spky deploy` / `spky release`) and compare it against the running build.
61
+ *
62
+ * Typical use: mount a small "new version available — Reload" notification
63
+ * gated on `updateAvailable()`, auto-invoking `reload()` when `mandatory()`
64
+ * (guard the auto path against reload loops with a per-version marker, since
65
+ * a client can reload while the deploy is still rolling out and land on the
66
+ * old bundle again).
67
+ */
68
+ export function useAppRelease(options: UseAppReleaseOptions): UseAppRelease {
69
+ const db = useDb();
70
+ const handle = db.getSp00ky().appRelease(options.app, { ttl: options.ttl });
71
+
72
+ const [snapshot, setSnapshot] = createSignal<AppReleaseSnapshot>(handle.snapshot());
73
+ const unsub = handle.subscribe(setSnapshot);
74
+
75
+ onCleanup(() => {
76
+ unsub();
77
+ handle.close();
78
+ });
79
+
80
+ const updateAvailable = () => semverGt(snapshot().version, options.currentVersion);
81
+
82
+ return {
83
+ latestVersion: () => snapshot().version,
84
+ updateAvailable,
85
+ mandatory: () => updateAvailable() && snapshot().mandatory,
86
+ cacheBust: () => snapshot().cacheBust,
87
+ reload: () => reloadForSnapshot(snapshot()),
88
+ };
89
+ }
@@ -0,0 +1,77 @@
1
+ import { createSignal, createEffect, onCleanup, type Accessor } from 'solid-js';
2
+ import type { SchemaStructure, BucketNames } from '@spooky-sync/query-builder';
3
+ import type { SyncedDb } from '../index';
4
+ import { useDb } from './context';
5
+
6
+ export interface UseBlurhashResult {
7
+ /** The stored blurhash for the path, or null while loading / when none exists. */
8
+ hash: Accessor<string | null>;
9
+ isLoading: Accessor<boolean>;
10
+ }
11
+
12
+ /**
13
+ * The blurhash sidecar for a bucket image (written automatically by
14
+ * `bucket.put`, see `Sp00kyConfig.blurhash`). Resolves from OPFS instantly on
15
+ * warm clients; a miss is remembered per tab. Use this directly when the hash
16
+ * belongs to a different rendition than the displayed image; otherwise
17
+ * `useBucketImage` / `BucketImage` bundle it with the download.
18
+ */
19
+ export function useBlurhash<S extends SchemaStructure>(
20
+ bucketName: BucketNames<S>,
21
+ path: Accessor<string | null | undefined>
22
+ ): UseBlurhashResult;
23
+ export function useBlurhash<S extends SchemaStructure>(
24
+ db: SyncedDb<S>,
25
+ bucketName: BucketNames<S>,
26
+ path: Accessor<string | null | undefined>
27
+ ): UseBlurhashResult;
28
+ export function useBlurhash<S extends SchemaStructure>(
29
+ dbOrBucketName: SyncedDb<S> | BucketNames<S>,
30
+ bucketNameOrPath?: BucketNames<S> | Accessor<string | null | undefined>,
31
+ maybePath?: Accessor<string | null | undefined>
32
+ ): UseBlurhashResult {
33
+ let db: SyncedDb<S>;
34
+ let bucketName: BucketNames<S>;
35
+ let path: Accessor<string | null | undefined>;
36
+
37
+ if (typeof dbOrBucketName === 'string') {
38
+ db = useDb<S>();
39
+ bucketName = dbOrBucketName as BucketNames<S>;
40
+ path = bucketNameOrPath as Accessor<string | null | undefined>;
41
+ } else {
42
+ db = dbOrBucketName as SyncedDb<S>;
43
+ bucketName = bucketNameOrPath as BucketNames<S>;
44
+ path = maybePath as Accessor<string | null | undefined>;
45
+ }
46
+
47
+ const [hash, setHash] = createSignal<string | null>(null);
48
+ const [isLoading, setIsLoading] = createSignal(false);
49
+
50
+ createEffect(() => {
51
+ const filePath = path();
52
+ if (!filePath) {
53
+ setHash(null);
54
+ setIsLoading(false);
55
+ return;
56
+ }
57
+ let cancelled = false;
58
+ setIsLoading(true);
59
+ db.bucket(bucketName)
60
+ .blurhash(filePath)
61
+ .then((result) => {
62
+ if (cancelled) return;
63
+ setHash(result);
64
+ setIsLoading(false);
65
+ })
66
+ .catch(() => {
67
+ if (cancelled) return;
68
+ setHash(null);
69
+ setIsLoading(false);
70
+ });
71
+ onCleanup(() => {
72
+ cancelled = true;
73
+ });
74
+ });
75
+
76
+ return { hash, isLoading };
77
+ }
@@ -0,0 +1,100 @@
1
+ import { createSignal, createEffect, on, type Accessor } from 'solid-js';
2
+ import type { SchemaStructure, BucketNames } from '@spooky-sync/query-builder';
3
+ import type { SyncedDb } from '../index';
4
+ import { useDb } from './context';
5
+ import {
6
+ useDownloadFile,
7
+ type UseDownloadFileOptions,
8
+ type UseDownloadFileResult,
9
+ } from './use-download-file';
10
+ import { useBlurhash } from './use-blurhash';
11
+
12
+ export interface UseBucketImageOptions extends UseDownloadFileOptions {
13
+ /**
14
+ * Also resolve the image's blurhash sidecar (see `Sp00kyConfig.blurhash`).
15
+ * Default `true`; the read is registered before the image bytes so the tiny
16
+ * sidecar tends to land first on the serialized remote chain.
17
+ */
18
+ blurhash?: boolean;
19
+ }
20
+
21
+ export interface UseBucketImageResult extends UseDownloadFileResult {
22
+ /** Blurhash for the same path, or null (off, missing, still loading). */
23
+ blurhash: Accessor<string | null>;
24
+ /** True once the current `url()` has been decoded and is safe to paint. */
25
+ ready: Accessor<boolean>;
26
+ /**
27
+ * Ref callback for the `<img>` rendering `url()`: flips `ready` when the
28
+ * bitmap is decoded (resolves on failure too, so a broken blob degrades to
29
+ * paint-on-load instead of hiding the image forever). Re-arms itself when
30
+ * the url changes.
31
+ */
32
+ gate: (img: HTMLImageElement) => void;
33
+ }
34
+
35
+ /**
36
+ * Everything needed to render a bucket image without a pop-in: the refcounted
37
+ * object URL, the blurhash placeholder, and a decode gate so the real bitmap
38
+ * is only revealed once it can paint in full. `BucketImage` wraps this into a
39
+ * drop-in component; use the hook for custom markup.
40
+ */
41
+ export function useBucketImage<S extends SchemaStructure>(
42
+ bucketName: BucketNames<S>,
43
+ path: Accessor<string | null | undefined>,
44
+ options?: UseBucketImageOptions
45
+ ): UseBucketImageResult;
46
+ export function useBucketImage<S extends SchemaStructure>(
47
+ db: SyncedDb<S>,
48
+ bucketName: BucketNames<S>,
49
+ path: Accessor<string | null | undefined>,
50
+ options?: UseBucketImageOptions
51
+ ): UseBucketImageResult;
52
+ export function useBucketImage<S extends SchemaStructure>(
53
+ dbOrBucketName: SyncedDb<S> | BucketNames<S>,
54
+ bucketNameOrPath?: BucketNames<S> | Accessor<string | null | undefined>,
55
+ pathOrOptions?: Accessor<string | null | undefined> | UseBucketImageOptions,
56
+ maybeOptions?: UseBucketImageOptions
57
+ ): UseBucketImageResult {
58
+ let db: SyncedDb<S>;
59
+ let bucketName: BucketNames<S>;
60
+ let path: Accessor<string | null | undefined>;
61
+ let options: UseBucketImageOptions;
62
+
63
+ if (typeof dbOrBucketName === 'string') {
64
+ db = useDb<S>();
65
+ bucketName = dbOrBucketName as BucketNames<S>;
66
+ path = bucketNameOrPath as Accessor<string | null | undefined>;
67
+ options = (pathOrOptions as UseBucketImageOptions) ?? {};
68
+ } else {
69
+ db = dbOrBucketName as SyncedDb<S>;
70
+ bucketName = bucketNameOrPath as BucketNames<S>;
71
+ path = pathOrOptions as Accessor<string | null | undefined>;
72
+ options = maybeOptions ?? {};
73
+ }
74
+
75
+ // Registered BEFORE the download so the sidecar read enters the serialized
76
+ // remote queue first: the placeholder should never wait behind the bytes it
77
+ // is standing in for.
78
+ const wantHash = options.blurhash !== false;
79
+ const { hash } = useBlurhash(db, bucketName, () => (wantHash ? path() : null));
80
+
81
+ const file = useDownloadFile(db, bucketName, path, options);
82
+
83
+ const [ready, setReady] = createSignal(false);
84
+ // A new url (path change, refetch) means a new undecoded bitmap.
85
+ createEffect(on(file.url, () => setReady(false), { defer: true }));
86
+
87
+ const gate = (img: HTMLImageElement) => {
88
+ const done = () => setReady(true);
89
+ if (typeof img.decode === 'function') {
90
+ img.decode().then(done, done);
91
+ } else if (img.complete) {
92
+ done();
93
+ } else {
94
+ img.onload = done;
95
+ img.onerror = done;
96
+ }
97
+ };
98
+
99
+ return { ...file, blurhash: hash, ready, gate };
100
+ }
@@ -0,0 +1,105 @@
1
+ import { createEffect, createSignal, onCleanup, untrack, useContext } from 'solid-js';
2
+ import type { ChannelPeer, ChannelTableNames, SchemaStructure } from '@spooky-sync/query-builder';
3
+ import type { ChannelQuery, ChannelState, ChannelStatus, Sp00kyChannel } from '@spooky-sync/core';
4
+ import type { SyncedDb } from '..';
5
+ import { Sp00kyContext } from './context';
6
+
7
+ /** Who a channel connects to: a list, or an accessor of one (re-read when it changes). */
8
+ export type ChannelPeers = Iterable<ChannelPeer> | (() => Iterable<ChannelPeer> | null | undefined);
9
+
10
+ /** What a channel carries: the rows a query (or several) matches. */
11
+ export type ChannelQueries<S extends SchemaStructure, T extends ChannelTableNames<S>> =
12
+ | ChannelQuery<S, T>
13
+ | ReadonlyArray<ChannelQuery<S, T>>;
14
+
15
+ /** An open channel, for as long as the component lives. */
16
+ export interface UseChannel<S extends SchemaStructure, T extends string> {
17
+ /** `idle` | `connecting` | `connected` | `failed` | `unsupported`. */
18
+ status: () => ChannelStatus;
19
+ /** Users with a tab connected. */
20
+ peers: () => ReadonlyArray<string>;
21
+ /** Writes that go to THIS channel's peers only (when the row matches its query), plus the database as always. */
22
+ update: Sp00kyChannel<S, T>['update'];
23
+ create: Sp00kyChannel<S, T>['create'];
24
+ delete: Sp00kyChannel<S, T>['delete'];
25
+ }
26
+
27
+ const IDLE: ChannelState = { status: 'idle', peers: [] };
28
+
29
+ /**
30
+ * Open a peer to peer channel to `peers` for the rows `query` matches, for
31
+ * the lifetime of the component. The query must be on a `-- @channel` table
32
+ * and only its `where` counts; it is checked against each row, never
33
+ * registered. Writes to matching rows (`db.update` / `db.create` /
34
+ * `db.delete`, or the channel's own) reach the peers over WebRTC in tens of
35
+ * ms; `-- @ephemeral` fields travel only this way. A connection forms when
36
+ * both sides list each other; your own id is skipped.
37
+ *
38
+ * ```ts
39
+ * const ch = useChannel(
40
+ * () => db.query('message').where({ conversation: convoId() }),
41
+ * () => [me(), other()]
42
+ * );
43
+ * ```
44
+ *
45
+ * `query` may be an accessor (re-read when it changes; `null` closes the
46
+ * channel until it returns a query again) or a list of queries.
47
+ */
48
+ export function useChannel<S extends SchemaStructure, T extends ChannelTableNames<S>>(
49
+ query: ChannelQueries<S, T> | (() => ChannelQueries<S, T> | null | undefined),
50
+ peers: ChannelPeers
51
+ ): UseChannel<S, T> {
52
+ const db = useContext(Sp00kyContext);
53
+ if (!db) throw new Error('useChannel must be used within a <Sp00kyProvider>.');
54
+ const queries = query as ChannelQueries<any, any> | (() => ChannelQueries<any, any> | null | undefined);
55
+ const readQueries = () => (typeof queries === 'function' ? queries() : queries);
56
+ const readPeers = () => (typeof peers === 'function' ? (peers() ?? []) : peers);
57
+ const [state, setState] = createSignal<ChannelState>(IDLE);
58
+
59
+ let channel: Sp00kyChannel<any, any> | null = null;
60
+ let stop = () => {};
61
+ const close = () => {
62
+ stop();
63
+ channel?.close();
64
+ channel = null;
65
+ setState(IDLE);
66
+ };
67
+ const sync = (q: ChannelQueries<any, any> | null | undefined) => {
68
+ if (!q) return close();
69
+ if (channel) return channel.setQueries(q);
70
+ channel = (db as SyncedDb<any>).channel(q, untrack(readPeers));
71
+ stop = channel.subscribe(setState);
72
+ };
73
+ sync(untrack(readQueries));
74
+
75
+ if (typeof queries === 'function') {
76
+ let first = true;
77
+ createEffect(() => {
78
+ const q = queries();
79
+ if (first) return void (first = false);
80
+ sync(q);
81
+ });
82
+ }
83
+ if (typeof peers === 'function') {
84
+ let first = true;
85
+ createEffect(() => {
86
+ const next = [...readPeers()];
87
+ if (first) return void (first = false);
88
+ channel?.setPeers(next);
89
+ });
90
+ }
91
+
92
+ onCleanup(close);
93
+
94
+ const open = () => {
95
+ if (!channel) throw new Error('This channel is closed (its query accessor returned nothing).');
96
+ return channel;
97
+ };
98
+ return {
99
+ status: () => state().status,
100
+ peers: () => state().peers,
101
+ update: ((...args: Parameters<Sp00kyChannel<any, any>['update']>) => open().update(...args)) as UseChannel<S, T>['update'],
102
+ create: ((...args: Parameters<Sp00kyChannel<any, any>['create']>) => open().create(...args)) as UseChannel<S, T>['create'],
103
+ delete: ((...args: Parameters<Sp00kyChannel<any, any>['delete']>) => open().delete(...args)) as UseChannel<S, T>['delete'],
104
+ };
105
+ }
@@ -0,0 +1,65 @@
1
+ import { createEffect, createMemo, createSignal, on, onCleanup, useContext, type Accessor } from 'solid-js';
2
+ import { Sp00kyContext } from './context';
3
+ import type { CrdtField } from '@spooky-sync/core';
4
+
5
+ /**
6
+ * Open a `@crdt` field of the record `recordId()` names, for an editor to bind
7
+ * to (`field()?.getDoc()`). Re-opens when the id changes; closes on cleanup.
8
+ *
9
+ * The accessor stays `null` until the field is loaded (`CrdtField.isLoaded`):
10
+ * this device had the document, or the server answered. Until then the
11
+ * document may be empty only because nothing has arrived yet, so show the
12
+ * column's text instead of binding an editor to it.
13
+ */
14
+ export function useCrdtField(
15
+ table: string,
16
+ recordId: () => string | undefined,
17
+ field: string,
18
+ ): Accessor<CrdtField | null> {
19
+ const db = useContext(Sp00kyContext);
20
+ if (!db) {
21
+ throw new Error('useCrdtField must be used within a <Sp00kyProvider>');
22
+ }
23
+
24
+ const [crdtField, setCrdtField] = createSignal<CrdtField | null>(null);
25
+ // Only a different id reopens: `recordId` may re-run on every live update.
26
+ const id = createMemo(recordId);
27
+
28
+ createEffect(
29
+ on(id, (current) => {
30
+ if (!current) return;
31
+ const sp00ky = db.getSp00ky();
32
+ let active = true;
33
+ let opened = false;
34
+ let offLoaded = () => {};
35
+ sp00ky
36
+ .openCrdtField(table, current, field)
37
+ .then((cf) => {
38
+ opened = true;
39
+ if (!active) {
40
+ void sp00ky.closeCrdtField(table, current, field);
41
+ return;
42
+ }
43
+ offLoaded = cf.onLoaded(() => {
44
+ if (active) setCrdtField(cf);
45
+ });
46
+ })
47
+ .catch((err) => {
48
+ // A silent rejection leaves the consumer's `Show when={field()}` on
49
+ // its fallback for good, with no trail. Surface the cause (missing
50
+ // `@crdt` annotation, schema codegen drift, local DB failure, ...).
51
+ console.error(`[useCrdtField] Failed to open CRDT field ${table}.${field} on ${current}:`, err);
52
+ });
53
+ // Runs before the next id opens, and on unmount. Closing a field whose
54
+ // open is still in flight is left to the `then` above.
55
+ onCleanup(() => {
56
+ active = false;
57
+ offLoaded();
58
+ setCrdtField(null);
59
+ if (opened) void sp00ky.closeCrdtField(table, current, field);
60
+ });
61
+ }),
62
+ );
63
+
64
+ return crdtField;
65
+ }
@@ -1,10 +1,31 @@
1
1
  import { createSignal, createEffect, onCleanup, type Accessor } from 'solid-js';
2
2
  import type { SchemaStructure, BucketNames } from '@spooky-sync/query-builder';
3
+ import type { BlobUrlLease } from '@spooky-sync/core';
3
4
  import type { SyncedDb } from '../index';
4
5
  import { useDb } from './context';
5
6
 
6
7
  export interface UseDownloadFileOptions {
8
+ /**
9
+ * Master switch, default `true`. `false` gives every hook instance its own
10
+ * private object URL fetched fresh from the bucket and revoked on unmount —
11
+ * no sharing, no persistence, no reuse.
12
+ */
7
13
  cache?: boolean;
14
+ /**
15
+ * Keep the bytes in OPFS so they survive a reload and are available offline.
16
+ * Default `true`. Turn off for one-shot or sensitive files; the in-tab object
17
+ * URL is still shared between components rendering the same path.
18
+ */
19
+ persist?: boolean;
20
+ /** Exempt this file from pressure eviction. Pinned bytes never expire. */
21
+ pin?: boolean;
22
+ /**
23
+ * `'never'` (default) treats a bucket path as immutable, which is how paths
24
+ * are written (`crypto.randomUUID() + ext`). `'head'` spends a remote `head()`
25
+ * to compare sizes before trusting the cached copy — for paths the app
26
+ * overwrites in place.
27
+ */
28
+ revalidate?: 'never' | 'head';
8
29
  }
9
30
 
10
31
  export interface UseDownloadFileResult {
@@ -14,28 +35,6 @@ export interface UseDownloadFileResult {
14
35
  refetch: () => void;
15
36
  }
16
37
 
17
- interface CacheEntry {
18
- url: string;
19
- refCount: number;
20
- }
21
-
22
- const downloadCache = new Map<string, CacheEntry>();
23
- const inflightRequests = new Map<string, Promise<string | null>>();
24
-
25
- function cacheKey(bucket: string, path: string): string {
26
- return `${bucket}:${path}`;
27
- }
28
-
29
- function releaseEntry(key: string): void {
30
- const entry = downloadCache.get(key);
31
- if (!entry) return;
32
- entry.refCount--;
33
- if (entry.refCount <= 0) {
34
- URL.revokeObjectURL(entry.url);
35
- downloadCache.delete(key);
36
- }
37
- }
38
-
39
38
  export function useDownloadFile<S extends SchemaStructure>(
40
39
  bucketName: BucketNames<S>,
41
40
  path: Accessor<string | null | undefined>,
@@ -76,68 +75,19 @@ export function useDownloadFile<S extends SchemaStructure>(
76
75
  const [isLoading, setIsLoading] = createSignal(false);
77
76
  const [error, setError] = createSignal<Error | null>(null);
78
77
 
79
- let currentKey: string | null = null;
78
+ // Exactly one of these is held at a time: a refcounted lease on the shared
79
+ // cache entry, or a private URL this instance minted and must revoke itself.
80
+ let lease: BlobUrlLease | null = null;
80
81
  let privateUrl: string | null = null;
82
+
81
83
  const [refetchSignal, setRefetchSignal] = createSignal(0);
82
- const refetchTrigger = () => setRefetchSignal((n) => n + 1);
83
-
84
- async function doDownload(key: string, filePath: string): Promise<string | null> {
85
- if (useCache) {
86
- // Check cache
87
- const cached = downloadCache.get(key);
88
- if (cached) {
89
- cached.refCount++;
90
- currentKey = key;
91
- return cached.url;
92
- }
93
-
94
- // Check inflight
95
- const inflight = inflightRequests.get(key);
96
- if (inflight) {
97
- const result = await inflight;
98
- if (result) {
99
- const entry = downloadCache.get(key);
100
- if (entry) {
101
- entry.refCount++;
102
- currentKey = key;
103
- }
104
- }
105
- return result;
106
- }
107
-
108
- // Start new download
109
- const promise = (async () => {
110
- const content = await db.bucket(bucketName).get(filePath);
111
- if (!content) return null;
112
- const objectUrl = URL.createObjectURL(new Blob([content as BlobPart]));
113
- downloadCache.set(key, { url: objectUrl, refCount: 1 });
114
- return objectUrl;
115
- })();
116
-
117
- inflightRequests.set(key, promise);
118
- try {
119
- const result = await promise;
120
- currentKey = key;
121
- return result;
122
- } finally {
123
- inflightRequests.delete(key);
124
- }
125
- } else {
126
- // No caching — private URL per instance
127
- const content = await db.bucket(bucketName).get(filePath);
128
- if (!content) return null;
129
- const objectUrl = URL.createObjectURL(new Blob([content as BlobPart]));
130
- privateUrl = objectUrl;
131
- return objectUrl;
132
- }
133
- }
84
+ /** Consumed by the next effect run, so `refetch()` bypasses every layer once. */
85
+ let reloadOnce = false;
134
86
 
135
- function releaseCurrentEntry() {
136
- if (useCache && currentKey) {
137
- releaseEntry(currentKey);
138
- currentKey = null;
139
- }
140
- if (!useCache && privateUrl) {
87
+ function releaseCurrent() {
88
+ lease?.release();
89
+ lease = null;
90
+ if (privateUrl) {
141
91
  URL.revokeObjectURL(privateUrl);
142
92
  privateUrl = null;
143
93
  }
@@ -148,8 +98,7 @@ export function useDownloadFile<S extends SchemaStructure>(
148
98
  // Subscribe to refetch signal so effect re-runs
149
99
  refetchSignal();
150
100
 
151
- // Release previous entry
152
- releaseCurrentEntry();
101
+ releaseCurrent();
153
102
 
154
103
  if (!filePath) {
155
104
  setUrl(null);
@@ -158,26 +107,41 @@ export function useDownloadFile<S extends SchemaStructure>(
158
107
  return;
159
108
  }
160
109
 
161
- const key = cacheKey(bucketName as string, filePath);
162
-
163
- // Synchronous cache hit
164
- if (useCache) {
165
- const cached = downloadCache.get(key);
166
- if (cached) {
167
- cached.refCount++;
168
- currentKey = key;
169
- setUrl(cached.url);
170
- setIsLoading(false);
171
- setError(null);
172
- return;
173
- }
174
- }
110
+ const reload = reloadOnce;
111
+ reloadOnce = false;
175
112
 
176
113
  let cancelled = false;
177
114
  setIsLoading(true);
178
115
  setError(null);
179
116
 
180
- doDownload(key, filePath).then(
117
+ const bucket = db.bucket(bucketName);
118
+ const resolve = useCache
119
+ ? bucket
120
+ .url(filePath, {
121
+ persist: options.persist !== false,
122
+ pin: options.pin,
123
+ revalidate: options.revalidate,
124
+ reload,
125
+ })
126
+ .then((acquired) => {
127
+ if (!acquired) return null;
128
+ if (cancelled) {
129
+ // Unmounted or the path changed mid-flight — hand the reference
130
+ // straight back, or the entry never drops to zero and its object
131
+ // URL leaks for the life of the tab.
132
+ acquired.release();
133
+ return null;
134
+ }
135
+ lease = acquired;
136
+ return acquired.url;
137
+ })
138
+ : bucket.read(filePath, { persist: false, reload: true }).then((blob) => {
139
+ if (!blob || cancelled) return null;
140
+ privateUrl = URL.createObjectURL(blob);
141
+ return privateUrl;
142
+ });
143
+
144
+ resolve.then(
181
145
  (result) => {
182
146
  if (!cancelled) {
183
147
  setUrl(result);
@@ -199,20 +163,12 @@ export function useDownloadFile<S extends SchemaStructure>(
199
163
  });
200
164
 
201
165
  onCleanup(() => {
202
- releaseCurrentEntry();
166
+ releaseCurrent();
203
167
  });
204
168
 
205
169
  const refetch = () => {
206
- // Evict current entry from cache before re-triggering
207
- if (useCache && currentKey) {
208
- const entry = downloadCache.get(currentKey);
209
- if (entry) {
210
- URL.revokeObjectURL(entry.url);
211
- downloadCache.delete(currentKey);
212
- }
213
- currentKey = null;
214
- }
215
- refetchTrigger();
170
+ reloadOnce = true;
171
+ setRefetchSignal((n) => n + 1);
216
172
  };
217
173
 
218
174
  return { url, isLoading, error, refetch };