@typewirets/react 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 0.2.0
+
+- Depends on `@typewirets/core` 0.2.0.
+- **`useTypeWire` returns preloaded falsy values.** It ended with `if (value) return value`, so a preloaded `0`, `""`, `false` or `null` suspended as if it weren't ready, and the fallback showed. It now tells "not ready" apart from a falsy value.
+- **New: `usePreload({ wires })`.** Suspends the calling component until every singleton in `wires` is created, in parallel, so components below it read them with `useTypeWire` without suspending: one fallback for a route or feature instead of one per wire. Skips wires that aren't singletons; a failed creation reaches the nearest error boundary. Works with any resolution context. New type: `UsePreloadOpts`.
+- **New: `useTypeWire(wire, { suspend: false })`.** Throws a `TypeWireError` with reason `NotPreloaded`, naming the wire, instead of suspending when the value isn't created yet, so a forgotten preload shows up at once. The default still suspends. New type: `UseTypeWireOpts`.
+- The README leads with preloading: `container.preload` before the first render, `usePreload` per route or feature, and Suspense for wires nobody preloaded.
+- **`useTypeWire` creates a `createWith` singleton once on first mount.** With `@typewirets/core` before this release, one reader created it twice, two readers in one Suspense boundary three times, and one reader under `StrictMode` four times. The fix is in core; upgrade `@typewirets/core` and `@typewirets/react` together ([#21](https://github.com/typewirets/typewirets/issues/21)).
+- **A component no longer gets a creation started before `unbind`.** `ReactResolutionContext` kept its own map of in-flight `get` calls. After `container.unbind(type)` and a re-apply, a component that mounted while the old creation was still pending got the old binding's value, or waited forever if that creation never finished. The map is gone; `@typewirets/core` already shares one in-flight creation per singleton and keeps creations from before `unbind` away from new callers. Two side effects:
+  - A custom `ResolutionContext` passed to `ResolutionContextProvider` must now share one in-flight creation per singleton itself, or readers may get different instances. `TypeWireContainer` and the `@typewirets/inversify` adapter both do.
+  - Concurrent `get` calls through `useContainer()` for a *transient* async wire no longer share one instance.
+- **Re-rendering `ResolutionContextProvider` keeps cached errors and the context value.** The provider used to build a new `ReactResolutionContext` on every render. Any re-render cleared the error cache, so failing wires were created again, and every consumer got a new context value. With a Suspense boundary above the provider, a failing async wire was created again on every retry, forever. The provider now uses one wrapper per context.
+- **New: `ReactResolutionContext.clearErrors(typeSymbol?)`.** A cached resolution error lasts until you clear it, including after `unbind` and a re-apply, because the cache can't tell that a binding changed. To retry, pass your own `ReactResolutionContext` to the provider, call `clearErrors` after replacing the binding, and reset the error boundary. A failure that settles after `clearErrors` is not cached. See "When a resolution fails" in the README.
+- **Node.js 22 or later is required.** `engines.node` is now `>=22`, because Node.js 20 reached end-of-life on 30 April 2026. CI tests Node.js 22, 24 and 26.
+
+### Also in this release: changes prepared as 0.1.1, which was never published
+
+- **CommonJS `require()` works.** The package is `"type": "module"`, so Node loaded the CommonJS build in `dist/cjs` as an ES module: `require()` from plain Node (TypeScript compiled to CommonJS, ts-node) threw `ReferenceError: exports is not defined`. Bundlers, Jest and ESM `import` were not affected. The build now writes `dist/cjs/package.json` with `{"type":"commonjs"}`.
+
+## 0.2.0-rc.1
+
+Release candidate for 0.2.0, with the same changes. They are listed under 0.2.0.
+
+## 0.1.0
+
+- Initial release.

package/README.md

@@ -33,6 +33,10 @@ async function main() {
 
   // Apply all wires to the container at once
   await wireGroup.apply(container);
+
+  // Create them before the first render, so components read them
+  // synchronously and no Suspense fallback appears
+  await container.preload({ wires: wireGroup.wires });
   
   // Render your React app with the container
   const rootEl = document.getElementById("root");
@@ -149,9 +153,50 @@ export function UserList() {
 }
 ```
 
+## Preloading
+
+React renders synchronously, but getting a TypeWire's value is async: any creator, or an override applied later, may be async. Preloading does that waiting at your app's own boundaries, so components read values synchronously:
+
+| Where | How | What the user sees |
+|---|---|---|
+| Before the first render | `await container.preload({ wires })` (or `container.preload()` for every singleton) | No fallback at all |
+| Where a part of the app starts (a route, a panel, a feature) | `usePreload({ wires })` under one `<Suspense>` | One fallback for the whole set, then the subtree renders without suspending again |
+| Nowhere | `useTypeWire` suspends on first use | A fallback each place a wire is first read |
+
+```tsx
+import { usePreload, useTypeWire } from "@typewirets/react";
+
+function ReportsRoute() {
+  // Suspends once, until both are created (in parallel)
+  usePreload({ wires: [ReportsServiceWire, ChartsWire] });
+  return <ReportsPage />;
+}
+
+function ReportsPage() {
+  const reports = useTypeWire(ReportsServiceWire); // already created: no suspend
+  return <ReportList reports={reports} />;
+}
+
+<Suspense fallback={<div>Loading reports...</div>}>
+  <ReportsRoute />
+</Suspense>
+```
+
+`usePreload` skips wires that aren't singletons, works with any resolution context (including the Inversify adapter), and sends a failed creation to the nearest error boundary.
+
+### Catching a forgotten preload
+
+If your app preloads every phase and should never show a fallback, pass `{ suspend: false }`. A wire that isn't created yet then throws a `TypeWireError` with reason `NotPreloaded`, naming the wire, instead of suspending:
+
+```tsx
+const userStore = useTypeWire(UserStoreWire, { suspend: false });
+```
+
+Preloaded values render as they are, including `0`, `""`, `false` and `null`.
+
 ## Handling Async TypeWires
 
-When using TypeWires with async initialization, React Suspense handles the loading state:
+A wire nobody preloaded still works: React Suspense handles the loading state:
 
 ```tsx
 // Component that depends on an async TypeWire
@@ -176,10 +221,50 @@ function App({ container }) {
 }
 ```
 
+### When a resolution fails
+
+If an async TypeWire fails, `useTypeWire` throws the error to the nearest error boundary. The error is cached, so React's Suspense retries don't start the creation again and again. Re-rendering or remounting `ResolutionContextProvider` keeps the cache: the provider uses one `ReactResolutionContext` per container.
+
+The cache can't tell that a binding was replaced, so a cached error lasts until you clear it, even after `unbind` and a re-apply. To retry, create the `ReactResolutionContext` yourself, then clear its errors after replacing the binding and reset the error boundary:
+
+```tsx
+import { ReactResolutionContext, ResolutionContextProvider } from "@typewirets/react";
+
+const resolution = new ReactResolutionContext(container);
+
+function App() {
+  const [attempt, setAttempt] = useState(0);
+
+  async function retry() {
+    await container.unbind(UserStoreWire.type);
+    await UserStoreWire.apply(container);
+    resolution.clearErrors(UserStoreWire.type);
+    setAttempt((n) => n + 1); // a new key resets the error boundary
+  }
+
+  return (
+    <ResolutionContextProvider resolutionContext={resolution}>
+      <ErrorBoundary key={attempt} fallback={<button onClick={retry}>Retry</button>}>
+        <Suspense fallback={<div>Loading dashboard...</div>}>
+          <UserDashboard />
+        </Suspense>
+      </ErrorBoundary>
+    </ResolutionContextProvider>
+  );
+}
+```
+
+`ErrorBoundary` stands for any error boundary component. `clearErrors()` with no argument clears every cached error.
+
+### Custom resolution contexts
+
+`ResolutionContextProvider` accepts any `ResolutionContext`. It doesn't merge concurrent requests itself, so the context must share one in-flight creation per singleton, or components may get different instances. `TypeWireContainer` and the `@typewirets/inversify` adapter both do.
+
 ## Core Components
 
 - **ResolutionContextProvider**: Provides TypeWire container to React components
 - **useTypeWire**: Hook to access TypeWire instances in components
+- **usePreload**: Hook that suspends a subtree once, until a set of wires is created
 - **useContainer**: Direct access to the ResolutionContext (advanced use cases)
 
 ## Best Practices
@@ -187,6 +272,7 @@ function App({ container }) {
 1. **Initialize TypeWires in a main function**:
    - Group your TypeWires with `typeWireGroupOf`
    - Apply them all at once before rendering
+   - Preload what the first screen needs with `container.preload({ wires })`; preload later phases with `usePreload`
 
 2. **Use state management libraries with TypeWire**:
    - Zustand, Redux, or MobX work well with TypeWire

package/dist/cjs/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/cjs/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"}