bazis 0.97.11 → 0.98.0

package/core/app/runApp.ts

@@ -238,9 +238,16 @@ function normalizeAbsolutePath(path: string): string {
  * The root module stays clean: `@Module({ imports: [UsersModule] })`.
  */
 export async function runApp(root: BazisModuleRef, options: RunAppOptions = {}): Promise<number> {
-  const configure = options.configure;
   await loadBazisGeneratedRuntime();
+  return Bazis.run(composeApp(root, options), options.kernel, options.configure);
+}
 
+/**
+ * @internal The application root `runApp` starts: infrastructure, cache and
+ * configs next to the feature root, wrapped in the HTTP/gRPC/UI hosts the
+ * options ask for. Shared with `startTestApp`, so tests run the same graph.
+ */
+export function composeApp(root: BazisModuleRef, options: RunAppOptions = {}): BazisModuleRef {
   // Infrastructure and cache are global modules; add them to the graph next to the feature root.
   const globals: BazisModuleRef[] = [];
   if (options.infra !== undefined) {
@@ -277,17 +284,15 @@ export async function runApp(root: BazisModuleRef, options: RunAppOptions = {}):
       validator,
       imports: [httpAppRoot],
     });
-    const runtimeRoot = options.grpc === undefined ? httpRoot : {
+    return options.grpc === undefined ? httpRoot : {
       imports: [httpRoot, grpcModule({ ...options.grpc, validator: options.grpc.validator === undefined ? validator : options.grpc.validator, imports: [appRoot, ...(options.grpc.imports ?? [])] })],
     };
-    return Bazis.run(runtimeRoot, options.kernel, configure);
   }
 
   if (options.validator) {
     useModelValidator(options.validator);
   }
   const runtimeRoot = withUiRuntime(appRoot, options.ui, undefined);
-  const transportRoot = options.grpc === undefined ? runtimeRoot
+  return options.grpc === undefined ? runtimeRoot
     : grpcModule({ ...options.grpc, validator: options.grpc.validator === undefined ? options.validator ?? modelValidatorAdapter : options.grpc.validator, imports: [runtimeRoot, ...(options.grpc.imports ?? [])] });
-  return Bazis.run(transportRoot, options.kernel, configure);
 }

package/core/di/index.ts

@@ -22,6 +22,7 @@ export {
 } from "./errors";
 export {
   createContainer,
+  type CreateContainerOptions,
   collectModuleControllers,
   collectModuleConfigs,
   collectModuleUiProfiles,

package/core/di/module/createContainer.ts

@@ -4,9 +4,9 @@ import { HOSTED_SERVICE, type HostedService } from "../extensions/hosted-service
 import { SERVICE_PROVIDER, SERVICE_PROVIDER_BY_TYPE } from "../extensions/service-provider-token";
 import { isClassProvider, ProviderDefinition, type Provider } from "../provider";
 import { getClassDeps } from "../internal/classDeps";
-import { ModuleEncapsulationError } from "../errors";
+import { DiError, ModuleEncapsulationError } from "../errors";
 import { OpenGenericRegistration } from "../internal/OpenGenericRegistration";
-import type { Class } from "../token";
+import { tokenToDebugName, type Class } from "../token";
 import type { BuildServiceProviderOptions } from "../types";
 import { DI } from "./DI";
 import { Global } from "./Global";
@@ -36,7 +36,17 @@ function moduleDiagnosticName(moduleRef: BazisModuleRef, fallbackIndex: number):
   return `module#${fallbackIndex}`;
 }
 
