bazis 0.97.11 → 0.98.1

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/http/Binding/ParameterBinder.ts

@@ -24,6 +24,21 @@ function bindValue(binding: ParameterBinding, raw: string | undefined, kind: str
   return binding.type && binding.type !== "string" ? convertOr400(raw, binding.type, binding.name ?? "?") : raw;
 }
 
+/**
+ * `?tag=a&tag=b` → `["a", "b"]`, each value converted by the element type.
+ * Without the parameter: the default, `undefined` for `tag?: string[]`, or `[]`.
+ */
+function bindArray(binding: ParameterBinding, ctx: HttpContext): unknown {
+  const raw = ctx.url.searchParams.getAll(binding.name ?? "");
+  if (raw.length === 0) {
+    if (binding.defaultValue !== undefined) return binding.defaultValue;
+    return binding.optional ? undefined : [];
+  }
+  return binding.type && binding.type !== "string"
+    ? raw.map((value) => convertOr400(value, binding.type!, binding.name ?? "?"))
+    : raw;
+}
+
 /**
  * Resolves generated binding descriptors into the action's argument list.
  * All conversions fail with 400 (never 500); body parse errors and model
@@ -52,7 +67,7 @@ export async function bindArguments(
         break;
       }
       case "query":
-        args[index] = bindValue(binding, ctx.query(binding.name ?? ""), "query");
+        args[index] = binding.array ? bindArray(binding, ctx) : bindValue(binding, ctx.query(binding.name ?? ""), "query");
         break;
       case "body": {
         const contentType = ctx.header("content-type") ?? "";

package/core/http/Binding/autoBindings.ts

@@ -55,7 +55,7 @@ function toBinding(spec: GeneratedBindingSpec, controllerName: string, methodNam
     case "route":
       return { source: "route", name: spec.name, type: spec.type, optional: spec.optional };
     case "query":
-      return { source: "query", name: spec.name, type: spec.type, optional: spec.optional };
+      return { source: "query", name: spec.name, type: spec.type, optional: spec.optional, array: spec.array };
     case "context":
       return { source: "context" };
     case "request":

package/core/http/Binding/bindings.ts

@@ -11,6 +11,8 @@ export interface ParameterBinding {
   readonly type?: ValueType;
   readonly defaultValue?: unknown;
   readonly optional?: boolean;
+  /** Query array: all values of the name (`?tag=a&tag=b`), each converted by `type`. */
+  readonly array?: boolean;
   /** Body model class (instantiated, sanitized and validated). */
   readonly model?: Class<object>;
   /** Whitelist/limits for the class-based list binding (JSON:API list query). */

package/core/http/Binding/generatedSpec.ts

@@ -13,6 +13,8 @@ export interface GeneratedBindingSpec {
   readonly type?: "int" | "number" | "bool" | "string";
   /** The parameter is declared with `?` or a default value. */
   readonly optional?: boolean;
+  /** A query array (`tag: string[]`): every `?tag=` value, each converted by `type`. */
+  readonly array?: boolean;
   /** DTO class name (resolved through the generated target; `@RequestModel()` classes are the fallback). */
   readonly model?: string;
 }

package/core/http/OpenApi/openApiDocument.ts

@@ -173,8 +173,8 @@ function collectParameters(
           parameters.push({
             name: binding.name,
             in: "query",
-            required: binding.optional !== true && binding.defaultValue === undefined,
-            schema: schemaForValueType(binding.type),
+            required: binding.array !== true && binding.optional !== true && binding.defaultValue === undefined,
+            schema: binding.array ? { type: "array", items: schemaForValueType(binding.type) } : schemaForValueType(binding.type),
           });
         }
         break;

package/core/http/Routing/Router.ts

