@ddd-ts-kit/aspects 0.0.0-stage → 0.1.0

package/dist/observability/log-call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-call.d.ts","sourceRoot":"","sources":["../../src/observability/log-call.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAI7E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sFAAsF;IACtF,QAAQ,CAAC,MAAM,EAAE,MAAM,SAAS,CAAC;CAClC;AAOD,0FAA0F;AAC1F,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAclF"}

package/dist/observability/log-call.js

@@ -0,0 +1,22 @@
+import { observed } from './observed.js';
+import { safely } from './safely.js';
+/** The three entries of one call: started, then succeeded or failed with the duration. */
+export function logCall(call, proceed) {
+    safely(() => {
+        write(call, 'debug', { word: 'started' });
+    });
+    return observed(call.clock, proceed, ({ durationMs, error, refused }) => {
+        if (error === undefined) {
+            write(call, call.level, { word: 'succeeded', fields: { durationMs } });
+            return;
+        }
+        write(call, refused ? 'warn' : 'error', { word: 'failed', fields: { durationMs, ...error } });
+    });
+}
+function write(call, level, outcome) {
+    if (!call.logger.isLevelEnabled(level)) {
+        return;
+    }
+    call.logger[level](`${call.operation} ${outcome.word}`, { ...call.fields(), ...outcome.fields });
+}
+//# sourceMappingURL=log-call.js.map

package/dist/observability/log-call.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-call.js","sourceRoot":"","sources":["../../src/observability/log-call.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAiBrC,0FAA0F;AAC1F,MAAM,UAAU,OAAO,CAAI,IAAgB,EAAE,OAAyB;IACpE,MAAM,CAAC,GAAG,EAAE;QACV,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEH,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE;QACtE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC;YAEvE,OAAO;QACT,CAAC;QAED,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,GAAG,KAAK,EAAE,EAAE,CAAC,CAAC;IAChG,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,KAAK,CAAC,IAAgB,EAAE,KAAe,EAAE,OAAgB;IAChE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,OAAO;IACT,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AACnG,CAAC"}

package/dist/observability/logged.d.ts

@@ -0,0 +1,22 @@
+import type { Clock, LogFields, LogLevel, Logger } from '@ddd-ts-kit/kernel';
+import type { AdviceFactory } from '../aspect/advice-factory.js';
+import type { Aspect } from '../aspect/aspect.js';
+export interface LoggedOptions {
+    /** Level of the entry written on success. Default `info`. The start entry is `debug`. */
+    readonly level?: LogLevel;
+    /** Added to every entry: static fields, or a function read at each entry that is written. Never call data. */
+    readonly fields?: LogFields | (() => LogFields);
+    /** Defaults to the logger of the aspect runtime. */
+    readonly logger?: Logger;
+    /** Defaults to the clock of the aspect runtime. */
+    readonly clock?: Clock;
+}
+/**
+ * Three entries per call: `<Class>.<method> started` (debug), then `succeeded` or `failed`
+ * with the duration. A failure carries the class of the error and its code, at `warn` for a
+ * business refusal and `error` for a fault. Never arguments, results or error messages, and
+ * nothing is built for an entry the logger would not write.
+ */
+export declare function logged(options?: LoggedOptions): Aspect;
+export declare function loggedAdvice(options?: LoggedOptions): AdviceFactory;
+//# sourceMappingURL=logged.d.ts.map

package/dist/observability/logged.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logged.d.ts","sourceRoot":"","sources":["../../src/observability/logged.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAOlD,MAAM,WAAW,aAAa;IAC5B,yFAAyF;IACzF,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAC1B,8GAA8G;IAC9G,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,CAAC,MAAM,SAAS,CAAC,CAAC;IAChD,oDAAoD;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,MAAM,CAE1D;AAED,wBAAgB,YAAY,CAAC,OAAO,GAAE,aAAkB,GAAG,aAAa,CAiBvE"}

package/dist/observability/logged.js

