@typewirets/react 0.1.0 → 0.2.0-rc.1

package/dist/esm/index.d.ts

@@ -1,14 +1,247 @@
+/**
+ * TypeWire React Integration
+ *
+ * Provides React bindings for TypeWire dependency injection, enabling
+ * context-based dependency resolution within React component trees.
+ *
+ * Key exports:
+ * - {@link ReactResolutionContext} — Wraps a `ResolutionContext` with error caching, so a failed resolution doesn't loop under Suspense
+ * - {@link ContainerContext} — React Context holding the active resolution context
+ * - {@link useContainer} — Hook to access the current resolution context
+ * - {@link useTypeWire} — Hook to resolve a TypeWire with React Suspense support
+ * - {@link usePreload} — Hook that suspends a subtree once until a set of wires is created
+ * - {@link ResolutionContextProvider} — Component that provides a resolution context to the tree
+ *
+ * @packageDocumentation
+ */
 import * as React from "react";
-import { type ResolutionContext, type TypeSymbol, type TypeWire } from "@typewirets/core";
+import { type AnyTypeSymbol, type AnyTypeWire, type ResolutionContext, type TypeSymbol, type TypeWire } from "@typewirets/core";
+/**
+ * A React-aware wrapper around {@link ResolutionContext} that caches resolution
+ * errors.
+ *
+ * When a component suspends on a resolution that then fails, React renders it
+ * again, and that render would start a new creation, suspend, fail and repeat
+ * forever. To stop that loop, the error from a failed `get` is cached, and
+ * later `get` and `getSync` calls for the same `TypeSymbol` throw it without
+ * calling the underlying context.
+ *
+ * A cached error lasts until {@link ReactResolutionContext.clearErrors} is
+ * called, even across `unbind` and a re-apply: this class only sees a
+ * `ResolutionContext`, so it cannot tell that a binding changed. To retry
+ * after replacing a binding, call `clearErrors` and then reset the error
+ * boundary that caught the error.
+ *
+ * Calls that run while a resolution is in flight are not deduplicated here.
+ * The underlying context must share one in-flight creation per singleton
+ * itself, or readers may get different instances. `TypeWireContainer` does,
+ * and never hands a creation started before `unbind` to new callers. So does
+ * the `@typewirets/inversify` adapter, because Inversify 7 shares concurrent
+ * singleton `getAsync` calls. A custom `ResolutionContext` must do the same.
+ *
+ * @example
+ * ```typescript
+ * const container = new TypeWireContainer();
+ * const context = new ReactResolutionContext(container);
+ * const value = await context.get(MySymbol);
+ *
+ * // After replacing the binding for MySymbol:
+ * context.clearErrors(MySymbol);
+ * ```
+ */
 export declare class ReactResolutionContext {
     #private;
     constructor(resolutionContext: ResolutionContext);
+    /**
+     * Synchronously retrieves a resolved instance for the given type symbol.
+     *
+     * @template T The type of the resolved instance
+     * @param typeSymbol - The typed symbol identifying the dependency to resolve
+     * @returns The resolved instance
+     * @throws Re-throws the cached error if a previous async resolution for this symbol failed
+     * @throws Throws if the instance has not been resolved yet (see {@link ResolutionContext.getSync})
+     */
     getSync<T>(typeSymbol: TypeSymbol<T>): T;
+    /**
+     * Asynchronously resolves an instance for the given type symbol.
+     *
+     * If a previous resolution for this symbol failed, the cached error is
+     * thrown immediately. Otherwise the call goes to the underlying context,
+     * which joins a creation already in flight for a singleton.
+     *
+     * @template T The type of the resolved instance
+     * @param typeSymbol - The typed symbol identifying the dependency to resolve
+     * @returns A promise that resolves to the instance
+     * @throws Re-throws the cached error if a previous resolution for this symbol failed
+     */
     get<T>(typeSymbol: TypeSymbol<T>): Promise<T>;
+    /**
+     * Forgets cached resolution errors, so the next `get` or `getSync` asks the
+     * underlying context again.
+     *
+     * Call it after replacing a failed binding (`unbind`, then apply the wire
+     * again), then reset the error boundary that shows the error. A failure that
+     * was still in flight when you call this is not cached when it settles.
+     *
+     * @param typeSymbol - The symbol whose error to forget. Omit to forget all.
+     */
+    clearErrors(typeSymbol?: AnyTypeSymbol): void;
 }
