di-craft 0.0.18 → 0.0.20

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)
@@ -38,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)
@@ -437,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
@@ -526,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,4 +1,6 @@
-//#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.
 */
@@ -6,7 +8,7 @@ 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.
 */
@@ -14,41 +16,7 @@ declare class InvalidProviderError extends DiError {
   constructor(message: string);
 }
 //#endregion
-//#region src/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/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/token/token.d.ts
+//#region src/core/token/token.d.ts
 /**
 * Creates a unique typed token.
 *
@@ -62,59 +30,7 @@ type Token<T> = {
 */
 declare const createToken: <T>(name: string) => Token<T>;
 //#endregion
-//#region src/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$1<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$1<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/provider/provider.d.ts
+//#region src/core/provider/provider.d.ts
 /**
 * Creates a provider for an already constructed value.
 *
@@ -160,7 +76,30 @@ declare const provideFactory: <T, TDeps extends DepsMap = Record<never, never>>(
 */
 declare const optional: <T>(token: Token<T>) => OptionalDependency<T>;
 //#endregion
-//#region src/annotation/types.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/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/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]> };
@@ -203,7 +142,7 @@ type InjectableOptions<T, TDeps extends InjectableDeps = InjectableDeps> = {
   readonly onDispose?: DisposeHook<T>;
 };
 //#endregion
-//#region src/annotation/annotation.d.ts
+//#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> & {
@@ -219,83 +158,7 @@ declare function Injectable<T>(options: InjectableOptionsWithoutDeps<T>): Inject
 */
 declare function provideInjectable<T>(target: InjectableClass<T>): FactoryProvider<T, DepsMap>;
 //#endregion
-//#region src/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
-/**
-* 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/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
-//#region src/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/resolver/errors.d.ts
+//#region src/core/resolver/errors.d.ts
 /**
 * Error thrown when resolving a token without a registered provider.
 */

package/dist/index.mjs

@@ -1 +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,c=e=>{if(e.length!==0)return Object.fromEntries(e.entries())},l=new WeakMap,u=e=>l.get(e),d=e=>{l.set(e.target,e.metadata)},f=e=>{let{context:n,target:r}=e;if(!(n.kind===`class`&&typeof r==`function`))throw new t(`@Injectable can only decorate classes`)};function p(e){return(t,n)=>{f({target:t,context:n}),d({target:t,metadata:e})}}function m(e){let n=u(e);if(!n)throw new t(`Class "${e.name||`<anonymous>`}" is not marked as injectable. Add @Injectable({ token: TOKEN }) before calling provideInjectable().`);let{deps:r=[],onDispose:a,scope:o,token:s}=n,l=c(r),d=e;return i(s,{useFactory:e=>new d(...r.map((t,n)=>e[String(n)])),...l?{deps:l}:{},...o?{scope:o}:{},...a?{onDispose:a}:{}})}var h=class extends e{constructor(e){super(`Provider for token "${e}" is already registered`),this.name=`DuplicateProviderError`}},g=class{providers=new Map;register(e,t){let n=this.providers.has(e.provide.id);if(n&&!t?.allowOverride)throw new h(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 _=()=>new g;var v=class extends e{constructor(e){super(`Provider for token "${e}" is not registered`),this.name=`MissingProviderError`}},y=class extends e{constructor(e){super(`Invalid dependency "${e}"`),this.name=`InvalidDependencyError`}},b=class extends e{constructor(e){super(`Circular dependency detected: ${e.join(` -> `)}`),this.name=`CircularDependencyError`}},x=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 S=()=>new x;var C=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 b([...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 w=e=>e===n.Scoped?1:e===n.Transient?2:0;var T=class{registry;store=S();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 v(e.name);if(s(c))return c.useValue;if(i!==void 0&&w(c.scope)>w(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 C;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 y(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 E=(e,t)=>new T(e,t);var D=class{registry;resolver;parent;constructor(e=[],t){this.parent=t,this.registry=_();for(let t of e)this.registry.register(t);this.resolver=E(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 O=(e=[])=>new D(e),k=(e,t=[])=>new D(t,e);var A=class{name;id;constructor(e){this.name=e,this.id=Symbol(e)}};const j=e=>new A(e);export{b as CircularDependencyError,e as DiError,h as DuplicateProviderError,p as Injectable,y as InvalidDependencyError,t as InvalidProviderError,v as MissingProviderError,n as Scopes,k as createChildContainer,O as createContainer,j as createToken,a as optional,i as provideFactory,m as provideInjectable,r as 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.18",
+	"version": "0.0.20",
 	"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": [