@@ -0,0 +1,38 @@
+import { defineAspect } from '../aspect/define-aspect.js';
+import { clockOr } from '../runtime/clock-or.js';
+import { loggerOr } from '../runtime/logger-or.js';
+import { logCall } from './log-call.js';
+/**
+ * Three entries per call: `<Class>.<method> started` (debug), then `succeeded` or `failed`
+ * with the duration. A failure carries the class of the error and its code, at `warn` for a
+ * business refusal and `error` for a fault. Never arguments, results or error messages, and
+ * nothing is built for an entry the logger would not write.
+ */
+export function logged(options = {}) {
+    return defineAspect(loggedAdvice(options));
+}
+export function loggedAdvice(options = {}) {
+    return (joinPoint) => {
+        const operation = `${joinPoint.className}.${joinPoint.method}`;
+        const subject = subjectFields(joinPoint);
+        return ({ proceed }) => logCall({
+            logger: loggerOr(options.logger),
+            clock: clockOr(options.clock),
+            level: options.level ?? 'info',
+            operation,
+            fields: () => ({ ...subject, ...extraFields(options) }),
+        }, proceed);
+    };
+}
+function subjectFields(joinPoint) {
+    return {
+        class: joinPoint.className,
+        method: joinPoint.method,
+        ...(joinPoint.kind === undefined ? {} : { kind: joinPoint.kind }),
+        ...(joinPoint.context === undefined ? {} : { context: joinPoint.context }),
+    };
+}
+function extraFields(options) {
+    return typeof options.fields === 'function' ? options.fields() : (options.fields ?? {});
+}
+//# sourceMappingURL=logged.js.map

package/dist/observability/logged.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logged.js","sourceRoot":"","sources":["../../src/observability/logged.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAaxC;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,OAAO,GAAkB,EAAE;IAChD,OAAO,YAAY,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAO,GAAkB,EAAE;IACtD,OAAO,CAAC,SAAS,EAAE,EAAE;QACnB,MAAM,SAAS,GAAG,GAAG,SAAS,CAAC,SAAS,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC;QAC/D,MAAM,OAAO,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;QAEzC,OAAO,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CACrB,OAAO,CACL;YACE,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC;YAChC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC;YAC7B,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,MAAM;YAC9B,SAAS;YACT,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;SACxD,EACD,OAAO,CACR,CAAC;IACN,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,SAAoB;IACzC,OAAO;QACL,KAAK,EAAE,SAAS,CAAC,SAAS;QAC1B,MAAM,EAAE,SAAS,CAAC,MAAM;QACxB,GAAG,CAAC,SAAS,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC;QACjE,GAAG,CAAC,SAAS,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC;KAC3E,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,OAAsB;IACzC,OAAO,OAAO,OAAO,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;AAC1F,CAAC"}

package/dist/observability/logging-middleware.d.ts

@@ -0,0 +1,13 @@
+import type { BusMiddleware, Clock, LogLevel, Logger } from '@ddd-ts-kit/kernel';
+export interface LoggingMiddlewareOptions {
+    /** Level of the entry written on success. Default `info`. */
+    readonly level?: LogLevel;
+    /** Defaults to the clock of the aspect runtime, then to the system clock. */
+    readonly clock?: Clock;
+}
+/**
+ * `logged` for use cases: the same three entries around every command and query, named after
+ * the message class, with `messageKind`. Never the content of the message or of the answer.
+ */
+export declare function loggingMiddleware(logger: Logger, options?: LoggingMiddlewareOptions): BusMiddleware;
+//# sourceMappingURL=logging-middleware.d.ts.map

package/dist/observability/logging-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging-middleware.d.ts","sourceRoot":"","sources":["../../src/observability/logging-middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAIjF,MAAM,WAAW,wBAAwB;IACvC,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,wBAA6B,GAAG,aAAa,CAYvG"}

package/dist/observability/logging-middleware.js

@@ -0,0 +1,16 @@
+import { clockOr } from '../runtime/clock-or.js';
+import { logCall } from './log-call.js';
+/**
+ * `logged` for use cases: the same three entries around every command and query, named after
+ * the message class, with `messageKind`. Never the content of the message or of the answer.
+ */
+export function loggingMiddleware(logger, options = {}) {
+    return (_message, next, info) => logCall({
+        logger,
+        clock: clockOr(options.clock),
+        level: options.level ?? 'info',
+        operation: `${info.kind} ${info.name}`,
+        fields: () => ({ message: info.name, messageKind: info.kind }),
+    }, next);
+}
+//# sourceMappingURL=logging-middleware.js.map