+/**
+ * React Context that holds the active {@link ResolutionContext} for the component tree.
+ *
+ * The default value is an empty {@link TypeWireContainer} wrapped in a
+ * {@link ReactResolutionContext}. In practice, you should provide your own
+ * container via {@link ResolutionContextProvider}.
+ */
 export declare const ContainerContext: React.Context<ResolutionContext>;
+/**
+ * Hook to access the current {@link ResolutionContext} from the nearest
+ * {@link ResolutionContextProvider}.
+ *
+ * @returns The current resolution context
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const container = useContainer();
+ *   // Use container for manual resolution if needed
+ * }
+ * ```
+ */
 export declare function useContainer(): ResolutionContext;
-export declare function useTypeWire<T>(typeWire: TypeWire<T>): T;
+/**
+ * Options for {@link useTypeWire}.
+ */
+export interface UseTypeWireOpts {
+    /**
+     * What to do when the value isn't created yet. `true` (the default)
+     * suspends until it is, so the nearest `<Suspense>` shows its fallback.
+     * `false` throws a `TypeWireError` with reason `NotPreloaded` naming the
+     * wire instead, for apps that preload every phase and never want a
+     * fallback: a forgotten preload then shows up at once, in development.
+     */
+    suspend?: boolean;
+}
+/**
+ * Hook that resolves a {@link TypeWire} within the current container context,
+ * with React Suspense integration.
+ *
+ * Resolution behavior:
+ * 1. **Sync available** — If the wire can be resolved synchronously (e.g., a singleton
+ *    that was already created or preloaded), the value is returned immediately,
+ *    including falsy values such as `0`, `""`, `false` and `null`.
+ * 2. **Async pending** — If sync resolution fails with a retriable error, the hook
+ *    starts an async resolution and throws the promise to trigger React Suspense.
+ *    With `{ suspend: false }` it throws a `TypeWireError` with reason
+ *    `NotPreloaded` instead.
+ * 3. **Error** — If sync resolution fails with a non-retriable error, it is re-thrown.
+ *
+ * To render without a fallback, preload the wires first, with
+ * `container.preload` before rendering or {@link usePreload} higher in the
+ * tree. A wire nobody preloaded suspends, so this hook must be used inside a
+ * `<Suspense>` boundary unless you pass `{ suspend: false }`.
+ *
+ * @template T The type of the resolved instance
+ * @param typeWire - The TypeWire to resolve
+ * @param opts - Optional settings; see {@link UseTypeWireOpts}
+ * @returns The resolved instance
+ * @throws The resolution promise when the value is not yet available (for Suspense)
+ * @throws {@link TypeWireError} with reason `NotPreloaded` when the value is not yet available and `suspend` is `false`
+ * @throws {@link TypeWireError} if synchronous resolution fails with a non-retriable error
+ *
+ * @example
+ * ```tsx
+ * function UserProfile() {
+ *   const userService = useTypeWire(UserServiceWire);
+ *   return <div>{userService.getName()}</div>;
+ * }
+ *
+ * // Preloaded before rendering: no fallback.
+ * await container.preload({ wires: [UserServiceWire] });
+ *
+ * // Or wrap in Suspense for wires that may not be ready yet.
+ * <Suspense fallback={<Loading />}>
+ *   <UserProfile />
+ * </Suspense>
+ * ```
+ */
+export declare function useTypeWire<T>(typeWire: TypeWire<T>, opts?: UseTypeWireOpts): T;
+/**
+ * Options for {@link usePreload}.
+ */
+export interface UsePreloadOpts {
+    /**
+     * The wires to create before the calling component renders. Their imports
+     * are created with them. Wires that aren't singletons are skipped. To
+     * preload a group, pass its `wires`.
+     */
+    wires: readonly AnyTypeWire[];
+}
+/**
+ * Hook that suspends the calling component until every singleton in
+ * `opts.wires` is created, so components below it read them with
+ * {@link useTypeWire} without suspending.
+ *
+ * Use it where a part of the app starts (a route, a panel, a feature), under
+ * one `<Suspense>` boundary: the fallback shows once for the whole set, and
+ * the creations run in parallel. A creation that fails reaches the nearest
+ * error boundary.
+ *
+ * It works with any resolution context, including the Inversify adapter.
+ * Outside React, use `container.preload` instead.
+ *
+ * @param opts - The wires to preload; see {@link UsePreloadOpts}
+ * @throws A promise while any of the wires is still being created (for Suspense)
+ * @throws The creation's error, once one has failed
+ *
+ * @example
+ * ```tsx
+ * function ReportsRoute() {
+ *   usePreload({ wires: [reportsServiceWire, chartsWire] });
+ *   return <ReportsPage />;
+ * }
+ *
+ * <Suspense fallback={<Loading />}>
+ *   <ReportsRoute />
+ * </Suspense>
+ * ```
+ */
+export declare function usePreload(opts: UsePreloadOpts): void;
+/**
+ * React component that provides a {@link ResolutionContext} to the component tree.
+ *
+ * If the given `resolutionContext` is not already a {@link ReactResolutionContext},
+ * it is wrapped in one, so a failed resolution reaches an error boundary
+ * instead of retrying under Suspense. Each plain context gets one wrapper,
+ * reused on every render and every mount, so re-rendering the provider keeps
+ * cached errors and gives consumers the same context value.
+ *
+ * A cached error lasts until `clearErrors` is called, even after `unbind` and
+ * a re-apply. To be able to retry, create the {@link ReactResolutionContext}
+ * yourself, pass it here, and call its `clearErrors` after replacing the
+ * binding.
+ *
+ * The context must share one in-flight creation per singleton (as
+ * `TypeWireContainer` does); see {@link ReactResolutionContext}.
+ *
+ * @param props.resolutionContext - The resolution context to provide to descendants
+ * @param props.children - Child components that will have access to the context
+ *
+ * @example
+ * ```tsx
+ * async function main() {
+ *   const container = new TypeWireContainer();
+ *   await AppWireGroup.apply(container);
+ *
+ *   createRoot(document.getElementById('root')!).render(
+ *     <ResolutionContextProvider resolutionContext={container}>
+ *       <App />
+ *     </ResolutionContextProvider>
+ *   );
+ * }
+ * ```
+ */
 export declare function ResolutionContextProvider(props: {
     resolutionContext: ResolutionContext;
     children?: React.ReactNode;

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,QAAQ,EAGd,MAAM,kBAAkB,CAAC;AAE1B,qBAAa,sBAAsB;;gBAKrB,iBAAiB,EAAE,iBAAiB;IAIhD,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC;IAOlC,GAAG,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAqBpD;AAED,eAAO,MAAM,gBAAgB,kCAE5B,CAAC;AAEF,wBAAgB,YAAY,sBAG3B;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAsCvD;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,2CAUA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,QAAQ,EAGd,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,sBAAsB;;gBAYrB,iBAAiB,EAAE,iBAAiB;IAIhD;;;;;;;;OAQG;IACH,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC;IAOxC;;;;;;;;;;;OAWG;IACG,GAAG,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAmBnD;;;;;;;;;OASG;IACH,WAAW,CAAC,UAAU,CAAC,EAAE,aAAa,GAAG,IAAI;CAoB9C;AA2BD;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,kCAE5B,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,sBAG3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA6CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EACrB,IAAI,CAAC,EAAE,eAAe,GACrB,CAAC,CA6CH;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAgBrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,2CAOA"}

package/dist/esm/index.js

@@ -9,88 +9,383 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _ReactResolutionContext_resolutionContext, _ReactResolutionContext_resolutions, _ReactResolutionContext_resolutionErrors;
+var _ReactResolutionContext_instances, _ReactResolutionContext_resolutionContext, _ReactResolutionContext_resolutionErrors, _ReactResolutionContext_generation, _ReactResolutionContext_allClearedAt, _ReactResolutionContext_clearedAt, _ReactResolutionContext_clearedSince;
 import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * TypeWire React Integration
+ *
+ * Provides React bindings for TypeWire dependency injection, enabling
+ * context-based dependency resolution within React component trees.
+ *
+ * Key exports:
+ * - {@link ReactResolutionContext} — Wraps a `ResolutionContext` with error caching, so a failed resolution doesn't loop under Suspense
+ * - {@link ContainerContext} — React Context holding the active resolution context
+ * - {@link useContainer} — Hook to access the current resolution context
+ * - {@link useTypeWire} — Hook to resolve a TypeWire with React Suspense support
+ * - {@link usePreload} — Hook that suspends a subtree once until a set of wires is created
+ * - {@link ResolutionContextProvider} — Component that provides a resolution context to the tree
+ *
+ * @packageDocumentation
+ */
 import * as React from "react";
 import { TypeWireError, TypeWireContainer, } from "@typewirets/core";
+/**
+ * A React-aware wrapper around {@link ResolutionContext} that caches resolution
+ * errors.
+ *
+ * When a component suspends on a resolution that then fails, React renders it
+ * again, and that render would start a new creation, suspend, fail and repeat
+ * forever. To stop that loop, the error from a failed `get` is cached, and
+ * later `get` and `getSync` calls for the same `TypeSymbol` throw it without
+ * calling the underlying context.
+ *
+ * A cached error lasts until {@link ReactResolutionContext.clearErrors} is
+ * called, even across `unbind` and a re-apply: this class only sees a
+ * `ResolutionContext`, so it cannot tell that a binding changed. To retry
+ * after replacing a binding, call `clearErrors` and then reset the error
+ * boundary that caught the error.
+ *
+ * Calls that run while a resolution is in flight are not deduplicated here.
+ * The underlying context must share one in-flight creation per singleton
+ * itself, or readers may get different instances. `TypeWireContainer` does,
+ * and never hands a creation started before `unbind` to new callers. So does
+ * the `@typewirets/inversify` adapter, because Inversify 7 shares concurrent
+ * singleton `getAsync` calls. A custom `ResolutionContext` must do the same.
+ *
+ * @example
+ * ```typescript
+ * const container = new TypeWireContainer();
+ * const context = new ReactResolutionContext(container);
+ * const value = await context.get(MySymbol);
+ *
+ * // After replacing the binding for MySymbol:
+ * context.clearErrors(MySymbol);
+ * ```
+ */
 export class ReactResolutionContext {
     constructor(resolutionContext) {
+        _ReactResolutionContext_instances.add(this);
+        /** The underlying resolution context that performs actual dependency resolution. */
         _ReactResolutionContext_resolutionContext.set(this, void 0);
-        _ReactResolutionContext_resolutions.set(this, new Map());
+        /** Cached resolution errors, keyed by symbol, to fail fast on repeated access. */
         _ReactResolutionContext_resolutionErrors.set(this, new Map());
+        /** Counts `clearErrors` calls, so a `get` can tell if one ran while it waited. */
+        _ReactResolutionContext_generation.set(this, 0);
+        /** The generation of the last `clearErrors()` call that cleared every symbol. */
+        _ReactResolutionContext_allClearedAt.set(this, 0);
+        /** The generation of the last `clearErrors(typeSymbol)` call, per symbol. */
+        _ReactResolutionContext_clearedAt.set(this, new Map());
         __classPrivateFieldSet(this, _ReactResolutionContext_resolutionContext, resolutionContext, "f");
     }
+    /**
+     * Synchronously retrieves a resolved instance for the given type symbol.
+     *
+     * @template T The type of the resolved instance
+     * @param typeSymbol - The typed symbol identifying the dependency to resolve
+     * @returns The resolved instance
+     * @throws Re-throws the cached error if a previous async resolution for this symbol failed
+     * @throws Throws if the instance has not been resolved yet (see {@link ResolutionContext.getSync})
+     */
     getSync(typeSymbol) {
         if (__classPrivateFieldGet(this, _ReactResolutionContext_resolutionErrors, "f").has(typeSymbol.symbol)) {
             throw __classPrivateFieldGet(this, _ReactResolutionContext_resolutionErrors, "f").get(typeSymbol.symbol);
         }
         return __classPrivateFieldGet(this, _ReactResolutionContext_resolutionContext, "f").getSync(typeSymbol);
     }
+    /**
+     * Asynchronously resolves an instance for the given type symbol.
+     *
+     * If a previous resolution for this symbol failed, the cached error is
+     * thrown immediately. Otherwise the call goes to the underlying context,
+     * which joins a creation already in flight for a singleton.
+     *
+     * @template T The type of the resolved instance
+     * @param typeSymbol - The typed symbol identifying the dependency to resolve
+     * @returns A promise that resolves to the instance
+     * @throws Re-throws the cached error if a previous resolution for this symbol failed
+     */
     async get(typeSymbol) {
-        if (__classPrivateFieldGet(this, _ReactResolutionContext_resolutionErrors, "f").has(typeSymbol.symbol)) {
-            throw __classPrivateFieldGet(this, _ReactResolutionContext_resolutionErrors, "f").get(typeSymbol.symbol);
+        const symbol = typeSymbol.symbol;
+        if (__classPrivateFieldGet(this, _ReactResolutionContext_resolutionErrors, "f").has(symbol)) {
+            throw __classPrivateFieldGet(this, _ReactResolutionContext_resolutionErrors, "f").get(symbol);
         }
-        const promise = __classPrivateFieldGet(this, _ReactResolutionContext_resolutions, "f").get(typeSymbol.symbol);
-        if (promise) {
-            return promise;
+        const startedAt = __classPrivateFieldGet(this, _ReactResolutionContext_generation, "f");
+        try {
+            return await __classPrivateFieldGet(this, _ReactResolutionContext_resolutionContext, "f").get(typeSymbol);
         }
-        const newResolution = __classPrivateFieldGet(this, _ReactResolutionContext_resolutionContext, "f").get(typeSymbol);
-        __classPrivateFieldGet(this, _ReactResolutionContext_resolutions, "f").set(typeSymbol.symbol, newResolution);
-        return newResolution
-            .catch((err) => {
-            __classPrivateFieldGet(this, _ReactResolutionContext_resolutionErrors, "f").set(typeSymbol.symbol, err);
+        catch (err) {
+            // A failure that settles after `clearErrors` belongs to the attempt the
+            // caller just discarded: hand it to this caller, but don't cache it.
+            if (!__classPrivateFieldGet(this, _ReactResolutionContext_instances, "m", _ReactResolutionContext_clearedSince).call(this, symbol, startedAt)) {
+                __classPrivateFieldGet(this, _ReactResolutionContext_resolutionErrors, "f").set(symbol, err);
+            }
             throw err;
-        })
-            .finally(() => {
-            __classPrivateFieldGet(this, _ReactResolutionContext_resolutions, "f").delete(typeSymbol.symbol);
-        });
+        }
     }
+    /**
+     * Forgets cached resolution errors, so the next `get` or `getSync` asks the
+     * underlying context again.
+     *
+     * Call it after replacing a failed binding (`unbind`, then apply the wire
+     * again), then reset the error boundary that shows the error. A failure that
+     * was still in flight when you call this is not cached when it settles.
+     *
+     * @param typeSymbol - The symbol whose error to forget. Omit to forget all.
+     */
+    clearErrors(typeSymbol) {
+        __classPrivateFieldSet(this, _ReactResolutionContext_generation, __classPrivateFieldGet(this, _ReactResolutionContext_generation, "f") + 1, "f");
+        if (typeSymbol) {
+            __classPrivateFieldGet(this, _ReactResolutionContext_resolutionErrors, "f").delete(typeSymbol.symbol);
+            __classPrivateFieldGet(this, _ReactResolutionContext_clearedAt, "f").set(typeSymbol.symbol, __classPrivateFieldGet(this, _ReactResolutionContext_generation, "f"));
+            return;
+        }
+        __classPrivateFieldGet(this, _ReactResolutionContext_resolutionErrors, "f").clear();
+        __classPrivateFieldGet(this, _ReactResolutionContext_clearedAt, "f").clear();
+        __classPrivateFieldSet(this, _ReactResolutionContext_allClearedAt, __classPrivateFieldGet(this, _ReactResolutionContext_generation, "f"), "f");
+    }
+}
+_ReactResolutionContext_resolutionContext = new WeakMap(), _ReactResolutionContext_resolutionErrors = new WeakMap(), _ReactResolutionContext_generation = new WeakMap(), _ReactResolutionContext_allClearedAt = new WeakMap(), _ReactResolutionContext_clearedAt = new WeakMap(), _ReactResolutionContext_instances = new WeakSet(), _ReactResolutionContext_clearedSince = function _ReactResolutionContext_clearedSince(symbol, generation) {
+    const clearedAt = Math.max(__classPrivateFieldGet(this, _ReactResolutionContext_allClearedAt, "f"), __classPrivateFieldGet(this, _ReactResolutionContext_clearedAt, "f").get(symbol) ?? 0);
+    return clearedAt > generation;
+};
+/**
+ * The wrapper {@link ResolutionContextProvider} uses for each plain context, so
+ * every render and every mount of a provider for that context share one error
+ * cache and one context value.
+ */
+const reactResolutionContexts = new WeakMap();
+function reactResolutionContextFor(resolutionContext) {
+    if (resolutionContext instanceof ReactResolutionContext) {
+        return resolutionContext;
+    }
+    let wrapper = reactResolutionContexts.get(resolutionContext);
+    if (!wrapper) {
+        wrapper = new ReactResolutionContext(resolutionContext);
+        reactResolutionContexts.set(resolutionContext, wrapper);
+    }
+    return wrapper;
 }
-_ReactResolutionContext_resolutionContext = new WeakMap(), _ReactResolutionContext_resolutions = new WeakMap(), _ReactResolutionContext_resolutionErrors = new WeakMap();
+/**
+ * React Context that holds the active {@link ResolutionContext} for the component tree.
+ *
+ * The default value is an empty {@link TypeWireContainer} wrapped in a
+ * {@link ReactResolutionContext}. In practice, you should provide your own
+ * container via {@link ResolutionContextProvider}.
+ */
 export const ContainerContext = React.createContext(new ReactResolutionContext(new TypeWireContainer()));
+/**
+ * Hook to access the current {@link ResolutionContext} from the nearest
+ * {@link ResolutionContextProvider}.
+ *
+ * @returns The current resolution context
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const container = useContainer();
+ *   // Use container for manual resolution if needed
+ * }
+ * ```
+ */
 export function useContainer() {
     const container = React.useContext(ContainerContext);
     return container;
 }
-export function useTypeWire(typeWire) {
+/** Error reason thrown by {@link useTypeWire} with `{ suspend: false }`. */
+const ReasonNotPreloaded = "NotPreloaded";
+const ScopeSingleton = "singleton";
+/** Marks a state that has no value yet, so falsy values still count as values. */
+const NotReady = Symbol("NotReady");
+/**
+ * Reads a wire synchronously. Returns `NotReady` when the value isn't
+ * created yet and can be waited for; rethrows any other error.
+ */
+function readSync(typeWire, container) {
+    try {
+        return typeWire.getInstanceSync(container);
+    }
+    catch (err) {
+        if (err instanceof TypeWireError && err.retriable) {
+            return NotReady;
+        }
+        throw err;
+    }
+}
+function notPreloaded(typeWire, cause) {
+    const name = typeWire.type.symbol.description ?? "(unnamed wire)";
+    const err = new TypeWireError(ReasonNotPreloaded, `${name} is not ready. It was rendered with { suspend: false } before it was created: preload it (container.preload or usePreload) before this component renders.`);
+    err.retriable = false;
+    Object.defineProperty(err, "cause", {
+        value: cause,
+        enumerable: false,
+        writable: true,
+        configurable: true,
+    });
+    return err;
+}
+/**
+ * Hook that resolves a {@link TypeWire} within the current container context,
+ * with React Suspense integration.
+ *
+ * Resolution behavior:
+ * 1. **Sync available** — If the wire can be resolved synchronously (e.g., a singleton
+ *    that was already created or preloaded), the value is returned immediately,
+ *    including falsy values such as `0`, `""`, `false` and `null`.
+ * 2. **Async pending** — If sync resolution fails with a retriable error, the hook
+ *    starts an async resolution and throws the promise to trigger React Suspense.
+ *    With `{ suspend: false }` it throws a `TypeWireError` with reason
+ *    `NotPreloaded` instead.
+ * 3. **Error** — If sync resolution fails with a non-retriable error, it is re-thrown.
+ *
+ * To render without a fallback, preload the wires first, with
+ * `container.preload` before rendering or {@link usePreload} higher in the
+ * tree. A wire nobody preloaded suspends, so this hook must be used inside a
+ * `<Suspense>` boundary unless you pass `{ suspend: false }`.
+ *
+ * @template T The type of the resolved instance
+ * @param typeWire - The TypeWire to resolve
+ * @param opts - Optional settings; see {@link UseTypeWireOpts}
+ * @returns The resolved instance
+ * @throws The resolution promise when the value is not yet available (for Suspense)
+ * @throws {@link TypeWireError} with reason `NotPreloaded` when the value is not yet available and `suspend` is `false`
+ * @throws {@link TypeWireError} if synchronous resolution fails with a non-retriable error
+ *
+ * @example
+ * ```tsx
+ * function UserProfile() {
+ *   const userService = useTypeWire(UserServiceWire);
+ *   return <div>{userService.getName()}</div>;
+ * }
+ *
+ * // Preloaded before rendering: no fallback.
+ * await container.preload({ wires: [UserServiceWire] });
+ *
+ * // Or wrap in Suspense for wires that may not be ready yet.
+ * <Suspense fallback={<Loading />}>
+ *   <UserProfile />
+ * </Suspense>
+ * ```
+ */
+export function useTypeWire(typeWire, opts) {
     const container = useContainer();
-    const [value, setValue] = React.useState(() => {
+    const suspend = opts?.suspend ?? true;
+    const [state, setState] = React.useState(() => ({ value: readSync(typeWire, container) }));
+    if (state.value === NotReady && !suspend) {
+        let cause;
         try {
-            return typeWire.getInstanceSync(container);
+            typeWire.getInstanceSync(container);
         }
         catch (err) {
-            if (err instanceof TypeWireError && err.retriable) {
-                return null;
-            }
-            throw err;
+            cause = err;
         }
-    });
+        throw notPreloaded(typeWire, cause);
+    }
     const promise = typeWire.getInstance(container);
     React.useEffect(() => {
-        let mounted = false;
+        let mounted = true;
         promise
             .then((value) => {
             if (mounted) {
-                console.log("we got the value", value);
-                setValue(() => value);
+                // Keep the same state object for the same value, so React skips the
+                // re-render; a new object here would re-render, start a new
+                // `getInstance` and run this effect again, forever.
+                setState((prev) => (Object.is(prev.value, value) ? prev : { value }));
             }
         })
             .catch((err) => {
-            console.error(err);
+            if (mounted) {
+                console.error(err);
+            }
         });
         return () => {
             mounted = false;
         };
     }, [promise]);
-    if (value) {
-        return value;
+    if (state.value !== NotReady) {
+        return state.value;
     }
     throw promise;
 }
+/**
+ * Hook that suspends the calling component until every singleton in
+ * `opts.wires` is created, so components below it read them with
+ * {@link useTypeWire} without suspending.
+ *
+ * Use it where a part of the app starts (a route, a panel, a feature), under
+ * one `<Suspense>` boundary: the fallback shows once for the whole set, and
+ * the creations run in parallel. A creation that fails reaches the nearest
+ * error boundary.
+ *
+ * It works with any resolution context, including the Inversify adapter.
+ * Outside React, use `container.preload` instead.
+ *
+ * @param opts - The wires to preload; see {@link UsePreloadOpts}
+ * @throws A promise while any of the wires is still being created (for Suspense)
+ * @throws The creation's error, once one has failed
+ *
+ * @example
+ * ```tsx
+ * function ReportsRoute() {
+ *   usePreload({ wires: [reportsServiceWire, chartsWire] });
+ *   return <ReportsPage />;
+ * }
+ *
+ * <Suspense fallback={<Loading />}>
+ *   <ReportsRoute />
+ * </Suspense>
+ * ```
+ */
+export function usePreload(opts) {
+    const container = useContainer();
+    const pending = [];
+    for (const wire of opts.wires) {
+        if ((wire.scope ?? ScopeSingleton) !== ScopeSingleton) {
+            continue;
+        }
+        if (readSync(wire, container) === NotReady) {
+            pending.push(wire.getInstance(container));
+        }
+    }
+    if (pending.length > 0) {
+        throw Promise.all(pending);
+    }
+}
+/**
+ * React component that provides a {@link ResolutionContext} to the component tree.
+ *
+ * If the given `resolutionContext` is not already a {@link ReactResolutionContext},
+ * it is wrapped in one, so a failed resolution reaches an error boundary
+ * instead of retrying under Suspense. Each plain context gets one wrapper,
+ * reused on every render and every mount, so re-rendering the provider keeps
+ * cached errors and gives consumers the same context value.
+ *
+ * A cached error lasts until `clearErrors` is called, even after `unbind` and
+ * a re-apply. To be able to retry, create the {@link ReactResolutionContext}
+ * yourself, pass it here, and call its `clearErrors` after replacing the
+ * binding.
+ *
+ * The context must share one in-flight creation per singleton (as
+ * `TypeWireContainer` does); see {@link ReactResolutionContext}.
+ *
+ * @param props.resolutionContext - The resolution context to provide to descendants
+ * @param props.children - Child components that will have access to the context
+ *
+ * @example
+ * ```tsx
+ * async function main() {
+ *   const container = new TypeWireContainer();
+ *   await AppWireGroup.apply(container);
+ *
+ *   createRoot(document.getElementById('root')!).render(
+ *     <ResolutionContextProvider resolutionContext={container}>
+ *       <App />
+ *     </ResolutionContextProvider>
+ *   );
+ * }
+ * ```
+ */
 export function ResolutionContextProvider(props) {
-    const resolutionContext = props.resolutionContext instanceof ReactResolutionContext
-        ? props.resolutionContext
-        : new ReactResolutionContext(props.resolutionContext);
+    const resolutionContext = reactResolutionContextFor(props.resolutionContext);
     return (_jsx(ContainerContext, { value: resolutionContext, children: props.children }));
 }
 //# sourceMappingURL=index.js.map