@ambarltd/core 0.1.17

package/dist/tracing/proxy.js

@@ -0,0 +1,103 @@
+// A Tracer that wraps another Tracer and forwards only the traces whose name
+// passes the configured filters. Non-matching traces run untraced — the work
+// still executes, but no span is created.
+//
+// The match is decided once per call and applies to the whole span (delegate the
+// call wholesale, or bypass it wholesale), so a span is never half-emitted.
+//
+// Optionally (config.includeCallSite) it tags each forwarded trace with the
+// source file and line it was called from, as `code.filepath` / `code.lineno`.
+//
+// Usage:
+//    setTracer(new ProxyTracer({
+//      tracer: new OpenTelemetryTracer({ ... }),
+//      traceFilter: name => /^mongo\./.test(name) || name.includes("idempotency"),
+//      includeCallSite: true,
+//    }));
+export { ProxyTracer };
+import { fileURLToPath } from "node:url";
+import { dirname, sep } from "node:path";
+class ProxyTracer {
+    inner;
+    // The name predicate, or `undefined` for "no filtering — forward all".
+    traceFilter;
+    includeCallSite;
+    constructor(config) {
+        this.inner = config.tracer;
+        this.traceFilter = config.traceFilter;
+        this.includeCallSite = config.includeCallSite ?? false;
+    }
+    // Whether a trace with this name should be forwarded to the wrapped tracer.
+    // No filter → forward everything; otherwise the predicate decides.
+    enabled(name) {
+        return this.traceFilter === undefined || this.traceFilter(name);
+    }
+    // Merge in the caller's source location when configured. Only called on the
+    // forwarding path, so the stack-walk cost is paid only for traces we keep.
+    withCallSite(attributes) {
+        if (!this.includeCallSite) {
+            return attributes;
+        }
+        const site = callSite();
+        return site === undefined ? attributes : { ...attributes, ...site };
+    }
+    trace(name, attributes, f) {
+        if (!this.enabled(name)) {
+            return f();
+        }
+        return this.inner.trace(name, this.withCallSite(attributes), f);
+    }
+    traceP(name, attributes, f) {
+        if (!this.enabled(name)) {
+            return f();
+        }
+        return this.inner.traceP(name, this.withCallSite(attributes), f);
+    }
+    traceF(name, attributes, f) {
+        if (!this.enabled(name)) {
+            return f;
+        }
+        return this.inner.traceF(name, this.withCallSite(attributes), f);
+    }
+    // Events are always forwarded: the wrapped tracer attaches them to the active
+    // span if one exists and no-ops otherwise, so an event naturally lands on its
+    // enclosing span when that span passed the filter, and is dropped when it did
+    // not (no span is active to attach to).
+    event(name, attributes) {
+        this.inner.event(name, attributes);
+    }
+}
+// Frames inside this directory (the tracing facade + tracers) are skipped when
+// looking for the caller's location.
+const TRACING_PREFIX = dirname(fileURLToPath(import.meta.url)) + sep;
+// Only need to see past the handful of tracing frames to reach the caller.
+const STACK_LIMIT = 12;
+// The source location of the first stack frame outside the tracing library, as
+// OpenTelemetry `code.*` attributes. Undefined if it can't be determined.
+function callSite() {
+    const previousLimit = Error.stackTraceLimit;
+    Error.stackTraceLimit = STACK_LIMIT; // only need one frame past ours; keep it cheap
+    const holder = {};
+    Error.captureStackTrace(holder);
+    Error.stackTraceLimit = previousLimit;
+    for (const line of holder.stack?.split("\n").slice(1) ?? []) {
+        const frame = parseFrame(line);
+        if (frame === undefined || frame.file.startsWith(TRACING_PREFIX)) {
+            continue; // skip non-frames and the tracing library's own frames
+        }
+        return { "code.filepath": frame.file, "code.lineno": frame.line };
+    }
+    return undefined;
+}
+// Pull "file:line:col" out of a V8 stack frame line, with or without the
+// "at fn (...)" wrapper.
+function parseFrame(line) {
+    const match = line.match(/\((.+):(\d+):(\d+)\)\s*$/) ?? line.match(/at\s+(?:async\s+)?(.+):(\d+):(\d+)\s*$/);
+    const path = match?.[1];
+    const lineno = match?.[2];
+    if (path === undefined || lineno === undefined) {
+        return undefined;
+    }
+    const file = path.startsWith("file://") ? fileURLToPath(path) : path;
+    return { file, line: Number(lineno) };
+}

package/dist/tracing/simple.d.ts

