@octanejs/dexie 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @octanejs/dexie
+
+[Dexie](https://dexie.org/) bindings for the [octane](https://github.com/octanejs/octane)
+UI framework.
+
+This package re-exports Dexie's framework-neutral IndexedDB API and ports the
+reactive hooks from `dexie-react-hooks` to Octane. Existing Dexie database,
+schema, transaction, and query code can remain unchanged.
+
+```tsx
+import Dexie from '@octanejs/dexie';
+import { useLiveQuery } from '@octanejs/dexie';
+
+const db = new Dexie('friends');
+db.version(1).stores({ friends: '++id, name' });
+
+function FriendList() @{
+	const friends = useLiveQuery(() => db.table('friends').toArray(), [], []);
+	<ul>
+		{friends.map((friend) => <li key={friend.id}>{friend.name as string}</li>)}
+	</ul>
+}
+```
+
+## Ported hooks
+
+- `useObservable`
+- `useLiveQuery`
+- `useSuspendingObservable`
+- `useSuspendingLiveQuery`
+- `usePermissions` for Dexie Cloud databases
+- `useDocument` for optional `y-dexie` document providers
+
+The suspending hooks use Octane's `use()` integration and work with Octane
+Suspense or `@try` / `@pending` / `@catch` boundaries.
+
+Conformance coverage includes the upstream `dexie-react-hooks` QUnit/Karma
+integration scenarios, run in Playwright Chromium against real IndexedDB
+(`packages/dexie/tests/browser/`).
+
+Dexie only observes changes made through Dexie. For async work outside Dexie
+inside a live query, follow Dexie's guidance and wrap the returned promise with
+`Promise.resolve()` so the observation context remains active.
+
+`useDocument` requires the consumer to install and import `y-dexie` and `yjs`
+before calling the hook. Those packages are intentionally not dependencies of
+`@octanejs/dexie`.
+
+## SSR and hydration
+
+Non-suspending live queries are SSR-safe: the configured default result renders
+without opening IndexedDB, and the client hydrates the existing host before
+replacing that default with live data. Suspending live queries are intended for
+client-side Suspense boundaries and do not load IndexedDB data during SSR.
+
+## Status
+
+Current scope, known divergences, and verification status are tracked in the
+generated [bindings status table](../../docs/bindings-status.md), sourced from
+this package's [`status.json`](./status.json).

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@octanejs/dexie",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "Dexie bindings for the octane renderer — reuses Dexie's IndexedDB core and ports dexie-react-hooks onto octane hooks.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/dexie"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "dexie": "4.4.4"
+  },
+  "peerDependencies": {
+    "octane": "0.1.7"
+  },
+  "devDependencies": {
+    "@tsrx/react": "^0.2.37",
+    "dexie": "4.4.4",
+    "dexie-react-hooks": "4.4.0",
+    "esbuild": "^0.28.1",
+    "fake-indexeddb": "6.2.5",
+    "playwright": "^1.61.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.9",
+    "octane": "0.1.7"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from 'dexie';
+export { default } from 'dexie';
+export * from './useDocument';
+export * from './useLiveQuery';
+export * from './useObservable';
+export * from './usePermissions';
+export * from './useSuspendingLiveQuery';
+export * from './useSuspendingObservable';

package/src/internal.ts

@@ -0,0 +1,23 @@
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+const bareTagCache = new Map<string, symbol>();
+
+export function subSlot(slot: symbol | undefined, tag: string): symbol {
+	if (slot === undefined) {
+		let bare = bareTagCache.get(tag);
+		if (bare === undefined) bareTagCache.set(tag, (bare = Symbol.for(':' + tag)));
+		return bare;
+	}
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) subSlotCache.set(slot, (byTag = new Map()));
+	let derived = byTag.get(tag);
+	if (derived === undefined) {
+		byTag.set(tag, (derived = Symbol.for((slot.description ?? '') + ':' + tag)));
+	}
+	return derived;
+}
+
+export function splitSlot(args: any[]): [any[], symbol | undefined] {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? tail : undefined;
+	return [slot === undefined ? args : args.slice(0, -1), slot];
+}

