@fluojs/testing 1.0.0-beta.1

package/dist/module.js

@@ -0,0 +1,405 @@
+import { getModuleMetadata } from '@fluojs/core/internal';
+import { isForwardRef, isOptionalToken } from '@fluojs/di';
+import { bootstrapModule, defineModule } from '@fluojs/runtime';
+import { createDispatcher, createHandlerMapping } from '@fluojs/http';
+import { createTestRequestContextMiddleware, makeRequest } from './http.js';
+/**
+ * Returns providers declared on a module metadata definition.
+ *
+ * @param moduleType Module type whose `providers` metadata should be inspected.
+ * @returns The declared provider list, or an empty array when the module has none.
+ */
+export function extractModuleProviders(moduleType) {
+  const metadata = getModuleMetadata(moduleType);
+  if (!metadata || !Array.isArray(metadata.providers)) {
+    return [];
+  }
+  return metadata.providers;
+}
+
+/**
+ * Returns controllers declared on a module metadata definition.
+ *
+ * @param moduleType Module type whose `controllers` metadata should be inspected.
+ * @returns The declared controller list, or an empty array when the module has none.
+ */
+export function extractModuleControllers(moduleType) {
+  const metadata = getModuleMetadata(moduleType);
+  if (!metadata || !Array.isArray(metadata.controllers)) {
+    return [];
+  }
+  return metadata.controllers;
+}
+
+/**
+ * Returns imported modules declared on a module metadata definition.
+ *
+ * @param moduleType Module type whose `imports` metadata should be inspected.
+ * @returns The declared import list, or an empty array when the module has none.
+ */
+export function extractModuleImports(moduleType) {
+  const metadata = getModuleMetadata(moduleType);
+  if (!metadata || !Array.isArray(metadata.imports)) {
+    return [];
+  }
+  return metadata.imports;
+}
+function createHandlerSources(bootstrappedModules) {
+  return bootstrappedModules.flatMap(compiledModule => (compiledModule.definition.controllers ?? []).map(controllerToken => ({
+    controllerToken,
+    moduleMiddleware: compiledModule.definition.middleware ?? [],
+    moduleType: compiledModule.type
+  })));
+}
+function createTestingDispatcher(bootstrapped) {
+  const handlerMapping = createHandlerMapping(createHandlerSources(bootstrapped.modules));
+  return createDispatcher({
+    appMiddleware: [createTestRequestContextMiddleware()],
+    handlerMapping,
+    rootContainer: bootstrapped.container
+  });
+}
+function isProviderDescriptor(value) {
+  return typeof value === 'object' && value !== null && 'provide' in value && ('useClass' in value || 'useFactory' in value || 'useValue' in value || 'useExisting' in value);
+}
+function isClassConstructor(value) {
+  if (typeof value !== 'function') {
+    return false;
+  }
+  const source = Function.prototype.toString.call(value);
+  return source.startsWith('class ');
+}
+function normalizeOverride(token, value) {
+  if (isProviderDescriptor(value)) {
+    if (value.provide !== token) {
+      throw new Error(`overrideProvider token mismatch: expected ${String(token)} but received provider for ${String(value.provide)}.`);
+    }
+    return {
+      ...value,
+      provide: token
+    };
+  }
+  if (isClassConstructor(value)) {
+    return {
+      provide: token,
+      useClass: value
+    };
+  }
+  return {
+    provide: token,
+    useValue: value
+  };
+}
+function isContainerIntrospection(value) {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  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 && parentValid && requestScopeValid;
+}
+function toContainerIntrospection(container) {
+  if (!isContainerIntrospection(container)) {
+    throw new Error('Testing container introspection is unavailable for the current container implementation.');
+  }
+  return container;
+}
+function isPromiseLike(value) {
+  return (typeof value === 'object' || typeof value === 'function') && value !== null && typeof value.then === 'function';
+}
+function collectMultiProviders(target, token) {
+  const fromParent = target.parent ? collectMultiProviders(target.parent, token) : [];
+  const local = target.multiRegistrations.get(token) ?? [];
+  return [...fromParent, ...local];
+}
+function lookupProvider(target, token) {
+  const local = target.registrations.get(token);
+  if (local) {
+    return local;
+  }
+  return target.parent ? lookupProvider(target.parent, token) : undefined;
+}
+function hasToken(state, token) {
+  return lookupProvider(state.introspection, token) !== undefined || collectMultiProviders(state.introspection, token).length > 0;
+}
+function resolveSyncDependency(entry, state) {
+  if (isOptionalToken(entry)) {
+    if (!hasToken(state, entry.token)) {
+      return undefined;
+    }
+    return resolveSyncToken(entry.token, state);
+  }
+  if (isForwardRef(entry)) {
+    return resolveSyncToken(entry.forwardRef(), state);
+  }
+  return resolveSyncToken(entry, state);
+}
+function instantiateSyncProvider(provider, state) {
+  switch (provider.type) {
+    case 'value':
+      {
+        return provider.useValue;
+      }
+    case 'existing':
+      {
+        if (!provider.useExisting) {
+          throw new Error('Existing provider is missing useExisting token.');
+        }
+        return resolveSyncToken(provider.useExisting, state);
+      }
+    case 'factory':
+      {
+        if (!provider.useFactory) {
+          throw new Error('Factory provider is missing useFactory.');
+        }
+        const deps = provider.inject.map(entry => resolveSyncDependency(entry, state));
+        const value = provider.useFactory(...deps);
+        if (isPromiseLike(value)) {
+          throw new Error(`Token ${String(provider.provide)} requires async resolution. Use resolve() instead of get() for async providers.`);
+        }
+        return value;
+      }
+    case 'class':
+      {
+        if (!provider.useClass) {
+          throw new Error('Class provider is missing useClass.');
+        }
+        const deps = provider.inject.map(entry => resolveSyncDependency(entry, state));
+        return new provider.useClass(...deps);
+      }
+    default:
+      {
+        throw new Error('Unknown provider type.');
+      }
+  }
+}
+function resolveSyncProvider(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.singletonCache.has(provider.provide)) {
+    return state.singletonCache.get(provider.provide);
+  }
+  const instance = instantiateSyncProvider(provider, state);
+  state.singletonCache.set(provider.provide, 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().`);
+  }
+  state.resolutionChain.add(token);
+  try {
+    const multiProviders = collectMultiProviders(state.introspection, token);
+    if (multiProviders.length > 0) {
+      return multiProviders.map(provider => instantiateSyncProvider(provider, state));
+    }
+    const provider = lookupProvider(state.introspection, token);
+    if (!provider) {
+      throw new Error(`No provider registered for token ${String(token)}.`);
+    }
+    return resolveSyncProvider(provider, state);
+  } finally {
+    state.resolutionChain.delete(token);
+  }
+}
+function createSyncResolver(container) {
+  const state = {
+    introspection: toContainerIntrospection(container),
+    resolutionChain: new Set(),
+    singletonCache: new Map()
+  };
+  return token => resolveSyncToken(token, state);
+}
+class DefaultOverrideProviderBuilder {
+  constructor(builder, token) {
+    this.builder = builder;
+    this.token = token;
+  }
+  useValue(value) {
+    this.builder.addOverride(normalizeOverride(this.token, value));
+    return this.builder;
+  }
+  useClass(cls) {
+    this.builder.addOverride({
+      provide: this.token,
+      useClass: cls
+    });
+    return this.builder;
+  }
+  useFactory(factory, inject) {
+    this.builder.addOverride({
+      provide: this.token,
+      useFactory: factory,
+      inject
+    });
+    return this.builder;
+  }
+  useExisting(token) {
+    this.builder.addOverride({
+      provide: this.token,
+      useExisting: token
+    });
+    return this.builder;
+  }
+}
+class DefaultTestingModuleBuilder {
+  overrides = [];
+  moduleReplacements = new Map();
+  constructor(options) {
+    this.options = options;
+  }
+  addOverride(provider) {
+    this.overrides.push(provider);
+  }
+  overrideProvider(token, ...rest) {
+    if (rest.length < 1) {
+      return new DefaultOverrideProviderBuilder(this, token);
+    }
+    const [value] = rest;
+    this.overrides.push(normalizeOverride(token, value));
+    return this;
+  }
+  overrideProviders(overrides) {
+    for (const [token, value] of overrides) {
+      this.overrideProvider(token, value);
+    }
+    return this;
+  }
+  overrideGuard(guard, fake = {}) {
+    const passthrough = {
+      canActivate: () => true,
+      ...fake
+    };
+    this.overrides.push({
+      provide: guard,
+      useValue: passthrough
+    });
+    return this;
+  }
+  overrideInterceptor(interceptor, fake = {}) {
+    const passthrough = {
+      intercept: (_ctx, next) => next.handle(),
+      ...fake
+    };
+    this.overrides.push({
+      provide: interceptor,
+      useValue: passthrough
+    });
+    return this;
+  }
+  overrideFilter(filter, fake = {}) {
+    this.overrides.push({
+      provide: filter,
+      useValue: fake
+    });
+    return this;
+  }
+  overrideModule(module, replacement) {
+    this.moduleReplacements.set(module, replacement);
+    return this;
+  }
+  async compile() {
+    const bootstrapped = this.bootstrapTestingModule();
+    return this.createTestingModuleRef(bootstrapped);
+  }
+  bootstrapTestingModule() {
+    const rootModule = this._applyModuleReplacements(this.options.rootModule);
+    const bootstrapped = bootstrapModule(rootModule, {
+      providers: this.options.providers
+    });
+    if (this.overrides.length > 0) {
+      bootstrapped.container.override(...this.overrides);
+    }
+    return bootstrapped;
+  }
+  createTestingModuleRef(bootstrapped) {
+    const dispatcher = createTestingDispatcher(bootstrapped);
+    const getSync = createSyncResolver(bootstrapped.container);
+    return {
+      ...bootstrapped,
+      has: token => bootstrapped.container.has(token),
+      get: token => getSync(token),
+      resolve: token => bootstrapped.container.resolve(token),
+      resolveAll: async tokens => {
+        const results = [];
+        const errors = [];
+        for (const token of tokens) {
+          try {
+            results.push(await bootstrapped.container.resolve(token));
+          } catch (error) {
+            errors.push({
+              token,
+              error
+            });
+          }
+        }
+        if (errors.length > 0) {
+          const summary = errors.map(({
+            token,
+            error
+          }) => `  - ${String(token)}: ${error instanceof Error ? error.message : String(error)}`).join('\n');
+          throw new Error(`Failed to resolve ${errors.length} of ${tokens.length} tokens:\n${summary}`);
+        }
+        return results;
+      },
+      dispatch: request => makeRequest(dispatcher, request)
+    };
+  }
+  _applyModuleReplacements(module) {
+    if (this.moduleReplacements.size === 0) {
+      return module;
+    }
+    const replacement = this.moduleReplacements.get(module);
+    if (replacement) {
+      return replacement;
+    }
+    const metadata = getModuleMetadata(module);
+    if (!metadata?.imports || metadata.imports.length === 0) {
+      return module;
+    }
+    const rewrittenImports = this.rewriteModuleImports(metadata.imports);
+    const hasChange = rewrittenImports.some((imp, i) => imp !== metadata.imports[i]);
+    if (!hasChange) {
+      return module;
+    }
+    class PatchedModule {}
+    const patchedModule = PatchedModule;
+    defineModule(patchedModule, {
+      ...metadata,
+      imports: rewrittenImports
+    });
+    return patchedModule;
+  }
+  rewriteModuleImports(imports) {
+    return imports.map(moduleImport => this._applyModuleReplacements(moduleImport));
+  }
+}
+
+/**
+ * Creates a fluent testing-module builder for overriding providers and compiling a test graph.
+ *
+ * @param options Bootstrap options plus the root module that should be compiled for the test.
+ * @returns A builder that supports provider and module overrides before compilation.
+ *
+ * @example
+ * ```ts
+ * const module = await createTestingModule({ rootModule: AppModule })
+ *   .overrideProvider(USER_REPOSITORY, fakeUserRepository)
+ *   .compile();
+ * ```
+ */
+export function createTestingModule(options) {
+  return new DefaultTestingModuleBuilder(options);
+}
+
+/**
+ * Namespace-style access point for `createTestingModule(...)`.
+ */
+export const Test = {
+  createTestingModule
+};

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

@@ -0,0 +1,83 @@
+import { type ModuleType, type UploadedFile } from '@fluojs/runtime';
+declare module '@fluojs/http' {
+    interface FrameworkRequest {
+        files?: UploadedFile[];
+        rawBody?: Uint8Array;
+    }
+}
+type AppLike = {
+    close(): Promise<void>;
+    listen(): Promise<void>;
+};
+/**
+ * Options for configuring the HTTP adapter portability harness.
+ *
+ * @template TBootstrapOptions - Type for bootstrap-specific options.
+ * @template TRunOptions - Type for run-specific options.
+ * @template TApp - Type for the application instance.
+ */
+export interface HttpAdapterPortabilityHarnessOptions<TBootstrapOptions extends object, TRunOptions extends object, TApp extends AppLike = AppLike> {
+    /**
+     * Function to bootstrap the application with the given root module and options.
+     *
+     * @param rootModule - The root module of the application.
+     * @param options - The bootstrap options.
+     * @returns A promise that resolves to the application instance.
+     */
+    bootstrap: (rootModule: ModuleType, options: TBootstrapOptions) => Promise<TApp>;
+    /**
+     * The name of the adapter being tested.
+     */
+    name: string;
+    /**
+     * Function to run the application with the given root module and options.
+     *
+     * @param rootModule - The root module of the application.
+     * @param options - The run options.
+     * @returns A promise that resolves to the application instance.
+     */
+    run: (rootModule: ModuleType, options: TRunOptions) => Promise<TApp>;
+}
+/**
+ * A portability harness for testing HTTP adapters to ensure they behave
+ * consistently across different environments.
+ *
+ * @template TBootstrapOptions - Type for bootstrap-specific options.
+ * @template TRunOptions - Type for run-specific options.
+ * @template TApp - Type for the application instance.
+ */
+export declare class HttpAdapterPortabilityHarness<TBootstrapOptions extends object, TRunOptions extends object, TApp extends AppLike = AppLike> {
+    private readonly options;
+    /**
+     * Creates a new instance of the {@link HttpAdapterPortabilityHarness}.
+     *
+     * @param options - Configuration options for the harness.
+     */
+    constructor(options: HttpAdapterPortabilityHarnessOptions<TBootstrapOptions, TRunOptions, TApp>);
+    /**
+     * Asserts that the adapter preserves malformed cookie values without crashing
+     * or incorrectly normalizing them.
+     */
+    assertPreservesMalformedCookieValues(): Promise<void>;
+    assertPreservesRawBodyForJsonAndText(): Promise<void>;
+    assertExcludesRawBodyForMultipart(): Promise<void>;
+    assertSupportsSseStreaming(): Promise<void>;
+    assertReportsConfiguredHostInStartupLogs(): Promise<void>;
+    assertReportsHttpsStartupUrl(https: {
+        cert: string;
+        key: string;
+    }): Promise<void>;
+    assertRemovesShutdownSignalListenersAfterClose(): Promise<void>;
+}
+/**
+ * Creates a new {@link HttpAdapterPortabilityHarness} instance with the provided options.
+ *
+ * @template TBootstrapOptions - Type for bootstrap-specific options.
+ * @template TRunOptions - Type for run-specific options.
+ * @template TApp - Type for the application instance.
+ * @param options - Configuration options for the harness.
+ * @returns A new portability harness instance.
+ */
+export declare function createHttpAdapterPortabilityHarness<TBootstrapOptions extends object, TRunOptions extends object, TApp extends AppLike = AppLike>(options: HttpAdapterPortabilityHarnessOptions<TBootstrapOptions, TRunOptions, TApp>): HttpAdapterPortabilityHarness<TBootstrapOptions, TRunOptions, TApp>;
+export {};
+//# sourceMappingURL=http-adapter-portability.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http-adapter-portability.d.ts","sourceRoot":"","sources":["../../src/portability/http-adapter-portability.ts"],"names":[],"mappings":"AAUA,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAC;AAEzB,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,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;OAMG;IACH,GAAG,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE;AAuDD;;;;;;;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;IA+CrD,oCAAoC,IAAI,OAAO,CAAC,IAAI,CAAC;IA8DrD,iCAAiC,IAAI,OAAO,CAAC,IAAI,CAAC;IA8ClD,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC;IAkD3C,wCAAwC,IAAI,OAAO,CAAC,IAAI,CAAC;IAuDzD,4BAA4B,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAuDjF,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"}