package/dist/observability/logging-middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging-middleware.js","sourceRoot":"","sources":["../../src/observability/logging-middleware.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AASxC;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,OAAO,GAA6B,EAAE;IACtF,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAC9B,OAAO,CACL;QACE,MAAM;QACN,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC;QAC7B,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,MAAM;QAC9B,SAAS,EAAE,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE;QACtC,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;KAC/D,EACD,IAAI,CACL,CAAC;AACN,CAAC"}

package/dist/observability/metrics-middleware.d.ts

@@ -0,0 +1,10 @@
+import type { BusMiddleware, Clock, Metrics } from '@ddd-ts-kit/kernel';
+export interface MetricsMiddlewareOptions {
+    /** Prefix of the two series: `<name>_duration_ms` and `<name>_total`. Default `use_case`. */
+    readonly name?: string;
+    /** Defaults to the clock of the aspect runtime, then to the system clock. */
+    readonly clock?: Clock;
+}
+/** `timed` for use cases: duration and outcome of every command and query, labelled `message` and `kind`. */
+export declare function metricsMiddleware(metrics: Metrics, options?: MetricsMiddlewareOptions): BusMiddleware;
+//# sourceMappingURL=metrics-middleware.d.ts.map

package/dist/observability/metrics-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-middleware.d.ts","sourceRoot":"","sources":["../../src/observability/metrics-middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAIxE,MAAM,WAAW,wBAAwB;IACvC,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED,6GAA6G;AAC7G,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,wBAA6B,GAAG,aAAa,CAWzG"}

package/dist/observability/metrics-middleware.js

@@ -0,0 +1,12 @@
+import { clockOr } from '../runtime/clock-or.js';
+import { timeCall } from './time-call.js';
+/** `timed` for use cases: duration and outcome of every command and query, labelled `message` and `kind`. */
+export function metricsMiddleware(metrics, options = {}) {
+    return (_message, next, info) => timeCall({
+        metrics,
+        clock: clockOr(options.clock),
+        name: options.name ?? 'use_case',
+        labels: { message: info.name, kind: info.kind },
+    }, next);
+}
+//# sourceMappingURL=metrics-middleware.js.map

package/dist/observability/metrics-middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-middleware.js","sourceRoot":"","sources":["../../src/observability/metrics-middleware.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAS1C,6GAA6G;AAC7G,MAAM,UAAU,iBAAiB,CAAC,OAAgB,EAAE,OAAO,GAA6B,EAAE;IACxF,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAC9B,QAAQ,CACN;QACE,OAAO;QACP,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC;QAC7B,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,UAAU;QAChC,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;KAChD,EACD,IAAI,CACL,CAAC;AACN,CAAC"}

package/dist/observability/observed.d.ts

@@ -0,0 +1,14 @@
+import { type Clock, type ErrorIdentity } from '@ddd-ts-kit/kernel';
+export interface CallOutcome {
+    readonly durationMs: number;
+    /** Present when the call failed. */
+    readonly error?: ErrorIdentity;
+    /** True when the failure is a business refusal rather than a fault. */
+    readonly refused: boolean;
+}
+/**
+ * Runs the call and reports how it went, once. The result and the error pass through
+ * untouched; a report that throws never changes the outcome of the call.
+ */
+export declare function observed<T>(clock: Clock, call: () => Promise<T>, report: (outcome: CallOutcome) => void): Promise<T>;
+//# sourceMappingURL=observed.d.ts.map

package/dist/observability/observed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observed.d.ts","sourceRoot":"","sources":["../../src/observability/observed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,KAAK,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAInF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,MAAM,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,GACrC,OAAO,CAAC,CAAC,CAAC,CAsBZ"}

package/dist/observability/observed.js

