@shaferllc/keel 0.36.0 → 0.58.0

package/dist/core/broker.d.ts

@@ -0,0 +1,398 @@
+/**
+ * A service broker — a Moleculer-style backbone for service-oriented code.
+ * Register *services* (a name plus a bag of `actions` and `events`), then reach
+ * them by string name: `broker.call("users.get", { id })` runs an action and
+ * returns its result; `broker.emit("user.created", user)` fans an event out to
+ * every service that listens. Actions receive a `Context` and can call *other*
+ * actions or emit events through it, so a request threads its `meta` (auth,
+ * trace ids) all the way down.
+ *
+ *   const broker = new Broker();
+ *   broker.createService({
+ *     name: "math",
+ *     actions: {
+ *       add: (ctx: Context<{ a: number; b: number }>) => ctx.params.a + ctx.params.b,
+ *     },
+ *   });
+ *   await broker.start();
+ *   await broker.call("math.add", { a: 2, b: 3 });   // 5
+ *
+ * Like the queue and Redis layers, clustering lives behind a pluggable seam: the
+ * default `LocalTransporter` is a single-node no-op, so the core imports no
+ * network client and runs on Node and the edge. Swap in a real `Transporter`
+ * (NATS, Redis, TCP) to span processes — the call/emit API doesn't change.
+ */
+import { Logger } from "./logger.js";
+import { Cache } from "./cache.js";
+import type { Schema } from "./validation.js";
+/** How an event was dispatched — `emit` (balanced) or `broadcast` (every listener). */
+export type EventType = "emit" | "broadcast";
+/** Per-call state, handed to every action and event handler. */
+export interface Context<P = any> {
+    /** The call parameters (an action's arguments) or an event's payload. */
+    params: P;
+    /** Metadata that flows down through nested `call`s — auth, trace ids, locale. */
+    meta: Record<string, unknown>;
+    /** Scratch space shared between this call's hooks and handler; never propagated. */
+    locals: Record<string, unknown>;
+    /** Per-call headers — like `meta`, but transient: not carried into nested calls. */
+    headers: Record<string, unknown>;
+    /** The broker handling this call. */
+    broker: Broker;
+    /** The service whose handler is running. */
+    service: Service;
+    /** The action or event name currently executing. */
+    name: string;
+    /** The action being executed (absent in event handlers). */
+    action?: {
+        name: string;
+    };
+    /** The event being handled (absent in action handlers). */
+    event?: {
+        name: string;
+        type: EventType;
+        groups: string[];
+    };
+    /** In an event handler, the emitted event's name. */
+    eventName?: string;
+    /** In an event handler, how it was dispatched — `"emit"` or `"broadcast"`. */
+    eventType?: EventType;
+    /** In an event handler, the groups the event targeted. */
+    eventGroups?: string[];
+    /** The node this call originated on. */
+    nodeID: string;
+    /** A unique id for this call, for tracing/logging. */
+    id: string;
+    /** The `id` of the parent context in a nested call, or `null` at the root. */
+    parentID: string | null;
+    /** Call depth — `1` at the root, incremented on each nested `call`. */
+    level: number;
+    /** Full name of the service that invoked this call, or `null` at the root. */
+    caller: string | null;
+    /** A correlation id shared by every call in the same request tree. */
+    requestID: string;
+    /** Call another action, inheriting this context's `meta` and `requestID`. */
+    call<R = unknown>(action: string, params?: unknown, opts?: CallOptions): Promise<R>;
+    /** Call several actions at once, inheriting this context's `meta`. */
+    mcall<R = unknown>(defs: MCallDefs, opts?: MCallOptions): Promise<R>;
+    /** A serializable snapshot of this context (drops functions and live refs). */
+    toJSON(): Record<string, unknown>;
+    /** Emit a balanced event, inheriting this context's `meta`. */
+    emit(event: string, payload?: unknown, opts?: EmitOptions): Promise<void>;
+    /** Broadcast an event to every listener, inheriting this context's `meta`. */
+    broadcast(event: string, payload?: unknown, opts?: EmitOptions): Promise<void>;
+}
+export interface CallOptions {
+    /** Metadata merged into (and overriding) the parent context's `meta`. */
+    meta?: Record<string, unknown>;
+    /** Per-call headers — available as `ctx.headers`, not propagated downstream. */
+    headers?: Record<string, unknown>;
+    /** Correlation id for the request tree; generated if omitted. */
+    requestID?: string;
+    /** Milliseconds to wait before rejecting with a `RequestTimeoutError`. */
+    timeout?: number;
+    /** Retry the call this many times on failure (total attempts = retries + 1). */
+    retries?: number;
+    /** A value (or `(err, ctx) => value`) to return if every attempt fails. */
+    fallback?: unknown | ((err: Error, ctx: Context) => unknown);
+    /** @internal parent context whose `meta`/`requestID` this call inherits. */
+    parentCtx?: Context;
+}
+export interface EmitOptions {
+    meta?: Record<string, unknown>;
+    /** Restrict delivery to listeners in these groups (defaults to all listeners). */
+    groups?: string[];
+}
+/** The shape passed to `mcall` — an array of calls, or a map of them by key. */
+export type MCallDefs = Array<{
+    action: string;
+    params?: unknown;
+    opts?: CallOptions;
+}> | Record<string, {
+    action: string;
+    params?: unknown;
+    opts?: CallOptions;
+}>;
+export interface MCallOptions extends CallOptions {
+    /** Return `{ status, value | reason }` per call instead of failing on the first rejection. */
+    settled?: boolean;
+}
+/** An action handler — receives a `Context`, returns (or resolves to) a result. */
+export type ActionHandler<P = any, R = any> = (ctx: Context<P>) => R | Promise<R>;
+/** An event handler — `ctx.params` is the event payload. */
+export type EventHandler<P = any> = (ctx: Context<P>) => void | Promise<void>;
+/** A before-hook — runs before the handler; mutate `ctx.params`/`meta`/`locals`. */
+export type BeforeHook<P = any> = (ctx: Context<P>) => void | Promise<void>;
+/** An after-hook — receives the result and returns the (possibly transformed) result. */
+export type AfterHook<P = any, R = any> = (ctx: Context<P>, res: R) => R | Promise<R>;
+/** An error-hook — receives the thrown error; return a fallback or re-throw. */
+export type ErrorHook<P = any> = (ctx: Context<P>, err: Error) => unknown;
+/** How far an action is reachable. `private` actions are hidden from `broker.call`. */
+export type Visibility = "published" | "public" | "protected" | "private";
+/** Hooks bound to a single action, in its full definition. */
+export interface ActionHooks {
+    before?: BeforeHook | BeforeHook[];
+    after?: AfterHook | AfterHook[];
+    error?: ErrorHook | ErrorHook[];
+}
+/** The full form of an action — a handler plus per-action options. */
+export interface ActionDef {
+    handler: ActionHandler;
+    /** Reachability; defaults to `published`. `private` blocks `broker.call`. */
+    visibility?: Visibility;
+    /** Per-action timeout (ms); overrides the broker default, overridden by the call. */
+    timeout?: number;
+    /** Validate `ctx.params` against this schema before the handler runs. */
+    params?: Schema<unknown>;
+    /** Cache the result (needs `BrokerOptions.cacher`). `keys` limits the cache key to those params. */
+    cache?: boolean | {
+        ttl?: number;
+        keys?: string[];
+    };
+    /** Hooks that wrap just this action. */
+    hooks?: ActionHooks;
+}
+/** An action entry: a bare handler (shorthand) or a full `ActionDef`. */
+export type ActionSchema = ActionHandler | ActionDef;
+/** An event entry: a bare handler (shorthand) or a handler plus a `group`. */
+export type EventSchema = EventHandler | {
+    group?: string;
+    handler: EventHandler;
+};
+/**
+ * Service-level hooks, keyed by action name. Keys may be `"*"` (all actions),
+ * an exact name, a `"a|b"` pipe list, or a `*` glob (`"get*"`).
+ */
+export interface ServiceHooks {
+    before?: Record<string, BeforeHook | BeforeHook[]>;
+    after?: Record<string, AfterHook | AfterHook[]>;
+    error?: Record<string, ErrorHook | ErrorHook[]>;
+}
+/**
+ * The shape you hand to `createService`. Handlers and lifecycle hooks run with
+ * `this` bound to the live `Service`, so they can reach `this.settings`,
+ * `this.broker`, `this.logger`, and any `methods` you define.
+ */
+export interface ServiceSchema {
+    /** Unique service name, e.g. `"users"`. Combined with `version` into a prefix. */
+    name: string;
+    /** Optional version; `2` or `"2"` namespaces actions as `v2.users.*`. */
+    version?: string | number;
+    /** Free-form config, readable from handlers as `this.settings`. */
+    settings?: Record<string, unknown>;
+    /** Arbitrary descriptive info, readable as `this.metadata`. */
+    metadata?: Record<string, unknown>;
+    /** Service name(s) that must be registered before this service's `started` runs. */
+    dependencies?: string | string[];
+    /** Reusable schemas merged into this one (this schema always wins on conflict). */
+    mixins?: ServiceSchema[];
+    /** Named actions — a bare handler, or a full `ActionDef`. */
+    actions?: Record<string, ActionSchema>;
+    /** Event listeners, keyed by event name (may be a glob, e.g. `"user.*"`). */
+    events?: Record<string, EventSchema>;
+    /** Private helpers, bound to the service and reachable as `this.<method>`. */
+    methods?: Record<string, (...args: any[]) => any>;
+    /** Hooks wrapping this service's actions. */
+    hooks?: ServiceHooks;
+    /** Called after mixins are merged, before the instance is created; receives the schema. */
+    merged?(this: void, schema: ServiceSchema): void;
+    /** Called synchronously when the service is created. */
+    created?(this: Service): void | Promise<void>;
+    /** Called during `broker.start()`, after every service is created. */
+    started?(this: Service): void | Promise<void>;
+    /** Called during `broker.stop()`, in reverse creation order. */
+    stopped?(this: Service): void | Promise<void>;
+}
+/** A normalized action ready to invoke — handlers and hooks already bound. */
+interface NormalizedAction {
+    name: string;
+    handler: ActionHandler;
+    visibility: Visibility;
+    timeout?: number;
+    params?: Schema<unknown>;
+    cache?: boolean | {
+        ttl?: number;
+        keys?: string[];
+    };
+    hooks: {
+        before: BeforeHook[];
+        after: AfterHook[];
+        error: ErrorHook[];
+    };
+}
+interface NormalizedEvent {
+    handler: EventHandler;
+    group: string;
+}
+interface NormalizedServiceHooks {
+    before: Record<string, BeforeHook[]>;
+    after: Record<string, AfterHook[]>;
+    error: Record<string, ErrorHook[]>;
+}
+/** A live service instance. Bound as `this` inside handlers, methods, and hooks. */
+export declare class Service {
+    readonly name: string;
+    readonly version?: string | number;
+    /** Versioned, dotted prefix — `"users"` or `"v2.users"`. */
+    readonly fullName: string;
+    readonly settings: Record<string, unknown>;
+    readonly metadata: Record<string, unknown>;
+    /** Services that must exist before this one's `started` hook runs. */
+    readonly dependencies: string[];
+    readonly broker: Broker;
+    readonly logger: Logger;
+    /** Internal callers for this service's own actions — `this.actions.foo(params)`. */
+    readonly actions: Record<string, (params?: unknown, opts?: CallOptions) => Promise<unknown>>;
+    /** Bound `methods` land here (and directly on the instance) — `this.<name>`. */
+    [key: string]: any;
+    /** @internal normalized actions, keyed by local (unprefixed) name. */
+    readonly _actions: Map<string, NormalizedAction>;
+    /** @internal normalized event listeners, keyed by pattern. */
+    readonly _events: Map<string, NormalizedEvent>;
+    /** @internal normalized service-level hooks. */
+    readonly _hooks: NormalizedServiceHooks;
+    constructor(broker: Broker, schema: ServiceSchema);
+    /** Wait until the named service(s) are registered on this broker. */
+    waitForServices(deps: string | string[], timeout?: number, interval?: number): Promise<void>;
+    /** @internal the merged schema, for lifecycle hooks. */
+    _schema: ServiceSchema;
+}
+/** Thrown by `call` when no action matches the requested name. */
+export declare class ServiceNotFoundError extends Error {
+    readonly action: string;
+    constructor(action: string);
+}
+/** Thrown by `call` when an action exceeds its timeout. */
+export declare class RequestTimeoutError extends Error {
+    readonly action: string;
+    readonly timeout: number;
+    constructor(action: string, timeout: number);
+}
+/**
+ * The seam where clustering plugs in. The default `LocalTransporter` is a
+ * single-node no-op; a real transporter (NATS, Redis, TCP) would register
+ * remote services with the broker on `connect` and relay published packets.
+ */
+export interface Transporter {
+    connect(broker: Broker): Promise<void>;
+    disconnect(): Promise<void>;
+}
+/** The default transporter — a single node, nothing to connect. */
+export declare class LocalTransporter implements Transporter {
+    connect(_broker: Broker): Promise<void>;
+    disconnect(): Promise<void>;
+}
+/**
+ * A broker middleware — wraps action calls and taps broker lifecycle. `localAction`
+ * receives the next handler in the chain and returns a replacement, so middlewares
+ * compose (the first in the array is the outermost). Great for logging, metrics,
+ * caching, or auth around every action.
+ */
+export interface BrokerMiddleware {
+    name?: string;
+    localAction?(next: ActionHandler, action: string): ActionHandler;
+    started?(broker: Broker): void | Promise<void>;
+    stopped?(broker: Broker): void | Promise<void>;
+}
+export interface BrokerOptions {
+    /** This node's id. Defaults to a generated `node-<rand>`. */
+    nodeID?: string;
+    /** Clustering transport. Defaults to `LocalTransporter` (single node). */
+    transporter?: Transporter;
+    /** Default per-call timeout in ms. `0` (default) disables it. */
+    requestTimeout?: number;
+    /** Default number of retries per call on failure. `0` (default) disables it. */
+    retries?: number;
+    /** Cache for actions marked `cache` — a Keel `Cache` (memory, Redis, …). */
+    cacher?: Cache;
+    /** Logger to use; defaults to a fresh `Logger`. */
+    logger?: Logger;
+    /** Middlewares that wrap every action call and tap broker lifecycle. */
+    middlewares?: BrokerMiddleware[];
+}
+export declare class Broker {
+    readonly nodeID: string;
+    readonly logger: Logger;
+    private readonly transporter;
+    private readonly requestTimeout;
+    private readonly defaultRetries;
+    private readonly cacher?;
+    private readonly middlewares;
+    private readonly services;
+    /** action fullName → endpoint. */
+    private readonly actions;
+    private started;
+    private uid;
+    constructor(options?: BrokerOptions);
+    /** Register a service from a schema (flattening any `mixins`). Returns the instance. */
+    createService(rawSchema: ServiceSchema): Service;
+    /** Look up a local service by (versioned) name. */
+    getLocalService(name: string): Service | undefined;
+    /** Remove a service, running its `stopped` hook and unregistering its actions. */
+    destroyService(service: Service): Promise<void>;
+    /** Resolve once every named service is registered; polls until `timeout` (ms). */
+    waitForServices(deps: string | string[], timeout?: number, interval?: number): Promise<void>;
+    /** Connect the transporter and run every service's `started` hook. */
+    start(): Promise<void>;
+    /** Run every service's `stopped` hook (reverse order) and disconnect. */
+    stop(): Promise<void>;
+    /** A short unique id for tracing. */
+    generateUid(): string;
+    /** Invoke an action by name and resolve with its result. */
+    call<R = unknown>(action: string, params?: unknown, opts?: CallOptions): Promise<R>;
+    /** Whether a callable (non-private) action is registered. */
+    hasAction(name: string): boolean;
+    /** The names of every callable (non-private) action, sorted. */
+    listActions(): string[];
+    /** The full names of every registered service. */
+    listServices(): string[];
+    /** A registered service by full name or bare name. */
+    getService(name: string): Service | undefined;
+    /** Invoke several actions at once — pass an array or a keyed map; returns the same shape. */
+    mcall<R = unknown>(defs: MCallDefs, opts?: MCallOptions): Promise<R>;
+    /** The full call pipeline: build context → before hooks → handler → after hooks. */
+    private invoke;
+    /** Race a promise against a timeout, rejecting with `RequestTimeoutError`. */
+    private withTimeout;
+    /**
+     * Assemble the hook chains for an action. Before: service wildcard → service
+     * named → action. After/Error run in reverse: action → service named →
+     * service wildcard.
+     */
+    private resolveHooks;
+    /**
+     * Emit a *balanced* event: each listening service receives it once. In a
+     * multi-node cluster only one instance per service group is chosen; locally,
+     * with one instance per service, that's every listener.
+     */
+    emit(event: string, payload?: unknown, opts?: EmitOptions): Promise<void>;
+    /** Broadcast an event to *every* listener (all instances, all groups). */
+    broadcast(event: string, payload?: unknown, opts?: EmitOptions): Promise<void>;
+    /**
+     * Broadcast to every *local* listener only. On a single node this is identical
+     * to `broadcast`; the distinction matters once a real transporter would
+     * otherwise relay the event to remote nodes.
+     */
+    broadcastLocal(event: string, payload?: unknown, opts?: EmitOptions): Promise<void>;
+    private dispatch;
+    /** True if any registered service listens for the given event. */
+    hasEventListener(event: string): boolean;
+    /**
+     * Measure round-trip latency (and clock difference) to a node. With the local
+     * transporter there's no network, so both are ~0 — the hook is here for real
+     * transporters to implement.
+     */
+    ping(nodeID?: string): Promise<{
+        nodeID: string;
+        elapsedTime: number;
+        timeDiff: number;
+    }>;
+    /** A snapshot of registered action names — handy for debugging. */
+    get registeredActions(): string[];
+    private makeContext;
+}
+/** Register the default broker returned by `broker()`. */
+export declare function setBroker(next: Broker): Broker;
+/** The default broker instance. */
+export declare function broker(): Broker;
+export {};