@fluojs/testing 1.0.2 → 1.0.4

package/README.ko.md

@@ -79,6 +79,8 @@ const service = await module.resolve(UserService);
 
 Testing builder는 route-pipeline 테스트에서 cross-cutting behavior를 교체할 수 있도록 `overrideGuard(...)`, `overrideInterceptor(...)`, `overrideFilter(...)`도 지원합니다.
 
+`compile()`은 lifecycle hook이 있는 singleton provider에 대해 production module bootstrap과 같은 의미를 따릅니다. effective provider graph를 해석하고, testing module을 반환하기 전에 provider 순서대로 각 instance의 `onModuleInit()`을 실행한 뒤 `onApplicationBootstrap()`을 실행합니다. `get()`은 synchronous singleton 및 multi-provider 경로에서도 DI ownership 의미를 보존하므로, 반복 sync read는 같은 singleton contribution을 재사용하고 `module.container.dispose()`가 해당 instance를 계속 정리할 수 있습니다.
+
 ### `overrideModule()` 사용 시 모듈 identity 보존
 
 `createTestingModule({ rootModule })`에는 명시적인 루트 모듈이 필요합니다. 그래야 테스트가 프로덕션 bootstrap과 같은 모듈 그래프 형태를 컴파일합니다. `overrideModule(source, replacement)`로 import된 모듈을 교체해도, 컴파일된 testing module은 provider 해석에 replacement import를 사용하면서 원래 `rootModule`과 컴파일된 `modules[].type` identity를 보존합니다. 따라서 diagnostics, graph assertion, module introspection 헬퍼는 테스트 전용 synthetic wrapper 클래스가 아니라 사용자가 작성한 애플리케이션 모듈 클래스에 계속 연결됩니다.
@@ -163,12 +165,10 @@ fluo는 테스트가 명시적인 `rootModule`을 이름으로 지정해야 한
 
 ## 공개 API
 
-- **루트 패키지**: `createTestingModule(...)`, `createTestApp(...)`, 모듈 introspection 헬퍼, 공용 테스트 타입
-- **서브패스**: `@fluojs/testing/app`, `@fluojs/testing/module`, `@fluojs/testing/http`, `@fluojs/testing/mock`, `@fluojs/testing/types`, `@fluojs/testing/vitest`
-- **Mock 서브패스**: `@fluojs/testing/mock`
-- **HTTP 헬퍼**: `@fluojs/testing/http`
+- **루트 패키지**: `createTestingModule(...)`, `Test.createTestingModule(...)`, `createTestApp(...)`, 모듈 introspection 헬퍼, 공용 테스트 타입
+- **서브패스**: `@fluojs/testing/app`, `@fluojs/testing/module`, `@fluojs/testing/http`, `@fluojs/testing/mock`, `@fluojs/testing/types`, `@fluojs/testing/vitest`, `@fluojs/testing/vitest/tooling`
 - **하니스 서브패스**: `platform-conformance`, `http-adapter-portability`, `web-runtime-adapter-portability`, `fetch-style-websocket-conformance`
-- **도구 지원**: `@fluojs/testing/vitest`와 `fluoBabelDecoratorsPlugin()` (`vitest`와 `@babel/core`를 함께 요구)
+- **도구 지원**: `@fluojs/testing/vitest`의 `fluoBabelDecoratorsPlugin()` 및 `@fluojs/testing/vitest/tooling`의 Vitest workspace config helper (`vitest`와 `@babel/core`를 함께 요구)
 
 ## 관련 패키지
 

package/README.md

@@ -77,6 +77,8 @@ const service = await module.resolve(UserService);
 
 The testing builder also supports `overrideGuard(...)`, `overrideInterceptor(...)`, and `overrideFilter(...)` for route-pipeline tests that need to replace cross-cutting behavior.
 
+`compile()` follows production module-bootstrap semantics for lifecycle-bearing singleton providers: it resolves the effective provider graph, runs `onModuleInit()` for each resolved instance, then runs `onApplicationBootstrap()` in the same provider order before the testing module is returned. `get()` keeps DI ownership semantics for synchronous singleton and multi-provider paths, so repeated sync reads reuse the same singleton contributions and `module.container.dispose()` can still clean them up.
+
 ### Preserve module identity with `overrideModule()`
 
 `createTestingModule({ rootModule })` requires an explicit root module so tests compile the same module graph shape that production bootstrap uses. When `overrideModule(source, replacement)` swaps imported modules, the compiled testing module preserves the original `rootModule` and compiled `modules[].type` identities while using the replacement imports for provider resolution. This keeps diagnostics, graph assertions, and module-introspection helpers tied to the application module classes you authored instead of synthetic test-only wrapper classes.
@@ -161,12 +163,10 @@ fluo differs from NestJS by requiring tests to name an explicit `rootModule`. Th
 
 ## Public API
 
-- **Root package**: `createTestingModule(...)`, `createTestApp(...)`, module introspection helpers, shared testing types
-- **Subpaths**: `@fluojs/testing/app`, `@fluojs/testing/module`, `@fluojs/testing/http`, `@fluojs/testing/mock`, `@fluojs/testing/types`, `@fluojs/testing/vitest`
-- **Mock subpath**: `@fluojs/testing/mock`
-- **HTTP helpers**: `@fluojs/testing/http`
+- **Root package**: `createTestingModule(...)`, `Test.createTestingModule(...)`, `createTestApp(...)`, module introspection helpers, shared testing types
+- **Subpaths**: `@fluojs/testing/app`, `@fluojs/testing/module`, `@fluojs/testing/http`, `@fluojs/testing/mock`, `@fluojs/testing/types`, `@fluojs/testing/vitest`, `@fluojs/testing/vitest/tooling`
 - **Harness subpaths**: `platform-conformance`, `http-adapter-portability`, `web-runtime-adapter-portability`, `fetch-style-websocket-conformance`