@@ -0,0 +1,27 @@
+import { identifyError } from '@ddd-ts-kit/kernel';
+import { isBusinessRefusal } from '../errors/is-business-refusal.js';
+import { safely } from './safely.js';
+/**
+ * Runs the call and reports how it went, once. The result and the error pass through
+ * untouched; a report that throws never changes the outcome of the call.
+ */
+export async function observed(clock, call, report) {
+    const startedAt = clock.now().getTime();
+    const elapsed = () => clock.now().getTime() - startedAt;
+    let result;
+    try {
+        result = await call();
+    }
+    catch (error) {
+        const outcome = { durationMs: elapsed(), error: identifyError(error), refused: isBusinessRefusal(error) };
+        safely(() => {
+            report(outcome);
+        });
+        throw error;
+    }
+    safely(() => {
+        report({ durationMs: elapsed(), refused: false });
+    });
+    return result;
+}
+//# sourceMappingURL=observed.js.map

package/dist/observability/observed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observed.js","sourceRoot":"","sources":["../../src/observability/observed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAkC,MAAM,oBAAoB,CAAC;AACnF,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAUrC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,KAAY,EACZ,IAAsB,EACtB,MAAsC;IAEtC,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;IACxC,MAAM,OAAO,GAAG,GAAW,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC;IAChE,IAAI,MAAS,CAAC;IAEd,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,IAAI,EAAE,CAAC;IACxB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;QAE1G,MAAM,CAAC,GAAG,EAAE;YACV,MAAM,CAAC,OAAO,CAAC,CAAC;QAClB,CAAC,CAAC,CAAC;QAEH,MAAM,KAAK,CAAC;IACd,CAAC;IAED,MAAM,CAAC,GAAG,EAAE;QACV,MAAM,CAAC,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/observability/safely.d.ts

@@ -0,0 +1,3 @@
+/** Observation must never break what it observes. */
+export declare function safely(act: () => void): void;
+//# sourceMappingURL=safely.d.ts.map

package/dist/observability/safely.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safely.d.ts","sourceRoot":"","sources":["../../src/observability/safely.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,IAAI,GAAG,IAAI,CAM5C"}

package/dist/observability/safely.js

@@ -0,0 +1,10 @@
+/** Observation must never break what it observes. */
+export function safely(act) {
+    try {
+        act();
+    }
+    catch {
+        return;
+    }
+}
+//# sourceMappingURL=safely.js.map

package/dist/observability/safely.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safely.js","sourceRoot":"","sources":["../../src/observability/safely.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,MAAM,UAAU,MAAM,CAAC,GAAe;IACpC,IAAI,CAAC;QACH,GAAG,EAAE,CAAC;IACR,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;AACH,CAAC"}

package/dist/observability/stdout-logger.d.ts

@@ -0,0 +1,45 @@
+import { type Clock, type LogFields, type LogLevel, type Logger } from '@ddd-ts-kit/kernel';
+export interface StdoutLoggerOptions {
+    /** Entries below it are not written. Default `info`. */
+    readonly level?: LogLevel;
+    /**
+     * Read at each entry: correlation fields of the work in progress, such as the trace ids of
+     * the tracing package or `logFieldsOf` of the current execution context.
+     */
+    readonly fields?: () => LogFields;
+    /** Added to every entry: service name, version, environment. */
+    readonly base?: LogFields;
+    /**
+     * Writes `SCRUBBED_MESSAGE` for the message of every logged error that is not a
+     * `DomainError`. Default `false`: see "StdoutLogger" in the README for the trade-off.
+     */
+    readonly scrubMessages?: boolean;
+    /** Defaults to the clock of the aspect runtime, then to the system clock. */
+    readonly clock?: Clock;
+    /** Receives each line, newline included. Defaults to the standard output. */
+    readonly write?: (line: string) => void;
+}
+/**
+ * The `Logger` port as JSON lines: one object per entry with `time`, `level`, `message`, then
+ * the fields. What a container platform collects as it is.
+ */
+export declare class StdoutLogger implements Logger {
+    private readonly options;
+    constructor(options?: StdoutLoggerOptions);
+    debug(message: string, fields?: LogFields): void;
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+    child(fields: LogFields): StdoutLogger;
+    isLevelEnabled(level: LogLevel): boolean;
+    /**
+     * Resolves once the standard output took every line written so far; at once with a `write`
+     * of the project, which is called before each log call returns. The logger stays usable.
+     */
+    flush(): Promise<void>;
+    private writeEntry;
+    private serialized;
+    private ambientFields;
+    private boundWith;
+}
+//# sourceMappingURL=stdout-logger.d.ts.map

