@zerotal/core 1.0.0

package/src/errors/ContainerErrors.ts

@@ -0,0 +1,143 @@
+/**
+ * Errors raised by the IoC container — unknown bindings, scope-lifetime misuse,
+ * synchronous resolution of async bindings, circular dependencies, and facades
+ * touched before the container is ready.
+ */
+import { ZerotalError } from "./ZerotalError.ts";
+
+/** Raised when resolving a token that no provider has registered. */
+export class BindingNotFoundError extends ZerotalError {
+  constructor(token: string) {
+    super(
+      `No binding registered for token: "${token}". Register it in a ServiceProvider's onRegister() method.`,
+      "E_BINDING_NOT_FOUND",
+      500,
+      { token },
+    );
+  }
+}
+
+/** Raised when a request-scoped binding is resolved with no request in scope. */
+export class ScopedOutsideRequestError extends ZerotalError {
+  constructor(message: string) {
+    super(message, "E_SCOPED_OUTSIDE_REQUEST", 500);
+  }
+}
+
+/** Raised when a request-scoped binding is resolved after the scope was flushed. */
+export class ScopedAfterFlushError extends ZerotalError {
+  constructor(message: string) {
+    super(message, "E_SCOPED_AFTER_FLUSH", 500);
+  }
+}
+
+/** Raised when an async-only binding is resolved through the synchronous API. */
+export class SyncResolutionError extends ZerotalError {
+  constructor(message: string) {
+    super(message, "E_SYNC_RESOLUTION", 500);
+  }
+}
+
+/**
+ * Raised when application code tries to register a binding through the `App`
+ * facade after `Application.boot()` has completed.
+ *
+ * The container is process-global and shared across every concurrent request,
+ * so mutating it at request time would leak state between requests. Register
+ * bindings at boot — in the bootstrap `App.bind()` callback, a `ServiceProvider`,
+ * the `app/services` convention, or top-of-module code — and use a `scoped`
+ * binding for anything that must be per-request.
+ */
+export class ContainerLockedError extends ZerotalError {
+  constructor(method: string) {
+    super(
+      [
+        `App.${method}() was called after the application finished booting.`,
+        ``,
+        `The container is locked once boot() completes: it is shared across every`,
+        `concurrent request, so registering a binding now would leak state between`,
+        `requests. Register bindings during boot instead:`,
+        ``,
+        `  • the bootstrap App.bind((c) => { ... }) callback`,
+        `  • a ServiceProvider's onRegister()`,
+        `  • the app/services convention (static lifetime = "singleton")`,
+        ``,
+        `Need per-request state? Register a scoped binding at boot — it resolves a`,
+        `fresh instance for each request without mutating the global container.`,
+      ].join("\n"),
+      "E_CONTAINER_LOCKED",
+      500,
+      { method },
+    );
+  }
+}
+
+/**
+ * Raised when bindings depend on each other in a cycle.
+ *
+ * @param chain - The resolution path that closed the loop, in order.
+ */
+export class CircularDependencyError extends ZerotalError {
+  constructor(chain: string[]) {
+    super(`Circular dependency detected: ${chain.join(" → ")}`, "E_CIRCULAR_DEPENDENCY", 500, {
+      chain,
+    });
+  }
+}
+
+/**
+ * Raised when a facade is used before `Application.boot()` has wired the
+ * container — typically from module-level code that runs on import.
+ */
+export class FacadeAccessedBeforeBootError extends ZerotalError {
+  constructor(facadeKey: string) {
+    super(
+      [
+        `You attempted to use the "${facadeKey}" facade before the container was ready.`,
+        ``,
+        `Facades are resolved from the IoC container, which is only available after`,
+        `Application.boot() completes. Using a facade at module scope (top-level code`,
+        `that runs on import) is not safe because the app may not have booted yet.`,
+        ``,
+        `Common causes:`,
+        `  • A top-level variable initialised with a Facade call:`,
+        `      const name = Config.get('app.name')  // ← runs before boot`,
+        `  • Module-level code outside of any function or class`,
+        ``,
+        `Fix: move Facade usage inside a function, controller method, or service`,
+        `provider hook (onRegister / onBooting / onBooted) where the container is`,
+        `guaranteed to be ready.`,
+      ].join("\n"),
+      "E_FACADE_BEFORE_BOOT",
+      500,
+      { facade: facadeKey },
+    );
+  }
+}
+
+/**
+ * Thrown when a facade is used after the app has booted but nothing provides its
+ * binding — almost always a missing ServiceProvider in `bootstrap/providers.ts`.
+ */
+export class FacadeBindingMissingError extends ZerotalError {
+  constructor(facadeKey: string) {
+    super(
+      [
+        `Could not resolve the "${facadeKey}" facade.`,
+        ``,
+        `The application has booted, but nothing provides the "${facadeKey}" binding —`,
+        `usually because the ServiceProvider that registers it isn't in your providers`,
+        `list (and occasionally because the binding hasn't been pre-resolved yet).`,
+        ``,
+        `Fix: register the provider in bootstrap/providers.ts. For example, the "log"`,
+        `facade is provided by LogProvider:`,
+        ``,
+        `      import { LogProvider } from "@zerotal/core/logger";`,
+        `      export default [/* …your providers… */, LogProvider];`,
+      ].join("\n"),
+      "E_FACADE_BINDING_MISSING",
+      500,
+      { facade: facadeKey },
+    );
+  }
+}