@@ -0,0 +1,10 @@
+export { SimpleTracer };
+import type { Tracer, Attributes } from "../tracing";
+import { Future } from "../future";
+declare class SimpleTracer implements Tracer {
+    constructor();
+    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;
+}

package/dist/tracing/simple.js

@@ -0,0 +1,224 @@
+// This module allows for the issuing of tracing events which can be seen
+// in a tracing explorer like https://ui.perfetto.dev/.
+//
+// It works by emitting the traces to stdout. You should then pipe stdout into a
+// JSON file, filtering only the lines that contain trace events.
+//
+// It uses AsyncLocalStorage to nest traces, so there is no need to pass a token
+// object around and it detects nested traces through promises.
+//
+// Collect events with:
+//    $ docker logs event-sourcing-backend | grep "\"ph\"" | jq -s '.' >events.json
+export { SimpleTracer };
+import { Future } from "../future";
+import { AsyncLocalStorage } from "node:async_hooks";
+// The currently-active trace. Nested `trace`/`traceP`/`traceF` calls read this
+// to find their parent, so nesting needs no token to be threaded through code.
+const store = new AsyncLocalStorage();
+// Begin a trace as a child of the active one, or a new root when none is active.
+function begin(name, attributes) {
+    const parent = store.getStore();
+    return parent ? parent.startSubtrace(name, attributes) : Trace.start(name, attributes);
+}
+// Run `fn` with `t` as the active trace; with `undefined`, run with no active
+// trace (used to restore the parent — which may be a root — when settling).
+function runIn(t, fn) {
+    return t ? store.run(t, fn) : store.exit(fn);
+}
+// Emits Perfetto/Chrome-event JSON to stdout, nesting traces via the
+// module-level AsyncLocalStorage `store` so no token is threaded through code.
+class SimpleTracer {
+    constructor() { }
+    // Trace a synchronous function.
+    trace(name, attributes, f) {
+        const t = begin(name, attributes);
+        try {
+            return store.run(t, f);
+        }
+        finally {
+            t.end();
+        }
+    }
+    // Trace an asynchronous function. `store.run` keeps the trace active across the
+    // awaits inside `f` (AsyncLocalStorage propagates it), so traces created within
+    // `f` nest under it. After the awaited promise settles we are back in the
+    // caller's context, so the trace ends in the right place and a subsequent
+    // `traceP` becomes a sibling.
+    async traceP(name, attributes, f) {
+        const t = begin(name, attributes);
+        try {
+            return await store.run(t, f);
+        }
+        finally {
+            t.end();
+        }
+    }
+    // Trace a Future.
+    // N.B. Forking here is fine. It's what `bracket` and `chainRej` do under the hood too.
+    traceF(name, attributes, f) {
+        return Future.create((reject, resolve) => {
+            const parent = store.getStore();
+            const t = parent ? parent.startSubtrace(name, attributes) : Trace.start(name, attributes);
+            return runIn(t, () => f.fork(err => {
+                t.end();
+                runIn(parent, () => reject(err));
+            }, val => {
+                t.end();
+                runIn(parent, () => resolve(val));
+            }));
+        });
+    }
+    // Record a point-in-time (instant) event on the active trace's lane. Renders
+    // as a marker on that track in Perfetto. No-op when no trace is active.
+    event(name, attributes = {}) {
+        const t = store.getStore();
+        if (!t) {
+            return;
+        }
+        emit({ name, ph: PhaseInstant, ts: nowMicros(), pid: PROCESS_ID, tid: t.threadId, s: "t", args: attributes });
+    }
+}
+const PROCESS_ID = 1;
+// Current time in microseconds from a monotonic, high-resolution clock.
+// `process.hrtime.bigint()` returns nanoseconds, so we divide by 1000. This
+// avoids the millisecond-granularity collisions of a wall-clock (Date/POSIX)
+// timestamp, which collapsed nested spans to zero width.
+function nowMicros() {
+    return Number(process.hrtime.bigint() / 1000n);
+}
+// A pool of thread ids. A root trace acquires one for its lifetime and releases
+// it on end, so concurrent requests always get distinct lanes while the total
+// number of lanes stays as small as the peak concurrency (rather than growing
+// once per request). Node runs JavaScript on a single thread, so no lock is
+// required (unlike the Python implementation).
+class ThreadIdPool {
+    free = [];
+    next = 0;
+    named = new Set();
+    acquire() {
+        const id = this.free.pop() ?? this.next++;
+        if (!this.named.has(id)) {
+            this.named.add(id);
+            emitThreadName(id, `request lane ${id}`);
+        }
+        return id;
+    }
+    release(id) {
+        this.free.push(id);
+    }
+}
+const threadPool = new ThreadIdPool();
+// Trace event phases — synchronous Duration events plus Metadata.
+// See https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview
+const PhaseDurationBegin = "B"; // Enter a duration on this thread
+const PhaseDurationEnd = "E"; // Leave the innermost open duration on this thread
+const PhaseInstant = "i"; // A point-in-time event on this thread
+const PhaseMetadata = "M"; // Metadata (thread/process names)
+/**
+ * An ongoing trace, occupying a track (thread) in the trace explorer.
+ *
+ * A root trace (created with `Trace.start`) owns a thread id for its lifetime.
+ * Subtraces share that thread id so they nest, by stack order, within the root.
+ * Because Duration events must be strictly nested per thread, callers must end
+ * subtraces before the parent ends — which `subtrace` guarantees.
+ */
+class Trace {
+    name;
+    threadId;
+    ownsThread;
+    args;
+    constructor(name, threadId, 
+    // Only a root trace owns its thread id and releases it back to the pool on
+    // end. Subtraces borrow the root's thread id.
+    ownsThread, args) {
+        this.name = name;
+        this.threadId = threadId;
+        this.ownsThread = ownsThread;
+        this.args = args;
+    }
+    // Start a trace on its own thread (track).
+    static start(name, args = {}) {
+        const trace = new Trace(name, threadPool.acquire(), true, args);
+        trace.begin();
+        return trace;
+    }
+    // Trace a subsection of the original trace, nested on the same thread.
+    startSubtrace(name, // trace name
+    args = {}) {
+        const trace = new Trace(name, this.threadId, false, args);
+        trace.begin();
+        return trace;
+    }
+    end() {
+        emit({
+            name: this.name,
+            ph: PhaseDurationEnd,
+            ts: nowMicros(),
+            pid: PROCESS_ID,
+            tid: this.threadId,
+            args: {},
+        });
+        if (this.ownsThread) {
+            threadPool.release(this.threadId);
+        }
+    }
+    begin() {
+        emit({
+            name: this.name,
+            ph: PhaseDurationBegin,
+            ts: nowMicros(),
+            pid: PROCESS_ID,
+            tid: this.threadId,
+            args: this.args,
+        });
+    }
+    // Run `body` within a nested trace, ending the subtrace afterwards even if
+    // `body` throws. This is the idiomatic TypeScript equivalent of the Python
+    // `subtrace` async context manager.
+    //
+    //    await trace.subtrace("my-step", async (sub) => {
+    //      ... // do work here.
+    //    });
+    //
+    async subtrace(name, body, args = {}) {
+        const trace = this.startSubtrace(name, args);
+        try {
+            return await body(trace);
+        }
+        finally {
+            trace.end();
+        }
+    }
+}
+let processNamed = false;
+// Name the process once, lazily, so the explorer shows a readable label.
+function ensureProcessName() {
+    if (processNamed) {
+        return;
+    }
+    processNamed = true;
+    emit({
+        name: "process_name",
+        ph: PhaseMetadata,
+        ts: 0,
+        pid: PROCESS_ID,
+        tid: 0,
+        args: { name: "backend" },
+    });
+}
+// Name a thread (lane) once, the first time it is used.
+function emitThreadName(tid, name) {
+    ensureProcessName();
+    emit({
+        name: "thread_name",
+        ph: PhaseMetadata,
+        ts: 0,
+        pid: PROCESS_ID,
+        tid,
+        args: { name },
+    });
+}
+// Emit a trace event as a JSON line on stdout.
+function emit(event) {
+    console.log(JSON.stringify(event));
+}

