di-craft 0.0.14 → 0.0.16

package/README.md

@@ -1,6 +1,21 @@
-# di-craft
+<h1 align="center">di-craft</h1>
+
+<p align="center">
+  <img src="./assets/logo.png" alt="di-craft" width="200" />
+</p>
+
+<p align="center">
+  <b>A tiny, type-safe dependency injection container for TypeScript</b>
+</p>
+
+<p align="center">
+  <img alt="NPM Version" src="https://img.shields.io/npm/v/di-craft?style=flat-square&color=%2364d4c1&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2Fdi-craft">
+  <img alt="NPM package gzipped size" src="https://img.shields.io/bundlejs/size/di-craft?style=flat-square&label=gzip&color=%2364d4c1">
+</p>
+
+> [!NOTE]
+> This README was generated with a bit of AI help — don't believe everything you see 🙂
 
-A tiny, type-safe dependency injection container for TypeScript.
 
 ## Contents
 
@@ -93,7 +108,8 @@ CommonJS code can load it with a dynamic `import()`.
 
 ### Tokens
 
-A token is a unique, type-carrying key. Identity is based on an internal `symbol`, **not** on the name — two tokens with the same name are still different.
+A token is a unique, type-carrying key. Identity is based on an internal `symbol`,
+**not** on the name — two tokens with the same name are still different.
 
 ```ts
 const PORT = createToken<number>("port");
@@ -101,7 +117,8 @@ const PORT = createToken<number>("port");
 PORT.name; // "port" — used only for error messages
 ```
 
-The type argument flows everywhere: providers must produce a matching value, and `container.get(PORT)` returns `number`.
+The type argument flows everywhere: providers must produce a matching value, and
+`container.get(PORT)` returns `number`.
 
 ### Providers
 
@@ -117,13 +134,14 @@ provideValue(PORT, 3000);
 
 ```ts
 provideFactory(HTTP, {
-  deps: { config: CONFIG },         // optional, keyed map of tokens
-  scope: "singleton",                // optional, defaults to "singleton"
+  deps: { config: CONFIG }, // optional, keyed map of tokens
+  scope: "singleton", // optional, defaults to "singleton"
   useFactory: ({ config }) => new HttpClient(config.apiUrl),
 });
 ```
 
-The keys in `deps` become the keys of the object passed to `useFactory`, each resolved to its token's type.
+The keys in `deps` become the keys of the object passed to `useFactory`, each
+resolved to its token's type.
 
 ### Optional dependencies
 
@@ -153,8 +171,7 @@ const logger = container.get(optional(LOGGER)); // Logger | undefined
 ```
 
 Optional only affects the token itself: if a provider _is_ registered, it is
-resolved normally and its own errors (cycles, missing nested deps) still
-surface.
+resolved normally and its own errors (cycles, missing nested deps) still surface.
 
 ### Container
 
@@ -164,16 +181,18 @@ dispose:
 
 - `register(provider, options?)` — add a provider at any time.
 - `has(token)` — whether a provider for the token is registered.
-- `get(token)` — resolve the value, building and caching it as its scope dictates. Accepts `optional(token)` to get `undefined` instead of throwing when absent.
-- `dispose()` — run `onDispose` hooks and release resolved instances.
+- `get(token)` — resolve the value, building and caching it as its scope dictates.
+  Accepts `optional(token)` to get `undefined` instead of throwing when absent.
+- `dispose()` — run `onDispose` hooks and release tracked instances owned by this
+  container.
 
 ```ts
 const container = createContainer(providers); // providers are optional
 
 container.register(provideValue(PORT, 3000)); // register more at any time
-container.has(PORT);                           // true
-container.get(PORT);                           // 3000
-await container.dispose();                     // release resolved singletons
+container.has(PORT); // true
+container.get(PORT); // 3000
+await container.dispose(); // clears tracked instances and awaits disposal hooks
 ```
 
 Registering the same token twice throws `DuplicateProviderError`. To replace an
@@ -192,11 +211,11 @@ so the resource is released, then register the replacement.
 
 ### Scopes
 
-| Scope                  | Behavior                                                         |
-| ---------------------- | ---------------------------------------------------------------- |
-| `singleton` (default)  | The factory runs once; the same instance is returned every time. |
-| `transient`            | The factory runs on every `get`, producing a fresh instance.     |
-| `scoped`               | One instance per container. In a child container each child gets its own instance, while the provider can still be declared once on the parent. |
+| Scope                 | Behavior                                                                                                                                     |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `singleton` (default) | The factory runs once; the same instance is returned every time.                                                                              |
+| `transient`           | The factory runs on every `get`, producing a fresh instance.                                                                                  |
+| `scoped`              | One instance per container. In a child container each child gets its own instance, while the provider can still be declared once on the parent. |
 
 Use the `Scopes` helper for autocompletion, or pass the plain string — both work:
 
@@ -222,7 +241,8 @@ example, reuses the shared singleton instance.
 
 Factory providers can declare an `onDispose` hook to release resources (database
 pools, sockets, timers, subscriptions). Calling `container.dispose()` runs the
-hooks for every resolved singleton and clears the cache:
+hooks for every resolved cached instance owned by that container and releases the
+container's tracked instances:
 
 ```ts
 const DB = createToken<Pool>("db");
