@fluojs/di 2.0.0 → 3.0.0

package/dist/errors.js

@@ -85,12 +85,13 @@ export class ScopeMismatchError extends FluoCodeError {
  *
  * @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.
+ * extracting shared logic, introducing a mediator, or moving the interaction to a later boundary.
+ * `forwardRef()` only defers declaration-time token lookup and cannot resolve a true constructor cycle.
  */
 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.';
+    const hint = 'Break the constructor cycle by extracting shared logic into a separate provider, introducing a mediator, or moving the interaction to a later boundary. forwardRef() only defers declaration-time token lookup and cannot resolve a true constructor cycle.';
     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)),

package/dist/internal.d.ts

@@ -1,3 +1,18 @@
+import type { Token } from '@fluojs/core';
+import { type MultiContributionResolverOwner } from './multi-contribution-registry.js';
+/**
+ * Resolves one ordered multi-provider contribution through its owning container.
+ *
+ * This integration seam is for Fluo packages such as `@fluojs/runtime` and
+ * `@fluojs/testing`; application code must use `Container.resolve(...)`.
+ *
+ * @param container Container that owns the multi-provider registration.
+ * @param token Multi-provider token.
+ * @param contributionIndex Provider-order index for the contribution.
+ * @returns The canonical container-resolved contribution instance.
+ * @throws {ContainerResolutionError} When the container has no registered internal resolver.
+ */
+export declare function resolveMultiContribution(container: MultiContributionResolverOwner, token: Token, contributionIndex: number): Promise<unknown>;
 export { validateProviderInputs } from './provider-normalization.js';
 export type { Provider } from './types.js';
 //# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAG1C,OAAO,EACL,KAAK,8BAA8B,EAEpC,MAAM,kCAAkC,CAAC;AAE1C;;;;;;;;;;;GAWG;AACH,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,8BAA8B,EACzC,KAAK,EAAE,KAAK,EACZ,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,OAAO,CAAC,CAWlB;AAED,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/internal.js

@@ -1 +1,26 @@
+import { ContainerResolutionError } from './errors.js';
+import { multiContributionResolverFor } from './multi-contribution-registry.js';
+
+/**
+ * Resolves one ordered multi-provider contribution through its owning container.
+ *
+ * This integration seam is for Fluo packages such as `@fluojs/runtime` and
+ * `@fluojs/testing`; application code must use `Container.resolve(...)`.
+ *
+ * @param container Container that owns the multi-provider registration.
+ * @param token Multi-provider token.
+ * @param contributionIndex Provider-order index for the contribution.
+ * @returns The canonical container-resolved contribution instance.
+ * @throws {ContainerResolutionError} When the container has no registered internal resolver.
+ */
+export async function resolveMultiContribution(container, token, contributionIndex) {
+  const resolver = multiContributionResolverFor(container);
+  if (!resolver) {
+    throw new ContainerResolutionError('Container does not expose the internal multi-provider contribution resolver.', {
+      token,
+      hint: 'Create the container through the @fluojs/di Container constructor.'
+    });
+  }
+  return resolver(token, contributionIndex);
+}
 export { validateProviderInputs } from './provider-normalization.js';

package/dist/multi-contribution-registry.d.ts

@@ -0,0 +1,26 @@
+import type { Token } from '@fluojs/core';
+type MultiContributionResolver = (token: Token, contributionIndex: number) => Promise<unknown>;
+/**
+ * Object identity that owns a canonical multi-provider contribution resolver.
+ *
+ * @internal
+ */
+export type MultiContributionResolverOwner = object;
+/**
+ * Associates a container with its canonical multi-provider contribution resolver.
+ *
+ * @internal
+ * @param container Container that owns the resolver.
+ * @param resolver Container-bound resolver that preserves DI lifecycle invariants.
+ */
+export declare function registerMultiContributionResolver(container: MultiContributionResolverOwner, resolver: MultiContributionResolver): void;
+/**
+ * Retrieves the canonical multi-provider contribution resolver for a container.
+ *
+ * @internal
+ * @param container Container that owns the resolver.
+ * @returns The container-bound resolver, if the container registered one.
+ */
+export declare function multiContributionResolverFor(container: MultiContributionResolverOwner): MultiContributionResolver | undefined;
+export {};
+//# sourceMappingURL=multi-contribution-registry.d.ts.map