@@ -17,6 +17,8 @@ export interface RouteAction {
 
 interface RouteEntry {
   readonly action: RouteAction;
+  /** The registered path, for diagnostics: `/tasks/:id`. */
+  readonly template: string;
   /** Names belong to the selected declaration, never to shared tree edges. */
   readonly bindings: readonly { readonly name: string; readonly index: number }[];
 }
@@ -58,6 +60,7 @@ export class Router {
   register(segments: readonly TemplateSegment[], httpMethod: string, versionKey: string, action: RouteAction): void {
     const entry: RouteEntry = {
       action,
+      template: renderTemplate(segments),
       bindings: segments.flatMap((segment, index) => segment.kind === "static" ? [] : [{ name: segment.name, index }]),
     };
     let node = this.root;
@@ -101,8 +104,11 @@ export class Router {
       leaf.set(httpMethod, versions);
     }
     if (versions.has(versionKey)) {
+      const existing = versions.get(versionKey)!;
+      const version = versionKey ? ` (version ${versionKey})` : "";
       throw new HttpSetupError(
-        `Duplicate route: ${httpMethod} (version "${versionKey || "-"}") already mapped to ${versions.get(versionKey)!.action.name}, cannot map ${entry.action.name}.`,
+        `Duplicate route: ${httpMethod} ${entry.template}${version} is mapped to both ${existing.action.name} (${existing.template}) and ${entry.action.name}. `
+          + "Routes that differ only in parameter names are the same route; change one of the paths.",
       );
     }
     versions.set(versionKey, entry);
@@ -199,3 +205,10 @@ function constraintPriority(constraint: SegmentConstraint | undefined): number {
       return 0;
   }
 }
+
+/** `/tasks/:id(int)/files/*path` from parsed segments. */
+function renderTemplate(segments: readonly TemplateSegment[]): string {
+  return `/${segments.map((segment) => segment.kind === "static" ? segment.value
+    : segment.kind === "param" ? `:${segment.name}${segment.constraint ? `(${segment.constraint.name})` : ""}`
+    : `*${segment.name}`).join("/")}`;
+}

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.1" }, 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/scripts/di-generate.ts

@@ -178,6 +178,7 @@ interface HttpBindingSpec {
   type?: "int" | "number" | "bool" | "string";
   optional?: boolean;
   model?: string;
+  array?: boolean;
 }
 let httpBindings: Record<string, Record<string, HttpBindingSpec[]>> = {};
 interface GrpcRequestBinding {
@@ -1030,6 +1031,16 @@ function readConstructorTypeNames(node: ts.ClassDeclaration): ConstructorDepende
 }
 
 /** Resolve imported type aliases/re-exports; runtime named binding stays module-scoped. */
+/** The element keyword of an array type: `string[]`, `Array<string>`, `readonly string[]` -> "string". */
+function arrayElementKeyword(node: ts.TypeNode): string | undefined {
+  if (ts.isTypeOperatorNode(node) && node.operator === ts.SyntaxKind.ReadonlyKeyword) return arrayElementKeyword(node.type);
+  if (ts.isArrayTypeNode(node)) return node.elementType.getText().trim();
+  if (ts.isTypeReferenceNode(node) && ["Array", "ReadonlyArray"].includes(node.typeName.getText()) && node.typeArguments?.length === 1) {
+    return node.typeArguments[0]!.getText().trim();
+  }
+  return undefined;
+}
+
 function getDependencyTypeName(node: ts.TypeNode): string | undefined {
   if (!ts.isTypeReferenceNode(node)) return undefined;
   const symbol = checker.getSymbolAtLocation(node.typeName);
@@ -1425,6 +1436,13 @@ function collectControllerBindings(node: ts.ClassDeclaration, controllerName: st
         specs.push({ source: "route", name: paramName, type: type === "string" ? undefined : type, optional });
         continue;
       }
+      // `tag: string[]`, `Array<number>`, `readonly boolean[]` -> every ?tag= value.
+      const elementKeyword = typeNode ? arrayElementKeyword(typeNode) : undefined;
+      const elementType = elementKeyword !== undefined ? PRIMITIVE_QUERY_TYPES[elementKeyword] : undefined;
+      if (elementType !== undefined) {
+        specs.push({ source: "query", name: paramName, type: elementType === "string" ? undefined : elementType, optional, array: true });
+        continue;
+      }
       const primitiveType =
         keywordType !== undefined ? PRIMITIVE_QUERY_TYPES[keywordType] : inferTypeFromInitializer(param.initializer);
       if (primitiveType !== undefined) {

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.1",
   "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",