package/dist/tracing.d.ts

@@ -0,0 +1,29 @@
+export { type Tracer, type Attributes, type Name, setTracer, trace, traceP, traceF, event };
+import type { Future } from "./future";
+type Attributes = Record<string, string | number | boolean>;
+type Name = string | (Attributes & {
+    name: string;
+});
+interface Tracer {
+    /**
+     * Trace a synchronous call.
+     */
+    trace<A>(name: string, attributes: Attributes, f: () => A): A;
+    /**
+     * Trace an asynchronous call.
+     */
+    traceP<A>(name: string, attributes: Attributes, f: () => Promise<A>): Promise<A>;
+    /**
+     * Trace a Future
+     */
+    traceF<E, A>(name: string, attributes: Attributes, f: Future<E, A>): Future<E, A>;
+    /**
+     * Record a point-in-time event on the currently-active trace.
+     */
+    event(name: string, attributes?: Attributes): void;
+}
+declare function setTracer(tracer: Tracer): void;
+declare function trace<A>(name: Name, f: () => A): A;
+declare function traceP<A>(name: Name, f: () => Promise<A>): Promise<A>;
+declare function traceF<E, A>(name: Name, f: Future<E, A>): Future<E, A>;
+declare function event(name: string, attributes?: Attributes): void;