package/src/useDocument.ts

@@ -0,0 +1,89 @@
+import { Dexie } from 'dexie';
+import { useEffect, useRef } from 'octane';
+import { splitSlot, subSlot } from './internal';
+
+export interface DexieYProvider<TDoc extends object = object> {
+	doc: TDoc;
+}
+
+interface DexieYProviderConstructor<TDoc extends object> {
+	load(doc: TDoc, options: { gracePeriod: number }): DexieYProvider<TDoc>;
+	for(doc: TDoc): DexieYProvider<TDoc> | undefined;
+	release(doc: TDoc): void;
+}
+
+type DexieWithYProvider = Dexie & {
+	DexieYProvider?: DexieYProviderConstructor<object>;
+};
+
+const gracePeriod = 100;
+const getProviderConstructor = () =>
+	(Dexie as unknown as DexieWithYProvider).DexieYProvider as
+		| DexieYProviderConstructor<object>
+		| undefined;
+
+const finalizationRegistry =
+	typeof FinalizationRegistry !== 'undefined'
+		? new FinalizationRegistry<object>((doc) => {
+				getProviderConstructor()?.release(doc);
+			})
+		: undefined;
+
+export function useDocument<TDoc extends object>(
+	doc: TDoc | null | undefined,
+	...rest: [symbol?]
+): DexieYProvider<TDoc> | null {
+	const [args, slot] = splitSlot(rest);
+	if (args.length !== 0) {
+		throw new TypeError('useDocument() accepts one document argument.');
+	}
+	if (!finalizationRegistry) {
+		throw new TypeError('useDocument() requires FinalizationRegistry support.');
+	}
+
+	const providerConstructor = getProviderConstructor() as
+		| DexieYProviderConstructor<TDoc>
+		| undefined;
+	if (!providerConstructor) {
+		throw new Error(
+			'DexieYProvider is not available. Make sure y-dexie is installed and imported.',
+		);
+	}
+
+	const providerRef = useRef<DexieYProvider<TDoc> | null>(null, subSlot(slot, 'document:provider'));
+	const unregisterTokenRef = useRef<object | undefined>(
+		undefined,
+		subSlot(slot, 'document:unregister'),
+	);
+
+	if (doc) {
+		if (doc !== providerRef.current?.doc) {
+			providerRef.current = providerConstructor.load(doc, { gracePeriod });
+			unregisterTokenRef.current = Object.create(null);
+			finalizationRegistry.register(providerRef, doc, unregisterTokenRef.current);
+		}
+	} else if (providerRef.current?.doc) {
+		providerRef.current = null;
+	}
+
+	useEffect(
+		() => {
+			if (!doc) return;
+			if (unregisterTokenRef.current) {
+				finalizationRegistry.unregister(unregisterTokenRef.current);
+				unregisterTokenRef.current = undefined;
+			}
+			const provider = providerConstructor.for(doc);
+			if (!provider) {
+				throw new Error(
+					'DexieYProvider.release() was called before useDocument() could take ownership.',
+				);
+			}
+			return () => providerConstructor.release(doc);
+		},
+		[doc],
+		subSlot(slot, 'document:effect'),
+	);
+
+	return providerRef.current;
+}

package/src/useLiveQuery.ts

@@ -0,0 +1,23 @@
+import { Dexie } from 'dexie';
+import { useObservable } from './useObservable';
+
+export function useLiveQuery<T>(querier: () => Promise<T> | T, deps?: unknown[]): T | undefined;
+export function useLiveQuery<T, TDefault>(
+	querier: () => Promise<T> | T,
+	deps: unknown[],
+	defaultResult: TDefault,
+): T | TDefault;
+export function useLiveQuery<T, TDefault>(
+	querier: () => Promise<T> | T,
+	...rest: [unknown?, unknown?, symbol?]
+): T | TDefault | undefined {
+	const slot = typeof rest[rest.length - 1] === 'symbol' ? rest.pop() : undefined;
+	const deps = (rest[0] as unknown[] | undefined) ?? [];
+	const defaultResult = rest[1] as TDefault | undefined;
+	return useObservable(
+		() => Dexie.liveQuery(querier) as any,
+		deps,
+		defaultResult,
+		slot as symbol | undefined,
+	) as T | TDefault | undefined;
+}

