bazis 0.96.1

package/core/background/BackgroundService.ts

@@ -0,0 +1,223 @@
+import type { HostedService } from "../di";
+import { backgroundOptionsOf } from "./decorator";
+import { delay } from "./delay";
+import { redactSensitive } from "../../library/redaction";
+
+/** Restart-on-crash policy for a long-running {@link BackgroundService}. */
+export interface BackgroundRestartPolicy {
+  /** Restarts after a crash (not counting the first run). Default: 0 (off). */
+  readonly maxRestarts?: number;
+  /** Initial backoff before a restart; doubles each time. Default: 500ms. */
+  readonly backoffMs?: number;
+  /** Backoff cap. Default: 30000ms. */
+  readonly maxBackoffMs?: number;
+  /** Synchronous diagnostic notification. Errors (including returned rejections) never stop restarts. */
+  readonly onError?: (error: unknown, restarts: number) => void;
+}
+
+export interface BackgroundServiceOptions {
+  /** Startup phase (see {@link HostedService.phase}). Default: 0. */
+  readonly phase?: number;
+  /** Grace period to await `execute` after abort on stop. Default: 5000ms. */
+  readonly stopTimeoutMs?: number;
+  /** Restart-on-crash policy. Default: no restart (crash is logged). */
+  readonly restart?: BackgroundRestartPolicy;
+}
+
+const DEFAULT_STOP_TIMEOUT_MS = 5_000;
+
+/**
+ * Base class for long-running background work, integrated with the kernel
+ * lifecycle as a {@link HostedService}.
+ *
+ * `start()` is **non-blocking**: it launches {@link execute} in the background
+ * (so it never stalls phased startup) and hands it an {@link AbortSignal}.
+ * `stop()` aborts that signal and awaits completion within `stopTimeoutMs`.
+ * Cooperate by checking `signal.aborted` and awaiting {@link delay}`(ms, signal)`.
+ *
+ * ```ts
+ * class Heartbeat extends BackgroundService {
+ *   constructor(private readonly api: HttpClient) { super({ stopTimeoutMs: 2000 }); }
+ *   protected async execute(signal: AbortSignal) {
+ *     while (!signal.aborted) {
+ *       await this.api.post("/heartbeat");
+ *       await delay(15_000, signal);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export abstract class BackgroundService implements HostedService {
+  public readonly phase: number;
+  private readonly stopTimeoutMs: number;
+  private readonly restart: BackgroundRestartPolicy;
+  private controller?: AbortController;
+  private runPromise?: Promise<void>;
+
+  public constructor(options?: BackgroundServiceOptions) {
+    // Explicit `super(...)` options win over `@Background({...})` metadata.
+    const resolved = { ...backgroundOptionsOf(this.constructor), ...options };
+    this.phase = resolved.phase ?? 0;
+    this.stopTimeoutMs = resolved.stopTimeoutMs ?? DEFAULT_STOP_TIMEOUT_MS;
+    this.restart = resolved.restart ?? {};
+  }
+
+  /** The background workload. Must observe `signal` for cooperative shutdown. */
+  protected abstract execute(signal: AbortSignal): void | Promise<void>;
+
+  public start(): void {
+    if (this.controller) {
+      return;
+    }
+    this.controller = new AbortController();
+    this.runPromise = this.runSupervised(this.controller.signal)
+      .catch((error: unknown) => logBackgroundError(this.constructor.name, error));
+  }
+
+  public async stop(): Promise<void> {
+    if (!this.controller) {
+      return;
+    }
+    this.controller.abort();
+    const pending = this.runPromise;
+    this.controller = undefined;
+    this.runPromise = undefined;
+    if (pending) {
+      await waitWithTimeout(pending, this.stopTimeoutMs, this.constructor.name);
+    }
+  }
+
+  /** Runs {@link execute}, restarting on crash per the policy. Never throws. */
+  private async runSupervised(signal: AbortSignal): Promise<void> {
+    const maxRestarts = Math.max(0, this.restart.maxRestarts ?? 0);
+    const baseBackoff = this.restart.backoffMs ?? 500;
+    const maxBackoff = this.restart.maxBackoffMs ?? 30_000;
+    let restarts = 0;
+
+    for (;;) {
+      try {
+        await this.execute(signal);
+        return;
+      } catch (error) {
+        if (signal.aborted) {
+          return;
+        }
+        this.reportError(error, restarts);
+        if (restarts >= maxRestarts) {
+          return;
+        }
+        restarts += 1;
+        await delay(Math.min(baseBackoff * 2 ** (restarts - 1), maxBackoff), signal);
+        if (signal.aborted) {
+          return;
+        }
+      }
+    }
+  }
+
+  private reportError(error: unknown, restarts: number): void {
+    if (this.restart.onError) {
+      observeDiagnostic(() => this.restart.onError!(error, restarts), this.constructor.name);
+    } else {
+      logBackgroundError(this.constructor.name, error);
+    }
+  }
+}
+
+export interface PeriodicBackgroundServiceOptions extends BackgroundServiceOptions {
+  /** Pause between ticks. */
+  readonly intervalMs: number;
+  /** Run a tick immediately on start (otherwise wait one interval). Default: true. */
+  readonly runImmediately?: boolean;
+}
+
+/**
+ * Base class for "do X every N ms" tasks. Override {@link tick}; the loop runs
+ * it on an interval until shutdown, **without overlap** (each tick is awaited
+ * before the next pause). A failing tick is reported via {@link onTickError}
+ * and the loop continues (one bad run does not kill the schedule).
+ */
+export abstract class PeriodicBackgroundService extends BackgroundService {
+  private readonly intervalMs: number;
+  private readonly runImmediately: boolean;
+
+  public constructor(options?: PeriodicBackgroundServiceOptions) {
+    super(options);
+    const resolved = { ...backgroundOptionsOf(this.constructor), ...options };
+    if (
+      typeof resolved.intervalMs !== "number"
+      || !Number.isFinite(resolved.intervalMs)
+      || resolved.intervalMs <= 0
+    ) {
+      throw new Error(
+        `${this.constructor.name}: intervalMs must be a finite positive number — set it via @Background({ intervalMs }) or super({ intervalMs }).`,
+      );
+    }
+    this.intervalMs = resolved.intervalMs;
+    this.runImmediately = resolved.runImmediately ?? true;
+  }
+
+  /** A single scheduled run. */
+  protected abstract tick(signal: AbortSignal): void | Promise<void>;
+
+  /** Hook for tick failures; default logs. The loop continues regardless. */
+  protected onTickError(error: unknown): void {
+    logBackgroundError(this.constructor.name, error);
+  }
+
+  protected override async execute(signal: AbortSignal): Promise<void> {
+    if (!this.runImmediately) {
+      await delay(this.intervalMs, signal);
+    }
+    while (!signal.aborted) {
+      try {
+        await this.tick(signal);
+      } catch (error) {
+        if (signal.aborted) {
+          return;
+        }
+        observeDiagnostic(() => this.onTickError(error), this.constructor.name);
+      }
+      if (signal.aborted) {
+        return;
+      }
+      await delay(this.intervalMs, signal);
+    }
+  }
+}
+
+/** Diagnostics are best-effort; even an accidentally async observer cannot own the loop. */
+function observeDiagnostic(callback: () => unknown, name: string): void {
+  try {
+    void Promise.resolve(callback()).catch((error: unknown) => logBackgroundError(name, error));
+  } catch (error) {
+    logBackgroundError(name, error);
+  }
+}
+
+function logBackgroundError(name: string, error: unknown): void {
+  try { console.error(`[background:${name}]`, redactSensitive(error)); }
+  catch { /* A broken diagnostic sink must not terminate the workload supervisor. */ }
+}
+
+async function waitWithTimeout(promise: Promise<void>, timeoutMs: number, name: string): Promise<void> {
+  const guarded = promise.catch(() => undefined);
+  if (timeoutMs <= 0) {
+    await guarded;
+    return;
+  }
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<void>((resolve) => {
+    timer = setTimeout(() => {
+      console.warn(`[background:${name}] did not stop within ${timeoutMs}ms; continuing shutdown`);
+      resolve();
+    }, timeoutMs);
+  });
+  try {
+    await Promise.race([guarded, timeout]);
+  } finally {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+  }
+}

