@typewirets/react 0.1.0 → 0.2.0

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.tsx"],"names":[],"mappings":"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"}

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