package/src/useObservable.ts

@@ -0,0 +1,123 @@
+import { useDebugValue, useEffect, useMemo, useReducer, useRef } from 'octane';
+import { splitSlot, subSlot } from './internal';
+
+export interface InteropableObservable<T> {
+	subscribe(
+		onNext: (value: T) => unknown,
+		onError?: (error: unknown) => unknown,
+	): { unsubscribe(): unknown } | (() => unknown);
+	getValue?(): T;
+	hasValue?(): boolean;
+}
+
+type ObservableFactory<T> = () => InteropableObservable<T>;
+
+function unsubscribe(subscription: { unsubscribe(): unknown } | (() => unknown)) {
+	if (typeof subscription === 'function') subscription();
+	else subscription.unsubscribe();
+}
+
+export function useObservable<T>(observable: InteropableObservable<T>): T | undefined;
+export function useObservable<T, TDefault>(
+	observable: InteropableObservable<T>,
+	defaultResult: TDefault,
+): T | TDefault;
+export function useObservable<T>(
+	observableFactory: ObservableFactory<T>,
+	deps?: unknown[],
+): T | undefined;
+export function useObservable<T, TDefault>(
+	observableFactory: ObservableFactory<T>,
+	deps: unknown[],
+	defaultResult: TDefault,
+): T | TDefault;
+export function useObservable<T, TDefault>(
+	observableFactory: ObservableFactory<T>,
+	deps: unknown[],
+	defaultResult: TDefault | undefined,
+	slot: symbol | undefined,
+): T | TDefault | undefined;
+export function useObservable<T, TDefault>(
+	observableOrFactory: InteropableObservable<T> | ObservableFactory<T>,
+	...rest: [unknown?, unknown?, symbol?]
+): T | TDefault | undefined {
+	const [args, slot] = splitSlot(rest);
+	const deps = typeof observableOrFactory === 'function' ? ((args[0] as unknown[]) ?? []) : [];
+	const defaultResult = (typeof observableOrFactory === 'function' ? args[1] : args[0]) as
+		| TDefault
+		| undefined;
+	const monitor = useRef(
+		{
+			hasResult: false,
+			result: defaultResult as T | TDefault | undefined,
+			error: null as unknown,
+		},
+		subSlot(slot, 'observable:monitor'),
+	);
+	const [, triggerUpdate] = useReducer(
+		(value: number) => value + 1,
+		0,
+		subSlot(slot, 'observable:update'),
+	);
+	const observable = useMemo(
+		() => {
+			const value =
+				typeof observableOrFactory === 'function' ? observableOrFactory() : observableOrFactory;
+			if (!value || typeof value.subscribe !== 'function') {
+				throw new TypeError(
+					typeof observableOrFactory === 'function'
+						? 'Observable factory did not return a valid observable.'
+						: 'Given argument was neither a valid observable nor a function.',
+				);
+			}
+			if (
+				!monitor.current.hasResult &&
+				typeof window !== 'undefined' &&
+				(typeof value.hasValue !== 'function' || value.hasValue())
+			) {
+				if (typeof value.getValue === 'function') {
+					monitor.current.result = value.getValue();
+					monitor.current.hasResult = true;
+				} else {
+					const subscription = value.subscribe((next) => {
+						monitor.current.result = next;
+						monitor.current.hasResult = true;
+					});
+					unsubscribe(subscription);
+				}
+			}
+			return value;
+		},
+		deps,
+		subSlot(slot, 'observable:memo'),
+	);
+
+	useDebugValue(monitor.current.result, subSlot(slot, 'observable:debug'));
+	useEffect(
+		() => {
+			const subscription = observable.subscribe(
+				(next) => {
+					const current = monitor.current;
+					if (current.error !== null || !Object.is(current.result, next)) {
+						current.error = null;
+						current.result = next;
+						current.hasResult = true;
+						triggerUpdate(0);
+					}
+				},
+				(error) => {
+					if (monitor.current.error !== error) {
+						monitor.current.error = error;
+						triggerUpdate(0);
+					}
+				},
+			);
+			return () => unsubscribe(subscription);
+		},
+		[observable],
+		subSlot(slot, 'observable:effect'),
+	);
+
+	if (monitor.current.error !== null) throw monitor.current.error;
+	return monitor.current.result;
+}