@@ -236,16 +256,21 @@ const container = createContainer([
 
 container.get(DB);
 
-await container.dispose(); // awaits async hooks, then clears instances
+await container.dispose(); // clears tracked instances and awaits disposal hooks
 ```
 
 Details:
 
 - Hooks run in reverse creation order (dependents before their dependencies).
 - `dispose()` returns a promise and awaits async hooks.
-- It is idempotent — calling it again is a no-op.
-- Only resolved singletons (and scoped instances on their container) are disposed; never-resolved instances are not tracked.
-- `onDispose` is only meaningful for cached instances. Declaring it on a `transient` provider throws `InvalidProviderError`, since transient instances are never tracked and the hook could never run.
+- Instances are removed from the cache before hooks run, making disposal
+  idempotent and re-entrancy safe.
+- Only resolved cached instances owned by that container are disposed: singletons
+  owned by that container and scoped instances created for that container.
+  Transient and never-resolved instances are not tracked.
+- `onDispose` is only meaningful for cached instances. Declaring it on a
+  `transient` provider throws `InvalidProviderError`, since transient instances
+  are never tracked and the hook could never run.
 
 ### Child containers
 
@@ -277,14 +302,19 @@ function handle(request: Request) {
 How resolution works across the chain:
 
 - A token is looked up in the child first, then walks up to the parent.
-- `singleton` is cached on the container that **owns** the provider, so it is shared by the whole subtree.
-- `scoped` is cached on the **requesting** child, so each child gets its own instance — even when the provider is declared once on the parent.
-- A `scoped` provider resolves its dependencies from the requesting child, so it can depend on values registered only in that child (like `REQUEST`).
-- `dispose()` only releases the container it is called on; it does not cascade to parents or children.
+- `singleton` is cached on the container that **owns** the provider, so it is
+  shared by the whole subtree.
+- `scoped` is cached on the **requesting** child, so each child gets its own
+  instance — even when the provider is declared once on the parent.
+- A `scoped` provider resolves its dependencies from the requesting child, so it
+  can depend on values registered only in that child (like `REQUEST`).
+- `dispose()` only releases the container it is called on; it does not cascade to
+  parents or children.
 
 ### Cycle detection
 
-If providers form a dependency cycle, resolution throws `CircularDependencyError` with the full path instead of overflowing the stack.
+If providers form a dependency cycle, resolution throws `CircularDependencyError`
+with the full path instead of overflowing the stack.
 
 ```ts
 // A -> B -> A
@@ -327,17 +357,33 @@ provideFactory(USERS, {
 // USERS is now Token<Promise<UsersRepo>> — consumers await it too.
 ```
 
+When using `Promise<T>` as the token value, disposal hooks receive the promise
+itself. Await it inside `onDispose` if cleanup needs the resolved value:
+
+```ts
+const POOL = createToken<Promise<Pool>>("pool");
+
+provideFactory(POOL, {
+  useFactory: () => createPool(),
+  onDispose: async (poolPromise) => {
+    const pool = await poolPromise;
+    await pool.end();
+  },
+});
+```
+
 ## Dependency injection vs service location
 
-di-craft is built for **dependency injection**: dependencies are declared up front
-and handed to your code. The opposite is **service location**, where code reaches
-into a container at runtime to pull what it needs, hiding its real dependencies.
+di-craft is built for **dependency injection**: dependencies are declared up
+front and handed to your code. The opposite is **service location**, where code
+reaches into a container at runtime to pull what it needs, hiding its real
+dependencies.
 
 Two habits keep usage canonical: call `container.get()` only at the **composition
-root** (entrypoint, framework hooks, route handlers), and never pass the container
-into your classes or functions. di-craft enforces the key half for you — **a
-factory only ever receives its declared `deps`, never the container** — so a
-provider physically cannot locate arbitrary services.
+root** (entrypoint, framework hooks, route handlers), and never pass the
+container into your classes or functions. di-craft enforces the key half for you
+— **a factory only ever receives its declared `deps`, never the container** — so
+a provider physically cannot locate arbitrary services.
 
 ```ts
 // Dependency injection — deps are explicit, the class never sees the container.
@@ -360,14 +406,15 @@ class UserService {
 }
 ```
 
-The second form compiles, but it hides dependencies and defeats DI. No runtime flag
-can forbid it — `get()` is the same call the composition root relies on — so keep
-resolution at the edges by convention, or enforce it with a lint rule that allows
-`.get()` only in your composition-root files.
+The second form compiles, but it hides dependencies and defeats DI. No runtime
+flag can forbid it — `get()` is the same call the composition root relies on — so
+keep resolution at the edges by convention, or enforce it with a lint rule that
+allows `.get()` only in your composition-root files.
 
 ## Error handling
 
-All errors extend the shared `DiError` base class, so you can catch any container error with a single check:
+All errors extend the shared `DiError` base class, so you can catch any container
+error with a single check:
 
 ```ts
 import { DiError, MissingProviderError } from "di-craft";
@@ -385,29 +432,32 @@ try {
 }
 ```
 
-| Error                      | Thrown when                                              |
-| -------------------------- | -------------------------------------------------------- |
-| `MissingProviderError`     | A token is resolved but no provider is registered.       |
-| `DuplicateProviderError`   | A token is registered more than once.                    |
-| `CircularDependencyError`  | Providers form a dependency cycle.                       |
-| `InvalidDependencyError`   | A declared dependency token is missing/undefined.        |
-| `InvalidProviderError`     | A provider is misconfigured (`onDispose` on a transient, or a dependency that outlives its consumer) or an override would drop a live disposable instance. |
+| Error                     | Thrown when                                                                                                                                                 |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MissingProviderError`    | A token is resolved but no provider is registered.                                                                                                           |
+| `DuplicateProviderError`  | A token is registered more than once.                                                                                                                        |
+| `CircularDependencyError` | Providers form a dependency cycle.                                                                                                                           |
+| `InvalidDependencyError`  | A declared dependency token is missing/undefined.                                                                                                            |
+| `InvalidProviderError`    | A provider is misconfigured (`onDispose` on a transient, or a dependency with a shorter lifetime than its consumer) or an override would drop a live disposable instance. |
 
 ## API reference
 
-| Export                  | Description                                                |
-| ----------------------- | ---------------------------------------------------------- |
-| `createToken<T>(name)`  | Create a unique, typed token.                              |
-| `provideValue(token, value)` | Provider that returns an existing value.              |
-| `provideFactory(token, options)` | Provider that builds a value via a factory.       |
-| `optional(token)`       | Mark a dependency as optional (resolves to `undefined` when absent). |
-| `createContainer(providers?)` | Create a container, optionally seeded with providers. |
-| `createChildContainer(parent, providers?)` | Create a child container that inherits from `parent`. |
-| `Scopes`                | Object of scope values (`Scopes.Singleton`, `Scopes.Transient`, `Scopes.Scoped`). |
-
-Exported types: `Container`, `Token`, `Provider`, `ValueProvider`, `FactoryProvider`, `Dependency`, `OptionalDependency`, `Scope`, `DisposeHook`, `RegisterOptions`.
-
-Exported errors: `DiError`, `MissingProviderError`, `DuplicateProviderError`, `CircularDependencyError`, `InvalidDependencyError`, `InvalidProviderError`.
+| Export                                     | Description                                                                 |
+| ------------------------------------------ | --------------------------------------------------------------------------- |
+| `createToken<T>(name)`                     | Create a unique, typed token.                                                |
+| `provideValue(token, value)`               | Provider that returns an existing value.                                     |
+| `provideFactory(token, options)`           | Provider that builds a value via a factory.                                  |
+| `optional(token)`                          | Mark a dependency as optional (resolves to `undefined` when absent).         |
+| `createContainer(providers?)`              | Create a container, optionally seeded with providers.                        |
+| `createChildContainer(parent, providers?)` | Create a child container that inherits from `parent`.                        |
+| `Scopes`                                   | Object of scope values (`Scopes.Singleton`, `Scopes.Transient`, `Scopes.Scoped`). |
+
+Exported types: `Container`, `Token`, `Provider`, `ValueProvider`,
+`FactoryProvider`, `Dependency`, `OptionalDependency`, `Scope`, `DisposeHook`,
+`RegisterOptions`.
+
+Exported errors: `DiError`, `MissingProviderError`, `DuplicateProviderError`,
+`CircularDependencyError`, `InvalidDependencyError`, `InvalidProviderError`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "di-craft",
-	"version": "0.0.14",
+	"version": "0.0.16",
 	"description": "A tiny, type-safe dependency injection container for TypeScript",
 	"license": "MIT",
 	"author": {