@ambarltd/core 0.1.17

package/dist/time.js

@@ -0,0 +1,387 @@
+import * as s from "./json/schema";
+import { fail, always } from "./json/decoder";
+import { Just, Nothing } from "./maybe";
+import { DateTime } from "luxon";
+/** Date + time stored as milliseconds passed since 00:00:00 UTC on January 1, 1970. */
+class POSIX {
+    value;
+    static fromDate(d) {
+        return new POSIX(d.valueOf());
+    }
+    static fromDuration(d) {
+        return new POSIX(d.asMilliseconds());
+    }
+    static now() {
+        return new POSIX(Date.now());
+    }
+    /** Takes number of milliseconds since epoch. */
+    constructor(value) {
+        this.value = value;
+    }
+    /** Time since Unix epoch (00:00:00 UTC on January 1, 1970). */
+    sinceEpoch() {
+        return Duration.milliseconds(this.value);
+    }
+    toDate() {
+        return new Date(this.value);
+    }
+    isAfter(other) {
+        return this.value > other.value;
+    }
+    greaterThan(other) {
+        return this.value > other.value;
+    }
+    compare(other) {
+        return (this.value > other.value ? 1
+            : this.value < other.value ? -1
+                : 0);
+    }
+    addDuration(d) {
+        return new POSIX(this.value + d.asMilliseconds());
+    }
+    subtractDuration(d) {
+        return new POSIX(this.value - d.asMilliseconds());
+    }
+    difference(other) {
+        return Duration.milliseconds(this.value - other.value);
+    }
+    static fromLocalDateAndTime(date, time, timezone) {
+        const s = `${date.pretty()}T${time.pretty()}`;
+        const luxonDate = DateTime.fromISO(s, { zone: timezone });
+        return new POSIX(luxonDate.toMillis());
+    }
+    toUTCDateAndTime() {
+        const dt = DateTime.fromMillis(this.value, { zone: "UTC" });
+        const date = new DateOnly(dt.year, dt.month, dt.day);
+        const time = TimeOfDay.fromParts({
+            hours: dt.hour,
+            minutes: dt.minute,
+            seconds: dt.second,
+        });
+        return { date, time };
+    }
+    toLocalDateAndTime(timezone) {
+        const dt = DateTime.fromMillis(this.value, { zone: "UTC" }).setZone(timezone);
+        const date = new DateOnly(dt.year, dt.month, dt.day);
+        const time = TimeOfDay.fromParts({
+            hours: dt.hour,
+            minutes: dt.minute,
+            seconds: dt.second,
+        });
+        return { date, time };
+    }
+    /** Parse PostgreSQL TIMESTAMPTZ string (e.g., "2026-03-17 10:30:00+00"). */
+    static fromSQLTimestamp(str) {
+        const date = DateTime.fromSQL(str, { zone: "UTC" });
+        return date.isValid ? new POSIX(date.toMillis()) : null;
+    }
+    /** Convert to PostgreSQL TIMESTAMPTZ string. */
+    toSQLTimestamp() {
+        return DateTime.fromMillis(this.value, { zone: "UTC" }).toSQL();
+    }
+    static schema = s.number.dimap(n => new POSIX(n), p => p.value);
+}
+const padded = (v) => v.toString().padStart(2, "0");
+class DateOnly {
+    year;
+    month; // 1-12
+    day; // 1-30ish
+    constructor(year, month, day) {
+        this.year = year;
+        this.month = month;
+        this.day = day;
+    }
+    static todayUTC() {
+        const utcTime = POSIX.now();
+        return utcTime.toUTCDateAndTime().date;
+    }
+    static todayLocal(timezone) {
+        const utcTime = POSIX.now();
+        return utcTime.toLocalDateAndTime(timezone).date;
+    }
+    static fromDate(date) {
+        return new DateOnly(date.getFullYear(), date.getMonth() + 1, date.getDate());
+    }
+    pretty() {
+        return `${this.year}-${padded(this.month)}-${padded(this.day)}`;
+    }
+    static schema = s.string.chain(str => {
+        const parts = str.split("-");
+        if (parts.length !== 3) {
+            return fail("Invalid Date");
+        }
+        const year = parseInt(parts[0], 10);
+        const month = parseInt(parts[1], 10);
+        const day = parseInt(parts[2], 10);
+        if (isNaN(year) || isNaN(month) || isNaN(day)) {
+            return fail("Invalid Date");
+        }
+        return always(new DateOnly(year, month, day));
+    }, date => date.pretty());
+    greaterThan(other) {
+        return this.compare(other) === 1;
+    }
+    compare(other) {
+        return (this.year > other.year ? 1
+            : this.year < other.year ? -1
+                : this.month > other.month ? 1
+                    : this.month < other.month ? -1
+                        : this.day > other.day ? 1
+                            : this.day < other.day ? -1
+                                : 0);
+    }
+    addMonths(months) {
+        const luxonDate = DateTime.fromObject({
+            year: this.year,
+            month: this.month,
+            day: this.day,
+        });
+        const newLuxonDate = luxonDate.plus({ months });
+        return new DateOnly(newLuxonDate.year, newLuxonDate.month, newLuxonDate.day);
+    }
+}
+class TimeOfDay {
+    seconds;
+    constructor(seconds) {
+        this.seconds = seconds;
+    }
+    static fromParts({ hours, minutes, seconds }) {
+        return new TimeOfDay(hours * 60 * 60 + minutes * 60 + seconds);
+    }
+    pretty() {
+        const hours = padded(Math.floor(this.seconds / (60 * 60)));
+        const minutes = padded(Math.floor(this.seconds / 60) % 60);
+        const wholeSeconds = padded(Math.floor(this.seconds) % 60);
+        return `${hours}:${minutes}:${wholeSeconds}`;
+    }
+    getSubSecondPrecision() {
+        return this.seconds - Math.floor(this.seconds);
+    }
+}
+/**
+ * Configuration strings for duration formatting.
+ */
+const DURATION_FORMAT_CONFIG = {
+    long: {
+        suffixes: {
+            weeks: { singular: " week", plural: " weeks" },
+            days: { singular: " day", plural: " days" },
+            hours: { singular: " hour", plural: " hours" },
+            minutes: { singular: " minute", plural: " minutes" },
+            seconds: { singular: " second", plural: " seconds" },
+            milliseconds: { singular: " millisecond", plural: " milliseconds" },
+        },
+        less_than: "less than ",
+        separator: ", ",
+    },
+    short: {
+        suffixes: {
+            weeks: { singular: "w", plural: "w" },
+            days: { singular: "d", plural: "d" },
+            hours: { singular: "h", plural: "h" },
+            minutes: { singular: "m", plural: "m" },
+            seconds: { singular: "s", plural: "s" },
+            milliseconds: { singular: "ms", plural: "ms" },
+        },
+        less_than: "< ",
+        separator: " ",
+    },
+};
+/** A length of time. */
+class Duration {
+    millis;
+    constructor(millis) {
+        this.millis = millis;
+    }
+    static milliseconds(n) {
+        return new Duration(n);
+    }
+    static seconds(n) {
+        return Duration.milliseconds(n * 1_000);
+    }
+    static minutes(n) {
+        return Duration.seconds(n * 60);
+    }
+    static hours(n) {
+        return Duration.minutes(n * 60);
+    }
+    static days(n) {
+        return Duration.hours(n * 24);
+    }
+    static weeks(n) {
+        return Duration.days(n * 7);
+    }
+    asMilliseconds() {
+        return this.millis;
+    }
+    asSeconds() {
+        return this.millis / Duration.seconds(1).millis;
+    }
+    asMinutes() {
+        return this.millis / Duration.minutes(1).millis;
+    }
+    asHours() {
+        return this.millis / Duration.hours(1).millis;
+    }
+    asDays() {
+        return this.millis / Duration.days(1).millis;
+    }
+    asWeeks() {
+        return this.millis / Duration.weeks(1).millis;
+    }
+    add(other) {
+        return new Duration(this.millis + other.millis);
+    }
+    subtract(other) {
+        return new Duration(this.millis - other.millis);
+    }
+    multiplyBy(n) {
+        return new Duration(n * this.millis);
+    }
+    divideBy(n) {
+        return new Duration(this.millis / n);
+    }
+    greaterThan(other) {
+        return this.millis > other.millis;
+    }
+    compare(other) {
+        return (this.millis > other.millis ? 1
+            : this.millis < other.millis ? -1
+                : 0);
+    }
+    /** Quantisation. Divide a duration into buckets of a fixed length. */
+    bucketsOf(length) {
+        const sign = Math.sign(this.millis);
+        const abs = this.absolute();
+        const count = Math.floor(abs.millis / length.millis);
+        const remainderStart = length.multiplyBy(count).multiplyBy(sign);
+        const remainder = Duration.milliseconds(abs.millis % length.millis).multiplyBy(sign);
+        return {
+            count: count * sign,
+            remainderStart,
+            remainder,
+        };
+    }
+    /** Returns a non-negative duration. */
+    absolute() {
+        return new Duration(Math.abs(this.millis));
+    }
+    parts() {
+        const d = new Duration(Math.abs(this.millis));
+        return {
+            days: Math.floor(d.asDays()),
+            hours: Math.floor(d.asHours()) % 24,
+            minutes: Math.floor(d.asMinutes()) % 60,
+            seconds: Math.floor(d.asSeconds()) % 60,
+            milliseconds: Math.floor(d.asMilliseconds() % 1_000),
+        };
+    }
+    /** Formats duration as ISO-8601 string (e.g., "P1DT2H30M45.123S"). */
+    toISO8601() {
+        const { days, hours, minutes } = this.parts();
+        const seconds = Math.abs(this.asSeconds()) % 60;
+        const formatSeconds = (s) => (s % 1 === 0 ? s.toString() : s.toFixed(3).replace(/\.?0+$/, ""));
+        const prefix = this.millis < 0 ? "-P" : "P";
+        const dayPart = days > 0 ? `${days}D` : "";
+        const hasTimePart = hours > 0 || minutes > 0 || seconds > 0 || days === 0;
+        const timeParts = [
+            hours > 0 ? `${hours}H` : "",
+            minutes > 0 ? `${minutes}M` : "",
+            seconds > 0 || (days === 0 && hours === 0 && minutes === 0) ? `${formatSeconds(seconds)}S` : "",
+        ].join("");
+        return prefix + dayPart + (hasTimePart ? "T" + timeParts : "");
+    }
+    /**
+     * Formats a duration to a friendly, human readable string.  First argument (`verbosity`) can be
+     * either "short" (e.g. 1w 3d 5h 2m 0s 20ms) or long (e.g. 1 week, 3 days, 5 hours, 2 minutes, 20 milliseconds).
+     *
+     * Options allow for truncation after minutes or seconds.  Additionally, if the truncated duration would
+     * evaluate to zero but not _exactly_ zero (e.g. a duration of 20 seconds when truncated to minutes will
+     * result in 0m), there is an option `show_less_than_when_close_to_zero` which will prefix either "<" (short)
+     * or "less than" long in this case, which is recommended when users are actively "watching the clock".
+     */
+    toFormatted(verbosity, options = {}) {
+        if (this.millis < 0) {
+            return this.absolute().toFormatted(verbosity, options);
+        }
+        const { days: _days, hours, minutes, seconds, milliseconds } = this.parts();
+        const weeks = Math.floor(this.asWeeks());
+        const days = _days % 7;
+        const { suffixes, less_than, separator } = DURATION_FORMAT_CONFIG[verbosity];
+        // Zero
+        if (this.millis === 0) {
+            return "0" + suffixes[options.truncateAfter ?? "milliseconds"].plural;
+        }
+        // Close to zero
+        if (options.onTruncation === "show_less_than_when_close_to_zero") {
+            // Less than one minute
+            if (options.truncateAfter === "minutes" && this.asMinutes() < 1) {
+                return `${less_than}1${suffixes["minutes"].singular}`;
+            }
+            // Less than one second
+            if (options.truncateAfter === "seconds" && this.asSeconds() < 1) {
+                return `${less_than}1${suffixes["seconds"].singular}`;
+            }
+            // Less than one millisecond
+            if (this.asMilliseconds() < 1) {
+                return `${less_than}1${suffixes["milliseconds"].singular}`;
+            }
+        }
+        const parts = [
+            [weeks, "weeks"],
+            [days, "days"],
+            [hours, "hours"],
+            [minutes, "minutes"],
+            [seconds, "seconds"],
+            [milliseconds, "milliseconds"],
+        ].slice(0, options.truncateAfter === "minutes" ? 4
+            : options.truncateAfter === "seconds" ? 5
+                : 6);
+        while (parts[0]?.[0] === 0)
+            parts.shift(); // remove leading zeroes
+        while (parts[parts.length - 1]?.[0] === 0)
+            parts.pop(); // remove trailing zeroes
+        const pluralised = (amount, forms) => amount.toString() + (amount == 1 ? forms.singular : forms.plural);
+        return parts.map(([amount, unit]) => pluralised(amount, suffixes[unit])).join(separator);
+    }
+    /** Parses ISO-8601 duration string (e.g., "P1DT2H30M45.123S"). */
+    static fromISO8601(str) {
+        // Supports: P[nD]T[nH][nM][nS] with optional decimals on any component
+        const regex = /^(-)?P(?:(\d+(?:\.\d+)?)D)?(T)?(?:(\d+(?:\.\d+)?)H)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)S)?$/;
+        const match = str.match(regex);
+        if (!match) {
+            return Nothing();
+        }
+        const hasDays = !!match[2];
+        const hasT = !!match[3];
+        const hasHours = !!match[4];
+        const hasMinutes = !!match[5];
+        const hasSeconds = !!match[6];
+        const hasTimeComponents = hasHours || hasMinutes || hasSeconds;
+        // Must have at least one component
+        if (!hasDays && !hasTimeComponents) {
+            return Nothing();
+        }
+        // If T is present, must have at least one time component
+        if (hasT && !hasTimeComponents) {
+            return Nothing();
+        }
+        const negative = match[1] === "-";
+        const days = match[2] ? parseFloat(match[2]) : 0;
+        const hours = match[4] ? parseFloat(match[4]) : 0;
+        const minutes = match[5] ? parseFloat(match[5]) : 0;
+        const seconds = match[6] ? parseFloat(match[6]) : 0;
+        // Chained factory methods (seconds → milliseconds) accumulate
+        // IEEE-754 floating point errors (~10⁻¹⁵). Rounding to milliseconds is safe
+        // as it's our internal precision and the error is far below this threshold.
+        const total = Duration.days(days)
+            .add(Duration.hours(hours))
+            .add(Duration.minutes(minutes))
+            .add(Duration.seconds(seconds));
+        const millis = Math.round(total.asMilliseconds());
+        return Just(Duration.milliseconds(negative ? -millis : millis));
+    }
+    /** Default: ISO-8601 string (standard, human-readable, interoperable). */
+    static schema = s.string.chain(str => Duration.fromISO8601(str).unwrap(() => fail("Invalid ISO-8601 duration format"), d => always(d)), d => d.toISO8601());
+}
+export { DateOnly, TimeOfDay, POSIX, Duration };

