@fluojs/di 1.0.0-beta.1

package/dist/errors.d.ts

@@ -0,0 +1,62 @@
+import { FluoCodeError } from '@fluojs/core';
+/**
+ * Structured context attached to DI errors so logs and tests can inspect the failing contract.
+ */
+export interface DiErrorContext {
+    readonly token?: unknown;
+    readonly scope?: string;
+    readonly module?: string;
+    readonly dependencyChain?: readonly unknown[];
+    readonly hint?: string;
+}
+/**
+ * Raised when a provider declaration or inject token cannot be normalized into a valid DI registration.
+ *
+ * @remarks
+ * This usually points to malformed provider objects, missing `@Inject(...)` tokens, or `null`/
+ * `undefined` references that were evaluated before a `forwardRef()` indirection could be applied.
+ */
+export declare class InvalidProviderError extends FluoCodeError {
+    constructor(message: string, context?: DiErrorContext);
+}
+/**
+ * Raised when the container cannot complete a lifecycle operation such as registration, resolution, or disposal.
+ *
+ * @remarks
+ * Use the attached context to inspect the token, module, scope, or dependency chain involved in the failed operation.
+ */
+export declare class ContainerResolutionError extends FluoCodeError {
+    constructor(message: string, context?: DiErrorContext);
+}
+/**
+ * Raised when a request-scoped provider is resolved outside a request container.
+ *
+ * @remarks
+ * This protects the documented lifecycle guarantee that request-scoped providers are isolated per child scope.
+ */
+export declare class RequestScopeResolutionError extends FluoCodeError {
+    constructor(message: string, context?: DiErrorContext);
+}
+/**
+ * Raised when a provider scope is registered or consumed from an incompatible container scope.
+ */
+export declare class ScopeMismatchError extends FluoCodeError {
+    constructor(message: string, context?: DiErrorContext);
+}
+/**
+ * Raised when the container detects a circular dependency chain while resolving providers.
+ *
+ * @remarks
+ * The formatted message includes the full dependency path plus a first-party hint that points callers toward
+ * extracting shared logic or using `forwardRef()` for intentional cycle deferral.
+ */
+export declare class CircularDependencyError extends FluoCodeError {
+    constructor(chain: readonly unknown[], detail?: string);
+}
+/**
+ * Raised when the same token is registered twice without going through `container.override(...)`.
+ */
+export declare class DuplicateProviderError extends FluoCodeError {
+    constructor(token: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAmB,MAAM,cAAc,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAgCD;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,aAAa;gBACzC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc;CAOtD;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,aAAa;gBAC7C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc;CAOtD;AAED;;;;;GAKG;AACH,qBAAa,2BAA4B,SAAQ,aAAa;gBAChD,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc;CAOtD;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,aAAa;gBACvC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc;CAOtD;AAED;;;;;;GAMG;AACH,qBAAa,uBAAwB,SAAQ,aAAa;gBAC5C,KAAK,EAAE,SAAS,OAAO,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM;CAWvD;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,aAAa;gBAC3C,KAAK,EAAE,OAAO;CAW3B"}

package/dist/errors.js

@@ -0,0 +1,126 @@
+import { FluoCodeError, formatTokenName } from '@fluojs/core';
+
+/**
+ * Structured context attached to DI errors so logs and tests can inspect the failing contract.
+ */
+
+function formatDiContext(ctx) {
+  if (!ctx) return '';
+  const parts = [];
+  if (ctx.token !== undefined) {
+    parts.push(`Token: ${formatTokenName(ctx.token)}`);
+  }
+  if (ctx.scope) {
+    parts.push(`Scope: ${ctx.scope}`);
+  }
+  if (ctx.module) {
+    parts.push(`Module: ${ctx.module}`);
+  }
+  if (ctx.dependencyChain && ctx.dependencyChain.length > 0) {
+    parts.push(`Dependency chain: ${ctx.dependencyChain.map(t => formatTokenName(t)).join(' -> ')}`);
+  }
+  if (ctx.hint) {
+    parts.push(`Hint: ${ctx.hint}`);
+  }
+  if (parts.length === 0) return '';
+  return `\n  ${parts.join('\n  ')}`;
+}
+
+/**
+ * Raised when a provider declaration or inject token cannot be normalized into a valid DI registration.
+ *
+ * @remarks
+ * This usually points to malformed provider objects, missing `@Inject(...)` tokens, or `null`/
+ * `undefined` references that were evaluated before a `forwardRef()` indirection could be applied.
+ */
+export class InvalidProviderError extends FluoCodeError {
+  constructor(message, context) {
+    super(message + formatDiContext(context), 'INVALID_PROVIDER', context ? {
+      meta: buildMeta(context)
+    } : undefined);
+  }
+}
+
+/**
+ * Raised when the container cannot complete a lifecycle operation such as registration, resolution, or disposal.
+ *
+ * @remarks
+ * Use the attached context to inspect the token, module, scope, or dependency chain involved in the failed operation.
+ */
+export class ContainerResolutionError extends FluoCodeError {
+  constructor(message, context) {
+    super(message + formatDiContext(context), 'CONTAINER_RESOLUTION_ERROR', context ? {
+      meta: buildMeta(context)
+    } : undefined);
+  }
+}
+
+/**
+ * Raised when a request-scoped provider is resolved outside a request container.
+ *
+ * @remarks
+ * This protects the documented lifecycle guarantee that request-scoped providers are isolated per child scope.
+ */
+export class RequestScopeResolutionError extends FluoCodeError {
+  constructor(message, context) {
+    super(message + formatDiContext(context), 'REQUEST_SCOPE_RESOLUTION_ERROR', context ? {
+      meta: buildMeta(context)
+    } : undefined);
+  }
+}
+
+/**
+ * Raised when a provider scope is registered or consumed from an incompatible container scope.
+ */
+export class ScopeMismatchError extends FluoCodeError {
+  constructor(message, context) {
+    super(message + formatDiContext(context), 'SCOPE_MISMATCH', context ? {
+      meta: buildMeta(context)
+    } : undefined);
+  }
+}
+
+/**
+ * Raised when the container detects a circular dependency chain while resolving providers.
+ *
+ * @remarks
+ * The formatted message includes the full dependency path plus a first-party hint that points callers toward
+ * extracting shared logic or using `forwardRef()` for intentional cycle deferral.
+ */
+export class CircularDependencyError extends FluoCodeError {
+  constructor(chain, detail) {
+    const path = chain.map(token => formatTokenName(token)).join(' -> ');
+    const hint = 'Break the cycle by extracting shared logic into a separate provider, or use forwardRef() to defer one side of the dependency.';
+    super((detail ? `Circular dependency detected: ${path}. ${detail}` : `Circular dependency detected: ${path}`) + `\n  Dependency chain: ${path}` + `\n  Hint: ${hint}`, 'CIRCULAR_DEPENDENCY', {
+      meta: {
+        chain: chain.map(t => formatTokenName(t)),
+        hint
+      }
+    });
+  }
+}
+
+/**
+ * Raised when the same token is registered twice without going through `container.override(...)`.
+ */
+export class DuplicateProviderError extends FluoCodeError {
+  constructor(token) {
+    const name = formatTokenName(token);
+    const hint = 'Use container.override() for intentional overrides, or check for accidental double-registration in your module providers array.';
+    super(`Token "${name}" is already registered.` + `\n  Token: ${name}` + `\n  Hint: ${hint}`, 'DUPLICATE_PROVIDER', {
+      meta: {
+        token: name,
+        hint
+      }
+    });
+  }
+}
+function buildMeta(context) {
+  const meta = {};
+  if (context.token !== undefined) meta.token = formatTokenName(context.token);
+  if (context.scope) meta.scope = context.scope;
+  if (context.module) meta.module = context.module;
+  if (context.dependencyChain) meta.dependencyChain = context.dependencyChain.map(t => formatTokenName(t));
+  if (context.hint) meta.hint = context.hint;
+  return meta;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './container.js';
+export * from './errors.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './container.js';
+export * from './errors.js';
+export * from './types.js';

package/dist/types.d.ts

@@ -0,0 +1,144 @@
+import type { Constructor, MaybePromise, Token } from '@fluojs/core';
+/**
+ * Lifetime policy understood by the DI container.
+ */
+export type Scope = 'singleton' | 'request' | 'transient';
+/**
+ * Namespace helpers for the public DI scope literals.
+ */
+export declare namespace Scope {
+    /**
+     * Default lifetime used when a provider omits an explicit scope.
+     */
+    const DEFAULT: Scope;
+    /**
+     * Scope literal for providers that should be recreated per request container.
+     */
+    const REQUEST: Scope;
+    /**
+     * Scope literal for providers that should be recreated on every resolution.
+     */
+    const TRANSIENT: Scope;
+}
+/**
+ * Constructable class token used by provider definitions.
+ */
+export type ClassType<T = unknown> = Constructor<T> & Function;
+/**
+ * Provider declaration that instantiates a class for a public token.
+ */
+export interface ClassProvider<T = unknown> {
+    provide: Token<T>;
+    useClass: ClassType<T>;
+    inject?: Array<Token | ForwardRefFn | OptionalToken>;
+    scope?: Scope;
+    multi?: boolean;
+}
+/**
+ * Provider declaration that computes its value through a factory function.
+ */
+export interface FactoryProvider<T = unknown> {
+    provide: Token<T>;
+    useFactory: (...deps: unknown[]) => MaybePromise<T>;
+    inject?: Array<Token | ForwardRefFn | OptionalToken>;
+    scope?: Scope;
+    multi?: boolean;
+    resolverClass?: ClassType;
+}
+/**
+ * Provider declaration that binds a token to an already-created value.
+ */
+export interface ValueProvider<T = unknown> {
+    provide: Token<T>;
+    useValue: T;
+    multi?: boolean;
+}
+/**
+ * Provider declaration that aliases one token to another token's resolved value.
+ */
+export interface ExistingProvider<T = unknown> {
+    provide: Token<T>;
+    useExisting: Token;
+}
+/**
+ * Deferred token resolver used to break declaration-time cycles between providers.
+ */
+export type ForwardRefFn<T = unknown> = {
+    __forwardRef__: true;
+    forwardRef: () => Token<T>;
+};
+/**
+ * Wrapper token that marks a dependency as optional during resolution.
+ */
+export type OptionalToken<T = unknown> = {
+    __optional__: true;
+    token: Token<T>;
+};
+/**
+ * Public provider shape accepted by container registration and override APIs.
+ */
+export type Provider<T = unknown> = ClassType<T> | ClassProvider<T> | FactoryProvider<T> | ValueProvider<T> | ExistingProvider<T>;
+/**
+ * Disposable provider contract recognized by container teardown flows.
+ */
+export interface Disposable {
+    onDestroy(): MaybePromise<void>;
+}
+/**
+ * Minimal request-scope facade exposed to helpers that should not depend on the full `Container` implementation.
+ */
+export interface RequestScopeContainer {
+    resolve<T>(token: Token<T>): Promise<T>;
+    dispose(): Promise<void>;
+}
+/**
+ * Internal normalized provider representation used after the container validates public provider inputs.
+ */
+export interface NormalizedProvider<T = unknown> {
+    inject: Array<Token | ForwardRefFn | OptionalToken>;
+    provide: Token<T>;
+    scope: Scope;
+    type: 'class' | 'factory' | 'value' | 'existing';
+    useClass?: ClassType<T>;
+    useFactory?: (...deps: unknown[]) => MaybePromise<T>;
+    useValue?: T;
+    useExisting?: Token;
+    multi?: boolean;
+}
+/**
+ * Wraps a token factory so DI metadata can defer token lookup until resolution time.
+ *
+ * @param fn Lazy token resolver used when the dependency is eventually resolved.
+ * @returns A marker object understood by container normalization and resolution helpers.
+ *
+ * @example
+ * ```ts
+ * @Inject(forwardRef(() => AuthService))
+ * class UsersService {
+ *   constructor(private readonly auth: AuthService) {}
+ * }
+ * ```
+ */
+export declare function forwardRef<T = unknown>(fn: () => Token<T>): ForwardRefFn<T>;
+/**
+ * Returns whether a value is a `forwardRef(...)` token wrapper.
+ *
+ * @param value Unknown dependency entry being inspected.
+ * @returns `true` when the value was produced by {@link forwardRef}.
+ */
+export declare function isForwardRef(value: unknown): value is ForwardRefFn;
+/**
+ * Marks a dependency token as optional so missing registrations resolve to `undefined` instead of throwing.
+ *
+ * @param token Token that may be absent in the current container hierarchy.
+ * @returns An optional-token wrapper understood by container resolution.
+ */
+export declare function optional<T = unknown>(token: Token<T>): OptionalToken<T>;
+/**
+ * Returns whether a value is an optional-token wrapper created by {@link optional}.
+ *
+ * @param value Unknown dependency entry being inspected.
+ * @returns `true` when the value wraps an optional token.
+ */
+export declare function isOptionalToken(value: unknown): value is OptionalToken;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,98 @@
+/**
+ * Lifetime policy understood by the DI container.
+ */
+/**
+ * Namespace helpers for the public DI scope literals.
+ */
+export let Scope;
+(function (_Scope) {
+  const DEFAULT = _Scope.DEFAULT = 'singleton';
+  const REQUEST = _Scope.REQUEST = 'request';
+  const TRANSIENT = _Scope.TRANSIENT = 'transient';
+})(Scope || (Scope = {}));
+/**
+ * Constructable class token used by provider definitions.
+ */
+/**
+ * Provider declaration that instantiates a class for a public token.
+ */
+/**
+ * Provider declaration that computes its value through a factory function.
+ */
+/**
+ * Provider declaration that binds a token to an already-created value.
+ */
+/**
+ * Provider declaration that aliases one token to another token's resolved value.
+ */
+/**
+ * Deferred token resolver used to break declaration-time cycles between providers.
+ */
+/**
+ * Wrapper token that marks a dependency as optional during resolution.
+ */
+/**
+ * Public provider shape accepted by container registration and override APIs.
+ */
+/**
+ * Disposable provider contract recognized by container teardown flows.
+ */
+/**
+ * Minimal request-scope facade exposed to helpers that should not depend on the full `Container` implementation.
+ */
+/**
+ * Internal normalized provider representation used after the container validates public provider inputs.
+ */
+/**
+ * Wraps a token factory so DI metadata can defer token lookup until resolution time.
+ *
+ * @param fn Lazy token resolver used when the dependency is eventually resolved.
+ * @returns A marker object understood by container normalization and resolution helpers.
+ *
+ * @example
+ * ```ts
+ * @Inject(forwardRef(() => AuthService))
+ * class UsersService {
+ *   constructor(private readonly auth: AuthService) {}
+ * }
+ * ```
+ */
+export function forwardRef(fn) {
+  return {
+    __forwardRef__: true,
+    forwardRef: fn
+  };
+}
+
+/**
+ * Returns whether a value is a `forwardRef(...)` token wrapper.
+ *
+ * @param value Unknown dependency entry being inspected.
+ * @returns `true` when the value was produced by {@link forwardRef}.
+ */
+export function isForwardRef(value) {
+  return typeof value === 'object' && value !== null && '__forwardRef__' in value && value.__forwardRef__ === true;
+}
+
+/**
+ * Marks a dependency token as optional so missing registrations resolve to `undefined` instead of throwing.
+ *
+ * @param token Token that may be absent in the current container hierarchy.
+ * @returns An optional-token wrapper understood by container resolution.
+ */
+export function optional(token) {
+  return {
+    __optional__: true,
+    token
+  };
+}
+
+/**
+ * Returns whether a value is an optional-token wrapper created by {@link optional}.
+ *
+ * @param value Unknown dependency entry being inspected.
+ * @returns `true` when the value wraps an optional token.
+ */
+export function isOptionalToken(value) {
+  return typeof value === 'object' && value !== null && '__optional__' in value && value.__optional__ === true;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@fluojs/di",
+  "description": "Minimal token-based dependency injection container powering every Fluo application.",
+  "keywords": [
+    "fluo",
+    "di",
+    "dependency-injection",
+    "ioc",
+    "container",
+    "provider"
+  ],
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fluojs/fluo.git",
+    "directory": "packages/di"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@fluojs/core": "^1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
+    "build": "pnpm exec babel src --extensions .ts --ignore 'src/**/*.test.ts' --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run -c vitest.config.ts",
+    "test:watch": "pnpm exec vitest -c vitest.config.ts"
+  }
+}