package/dist/tracing.js

@@ -0,0 +1,55 @@
+// Tracing facade.
+//
+// The application imports `trace`, `traceP`, `traceF` and `traceRequests` from
+// here. The first three delegate to the currently-selected `Tracer`, so the
+// whole program's tracing destination is switched at runtime with `setTracer`.
+//
+// There is NO tracer by default: Use  `setTracer` to set one.
+//
+export { setTracer, trace, traceP, traceF, event };
+// The active tracer. None by default — traces are no-ops until one is set.
+let current = undefined;
+// Choose where traces go. Affects every subsequent trace call across the program.
+function setTracer(tracer) {
+    current = tracer;
+}
+// The delegating API. These read `current` at call time, so a `setTracer` switch
+// takes effect immediately for all callers. With no tracer set, they run the
+// work untraced. The name argument may be a plain string or an attributes object
+// carrying the name (see `Name`).
+function trace(name, f) {
+    if (!current) {
+        return f();
+    }
+    const t = named(name);
+    return current.trace(t.name, t.attributes, f);
+}
+function traceP(name, f) {
+    if (!current) {
+        return f();
+    }
+    const t = named(name);
+    return current.traceP(t.name, t.attributes, f);
+}
+function traceF(name, f) {
+    if (!current) {
+        return f;
+    }
+    const t = named(name);
+    return current.traceF(t.name, t.attributes, f);
+}
+// Record a named, timestamped marker on whatever trace is currently active — for
+// annotating "something happened here" (a cache miss, a retry, a validation
+// failure) at a point in time, without opening a child trace. A no-op when no
+// trace is active (or no tracer is set).
+function event(name, attributes) {
+    current?.event(name, attributes);
+}
+// Split a `Name` into the trace name and its attributes.
+function named(name) {
+    if (typeof name === "string") {
+        return { name, attributes: {} };
+    }
+    const { name: n, ...attributes } = name;
+    return { name: n, attributes };
+}

package/dist/trampoline.d.ts

@@ -0,0 +1,24 @@
+export { type Trampoline, tailRecursive, end, fix };
+/**
+ * A value that represents a suspended recursive computation.
+ *
+ * Use `tailRecursive` or `fix` to build trampolined functions that won't
+ * blow the stack on deeply recursive calls. Call `.run()` to evaluate.
+ */
+type Trampoline<A> = End<A> | Rec<A>;
+declare const end: <A>(v: A) => Trampoline<A>;
+declare class End<A> {
+    value: A;
+    constructor(v: A);
+    run(): A;
+    map<B>(f: (v: A) => B): Trampoline<B>;
+}
+declare class Rec<A> {
+    fun: () => Trampoline<A>;
+    constructor(f: () => Trampoline<A>);
+    run(): A;
+    map<B>(f: (v: A) => B): Trampoline<B>;
+}
+type Fun<A extends unknown[], B> = (...args: A) => B;
+declare function fix<A extends unknown[], R>(f: Fun<[Fun<A, Trampoline<R>>, (r: R) => Trampoline<R>], Fun<A, Trampoline<R>>>): Fun<A, R>;
+declare function tailRecursive<A extends unknown[], R>(f: Fun<A, Trampoline<R>>): Fun<A, Trampoline<R>>;

package/dist/trampoline.js

@@ -0,0 +1,46 @@
+export { tailRecursive, end, fix };
+function run(tramp) {
+    let result = tramp;
+    while (result instanceof Rec) {
+        result = result.fun();
+    }
+    return result.value;
+}
+const rec = (f) => new Rec(f);
+const end = (v) => new End(v);
+class End {
+    value;
+    constructor(v) {
+        this.value = v;
+    }
+    run() {
+        return run(this);
+    }
+    map(f) {
+        return end(f(this.value));
+    }
+}
+class Rec {
+    fun;
+    constructor(f) {
+        this.fun = f;
+    }
+    run() {
+        return run(this);
+    }
+    map(f) {
+        const v = this.fun();
+        return rec(() => v.map(f));
+    }
+}
+function fix(f) {
+    let lazy_f = (..._) => {
+        throw new Error("recursion error");
+    };
+    const recurse = (...args) => rec(() => lazy_f(...args));
+    lazy_f = f(recurse, end);
+    return (...args) => lazy_f(...args).run();
+}
+function tailRecursive(f) {
+    return (...args) => rec(() => f(...args));
+}