package/src/errors/HttpError.ts

@@ -0,0 +1,127 @@
+/**
+ * The HTTP error hierarchy. `HttpError` carries a status and optional response
+ * headers; the named subclasses below are convenience constructors for the
+ * common status codes, each with a default message and a stable error code.
+ */
+import { ZerotalError } from "./ZerotalError.ts";
+
+/**
+ * An error that maps directly onto an HTTP response.
+ *
+ * @param code - Defaults to `E_HTTP_<status>` when omitted.
+ * @param headers - Response headers to merge in (e.g. `Allow`, `Retry-After`).
+ */
+export class HttpError extends ZerotalError {
+  headers?: Record<string, string>;
+
+  constructor(message: string, status: number, code?: string, headers?: Record<string, string>) {
+    super(message, code ?? `E_HTTP_${status}`, status);
+    if (headers) this.headers = headers;
+  }
+}
+
+/** 400 Bad Request — the request was malformed or failed basic validation. */
+export class BadRequestError extends HttpError {
+  constructor(message = "Bad Request") {
+    super(message, 400, "E_BAD_REQUEST");
+  }
+}
+/** 401 Unauthorized — authentication is required and has failed or is missing. */
+export class UnauthorizedError extends HttpError {
+  constructor(message = "Unauthorized") {
+    super(message, 401, "E_UNAUTHORIZED");
+  }
+}
+/** 403 Forbidden — authenticated, but not allowed to perform this action. */
+export class ForbiddenError extends HttpError {
+  constructor(message = "Forbidden") {
+    super(message, 403, "E_FORBIDDEN");
+  }
+}
+/** 404 Not Found — no resource matches the request. */
+export class NotFoundError extends HttpError {
+  constructor(message = "Not Found") {
+    super(message, 404, "E_NOT_FOUND");
+  }
+}
+/**
+ * 405 Method Not Allowed — the route exists but not for this HTTP method.
+ *
+ * @param allowed - Methods the route does accept; populates the `Allow` header.
+ */
+export class MethodNotAllowedError extends HttpError {
+  constructor(allowed: string[] = [], message = "Method Not Allowed") {
+    super(
+      message,
+      405,
+      "E_METHOD_NOT_ALLOWED",
+      allowed.length ? { Allow: allowed.join(", ") } : undefined,
+    );
+  }
+}
+/** 409 Conflict — the request conflicts with the current state of the resource. */
+export class ConflictError extends HttpError {
+  constructor(message = "Conflict") {
+    super(message, 409, "E_CONFLICT");
+  }
+}
+/** 410 Gone — the resource existed once but has been permanently removed. */
+export class GoneError extends HttpError {
+  constructor(message = "Gone") {
+    super(message, 410, "E_GONE");
+  }
+}
+/** 422 Unprocessable Entity — well-formed but semantically invalid request. */
+export class UnprocessableEntityError extends HttpError {
+  constructor(message = "Unprocessable Entity") {
+    super(message, 422, "E_UNPROCESSABLE_ENTITY");
+  }
+}
+/**
+ * 429 Too Many Requests — the client has exceeded a rate limit.
+ *
+ * @param retryAfter - Seconds to wait before retrying; populates `Retry-After`.
+ */
+export class TooManyRequestsError extends HttpError {
+  readonly retryAfter?: number | undefined;
+  constructor(retryAfter?: number, message = "Too Many Requests") {
+    super(
+      message,
+      429,
+      "E_TOO_MANY_REQUESTS",
+      retryAfter !== undefined ? { "Retry-After": String(retryAfter) } : undefined,
+    );
+    this.retryAfter = retryAfter;
+  }
+}
+/**
+ * 503 Service Unavailable — the server is temporarily unable to handle the request.
+ *
+ * @param reason - Appended to the message for context (e.g. "database down").
+ * @param retryAfter - Seconds to wait before retrying; populates `Retry-After`.
+ */
+export class ServiceUnavailableError extends HttpError {
+  readonly retryAfter?: number | undefined;
+  constructor(reason?: string, retryAfter?: number) {
+    super(
+      reason ? `Service Unavailable: ${reason}` : "Service Unavailable",
+      503,
+      "E_SERVICE_UNAVAILABLE",
+      retryAfter !== undefined ? { "Retry-After": String(retryAfter) } : undefined,
+    );
+    this.retryAfter = retryAfter;
+  }
+}
+/**
+ * 500 — `RequestContext` was accessed with no active HTTP request in scope
+ * (e.g. from module-level code or a background task).
+ */
+export class ContextOutsideRequestError extends HttpError {
+  constructor() {
+    super(
+      "Attempted to access RequestContext outside of an active HTTP request lifecycle.",
+      500,
+      "E_CONTEXT_OUTSIDE_REQUEST",
+    );
+  }
+}

