bazis 0.108.0 → 0.109.1

package/core/cache/ICache.ts

@@ -1,4 +1,5 @@
 import { createToken, type InjectionToken } from "../di";
+import { registerNamedDependencyHint } from "../di/errors/NamedDependencyNotFoundError";
 import type { CacheEntry } from "./types/CacheEntry";
 import type { CacheSetOptions } from "./types/CacheOptions";
 
@@ -65,6 +66,10 @@ export interface ICache<TValue = unknown> {
 /** Default cache DI token. */
 export const ICache = createToken<ICache>("ICache") as InjectionToken<ICache<unknown>>;
 
+registerNamedDependencyHint((name) => name === "ICache" || name.startsWith("ICache<")
+  ? "The cache is provided by a cache module: add cache: memory() to the runApp options (startTestApp takes the same options)."
+  : undefined);
+
 /** Typed token for a specific value type. */
 export function cacheToken<TValue>(name: string): InjectionToken<ICache<TValue>> {
   return createToken<ICache<TValue>>(`ICache<${name}>`);

package/core/cache/distributed/IDistributedCache.ts

@@ -1,4 +1,5 @@
 import { createToken, type InjectionToken } from "../../di";
+import { registerNamedDependencyHint } from "../../di/errors/NamedDependencyNotFoundError";
 import type { CacheSetOptions } from "../types/CacheOptions";
 
 /** Default named connection used when a decorator omits `connection`. */
@@ -47,3 +48,7 @@ export interface IDistributedCache<TValue = unknown> {
  * `DISTRIBUTED_SERVICE_CACHE.resolve(name)`.
  */
 export const IDistributedCache = createToken<IDistributedCache>("IDistributedCache") as InjectionToken<IDistributedCache<unknown>>;
+
+registerNamedDependencyHint((name) => name === "IDistributedCache"
+  ? "The distributed cache is provided by Redis: add redisConnect(redisConfig, { cache: \"distributed\" }) to the @Infra manifest."
+  : undefined);

package/core/di/errors/NamedDependencyNotFoundError.ts

@@ -1,11 +1,11 @@
 import { DiError } from "./DiError";
 
-/** Returns a hint for a named dependency nobody registers, or `undefined`. */
+/** Returns a hint for a dependency nobody registers (by its name), or `undefined`. */
 export type NamedDependencyHint = (name: string) => string | undefined;
 
 const hints: NamedDependencyHint[] = [];
 
-/** Infrastructure extensions (ORM repositories, …) explain their own named dependencies here. */
+/** Infrastructure extensions (ORM repositories, the cache, …) explain their own dependencies here. */
 export function registerNamedDependencyHint(hint: NamedDependencyHint): void {
   hints.push(hint);
 }
@@ -15,9 +15,10 @@ function hintFor(name: string): string {
   return hint ? ` ${hint}` : "";
 }
 
-/** The graph-validation issue for a named dependency nobody registers, naming the service that needs it. */
-export function missingNamedDependencyIssue(name: string, requester: string): string {
-  return `Missing dependency "${name}" for "${requester}".${hintFor(name)}`;
+/** The graph-validation issue for a dependency nobody registers, naming the service that needs it and the fix when one is known. */
+export function missingDependencyIssue(name: string, requester: string): string {
+  const hint = hintFor(name);
+  return hint === "" ? `Missing dependency "${name}" for "${requester}"` : `Missing dependency "${name}" for "${requester}".${hint}`;
 }
 
 export class NamedDependencyNotFoundError extends DiError {

package/core/di/internal/GraphValidator.ts

@@ -1,5 +1,5 @@
 import { ServiceValidationError } from "../errors";
-import { missingNamedDependencyIssue } from "../errors/NamedDependencyNotFoundError";
+import { missingDependencyIssue } from "../errors/NamedDependencyNotFoundError";
 import { isClassProvider, isLazyDependency, isNamedDependency, isOptionalDependency } from "../provider";
 import type {
   KeyedDependency,
@@ -99,7 +99,7 @@ export class GraphValidator {
         const inner = isLazy || isOptional ? dependency.inner : dependency;
         // An optional dependency on a name nothing registered is simply absent.
         if (isNamedDependency(inner) && !this.context.hasName(inner.name)) {
-          if (!isOptional) issues.add(missingNamedDependencyIssue(inner.name, serviceName(registration)));
+          if (!isOptional) issues.add(missingDependencyIssue(inner.name, serviceName(registration)));
           continue;
         }
         const descriptor = this.context.describeDependency(inner);
@@ -109,7 +109,7 @@ export class GraphValidator {
         }
         if (!depRegistration) {
           issues.add(
-            `Missing dependency "${tokenToDebugName(descriptor.token)}" for "${serviceName(registration)}"`,
+            missingDependencyIssue(tokenToDebugName(descriptor.token), serviceName(registration)),
           );
           continue;
         }

package/core/di/module/encapsulation.ts

@@ -184,16 +184,30 @@ export function validateModuleEncapsulation(
     // module, say) registered the token.
     const blocking = consumer.imports.find((imported) => !imported.providedTokens.has(token)
       && !exportedTokens(imported).has(token) && visibleTokens(imported).has(token));
+    const owner = records.find((record) => record !== consumer && record.providedTokens.has(token));
     if (blocking !== undefined) {
-      return `which its import "${blocking.name}" receives from its own imports but does not export. Add it to the exports of "${blocking.name}".`;
+      // The module that registers and exports the token can be imported
+      // directly; an unnamed inner module (`ormBazis`) cannot.
+      const direct = owner !== undefined && owner !== blocking && exportedTokens(owner).has(token) && !/^module#\d+$/.test(owner.name);
+      return direct
+        ? `which its import "${blocking.name}" receives from "${owner.name}" but does not export. Add "${owner.name}" to the imports of "${consumer.name}", or add it to the exports of "${blocking.name}".`
+        : `which its import "${blocking.name}" receives from its own imports but does not export. Add it to the exports of "${blocking.name}".`;
     }
-    const owner = records.find((record) => record !== consumer && record.providedTokens.has(token));
     if (owner === undefined) return "which is provided by another module but not exported.";
     return exportedTokens(owner).has(token)
       ? `which module "${owner.name}" exports, but "${consumer.name}" does not list "${owner.name}" in its imports. Add "${owner.name}" to the imports of "${consumer.name}".`
       : `which module "${owner.name}" provides but does not export. Add it to the exports of "${owner.name}".`;
   };
 
+  // Whether `record` imports `target`, directly or through other modules. Such a
+  // module cannot be the fix: importing it into `target` would be a cycle, and a
+  // root without exports (AppModule, the kernel root) passes on everything.
+  const importsModule = (record: ModuleGraphRecord, target: ModuleGraphRecord, path = new Set<ModuleGraphRecord>()): boolean => {
+    if (path.has(record)) return false;
+    path.add(record);
+    return record.imports.some((imported) => imported === target || importsModule(imported as ModuleGraphRecord, target, path));
+  };
+
   // A closed token (`IRepository<Product>`) travels with its family export, so
   // the fix is named in family terms and skips unnamed inner modules such as
   // the one `ormBazis` creates.
@@ -203,7 +217,7 @@ export function validateModuleEncapsulation(
     const exportFix = `${family} (or only ${closed})`;
     const sees = (record: ModuleGraphRecord) => visibleFamilies(record).has(familyId) || visibleTokens(record).has(token);
     const passes = (record: ModuleGraphRecord) => exportedFamilies(record).has(familyId) || exportedTokens(record).has(token);
-    const named = (record: ModuleGraphRecord) => !/^module#\d+$/.test(record.name);
+    const named = (record: ModuleGraphRecord) => !/^module#\d+$/.test(record.name) && !importsModule(record, consumer);
     const blocking = consumer.imports.find((imported) => named(imported) && sees(imported) && !passes(imported));
     if (blocking !== undefined) {
       return `which its import "${blocking.name}" receives from its own imports but does not export. Add ${exportFix} to the exports of "${blocking.name}".`;

package/core/http/OpenApi/openApiDocument.ts

@@ -379,9 +379,9 @@ function successStatus(method: string, action: ActionMeta, generated: number | u
 
 /**
  * Errors the operation can answer with: 400 when the request carries values
- * that are converted or validated (body, list query, query, typed route
- * parameters), 401/403 under @Authorize, and the errors the method body
- * returns or throws itself.
+ * that are converted or validated (body, list query, query and header values
+ * and models, typed route parameters), 401/403 under @Authorize, and the
+ * errors the method body returns or throws itself.
  */
 function errorStatuses(
   bindings: readonly ParameterBinding[],
@@ -390,7 +390,8 @@ function errorStatuses(
 ): number[] {
   const statuses = new Set(generated ?? []);
   const validated = bindings.some((binding) =>
-    binding.source === "body" || binding.source === "list" || binding.source === "query"
+    binding.source === "body" || binding.source === "list" || binding.source === "query" || binding.source === "header"
+    || binding.source === "queryModel" || binding.source === "headerModel"
     || (binding.source === "route" && binding.type !== undefined && binding.type !== "string"));
   if (validated) statuses.add(400);
   if (authorized) {

package/core/http-client/index.ts

@@ -2,17 +2,20 @@
  * Core DI/correlation integration for the pure `@/library/http-client`.
  *
  * The HTTP engine lives in the library (framework-agnostic). This module only
- * wires it into the runtime: DI tokens, a module factory, and kernel-based
- * correlation propagation. All library symbols are re-exported for convenience.
+ * wires it into the runtime: a module factory that registers the clients for
+ * injection by type, and kernel-based correlation propagation. All library
+ * symbols are re-exported for convenience.
  *
  * ```ts
- * import { httpClientModule, HTTP_CLIENT } from "@/core/http-client";
+ * import { HttpClient, httpClientModule } from "@/core/http-client";
  *
- * @Module({ imports: [httpClientModule({ default: { baseUrl: "https://api" } })] })
- * class AppModule {}
+ * @Module({ imports: [httpClientModule({ default: { baseUrl: "https://api" } })], providers: [scoped(WeatherService)] })
+ * class WeatherModule {}
+ *
+ * class WeatherService { constructor(private readonly http: HttpClient) {} }
  * ```
  */
-import { DI, Module, createToken, type BazisModule, type ProviderDefinition } from "../di";
+import { DI, Module, type BazisModule, type ProviderDefinition } from "../di";
 import { getOutboundCorrelationHeaders } from "../kernel";
 import {
   HttpClient,
@@ -24,15 +27,10 @@ import {
 
 export * from "../../library/http-client";
 
-/** Named-clients factory token. */
-export const HTTP_CLIENT_FACTORY = createToken<HttpClientFactory>("IHttpClientFactory");
-/** Default injectable {@link HttpClient} token. */
-export const HTTP_CLIENT = createToken<HttpClient>("HttpClient");
-
 export interface HttpClientModuleConfig {
-  /** Named clients resolvable via `HTTP_CLIENT_FACTORY.createClient(name)`. */
+  /** Named clients: `HttpClientFactory.createClient(name)`. */
   readonly clients?: Readonly<Record<string, RequestConfig>>;
-  /** Defaults for the injectable {@link HTTP_CLIENT} and `createClient()`. */
+  /** Defaults for the injectable `HttpClient` and `createClient()`. */
   readonly default?: RequestConfig;
   /** Correlation header source. Default: the kernel async request context. */
   readonly correlationHeaders?: () => HeaderBag;
@@ -45,9 +43,8 @@ export interface HttpClientModuleConfig {
 /**
  * Registers the outbound HTTP client in DI with correlation propagation wired
  * to the kernel request context. A service takes it by type:
- * - `HttpClient` (or the {@link HTTP_CLIENT} token) — the default client;
- * - `HttpClientFactory` (or {@link HTTP_CLIENT_FACTORY}) — named clients
- *   (fail-fast on unknown names).
+ * - `HttpClient` — the default client;
+ * - `HttpClientFactory` — named clients (fail-fast on unknown names).
  */
 export function httpClientModule(config: HttpClientModuleConfig = {}): BazisModule {
   const correlationHeaders = config.correlationHeaders ?? getOutboundCorrelationHeaders;
@@ -85,13 +82,10 @@ export function httpClientModule(config: HttpClientModuleConfig = {}): BazisModu
   const factory = builder.build();
 
   const client = factory.createClient();
-  // One factory and one default client, under the class (injection by type)
-  // and under the original tokens.
+  // One factory and one default client, injected by type.
   const providers: ProviderDefinition[] = [
     DI.singleton(DI.valueProvider(HttpClientFactory, factory)),
-    DI.singleton(DI.valueProvider(HTTP_CLIENT_FACTORY, factory)),
     DI.singleton(DI.valueProvider(HttpClient, client)),
-    DI.singleton(DI.valueProvider(HTTP_CLIENT, client)),
   ];
 
   @Module({ providers })

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.108.0" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.109.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/testing/index.ts

@@ -1,23 +1,36 @@
-import { HOSTED_SERVICE, createContainer, type BazisModuleRef, type CreateContainerOptions, type DiContainer, type ProviderDefinition } from "../di";
+import { HOSTED_SERVICE, type BazisModuleRef, 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";
 
+export interface TestContainerOptions {
+  /** Replacements for registered providers: `singleton(ITaskStore, FakeStore)`. */
+  readonly overrides?: readonly ProviderDefinition[];
+  /** Adjust the kernel before it is built: config sources, a logger. */
+  readonly configure?: (builder: KernelBuilder) => void;
+}
+
 /**
- * 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.
+ * A container for module tests: the module graph with the kernel services an
+ * application has — `Logger`, `EventBus`, `ConfigView` of declared configs,
+ * `Environment` (`test`) — but nothing started: no hosted services, no HTTP.
+ * Loads the project's generated code first (without it constructor
+ * dependencies are missing and a test passes for the wrong reason).
  *
  * ```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> {
+export async function createTestContainer(root: BazisModuleRef, options: TestContainerOptions = {}): Promise<DiContainer> {
   await loadBazisGeneratedRuntime();
-  return createContainer(root, { validateOnBuild: true, ...options });
+  const builder = new KernelBuilder(root).useOptions({ startupReport: false, environment: "test", signals: [] });
+  options.configure?.(builder);
+  if (options.overrides !== undefined) builder.useOverrides(options.overrides);
+  const kernel: Kernel = await builder.build();
+  return kernel.container;
 }
 
 export interface TestAppOptions extends Omit<RunAppOptions, "http"> {

package/library/redaction/index.ts

@@ -84,10 +84,25 @@ function redactValue(
   if (depth >= options.maxDepth) {
     return options.replacement;
   }
+  // `seen` holds the objects on the current path only: an object reached
+  // again through another branch is a shared reference, not a cycle.
   if (seen.has(value)) {
     return CIRCULAR;
   }
   seen.add(value);
+  try {
+    return redactObject(value, options, seen, depth);
+  } finally {
+    seen.delete(value);
+  }
+}
+
+function redactObject(
+  value: object,
+  options: NormalizedRedactionOptions,
+  seen: WeakSet<object>,
+  depth: number,
+): unknown {
   if (value instanceof Error) {
     return redactError(value, options, seen, depth);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.108.0",
+  "version": "0.109.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",