package/dist/tracing/opentelemetry.d.ts

@@ -0,0 +1,27 @@
+export { OpenTelemetryTracer, OtlpJsonStdoutProcessor };
+import { type Tracer, type Attributes } from "../tracing";
+import { Future } from "../future";
+import type { SpanProcessor, ReadableSpan, Sampler } from "@opentelemetry/sdk-trace-base";
+declare class OtlpJsonStdoutProcessor implements SpanProcessor {
+    private readonly byTrace;
+    onStart(): void;
+    onEnd(span: ReadableSpan): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+interface OpenTelemetryTracerOptions {
+    serviceName: string;
+    spanProcessor: SpanProcessor;
+    sampler?: Sampler;
+}
+declare class OpenTelemetryTracer implements Tracer {
+    private readonly tracer;
+    private readonly provider;
+    constructor(options: OpenTelemetryTracerOptions);
+    private begin;
+    trace<A>(name: string, attributes: Attributes, f: () => A): A;
+    traceP<A>(name: string, attributes: Attributes, f: () => Promise<A>): Promise<A>;
+    traceF<E, A>(name: string, attributes: Attributes, f: Future<E, A>): Future<E, A>;
+    event(name: string, attributes?: Attributes): void;
+    shutdown(): Promise<void>;
+}

package/dist/tracing/opentelemetry.js

@@ -0,0 +1,215 @@
+// OpenTelemetry tracing: a `Tracer` (see ./index.ts) exposing the same API as
+// `./simple.ts` — `trace`, `traceP`, `traceF`.
+//
+// Nesting is automatic and needs no token threaded through the code — it rides on
+// OpenTelemetry's AsyncLocalStorage context manager, which propagates the active
+// span across `await`s and Fluture's `.chain`/`.map` continuations. A span
+// created while another is active becomes its child.
+//
+// Construct it with a service name and a span processor:
+//
+//    new OpenTelemetryTracer({ serviceName: "backend", spanProcessor: new OtlpJsonStdoutProcessor() })
+//
+// `OtlpJsonStdoutProcessor` (also exported here) prints each completed trace to
+// stdout as an OTLP/JSON document (`{ resourceSpans: [...] }`) — paste it into an
+// OTLP trace viewer such as https://tracekit.dev/tools/trace-visualizer.
+export { OpenTelemetryTracer, OtlpJsonStdoutProcessor };
+import { Future } from "../future";
+import { context, trace as otel, SpanStatusCode, } from "@opentelemetry/api";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+// --- OTLP/JSON stdout span processor ---------------------------------------
+//
+// Prints completed traces to stdout as OTLP/JSON (`{ resourceSpans: [...] }`),
+// one self-contained document per trace, flushed when the trace's ROOT span ends
+// (which is after all of its children). Hand-rolled to avoid depending on
+// @opentelemetry/otlp-transformer. trace/span ids are emitted as hex and int
+// attributes as strings, per the OTLP/JSON encoding the OTel SDKs and Collector
+// use.
+class OtlpJsonStdoutProcessor {
+    // Spans accumulated per in-flight trace, flushed when the trace's root ends.
+    byTrace = new Map();
+    onStart() { }
+    onEnd(span) {
+        const traceId = span.spanContext().traceId;
+        const spans = this.byTrace.get(traceId) ?? [];
+        spans.push(span);
+        this.byTrace.set(traceId, spans);
+        if (!parentSpanId(span)) {
+            // Root span ended → the trace is complete.
+            this.byTrace.delete(traceId);
+            console.log(JSON.stringify(toOtlp(spans)));
+        }
+    }
+    forceFlush() {
+        return Promise.resolve();
+    }
+    shutdown() {
+        return Promise.resolve();
+    }
+}
+// ReadableSpan exposes the parent either as `parentSpanContext` (newer SDKs) or
+// `parentSpanId` (older ones). A missing/empty value means this is a root span.
+function parentSpanId(span) {
+    const s = span;
+    return s.parentSpanContext?.spanId ?? s.parentSpanId ?? undefined;
+}
+function toOtlp(spans) {
+    const first = spans[0];
+    return {
+        resourceSpans: [
+            {
+                resource: { attributes: toAttributes(first?.resource.attributes ?? {}) },
+                scopeSpans: [
+                    {
+                        scope: {
+                            name: first?.instrumentationScope.name ?? "",
+                            version: first?.instrumentationScope.version,
+                        },
+                        spans: spans.map(toOtlpSpan),
+                    },
+                ],
+            },
+        ],
+    };
+}
+function toOtlpSpan(span) {
+    const ctx = span.spanContext();
+    return {
+        traceId: ctx.traceId,
+        spanId: ctx.spanId,
+        parentSpanId: parentSpanId(span),
+        name: span.name,
+        // OTLP SpanKind is the API SpanKind + 1 (OTLP reserves 0 for UNSPECIFIED).
+        kind: span.kind + 1,
+        startTimeUnixNano: hrTimeToNanoString(span.startTime),
+        endTimeUnixNano: hrTimeToNanoString(span.endTime),
+        attributes: toAttributes(span.attributes),
+        events: span.events.map(e => ({
+            timeUnixNano: hrTimeToNanoString(e.time),
+            name: e.name,
+            attributes: toAttributes(e.attributes ?? {}),
+        })),
+        status: { code: span.status.code },
+    };
+}
+function toAttributes(attrs) {
+    return Object.entries(attrs)
+        .filter(([, v]) => v !== undefined)
+        .map(([key, value]) => ({ key, value: toAnyValue(value) }));
+}
+function toAnyValue(value) {
+    if (typeof value === "string") {
+        return { stringValue: value };
+    }
+    if (typeof value === "boolean") {
+        return { boolValue: value };
+    }
+    if (typeof value === "number") {
+        // int64 fields are encoded as strings in OTLP/JSON.
+        return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+    }
+    if (Array.isArray(value)) {
+        return { arrayValue: { values: value.map(v => toAnyValue(v)) } };
+    }
+    return { stringValue: String(value) };
+}
+// HrTime is [seconds, nanos]. Combine via BigInt to avoid the precision loss of
+// representing epoch-nanoseconds (~1.8e18) as a JS number.
+function hrTimeToNanoString(time) {
+    return (BigInt(time[0]) * 1000000000n + BigInt(time[1])).toString();
+}
+// Mark a span as failed: record the error and set its status to ERROR. Accepts
+// any thrown/rejected value (Futures reject with an arbitrary `E`), coercing
+// non-Error values to a string.
+function recordError(span, err) {
+    span.recordException(err instanceof Error ? err : String(err));
+    span.setStatus({ code: SpanStatusCode.ERROR });
+}
+class OpenTelemetryTracer {
+    tracer;
+    provider;
+    constructor(options) {
+        this.provider = new NodeTracerProvider({
+            resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: options.serviceName }),
+            spanProcessors: [options.spanProcessor],
+            ...(options.sampler ? { sampler: options.sampler } : {}),
+        });
+        // The AsyncLocalStorage context manager is what lets `context.active()`
+        // return the right parent span inside `await`s and Fluture continuations.
+        this.provider.register({ contextManager: new AsyncLocalStorageContextManager().enable() });
+        this.tracer = otel.getTracer(options.serviceName);
+    }
+    // Begin a span as a child of the active one (or a new root when none is
+    // active) and return both the span and the context that makes it active.
+    begin(name, attributes) {
+        const parentCtx = context.active();
+        const span = this.tracer.startSpan(name, { attributes }, parentCtx);
+        return { span, ctx: otel.setSpan(parentCtx, span) };
+    }
+    // Trace a synchronous function.
+    trace(name, attributes, f) {
+        const { span, ctx } = this.begin(name, attributes);
+        try {
+            return context.with(ctx, f);
+        }
+        catch (err) {
+            recordError(span, err);
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    }
+    // Trace an asynchronous function. `context.with` keeps the span active across
+    // the awaits inside `f` (AsyncLocalStorage propagates it), so spans created
+    // within `f` nest under it. After the awaited promise settles we are back in
+    // the caller's context, so the span ends in the right place and a subsequent
+    // `traceP` becomes a sibling.
+    async traceP(name, attributes, f) {
+        const { span, ctx } = this.begin(name, attributes);
+        try {
+            return await context.with(ctx, f);
+        }
+        catch (err) {
+            recordError(span, err);
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    }
+    // Trace a Future. Because Futures are lazy, the span begins when the Future is
+    // forked (its real start) and ends when it settles. The span is made active
+    // for the Future's execution so nested spans nest under it; the parent context
+    // is restored when settling so that a `.chain` *after* `traceF(...)` is a
+    // sibling rather than a descendant.
+    traceF(name, attributes, f) {
+        return Future.create((reject, resolve) => {
+            const parentCtx = context.active();
+            const span = this.tracer.startSpan(name, { attributes }, parentCtx);
+            const ctx = otel.setSpan(parentCtx, span);
+            return context.with(ctx, () => f.fork(err => {
+                recordError(span, err);
+                span.end();
+                context.with(parentCtx, () => reject(err));
+            }, val => {
+                span.end();
+                context.with(parentCtx, () => resolve(val));
+            }));
+        });
+    }
+    // Record a point-in-time event on the currently-active span (the span made
+    // active by an enclosing trace/traceP/traceF). No-op when none is active.
+    event(name, attributes) {
+        otel.getActiveSpan()?.addEvent(name, attributes);
+    }
+    // Flush any pending spans, then shut down the provider and its span processors.
+    // Call on graceful shutdown (SIGTERM/SIGINT) so the final batch is not dropped.
+    async shutdown() {
+        await this.provider.forceFlush();
+        await this.provider.shutdown();
+    }
+}

package/dist/tracing/proxy.d.ts

@@ -0,0 +1,20 @@
+export { ProxyTracer, type Config };
+import { type Tracer, type Attributes } from "../tracing";
+import type { Future } from "../future";
+interface Config {
+    tracer: Tracer;
+    traceFilter?: (name: string) => boolean;
+    includeCallSite?: boolean;
+}
+declare class ProxyTracer implements Tracer {
+    private readonly inner;
+    private readonly traceFilter;
+    private readonly includeCallSite;
+    constructor(config: Config);
+    private enabled;
+    private withCallSite;
+    trace<A>(name: string, attributes: Attributes, f: () => A): A;
+    traceP<A>(name: string, attributes: Attributes, f: () => Promise<A>): Promise<A>;
+    traceF<E, A>(name: string, attributes: Attributes, f: Future<E, A>): Future<E, A>;
+    event(name: string, attributes?: Attributes): void;
+}