package/core/background/backgroundModule.ts

@@ -0,0 +1,42 @@
+import {
+  DI,
+  HOSTED_SERVICE,
+  Module,
+  singleton,
+  type Class,
+  type HostedService,
+  type BazisModule,
+  type ProviderDefinition,
+} from "../di";
+
+export interface BackgroundModuleConfig {
+  /**
+   * Background service classes (subclasses of `BackgroundService` /
+   * `PeriodicBackgroundService`). Each is registered as a singleton (with
+   * auto-resolved constructor dependencies) and exposed as a `HOSTED_SERVICE`,
+   * so the kernel starts and gracefully stops it with the rest of the app.
+   */
+  readonly services: readonly Class<HostedService>[];
+}
+
+/**
+ * Registers background services in DI and wires them into the kernel lifecycle.
+ *
+ * ```ts
+ * @Module({ imports: [backgroundModule({ services: [SessionCleanup, Heartbeat] })] })
+ * class AppModule {}
+ * ```
+ */
+export function backgroundModule(config: BackgroundModuleConfig): BazisModule {
+  const providers: ProviderDefinition[] = config.services.flatMap((ServiceClass) => [
+    singleton(ServiceClass),
+    DI.singleton(
+      DI.factoryProviderWithResolver(HOSTED_SERVICE, [], (resolver) => resolver.resolve(ServiceClass)),
+    ),
+  ]);
+
+  @Module({ providers })
+  class BackgroundModule {}
+
+  return BackgroundModule;
+}