package/src/usePermissions.ts

@@ -0,0 +1,102 @@
+import { Dexie } from 'dexie';
+import { useObservable } from './useObservable';
+
+type PermissionKeyPaths<T> = {
+	[P in keyof T]: P extends string
+		? T[P] extends readonly (infer K)[]
+			? K extends object
+				? P | `${P}.${number}` | `${P}.${number}.${PermissionKeyPaths<K>}`
+				: P | `${P}.${number}`
+			: T[P] extends (...args: any[]) => any
+				? never
+				: T[P] extends object
+					? P | `${P}.${PermissionKeyPaths<T[P]>}`
+					: P
+		: never;
+}[keyof T];
+
+export type PermissionChecker<T, TableName extends string> = {
+	add(...tableNames: TableName[]): boolean;
+	update(...props: PermissionKeyPaths<T>[]): boolean;
+	delete(): boolean;
+};
+
+type Entity = {
+	table?: () => string;
+	realmId?: string;
+	owner?: string;
+	db?: Dexie;
+};
+
+export function usePermissions<T extends Entity>(
+	entity: T,
+): PermissionChecker<T, T extends { table: () => infer Name } ? Extract<Name, string> : string>;
+export function usePermissions<TDB extends Dexie, T>(
+	db: TDB,
+	table: string,
+	obj: T,
+): PermissionChecker<T, string>;
+export function usePermissions(...rest: any[]) {
+	const [args, slot] = (() => {
+		const tail = rest[rest.length - 1];
+		return typeof tail === 'symbol' ? [rest.slice(0, -1), tail as symbol] : [rest, undefined];
+	})();
+	const firstArg = args[0] as Entity | Dexie | undefined;
+	if (!firstArg) throw new TypeError('Invalid arguments to usePermissions(): undefined or null');
+
+	let db: Dexie;
+	let table: string;
+	let obj: Entity;
+	if (args.length >= 3) {
+		if (!('transaction' in firstArg)) {
+			throw new TypeError(
+				'Invalid arguments to usePermissions(db, table, obj): 1st arg must be a Dexie instance',
+			);
+		}
+		if (typeof args[1] !== 'string') {
+			throw new TypeError(
+				'Invalid arguments to usePermissions(db, table, obj): 2nd arg must be string',
+			);
+		}
+		if (!args[2] || typeof args[2] !== 'object') {
+			throw new TypeError(
+				'Invalid arguments to usePermissions(db, table, obj): 3rd arg must be an object',
+			);
+		}
+		db = firstArg as Dexie;
+		table = args[1];
+		obj = args[2];
+	} else if (
+		typeof firstArg !== 'object' ||
+		typeof (firstArg as Entity).table !== 'function' ||
+		!(firstArg as Entity).db
+	) {
+		throw new TypeError(
+			'Invalid arguments to usePermissions(). Expected a Dexie Cloud entity or (db, table, obj).',
+		);
+	} else {
+		const entity = firstArg as Entity;
+		db = entity.db!;
+		table = entity.table!();
+		obj = entity;
+	}
+
+	const cloud = (db as Dexie & { cloud?: { permissions: (obj: Entity, table: string) => unknown } })
+		.cloud;
+	if (!cloud) {
+		throw new Error(
+			"usePermissions() is only for Dexie Cloud but there's no dexie-cloud-addon active in the given db.",
+		);
+	}
+	if (typeof cloud.permissions !== 'function') {
+		throw new Error(
+			'usePermissions() requires a newer version of dexie-cloud-addon. Please upgrade it.',
+		);
+	}
+	return useObservable(
+		() => cloud.permissions(obj, table) as any,
+		[obj.realmId, obj.owner, table],
+		undefined,
+		slot,
+	);
+}