package/dist/observability/stdout-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdout-logger.d.ts","sourceRoot":"","sources":["../../src/observability/stdout-logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAG5B,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,SAAS,CAAC;IAClC,gEAAgE;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAQD;;;GAGG;AACH,qBAAa,YAAa,YAAW,MAAM;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAApC,YAA6B,OAAO,GAAE,mBAAwB,EAAI;IAElE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAE/C;IAED,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAE9C;IAED,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAE9C;IAED,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAE/C;IAED,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG,YAAY,CAErC;IAED,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAEvC;IAED;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAcrB;IAED,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,SAAS;CAOlB"}

package/dist/observability/stdout-logger.js

@@ -0,0 +1,85 @@
+import { LOG_LEVELS, UNWRITABLE_FIELDS, describeErrorFields, } from '@ddd-ts-kit/kernel';
+import { clockOr } from '../runtime/clock-or.js';
+/**
+ * The `Logger` port as JSON lines: one object per entry with `time`, `level`, `message`, then
+ * the fields. What a container platform collects as it is.
+ */
+export class StdoutLogger {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    debug(message, fields) {
+        this.writeEntry('debug', message, fields);
+    }
+    info(message, fields) {
+        this.writeEntry('info', message, fields);
+    }
+    warn(message, fields) {
+        this.writeEntry('warn', message, fields);
+    }
+    error(message, fields) {
+        this.writeEntry('error', message, fields);
+    }
+    child(fields) {
+        return new StdoutLogger({ ...this.options, base: this.boundWith(fields) });
+    }
+    isLevelEnabled(level) {
+        return LOG_LEVELS.indexOf(level) >= LOG_LEVELS.indexOf(this.options.level ?? 'info');
+    }
+    /**
+     * Resolves once the standard output took every line written so far; at once with a `write`
+     * of the project, which is called before each log call returns. The logger stays usable.
+     */
+    flush() {
+        if (this.options.write !== undefined) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            try {
+                process.stdout.write('', () => {
+                    resolve();
+                });
+            }
+            catch {
+                resolve();
+            }
+        });
+    }
+    writeEntry(level, message, fields = {}) {
+        if (!this.isLevelEnabled(level)) {
+            return;
+        }
+        const header = { time: clockOr(this.options.clock).now().toISOString(), level, message };
+        (this.options.write ?? writeToStdout)(`${this.serialized(header, fields)}\n`);
+    }
+    serialized(header, fields) {
+        try {
+            const written = describeErrorFields({ ...this.options.base, ...this.ambientFields(), ...fields }, this.options);
+            return JSON.stringify({ ...header, ...written, ...header });
+        }
+        catch {
+            return JSON.stringify({ ...header, ...UNWRITABLE_FIELDS });
+        }
+    }
+    ambientFields() {
+        try {
+            return this.options.fields?.() ?? {};
+        }
+        catch {
+            return {};
+        }
+    }
+    boundWith(fields) {
+        try {
+            return { ...this.options.base, ...fields };
+        }
+        catch {
+            return { ...this.options.base, ...UNWRITABLE_FIELDS };
+        }
+    }
+}
+function writeToStdout(line) {
+    process.stdout.write(line);
+}
+//# sourceMappingURL=stdout-logger.js.map

