@ts-ioc-container/react 0.36.0 → 0.37.0

package/AGENTS.md

@@ -0,0 +1,67 @@
+# @ts-ioc-container/react — guide for AI coding agents
+
+React bindings for [`ts-ioc-container`](https://www.npmjs.com/package/ts-ioc-container).
+This file ships inside the npm package, so it matches the installed version.
+For the container itself, read `node_modules/ts-ioc-container/AGENTS.md` first.
+
+## API
+
+| Export | What it does |
+| --- | --- |
+| `ScopeContext` | React context holding the current `IContainer`. Put the root container in it with `ScopeContext.Provider` |
+| `Scope` | `<Scope tags={[...]}>`: creates a child scope for its subtree once and disposes it on unmount |
+| `useScope()` | The surrounding scope, or `null` |
+| `useScopeOrFail()` | The surrounding scope; throws `OutOfScopeError` when there is none |
+| `useResolveOrFail(tokenOrClass)` | Resolves a token (`token.resolve(scope)`) or a class from the surrounding scope |
+| `OutOfScopeError` | Thrown outside a scope. `code: 'IOC_OUT_OF_SCOPE'` |
+
+## Recipe
+
+```tsx
+import 'reflect-metadata';
+import { bindTo, Container, register, Registration as R, scope, singleton, SingleToken } from 'ts-ioc-container';
+import { Scope, ScopeContext, useResolveOrFail } from '@ts-ioc-container/react';
+
+interface IGreeter {
+  greet(): string;
+}
+const IGreeterToken = new SingleToken<IGreeter>('IGreeter');
+
+// one instance per widget scope
+@register(bindTo(IGreeterToken), scope((s) => s.hasTag('widget')), singleton())
+class Greeter implements IGreeter {
+  greet() {
+    return 'hello';
+  }
+}
+
+const app = new Container({ tags: ['application'] }).addRegistration(R.fromClass(Greeter));
+
+function Greeting() {
+  const greeter = useResolveOrFail(IGreeterToken);
+  return <p>{greeter.greet()}</p>;
+}
+
+export function App() {
+  return (
+    <ScopeContext.Provider value={app}>
+      <Scope tags={['page']}>
+        <Scope tags={['widget']}>
+          <Greeting />
+        </Scope>
+      </Scope>
+    </ScopeContext.Provider>
+  );
+}
+```
+
+Frontend scope tags are `application` / `page` / `widget`.
+
+## Pitfalls
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `OutOfScopeError` | No `ScopeContext.Provider` above the component | Wrap the root in `<ScopeContext.Provider value={container}>` |
+| `DependencyNotFoundError` in a component | The registration's `scope(...)` rule does not match any scope on the path | Add a `<Scope tags={[...]}>` with the matching tag, or relax the rule |
+| Subtree uses a disposed scope in development | `StrictMode` unmounts and remounts effects, which disposes the `Scope`'s child | Render `Scope` outside `StrictMode` |
+| Registration added later is missing | Child scopes copy registrations when they are created | Register on the root container before rendering |

package/cjm/OutOfScopeError.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OutOfScopeError = void 0;
 class OutOfScopeError extends Error {
     name = 'OutOfScopeError';
+    code = 'IOC_OUT_OF_SCOPE';
     constructor(message) {
         super(message);
         Object.setPrototypeOf(this, OutOfScopeError.prototype);

package/cjm/ScopeContext.js

@@ -16,7 +16,7 @@ function useScope() {
 function useScopeOrFail() {
     const container = useScope();
     if (!container) {
-        throw new OutOfScopeError_1.OutOfScopeError('useScopeOrFail must be called inside ScopeContext.Provider');
+        throw new OutOfScopeError_1.OutOfScopeError('useScopeOrFail must be called inside ScopeContext.Provider: wrap the tree in <ScopeContext.Provider value={container}>.');
     }
     return container;
 }

package/esm/OutOfScopeError.js

@@ -1,5 +1,6 @@
 export class OutOfScopeError extends Error {
     name = 'OutOfScopeError';
+    code = 'IOC_OUT_OF_SCOPE';
     constructor(message) {
         super(message);
         Object.setPrototypeOf(this, OutOfScopeError.prototype);

package/esm/ScopeContext.js

@@ -9,7 +9,7 @@ export function useScope() {
 export function useScopeOrFail() {
     const container = useScope();
     if (!container) {
-        throw new OutOfScopeError('useScopeOrFail must be called inside ScopeContext.Provider');
+        throw new OutOfScopeError('useScopeOrFail must be called inside ScopeContext.Provider: wrap the tree in <ScopeContext.Provider value={container}>.');
     }
     return container;
 }

package/lib/OutOfScopeError.ts

@@ -0,0 +1,10 @@
+export class OutOfScopeError extends Error {
+  name = 'OutOfScopeError';
+  readonly code = 'IOC_OUT_OF_SCOPE';
+
+  constructor(message: string) {
+    super(message);
+
+    Object.setPrototypeOf(this, OutOfScopeError.prototype);
+  }
+}

package/lib/ScopeContext.tsx

@@ -0,0 +1,65 @@
+import { createContext, type ReactNode, useContext, useEffect, useState } from 'react';
+import { type constructor, type IContainer, InjectionToken } from 'ts-ioc-container';
+
+import { OutOfScopeError } from './OutOfScopeError';
+
+export const ScopeContext = createContext<IContainer | null>(null);
+
+/**
+ * Reads the surrounding scope, or `null` when there is no `ScopeContext.Provider` above the caller.
+ */
+export function useScope(): IContainer | null {
+  return useContext(ScopeContext);
+}
+
+/**
+ * @throws {OutOfScopeError} when there is no `ScopeContext.Provider` above the caller.
+ */
+export function useScopeOrFail(): IContainer {
+  const container = useScope();
+  if (!container) {
+    throw new OutOfScopeError(
+      'useScopeOrFail must be called inside ScopeContext.Provider: wrap the tree in <ScopeContext.Provider value={container}>.',
+    );
+  }
+  return container;
+}
+
+/**
+ * @throws {OutOfScopeError} when there is no `ScopeContext.Provider` above the caller.
+ */
+export function useResolveOrFail<T>(key: InjectionToken<T> | constructor<T>): T {
+  const container = useScopeOrFail();
+  if (key instanceof InjectionToken) {
+    return key.resolve(container);
+  }
+  return container.resolve(key);
+}
+
+interface ScopeProps {
+  tags: string[];
+  children: ReactNode;
+}
+
+/**
+ * Creates a child scope for its subtree once, when the component instance is
+ * first created (lazy state init), and disposes it on unmount.
+ *
+ * NOTE: relies on the surrounding tree not being wrapped in `StrictMode`.
+ * StrictMode's dev-only mount/unmount/remount cycle runs this effect's
+ * cleanup (disposing the scope) and then re-runs the effect's setup without
+ * re-rendering the component, so there is no render pass left to create a
+ * replacement — the subtree would be left on a disposed scope. Render the
+ * app root outside `StrictMode`, or scope `StrictMode` to trees that don't
+ * mount `Scope`.
+ *
+ * @throws {OutOfScopeError} when there is no `ScopeContext.Provider` above the caller.
+ */
+export function Scope(props: ScopeProps) {
+  const parent = useScopeOrFail();
+  const [child] = useState(() => parent.createScope({ tags: props.tags }));
+
+  useEffect(() => () => child.dispose(), [child]);
+
+  return <ScopeContext.Provider value={child}>{props.children}</ScopeContext.Provider>;
+}

package/lib/index.ts

@@ -0,0 +1,2 @@
+export { Scope, ScopeContext, useResolveOrFail, useScope, useScopeOrFail } from './ScopeContext';
+export { OutOfScopeError } from './OutOfScopeError';

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@ts-ioc-container/react",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "React bindings for ts-ioc-container: a Scope component that maps container scopes onto the component tree, plus hooks to resolve from the surrounding scope.",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "author": "ibabkin <igba14@gmail.com>",
-  "homepage": "https://igorbabkin.github.io/ts-ioc-container",
+  "homepage": "https://github.com/IgorBabkin/ts-ioc-container/tree/main/packages/react#readme",
   "license": "ISC",
   "sideEffects": false,
   "main": "cjm/index.js",
@@ -41,7 +41,9 @@
   "files": [
     "cjm/**/*",
     "esm/**/*",
-    "typings/**/*"
+    "typings/**/*",
+    "lib/**/*",
+    "AGENTS.md"
   ],
   "repository": {
     "type": "git",
@@ -64,7 +66,7 @@
     "typescript": "5.8.3",
     "unplugin-swc": "^1.5.9",
     "vitest": "^4.1.11",
-    "ts-ioc-container": "72.1.0"
+    "ts-ioc-container": "72.2.0"
   },
   "engines": {
     "node": ">= 18"

package/typings/OutOfScopeError.d.ts

@@ -1,4 +1,6 @@
 export declare class OutOfScopeError extends Error {
     name: string;
+    readonly code = "IOC_OUT_OF_SCOPE";
     constructor(message: string);
 }
+//# sourceMappingURL=OutOfScopeError.d.ts.map

package/typings/OutOfScopeError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OutOfScopeError.d.ts","sourceRoot":"","sources":["../lib/OutOfScopeError.ts"],"names":[],"mappings":"AAAA,qBAAa,eAAgB,SAAQ,KAAK;IACxC,IAAI,SAAqB;IACzB,QAAQ,CAAC,IAAI,sBAAsB;gBAEvB,OAAO,EAAE,MAAM;CAK5B"}

package/typings/ScopeContext.d.ts

@@ -1,12 +1,36 @@
 import { type ReactNode } from 'react';
 import { type constructor, type IContainer, InjectionToken } from 'ts-ioc-container';
 export declare const ScopeContext: import("react").Context<IContainer | null>;
+/**
+ * Reads the surrounding scope, or `null` when there is no `ScopeContext.Provider` above the caller.
+ */
 export declare function useScope(): IContainer | null;
+/**
+ * @throws {OutOfScopeError} when there is no `ScopeContext.Provider` above the caller.
+ */
 export declare function useScopeOrFail(): IContainer;
+/**
+ * @throws {OutOfScopeError} when there is no `ScopeContext.Provider` above the caller.
+ */
 export declare function useResolveOrFail<T>(key: InjectionToken<T> | constructor<T>): T;
 interface ScopeProps {
     tags: string[];
     children: ReactNode;
 }
+/**
+ * Creates a child scope for its subtree once, when the component instance is
+ * first created (lazy state init), and disposes it on unmount.
+ *
+ * NOTE: relies on the surrounding tree not being wrapped in `StrictMode`.
+ * StrictMode's dev-only mount/unmount/remount cycle runs this effect's
+ * cleanup (disposing the scope) and then re-runs the effect's setup without
+ * re-rendering the component, so there is no render pass left to create a
+ * replacement — the subtree would be left on a disposed scope. Render the
+ * app root outside `StrictMode`, or scope `StrictMode` to trees that don't
+ * mount `Scope`.
+ *
+ * @throws {OutOfScopeError} when there is no `ScopeContext.Provider` above the caller.
+ */
 export declare function Scope(props: ScopeProps): import("react").JSX.Element;
 export {};
+//# sourceMappingURL=ScopeContext.d.ts.map

package/typings/ScopeContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScopeContext.d.ts","sourceRoot":"","sources":["../lib/ScopeContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,SAAS,EAAmC,MAAM,OAAO,CAAC;AACvF,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAIrF,eAAO,MAAM,YAAY,4CAAyC,CAAC;AAEnE;;GAEG;AACH,wBAAgB,QAAQ,IAAI,UAAU,GAAG,IAAI,CAE5C;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,UAAU,CAQ3C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAM9E;AAED,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,+BAOtC"}

package/typings/index.d.ts

@@ -1,2 +1,3 @@
 export { Scope, ScopeContext, useResolveOrFail, useScope, useScopeOrFail } from './ScopeContext.js';
 export { OutOfScopeError } from './OutOfScopeError.js';
+//# sourceMappingURL=index.d.ts.map

package/typings/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACjG,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}