-export function createContainer(rootModule: BazisModuleRef, options?: BuildServiceProviderOptions): DiContainer {
+export interface CreateContainerOptions extends BuildServiceProviderOptions {
+  /**
+   * Replacements for registered providers, for tests: `singleton(ITaskStore,
+   * FakeStore)`. They are registered after the whole module graph, so they win
+   * regardless of `imports` order, and they are visible to every module. Each
+   * one must replace an existing registration of its token (and key).
+   */
+  readonly overrides?: readonly ProviderDefinition[];
+}
+
+export function createContainer(rootModule: BazisModuleRef, options?: CreateContainerOptions): DiContainer {
   // The container itself is injectable (SERVICE_PROVIDER, .NET-style). The
   // instance does not exist until the end of this function, so the factory
   // closes over a ref that is assigned right after construction.
@@ -187,6 +197,9 @@ export function createContainer(rootModule: BazisModuleRef, options?: BuildServi
 
   loadModule(diInfraModule);
   loadModule(rootModule);
+  if (options?.overrides !== undefined && options.overrides.length > 0) {
+    loadModule(overridesModule(rootModule, options.overrides, collection.toArray()));
+  }
   const recordList = Array.from(records.values());
   const collectedDefinitions = collection.toArray();
   const classProviderHooks = collectClassProviderHooks(collectedDefinitions);
@@ -247,6 +260,30 @@ export function createContainer(rootModule: BazisModuleRef, options?: BuildServi
   return built;
 }
 
+/**
+ * A global module loaded last: its registrations win and are exported to every
+ * module. It imports the root, so a replacement may use the root's exports.
+ */
+function overridesModule(
+  rootModule: BazisModuleRef,
+  overrides: readonly ProviderDefinition[],
+  registered: readonly ProviderDefinition[],
+): BazisModuleRef {
+  for (const override of overrides) {
+    const token = override.provider.provide;
+    if (!registered.some((definition) => definition.provider.provide === token && definition.key === override.key)) {
+      const subject = override.key === undefined ? `"${tokenToDebugName(token)}"` : `"${tokenToDebugName(token)}" with key ${JSON.stringify(String(override.key))}`;
+      throw new DiError(`Override of ${subject} replaces nothing: no module registers it. Check the token, or register it in a module first.`);
+    }
+  }
+  return {
+    imports: [rootModule],
+    providers: overrides,
+    exports: [...new Set(overrides.map((override) => override.provider.provide))],
+    global: true,
+  };
+}
+
 function normalizeLateGeneratedClassDeps(definition: ProviderDefinition): ProviderDefinition {
   const provider = definition.provider;
   if (!isClassProvider(provider) || provider.deps !== undefined || getClassDeps(provider.useClass) !== undefined) {

package/core/di/module/index.ts

@@ -25,7 +25,7 @@ export {
   type ModuleOwnedProviderContributionContext,
   type ModuleOwnedProviderContributor,
 } from "./moduleOwnedProviderContributors";
-export { createContainer } from "./createContainer";
+export { createContainer, type CreateContainerOptions } from "./createContainer";
 export { collectModuleControllers } from "./collectModuleControllers";
 export { collectModuleConfigs } from "./collectModuleConfigs";
 export { collectModuleUiProfiles } from "./collectModuleUiProfiles";

package/core/generatedRuntime.ts

@@ -165,12 +165,14 @@ async function loadRuntimeOnce(): Promise<void> {
 
 /**
  * The project's generated module `name`, or undefined when it does not exist.
- * Framework sources inside the project (`src/bazis`) find `src/generated`
- * next to them; an installed package (`node_modules/bazis`) cannot, so the
- * project root is the working directory, as for `bazis dev` and `bazis test`.
+ * The project root is the working directory, as for `bazis dev` and `bazis
+ * test`; it comes first, because a framework linked from another checkout
+ * (`bazis new --link-framework`) would otherwise find that checkout's own
+ * `src/generated` next to its sources. Framework sources inside the project
+ * (`src/bazis`) find the same directory either way.
  */
 async function importGeneratedModule<T>(name: string): Promise<T | undefined> {
-  const candidates = [`../../generated/bazis/${name}`, path.join(process.cwd(), "src/generated/bazis", name)];
+  const candidates = [path.join(process.cwd(), "src/generated/bazis", name), `../../generated/bazis/${name}`];
   for (const candidate of candidates) {
     try {
       return (await import(candidate)) as T;

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.97.11" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.0" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/kernel/KernelBuilder.ts

@@ -1,4 +1,4 @@
-import { DI, Global, Module, collectModuleConfigs, createContainer, type BazisModule, type BazisModuleRef } from "../di";
+import { DI, Global, Module, collectModuleConfigs, createContainer, type BazisModule, type BazisModuleRef, type ProviderDefinition } from "../di";
 import { isBazisModuleClass } from "../di/module/Module";
 import { ApplicationLifetime } from "./ApplicationLifetime";
 import { Configuration, loadConfiguration } from "./config/Configuration";
@@ -44,6 +44,7 @@ export class KernelBuilder {
   private signals: readonly NodeJS.Signals[] = DEFAULT_SIGNALS;
   private unhandledErrorPolicy: UnhandledErrorPolicy = "shutdown";
   private validateOnBuild = true;
+  private overrides: readonly ProviderDefinition[] = [];
   private startupReport?: boolean;
   private logger?: Logger;
 
@@ -100,6 +101,15 @@ export class KernelBuilder {
     return this;
   }
 
+  /**
+   * Replacements for registered providers, for tests (see `createContainer`
+   * `overrides`): registered after the whole graph and visible to every module.
+   */
+  public useOverrides(overrides: readonly ProviderDefinition[]): this {
+    this.overrides = [...this.overrides, ...overrides];
+    return this;
+  }
+
   /** Sources are merged in registration order: later sources override earlier ones. */
   public addConfigSource(source: ConfigSource): this {
     this.configSources.push(source);
@@ -152,7 +162,7 @@ export class KernelBuilder {
     const kernelRootModule = BazisKernelModule;
 
     const containerStartedAt = performance.now();
-    const container = createContainer(kernelRootModule, { validateOnBuild: this.validateOnBuild });
+    const container = createContainer(kernelRootModule, { validateOnBuild: this.validateOnBuild, overrides: this.overrides });
     const containerMs = performance.now() - containerStartedAt;
 
     const timings: KernelTimings = {

package/core/testing/index.ts

@@ -0,0 +1,75 @@
+import { HOSTED_SERVICE, createContainer, type BazisModuleRef, type CreateContainerOptions, type DiContainer, type ProviderDefinition } from "../di";
+import { loadBazisGeneratedRuntime } from "../generatedRuntime";
+import { HttpServer, type HttpModuleOptions } from "../http";
+import { KernelBuilder, type Kernel } from "../kernel";
+import { composeApp } from "../app/runApp";
+import type { RunAppOptions } from "../app";
+
+/**
+ * A container for module tests. Loads the project's generated code first
+ * (without it constructor dependencies are missing and a test passes for the
+ * wrong reason), then builds the graph with the replacements.
+ *
+ * ```ts
+ * const container = await createTestContainer(TaskModule, { overrides: [singleton(ITaskStore, FakeStore)] });
+ * const tasks = container.createScope().resolve(TaskService);
+ * ```
+ */
+export async function createTestContainer(root: BazisModuleRef, options: CreateContainerOptions = {}): Promise<DiContainer> {
+  await loadBazisGeneratedRuntime();
+  return createContainer(root, { validateOnBuild: true, ...options });
+}
+
+export interface TestAppOptions extends Omit<RunAppOptions, "http"> {
+  /** HTTP options; the test app always listens on 127.0.0.1 and a free port. `false`: no HTTP server. */
+  readonly http?: Omit<HttpModuleOptions, "port" | "hostname"> | false;
+  /** Replacements for registered providers, see `createContainer` `overrides`. */
+  readonly overrides?: readonly ProviderDefinition[];
+}
+
+export interface TestApp {
+  /** `http://127.0.0.1:<port>`; empty without an HTTP server. */
+  readonly url: string;
+  /** `fetch` relative to {@link url}: `app.fetch("/tasks/1")`. */
+  fetch(path: string, init?: RequestInit): Promise<Response>;
+  /** The application container: `app.container.createScope().resolve(TaskService)`. */
+  readonly container: DiContainer;
+  /** Graceful stop, like SIGTERM in a real run. */
+  stop(): Promise<void>;
+}
+
+/**
+ * Starts the application in this process the way `runApp` does, for tests:
+ * environment `test`, a free port, no signal handlers, no startup report.
+ * Configuration errors and failing startup throw instead of exiting the process.
+ *
+ * ```ts
+ * const app = await startTestApp(AppModule, { overrides: [singleton(ITaskStore, FakeStore)] });
+ * try {
+ *   expect((await app.fetch("/tasks/1")).status).toBe(200);
+ * } finally {
+ *   await app.stop();
+ * }
+ * ```
+ */
+export async function startTestApp(root: BazisModuleRef, options: TestAppOptions = {}): Promise<TestApp> {
+  await loadBazisGeneratedRuntime();
+  const { http, overrides, configure, kernel: kernelOptions, ...rest } = options;
+  const appRoot = composeApp(root, { ...rest, http: http === false ? undefined : { ...http, hostname: "127.0.0.1", port: 0 } });
+  const builder = new KernelBuilder(appRoot).useOptions({ startupReport: false, ...kernelOptions, environment: kernelOptions?.environment ?? "test", signals: [] });
+  configure?.(builder);
+  if (overrides !== undefined) builder.useOverrides(overrides);
+  const kernel: Kernel = await builder.build();
+  await kernel.start();
+  const server = kernel.container.resolveAll(HOSTED_SERVICE).find((service): service is HttpServer => service instanceof HttpServer);
+  const url = server ? `http://127.0.0.1:${server.port}` : "";
+  return {
+    url,
+    container: kernel.container,
+    fetch: (path, init) => {
+      if (!url) throw new Error("startTestApp was started with http: false.");
+      return fetch(`${url}${path}`, init);
+    },
+    stop: () => kernel.stop(),
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.97.11",
+  "version": "0.98.0",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",
@@ -41,6 +41,7 @@
     "./core/infra": "./core/infra/index.ts",
     "./core/kernel": "./core/kernel/index.ts",
     "./core/orm": "./core/orm/index.ts",
+    "./core/testing": "./core/testing/index.ts",
     "./core/websocket": "./core/websocket/index.ts",
     "./library/boundary": "./library/boundary/index.ts",
     "./library/http-client": "./library/http-client/index.ts",