package/src/useSuspendingLiveQuery.ts

@@ -0,0 +1,21 @@
+import { Dexie } from 'dexie';
+import { useSuspendingObservable } from './useSuspendingObservable';
+
+export function useSuspendingLiveQuery<T>(
+	querier: () => Promise<T> | T,
+	cacheKey: readonly unknown[],
+): T;
+export function useSuspendingLiveQuery<T>(
+	querier: () => Promise<T> | T,
+	...rest: [readonly unknown[], symbol?]
+): T {
+	const [args, slot] =
+		typeof rest[rest.length - 1] === 'symbol'
+			? [rest.slice(0, -1), rest[rest.length - 1] as symbol]
+			: [rest, undefined];
+	return useSuspendingObservable(
+		() => Dexie.liveQuery(querier),
+		['dexie', ...(args[0] as readonly unknown[])],
+		slot,
+	);
+}

package/src/useSuspendingObservable.ts

@@ -0,0 +1,197 @@
+import { use, useEffect, useReducer, useRef } from 'octane';
+import type { InteropableObservable } from './useObservable';
+import { splitSlot, subSlot } from './internal';
+
+type Observer<T> = {
+	next?: (value: T) => void;
+	error?: (error: unknown) => void;
+	complete?: () => void;
+};
+
+type Subscription = { unsubscribe(): unknown } | (() => unknown);
+
+type CacheEntry<T> = {
+	key: readonly unknown[];
+	source: any;
+	current?: T;
+	hasValue: boolean;
+	promise?: Promise<T>;
+	observers: Set<Observer<T>>;
+	sourceSubscription?: Subscription;
+	cleanup?: ReturnType<typeof setTimeout>;
+	subscribe(observer: Observer<T>): Subscription;
+};
+
+const CLEANUP_DELAY = 3000;
+const cache: CacheEntry<any>[] = [];
+const sameKey = (left: readonly unknown[], right: readonly unknown[]) =>
+	left.length === right.length && left.every((value, index) => Object.is(value, right[index]));
+
+function stop(subscription: Subscription | undefined) {
+	if (subscription === undefined) return;
+	if (typeof subscription === 'function') subscription();
+	else subscription.unsubscribe();
+}
+
+function getEntry<T>(
+	getObservable: (() => InteropableObservable<T>) | InteropableObservable<T>,
+	cacheKey: readonly unknown[],
+): CacheEntry<T> {
+	const existing = cache.find((entry) => sameKey(entry.key, cacheKey)) as CacheEntry<T> | undefined;
+	if (existing) return existing;
+
+	const source: any =
+		typeof getObservable === 'function'
+			? getObservable()
+			: (getObservable as InteropableObservable<T>);
+	const entry = {
+		key: [...cacheKey],
+		source,
+		current: undefined,
+		hasValue: false,
+		observers: new Set<Observer<T>>(),
+	} as unknown as CacheEntry<T>;
+
+	const emit = (observer: Observer<T>, method: 'next' | 'error' | 'complete', value?: unknown) => {
+		observer[method]?.(value as never);
+	};
+
+	const scheduleCleanup = () => {
+		if (entry.cleanup !== undefined) return;
+		entry.cleanup = setTimeout(() => {
+			stop(entry.sourceSubscription);
+			entry.sourceSubscription = undefined;
+			const index = cache.indexOf(entry);
+			if (index !== -1) cache.splice(index, 1);
+		}, CLEANUP_DELAY);
+	};
+
+	// Match dexie-react-hooks handleFinalize: drop promise/value/observers so a later
+	// subscribe (same cache key) can start fresh. Do not unsubscribe the source here —
+	// upstream clears its subscription pointer without stopping, so Dexie can finish
+	// handling a querier rejection without leaving an unhandled rejection.
+	const handleFinalize = () => {
+		entry.sourceSubscription = undefined;
+		entry.promise = undefined;
+		entry.hasValue = false;
+		entry.current = undefined;
+		entry.observers.clear();
+		scheduleCleanup();
+	};
+
+	const subscribeSource = () => {
+		if (entry.sourceSubscription) return;
+		entry.sourceSubscription = source.subscribe({
+			next: (value: T) => {
+				entry.current = value;
+				entry.hasValue = true;
+				for (const observer of [...entry.observers]) emit(observer, 'next', value);
+			},
+			error: (error: unknown) => {
+				const lastObservers = new Set(entry.observers);
+				handleFinalize();
+				for (const observer of lastObservers) emit(observer, 'error', error);
+			},
+			complete: () => {
+				const lastObservers = new Set(entry.observers);
+				handleFinalize();
+				for (const observer of lastObservers) emit(observer, 'complete');
+			},
+		});
+	};
+
+	entry.subscribe = (observer) => {
+		if (entry.cleanup !== undefined) {
+			clearTimeout(entry.cleanup);
+			entry.cleanup = undefined;
+		}
+		entry.observers.add(observer);
+		subscribeSource();
+		if (entry.hasValue) observer.next?.(entry.current as T);
+		return () => {
+			if (!entry.observers.has(observer)) return;
+			entry.observers.delete(observer);
+			if (entry.observers.size === 0) scheduleCleanup();
+		};
+	};
+	cache.push(entry);
+	return entry;
+}
+
+export function useSuspendingObservable<T>(
+	getObservable: (() => InteropableObservable<T>) | InteropableObservable<T>,
+	cacheKey: readonly unknown[],
+): T;
+export function useSuspendingObservable<T>(
+	getObservable: (() => InteropableObservable<T>) | InteropableObservable<T>,
+	cacheKey: readonly unknown[],
+	slot: symbol | undefined,
+): T;
+export function useSuspendingObservable<T>(
+	getObservable: (() => InteropableObservable<T>) | InteropableObservable<T>,
+	...rest: [readonly unknown[], symbol?]
+): T {
+	const [args, slot] = splitSlot(rest);
+	const entry = getEntry(getObservable, args[0] as readonly unknown[]);
+	if (!entry.promise) {
+		entry.promise = new Promise<T>((resolve, reject) => {
+			let subscription: Subscription;
+			subscription = entry.subscribe({
+				next: (value) => {
+					resolve(value);
+					queueMicrotask(() => stop(subscription));
+				},
+				error: (error) => {
+					reject(error);
+					queueMicrotask(() => stop(subscription));
+				},
+			});
+		});
+		// Octane's use() may reuse a prior promise on replay and abandon a freshly
+		// created one after handleFinalize cleared entry.promise. Attach a sink so
+		// that wasted rejection is not reported as unhandled (the active use()
+		// slot still observes the settled promise).
+		entry.promise.catch(() => {});
+	}
+
+	const initialValue = use(entry.promise);
+	const value = useRef(initialValue, subSlot(slot, 'suspending:value'));
+	const error = useRef<unknown>(undefined, subSlot(slot, 'suspending:error'));
+	const activeEntry = useRef(entry, subSlot(slot, 'suspending:entry'));
+	const [, rerender] = useReducer(
+		(count: number) => count + 1,
+		0,
+		subSlot(slot, 'suspending:update'),
+	);
+
+	// Per Bugbot discussion_r3597801534: a prior entry's error must not stick after cacheKey changes.
+	if (activeEntry.current !== entry) {
+		activeEntry.current = entry;
+		error.current = undefined;
+	}
+
+	value.current = entry.hasValue ? (entry.current as T) : initialValue;
+
+	useEffect(
+		() => {
+			const subscription = entry.subscribe({
+				next: (next) => {
+					if (!Object.is(value.current, next)) {
+						value.current = next;
+						rerender(0);
+					}
+				},
+				error: (nextError) => {
+					error.current = nextError;
+					rerender(0);
+				},
+			});
+			return () => stop(subscription);
+		},
+		[entry],
+		subSlot(slot, 'suspending:effect'),
+	);
+
+	if (error.current !== undefined) throw error.current;
+	return value.current;
+}