package/dist/observability/stdout-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdout-logger.js","sourceRoot":"","sources":["../../src/observability/stdout-logger.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,mBAAmB,GAKpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AA6BjD;;;GAGG;AACH,MAAM,OAAO,YAAY;IACM,OAAO;IAApC,YAA6B,OAAO,GAAwB,EAAE;uBAAjC,OAAO;IAA6B,CAAC;IAElE,KAAK,CAAC,OAAe,EAAE,MAAkB;QACvC,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC5C,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,MAAkB;QACtC,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,MAAkB;QACtC,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,MAAkB;QACvC,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,MAAiB;QACrB,OAAO,IAAI,YAAY,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC7E,CAAC;IAED,cAAc,CAAC,KAAe;QAC5B,OAAO,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,MAAM,CAAC,CAAC;IACvF,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YACrC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,IAAI,CAAC;gBACH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,EAAE;oBAC5B,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC,CAAC;YACL,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,UAAU,CAAC,KAAe,EAAE,OAAe,EAAE,MAAM,GAAc,EAAE;QACzE,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;YAChC,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QAEzF,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,aAAa,CAAC,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAChF,CAAC;IAEO,UAAU,CAAC,MAAc,EAAE,MAAiB;QAClD,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,mBAAmB,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,aAAa,EAAE,EAAE,GAAG,MAAM,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;YAEhH,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;QAC9D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,GAAG,iBAAiB,EAAE,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IAEO,aAAa;QACnB,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAEO,SAAS,CAAC,MAAiB;QACjC,IAAI,CAAC;YACH,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,iBAAiB,EAAE,CAAC;QACxD,CAAC;IACH,CAAC;CACF;AAED,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC"}

package/dist/observability/time-call.d.ts