package/core/background/decorator.ts

@@ -0,0 +1,43 @@
+import type { BackgroundServiceOptions, PeriodicBackgroundServiceOptions } from "./BackgroundService";
+
+// Bun runs TC39 decorators natively, but Symbol.metadata may be absent in the
+// runtime — the same one-line polyfill used by the http/validation modules.
+(Symbol as { metadata?: symbol }).metadata ??= Symbol.for("Symbol.metadata");
+
+const BG_META = Symbol.for("bazis:background:options");
+
+/** Options accepted by {@link Background}; a superset covering periodic tasks. */
+export type BackgroundDecoratorOptions = BackgroundServiceOptions &
+  Partial<Pick<PeriodicBackgroundServiceOptions, "intervalMs" | "runImmediately">>;
+
+interface BackgroundMetadataCarrier {
+  [BG_META]?: BackgroundDecoratorOptions;
+}
+
+/**
+ * Declares background-service options on the class, so subclasses of
+ * `BackgroundService` / `PeriodicBackgroundService` need no `super({...})`:
+ *
+ * ```ts
+ * @Background({ intervalMs: 15_000, restart: { maxRestarts: 3 } })
+ * class Heartbeat extends PeriodicBackgroundService {
+ *   protected async tick() { await this.api.post("/heartbeat"); }
+ * }
+ * ```
+ *
+ * Options passed explicitly to `super(...)` take precedence over the decorator.
+ * Registration stays explicit — list the class in `backgroundModule({ services })`.
+ */
+export function Background(options: BackgroundDecoratorOptions = {}) {
+  return (_value: abstract new (...args: never[]) => unknown, context: ClassDecoratorContext): void => {
+    (context.metadata as BackgroundMetadataCarrier)[BG_META] = options;
+  };
+}
+
+/** Reads {@link Background} options off a class (undefined if not decorated). */
+export function backgroundOptionsOf(ctor: object): BackgroundDecoratorOptions | undefined {
+  const metadata = (ctor as { [key: symbol]: unknown })[Symbol.metadata as unknown as symbol] as
+    | BackgroundMetadataCarrier
+    | undefined;
+  return metadata?.[BG_META];
+}

package/core/background/delay.ts