package/dist/multi-contribution-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-contribution-registry.d.ts","sourceRoot":"","sources":["../src/multi-contribution-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,KAAK,yBAAyB,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE/F;;;;GAIG;AACH,MAAM,MAAM,8BAA8B,GAAG,MAAM,CAAC;AAIpD;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAC/C,SAAS,EAAE,8BAA8B,EACzC,QAAQ,EAAE,yBAAyB,GAClC,IAAI,CAEN;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,8BAA8B,GACxC,yBAAyB,GAAG,SAAS,CAEvC"}

package/dist/multi-contribution-registry.js

@@ -0,0 +1,29 @@
+/**
+ * Object identity that owns a canonical multi-provider contribution resolver.
+ *
+ * @internal
+ */
+
+const multiContributionResolvers = new WeakMap();
+
+/**
+ * Associates a container with its canonical multi-provider contribution resolver.
+ *
+ * @internal
+ * @param container Container that owns the resolver.
+ * @param resolver Container-bound resolver that preserves DI lifecycle invariants.
+ */
+export function registerMultiContributionResolver(container, resolver) {
+  multiContributionResolvers.set(container, resolver);
+}
+
+/**
+ * Retrieves the canonical multi-provider contribution resolver for a container.
+ *
+ * @internal
+ * @param container Container that owns the resolver.
+ * @returns The container-bound resolver, if the container registered one.
+ */
+export function multiContributionResolverFor(container) {
+  return multiContributionResolvers.get(container);
+}

package/dist/provider-normalization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-normalization.d.ts","sourceRoot":"","sources":["../src/provider-normalization.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAA2B,kBAAkB,EAAiB,QAAQ,EAAE,MAAM,YAAY,CAAC;AA6JvG;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,kBAAkB,CAiFxE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAMxE"}
+{"version":3,"file":"provider-normalization.d.ts","sourceRoot":"","sources":["../src/provider-normalization.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAA2B,kBAAkB,EAAiB,QAAQ,EAAE,MAAM,YAAY,CAAC;AA6JvG;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,kBAAkB,CAuFxE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAMxE"}

package/dist/provider-normalization.js

@@ -37,8 +37,8 @@ function isScope(value) {
   return value === 'singleton' || value === 'request' || value === 'transient';
 }
 function assertProviderToken(provider) {
-  if (!('provide' in provider) || provider.provide == null) {
-    throw new InvalidProviderError('Provider object must include a non-null provide token.');
+  if (!('provide' in provider) || !isToken(provider.provide)) {
+    throw new InvalidProviderError('Provider object must include a string, symbol, or constructable class provide token.');
   }
 }
 function assertProviderStrategy(provider) {
@@ -138,6 +138,11 @@ export function normalizeProvider(provider) {
   assertObjectProvider(objectProvider);
   const explicitScope = normalizeProviderScope(objectProvider.scope, objectProvider.provide);
   if ('useValue' in objectProvider) {
+    if (Object.hasOwn(objectProvider, 'inject')) {
+      throw new InvalidProviderError('Value providers must not declare inject dependencies.', {
+        token: objectProvider.provide
+      });
+    }
     return freezeNormalizedProvider({
       inject: [],
       multi: objectProvider.multi,
@@ -180,8 +185,8 @@ export function normalizeProvider(provider) {
     });
   }
   if ('useExisting' in objectProvider) {
-    if (objectProvider.useExisting == null) {
-      throw new InvalidProviderError('Alias provider useExisting must be a non-null token.', {
+    if (!isToken(objectProvider.useExisting)) {
+      throw new InvalidProviderError('Alias provider useExisting must be a string, symbol, or constructable class token.', {
         token: objectProvider.provide
       });
     }

package/package.json

@@ -9,7 +9,7 @@
     "container",
     "provider"
   ],
-  "version": "2.0.0",
+  "version": "3.0.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -18,7 +18,7 @@
     "directory": "packages/di"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=24.0.0 <27"
   },
   "publishConfig": {
     "access": "public"
@@ -40,15 +40,15 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.1.0"
+    "@fluojs/core": "^2.0.0"
   },
   "devDependencies": {
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.11"
   },
   "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",
+    "typecheck": "pnpm exec tsc -p tsconfig.typecheck.json --noEmit",
     "test": "pnpm exec vitest run -c vitest.config.ts",
     "test:watch": "pnpm exec vitest -c vitest.config.ts"
   }