@btravstack/core 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,458 @@
+import { AsyncResult, Result } from "unthrown";
+import { AnyPort, Context, Module, PortClass, Scope, ServiceOf } from "@btravstack/di";
+import { Env, Environment } from "@btravstack/config";
+//#region src/clock.d.ts
+type Clock = {
+  readonly now: () => number;
+  readonly sleep: (ms: number, signal?: AbortSignal) => AsyncResult<void, never>;
+};
+declare const systemClock: Clock;
+//#endregion
+//#region src/units.d.ts
+/**
+ * What the kernel opens per unit and `currentUnit()` reads: a small, fixed
+ * record of **data about this unit**, and never a service.
+ *
+ * `signal` is the same `AbortSignal` the work callback receives — aborted at
+ * the drain deadline, or at once on a path that skips the drain. It is here
+ * because the callback is not always where the work is: a middleware-shaped
+ * runtime opens the unit around a call whose arguments it does not own. A
+ * transport's own cancellation is a different clock, not this one.
+ */
+type UnitRecord = {
+  readonly unitId: string;
+  readonly traceId: string;
+  readonly tenantId: string | undefined;
+  readonly deadline: number | undefined;
+  readonly signal: AbortSignal;
+};
+declare const currentUnit: () => UnitRecord | undefined;
+/**
+ * What a runtime says about one piece of work as it submits it. `kind` is the
+ * category (`"http"`, `"tick"`, `"job"`); `id` identifies **this** unit.
+ *
+ * @remarks
+ * **`id` must be unique per unit unless a `traceId` is supplied**, because
+ * `traceId` defaults to it. A runtime passing a CATEGORY as the id — a route
+ * template such as `"POST /orders"` — gives every request the same trace id and
+ * silently defeats the ambient record. A route template is a `kind`.
+ *
+ * The kernel cannot check this, so uniqueness is the runtime's to guarantee.
+ * What it does guarantee is {@link UnitRecord}'s `unitId`, minted per unit;
+ * `traceId` is the CORRELATION id, which is why it is the one a runtime may
+ * supply — it carries an id from outside the process.
+ */
+type UnitMeta = {
+  readonly kind: string;
+  readonly id: string;
+  readonly traceId?: string;
+  readonly tenantId?: string;
+  readonly deadline?: number;
+};
+type UnitWork<T, E> = (signal: AbortSignal) => AsyncResult<T, E> | Promise<Result<T, E>> | Result<T, E>;
+type UnitRegistry = {
+  readonly run: <T, E>(meta: UnitMeta, work: UnitWork<T, E>) => AsyncResult<T, E>;
+  readonly inFlight: () => number;
+  readonly closed: () => number;
+  readonly abortAll: () => void;
+  readonly awaitIdle: () => AsyncResult<void, never>;
+};
+//#endregion
+//#region src/runtime.d.ts
+declare const RuntimeStartFailed_base: import("unthrown").TaggedErrorConstructor<"RuntimeStartFailed">;
+declare class RuntimeStartFailed extends RuntimeStartFailed_base<{
+  readonly runtime: string;
+  readonly cause: unknown;
+}> {
+  message: string;
+}
+/**
+ * Submit one piece of work as a **unit**: the kernel counts it towards the
+ * drain, hands it an `AbortSignal` and an ambient record, and gives the work's
+ * own `Result` straight back — mapping that outcome to a transport is the
+ * runtime's job, never the kernel's.
+ *
+ * @remarks
+ * **Everything the client must receive has to be flushed INSIDE `work`, never
+ * after the returned `AsyncResult` settles.** A unit closes the instant its
+ * `Result` settles, and an idle registry is the drain's permission to call
+ * `Serving.stop()` — so a runtime that writes after resolving is racing the
+ * transport being torn down.
+ *
+ * `UnitMeta.id` must be unique per unit unless a `traceId` is supplied — see
+ * {@link UnitMeta}.
+ *
+ * With a `StartOptions.unit` module in play, `work` runs only once the fork is
+ * built. A runtime that subscribes to an event from inside `work` must first
+ * check whether it has already fired.
+ */
+type RunUnit<Resolves extends AnyPort> = <T, E>(meta: UnitMeta, work: (ctx: Context<InstanceType<Resolves>>, signal: AbortSignal) => ReturnType<UnitWork<T, E>>) => AsyncResult<T, E>;
+/**
+ * What a runtime is handed at `start`: the application services **and** the
+ * kernel's {@link RunUnit}. Handing it a bare `Context` would leave every
+ * runtime inventing its own unit tracking — the thing the kernel exists to own.
+ *
+ * @remarks
+ * The two contracts a runtime author owes, neither checkable by the kernel: a
+ * unit's response must be flushed **inside** the work callback (see
+ * {@link RunUnit}), and `UnitMeta.id` must be unique per unit unless a
+ * `traceId` is supplied (see {@link UnitMeta}).
+ *
+ * `ctx` is the **application** context: a port a `StartOptions.unit` module
+ * provides exists only while a unit is open, so a runtime naming it in
+ * `resolves` is rejected at `start`'s call site.
+ */
+type RuntimeHost<Resolves extends AnyPort> = {
+  readonly ctx: Context<InstanceType<Resolves>>;
+  readonly run: RunUnit<Resolves>;
+};
+/**
+ * What a runtime is, once it is up — plus, optionally, what it wants to say
+ * about itself, read back through `RunningApp.runtimeInfo()`.
+ *
+ * `Info` is the runtime's own shape rather than a port number: a queue consumer
+ * has no port and might publish `{ queue, prefetch }`. It defaults to `never`,
+ * so `info` is unwritable for a runtime with nothing to publish.
+ */
+type Serving<Info = never> = {
+  readonly drain: (signal: AbortSignal) => AsyncResult<void, never>;
+  readonly stop: () => AsyncResult<void, never>;
+  readonly info?: Info;
+};
+type Runtime<Resolves extends AnyPort = never, Info = never> = {
+  readonly name: string;
+  readonly resolves: readonly Resolves[];
+  readonly start: (host: RuntimeHost<Resolves>) => AsyncResult<Serving<Info>, RuntimeStartFailed>;
+};
+/**
+ * The port the kernel resolves its runtime from. A runtime is a **service the
+ * module provides**, not an option handed to `start`: a runtime package
+ * declares its own port over this one — `class HttpRuntime extends
+ * RuntimePort<Runtime<never, HttpInfo>> {}` — so it is built by di like
+ * everything else, and the kernel owns nothing but the lifecycle.
+ *
+ * Left generic on purpose: every runtime port is one id at runtime, since a
+ * process boots exactly one, while each carries its own `Resolves`/`Info` in
+ * the type.
+ */
+declare const RuntimePort: PortClass<"Runtime">;
+/** The instance type every runtime port shares — `Extract` this from a module's exports to find its runtime. */
+type RuntimeInstance = InstanceType<PortClass<"Runtime">>;
+/** The `Runtime<Resolves, Info>` a module exports, or `never` when it exports none. */
+type RuntimeOf<X> = ServiceOf<Extract<X, RuntimeInstance>>;
+type RuntimeResolvesOf<X> = RuntimeOf<X> extends Runtime<infer Resolves, unknown> ? Resolves : never;
+type RuntimeInfoOf<X> = RuntimeOf<X> extends Runtime<AnyPort, infer Info> ? Info : never;
+/**
+ * `running`, but no later than the kernel's drain deadline — the primitive a
+ * `Serving.drain` needs when the work it awaits settles on somebody else's
+ * clock (Temporal's `shutdownForceTime`, a broker library's close) and so
+ * cannot honour `signal` itself.
+ *
+ * **The losing branch's `Result` is dropped**, which is the point rather than
+ * an oversight: once the deadline wins, the kernel has already moved on and
+ * the eventual outcome has no consumer left. What that costs is the runtime's
+ * own business — an un-acked AMQP delivery is redelivered, so abandoning one
+ * repeats work rather than losing it, while a Temporal activity is retried on
+ * another worker.
+ *
+ * Deliberately **`Clock`-agnostic**: there is no duration here, only a signal,
+ * so it behaves identically under `@btravstack/testing`'s fake clock. Racing
+ * work against a *timeout* is a different primitive and belongs on `Clock`
+ * (`drain.ts` uses `clock.sleep` for exactly that, so a fake clock can control
+ * it) — do not fold the two together.
+ */
+declare const releasedBy: (signal: AbortSignal, running: AsyncResult<void, never>) => AsyncResult<void, never>;
+//#endregion
+//#region src/drain.d.ts
+type DrainReport = {
+  /** Units in flight when the drain began. */
+  readonly inFlightAtStart: number;
+  /**
+   * Units that closed during the drain, counted from a monotonic total. It may
+   * exceed `inFlightAtStart` when in-flight work spawned more units — honest
+   * reporting, where `inFlightAtStart - abandoned` can go negative.
+   */
+  readonly completed: number;
+  /** Units still open at the deadline. The exit-code decision reads this. */
+  readonly abandoned: number;
+};
+//#endregion
+//#region src/events.d.ts
+type KernelEvent = {
+  readonly type: "building";
+} | {
+  readonly type: "startFailed";
+  readonly cause: unknown;
+} | {
+  readonly type: "serving";
+  readonly runtime: string;
+  /**
+   * Whatever the runtime published on `Serving.info`. `unknown` because the
+   * kernel does not know a runtime's `Info` at the event union — it is read
+   * off the module at `start`'s call site, not here — and a sink is
+   * serialising it anyway. A generic `KernelEvent<Info>` would infect
+   * `EventSink`, `stderrSink` and every adapter for one field none of them
+   * reads structurally.
+   */
+  readonly info: unknown;
+  /**
+   * The port the kernel's own probe listener bound, `undefined` when probes
+   * are off. Its own field rather than folded into `info`: the probe server
+   * is the kernel's, not the runtime's, so publishing it as something the
+   * runtime said would be a small lie.
+   */
+  readonly probePort: number | undefined;
+} | {
+  readonly type: "draining";
+  readonly inFlight: number;
+} | {
+  readonly type: "drained";
+  readonly report: DrainReport;
+} | {
+  readonly type: "stopping";
+} | {
+  readonly type: "exited";
+} | {
+  readonly type: "teardownError";
+  readonly port: string;
+  readonly cause: unknown;
+} | {
+  readonly type: "uncaught";
+  readonly cause: unknown;
+};
+type EventSink = (event: KernelEvent) => void;
+declare const stderrSink: EventSink;
+//#endregion
+//#region src/observability.d.ts
+/**
+ * The severity of one line, and the whole of the set: six levels, ordered, with
+ * no caller-defined additions — which is what lets `LOG_LEVEL` be validated at
+ * startup and `isEnabled` be a comparison rather than a lookup.
+ */
+type Level = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+/** The levels in order, least severe first — what `isEnabled` compares through. */
+declare const LEVELS: readonly Level[];
+/**
+ * What a line, a span or a measurement carries besides itself: a flat record of
+ * scalars.
+ *
+ * Flat and scalar on purpose. A nested object is where a field's name stops
+ * being stable, and an `unknown` value is where a logger starts stringifying
+ * whatever it is handed — which is how a log call becomes the thing that
+ * throws. A failure has a channel of its own, `cause`.
+ */
+type Attributes = Readonly<Record<string, string | number | boolean | undefined>>;
+/**
+ * Every method takes the same three arguments in the same order:
+ * `(message, attributes?, cause?)`.
+ *
+ * Uniform on purpose. A failure is not a property of severity — an `info` line
+ * reporting a recovered fault carries one too — so every level can take a
+ * `cause`, at the cost of `logger.error("boom", undefined, cause)` for a
+ * failure with nothing else to say.
+ */
+type LoggerService = {
+  readonly log: (level: Level, message: string, attributes?: Attributes, cause?: unknown) => void;
+  readonly trace: (message: string, attributes?: Attributes, cause?: unknown) => void;
+  readonly debug: (message: string, attributes?: Attributes, cause?: unknown) => void;
+  readonly info: (message: string, attributes?: Attributes, cause?: unknown) => void;
+  readonly warn: (message: string, attributes?: Attributes, cause?: unknown) => void;
+  /** `cause` is the failure itself — an `Error`, an `unthrown` `Err`'s error, a rejected value. */
+  readonly error: (message: string, attributes?: Attributes, cause?: unknown) => void;
+  readonly fatal: (message: string, attributes?: Attributes, cause?: unknown) => void;
+  /** A logger carrying `attributes` on every line it writes, on top of this one's. Never mutates this one. */
+  readonly with: (attributes: Attributes) => LoggerService;
+  /** Whether a line at `level` would be written — for a payload expensive enough to be worth not building. */
+  readonly isEnabled: (level: Level) => boolean;
+};
+declare const Logger_base: import("@btravstack/di").PortClass<"Logger">;
+/**
+ * The application's logger, as a port — declared here and implemented in
+ * `@btravstack/observability`, because a contract every package may depend on
+ * has to be reachable without installing an implementation, and because the
+ * correlation an implementation stamps per line is the kernel's own ambient
+ * record.
+ *
+ * An implementation must not throw: a logger that throws turns an observability
+ * problem into an outage. Synchronous `void`, not an `AsyncResult` — thesis 6's
+ * one deliberate exemption, since a lost line is not a modeled error.
+ */
+declare class Logger extends Logger_base<LoggerService> {}
+/** A span's outcome: unset until something says otherwise, then `ok` or `error`. */
+declare const SPAN_STATUS: {
+  readonly unset: 0;
+  readonly ok: 1;
+  readonly error: 2;
+};
+/** The three codes {@link SPAN_STATUS} names, as the type a {@link Span} takes. */
+type SpanStatusCode = (typeof SPAN_STATUS)[keyof typeof SPAN_STATUS];
+/**
+ * One span, narrowed to what a framework package does with it: label it, say
+ * how it ended, end it. The numbers are OpenTelemetry's own, so an OTel span
+ * satisfies this structurally with no translation in between.
+ */
+type Span = {
+  readonly setAttributes: (attributes: Attributes) => unknown;
+  readonly setStatus: (status: {
+    readonly code: SpanStatusCode;
+    readonly message?: string;
+  }) => unknown;
+  readonly end: () => void;
+};
+/** What a {@link Tracer} does: start a span, by name. */
+type TracerService = {
+  readonly startSpan: (name: string) => Span;
+};
+declare const Tracer_base: import("@btravstack/di").PortClass<"Tracer">;
+/**
+ * The application's tracer, as a port — declared without naming OpenTelemetry,
+ * because a port typed as a vendor's type points the dependency arrow outwards
+ * and makes the whole family install that vendor.
+ */
+declare class Tracer extends Tracer_base<TracerService> {}
+/** A monotonic count. */
+type Counter = {
+  readonly add: (value: number, attributes?: Attributes) => void;
+};
+/** A distribution of measurements. */
+type Histogram = {
+  readonly record: (value: number, attributes?: Attributes) => void;
+};
+/**
+ * What a {@link Meter} does: mint the two instruments a framework package needs
+ * — it counts what happened and measures how long it took. A gauge is something
+ * an application declares about its own domain, reaching the vendor's meter for
+ * it as it would any other adapter.
+ */
+type MeterService = {
+  readonly createCounter: (name: string, options?: {
+    readonly description?: string;
+    readonly unit?: string;
+  }) => Counter;
+  readonly createHistogram: (name: string, options?: {
+    readonly description?: string;
+    readonly unit?: string;
+  }) => Histogram;
+};
+declare const Meter_base: import("@btravstack/di").PortClass<"Meter">;
+/** The application's meter, as a port. See {@link Tracer} for why it does not name a vendor. */
+declare class Meter extends Meter_base<MeterService> {}
+//#endregion
+//#region src/phase.d.ts
+type Phase = "building" | "starting" | "serving" | "draining" | "stopping" | "exited";
+//#endregion
+//#region src/start.d.ts
+type TeardownError = {
+  readonly port: string;
+  readonly cause: unknown;
+};
+type ExitReport = {
+  readonly reason: "signal" | "runtimeStopped" | "uncaught";
+  readonly drain: DrainReport | undefined;
+  readonly teardownErrors: readonly TeardownError[];
+  readonly uptimeMs: number;
+};
+type StartOptions<UnitX = never, UnitNeeds = never> = {
+  /**
+   * The environment the graph is configured from, provided to it as the `Env`
+   * port and read for the kernel's own `PROBE_PORT`. Defaults to
+   * `process.env`.
+   */
+  readonly env?: Environment;
+  /**
+   * A module forked around **every unit**: built as the unit opens, torn down
+   * as it closes — while the unit's ambient record is still open — reading
+   * anything the application context carries.
+   *
+   * A failing unit finaliser is reported as a `teardownError` event and never
+   * in `ExitReport.teardownErrors`. With this option the unit's work runs only
+   * once the fork is built, so a runtime that subscribes to an event from
+   * inside its work must be ready for it to have already fired.
+   */
+  readonly unit?: Module<UnitX, never, UnitNeeds>;
+  readonly clock?: Clock;
+  readonly signals?: boolean;
+  /**
+   * The probe server's port. Unset, it is bound from `PROBE_PORT` in `env`
+   * (default `9000`); `false` disables the probe server.
+   */
+  readonly probes?: {
+    readonly port: number;
+  } | false;
+  readonly preDrainDelayMs?: number;
+  readonly drainTimeoutMs?: number;
+  readonly onEvent?: EventSink;
+};
+type RunningApp<E, Info = never> = {
+  readonly exited: AsyncResult<ExitReport, E | RuntimeStartFailed>;
+  readonly stop: () => void;
+  readonly requestDrain: () => void;
+  readonly phase: () => Phase;
+  /**
+   * The predicate `/readyz` answers from — serving, and not forced unready by
+   * a drain or an uncaught exception — read synchronously, which the probe
+   * endpoint is not.
+   */
+  readonly ready: () => boolean;
+  /**
+   * The port the probe server actually bound, once the bind attempt has
+   * settled; `undefined` when probes are disabled or the bind failed.
+   */
+  readonly probePort: () => AsyncResult<number | undefined, never>;
+  /**
+   * Whatever the runtime published on `Serving.info` once it is serving;
+   * `undefined` when it publishes nothing or never reached `serving`.
+   */
+  readonly runtimeInfo: () => AsyncResult<Info | undefined, never>;
+};
+/**
+ * The phantom marker `start`, `runMain` and `Boot` all intersect onto their
+ * `module` parameter: `unknown` — and invisible — when the module exports a
+ * runtime, its exports cover what that runtime resolves and they cover the
+ * unit module's needs; one of three sentences otherwise, printed at the call
+ * site as the parameter type the argument did not match.
+ *
+ * `unknown` is the satisfied arm because intersecting it leaves the module
+ * type untouched. A runtime's `resolves` is checked against the module's
+ * exports only, never the unit module's: `RuntimeHost.ctx` is the application
+ * context, so a unit-only port would resolve to nothing there.
+ */
+type StartGate<X, UnitNeeds = never> = [Extract<X, RuntimeInstance>] extends [never] ? "NO RUNTIME — the module exports no port declared over RuntimePort" : [InstanceType<RuntimeResolvesOf<X>>] extends [X] ? [Exclude<UnitNeeds, X | Scope | Env>] extends [never] ? unknown : "UNSATISFIED UNIT NEEDS — the unit module needs a port the module does not export" : "UNSATISFIED RUNTIME PORTS — the runtime resolves a port the module does not export";
+declare const start: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X, E, Scope | Env> & StartGate<X, UnitNeeds>, options?: StartOptions<UnitX, UnitNeeds>) => RunningApp<E, RuntimeInfoOf<X>>;
+//#endregion
+//#region src/run-main.d.ts
+/**
+ * Boot a module and turn its outcome into a process exit code — the front
+ * door, and the one sanctioned place this package decides a process's fate.
+ * `start` composed with the wait for `exited`: use `start` instead when the
+ * `RunningApp` itself is wanted (a test, an embedder, a dev runner booting
+ * two applications — none of which may claim `process.exitCode`).
+ *
+ * `exit` is injectable and defaults to setting `process.exitCode`: `runMain`
+ * never calls `process.exit()`, so pending output is flushed, an embedding
+ * host keeps control of its own lifetime, and a test can observe the code
+ * without ending the run.
+ *
+ * | outcome | code |
+ * | --- | --- |
+ * | exited cleanly | `0` |
+ * | startup failure (a modeled `Err`) | `1` |
+ * | a configuration port that could not be bound (`ConfigInvalid`, `PROBE_PORT` included) | `78` |
+ * | drained with work abandoned | `2` |
+ * | exited with teardown errors | `2` |
+ * | stopped by an uncaught exception or unhandled rejection | `70` |
+ * | a defect | `70` |
+ *
+ * The two `70`s are the same statement reached through the two channels a bug
+ * can take. A crash takes precedence over abandoned work.
+ *
+ * @example
+ * ```ts
+ * // `OrderApi` imports the application next to `http()` and exports
+ * // `HttpRuntime`. `PORT`, `HOST` and `PROBE_PORT` are read inside the graph.
+ * await runMain(OrderApi);
+ * ```
+ */
+declare const runMain: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X, E, Scope | Env> & StartGate<X, UnitNeeds>, options?: StartOptions<UnitX, UnitNeeds>, exit?: (code: number) => void) => Promise<void>;
+//#endregion
+export { type Attributes, type Clock, type Counter, type DrainReport, type EventSink, type ExitReport, type Histogram, type KernelEvent, LEVELS, type Level, Logger, type LoggerService, Meter, type MeterService, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, releasedBy, runMain, start, stderrSink, systemClock };