di-craft 0.0.17 → 0.0.19

package/README.md

@@ -17,10 +17,6 @@
   </a>
 </p>
 
-> [!NOTE]
-> This README was generated with a bit of AI help — don't believe everything you see 🙂
-
-
 ## Contents
 
 - [Quick start](#quick-start)
@@ -30,6 +26,7 @@
 - [Core concepts](#core-concepts)
   - [Tokens](#tokens)
   - [Providers](#providers)
+  - [Annotation-based class providers](#annotation-based-class-providers)
   - [Optional dependencies](#optional-dependencies)
   - [Container](#container)
   - [Scopes](#scopes)
@@ -37,6 +34,8 @@
   - [Child containers](#child-containers)
   - [Cycle detection](#cycle-detection)
   - [Async dependencies](#async-dependencies)
+- [Adapters](#adapters)
+  - [Next.js App Router](#nextjs-app-router)
 - [Dependency injection vs service location](#dependency-injection-vs-service-location)
 - [Error handling](#error-handling)
 - [API reference](#api-reference)
@@ -80,14 +79,17 @@ const users = container.get(USERS); // UserService, fully typed
 
 ## Philosophy
 
-Dependency injection without the magic — no decorators, no `reflect-metadata`, no
-framework coupling. You work with just **tokens**, **providers**, a **container**,
-**scopes**, and **cycle detection**.
+Dependency injection without hidden magic — no `reflect-metadata`, no runtime
+type guessing, and no framework coupling. You work with just **tokens**,
+**providers**, a **container**, **scopes**, and **cycle detection**. Standard
+JavaScript decorators are available as optional sugar for class providers, but
+they still use explicit tokens.
 
 ## Features
 
 - Zero runtime dependencies
 - Type-safe tokens and factories
+- Optional `@Injectable` annotation for class providers
 - Optional dependencies via `optional()`
 - Singleton, transient, and scoped lifetimes
 - Hierarchical child containers
@@ -147,6 +149,63 @@ provideFactory(HTTP, {
 The keys in `deps` become the keys of the object passed to `useFactory`, each
 resolved to its token's type.
 
+### Annotation-based class providers
+
+If you write services as classes, you can attach provider metadata to the class
+with standard JavaScript decorators, then turn the class into a normal provider
+with `provideInjectable`.
+
+`@Injectable(options)` marks a class as a provider for `options.token`.
+`deps` is an ordered list of constructor dependencies. `scope` and
+`onDispose` behave exactly like they do in `provideFactory`.
+
+```ts
+import {
+  Injectable,
+  Scopes,
+  createContainer,
+  createToken,
+  optional,
+  provideInjectable,
+  provideValue,
+} from "di-craft";
+
+const CONFIG = createToken<Config>("config");
+const LOGGER = createToken<Logger>("logger");
+const USERS = createToken<UserService>("users");
+
+@Injectable({
+  token: USERS,
+  deps: [LOGGER, optional(CONFIG)],
+  scope: Scopes.Scoped,
+})
+class UserService {
+  private readonly logger: Logger;
+  private readonly config: Config | undefined;
+
+  constructor(logger: Logger, config: Config | undefined) {
+    this.logger = logger;
+    this.config = config;
+  }
+}
+
+const container = createContainer([
+  provideValue(LOGGER, new Logger()),
+  provideInjectable(UserService),
+]);
+
+const users = container.get(USERS); // UserService
+```
+
+`@Injectable` is the only annotation needed for class injection. It produces a
+regular factory provider internally, so all existing container behavior still
+applies: optional dependencies, scopes, child containers, disposal hooks,
+overrides, and cycle detection.
+
+di-craft does not use `reflect-metadata` or parameter decorators. Constructor
+types are erased by JavaScript at runtime, so dependency tokens stay explicit
+instead of being guessed from TypeScript types.
+
 ### Optional dependencies
 
 Wrap a token with `optional` to mark a dependency as not required. When no
@@ -376,6 +435,125 @@ provideFactory(POOL, {
 });
 ```
 
+## Adapters
+
+Adapters are optional framework integrations built around the core container.
+They live behind subpath exports, so the root import stays framework-agnostic:
+
+```ts
+import { createContainer } from "di-craft"; // core only
+```
+
+### Next.js App Router
+
+The Next adapter helps connect di-craft to the App Router request lifecycle
+without making React or Next.js part of the core import.
+
+Use `di-craft/next/server` from a server-only composition file. Pass React's
+`cache` function so React/Next owns request memoization while di-craft owns only
+the dependency graph:
+
+```ts
+// app/di.server.ts
+import "server-only";
+import { cache } from "react";
+import { provideValue } from "di-craft";
+import { createNextDi } from "di-craft/next/server";
+
+export const {
+  getRequestContainer,
+  getRootContainer,
+  runWithRequestContainer,
+} = createNextDi({
+  cache,
+  providers,
+  requestProviders: () => [
+    provideValue(REQUEST_ID, crypto.randomUUID()),
+  ],
+});
+```
+
+Then resolve dependencies in Server Components at the composition edge:
+
+```ts
+import { getRequestContainer } from "./di.server";
+
+export default async function Page() {
+  const users = getRequestContainer().get(USERS_SERVICE);
+
+  return <UsersView users={await users.list()} />;
+}
+```
+
+Next.js does not expose a general "RSC render is finished" hook, so the adapter
+does not pretend it can automatically dispose a cached Server Component request
+container. If you own the lifecycle, for example in a Route Handler, Server
+Action, test, or job, use `runWithRequestContainer`. It creates a fresh child
+container and disposes it in a `finally` block:
+
+```ts
+import { runWithRequestContainer } from "./di.server";
+
+export async function GET() {
+  return runWithRequestContainer({
+    run: async (container) => {
+      const users = await container.get(USERS_SERVICE).list();
+
+      return Response.json(users);
+    },
+  });
+}
+```
+
+State hydration is explicit. The server reads serializable snapshots with
+`di-craft/next/server`; the client restores them with `di-craft/next/client`.
+The DI container itself is never hydrated.
+
+Import boundary-specific runtime helpers from their own subpath:
+
+- `di-craft/next/server` — `createNextDi`, `dehydrate`, server-only adapter types.
+- `di-craft/next/client` — `hydrate`, client-boundary hydration types.
+- Shared hydration contracts like `Hydratable`, `HydrationSchema`, and
+  `HydrationSnapshot` are exported from both subpaths for convenience.
+
+```ts
+import {
+  dehydrate,
+  type Hydratable,
+  type HydrationSchema,
+} from "di-craft/next/server";
+
+class UserState implements Hydratable<UserSnapshot> {
+  dehydrate(): UserSnapshot {
+    return { users: this.users };
+  }
+
+  hydrate(snapshot: UserSnapshot): void {
+    this.users = snapshot.users;
+  }
+}
+
+const hydration = {
+  user: USER_STATE,
+} satisfies HydrationSchema;
+const snapshot = dehydrate({
+  container: getRequestContainer(),
+  schema: hydration,
+});
+```
+
+```ts
+"use client";
+
+import { hydrate } from "di-craft/next/client";
+
+hydrate({
+  container: clientContainer,
+  schema: hydration,
+  snapshot,
+});
+```
+
 ## Dependency injection vs service location
 
 di-craft is built for **dependency injection**: dependencies are declared up
@@ -451,6 +629,8 @@ try {
 | `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.                                  |
+| `@Injectable(options)`                     | Mark a class as a token-backed injectable provider.                          |
+| `provideInjectable(class)`                 | Create a factory provider from an injectable class.                           |
 | `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`.                        |
@@ -463,6 +643,13 @@ Exported types: `Container`, `Token`, `Provider`, `ValueProvider`,
 Exported errors: `DiError`, `MissingProviderError`, `DuplicateProviderError`,
 `CircularDependencyError`, `InvalidDependencyError`, `InvalidProviderError`.
 
+Subpath exports:
+
+| Export                      | Description                                             |
+| --------------------------- | ------------------------------------------------------- |
+| `di-craft/next/server`      | Next.js server adapter for request-scoped containers.   |
+| `di-craft/next/client`      | Client-boundary helpers for restoring state snapshots.  |
+
 ## License
 
 [MIT](./LICENSE)

package/dist/container-C6GcrdNn.mjs

@@ -0,0 +1 @@
+var e=class extends Error{constructor(e){super(e),this.name=`DiError`,Error.captureStackTrace&&Error.captureStackTrace(this,this.constructor)}},t=class extends e{constructor(e){super(e),this.name=`InvalidProviderError`}};const n={Singleton:`singleton`,Transient:`transient`,Scoped:`scoped`},r=(e,t)=>({provide:e,useValue:t}),i=(e,r)=>{if(r.scope===n.Transient&&r.onDispose)throw new t(`onDispose is not supported for transient providers (token "${e.name}"): transient instances are not tracked, so the hook would never run.`);return{provide:e,useFactory:r.useFactory,scope:r.scope??n.Singleton,...r.deps?{deps:r.deps}:{},...r.onDispose?{onDispose:r.onDispose}:{}}},a=e=>({token:e,optional:!0}),o=e=>e.optional===!0,s=e=>`useValue`in e;var c=class extends e{constructor(e){super(`Provider for token "${e}" is already registered`),this.name=`DuplicateProviderError`}},l=class{providers=new Map;register(e,t){let n=this.providers.has(e.provide.id);if(n&&!t?.allowOverride)throw new c(e.provide.name);return this.providers.set(e.provide.id,e),n}get(e){return this.providers.get(e.id)}has(e){return this.providers.has(e.id)}};const u=()=>new l;var d=class extends e{constructor(e){super(`Provider for token "${e}" is not registered`),this.name=`MissingProviderError`}},f=class extends e{constructor(e){super(`Invalid dependency "${e}"`),this.name=`InvalidDependencyError`}},p=class extends e{constructor(e){super(`Circular dependency detected: ${e.join(` -> `)}`),this.name=`CircularDependencyError`}},m=class{instances=new Map;get(e){return this.instances.get(e.id)}set(e,t){this.instances.set(e.id,t)}delete(e){this.instances.delete(e.id)}async dispose(){let e=[...this.instances.values()].reverse();this.instances.clear();for(let t of e)t.onDispose&&await t.onDispose(t.value)}};const h=()=>new m;var g=class{resolving=new Set;path=[];enter(e){if(this.resolving.has(e.id)){let t=this.path.findIndex(t=>t.id===e.id);throw new p([...this.path.slice(t),e].map(e=>e.name))}this.resolving.add(e.id),this.path.push(e)}exit(e){this.path.pop(),this.resolving.delete(e.id)}};const _=e=>e===n.Scoped?1:e===n.Transient?2:0;var v=class{registry;store=h();parent;constructor(e,t){this.registry=e,this.parent=t}resolve(e){return this.resolveToken(e,void 0)}resolveOptional(e){return this.lookupOptional(e,void 0)}invalidate(e){this.store.delete(e)}hasDisposableInstance(e){return this.store.get(e)?.onDispose!==void 0}dispose(){return this.store.dispose()}resolveToken(e,r,i,a){let o=this,c;for(;o&&(c=o.registry.get(e),!c);)o=o.parent;if(!c||!o)throw new d(e.name);if(s(c))return c.useValue;if(i!==void 0&&_(c.scope)>_(i))throw new t(`"${a}" (${i}) cannot depend on "${e.name}" (${c.scope??n.Singleton}): a longer-lived provider would capture a shorter-lived one. Widen the dependency's scope or narrow the consumer's.`);let l=this.selectHost(c.scope,o);if(l){let t=l.store.get(e);if(t)return t.value}let u=r??new g;u.enter(e);try{let t=(l??this).resolveDeps(c.deps,u,c.scope,e.name),n=c.useFactory(t);return l&&l.store.set(e,{value:n,...c.onDispose?{onDispose:c.onDispose}:{}}),n}finally{u.exit(e)}}selectHost(e,t){if(e!==n.Transient)return e===n.Scoped?this:t}resolveDeps(e,t,n,r){if(!e)return{};let i={};for(let a of Object.keys(e)){let s=e[a];if(s===void 0)throw new f(String(a));i[a]=o(s)?this.lookupOptional(s.token,t,n,r):this.resolveToken(s,t,n,r)}return i}lookupOptional(e,t,n,r){let i=this;for(;i;){if(i.registry.has(e))return this.resolveToken(e,t,n,r);i=i.parent}}};const y=(e,t)=>new v(e,t);var b=class{registry;resolver;parent;constructor(e=[],t){this.parent=t,this.registry=u();for(let t of e)this.registry.register(t);this.resolver=y(this.registry,t?.resolver)}register(e,n){if(n?.allowOverride&&this.resolver.hasDisposableInstance(e.provide))throw new t(`Cannot override token "${e.provide.name}": its instance was already created and has an onDispose hook. Dispose the container before replacing it.`);this.registry.register(e,n)&&this.resolver.invalidate(e.provide)}get(e){return o(e)?this.resolver.resolveOptional(e.token):this.resolver.resolve(e)}has(e){return this.registry.has(e)||(this.parent?.has(e)??!1)}dispose(){return this.resolver.dispose()}};const x=(e=[])=>new b(e),S=(e,t=[])=>new b(t,e);export{d as a,i as c,t as d,e as f,f as i,r as l,x as n,c as o,p as r,a as s,S as t,n as u};

package/dist/hydration-BJ-gWd38.d.mts

@@ -0,0 +1,174 @@
+import { d as Token, l as Provider, t as Container } from "./types-BzLfq9VA.mjs";
+
+//#region src/adapters/next/types.d.ts
+/**
+* Minimal shape of React's `cache` function needed by the adapter.
+*
+* Passing it in keeps React out of di-craft's dependency graph while still
+* letting React/Next own the current request cache.
+*
+* @example
+* ```ts
+* import { cache } from "react";
+*
+* createNextDi({ cache, providers });
+* ```
+*/
+type RequestCache = <T>(factory: () => T) => () => T;
+/**
+* Options for `createNextDi`.
+*/
+type CreateNextDiOptions = {
+  /**
+  * Providers registered once in the root server container.
+  */
+  readonly providers?: readonly Provider[];
+  /**
+  * React request cache, imported from `react` in a Next server file.
+  */
+  readonly cache: RequestCache;
+  /**
+  * Providers registered in each request-scoped child container.
+  */
+  readonly requestProviders?: () => readonly Provider[];
+};
+/**
+* Options for running work inside a fresh request-scoped child container.
+*/
+type RunWithRequestContainerOptions<TResult> = {
+  /**
+  * Extra providers registered only for this manual request container.
+  */
+  readonly providers?: readonly Provider[];
+  /**
+  * Work that owns the request lifecycle. The container is disposed after this
+  * callback settles.
+  */
+  readonly run: (container: Container) => TResult | Promise<TResult>;
+};
+/**
+* Next.js server adapter instance created by `createNextDi`.
+*/
+type NextDiAdapter = {
+  /**
+  * Returns the long-lived root server container.
+  */
+  readonly getRootContainer: () => Container;
+  /**
+  * Returns the current request-scoped child container.
+  */
+  readonly getRequestContainer: () => Container;
+  /**
+  * Creates a fresh child container manually, useful in route handlers or tests.
+  */
+  readonly createRequestContainer: (providers?: readonly Provider[]) => Container;
+  /**
+  * Runs work inside a fresh child container and disposes it in a `finally`
+  * block. Use this in Route Handlers, Server Actions, or tests where the
+  * request lifecycle is explicit.
+  */
+  readonly runWithRequestContainer: <TResult>(options: RunWithRequestContainerOptions<TResult>) => Promise<Awaited<TResult>>;
+  /**
+  * Disposes cached instances owned by the root container.
+  */
+  readonly disposeRootContainer: () => Promise<void>;
+};
+type SerializablePrimitive = string | number | boolean | null;
+/**
+* JSON-like value that can safely cross a Server Component boundary.
+*/
+type Serializable = SerializablePrimitive | readonly Serializable[] | {
+  readonly [key: string]: Serializable;
+};
+/**
+* Entity that can expose and restore a serializable state snapshot.
+*
+* The snapshot, not the DI container, is what crosses the RSC/client boundary.
+*/
+type Hydratable<TSnapshot extends Serializable> = {
+  /**
+  * Returns the minimal serializable state needed by the client.
+  */
+  dehydrate(): TSnapshot;
+  /**
+  * Restores state from a previously serialized snapshot.
+  */
+  hydrate(snapshot: TSnapshot): void;
+};
+/**
+* Named hydratable tokens that define a client-boundary snapshot shape.
+*
+* Use it with `satisfies` to validate the schema without losing literal keys or
+* token-specific snapshot inference.
+*
+* @example
+* ```ts
+* const hydration = {
+*   user: USER_STATE,
+* } satisfies HydrationSchema;
+* ```
+*/
+type HydrationSchema = Readonly<Record<string, Token<Hydratable<Serializable>>>>;
+/**
+* Snapshot object inferred from a hydration schema.
+*/
+type HydrationSnapshot<TSchema extends HydrationSchema> = { readonly [TKey in keyof TSchema]: TSchema[TKey] extends Token<Hydratable<infer TSnapshot>> ? TSnapshot : never };
+/**
+* Options for reading a serializable snapshot from a container.
+*/
+type DehydrateOptions<TSchema extends HydrationSchema> = {
+  /**
+  * Container that owns the hydratable state entities.
+  */
+  readonly container: Container;
+  /**
+  * Hydratable tokens keyed by snapshot field name.
+  */
+  readonly schema: TSchema;
+};
+/**
+* Options for restoring a serializable snapshot into a container.
+*/
+type HydrateOptions<TSchema extends HydrationSchema> = DehydrateOptions<TSchema> & {
+  /**
+  * Serializable state produced by `dehydrate` for the same schema.
+  */
+  readonly snapshot: HydrationSnapshot<TSchema>;
+};
+//#endregion
+//#region src/adapters/next/hydration.d.ts
+/**
+* Reads serializable snapshots from hydratable entities declared in a schema.
+*
+* Use this on the server side before crossing into a Client Component. Only the
+* returned snapshot should cross the boundary, not the container or service
+* instances themselves.
+*
+* @example
+* ```ts
+* const hydration = { user: USER_STATE };
+* const snapshot = dehydrate({
+*   container: getRequestContainer(),
+*   schema: hydration,
+* });
+* ```
+*/
+declare const dehydrate: <const TSchema extends HydrationSchema>(options: DehydrateOptions<TSchema>) => HydrationSnapshot<TSchema>;
+/**
+* Restores serializable snapshots into hydratable entities declared in a schema.
+*
+* Use this with a client-safe container and the snapshot received through a
+* Client Component prop.
+*
+* @example
+* ```ts
+* hydrate({
+*   container: clientContainer,
+*   schema: hydration,
+*   snapshot,
+* });
+* ```
+*/
+declare const hydrate: <const TSchema extends HydrationSchema>(options: HydrateOptions<TSchema>) => void;
+//#endregion
+export { Hydratable as a, HydrationSnapshot as c, RunWithRequestContainerOptions as d, Serializable as f, DehydrateOptions as i, NextDiAdapter as l, hydrate as n, HydrateOptions as o, SerializablePrimitive as p, CreateNextDiOptions as r, HydrationSchema as s, dehydrate as t, RequestCache as u };

package/dist/hydration-DsCFyhuJ.mjs

@@ -0,0 +1 @@
+const e=e=>{let t={};for(let n of Object.keys(e.schema)){let r=e.schema[n],i=r===void 0,a=String(n);if(i)throw Error(`Missing hydration token for key "${a}".`);t[a]=e.container.get(r).dehydrate()}return t},t=e=>{let t=e.snapshot;for(let n of Object.keys(e.schema)){let r=e.schema[n],i=String(n),a=t[i],o=r===void 0,s=a===void 0;if(o)throw Error(`Missing hydration token for key "${i}".`);if(s)throw Error(`Missing hydration snapshot for key "${i}".`);e.container.get(r).hydrate(a)}};export{t as n,e as t};

package/dist/index.d.mts

@@ -1,98 +1,181 @@
-//#region src/error/error.d.ts
+import { a as DisposeHook, c as OptionalDependency, d as Token, f as Scope, i as DepsMap, l as Provider, n as RegisterOptions, o as Factory, p as Scopes, r as Dependency, s as FactoryProvider, t as Container, u as ValueProvider } from "./types-BzLfq9VA.mjs";
+
+//#region src/core/error/error.d.ts
+/**
+* Base class for all di-craft runtime errors.
+*/
 declare class DiError extends Error {
   constructor(message: string);
 }
 //#endregion
-//#region src/provider/errors.d.ts
+//#region src/core/provider/errors.d.ts
+/**
+* Error thrown when a provider configuration cannot be used safely.
+*/
 declare class InvalidProviderError extends DiError {
   constructor(message: string);
 }
 //#endregion
-//#region src/scope/scope.d.ts
-declare const Scopes: {
-  readonly Singleton: "singleton";
-  readonly Transient: "transient";
-  readonly Scoped: "scoped";
-};
-type Scope = (typeof Scopes)[keyof typeof Scopes];
-//#endregion
-//#region src/token/types.d.ts
-type Token<T> = {
-  readonly id: symbol;
-  readonly name: string;
-  readonly __type?: T;
-};
-//#endregion
-//#region src/token/token.d.ts
+//#region src/core/token/token.d.ts
+/**
+* Creates a unique typed token.
+*
+* The `name` is used only for diagnostics. Token identity is unique per call,
+* so two tokens with the same name do not collide.
+*
+* @example
+* ```ts
+* const CONFIG = createToken<Config>("config");
+* ```
+*/
 declare const createToken: <T>(name: string) => Token<T>;
 //#endregion
-//#region src/provider/types.d.ts
-type OptionalDependency<T> = {
-  readonly token: Token<T>;
-  readonly optional: true;
-};
-type Dependency<T> = Token<T> | OptionalDependency<T>;
-type DepsMap = Record<string, Dependency<unknown>>;
-type DependencyValue<TDep> = TDep extends OptionalDependency<infer T> ? T | undefined : TDep extends Token<infer T> ? T : never;
-type ResolveDeps<TDeps extends DepsMap> = { readonly [TKey in keyof TDeps]: DependencyValue<TDeps[TKey]> };
-type Factory<T, TDeps extends DepsMap> = (deps: ResolveDeps<TDeps>) => T;
-type DisposeHook<T> = (instance: T) => void | Promise<void>;
-type ValueProvider<T> = {
-  readonly provide: Token<T>;
-  readonly useValue: T;
-};
-type FactoryProvider<T, TDeps extends DepsMap = Record<never, never>> = {
-  readonly provide: Token<T>;
-  readonly deps?: TDeps;
-  readonly scope?: Scope;
-  readonly useFactory: Factory<T, TDeps>;
-  readonly onDispose?: DisposeHook<T>;
-};
-type AnyFactoryProvider = FactoryProvider<any, any>;
-type Provider = ValueProvider<unknown> | AnyFactoryProvider;
-//#endregion
-//#region src/provider/provider.d.ts
+//#region src/core/provider/provider.d.ts
+/**
+* Creates a provider for an already constructed value.
+*
+* The value must match the token type.
+*
+* @example
+* ```ts
+* provideValue(PORT, 3000);
+* ```
+*/
 declare const provideValue: <T>(token: Token<T>, useValue: T) => ValueProvider<T>;
+/**
+* Creates a provider that lazily builds a value.
+*
+* Dependencies declared in `deps` become the object passed to `useFactory`.
+* The factory return type must match the token type.
+*
+* @example
+* ```ts
+* provideFactory(HTTP, {
+*   deps: { config: CONFIG },
+*   useFactory: ({ config }) => new HttpClient(config.apiUrl),
+* });
+* ```
+*/
 declare const provideFactory: <T, TDeps extends DepsMap = Record<never, never>>(token: Token<T>, options: {
   readonly deps?: TDeps;
   readonly scope?: Scope;
   readonly useFactory: Factory<T, TDeps>;
   readonly onDispose?: DisposeHook<T>;
 }) => FactoryProvider<T, TDeps>;
+/**
+* Marks a token as optional.
+*
+* Optional dependencies resolve to `undefined` instead of throwing when no
+* provider exists in the container chain. They can be used in factory `deps`
+* or passed directly to `container.get`.
+*
+* @example
+* ```ts
+* const logger = container.get(optional(LOGGER));
+* ```
+*/
 declare const optional: <T>(token: Token<T>) => OptionalDependency<T>;
 //#endregion
-//#region src/registry/errors.d.ts
+//#region src/core/registry/errors.d.ts
+/**
+* Error thrown when registering a provider for an already registered token.
+*/
 declare class DuplicateProviderError extends DiError {
   constructor(tokenName: string);
 }
 //#endregion
-//#region src/registry/types.d.ts
-type RegisterOptions = {
-  readonly allowOverride?: boolean;
-};
+//#region src/core/container/container.d.ts
+/**
+* Creates a root container with optional initial providers.
+*
+* Root containers own singleton instances for providers registered in them.
+*/
+declare const createContainer: (providers?: readonly Provider[]) => Container;
+/**
+* Creates a child container that can resolve providers from its parent.
+*
+* Child containers may register their own providers while still reusing parent
+* providers. Scoped providers create one cached instance per resolving child.
+*/
+declare const createChildContainer: (parent: Container, providers?: readonly Provider[]) => Container;
 //#endregion
-//#region src/container/types.d.ts
-type Container = {
-  register(provider: Provider, options?: RegisterOptions): void;
-  get<T>(token: Token<T>): T;
-  get<T>(dependency: OptionalDependency<T>): T | undefined;
-  has(token: Token<unknown>): boolean;
-  dispose(): Promise<void>;
+//#region src/core/annotation/types.d.ts
+type InjectableDeps = readonly Dependency<unknown>[];
+type DependencyValue<TDependency> = TDependency extends OptionalDependency<infer T> ? T | undefined : TDependency extends Token<infer T> ? T : never;
+type ResolveDependencyTuple<TDeps extends InjectableDeps> = { -readonly [TKey in keyof TDeps]: DependencyValue<TDeps[TKey]> };
+/**
+* Constructor type whose parameters match an injectable dependency tuple.
+*/
+type InjectableConstructor<T, TDeps extends InjectableDeps> = new (...args: ResolveDependencyTuple<TDeps>) => T;
+/**
+* Class that can be passed to `provideInjectable`.
+*
+* `never[]` keeps classes with required constructor parameters assignable
+* without claiming arbitrary constructor arguments are valid.
+*/
+type InjectableClass<T = unknown> = new (...args: never[]) => T;
+/**
+* Options stored by `@Injectable` and converted into a factory provider.
+*/
+type InjectableOptions<T, TDeps extends InjectableDeps = InjectableDeps> = {
+  /**
+  * Token provided by the decorated class.
+  */
+  readonly token: Token<T>;
+  /**
+  * Ordered constructor dependencies.
+  *
+  * Each item is resolved and passed to the constructor at the same index.
+  */
+  readonly deps?: TDeps;
+  /**
+  * Provider lifetime.
+  *
+  * Defaults to `Scopes.Singleton`.
+  */
+  readonly scope?: Scope;
+  /**
+  * Cleanup hook for cached singleton and scoped instances.
+  *
+  * Not supported for transient providers.
+  */
+  readonly onDispose?: DisposeHook<T>;
 };
 //#endregion
-//#region src/container/container.d.ts
-declare const createContainer: (providers?: readonly Provider[]) => Container;
-declare const createChildContainer: (parent: Container, providers?: readonly Provider[]) => Container;
+//#region src/core/annotation/annotation.d.ts
+type InjectableDecorator<TTarget> = (target: TTarget, context: ClassDecoratorContext) => void;
+type InjectableOptionsWithoutDeps<T> = Omit<InjectableOptions<T, readonly []>, "deps">;
+declare function Injectable<T, const TDeps extends readonly Dependency<unknown>[]>(options: InjectableOptions<T, TDeps> & {
+  readonly deps: TDeps;
+}): InjectableDecorator<InjectableConstructor<T, TDeps>>;
+declare function Injectable<T>(options: InjectableOptionsWithoutDeps<T>): InjectableDecorator<InjectableConstructor<T, readonly []>>;
+/**
+* Creates a factory provider from a class marked with `@Injectable`.
+*
+* The returned provider is a normal di-craft factory provider, so scopes,
+* optional dependencies, disposal hooks, overrides, and cycle detection behave
+* the same as with `provideFactory`.
+*/
+declare function provideInjectable<T>(target: InjectableClass<T>): FactoryProvider<T, DepsMap>;
 //#endregion
-//#region src/resolver/errors.d.ts
+//#region src/core/resolver/errors.d.ts
+/**
+* Error thrown when resolving a token without a registered provider.
+*/
 declare class MissingProviderError extends DiError {
   constructor(tokenName: string);
 }
+/**
+* Error thrown when a dependency descriptor is invalid.
+*/
 declare class InvalidDependencyError extends DiError {
   constructor(dependencyKey: string);
 }
+/**
+* Error thrown when provider dependencies form a cycle.
+*/
 declare class CircularDependencyError extends DiError {
   constructor(tokenNames: string[]);
 }
 //#endregion
-export { CircularDependencyError, type Container, type Dependency, DiError, type DisposeHook, DuplicateProviderError, type FactoryProvider, InvalidDependencyError, InvalidProviderError, MissingProviderError, type OptionalDependency, type Provider, type RegisterOptions, type Scope, Scopes, type Token, type ValueProvider, createChildContainer, createContainer, createToken, optional, provideFactory, provideValue };
+export { CircularDependencyError, type Container, type Dependency, DiError, type DisposeHook, DuplicateProviderError, type FactoryProvider, Injectable, InvalidDependencyError, InvalidProviderError, MissingProviderError, type OptionalDependency, type Provider, type RegisterOptions, type Scope, Scopes, type Token, type ValueProvider, createChildContainer, createContainer, createToken, optional, provideFactory, provideInjectable, provideValue };

package/dist/index.mjs

@@ -1,267 +1 @@
-//#region src/error/error.ts
-var DiError = class extends Error {
-	constructor(message) {
-		super(message);
-		this.name = "DiError";
-		if (Error.captureStackTrace) Error.captureStackTrace(this, this.constructor);
-	}
-};
-
-//#endregion
-//#region src/provider/errors.ts
-var InvalidProviderError = class extends DiError {
-	constructor(message) {
-		super(message);
-		this.name = "InvalidProviderError";
-	}
-};
-
-//#endregion
-//#region src/scope/scope.ts
-const Scopes = {
-	Singleton: "singleton",
-	Transient: "transient",
-	Scoped: "scoped"
-};
-
-//#endregion
-//#region src/provider/provider.ts
-const provideValue = (token, useValue) => ({
-	provide: token,
-	useValue
-});
-const provideFactory = (token, options) => {
-	if (options.scope === Scopes.Transient && options.onDispose) throw new InvalidProviderError(`onDispose is not supported for transient providers (token "${token.name}"): transient instances are not tracked, so the hook would never run.`);
-	return {
-		provide: token,
-		useFactory: options.useFactory,
-		scope: options.scope ?? Scopes.Singleton,
-		...options.deps ? { deps: options.deps } : {},
-		...options.onDispose ? { onDispose: options.onDispose } : {}
-	};
-};
-const optional = (token) => ({
-	token,
-	optional: true
-});
-const isOptionalDependency = (dependency) => {
-	return dependency.optional === true;
-};
-const isValueProvider = (provider) => {
-	return "useValue" in provider;
-};
-
-//#endregion
-//#region src/registry/errors.ts
-var DuplicateProviderError = class extends DiError {
-	constructor(tokenName) {
-		super(`Provider for token "${tokenName}" is already registered`);
-		this.name = "DuplicateProviderError";
-	}
-};
-
-//#endregion
-//#region src/registry/registry.ts
-var RegistryClass = class {
-	providers = /* @__PURE__ */ new Map();
-	register(provider, options) {
-		const existed = this.providers.has(provider.provide.id);
-		if (existed && !options?.allowOverride) throw new DuplicateProviderError(provider.provide.name);
-		this.providers.set(provider.provide.id, provider);
-		return existed;
-	}
-	get(token) {
-		return this.providers.get(token.id);
-	}
-	has(token) {
-		return this.providers.has(token.id);
-	}
-};
-const createRegistry = () => new RegistryClass();
-
-//#endregion
-//#region src/resolver/errors.ts
-var MissingProviderError = class extends DiError {
-	constructor(tokenName) {
-		super(`Provider for token "${tokenName}" is not registered`);
-		this.name = "MissingProviderError";
-	}
-};
-var InvalidDependencyError = class extends DiError {
-	constructor(dependencyKey) {
-		super(`Invalid dependency "${dependencyKey}"`);
-		this.name = "InvalidDependencyError";
-	}
-};
-var CircularDependencyError = class extends DiError {
-	constructor(tokenNames) {
-		super(`Circular dependency detected: ${tokenNames.join(" -> ")}`);
-		this.name = "CircularDependencyError";
-	}
-};
-
-//#endregion
-//#region src/store/store.ts
-var StoreClass = class {
-	instances = /* @__PURE__ */ new Map();
-	get(token) {
-		return this.instances.get(token.id);
-	}
-	set(token, record) {
-		this.instances.set(token.id, record);
-	}
-	delete(token) {
-		this.instances.delete(token.id);
-	}
-	async dispose() {
-		const records = [...this.instances.values()].reverse();
-		this.instances.clear();
-		for (const record of records) if (record.onDispose) await record.onDispose(record.value);
-	}
-};
-const createStore = () => new StoreClass();
-
-//#endregion
-//#region src/resolver/context.ts
-var ResolutionContext = class {
-	resolving = /* @__PURE__ */ new Set();
-	path = [];
-	enter(token) {
-		if (this.resolving.has(token.id)) {
-			const cycleStartIndex = this.path.findIndex((pathToken) => pathToken.id === token.id);
-			throw new CircularDependencyError([...this.path.slice(cycleStartIndex), token].map((cycleToken) => cycleToken.name));
-		}
-		this.resolving.add(token.id);
-		this.path.push(token);
-	}
-	exit(token) {
-		this.path.pop();
-		this.resolving.delete(token.id);
-	}
-};
-
-//#endregion
-//#region src/resolver/resolver.ts
-const lifetimeRank = (scope) => scope === Scopes.Scoped ? 1 : scope === Scopes.Transient ? 2 : 0;
-var ResolverClass = class {
-	registry;
-	store = createStore();
-	parent;
-	constructor(registry, parent) {
-		this.registry = registry;
-		this.parent = parent;
-	}
-	resolve(token) {
-		return this.resolveToken(token, void 0);
-	}
-	resolveOptional(token) {
-		return this.lookupOptional(token, void 0);
-	}
-	invalidate(token) {
-		this.store.delete(token);
-	}
-	hasDisposableInstance(token) {
-		return this.store.get(token)?.onDispose !== void 0;
-	}
-	dispose() {
-		return this.store.dispose();
-	}
-	resolveToken(token, context, consumerScope, consumerName) {
-		let owner = this;
-		let provider;
-		while (owner) {
-			provider = owner.registry.get(token);
-			if (provider) break;
-			owner = owner.parent;
-		}
-		if (!provider || !owner) throw new MissingProviderError(token.name);
-		if (isValueProvider(provider)) return provider.useValue;
-		if (consumerScope !== void 0 && lifetimeRank(provider.scope) > lifetimeRank(consumerScope)) throw new InvalidProviderError(`"${consumerName}" (${consumerScope}) cannot depend on "${token.name}" (${provider.scope ?? Scopes.Singleton}): a longer-lived provider would capture a shorter-lived one. Widen the dependency's scope or narrow the consumer's.`);
-		const host = this.selectHost(provider.scope, owner);
-		if (host) {
-			const cached = host.store.get(token);
-			if (cached) return cached.value;
-		}
-		const ctx = context ?? new ResolutionContext();
-		ctx.enter(token);
-		try {
-			const deps = (host ?? this).resolveDeps(provider.deps, ctx, provider.scope, token.name);
-			const value = provider.useFactory(deps);
-			if (host) host.store.set(token, {
-				value,
-				...provider.onDispose ? { onDispose: provider.onDispose } : {}
-			});
-			return value;
-		} finally {
-			ctx.exit(token);
-		}
-	}
-	selectHost(scope, owner) {
-		if (scope === Scopes.Transient) return;
-		if (scope === Scopes.Scoped) return this;
-		return owner;
-	}
-	resolveDeps(deps, context, consumerScope, consumerName) {
-		if (!deps) return {};
-		const resolvedDeps = {};
-		for (const key of Object.keys(deps)) {
-			const dependency = deps[key];
-			if (dependency === void 0) throw new InvalidDependencyError(String(key));
-			resolvedDeps[key] = isOptionalDependency(dependency) ? this.lookupOptional(dependency.token, context, consumerScope, consumerName) : this.resolveToken(dependency, context, consumerScope, consumerName);
-		}
-		return resolvedDeps;
-	}
-	lookupOptional(token, context, consumerScope, consumerName) {
-		let owner = this;
-		while (owner) {
-			if (owner.registry.has(token)) return this.resolveToken(token, context, consumerScope, consumerName);
-			owner = owner.parent;
-		}
-	}
-};
-const createResolver = (registry, parent) => new ResolverClass(registry, parent);
-
-//#endregion
-//#region src/container/container.ts
-var ContainerClass = class {
-	registry;
-	resolver;
-	parent;
-	constructor(providers = [], parent) {
-		this.parent = parent;
-		this.registry = createRegistry();
-		for (const provider of providers) this.registry.register(provider);
-		this.resolver = createResolver(this.registry, parent?.resolver);
-	}
-	register(provider, options) {
-		if (options?.allowOverride && this.resolver.hasDisposableInstance(provider.provide)) throw new InvalidProviderError(`Cannot override token "${provider.provide.name}": its instance was already created and has an onDispose hook. Dispose the container before replacing it.`);
-		if (this.registry.register(provider, options)) this.resolver.invalidate(provider.provide);
-	}
-	get(dependency) {
-		if (isOptionalDependency(dependency)) return this.resolver.resolveOptional(dependency.token);
-		return this.resolver.resolve(dependency);
-	}
-	has(token) {
-		return this.registry.has(token) || (this.parent?.has(token) ?? false);
-	}
-	dispose() {
-		return this.resolver.dispose();
-	}
-};
-const createContainer = (providers = []) => new ContainerClass(providers);
-const createChildContainer = (parent, providers = []) => new ContainerClass(providers, parent);
-
-//#endregion
-//#region src/token/token.ts
-var TokenClass = class {
-	name;
-	id;
-	constructor(name) {
-		this.name = name;
-		this.id = Symbol(name);
-	}
-};
-const createToken = (name) => new TokenClass(name);
-
-//#endregion
-export { CircularDependencyError, DiError, DuplicateProviderError, InvalidDependencyError, InvalidProviderError, MissingProviderError, Scopes, createChildContainer, createContainer, createToken, optional, provideFactory, provideValue };
+import{a as e,c as t,d as n,f as r,i,l as a,n as o,o as s,r as c,s as l,t as u,u as d}from"./container-C6GcrdNn.mjs";const f=e=>{if(e.length!==0)return Object.fromEntries(e.entries())},p=new WeakMap,m=e=>p.get(e),h=e=>{p.set(e.target,e.metadata)},g=e=>{let{context:t,target:r}=e;if(!(t.kind===`class`&&typeof r==`function`))throw new n(`@Injectable can only decorate classes`)};function _(e){return(t,n)=>{g({target:t,context:n}),h({target:t,metadata:e})}}function v(e){let r=m(e);if(!r)throw new n(`Class "${e.name||`<anonymous>`}" is not marked as injectable. Add @Injectable({ token: TOKEN }) before calling provideInjectable().`);let{deps:i=[],onDispose:a,scope:o,token:s}=r,c=f(i),l=e;return t(s,{useFactory:e=>new l(...i.map((t,n)=>e[String(n)])),...c?{deps:c}:{},...o?{scope:o}:{},...a?{onDispose:a}:{}})}var y=class{name;id;constructor(e){this.name=e,this.id=Symbol(e)}};const b=e=>new y(e);export{c as CircularDependencyError,r as DiError,s as DuplicateProviderError,_ as Injectable,i as InvalidDependencyError,n as InvalidProviderError,e as MissingProviderError,d as Scopes,u as createChildContainer,o as createContainer,b as createToken,l as optional,t as provideFactory,v as provideInjectable,a as provideValue};

package/dist/next/client.d.mts

@@ -0,0 +1,2 @@
+import { a as Hydratable, c as HydrationSnapshot, f as Serializable, n as hydrate, o as HydrateOptions, p as SerializablePrimitive, s as HydrationSchema } from "../hydration-BJ-gWd38.mjs";
+export { type Hydratable, type HydrateOptions, type HydrationSchema, type HydrationSnapshot, type Serializable, type SerializablePrimitive, hydrate };

package/dist/next/client.mjs

@@ -0,0 +1 @@
+import{n as e}from"../hydration-DsCFyhuJ.mjs";export{e as hydrate};

package/dist/next/server.d.mts

@@ -0,0 +1,33 @@
+import { a as Hydratable, c as HydrationSnapshot, d as RunWithRequestContainerOptions, f as Serializable, i as DehydrateOptions, l as NextDiAdapter, p as SerializablePrimitive, r as CreateNextDiOptions, s as HydrationSchema, t as dehydrate, u as RequestCache } from "../hydration-BJ-gWd38.mjs";
+
+//#region src/adapters/next/server.d.ts
+/**
+* Creates a server adapter for Next.js App Router and React Server Components.
+*
+* The root container is created once. `getRequestContainer` creates a child
+* container through the provided React request cache, so repeated calls inside
+* one RSC request resolve through the same scoped dependency graph.
+*
+* Import this helper from a server-only composition file. The adapter does not
+* import React itself; pass `cache` from `react` so React/Next owns request
+* memoization.
+*
+* @example
+* ```ts
+* import "server-only";
+* import { cache } from "react";
+* import { createNextDi } from "di-craft/next/server";
+*
+* export const { getRequestContainer } = createNextDi({
+*   cache,
+*   providers,
+* });
+* ```
+*/
+declare const createNextDi: ({
+  cache,
+  providers,
+  requestProviders
+}: CreateNextDiOptions) => NextDiAdapter;
+//#endregion
+export { type CreateNextDiOptions, type DehydrateOptions, type Hydratable, type HydrationSchema, type HydrationSnapshot, type NextDiAdapter, type RequestCache, type RunWithRequestContainerOptions, type Serializable, type SerializablePrimitive, createNextDi, dehydrate };

package/dist/next/server.mjs

@@ -0,0 +1 @@
+import{n as e,t}from"../container-C6GcrdNn.mjs";import{t as n}from"../hydration-DsCFyhuJ.mjs";const r=()=>{if(`window`in globalThis)throw Error(`di-craft/next/server can only be used in a server runtime.`)},i=({cache:n,providers:i=[],requestProviders:a})=>{r();let o=e(i),s=(e=[])=>t(o,[...a?.()??[],...e]);return{getRootContainer:()=>o,getRequestContainer:n(()=>s()),createRequestContainer:s,runWithRequestContainer:async({providers:e=[],run:t})=>{let n=s(e);try{return await t(n)}finally{await n.dispose()}},disposeRootContainer:()=>o.dispose()}};export{i as createNextDi,n as dehydrate};

package/dist/types-BzLfq9VA.d.mts

@@ -0,0 +1,140 @@
+//#region src/core/scope/scope.d.ts
+/**
+* Built-in provider lifetimes.
+*/
+declare const Scopes: {
+  readonly Singleton: "singleton";
+  readonly Transient: "transient";
+  readonly Scoped: "scoped";
+};
+/**
+* Provider lifetime.
+*
+* - `singleton`: one cached instance in the container that owns the provider.
+* - `scoped`: one cached instance in the container that resolves the provider.
+* - `transient`: a new instance for every resolution.
+*/
+type Scope = (typeof Scopes)[keyof typeof Scopes];
+//#endregion
+//#region src/core/token/types.d.ts
+/** A unique, typed key used to register and resolve a dependency. */
+type Token<T> = {
+  /**
+  * Runtime identity of the token.
+  *
+  * Tokens with the same name still have different identities.
+  */
+  readonly id: symbol;
+  /**
+  * Human-readable name used in error messages and diagnostics.
+  */
+  readonly name: string;
+  readonly __type?: T;
+};
+//#endregion
+//#region src/core/provider/types.d.ts
+/**
+* A token wrapped as an optional dependency.
+*
+* Optional dependencies resolve to `undefined` when no provider is registered
+* in the container chain.
+*/
+type OptionalDependency<T> = {
+  readonly token: Token<T>;
+  readonly optional: true;
+};
+/**
+* A dependency accepted by factory providers and `container.get`.
+*/
+type Dependency<T> = Token<T> | OptionalDependency<T>;
+type DepsMap = Record<string, Dependency<unknown>>;
+type DependencyValue<TDep> = TDep extends OptionalDependency<infer T> ? T | undefined : TDep extends Token<infer T> ? T : never;
+type ResolveDeps<TDeps extends DepsMap> = { readonly [TKey in keyof TDeps]: DependencyValue<TDeps[TKey]> };
+type Factory<T, TDeps extends DepsMap> = (deps: ResolveDeps<TDeps>) => T;
+/**
+* Cleanup hook called for a cached instance during container disposal.
+*
+* Transient providers cannot use disposal hooks because their instances are not
+* cached or tracked by the container.
+*/
+type DisposeHook<T> = (instance: T) => void | Promise<void>;
+/**
+* Provider that resolves a token to an existing value.
+*/
+type ValueProvider<T> = {
+  readonly provide: Token<T>;
+  readonly useValue: T;
+};
+/**
+* Provider that lazily creates a token value from typed dependencies.
+*
+* `deps` keys become the properties passed to `useFactory`, `scope` controls
+* caching lifetime, and `onDispose` runs for cached singleton/scoped instances.
+*/
+type FactoryProvider<T, TDeps extends DepsMap = Record<never, never>> = {
+  readonly provide: Token<T>;
+  readonly deps?: TDeps;
+  readonly scope?: Scope;
+  readonly useFactory: Factory<T, TDeps>;
+  readonly onDispose?: DisposeHook<T>;
+};
+type AnyFactoryProvider = FactoryProvider<any, any>;
+/**
+* Provider accepted by `createContainer` and `container.register`.
+*/
+type Provider = ValueProvider<unknown> | AnyFactoryProvider;
+//#endregion
+//#region src/core/registry/types.d.ts
+/**
+* Options for provider registration.
+*/
+type RegisterOptions = {
+  /**
+  * Replace an existing provider for the same token.
+  *
+  * Overriding an already resolved disposable singleton is rejected to avoid
+  * dropping resources without running their cleanup hook.
+  */
+  readonly allowOverride?: boolean;
+};
+//#endregion
+//#region src/core/container/types.d.ts
+/**
+* Container that stores providers and resolves typed dependencies.
+*/
+type Container = {
+  /**
+  * Registers a provider in this container.
+  *
+  * Pass `{ allowOverride: true }` to intentionally replace an existing
+  * provider for the same token.
+  */
+  register(provider: Provider, options?: RegisterOptions): void;
+  /**
+  * Resolves a required token.
+  *
+  * Throws `MissingProviderError` when no provider exists in this container or
+  * any parent container.
+  */
+  get<T>(token: Token<T>): T;
+  /**
+  * Resolves an optional dependency.
+  *
+  * Returns `undefined` when no provider exists in this container or any parent
+  * container.
+  */
+  get<T>(dependency: OptionalDependency<T>): T | undefined;
+  /**
+  * Checks whether this container or one of its parents has a provider.
+  */
+  has(token: Token<unknown>): boolean;
+  /**
+  * Disposes cached instances owned by this container.
+  *
+  * Disposal hooks run in reverse creation order. Calling `dispose` more than
+  * once is safe.
+  */
+  dispose(): Promise<void>;
+};
+//#endregion
+export { DisposeHook as a, OptionalDependency as c, Token as d, Scope as f, DepsMap as i, Provider as l, RegisterOptions as n, Factory as o, Scopes as p, Dependency as r, FactoryProvider as s, Container as t, ValueProvider as u };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "di-craft",
-	"version": "0.0.17",
+	"version": "0.0.19",
 	"description": "A tiny, type-safe dependency injection container for TypeScript",
 	"license": "MIT",
 	"author": {
@@ -20,6 +20,14 @@
 			"types": "./dist/index.d.mts",
 			"default": "./dist/index.mjs"
 		},
+		"./next/client": {
+			"types": "./dist/next/client.d.mts",
+			"default": "./dist/next/client.mjs"
+		},
+		"./next/server": {
+			"types": "./dist/next/server.d.mts",
+			"default": "./dist/next/server.mjs"
+		},
 		"./package.json": "./package.json"
 	},
 	"files": [