-- **Tooling**: `@fluojs/testing/vitest` with `fluoBabelDecoratorsPlugin()` (requires `vitest` and `@babel/core` in the consuming workspace)
+- **Tooling**: `@fluojs/testing/vitest` with `fluoBabelDecoratorsPlugin()` and `@fluojs/testing/vitest/tooling` with Vitest workspace config helpers (requires `vitest` and `@babel/core` in the consuming workspace)
 
 ## Related Packages
 

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,SAAS,EAId,KAAK,QAAQ,EACd,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAqC,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAMrF,OAAO,KAAK,EAA2B,oBAAoB,EAAE,oBAAoB,EAAoB,MAAM,YAAY,CAAC;AAExH;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,UAAU,GAAG,QAAQ,EAAE,CAQzE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,EAAE,CAQ5E;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,EAAE,CAQzE;AAkkBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,oBAAoB,CAEvF;AAED;;GAEG;AACH,eAAO,MAAM,IAAI;;CAEhB,CAAC"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,SAAS,EAId,KAAK,QAAQ,EAEd,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAqC,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAMrF,OAAO,KAAK,EAA2B,oBAAoB,EAAE,oBAAoB,EAAoB,MAAM,YAAY,CAAC;AAExH;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,UAAU,GAAG,QAAQ,EAAE,CAQzE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,EAAE,CAQ5E;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,EAAE,CAQzE;AAqyBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,oBAAoB,CAEvF;AAED;;GAEG;AACH,eAAO,MAAM,IAAI;;CAEhB,CAAC"}

package/dist/module.js

@@ -1,5 +1,5 @@
 import { getModuleMetadata } from '@fluojs/core';
-import { isForwardRef, isOptionalToken } from '@fluojs/di';
+import { isForwardRef, isOptionalToken, Scope } from '@fluojs/di';
 import { bootstrapModule, defineModule } from '@fluojs/runtime';
 import { createDispatcher, createHandlerMapping } from '@fluojs/http';
 import { createTestRequestContextMiddleware, makeRequest } from './http.js';