@@ -0,0 +1,10 @@
+import type { Clock, MetricLabels, Metrics } from '@ddd-ts-kit/kernel';
+export interface TimedCall {
+    readonly metrics: Metrics;
+    readonly clock: Clock;
+    readonly name: string;
+    readonly labels: MetricLabels;
+}
+/** The duration and the outcome of one call, in the two series named after `name`. */
+export declare function timeCall<T>(call: TimedCall, proceed: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=time-call.d.ts.map

package/dist/observability/time-call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-call.d.ts","sourceRoot":"","sources":["../../src/observability/time-call.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAGvE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B;AAED,sFAAsF;AACtF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CASlF"}

package/dist/observability/time-call.js

@@ -0,0 +1,11 @@
+import { observed } from './observed.js';
+/** The duration and the outcome of one call, in the two series named after `name`. */
+export function timeCall(call, proceed) {
+    const { metrics, name, labels } = call;
+    return observed(call.clock, proceed, ({ durationMs, error }) => {
+        const outcome = error === undefined ? 'success' : 'failure';
+        metrics.histogram(`${name}_duration_ms`).record(durationMs, { ...labels, outcome });
+        metrics.counter(`${name}_total`).increment({ ...labels, outcome, error_code: error?.errorCode });
+    });
+}
+//# sourceMappingURL=time-call.js.map

package/dist/observability/time-call.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-call.js","sourceRoot":"","sources":["../../src/observability/time-call.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AASzC,sFAAsF;AACtF,MAAM,UAAU,QAAQ,CAAI,IAAe,EAAE,OAAyB;IACpE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAEvC,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE,EAAE;QAC7D,MAAM,OAAO,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;QAE5D,OAAO,CAAC,SAAS,CAAC,GAAG,IAAI,cAAc,CAAC,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;QACpF,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,QAAQ,CAAC,CAAC,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IACnG,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/observability/timed.d.ts

@@ -0,0 +1,19 @@
+import type { Clock, Metrics } from '@ddd-ts-kit/kernel';
+import type { AdviceFactory } from '../aspect/advice-factory.js';
+import type { Aspect } from '../aspect/aspect.js';
+export interface TimedOptions {
+    /** Prefix of the two series: `<name>_duration_ms` and `<name>_total`. Default `dependency_call`. */
+    readonly name?: string;
+    /** Defaults to the metrics of the aspect runtime. */
+    readonly metrics?: Metrics;
+    /** Defaults to the clock of the aspect runtime. */
+    readonly clock?: Clock;
+}
+/**
+ * Per call: a duration in the histogram `<name>_duration_ms` and one in the counter
+ * `<name>_total`, labelled `class`, `method`, `kind`, `context`, `outcome`, and `error_code`
+ * on a failure that has one. Labels are names from the code, never values of a call.
+ */
+export declare function timed(options?: TimedOptions): Aspect;
+export declare function timedAdvice(options?: TimedOptions): AdviceFactory;
+//# sourceMappingURL=timed.d.ts.map

package/dist/observability/timed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timed.d.ts","sourceRoot":"","sources":["../../src/observability/timed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAgB,OAAO,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAOlD,MAAM,WAAW,YAAY;IAC3B,oGAAoG;IACpG,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAID;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,MAAM,CAExD;AAED,wBAAgB,WAAW,CAAC,OAAO,GAAE,YAAiB,GAAG,aAAa,CAerE"}

package/dist/observability/timed.js

@@ -0,0 +1,33 @@
+import { defineAspect } from '../aspect/define-aspect.js';
+import { clockOr } from '../runtime/clock-or.js';
+import { metricsOr } from '../runtime/metrics-or.js';
+import { timeCall } from './time-call.js';
+const DEFAULT_NAME = 'dependency_call';
+/**
+ * Per call: a duration in the histogram `<name>_duration_ms` and one in the counter
+ * `<name>_total`, labelled `class`, `method`, `kind`, `context`, `outcome`, and `error_code`
+ * on a failure that has one. Labels are names from the code, never values of a call.
+ */
+export function timed(options = {}) {
+    return defineAspect(timedAdvice(options));
+}
+export function timedAdvice(options = {}) {
+    return (joinPoint) => {
+        const labels = subjectLabels(joinPoint);
+        return ({ proceed }) => timeCall({
+            metrics: metricsOr(options.metrics),
+            clock: clockOr(options.clock),
+            name: options.name ?? DEFAULT_NAME,
+            labels,
+        }, proceed);
+    };
+}
+function subjectLabels(joinPoint) {
+    return {
+        class: joinPoint.className,
+        method: joinPoint.method,
+        kind: joinPoint.kind,
+        context: joinPoint.context,
+    };
+}
+//# sourceMappingURL=timed.js.map

package/dist/observability/timed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timed.js","sourceRoot":"","sources":["../../src/observability/timed.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAW1C,MAAM,YAAY,GAAG,iBAAiB,CAAC;AAEvC;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,OAAO,GAAiB,EAAE;IAC9C,OAAO,YAAY,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAO,GAAiB,EAAE;IACpD,OAAO,CAAC,SAAS,EAAE,EAAE;QACnB,MAAM,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;QAExC,OAAO,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CACrB,QAAQ,CACN;YACE,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC;YACnC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC;YAC7B,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,YAAY;YAClC,MAAM;SACP,EACD,OAAO,CACR,CAAC;IACN,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,SAAoB;IACzC,OAAO;QACL,KAAK,EAAE,SAAS,CAAC,SAAS;QAC1B,MAAM,EAAE,SAAS,CAAC,MAAM;QACxB,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,OAAO,EAAE,SAAS,CAAC,OAAO;KAC3B,CAAC;AACJ,CAAC"}

package/dist/retry/backoff.d.ts

@@ -0,0 +1,12 @@
+import type { Jitter } from './jitter.js';
+export interface Backoff {
+    /** Delay before the first retry. */
+    readonly baseMs: number;
+    /** Multiplies the delay at each retry. Default 2. */
+    readonly factor?: number;
+    /** The delay never exceeds it. Default 30 seconds. */
+    readonly maxMs?: number;
+    /** Default `fullJitter()`. */
+    readonly jitter?: Jitter;
+}
+//# sourceMappingURL=backoff.d.ts.map

package/dist/retry/backoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../../src/retry/backoff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,WAAW,OAAO;IACtB,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B"}

package/dist/retry/backoff.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=backoff.js.map

package/dist/retry/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../../src/retry/backoff.ts"],"names":[],"mappings":""}

package/dist/retry/delay-before-retry.d.ts

@@ -0,0 +1,4 @@
+import type { Backoff } from './backoff.js';
+/** The delay waited after the failed attempt of that number, the first being 1. */
+export declare function delayBeforeRetry(attempt: number, backoff: Backoff): number;
+//# sourceMappingURL=delay-before-retry.d.ts.map

package/dist/retry/delay-before-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delay-before-retry.d.ts","sourceRoot":"","sources":["../../src/retry/delay-before-retry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAM5C,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAK1E"}

package/dist/retry/delay-before-retry.js

@@ -0,0 +1,10 @@
+import { fullJitter } from './full-jitter.js';
+const DEFAULT_FACTOR = 2;
+const DEFAULT_MAX_MS = 30_000;
+/** The delay waited after the failed attempt of that number, the first being 1. */
+export function delayBeforeRetry(attempt, backoff) {
+    const exponential = backoff.baseMs * (backoff.factor ?? DEFAULT_FACTOR) ** (attempt - 1);
+    const capped = Math.min(exponential, backoff.maxMs ?? DEFAULT_MAX_MS);
+    return Math.max(0, (backoff.jitter ?? fullJitter())(capped, attempt));
+}
+//# sourceMappingURL=delay-before-retry.js.map

package/dist/retry/delay-before-retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delay-before-retry.js","sourceRoot":"","sources":["../../src/retry/delay-before-retry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,MAAM,cAAc,GAAG,CAAC,CAAC;AACzB,MAAM,cAAc,GAAG,MAAM,CAAC;AAE9B,mFAAmF;AACnF,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,OAAgB;IAChE,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,cAAc,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;IACzF,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,KAAK,IAAI,cAAc,CAAC,CAAC;IAEtE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,IAAI,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AACxE,CAAC"}

package/dist/retry/full-jitter.d.ts

@@ -0,0 +1,7 @@
+import type { Jitter } from './jitter.js';
+/**
+ * A delay anywhere between zero and the computed one, so that callers failing together do not
+ * retry together. Give a seeded `random` to make it deterministic.
+ */
+export declare function fullJitter(random?: () => number): Jitter;
+//# sourceMappingURL=full-jitter.d.ts.map

package/dist/retry/full-jitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"full-jitter.d.ts","sourceRoot":"","sources":["../../src/retry/full-jitter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,GAAE,MAAM,MAAoB,GAAG,MAAM,CAErE"}

package/dist/retry/full-jitter.js

@@ -0,0 +1,8 @@
+/**
+ * A delay anywhere between zero and the computed one, so that callers failing together do not
+ * retry together. Give a seeded `random` to make it deterministic.
+ */
+export function fullJitter(random = Math.random) {
+    return (delayMs) => random() * delayMs;
+}
+//# sourceMappingURL=full-jitter.js.map

package/dist/retry/full-jitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"full-jitter.js","sourceRoot":"","sources":["../../src/retry/full-jitter.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAAM,GAAiB,IAAI,CAAC,MAAM;IAC3D,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,EAAE,GAAG,OAAO,CAAC;AACzC,CAAC"}

package/dist/retry/is-transient.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Worth another attempt: anything but a business refusal and the two refusals of this package
+ * that protect a dependency (an open circuit, a full bulkhead).
+ */
+export declare function isTransient(error: unknown): boolean;
+//# sourceMappingURL=is-transient.d.ts.map

package/dist/retry/is-transient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-transient.d.ts","sourceRoot":"","sources":["../../src/retry/is-transient.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEnD"}

package/dist/retry/is-transient.js

@@ -0,0 +1,11 @@
+import { BulkheadFullError } from '../errors/bulkhead-full-error.js';
+import { CircuitOpenError } from '../errors/circuit-open-error.js';
+import { isBusinessRefusal } from '../errors/is-business-refusal.js';
+/**
+ * Worth another attempt: anything but a business refusal and the two refusals of this package
+ * that protect a dependency (an open circuit, a full bulkhead).
+ */
+export function isTransient(error) {
+    return !(isBusinessRefusal(error) || error instanceof CircuitOpenError || error instanceof BulkheadFullError);
+}
+//# sourceMappingURL=is-transient.js.map

package/dist/retry/is-transient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-transient.js","sourceRoot":"","sources":["../../src/retry/is-transient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAErE;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,CAAC,CAAC,iBAAiB,CAAC,KAAK,CAAC,IAAI,KAAK,YAAY,gBAAgB,IAAI,KAAK,YAAY,iBAAiB,CAAC,CAAC;AAChH,CAAC"}

package/dist/retry/jitter.d.ts

@@ -0,0 +1,3 @@
+/** Turns the computed delay before a retry into the one that is waited. */
+export type Jitter = (delayMs: number, attempt: number) => number;
+//# sourceMappingURL=jitter.d.ts.map

package/dist/retry/jitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jitter.d.ts","sourceRoot":"","sources":["../../src/retry/jitter.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC"}

package/dist/retry/jitter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=jitter.js.map