package/dist/tree-map.d.ts

@@ -0,0 +1,73 @@
+import { type default as BTreeType } from "sorted-btree";
+import { Maybe } from "./maybe";
+declare const stringMap: <T>() => TreeMap<string, T>;
+interface Comparable<T> {
+    compare(other: T): number;
+}
+/**
+ * Shared base for {@link TreeMap} and {@link ImmutableTreeMap}.
+ *
+ * Holds the BTree state, all read methods, and every bulk transformation.
+ * The only thing each subclass supplies is mutation methods and a `wrap`
+ * factory that lifts a fresh BTree back into its own kind.
+ */
+declare abstract class TreeMapCore<K, V> {
+    private readonly _;
+    protected tree: BTreeType<K, V>;
+    readonly compare: (l: K, r: K) => number;
+    protected constructor(tree: BTreeType<K, V>, compare: (l: K, r: K) => number);
+    /** Construct a new instance of the same subclass around a fresh BTree. */
+    protected abstract wrap<W>(tree: BTreeType<K, W>): TreeMapCore<K, W>;
+    get(k: K): Maybe<V>;
+    has(k: K): boolean;
+    keys(): IterableIterator<K>;
+    values(): IterableIterator<V>;
+    entries(): IterableIterator<[K, V]>;
+    size(): number;
+    clone(): this;
+    /** Create a new map with keys from both maps. */
+    unionWith(other: TreeMapCore<K, V>, f: (old: V, new_: V) => V): this;
+    /**
+     * Difference in the set of keys.
+     * `A.difference(B)` equals A minus all keys present in B.
+     */
+    difference(other: TreeMapCore<K, unknown>): this;
+    /** Create a new map from keys common to two other maps. */
+    intersectionWith<W, X>(other: TreeMapCore<K, W>, f: (left: V, right: W) => X): TreeMapCore<K, X>;
+    mapWithKeys<W>(f: (k: K, v: V) => W): TreeMapCore<K, W>;
+    map<W>(f: (v: V) => W): TreeMapCore<K, W>;
+}
+/**
+ * A mutable Map type that requires a comparison function.
+ *
+ * This is just a wrapper around BTree which requires the comparison function.
+ */
+declare class TreeMap<K, V> extends TreeMapCore<K, V> {
+    static new<K, V>(compare: (l: K, r: K) => number): TreeMap<K, V>;
+    static new_<K extends Comparable<K>, V>(): TreeMap<K, V>;
+    static from<K, V>(compare: (l: K, r: K) => number, xs: Array<[K, V]>): TreeMap<K, V>;
+    static from_<K extends Comparable<K>, V>(xs: Array<[K, V]>): TreeMap<K, V>;
+    protected wrap<W>(tree: BTreeType<K, W>): TreeMap<K, W>;
+    set(k: K, v: V): this;
+    setWith(k: K, v: V, f: (old: V, _new: V) => V): this;
+    remove(k: K): this;
+    setEntries(it: IterableIterator<[K, V]>): this;
+}
+/**
+ * An immutable Map type that requires a comparison function.
+ *
+ * Every update returns a new ImmutableTreeMap; the receiver is untouched.
+ * Each update clones the underlying BTree before mutating the copy.
+ */
+declare class ImmutableTreeMap<K, V> extends TreeMapCore<K, V> {
+    static new<K, V>(compare: (l: K, r: K) => number): ImmutableTreeMap<K, V>;
+    static new_<K extends Comparable<K>, V>(): ImmutableTreeMap<K, V>;
+    static from<K, V>(compare: (l: K, r: K) => number, xs: Array<[K, V]>): ImmutableTreeMap<K, V>;
+    static from_<K extends Comparable<K>, V>(xs: Array<[K, V]>): ImmutableTreeMap<K, V>;
+    protected wrap<W>(tree: BTreeType<K, W>): ImmutableTreeMap<K, W>;
+    set(k: K, v: V): ImmutableTreeMap<K, V>;
+    setWith(k: K, v: V, f: (old: V, _new: V) => V): ImmutableTreeMap<K, V>;
+    remove(k: K): ImmutableTreeMap<K, V>;
+    setEntries(it: IterableIterator<[K, V]>): ImmutableTreeMap<K, V>;
+}
+export { TreeMap, ImmutableTreeMap, TreeMapCore, stringMap };