@@ -97,7 +97,7 @@ function isContainerIntrospection(value) {
   const candidate = value;
   const parentValid = candidate.parent === undefined || isContainerIntrospection(candidate.parent);
   const requestScopeValid = candidate.requestScopeEnabled === undefined || typeof candidate.requestScopeEnabled === 'boolean';
-  return candidate.registrations instanceof Map && candidate.multiRegistrations instanceof Map && candidate.singletonCache instanceof Map && parentValid && requestScopeValid;
+  return candidate.registrations instanceof Map && candidate.multiRegistrations instanceof Map && candidate.multiSingletonCache instanceof Map && candidate.singletonCache instanceof Map && parentValid && requestScopeValid;
 }
 function toContainerIntrospection(container) {
   if (!isContainerIntrospection(container)) {
@@ -108,6 +108,108 @@ function toContainerIntrospection(container) {
 function isPromiseLike(value) {
   return (typeof value === 'object' || typeof value === 'function') && value !== null && typeof value.then === 'function';
 }
+function hasLifecycleHook(value, hookName) {
+  return (typeof value === 'object' || typeof value === 'function') && value !== null && typeof value[hookName] === 'function';
+}
+function hasAnyBootstrapLifecycleHook(value) {
+  return hasLifecycleHook(value, 'onModuleInit') || hasLifecycleHook(value, 'onApplicationBootstrap');
+}
+function providerToken(provider) {
+  return isProviderDescriptor(provider) ? provider.provide : provider;
+}
+function effectiveProvidersForToken(introspection, token) {
+  const multiProviders = collectMultiProviders(introspection, token);
+  if (multiProviders.length > 0) {
+    return multiProviders;
+  }
+  const provider = lookupProvider(introspection, token);
+  return provider ? [provider] : [];
+}
+function isSingletonLifecycleProvider(provider) {
+  if (provider.scope !== Scope.DEFAULT) {
+    return false;
+  }
+  return provider.type === 'class' || provider.type === 'value' && hasAnyBootstrapLifecycleHook(provider.useValue);
+}
+async function resolveLifecycleDependency(entry, bootstrapped, introspection) {
+  if (isOptionalToken(entry) && !hasTokenInContainer(introspection, entry.token)) {
+    return undefined;
+  }
+  return bootstrapped.container.resolve(dependencyToken(entry));
+}
+async function instantiateLifecycleProvider(provider, bootstrapped, introspection) {
+  if (provider.type !== 'class' || !provider.useClass) {
+    throw new Error(`Lifecycle provider ${String(provider.provide)} must use a class provider.`);
+  }
+  const dependencies = await Promise.all(provider.inject.map(entry => resolveLifecycleDependency(entry, bootstrapped, introspection)));
+  return new provider.useClass(...dependencies);
+}
+async function resolveMultiLifecycleProvider(provider, bootstrapped, introspection) {
+  const cache = rootContainerIntrospection(introspection).multiSingletonCache;
+  const cached = cache.get(provider);
+  if (cached) {
+    return cached;
+  }
+  const instance = instantiateLifecycleProvider(provider, bootstrapped, introspection).catch(error => {
+    cache.delete(provider);
+    throw error;
+  });
+  cache.set(provider, instance);
+  return instance;
+}
+async function resolveTestingLifecycleInstances(bootstrapped, overrides = []) {
+  const lifecycleProviders = [...bootstrapped.effectiveProviders.runtimeProviders, ...bootstrapped.effectiveProviders.moduleProviders, ...overrides];
+  const instances = [];
+  const seenProviders = new Set();
+  const introspection = toContainerIntrospection(bootstrapped.container);
+  for (const provider of lifecycleProviders) {
+    const token = providerToken(provider);
+    const effectiveProviders = effectiveProvidersForToken(introspection, token);
+    for (let index = 0; index < effectiveProviders.length; index += 1) {
+      const effectiveProvider = effectiveProviders[index];
+      if (!effectiveProvider) {
+        continue;
+      }
+      if (seenProviders.has(effectiveProvider)) {
+        continue;
+      }
+      seenProviders.add(effectiveProvider);
+      if (!isSingletonLifecycleProvider(effectiveProvider)) {
+        continue;
+      }
+      if (effectiveProvider.type === 'value') {
+        instances.push(effectiveProvider.useValue);
+        continue;
+      }
+      try {
+        if (effectiveProvider.multi === true) {
+          instances.push(await resolveMultiLifecycleProvider(effectiveProvider, bootstrapped, introspection));
+          continue;
+        }
+        instances.push(await bootstrapped.container.resolve(token));
+      } catch (error) {
+        if (error instanceof Error && error.message.includes('Request-scoped provider')) {
+          continue;
+        }
+        throw error;
+      }
+    }
+  }
+  return instances;
+}
+async function runTestingBootstrapLifecycle(bootstrapped, overrides = []) {
+  const instances = await resolveTestingLifecycleInstances(bootstrapped, overrides);
+  for (const instance of instances) {
+    if (hasLifecycleHook(instance, 'onModuleInit')) {
+      await instance.onModuleInit();
+    }
+  }
+  for (const instance of instances) {
+    if (hasLifecycleHook(instance, 'onApplicationBootstrap')) {
+      await instance.onApplicationBootstrap();
+    }
+  }
+}
 function rootContainerIntrospection(target) {
   return target.parent ? rootContainerIntrospection(target.parent) : target;
 }
@@ -124,7 +226,10 @@ function lookupProvider(target, token) {
   return target.parent ? lookupProvider(target.parent, token) : undefined;
 }
 function hasToken(state, token) {
-  return lookupProvider(state.introspection, token) !== undefined || collectMultiProviders(state.introspection, token).length > 0;
+  return hasTokenInContainer(state.introspection, token);
+}
+function hasTokenInContainer(introspection, token) {
+  return lookupProvider(introspection, token) !== undefined || collectMultiProviders(introspection, token).length > 0;
 }
 function dependencyToken(entry) {
   if (isOptionalToken(entry)) {
@@ -190,6 +295,20 @@ function canPromoteCachedSingleton(state, token) {
   const provider = lookupProvider(state.introspection, token);
   return provider !== undefined && provider.scope !== 'request' && providerGraphIsSyncResolvable(state, token);
 }
+function providerGraphForProviderIsSyncResolvable(state, provider, visited = new Set()) {
+  if (provider.type === 'factory') {
+    return state.factoryResolutionKinds.get(provider) === 'sync';
+  }
+  if (provider.type === 'existing') {
+    return provider.useExisting !== undefined && providerGraphIsSyncResolvable(state, provider.useExisting, visited);
+  }
+  return provider.inject.every(entry => {
+    if (isOptionalToken(entry) && !hasToken(state, entry.token)) {
+      return true;
+    }
+    return providerGraphIsSyncResolvable(state, dependencyToken(entry), visited);
+  });
+}
 function resolveSyncDependency(entry, state) {
   if (isOptionalToken(entry)) {
     if (!hasToken(state, entry.token)) {
@@ -259,6 +378,24 @@ function resolveSyncProvider(provider, state) {
   state.singletonCache.set(provider.provide, Promise.resolve(instance));
   return instance;
 }
+function resolveSyncMultiProvider(provider, state) {
+  if (provider.scope === 'request' && !state.introspection.requestScopeEnabled) {
+    throw new Error(`Request-scoped provider ${String(provider.provide)} cannot be resolved outside request scope.`);
+  }
+  if (provider.scope === 'transient') {
+    return instantiateSyncProvider(provider, state);
+  }
+  if (state.syncMultiSingletonValues.has(provider)) {
+    return state.syncMultiSingletonValues.get(provider);
+  }
+  if (state.multiSingletonCache.has(provider)) {
+    throw new Error(`Token ${String(provider.provide)} was already resolved asynchronously. Use resolve() instead of get() for this provider.`);
+  }
+  const instance = instantiateSyncProvider(provider, state);
+  state.syncMultiSingletonValues.set(provider, instance);
+  state.multiSingletonCache.set(provider, Promise.resolve(instance));
+  return instance;
+}
 function resolveSyncToken(token, state) {
   if (state.resolutionChain.has(token)) {
     throw new Error(`Circular dependency detected while resolving token ${String(token)} via get().`);
@@ -267,7 +404,7 @@ function resolveSyncToken(token, state) {
   try {
     const multiProviders = collectMultiProviders(state.introspection, token);
     if (multiProviders.length > 0) {
-      return multiProviders.map(provider => instantiateSyncProvider(provider, state));
+      return multiProviders.map(provider => resolveSyncMultiProvider(provider, state));
     }
     const provider = lookupProvider(state.introspection, token);
     if (!provider) {
@@ -285,8 +422,10 @@ function createSyncResolver(container) {
   const state = {
     factoryResolutionKinds,
     introspection,
+    multiSingletonCache: rootContainerIntrospection(introspection).multiSingletonCache,
     resolutionChain: new Set(),
     singletonCache: rootContainerIntrospection(introspection).singletonCache,
+    syncMultiSingletonValues: new Map(),
     syncSingletonValues: new Map()
   };
   return {
@@ -298,6 +437,12 @@ function createSyncResolver(container) {
         }
         state.syncSingletonValues.set(token, await promise);
       }
+      for (const [provider, promise] of state.multiSingletonCache) {
+        if (!providerGraphForProviderIsSyncResolvable(state, provider)) {
+          continue;
+        }
+        state.syncMultiSingletonValues.set(provider, await promise);
+      }
     }
   };
 }
@@ -392,7 +537,10 @@ class DefaultTestingModuleBuilder {
   }
   async compile() {
     const bootstrapped = this.bootstrapTestingModule();
-    return this.createTestingModuleRef(bootstrapped);
+    const syncResolver = createSyncResolver(bootstrapped.container);
+    await runTestingBootstrapLifecycle(bootstrapped, this.overrides);
+    await syncResolver.syncFromContainer();
+    return this.createTestingModuleRef(bootstrapped, syncResolver);
   }
   bootstrapTestingModule() {
     const bootstrapped = this.bootstrapWithPatchedModuleImports();
@@ -411,9 +559,8 @@ class DefaultTestingModuleBuilder {
       this.restorePatchedModuleImports();
     }
   }
-  createTestingModuleRef(bootstrapped) {
+  createTestingModuleRef(bootstrapped, syncResolver) {
     const dispatcher = createTestingDispatcher(bootstrapped);
-    const syncResolver = createSyncResolver(bootstrapped.container);
     return {
       ...bootstrapped,
       has: token => bootstrapped.container.has(token),

package/dist/portability/http-adapter-portability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-adapter-portability.d.ts","sourceRoot":"","sources":["../../src/portability/http-adapter-portability.ts"],"names":[],"mappings":"AAIA,OAAO,EAAwC,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE3G,OAAO,QAAQ,cAAc,CAAC;IAC5B,UAAU,gBAAgB;QACxB,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;QACvB,OAAO,CAAC,EAAE,UAAU,CAAC;KACtB;CACF;AAED,KAAK,OAAO,GAAG;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,oCAAoC,CACnD,iBAAiB,SAAS,MAAM,EAChC,WAAW,SAAS,MAAM,EAC1B,IAAI,SAAS,OAAO,GAAG,OAAO;IAE9B;;;;;;OAMG;IACH,SAAS,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjF;;OAEG;IACH,2BAA2B,CAAC,EAAE,MAAM,CAAC;IAErC;;OAEG;IACH,2BAA2B,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElE;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;OAMG;IACH,GAAG,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE;AAuGD;;;;;;;GAOG;AACH,qBAAa,6BAA6B,CACxC,iBAAiB,SAAS,MAAM,EAChC,WAAW,SAAS,MAAM,EAC1B,IAAI,SAAS,OAAO,GAAG,OAAO;IAOlB,OAAO,CAAC,QAAQ,CAAC,OAAO;IALpC;;;;OAIG;gBAC0B,OAAO,EAAE,oCAAoC,CAAC,iBAAiB,EAAE,WAAW,EAAE,IAAI,CAAC;IAEhH;;;OAGG;IACG,oCAAoC,IAAI,OAAO,CAAC,IAAI,CAAC;IAkDrD,oCAAoC,IAAI,OAAO,CAAC,IAAI,CAAC;IAsErD,wDAAwD,IAAI,OAAO,CAAC,IAAI,CAAC;IA+CzE,iCAAiC,IAAI,OAAO,CAAC,IAAI,CAAC;IAuDlD,8CAA8C,IAAI,OAAO,CAAC,IAAI,CAAC;IAsD/D,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC;IAmDjD;;;OAGG;IACG,mCAAmC,IAAI,OAAO,CAAC,IAAI,CAAC;IA0DpD,wCAAwC,IAAI,OAAO,CAAC,IAAI,CAAC;IAqDzD,4BAA4B,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAqDjF,8CAA8C,IAAI,OAAO,CAAC,IAAI,CAAC;CA4CtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mCAAmC,CACjD,iBAAiB,SAAS,MAAM,EAChC,WAAW,SAAS,MAAM,EAC1B,IAAI,SAAS,OAAO,GAAG,OAAO,EAE9B,OAAO,EAAE,oCAAoC,CAAC,iBAAiB,EAAE,WAAW,EAAE,IAAI,CAAC,GAClF,6BAA6B,CAAC,iBAAiB,EAAE,WAAW,EAAE,IAAI,CAAC,CAErE"}
+{"version":3,"file":"http-adapter-portability.d.ts","sourceRoot":"","sources":["../../src/portability/http-adapter-portability.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwC,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE3G,OAAO,QAAQ,cAAc,CAAC;IAC5B,UAAU,gBAAgB;QACxB,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;QACvB,OAAO,CAAC,EAAE,UAAU,CAAC;KACtB;CACF;AAED,KAAK,OAAO,GAAG;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB,CAAC;AAUF;;;;;;GAMG;AACH,MAAM,WAAW,oCAAoC,CACnD,iBAAiB,SAAS,MAAM,EAChC,WAAW,SAAS,MAAM,EAC1B,IAAI,SAAS,OAAO,GAAG,OAAO;IAE9B;;;;;;OAMG;IACH,SAAS,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjF;;OAEG;IACH,2BAA2B,CAAC,EAAE,MAAM,CAAC;IAErC;;OAEG;IACH,2BAA2B,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElE;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;OAMG;IACH,GAAG,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE;AAgHD;;;;;;;GAOG;AACH,qBAAa,6BAA6B,CACxC,iBAAiB,SAAS,MAAM,EAChC,WAAW,SAAS,MAAM,EAC1B,IAAI,SAAS,OAAO,GAAG,OAAO;IAOlB,OAAO,CAAC,QAAQ,CAAC,OAAO;IALpC;;;;OAIG;gBAC0B,OAAO,EAAE,oCAAoC,CAAC,iBAAiB,EAAE,WAAW,EAAE,IAAI,CAAC;IAEhH;;;OAGG;IACG,oCAAoC,IAAI,OAAO,CAAC,IAAI,CAAC;IAiDrD,oCAAoC,IAAI,OAAO,CAAC,IAAI,CAAC;IAqErD,wDAAwD,IAAI,OAAO,CAAC,IAAI,CAAC;IA8CzE,iCAAiC,IAAI,OAAO,CAAC,IAAI,CAAC;IAsDlD,8CAA8C,IAAI,OAAO,CAAC,IAAI,CAAC;IAqD/D,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC;IAkDjD;;;OAGG;IACG,mCAAmC,IAAI,OAAO,CAAC,IAAI,CAAC;IAyDpD,wCAAwC,IAAI,OAAO,CAAC,IAAI,CAAC;IAoDzD,4BAA4B,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAoDjF,8CAA8C,IAAI,OAAO,CAAC,IAAI,CAAC;CA2CtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mCAAmC,CACjD,iBAAiB,SAAS,MAAM,EAChC,WAAW,SAAS,MAAM,EAC1B,IAAI,SAAS,OAAO,GAAG,OAAO,EAE9B,OAAO,EAAE,oCAAoC,CAAC,iBAAiB,EAAE,WAAW,EAAE,IAAI,CAAC,GAClF,6BAA6B,CAAC,iBAAiB,EAAE,WAAW,EAAE,IAAI,CAAC,CAErE"}

package/dist/portability/http-adapter-portability.js

@@ -3,7 +3,6 @@ function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol"
 function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
 function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
 function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
-import { createServer } from 'node:net';
 import { request as httpsRequest } from 'node:https';
 import { Controller, Get, Post, SseResponse } from '@fluojs/http';
 import { defineModule } from '@fluojs/runtime';
@@ -16,25 +15,19 @@ import { defineModule } from '@fluojs/runtime';
  * @template TApp - Type for the application instance.
  */
 
-async function findAvailablePort() {
-  return await new Promise((resolve, reject) => {
-    const server = createServer();
-    server.once('error', reject);
-    server.listen(0, () => {
-      const address = server.address();
-      if (!address || typeof address === 'string') {
-        reject(new Error('Failed to resolve an available port.'));
-        return;
-      }
-      server.close(error => {
-        if (error) {
-          reject(error);
-          return;
-        }
-        resolve(address.port);
-      });
-    });
-  });
+function hasListenTarget(value) {
+  return typeof value === 'object' && value !== null && 'getListenTarget' in value && typeof value.getListenTarget === 'function';
+}
+function resolveListeningUrl(app, adapterName) {
+  const adapter = Reflect.get(app, 'adapter');
+  if (!hasListenTarget(adapter)) {
+    throw new Error(`${adapterName} adapter portability harness cannot resolve the listener URL after binding port 0.`);
+  }
+  const target = adapter.getListenTarget();
+  if (typeof target.url !== 'string' || target.url.length === 0) {
+    throw new Error(`${adapterName} adapter portability harness resolved an empty listener URL after binding port 0.`);
+  }
+  return target.url;
 }
 async function requestHttps(url) {
   return await new Promise((resolve, reject) => {
@@ -78,6 +71,11 @@ async function runWithCleanup(app, adapterName, assertion) {
     throw assertionError;
   }
 }
+async function runWithListeningUrlCleanup(app, adapterName, assertion) {
+  await runWithCleanup(app, adapterName, async () => {
+    await assertion(resolveListeningUrl(app, adapterName));
+  });
+}
 async function prepareAndListenWithCleanup(app, adapterName, prepare) {
   try {
     await prepare?.();
@@ -138,14 +136,13 @@ export class HttpAdapterPortabilityHarness {
     defineModule(AppModule, {
       controllers: [_CookieController]
     });
-    const port = await findAvailablePort();
     const app = await this.options.bootstrap(AppModule, {
       cors: false,
-      port
+      port: 0
     });
     await prepareAndListenWithCleanup(app, this.options.name);
-    await runWithCleanup(app, this.options.name, async () => {
-      const response = await fetch(`http://127.0.0.1:${String(port)}/cookies`, {
+    await runWithListeningUrlCleanup(app, this.options.name, async baseUrl => {
+      const response = await fetch(`${baseUrl}/cookies`, {
         headers: {
           cookie: 'good=hello%20world; bad=%E0%A4%A'
         }
@@ -192,15 +189,14 @@ export class HttpAdapterPortabilityHarness {
     defineModule(AppModule, {
       controllers: [_WebhookController]
     });
-    const port = await findAvailablePort();
     const app = await this.options.bootstrap(AppModule, {
       cors: false,
-      port,
+      port: 0,
       rawBody: true
     });
     await prepareAndListenWithCleanup(app, this.options.name);
-    await runWithCleanup(app, this.options.name, async () => {
-      const [jsonResponse, textResponse] = await Promise.all([fetch(`http://127.0.0.1:${String(port)}/webhooks/json`, {
+    await runWithListeningUrlCleanup(app, this.options.name, async baseUrl => {
+      const [jsonResponse, textResponse] = await Promise.all([fetch(`${baseUrl}/webhooks/json`, {
         body: JSON.stringify({
           provider: 'stripe'
         }),
@@ -208,7 +204,7 @@ export class HttpAdapterPortabilityHarness {
           'content-type': 'application/json'
         },
         method: 'POST'
-      }), fetch(`http://127.0.0.1:${String(port)}/webhooks/text`, {
+      }), fetch(`${baseUrl}/webhooks/text`, {
         body: 'ping=1',
         headers: {
           'content-type': 'text/plain; charset=utf-8'
@@ -261,19 +257,18 @@ export class HttpAdapterPortabilityHarness {
     defineModule(AppModule, {
       controllers: [_WebhookController2]
     });
-    const port = await findAvailablePort();
     const app = await this.options.bootstrap(AppModule, {
       cors: false,
-      port,
+      port: 0,
       rawBody: true
     });
     await prepareAndListenWithCleanup(app, this.options.name, async () => {
       await this.options.prepareExactRawBodyByteTest?.(app);
     });
-    await runWithCleanup(app, this.options.name, async () => {
+    await runWithListeningUrlCleanup(app, this.options.name, async baseUrl => {
       const payload = Uint8Array.from([0xe9, 0x41]);
       const contentType = this.options.exactRawBodyByteContentType ?? 'text/plain; charset=latin1';
-      const response = await fetch(`http://127.0.0.1:${String(port)}/webhooks/bytes`, {
+      const response = await fetch(`${baseUrl}/webhooks/bytes`, {
         body: payload,
         headers: {
           'content-type': contentType
@@ -319,20 +314,19 @@ export class HttpAdapterPortabilityHarness {
     defineModule(AppModule, {
       controllers: [_UploadController]
     });
-    const port = await findAvailablePort();
     const app = await this.options.bootstrap(AppModule, {
       cors: false,
-      port,
+      port: 0,
       rawBody: true
     });
     await prepareAndListenWithCleanup(app, this.options.name);
-    await runWithCleanup(app, this.options.name, async () => {
+    await runWithListeningUrlCleanup(app, this.options.name, async baseUrl => {
       const form = new FormData();
       form.set('name', 'Ada');
       form.set('payload', new Blob(['hello'], {
         type: 'text/plain'
       }), 'payload.txt');
-      const response = await fetch(`http://127.0.0.1:${String(port)}/uploads`, {
+      const response = await fetch(`${baseUrl}/uploads`, {
         body: form,
         method: 'POST'
       });
@@ -378,23 +372,22 @@ export class HttpAdapterPortabilityHarness {
     defineModule(AppModule, {
       controllers: [_UploadController2]
     });
-    const port = await findAvailablePort();
     const app = await this.options.bootstrap(AppModule, {
       cors: false,
       maxBodySize: 8,
       multipart: {
         maxFileSize: 1024
       },
-      port
+      port: 0
     });
     await prepareAndListenWithCleanup(app, this.options.name);
-    await runWithCleanup(app, this.options.name, async () => {
+    await runWithListeningUrlCleanup(app, this.options.name, async baseUrl => {
       const form = new FormData();
       form.set('name', 'Ada');
       form.set('payload', new Blob(['12345678'], {
         type: 'text/plain'
       }), 'payload.txt');
-      const response = await fetch(`http://127.0.0.1:${String(port)}/uploads`, {
+      const response = await fetch(`${baseUrl}/uploads`, {
         body: form,
         method: 'POST'
       });
@@ -442,14 +435,13 @@ export class HttpAdapterPortabilityHarness {
     defineModule(AppModule, {
       controllers: [_EventsController]
     });
-    const port = await findAvailablePort();
     const app = await this.options.bootstrap(AppModule, {
       cors: false,
-      port
+      port: 0
     });
     await prepareAndListenWithCleanup(app, this.options.name);
-    await runWithCleanup(app, this.options.name, async () => {
-      const response = await fetch(`http://127.0.0.1:${String(port)}/events`, {
+    await runWithListeningUrlCleanup(app, this.options.name, async baseUrl => {
+      const response = await fetch(`${baseUrl}/events`, {
         headers: {
           accept: 'text/event-stream'
         }
@@ -510,14 +502,13 @@ export class HttpAdapterPortabilityHarness {
     defineModule(AppModule, {
       controllers: [_EventsController2]
     });
-    const port = await findAvailablePort();
     const app = await this.options.bootstrap(AppModule, {
       cors: false,
-      port
+      port: 0
     });
     await prepareAndListenWithCleanup(app, this.options.name);
-    await runWithCleanup(app, this.options.name, async () => {
-      const response = await fetch(`http://127.0.0.1:${String(port)}/events`, {
+    await runWithListeningUrlCleanup(app, this.options.name, async baseUrl => {
+      const response = await fetch(`${baseUrl}/events`, {
         headers: {
           accept: 'text/event-stream'
         }
@@ -566,15 +557,14 @@ export class HttpAdapterPortabilityHarness {
     defineModule(AppModule, {
       controllers: [_HealthController]
     });
-    const port = await findAvailablePort();
     const app = await this.options.run(AppModule, {
       cors: false,
       host: '127.0.0.1',
       logger,
-      port
+      port: 0
     });
-    await runWithCleanup(app, this.options.name, async () => {
-      const response = await fetch(`http://127.0.0.1:${String(port)}/health`);
+    await runWithListeningUrlCleanup(app, this.options.name, async baseUrl => {
+      const response = await fetch(`${baseUrl}/health`);
       if (response.status !== 200) {
         throw new Error(`${this.options.name} adapter changed host-bound health response semantics.`);
       }
@@ -584,7 +574,7 @@ export class HttpAdapterPortabilityHarness {
       })) {
         throw new Error(`${this.options.name} adapter changed host-bound response payload.`);
       }
-      const expectedLog = `log:FluoFactory:Listening on http://127.0.0.1:${String(port)}`;
+      const expectedLog = `log:FluoFactory:Listening on ${baseUrl}`;
       if (!loggerEvents.includes(expectedLog)) {
         throw new Error(`${this.options.name} adapter changed startup host logging.`);
       }
@@ -627,16 +617,15 @@ export class HttpAdapterPortabilityHarness {
     defineModule(AppModule, {
       controllers: [_HealthController2]
     });
-    const port = await findAvailablePort();
     const app = await this.options.run(AppModule, {
       cors: false,
       host: '127.0.0.1',
       https,
       logger,
-      port
+      port: 0
     });
-    await runWithCleanup(app, this.options.name, async () => {
-      const response = await requestHttps(`https://127.0.0.1:${String(port)}/health`);
+    await runWithListeningUrlCleanup(app, this.options.name, async baseUrl => {
+      const response = await requestHttps(`${baseUrl}/health`);
       if (response.statusCode !== 200) {
         throw new Error(`${this.options.name} adapter changed HTTPS response status semantics.`);
       }
@@ -645,7 +634,7 @@ export class HttpAdapterPortabilityHarness {
       })) {
         throw new Error(`${this.options.name} adapter changed HTTPS response payload semantics.`);
       }
-      const expectedLog = `log:FluoFactory:Listening on https://127.0.0.1:${String(port)}`;
+      const expectedLog = `log:FluoFactory:Listening on ${baseUrl}`;
       if (!loggerEvents.includes(expectedLog)) {
         throw new Error(`${this.options.name} adapter changed HTTPS startup logging.`);
       }
@@ -685,11 +674,10 @@ export class HttpAdapterPortabilityHarness {
     });
     const signal = 'SIGTERM';
     const listenersBefore = new Set(process.listeners(signal));
-    const port = await findAvailablePort();
     const app = await this.options.run(AppModule, {
       cors: false,
       logger,
-      port,
+      port: 0,
       shutdownSignals: [signal]
     });
     const registeredListeners = process.listeners(signal).filter(listener => !listenersBefore.has(listener));

package/dist/vitest/tooling.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Collects source-file aliases for a fluo monorepo checkout.
+ *
+ * @param repoRootUrl - Repository root as a file URL or absolute path URL string.
+ * @returns A Vite/Vitest alias map that points public package imports at workspace source files.
+ */
+export declare function collectWorkspaceAliases(repoRootUrl: string | URL): Record<string, string>;
+/**
+ * Creates the shared Vitest configuration used by fluo workspace packages.
+ *
+ * @param repoRootUrl - Repository root as a file URL or absolute path URL string.
+ * @param overrides - Optional Vitest config overrides merged after the fluo defaults.
+ * @returns A Vitest configuration with fluo decorator transforms and workspace aliases.
+ */
+export declare function createFluoVitestWorkspaceConfig(repoRootUrl: string | URL, overrides?: {}): Record<string, any>;
+/**
+ * Defines a Vitest config rooted at the current fluo repository checkout.
+ *
+ * @returns A Vitest configuration for repository-local package tests.
+ */
+export declare function defineFluoVitestConfig(): Record<string, any>;
+//# sourceMappingURL=tooling.d.ts.map

package/dist/vitest/tooling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooling.d.ts","sourceRoot":"","sources":["../../src/vitest/tooling.ts"],"names":[],"mappings":"AA4EA;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEzF;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,EAAE,SAAS,KAAK,uBAaxF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,wBAErC"}

package/dist/vitest/tooling.js

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { extname, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defineConfig, mergeConfig } from 'vitest/config';
+import { fluoBabelDecoratorsPlugin } from '../vitest.js';
+function collectSourceEntries(sourceRoot) {
+  const entries = [];
+  for (const directoryEntry of readdirSync(sourceRoot, {
+    withFileTypes: true
+  })) {
+    const entryPath = join(sourceRoot, directoryEntry.name);
+    if (directoryEntry.isDirectory()) {
+      entries.push(...collectSourceEntries(entryPath));
+      continue;
+    }
+    if (directoryEntry.isFile()) {
+      entries.push(entryPath);
+    }
+  }
+  return entries;
+}
+function collectWorkspaceAliasesFromRoot(repoRoot) {
+  const packagesRoot = join(repoRoot, 'packages');
+  const aliases = {};
+  for (const packageDirectoryName of readdirSync(packagesRoot)) {
+    const packageRoot = join(packagesRoot, packageDirectoryName);
+    const sourceRoot = join(packageRoot, 'src');
+    const manifestPath = join(packageRoot, 'package.json');
+    if (!existsSync(sourceRoot) || !existsSync(manifestPath)) {
+      continue;
+    }
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    const scopeName = manifest.name ?? `@fluojs/${packageDirectoryName}`;
+    for (const sourceEntryPath of collectSourceEntries(sourceRoot)) {
+      const relativeSourceEntry = relative(sourceRoot, sourceEntryPath);
+      if (extname(sourceEntryPath) !== '.ts' || relativeSourceEntry.endsWith('.test.ts') || relativeSourceEntry === 'index.ts') {
+        continue;
+      }
+      const subpath = relativeSourceEntry.slice(0, -3).split(sep).join('/');
+      aliases[`${scopeName}/${subpath}`] = sourceEntryPath;
+    }
+    const indexPath = join(sourceRoot, 'index.ts');
+    if (existsSync(indexPath)) {
+      aliases[scopeName] = indexPath;
+    }
+  }
+  return {
+    '@fluojs/runtime/internal/http-adapter': join(packagesRoot, 'runtime', 'src', 'internal-http-adapter.ts'),
+    '@fluojs/runtime/internal/request-response-factory': join(packagesRoot, 'runtime', 'src', 'internal-request-response-factory.ts'),
+    ...aliases
+  };
+}
+
+/**
+ * Collects source-file aliases for a fluo monorepo checkout.
+ *
+ * @param repoRootUrl - Repository root as a file URL or absolute path URL string.
+ * @returns A Vite/Vitest alias map that points public package imports at workspace source files.
+ */
+export function collectWorkspaceAliases(repoRootUrl) {
+  return collectWorkspaceAliasesFromRoot(fileURLToPath(repoRootUrl));
+}
+
+/**
+ * Creates the shared Vitest configuration used by fluo workspace packages.
+ *
+ * @param repoRootUrl - Repository root as a file URL or absolute path URL string.
+ * @param overrides - Optional Vitest config overrides merged after the fluo defaults.
+ * @returns A Vitest configuration with fluo decorator transforms and workspace aliases.
+ */
+export function createFluoVitestWorkspaceConfig(repoRootUrl, overrides = {}) {
+  return mergeConfig(defineConfig({
+    plugins: [fluoBabelDecoratorsPlugin()],
+    resolve: {
+      alias: collectWorkspaceAliases(repoRootUrl)
+    },
+    test: {
+      environment: 'node'
+    }
+  }), defineConfig(overrides));
+}
+
+/**
+ * Defines a Vitest config rooted at the current fluo repository checkout.
+ *
+ * @returns A Vitest configuration for repository-local package tests.
+ */
+export function defineFluoVitestConfig() {
+  return createFluoVitestWorkspaceConfig(new URL('../../../../', import.meta.url));
+}

package/package.json

@@ -9,7 +9,7 @@
     "override",
     "module-builder"
   ],
-  "version": "1.0.2",
+  "version": "1.0.4",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -68,6 +68,10 @@
     "./vitest": {
       "types": "./dist/vitest.d.ts",
       "import": "./dist/vitest.js"
+    },
+    "./vitest/tooling": {
+      "types": "./dist/vitest/tooling.d.ts",
+      "import": "./dist/vitest/tooling.js"
     }
   },
   "main": "./dist/index.js",
@@ -77,10 +81,10 @@
   ],
   "dependencies": {
     "@fluojs/config": "^1.0.2",
-    "@fluojs/core": "^1.0.2",
-    "@fluojs/http": "^1.0.0",
-    "@fluojs/di": "^1.0.2",
-    "@fluojs/runtime": "^1.1.0"
+    "@fluojs/core": "^1.0.3",
+    "@fluojs/http": "^1.1.0",
+    "@fluojs/di": "^1.0.3",
+    "@fluojs/runtime": "^1.1.2"
   },
   "peerDependencies": {
     "@babel/core": ">=7.0.0",
@@ -88,12 +92,12 @@
   },
   "devDependencies": {
     "vitest": "^3.2.4",
-    "@fluojs/platform-bun": "^1.0.2",
-    "@fluojs/platform-cloudflare-workers": "^1.0.2",
-    "@fluojs/platform-deno": "^1.0.2",
-    "@fluojs/platform-nodejs": "^1.0.2",
-    "@fluojs/platform-express": "^1.0.2",
-    "@fluojs/platform-fastify": "^1.0.2"
+    "@fluojs/platform-bun": "^1.0.3",
+    "@fluojs/platform-cloudflare-workers": "^1.0.3",
+    "@fluojs/platform-deno": "^1.0.4",
+    "@fluojs/platform-nodejs": "^1.0.3",
+    "@fluojs/platform-express": "^1.0.3",
+    "@fluojs/platform-fastify": "^1.0.4"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",