bazis 0.100.7 → 0.100.8

package/core/di/errors/InvalidProviderError.ts

@@ -1,9 +1,10 @@
 import { DiError } from "./DiError";
 
 export class InvalidProviderError extends DiError {
-  public constructor(tokenName: string) {
+  /** `message` replaces the default text when the caller knows more (the module and position). */
+  public constructor(tokenName: string, message?: string) {
     super(
-      `Provider for "${tokenName}" has unknown shape: expected one of useClass/useFactory/useValue.`,
+      message ?? `Provider for "${tokenName}" has unknown shape: expected one of useClass/useFactory/useValue.`,
     );
   }
 }

package/core/di/errors/ScopedServiceFromRootError.ts

@@ -4,6 +4,7 @@ import { DiError } from "./DiError";
 
 export class ScopedServiceFromRootError extends DiError {
   public constructor(token: Token<unknown>) {
-    super(`Cannot resolve scoped service "${tokenToDebugName(token)}" from root provider.`);
+    const name = tokenToDebugName(token);
+    super(`Cannot resolve scoped service "${name}" from root provider. A scoped service lives in a request or a scope: create one with provider.createScope(), resolve "${name}" from it and dispose the scope when done.`);
   }
 }

package/core/di/internal/GraphValidator.ts

@@ -64,8 +64,12 @@ export class GraphValidator {
     issues: Set<string>,
   ): void {
     if (registrationPath.has(registration.id)) {
-      const cyclePath = [...tokenPath, registration.token].map((token) => tokenToDebugName(token)).join(" -> ");
-      issues.add(`Cycle detected: ${cyclePath}`);
+      // One cycle is reached from each of its members: report it once, as the cycle itself.
+      const start = tokenPath.indexOf(registration.token);
+      const members = (start >= 0 ? tokenPath.slice(start) : tokenPath).map((token) => tokenToDebugName(token));
+      const first = members.indexOf([...members].sort()[0] as string);
+      const canonical = [...members.slice(first), ...members.slice(0, first)];
+      issues.add(`Cycle detected: ${[...canonical, canonical[0]].join(" -> ")}`);
       return;
     }
 

package/core/di/module/createContainer.ts

@@ -4,7 +4,7 @@ import { HOSTED_SERVICE, HOSTED_SERVICE_HEALTH, type HostedService } from "../ex
 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 { DiError, ModuleEncapsulationError } from "../errors";
+import { DiError, InvalidProviderError, ModuleEncapsulationError } from "../errors";
 import { OpenGenericRegistration } from "../internal/OpenGenericRegistration";
 import { tokenToDebugName, type Class } from "../token";
 import type { BuildServiceProviderOptions } from "../types";
@@ -133,6 +133,7 @@ export function createContainer(rootModule: BazisModuleRef, options?: CreateCont
     const providers = moduleRef.providers;
     if (providers) {
       for (let index = 0; index < providers.length; index += 1) {
+        assertProviderDefinition(providers[index], record.name, index);
         collection.add(providers[index] as ProviderDefinition);
       }
     }
@@ -311,3 +312,19 @@ function normalizeLateGeneratedClassDeps(definition: ProviderDefinition): Provid
   const normalizedProvider = { ...provider, deps: generatedDeps } as Provider<unknown>;
   return new ProviderDefinition(normalizedProvider, definition.lifetime, definition.key);
 }
+
+/**
+ * A module lists registrations made by singleton/scoped/transient/…; a raw
+ * `{ provide: X }` object used to crash later with a bare TypeError.
+ */
+function assertProviderDefinition(value: unknown, moduleName: string, index: number): void {
+  const provider = (value as { provider?: unknown } | null | undefined)?.provider;
+  if (typeof provider === "object" && provider !== null && "provide" in provider) return;
+  const provide = (value as { provide?: unknown } | null | undefined)?.provide;
+  const name = typeof provide === "function" ? provide.name : typeof provide === "string" ? provide : String(provide ?? value);
+  throw new InvalidProviderError(
+    name,
+    `Module "${moduleName}": providers[${index}] is not a provider registration${provide === undefined ? "" : ` ({ provide: ${name} })`}. `
+      + `Register it with singleton(${name}), scoped(${name}), transient(${name}), singletonValue(TOKEN, value) or singletonFactory(TOKEN, [deps], factory).`,
+  );
+}

package/core/http/Errors/HttpError.ts

@@ -1,3 +1,4 @@
+import { KernelError } from "../../kernel";
 import type { ModelValidationIssue } from "../Binding/modelValidator";
 import { englishHttpMessage, type HttpMessageKey, type LocalizedMessage, type MessageParams } from "./messages";
 
@@ -111,11 +112,7 @@ export function frameworkBadRequest(key: HttpMessageKey, params?: MessageParams,
 
 /**
  * Misconfigured routes/controllers (duplicate route, bad template, missing
- * @Controller). Thrown at startup, never at request time — fail fast.
+ * @Controller). Thrown at startup, never at request time — fail fast. A
+ * KernelError: the start reports it as a configuration error of the code.
  */
-export class HttpSetupError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "HttpSetupError";
-  }
-}
+export class HttpSetupError extends KernelError {}

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

@@ -69,9 +69,17 @@ export class Bazis {
     } catch (error) {
       stopWaiting?.();
       if (error instanceof ShutdownTimeoutError) {
+        // A failed start whose cleanup is stuck: report why the start failed
+        // first, otherwise only the cleanup timeout would be visible.
+        const startFailure = error.cause;
+        if (startFailure !== undefined) {
+          if (screen !== undefined) screen.failed(startFailure, kernel);
+          else console.error(`[bazis] application failed: ${formatStartupFailure(startFailure)}`);
+        }
         // Graceful shutdown is stuck: hanging handles would keep the process
         // alive forever, so this is the one place a hard exit is correct.
-        console.error(`[bazis] ${redactSensitiveText(error.message)} Forcing exit.`);
+        const text = startFailure === undefined ? error.message : `Cleanup after the failed start did not finish within ${error.timeoutMs}ms.`;
+        console.error(`[bazis] ${redactSensitiveText(text)} Forcing exit.`);
         process.exit(1);
       }
       // Configuration problems surfacing at start (e.g. options fail-fast)

package/core/kernel/LifecycleCoordinator.ts

@@ -97,7 +97,16 @@ export class LifecycleCoordinator {
 
     try {
       for (let index = 0; index < this.hooks.length; index += 1) {
-        await this.invokeHook(() => (this.hooks[index] as LifecycleHook).onInit?.(), signal);
+        const hook = this.hooks[index] as LifecycleHook;
+        if (hook.onInit === undefined) continue;
+        // A hung onInit is named by the startup timeout, like a hosted service.
+        const name = `hook ${hook.constructor?.name ?? "LifecycleHook"}.onInit`;
+        this.pending.add(name);
+        try {
+          await this.invokeHook(() => hook.onInit?.(), signal);
+        } finally {
+          this.pending.delete(name);
+        }
       }
 
       const phases = groupByPhase(hosted);

package/core/kernel/config/defineConfig.ts

@@ -184,7 +184,11 @@ export function defineConfig(prefixOrSchema: string | ConfigSchema<Defaults>, ma
       const priority = Math.max(...candidates.map(candidate => candidate.priority));
       const winners = candidates.filter(candidate => candidate.priority === priority);
       const selected = winners[0];
-      if (winners.some(candidate => candidate.raw !== selected?.raw)) issue(key, "conflict", "conflicting environment aliases");
+      if (winners.some(candidate => candidate.raw !== selected?.raw)) {
+        // Names only: the values may be secrets.
+        const variables = [...new Set(winners.map(candidate => candidate.name))];
+        issue(key, "conflict", `conflicting environment aliases: ${variables.join(" and ")} are set to different values; set only one`);
+      }
       const raw = selected?.raw ?? (isSecret(cell) || isEnum(cell) ? cell.default : cell);
       let value: ConfigValueType | undefined;
       if (type === "secret") {

package/core/kernel/startupFailure.ts

@@ -1,6 +1,6 @@
 import { inspect } from "node:util";
 import { redactSensitive, redactSensitiveText } from "../../library/redaction";
-import { StartupFailuresError } from "./errors";
+import { ShutdownTimeoutError, StartupFailuresError, StartupTimeoutError } from "./errors";
 
 const MAX_CAUSES = 5;
 /** Properties already printed in the header, the frames or the cause chain. */
@@ -32,7 +32,9 @@ export function formatStartupFailure(error: unknown): string {
     // Services that failed together: the list above is the report; the
     // aggregate's own frames are the kernel's, not the application's.
     if (!(current instanceof StartupFailuresError)) lines.push(...(current.stack ?? "").split("\n").filter((line) => /^\s+at /.test(line)));
-    const details = Object.fromEntries(Object.entries(current).filter(([name]) => !SHOWN.has(name)));
+    // Timeouts already say their limit and what was pending in the message.
+    const restated = current instanceof StartupTimeoutError || current instanceof ShutdownTimeoutError;
+    const details = restated ? {} : Object.fromEntries(Object.entries(current).filter(([name]) => !SHOWN.has(name)));
     if (Object.keys(details).length > 0) lines.push(inspect(redactSensitive(details), INSPECT));
     current = current.cause;
   }

package/library/http-client/HttpClient.ts

@@ -1,4 +1,5 @@
 import { HttpClientError, HttpErrorCode } from "./errors";
+import { assertKnownOptions } from "./configKeys";
 import { InspectableRedirectProtocol as redirectProtocol } from "./redirectProtocol";
 import { InterceptorManager } from "./interceptors";
 import { trackDownload } from "./progress";
@@ -85,6 +86,7 @@ export class HttpClient {
   };
 
   public constructor(defaults: RequestConfig = {}) {
+    assertKnownOptions(defaults, "the client defaults");
     this.defaults = defaults;
     this.interceptors = {
       request: new InterceptorManager<ResolvedRequestConfig>(),
@@ -106,6 +108,11 @@ export class HttpClient {
   public request<T = unknown>(configOrUrl: RequestConfig | string, maybeConfig: RequestConfig = {}): Promise<HttpResponse<T>> {
     const config: RequestConfig =
       typeof configOrUrl === "string" ? { ...maybeConfig, url: configOrUrl } : configOrUrl;
+    try {
+      assertKnownOptions(config, "the request config");
+    } catch (error) {
+      return Promise.reject(error);
+    }
     const merged = this.mergeConfig(this.defaults, config);
 
     // axios ordering: request interceptors run last-registered-first.

package/library/http-client/configKeys.ts

@@ -0,0 +1,36 @@
+import { HttpClientError } from "./errors";
+import type { RequestConfig } from "./types";
+
+/**
+ * Every option of {@link RequestConfig}, checked so a misspelled one is not
+ * silently ignored. A record, not a list: a new option fails typecheck until
+ * it is added here.
+ */
+const OPTIONS: Readonly<Record<keyof RequestConfig, true>> = {
+  url: true, method: true, baseUrl: true, headers: true, params: true, paramsSerializer: true, data: true,
+  transformRequest: true, transformResponse: true, onDownloadProgress: true, timeoutMs: true, maxResponseBytes: true,
+  signal: true, responseType: true, withCredentials: true, credentials: true, auth: true,
+  allowCrossOriginCredentials: true, validateStatus: true, retry: true, propagateCorrelation: true,
+  correlationHeaders: true, fetch: true, inspectableRedirects: true, redirect: true, maxRedirects: true, cache: true,
+  mode: true, keepalive: true, meta: true,
+};
+const KNOWN: ReadonlySet<string> = new Set(Object.keys(OPTIONS));
+
+/** axios names with a different spelling here. */
+const AXIOS_NAMES: Readonly<Record<string, keyof RequestConfig>> = {
+  timeout: "timeoutMs",
+  maxContentLength: "maxResponseBytes",
+};
+
+/**
+ * Rejects an option the client does not know. Without it `baseURL` (the axios
+ * spelling) was dropped, and every call failed with ERR_NETWORK
+ * "fetch() URL is invalid".
+ */
+export function assertKnownOptions(config: object, where: string): void {
+  for (const key of Object.keys(config)) {
+    if (KNOWN.has(key)) continue;
+    const suggestion = AXIOS_NAMES[key] ?? [...KNOWN].find((known) => known.toLowerCase() === key.toLowerCase());
+    throw new HttpClientError(`Unknown HttpClient option "${key}" in ${where}${suggestion === undefined ? "" : `; did you mean "${suggestion}"?`}`);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.100.7",
+  "version": "0.100.8",
   "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",