package/src/errors/ValidationError.ts

@@ -0,0 +1,19 @@
+/**
+ * The error raised when request input fails validation. Carries the per-field
+ * messages so the handler can render them back to the client (422).
+ */
+import { HttpError } from "./HttpError.ts";
+
+/**
+ * Raised when input validation fails.
+ *
+ * @param errors - Field name → list of messages for that field.
+ */
+export class ValidationError extends HttpError {
+  constructor(
+    message: string,
+    public readonly errors: Record<string, string[]>,
+  ) {
+    super(message, 422, "E_VALIDATION_FAILED");
+  }
+}

package/src/errors/ZerotalError.ts

@@ -0,0 +1,25 @@
+/**
+ * The base error type for the framework. Every error Zerotal throws extends this,
+ * carrying a machine-readable `code`, an HTTP `status`, and optional structured
+ * `context` so handlers can render and log it consistently.
+ */
+
+/**
+ * Base class for all framework errors.
+ *
+ * @param code - Stable machine-readable identifier (e.g. `E_BINDING_NOT_FOUND`),
+ *   safe to switch on; unlike the message, it is not meant to change.
+ * @param status - HTTP status to respond with when this error reaches the handler.
+ * @param context - Structured detail attached to logs and error pages.
+ */
+export class ZerotalError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly status: number = 500,
+    public readonly context?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Public barrel for the framework's error types (the `@zerotal/core/errors`
+ * subpath) — the base {@link ZerotalError}, the {@link HttpError} hierarchy of
+ * status-coded convenience classes, and the validation/config/container errors.
+ * Every error carries a stable machine-readable `code` and an HTTP `status`.
+ *
+ * @example
+ * ```ts
+ * import { NotFoundError, ValidationError } from "@zerotal/core/errors";
+ *
+ * throw new NotFoundError("User not found");
+ * throw new ValidationError("Invalid input", { email: ["is required"] });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { ZerotalError } from "./ZerotalError.ts";
+export {
+  HttpError,
+  BadRequestError,
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+  MethodNotAllowedError,
+  ConflictError,
+  GoneError,
+  UnprocessableEntityError,
+  TooManyRequestsError,
+  ServiceUnavailableError,
+  ContextOutsideRequestError,
+} from "./HttpError.ts";
+export { ValidationError } from "./ValidationError.ts";
+export { ConfigError } from "./ConfigError.ts";
+export { BootCheckError } from "../application/BootDoctor.ts";
+export type { BootCheckFailure } from "../application/BootDoctor.ts";
+export { ConfigValidationError } from "../config/validation.ts";
+export {
+  BindingNotFoundError,
+  ScopedOutsideRequestError,
+  ScopedAfterFlushError,
+  SyncResolutionError,
+  CircularDependencyError,
+  FacadeAccessedBeforeBootError,
+  FacadeBindingMissingError,
+  ContainerLockedError,
+} from "./ContainerErrors.ts";

package/src/events/CallQueuedListener.ts

@@ -0,0 +1,66 @@
+/**
+ * A serialisable wrapper that lets an event listener be deferred to a queue:
+ * it captures the listener name and event payload, can round-trip through a
+ * plain object, and re-dispatches the listener when the worker runs it.
+ */
+import { currentApp } from "../application/currentApp.ts";
+
+/** A queued event listener, carrying everything the worker needs to run it later. */
+export class CallQueuedListener {
+  readonly queue: string;
+  readonly maxAttempts: number;
+  readonly retryDelay: number;
+
+  constructor(
+    public readonly listenerName: string,
+    public readonly eventName: string,
+    public readonly eventPayload: any,
+    queueName: string | boolean = "default",
+    maxAttempts = 3,
+    retryDelay = 1000,
+  ) {
+    this.queue = typeof queueName === "string" ? queueName : "default";
+    this.maxAttempts = maxAttempts;
+    this.retryDelay = retryDelay;
+  }
+
+  /** Serialise this listener to a plain object for storage on the queue. */
+  payload(): Record<string, unknown> {
+    return {
+      listenerName: this.listenerName,
+      eventName: this.eventName,
+      eventPayload: this.eventPayload,
+      queue: this.queue,
+      maxAttempts: this.maxAttempts,
+      retryDelay: this.retryDelay,
+    };
+  }
+
+  /** The job class name the queue uses to route this listener back to {@link fromPayload}. */
+  get className(): string {
+    return "CallQueuedListener";
+  }
+
+  /** Reconstruct a queued listener from the plain object produced by {@link payload}. */
+  static fromPayload(payload: Record<string, unknown>) {
+    return new CallQueuedListener(
+      payload.listenerName as string,
+      payload.eventName as string,
+      payload.eventPayload,
+      payload.queue as string,
+      payload.maxAttempts as number,
+      payload.retryDelay as number,
+    );
+  }
+
+  /** Run the wrapped listener through the live emitter. No-op if no emitter is bound. */
+  async handle(): Promise<void> {
+    const application = currentApp();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the events binding has no cross-package type here; the dispatch method is checked at the call site.
+    const emitter = application.container.tryMake("events") as any;
+    if (!emitter) return;
+
+    // Emitter needs to expose a way to execute a listener by name with a raw payload
+    await emitter.dispatchQueuedListener(this.listenerName, this.eventPayload);
+  }
+}