@@ -0,0 +1,27 @@
+/**
+ * Cancellable pause. Resolves after `ms` **or** as soon as `signal` aborts —
+ * it never rejects, so loops just re-check `signal.aborted` after awaiting:
+ *
+ * ```ts
+ * while (!signal.aborted) {
+ *   await work();
+ *   await delay(1000, signal);
+ * }
+ * ```
+ */
+export function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted || ms <= 0) {
+    return Promise.resolve();
+  }
+  return new Promise<void>((resolve) => {
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/core/background/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Background services: long-running and periodic in-process workers integrated
+ * with the kernel lifecycle (non-blocking start, cooperative cancellation,
+ * graceful stop, optional restart-on-crash).
+ */
+export {
+  BackgroundService,
+  PeriodicBackgroundService,
+  type BackgroundRestartPolicy,
+  type BackgroundServiceOptions,
+  type PeriodicBackgroundServiceOptions,
+} from "./BackgroundService";
+export { backgroundModule, type BackgroundModuleConfig } from "./backgroundModule";
+export { Background, backgroundOptionsOf, type BackgroundDecoratorOptions } from "./decorator";
+export { delay } from "./delay";

package/core/cache/COMPATIBILITY.md

@@ -0,0 +1,13 @@
+# Cache Compatibility
+
+The aliases below were removed in 0.96.1, before the first `bazis` npm release,
+so no published version ever contained them. Use the replacement.
+
+| Removed name | Kind | Replacement |
+| --- | --- | --- |
+| `autoCachedScoped` | public alias | `cachedScoped` |
+| `autoCachedSingleton` | public alias | `cachedSingleton` |
+| `warnInsecureOutputCacheRoute` | public alias | `guardInsecureOutputCacheRoute` |
+| `warnOnAuthorizedRoutesWithoutVaryByUser` | config switch | `insecureAuthorizedRouteBehavior` (`false` was `"ignore"`) |
+| `DEFAULT_CACHEABLE_METHODS` | internal alias | `DEFAULT_OUTPUT_CACHE_METHODS` |
+| `DEFAULT_CACHEABLE_STATUS_CODES` | internal alias | `DEFAULT_OUTPUT_CACHE_STATUS_CODES` |

package/core/cache/ICache.ts

@@ -0,0 +1,71 @@
+import { createToken, type InjectionToken } from "../di";
+import type { CacheEntry } from "./types/CacheEntry";
+import type { CacheSetOptions } from "./types/CacheOptions";
+
+/** Factory for {@link ICache.getOrCreate} / {@link ICache.getOrCreateAsync}. */
+export type CacheFactory<TValue> = () => TValue | Promise<TValue | undefined> | undefined;
+
+/**
+ * Key-value cache contract.
+ *
+ * Implementations must:
+ * - validate keys (a non-empty string, no `__proto__` and the like);
+ * - return a cache miss when there is no value; never hide input or factory errors;
+ * - treat expired entries as absent when a TTL is set.
+ */
+export interface ICache<TValue = unknown> {
+  /** Reads one entry; `undefined` if missing or its TTL expired. */
+  get(key: string): TValue | undefined;
+
+  /** Snapshot of all current entries (expired ones excluded). */
+  list(): readonly CacheEntry<TValue>[];
+
+  /** Writes a value; evicts the LRU entry when full. */
+  set(key: string, value: TValue, options?: CacheSetOptions): void;
+
+  /**
+   * Returns the cached value or creates it through `factory`.
+   * `undefined` from the factory is not stored.
+   * MemoryCache throws CacheCapacityError before starting a new factory once
+   * maxInFlight is reached; cache hits and joining running work are allowed.
+   */
+  getOrCreate(
+    key: string,
+    factory: CacheFactory<TValue>,
+    options?: CacheSetOptions,
+  ): TValue | Promise<TValue | undefined> | undefined;
+
+  /**
+   * Async version with per-key in-flight request dedup (anti-stampede).
+   * `undefined` from the factory is not stored.
+   * Input and admission checks may throw synchronously before a Promise is returned.
+   */
+  getOrCreateAsync(
+    key: string,
+    factory: () => Promise<TValue | undefined>,
+    options?: CacheSetOptions,
+  ): Promise<TValue | undefined>;
+
+  /** Removes one entry; `true` if the entry existed. */
+  remove(key: string): boolean;
+
+  /** Removes all entries. */
+  clear(): void;
+
+  /**
+   * Removes all entries with the given tag.
+   * @returns the number of removed entries.
+   */
+  evictByTag(tag: string): number;
+
+  /** Number of current entries (after lazy TTL cleanup). */
+  readonly size: number;
+}
+
+/** Default cache DI token. */
+export const ICache = createToken<ICache>("ICache") as InjectionToken<ICache<unknown>>;
+
+/** Typed token for a specific value type. */
+export function cacheToken<TValue>(name: string): InjectionToken<ICache<TValue>> {
+  return createToken<ICache<TValue>>(`ICache<${name}>`);
+}