ditox-react 3.0.1 → 3.2.0

package/README.md

@@ -2,14 +2,14 @@
 
 <img alt="lemon" src="https://raw.githubusercontent.com/mnasyrov/ditox/master/lemon.svg" width="120" />
 
-**Dependency injection container for React.js**
+**Dependency injection helpers for React.js**
 
 Please see the documentation at [ditox.js.org](https://ditox.js.org)
 
-[![npm](https://img.shields.io/npm/v/ditox)](https://www.npmjs.com/package/ditox)
+[![npm](https://img.shields.io/npm/v/ditox-react)](https://www.npmjs.com/package/ditox-react)
 [![stars](https://img.shields.io/github/stars/mnasyrov/ditox)](https://github.com/mnasyrov/ditox/stargazers)
-[![types](https://img.shields.io/npm/types/ditox)](https://www.npmjs.com/package/ditox)
-[![licence](https://img.shields.io/github/license/mnasyrov/ditox)](https://github.com/mnasyrov/ditox/blob/master/LICENSE)
+[![types](https://img.shields.io/npm/types/ditox-react)](https://www.npmjs.com/package/ditox-react)
+[![license](https://img.shields.io/github/license/mnasyrov/ditox)](https://github.com/mnasyrov/ditox/blob/master/LICENSE)
 [![coverage](https://coveralls.io/repos/github/mnasyrov/ditox/badge)](https://coveralls.io/github/mnasyrov/ditox)
 
 ## Installation
@@ -20,14 +20,14 @@ You can use the following command to install this package:
 npm install --save ditox-react
 ```
 
-The packages can be used as [UMD](https://github.com/umdjs/umd) modules. Use
-[jsdelivr.com](https://jsdelivr.com) CDN site to load
+Packages can be used as [UMD](https://github.com/umdjs/umd) modules. Use
+[jsdelivr.com](https://jsdelivr.com) CDN to load
 [ditox](https://www.jsdelivr.com/package/npm/ditox) and
 [ditox-react](https://www.jsdelivr.com/package/npm/ditox-react):
 
 ```html
-<script src="//cdn.jsdelivr.net/npm/ditox/dist/umd/index.js" />
-<script src="//cdn.jsdelivr.net/npm/ditox-react@2.3.0/dist/umd/index.js" />
+<script src="//cdn.jsdelivr.net/npm/ditox/dist/umd/index.js"></script>
+<script src="//cdn.jsdelivr.net/npm/ditox-react/dist/umd/index.js"></script>
 <script>
   const container = Ditox.createContainer();
   // DitoxReact.useDependency(SOME_TOKEN);
@@ -40,20 +40,24 @@ The packages can be used as [UMD](https://github.com/umdjs/umd) modules. Use
 in React apps:
 
 - Components:
-  - `DepencencyContainer` - provides a new or existed container to React
-    components.
-  - `DepencencyModule` - binds a dependency module to a new container.
-  - `CustomDepencencyContainer` - provides an existed dependency container.
+  - `DependencyContainer` — creates and provides a new container to React
+    children. Optionally binds dependencies via a binder callback. Can start a
+    new root container with `root` flag.
+  - `DependencyModule` — binds a dependency module to a new container (supports
+    `scope`: `singleton` (default) or `scoped`).
+  - `CustomDependencyContainer` — provides an existing dependency container.
 - Hooks:
-  - `useDependencyContainer()` - returns a provided dependency container.
-  - `useDependency()` - returns a resolved value by a specified token. It throws
-    an error in case a container or value is not found.
-  - `useOptionalDependency()` - returns a resolved value by a specified token,
-    or returns `undefined` in case a container or value is not found.
+  - `useDependencyContainer(mode?)` — returns a provided dependency container.
+    With `mode = 'strict'` it throws if the container is not provided; by
+    default it returns `undefined` when not provided.
+  - `useDependency(token)` — resolves and returns a value by a specified token.
+    Throws if a container or the value is not found.
+  - `useOptionalDependency(token)` — returns a resolved value by a specified
+    token, or `undefined` if not found or not provided.
 
 ## Usage Examples
 
-```jsx
+```tsx
 import {token} from 'ditox';
 import {
   DependencyContainer,
@@ -62,8 +66,8 @@ import {
   useOptionalDependency,
 } from 'ditox-react';
 
-const FOO_TOKEN = token();
-const BAR_TOKEN = token();
+const FOO_TOKEN = token<string>();
+const BAR_TOKEN = token<string>();
 
 function appDependencyBinder(container) {
   container.bindValue(FOO_TOKEN, 'foo');
@@ -71,15 +75,15 @@ function appDependencyBinder(container) {
 
 function App() {
   return (
-    <DependencyContainer binder={appDependencyBinder}>
+    <DependencyContainer root binder={appDependencyBinder}>
       <NestedComponent />
     </DependencyContainer>
   );
 }
 
 function NestedComponent() {
-  // Get access to the container
-  const container = useDependencyContainer();
+  // Get access to the container (optionally)
+  const container = useDependencyContainer(); // or useDependencyContainer('strict') to enforce presence
 
   // Use a resolved value
   const foo = useDependency(FOO_TOKEN);
@@ -95,21 +99,85 @@ function NestedComponent() {
 }
 ```
 
+### Providing an existing container
+
+```tsx
+import {createContainer, token} from 'ditox';
+import {CustomDependencyContainer, useDependency} from 'ditox-react';
+
+const GREETING_TOKEN = token<string>();
+
+const container = createContainer();
+container.bindValue(GREETING_TOKEN, 'Hello');
+
+function App() {
+  return (
+    <CustomDependencyContainer container={container}>
+      <Greeting />
+    </CustomDependencyContainer>
+  );
+}
+
+function Greeting() {
+  const text = useDependency(GREETING_TOKEN);
+  return <>{text}</>;
+}
+```
+
 ## Dependency Modules
 
-Dependency modules can be provided to the app with `<DependencyModule />`
-component:
+Dependency modules can be provided to the app with the `<DependencyModule />`
+component. You can also specify a binding scope (`singleton` by default or
+`scoped`):
 
 ```tsx
 function App() {
   return (
-    <DependencyModule module={LOGGER_MODULE}>
+    <DependencyModule module={LOGGER_MODULE} scope="singleton">
       <NestedComponent />
     </DependencyModule>
   );
 }
 ```
 
+## API Reference
+
+- Components
+
+  - DependencyContainer(props)
+    - props.children: ReactNode — React children to wrap
+    - props.root?: boolean — if true, create a new root container that does not
+      inherit from any parent container
+    - props.binder?: (container: Container) => unknown — optional callback to
+      set up bindings for the newly created container
+    - Behavior: creates a new container linked to the parent container by
+      default; removes all bindings on unmount
+  - CustomDependencyContainer(props)
+    - props.children: ReactNode — React children to wrap
+    - props.container: Container — an existing container instance to provide
+  - DependencyModule(props)
+    - props.children: ReactNode — React children to wrap
+    - props.module: ModuleDeclaration — module to bind to a new container
+    - props.scope?: 'singleton' | 'scoped' — scope for the module bindings
+      (default: 'singleton')
+
+- Hooks
+  - useDependencyContainer(mode?: 'optional' | 'strict')
+    - Returns the container. In 'strict' mode throws if not provided; in
+      optional mode returns undefined if not provided
+  - useDependency<T>(token: Token<T>): T
+    - Resolves and returns the value; throws if not bound or container is
+      missing
+  - useOptionalDependency<T>(token: Token<T>): T | undefined
+    - Returns the value if bound, otherwise undefined
+
+Notes:
+
+- A parent container (if provided higher in the tree) is used as the parent for
+  new containers created by DependencyContainer and DependencyModule, unless
+  root is set to true.
+- All bindings made inside a DependencyContainer are removed on unmount.
+
 ---
 
 This project is licensed under the

package/dist/browser/index.d.ts

@@ -6,8 +6,8 @@ import { ReactNode, ReactElement } from 'react';
  */
 type DependencyContainerBinder = (container: Container) => unknown;
 /**
- * Specifies an existed container or options for a new container:
- * @property binder - A callback which setup bindings to the container.
+ * Specifies options for a new container:
+ * @property binder - A callback which sets up bindings for the container.
  * @property root - If `true` then a new container does not depend on any parent containers
  */
 type DependencyContainerParams = {
@@ -18,16 +18,16 @@ type DependencyContainerParams = {
 /**
  * Provides a new dependency container to React app
  *
- * This component creates a new container and provides it down to React children.
+ * This component creates a new container and provides it to React children.
  *
- * If `binder` callback is specified, it will be called for a new container
- * to binds it with dependencies.
+ * If a `binder` callback is specified, it will be called for the new container
+ * to bind it with dependencies.
  *
- * If a parent container is exist, it is connected to the current one by default.
- * For making a new root container specify `root` parameter as `true`,
+ * If a parent container exists, it is connected to the current one by default.
+ * To create a root container specify `root` parameter as `true`,
  * and the container will not depend on any parent container.
  *
- * @param params.binder - A callback which setup bindings to the container.
+ * @param params.binder - A callback which sets up bindings for the container.
  * @param params.root - If `true` then a new container does not depend on any parent containers
  *
  * @example
@@ -101,7 +101,7 @@ declare function useOptionalDependency<T>(token: Token<T>): T | undefined;
 /**
  * Binds the module to a new dependency container.
  *
- * If a parent container is exist, it is connected to the current one by default.
+ * If a parent container exists, it is connected to the current one by default.
  *
  * @param params.module - Module declaration for binding
  * @param params.scope - Optional scope for binding: `singleton` (default) or `scoped`.

package/dist/cjs/DependencyContainer.d.ts

@@ -6,8 +6,8 @@ export declare const DependencyContainerContext: React.Context<Container | undef
  */
 export type DependencyContainerBinder = (container: Container) => unknown;
 /**
- * Specifies an existed container or options for a new container:
- * @property binder - A callback which setup bindings to the container.
+ * Specifies options for a new container:
+ * @property binder - A callback which sets up bindings for the container.
  * @property root - If `true` then a new container does not depend on any parent containers
  */
 export type DependencyContainerParams = {
@@ -18,16 +18,16 @@ export type DependencyContainerParams = {
 /**
  * Provides a new dependency container to React app
  *
- * This component creates a new container and provides it down to React children.
+ * This component creates a new container and provides it to React children.
  *
- * If `binder` callback is specified, it will be called for a new container
- * to binds it with dependencies.
+ * If a `binder` callback is specified, it will be called for the new container
+ * to bind it with dependencies.
  *
- * If a parent container is exist, it is connected to the current one by default.
- * For making a new root container specify `root` parameter as `true`,
+ * If a parent container exists, it is connected to the current one by default.
+ * To create a root container specify `root` parameter as `true`,
  * and the container will not depend on any parent container.
  *
- * @param params.binder - A callback which setup bindings to the container.
+ * @param params.binder - A callback which sets up bindings for the container.
  * @param params.root - If `true` then a new container does not depend on any parent containers
  *
  * @example

package/dist/cjs/DependencyContainer.js

@@ -30,16 +30,16 @@ exports.DependencyContainerContext = (0, react_1.createContext)(undefined);
 /**
  * Provides a new dependency container to React app
  *
- * This component creates a new container and provides it down to React children.
+ * This component creates a new container and provides it to React children.
  *
- * If `binder` callback is specified, it will be called for a new container
- * to binds it with dependencies.
+ * If a `binder` callback is specified, it will be called for the new container
+ * to bind it with dependencies.
  *
- * If a parent container is exist, it is connected to the current one by default.
- * For making a new root container specify `root` parameter as `true`,
+ * If a parent container exists, it is connected to the current one by default.
+ * To create a root container specify `root` parameter as `true`,
  * and the container will not depend on any parent container.
  *
- * @param params.binder - A callback which setup bindings to the container.
+ * @param params.binder - A callback which sets up bindings for the container.
  * @param params.root - If `true` then a new container does not depend on any parent containers
  *
  * @example

package/dist/cjs/DependencyModule.d.ts

@@ -3,7 +3,7 @@ import { ReactElement, ReactNode } from 'react';
 /**
  * Binds the module to a new dependency container.
  *
- * If a parent container is exist, it is connected to the current one by default.
+ * If a parent container exists, it is connected to the current one by default.
  *
  * @param params.module - Module declaration for binding
  * @param params.scope - Optional scope for binding: `singleton` (default) or `scoped`.

package/dist/cjs/DependencyModule.js

@@ -30,7 +30,7 @@ const DependencyContainer_1 = require("./DependencyContainer");
 /**
  * Binds the module to a new dependency container.
  *
- * If a parent container is exist, it is connected to the current one by default.
+ * If a parent container exists, it is connected to the current one by default.
  *
  * @param params.module - Module declaration for binding
  * @param params.scope - Optional scope for binding: `singleton` (default) or `scoped`.

package/dist/esm/DependencyContainer.d.ts

@@ -6,8 +6,8 @@ export declare const DependencyContainerContext: React.Context<Container | undef
  */
 export type DependencyContainerBinder = (container: Container) => unknown;
 /**
- * Specifies an existed container or options for a new container:
- * @property binder - A callback which setup bindings to the container.
+ * Specifies options for a new container:
+ * @property binder - A callback which sets up bindings for the container.
  * @property root - If `true` then a new container does not depend on any parent containers
  */
 export type DependencyContainerParams = {
@@ -18,16 +18,16 @@ export type DependencyContainerParams = {
 /**
  * Provides a new dependency container to React app
  *
- * This component creates a new container and provides it down to React children.
+ * This component creates a new container and provides it to React children.
  *
- * If `binder` callback is specified, it will be called for a new container
- * to binds it with dependencies.
+ * If a `binder` callback is specified, it will be called for the new container
+ * to bind it with dependencies.
  *
- * If a parent container is exist, it is connected to the current one by default.
- * For making a new root container specify `root` parameter as `true`,
+ * If a parent container exists, it is connected to the current one by default.
+ * To create a root container specify `root` parameter as `true`,
  * and the container will not depend on any parent container.
  *
- * @param params.binder - A callback which setup bindings to the container.
+ * @param params.binder - A callback which sets up bindings for the container.
  * @param params.root - If `true` then a new container does not depend on any parent containers
  *
  * @example

package/dist/esm/DependencyContainer.js

@@ -4,16 +4,16 @@ export const DependencyContainerContext = createContext(undefined);
 /**
  * Provides a new dependency container to React app
  *
- * This component creates a new container and provides it down to React children.
+ * This component creates a new container and provides it to React children.
  *
- * If `binder` callback is specified, it will be called for a new container
- * to binds it with dependencies.
+ * If a `binder` callback is specified, it will be called for the new container
+ * to bind it with dependencies.
  *
- * If a parent container is exist, it is connected to the current one by default.
- * For making a new root container specify `root` parameter as `true`,
+ * If a parent container exists, it is connected to the current one by default.
+ * To create a root container specify `root` parameter as `true`,
  * and the container will not depend on any parent container.
  *
- * @param params.binder - A callback which setup bindings to the container.
+ * @param params.binder - A callback which sets up bindings for the container.
  * @param params.root - If `true` then a new container does not depend on any parent containers
  *
  * @example

package/dist/esm/DependencyModule.d.ts

@@ -3,7 +3,7 @@ import { ReactElement, ReactNode } from 'react';
 /**
  * Binds the module to a new dependency container.
  *
- * If a parent container is exist, it is connected to the current one by default.
+ * If a parent container exists, it is connected to the current one by default.
  *
  * @param params.module - Module declaration for binding
  * @param params.scope - Optional scope for binding: `singleton` (default) or `scoped`.

package/dist/esm/DependencyModule.js

@@ -4,7 +4,7 @@ import { DependencyContainer, } from './DependencyContainer';
 /**
  * Binds the module to a new dependency container.
  *
- * If a parent container is exist, it is connected to the current one by default.
+ * If a parent container exists, it is connected to the current one by default.
  *
  * @param params.module - Module declaration for binding
  * @param params.scope - Optional scope for binding: `singleton` (default) or `scoped`.

package/dist/umd/index.d.ts

@@ -6,8 +6,8 @@ import { ReactNode, ReactElement } from 'react';
  */
 type DependencyContainerBinder = (container: Container) => unknown;
 /**
- * Specifies an existed container or options for a new container:
- * @property binder - A callback which setup bindings to the container.
+ * Specifies options for a new container:
+ * @property binder - A callback which sets up bindings for the container.
  * @property root - If `true` then a new container does not depend on any parent containers
  */
 type DependencyContainerParams = {
@@ -18,16 +18,16 @@ type DependencyContainerParams = {
 /**
  * Provides a new dependency container to React app
  *
- * This component creates a new container and provides it down to React children.
+ * This component creates a new container and provides it to React children.
  *
- * If `binder` callback is specified, it will be called for a new container
- * to binds it with dependencies.
+ * If a `binder` callback is specified, it will be called for the new container
+ * to bind it with dependencies.
  *
- * If a parent container is exist, it is connected to the current one by default.
- * For making a new root container specify `root` parameter as `true`,
+ * If a parent container exists, it is connected to the current one by default.
+ * To create a root container specify `root` parameter as `true`,
  * and the container will not depend on any parent container.
  *
- * @param params.binder - A callback which setup bindings to the container.
+ * @param params.binder - A callback which sets up bindings for the container.
  * @param params.root - If `true` then a new container does not depend on any parent containers
  *
  * @example
@@ -101,7 +101,7 @@ declare function useOptionalDependency<T>(token: Token<T>): T | undefined;
 /**
  * Binds the module to a new dependency container.
  *
- * If a parent container is exist, it is connected to the current one by default.
+ * If a parent container exists, it is connected to the current one by default.
  *
  * @param params.module - Module declaration for binding
  * @param params.scope - Optional scope for binding: `singleton` (default) or `scoped`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ditox-react",
-  "version": "3.0.1",
+  "version": "3.2.0",
   "description": "Dependency injection container for React.js",
   "publishConfig": {
     "access": "public"
@@ -57,7 +57,7 @@
     "typedoc": "typedoc"
   },
   "dependencies": {
-    "ditox": "3.0.0"
+    "ditox": "3.2.0"
   },
   "peerDependencies": {
     "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
@@ -69,5 +69,5 @@
     "react-dom": "19.0.0",
     "react-test-renderer": "19.0.0"
   },
-  "gitHead": "d5f20401897dc859670feeb0e55d74d4b54818db"
+  "gitHead": "493e9ba9fcb36feea88e3948a23a4249a119d03e"
 }

package/src/DependencyContainer.tsx

@@ -19,8 +19,8 @@ export const DependencyContainerContext = createContext<Container | undefined>(
 export type DependencyContainerBinder = (container: Container) => unknown;
 
 /**
- * Specifies an existed container or options for a new container:
- * @property binder - A callback which setup bindings to the container.
+ * Specifies options for a new container:
+ * @property binder - A callback which sets up bindings for the container.
  * @property root - If `true` then a new container does not depend on any parent containers
  */
 export type DependencyContainerParams = {
@@ -32,16 +32,16 @@ export type DependencyContainerParams = {
 /**
  * Provides a new dependency container to React app
  *
- * This component creates a new container and provides it down to React children.
+ * This component creates a new container and provides it to React children.
  *
- * If `binder` callback is specified, it will be called for a new container
- * to binds it with dependencies.
+ * If a `binder` callback is specified, it will be called for the new container
+ * to bind it with dependencies.
  *
- * If a parent container is exist, it is connected to the current one by default.
- * For making a new root container specify `root` parameter as `true`,
+ * If a parent container exists, it is connected to the current one by default.
+ * To create a root container specify `root` parameter as `true`,
  * and the container will not depend on any parent container.
  *
- * @param params.binder - A callback which setup bindings to the container.
+ * @param params.binder - A callback which sets up bindings for the container.
  * @param params.root - If `true` then a new container does not depend on any parent containers
  *
  * @example

package/src/DependencyModule.tsx

@@ -9,7 +9,7 @@ import {
 /**
  * Binds the module to a new dependency container.
  *
- * If a parent container is exist, it is connected to the current one by default.
+ * If a parent container exists, it is connected to the current one by default.
  *
  * @param params.module - Module declaration for binding
  * @param params.scope - Optional scope for binding: `singleton` (default) or `scoped`.