@private.me/xbind 3.0.2 → 3.0.4

package/dist-standalone/cjs/trace-spans.js

@@ -1,495 +1 @@
-"use strict";
-/**
- * @module trace-spans
- * Distributed tracing spans with parent-child relationships
- *
- * Provides span tracking for distributed tracing with automatic timing,
- * attribute collection, and integration with W3C Trace Context.
- *
- * Performance target: <1ms overhead per operation
- *
- * Usage:
- * ```typescript
- * import { TraceSpan, SpanRecorder } from '@private.me/xbind';
- *
- * // Create a span recorder
- * const recorder = new SpanRecorder();
- *
- * // Start a span
- * const span = recorder.startSpan('operation-name', { attr: 'value' });
- *
- * // Do work...
- *
- * // End the span
- * span.end();
- *
- * // Get completed spans
- * const spans = recorder.getCompletedSpans();
- * ```
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SpanRecorder = exports.TraceSpan = exports.SpanKind = exports.SpanStatusCode = void 0;
-exports.measureAsync = measureAsync;
-exports.measureSync = measureSync;
-const trace_context_js_1 = require("./trace-context.js");
-/**
- * Span status codes (aligned with OpenTelemetry)
- */
-var SpanStatusCode;
-(function (SpanStatusCode) {
-    /** Operation completed successfully */
-    SpanStatusCode[SpanStatusCode["OK"] = 0] = "OK";
-    /** Operation encountered an error */
-    SpanStatusCode[SpanStatusCode["ERROR"] = 1] = "ERROR";
-    /** Status is unset (default) */
-    SpanStatusCode[SpanStatusCode["UNSET"] = 2] = "UNSET";
-})(SpanStatusCode || (exports.SpanStatusCode = SpanStatusCode = {}));
-/**
- * Span kind (aligned with OpenTelemetry)
- */
-var SpanKind;
-(function (SpanKind) {
-    /** Internal span (default) */
-    SpanKind[SpanKind["INTERNAL"] = 0] = "INTERNAL";
-    /** Server span (handling incoming request) */
-    SpanKind[SpanKind["SERVER"] = 1] = "SERVER";
-    /** Client span (outgoing request) */
-    SpanKind[SpanKind["CLIENT"] = 2] = "CLIENT";
-    /** Producer span (message queue producer) */
-    SpanKind[SpanKind["PRODUCER"] = 3] = "PRODUCER";
-    /** Consumer span (message queue consumer) */
-    SpanKind[SpanKind["CONSUMER"] = 4] = "CONSUMER";
-})(SpanKind || (exports.SpanKind = SpanKind = {}));
-/**
- * Trace span for distributed tracing
- *
- * Represents a single unit of work in a distributed trace with automatic timing.
- */
-class TraceSpan {
-    /** Span ID (unique within trace) */
-    spanId;
-    /** Trace context */
-    traceContext;
-    /** Span name */
-    name;
-    /** Span kind */
-    kind;
-    /** Parent span ID */
-    parentSpanId;
-    /** Start timestamp (milliseconds since epoch) */
-    startTime;
-    /** End timestamp (milliseconds since epoch, undefined if not ended) */
-    endTime;
-    /** Span status */
-    status;
-    /** Span attributes */
-    attributes;
-    /** Span events */
-    events;
-    /** Whether span has ended */
-    ended;
-    /**
-     * Create a trace span
-     *
-     * @param name - Span name
-     * @param traceContext - Trace context
-     * @param options - Span options
-     */
-    constructor(name, traceContext, options = {}) {
-        this.spanId = (0, trace_context_js_1.generateSpanId)();
-        this.traceContext = traceContext;
-        this.name = name;
-        this.kind = options.kind ?? SpanKind.INTERNAL;
-        this.parentSpanId = options.parentSpanId;
-        this.startTime = Date.now();
-        this.status = { code: SpanStatusCode.UNSET };
-        this.attributes = options.attributes ?? {};
-        this.events = [];
-        this.ended = false;
-    }
-    /**
-     * Set span attribute
-     *
-     * @param key - Attribute key
-     * @param value - Attribute value
-     * @returns This span (for chaining)
-     */
-    setAttribute(key, value) {
-        if (this.ended) {
-            throw new Error('Cannot set attribute on ended span');
-        }
-        this.attributes[key] = value;
-        return this;
-    }
-    /**
-     * Set multiple span attributes
-     *
-     * @param attributes - Attributes to set
-     * @returns This span (for chaining)
-     */
-    setAttributes(attributes) {
-        if (this.ended) {
-            throw new Error('Cannot set attributes on ended span');
-        }
-        Object.assign(this.attributes, attributes);
-        return this;
-    }
-    /**
-     * Add an event to the span
-     *
-     * Events are timestamped log entries within a span.
-     *
-     * @param name - Event name
-     * @param attributes - Optional event attributes
-     * @returns This span (for chaining)
-     */
-    addEvent(name, attributes) {
-        if (this.ended) {
-            throw new Error('Cannot add event to ended span');
-        }
-        this.events.push({
-            name,
-            timestamp: Date.now(),
-            attributes,
-        });
-        return this;
-    }
-    /**
-     * Set span status
-     *
-     * @param code - Status code
-     * @param message - Optional status message
-     * @returns This span (for chaining)
-     */
-    setStatus(code, message) {
-        if (this.ended) {
-            throw new Error('Cannot set status on ended span');
-        }
-        this.status = { code, message };
-        return this;
-    }
-    /**
-     * Record an exception in the span
-     *
-     * Automatically sets status to ERROR and adds exception event.
-     *
-     * @param error - Error to record
-     * @returns This span (for chaining)
-     */
-    recordException(error) {
-        if (this.ended) {
-            throw new Error('Cannot record exception on ended span');
-        }
-        this.setStatus(SpanStatusCode.ERROR);
-        const attributes = {};
-        if (error instanceof Error) {
-            attributes['exception.type'] = error.name;
-            attributes['exception.message'] = error.message;
-            if (error.stack) {
-                attributes['exception.stacktrace'] = error.stack;
-            }
-        }
-        else {
-            attributes['exception.message'] = String(error);
-        }
-        this.addEvent('exception', attributes);
-        return this;
-    }
-    /**
-     * End the span
-     *
-     * Records the end timestamp and marks the span as complete.
-     * If status is UNSET, automatically sets to OK.
-     *
-     * @param endTime - Optional end timestamp (defaults to now)
-     */
-    end(endTime) {
-        if (this.ended) {
-            return; // Idempotent
-        }
-        this.endTime = endTime ?? Date.now();
-        this.ended = true;
-        // Auto-set status to OK if unset
-        if (this.status.code === SpanStatusCode.UNSET) {
-            this.status = { code: SpanStatusCode.OK };
-        }
-    }
-    /**
-     * Check if span has ended
-     *
-     * @returns True if ended
-     */
-    isEnded() {
-        return this.ended;
-    }
-    /**
-     * Get span duration in milliseconds
-     *
-     * @returns Duration or null if not ended
-     */
-    getDuration() {
-        if (!this.ended || !this.endTime)
-            return null;
-        return this.endTime - this.startTime;
-    }
-    /**
-     * Export span data
-     *
-     * @returns Span data (throws if span not ended)
-     */
-    toData() {
-        if (!this.ended || !this.endTime) {
-            throw new Error('Cannot export data from active span. Call end() first.');
-        }
-        return {
-            spanId: this.spanId,
-            traceId: this.traceContext.traceId,
-            parentSpanId: this.parentSpanId,
-            name: this.name,
-            kind: this.kind,
-            startTime: this.startTime,
-            endTime: this.endTime,
-            duration: this.endTime - this.startTime,
-            status: { ...this.status },
-            attributes: { ...this.attributes },
-            events: this.events.map((e) => ({
-                name: e.name,
-                timestamp: e.timestamp,
-                attributes: e.attributes ? { ...e.attributes } : undefined,
-            })),
-        };
-    }
-    /**
-     * Create a child span
-     *
-     * The child span will have the same trace ID but a new span ID.
-     *
-     * @param name - Child span name
-     * @param options - Span options
-     * @returns New child span
-     */
-    createChild(name, options = {}) {
-        return new TraceSpan(name, this.traceContext, {
-            ...options,
-            parentSpanId: this.spanId,
-        });
-    }
-}
-exports.TraceSpan = TraceSpan;
-/**
- * Span recorder for collecting completed spans
- *
- * Manages span lifecycle and provides access to completed span data.
- */
-class SpanRecorder {
-    /** Active spans (not yet ended) */
-    activeSpans;
-    /** Completed spans */
-    completedSpans;
-    /** Maximum number of completed spans to keep (prevent memory leak) */
-    maxSpans;
-    /** Trace context for root spans */
-    rootContext;
-    /**
-     * Create a span recorder
-     *
-     * @param options - Recorder options
-     */
-    constructor(options = {}) {
-        this.activeSpans = new Map();
-        this.completedSpans = [];
-        this.maxSpans = options.maxSpans ?? 1000;
-        this.rootContext = options.traceContext;
-    }
-    /**
-     * Start a new span
-     *
-     * @param name - Span name
-     * @param options - Span options
-     * @returns New span
-     */
-    startSpan(name, options = {}) {
-        const context = options.traceContext ??
-            options.parentSpan?.traceContext ??
-            this.rootContext ??
-            trace_context_js_1.TraceContext.create();
-        const span = new TraceSpan(name, context, {
-            kind: options.kind,
-            attributes: options.attributes,
-            parentSpanId: options.parentSpan?.spanId,
-        });
-        this.activeSpans.set(span.spanId, span);
-        // Auto-end on next tick if forgotten (safety measure)
-        // This prevents memory leaks from forgotten spans
-        const timeout = setTimeout(() => {
-            if (!span.isEnded()) {
-                span.setStatus(SpanStatusCode.ERROR, 'Span not ended (auto-ended by recorder)');
-                this.endSpan(span);
-            }
-        }, 60000); // 60 second timeout
-        // Clear timeout if span ends normally
-        const originalEnd = span.end.bind(span);
-        span.end = (endTime) => {
-            clearTimeout(timeout);
-            originalEnd(endTime);
-            this.endSpan(span);
-        };
-        return span;
-    }
-    /**
-     * End a span and record its data
-     *
-     * @param span - Span to end
-     */
-    endSpan(span) {
-        if (!span.isEnded()) {
-            span.end();
-        }
-        // Remove from active spans
-        this.activeSpans.delete(span.spanId);
-        // Add to completed spans
-        const data = span.toData();
-        this.completedSpans.push(data);
-        // Enforce max spans limit (FIFO)
-        if (this.completedSpans.length > this.maxSpans) {
-            this.completedSpans.shift();
-        }
-    }
-    /**
-     * Get all completed spans
-     *
-     * @returns Array of completed span data
-     */
-    getCompletedSpans() {
-        return [...this.completedSpans];
-    }
-    /**
-     * Get active spans
-     *
-     * @returns Array of active spans
-     */
-    getActiveSpans() {
-        return Array.from(this.activeSpans.values());
-    }
-    /**
-     * Clear all completed spans
-     */
-    clearCompletedSpans() {
-        this.completedSpans = [];
-    }
-    /**
-     * Get span count
-     *
-     * @returns Object with active and completed span counts
-     */
-    getSpanCount() {
-        return {
-            active: this.activeSpans.size,
-            completed: this.completedSpans.length,
-        };
-    }
-    /**
-     * Find completed spans by trace ID
-     *
-     * @param traceId - Trace ID to search for
-     * @returns Array of matching spans
-     */
-    findSpansByTraceId(traceId) {
-        return this.completedSpans.filter((span) => span.traceId === traceId);
-    }
-    /**
-     * Build trace tree from completed spans
-     *
-     * Groups spans by trace ID and builds parent-child relationships.
-     *
-     * @param traceId - Trace ID to build tree for
-     * @returns Tree structure
-     */
-    buildTraceTree(traceId) {
-        const spans = this.findSpansByTraceId(traceId);
-        if (spans.length === 0)
-            return null;
-        // Find root span (no parent)
-        const root = spans.find((s) => !s.parentSpanId);
-        if (!root)
-            return null;
-        // Build tree recursively
-        return buildSpanTreeNode(root, spans);
-    }
-}
-exports.SpanRecorder = SpanRecorder;
-/**
- * Build span tree node recursively
- *
- * @param span - Current span
- * @param allSpans - All spans in trace
- * @returns Tree node
- */
-function buildSpanTreeNode(span, allSpans) {
-    const children = allSpans
-        .filter((s) => s.parentSpanId === span.spanId)
-        .map((child) => buildSpanTreeNode(child, allSpans));
-    return { span, children };
-}
-/**
- * Helper function to measure async operation with automatic span tracking
- *
- * @param recorder - Span recorder
- * @param name - Span name
- * @param fn - Async function to measure
- * @param options - Span options
- * @returns Result of async function
- *
- * @example
- * ```typescript
- * const result = await measureAsync(recorder, 'database-query', async () => {
- *   return await db.query('SELECT * FROM users');
- * });
- * ```
- */
-async function measureAsync(recorder, name, fn, options) {
-    const span = recorder.startSpan(name, options);
-    try {
-        const result = await fn();
-        span.setStatus(SpanStatusCode.OK);
-        return result;
-    }
-    catch (error) {
-        span.recordException(error);
-        throw error;
-    }
-    finally {
-        span.end();
-    }
-}
-/**
- * Helper function to measure sync operation with automatic span tracking
- *
- * @param recorder - Span recorder
- * @param name - Span name
- * @param fn - Sync function to measure
- * @param options - Span options
- * @returns Result of sync function
- *
- * @example
- * ```typescript
- * const result = measureSync(recorder, 'encryption', () => {
- *   return encrypt(data, key);
- * });
- * ```
- */
-function measureSync(recorder, name, fn, options) {
-    const span = recorder.startSpan(name, options);
-    try {
-        const result = fn();
-        span.setStatus(SpanStatusCode.OK);
-        return result;
-    }
-    catch (error) {
-        span.recordException(error);
-        throw error;
-    }
-    finally {
-        span.end();
-    }
-}
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.SpanRecorder=exports.TraceSpan=exports.SpanKind=exports.SpanStatusCode=void 0,exports.measureAsync=measureAsync,exports.measureSync=measureSync;const trace_context_js_1=require("./trace-context.js");var SpanStatusCode,SpanKind;!function(t){t[t.OK=0]="OK",t[t.ERROR=1]="ERROR",t[t.UNSET=2]="UNSET"}(SpanStatusCode||(exports.SpanStatusCode=SpanStatusCode={})),function(t){t[t.INTERNAL=0]="INTERNAL",t[t.SERVER=1]="SERVER",t[t.CLIENT=2]="CLIENT",t[t.PRODUCER=3]="PRODUCER",t[t.CONSUMER=4]="CONSUMER"}(SpanKind||(exports.SpanKind=SpanKind={}));class TraceSpan{spanId;traceContext;name;kind;parentSpanId;startTime;endTime;status;attributes;events;ended;constructor(t,e,n={}){this.spanId=(0,trace_context_js_1.generateSpanId)(),this.traceContext=e,this.name=t,this.kind=n.kind??SpanKind.INTERNAL,this.parentSpanId=n.parentSpanId,this.startTime=Date.now(),this.status={code:SpanStatusCode.UNSET},this.attributes=n.attributes??{},this.events=[],this.ended=!1}setAttribute(t,e){if(this.ended)throw new Error("Cannot set attribute on ended span");return this.attributes[t]=e,this}setAttributes(t){if(this.ended)throw new Error("Cannot set attributes on ended span");return Object.assign(this.attributes,t),this}addEvent(t,e){if(this.ended)throw new Error("Cannot add event to ended span");return this.events.push({name:t,timestamp:Date.now(),attributes:e}),this}setStatus(t,e){if(this.ended)throw new Error("Cannot set status on ended span");return this.status={code:t,message:e},this}recordException(t){if(this.ended)throw new Error("Cannot record exception on ended span");this.setStatus(SpanStatusCode.ERROR);const e={};return t instanceof Error?(e["exception.type"]=t.name,e["exception.message"]=t.message,t.stack&&(e["exception.stacktrace"]=t.stack)):e["exception.message"]=String(t),this.addEvent("exception",e),this}end(t){this.ended||(this.endTime=t??Date.now(),this.ended=!0,this.status.code===SpanStatusCode.UNSET&&(this.status={code:SpanStatusCode.OK}))}isEnded(){return this.ended}getDuration(){return this.ended&&this.endTime?this.endTime-this.startTime:null}toData(){if(!this.ended||!this.endTime)throw new Error("Cannot export data from active span. Call end() first.");return{spanId:this.spanId,traceId:this.traceContext.traceId,parentSpanId:this.parentSpanId,name:this.name,kind:this.kind,startTime:this.startTime,endTime:this.endTime,duration:this.endTime-this.startTime,status:{...this.status},attributes:{...this.attributes},events:this.events.map(t=>({name:t.name,timestamp:t.timestamp,attributes:t.attributes?{...t.attributes}:void 0}))}}createChild(t,e={}){return new TraceSpan(t,this.traceContext,{...e,parentSpanId:this.spanId})}}exports.TraceSpan=TraceSpan;class SpanRecorder{activeSpans;completedSpans;maxSpans;rootContext;constructor(t={}){this.activeSpans=new Map,this.completedSpans=[],this.maxSpans=t.maxSpans??1e3,this.rootContext=t.traceContext}startSpan(t,e={}){const n=e.traceContext??e.parentSpan?.traceContext??this.rootContext??trace_context_js_1.TraceContext.create(),s=new TraceSpan(t,n,{kind:e.kind,attributes:e.attributes,parentSpanId:e.parentSpan?.spanId});this.activeSpans.set(s.spanId,s);const a=setTimeout(()=>{s.isEnded()||(s.setStatus(SpanStatusCode.ERROR,"Span not ended (auto-ended by recorder)"),this.endSpan(s))},6e4),r=s.end.bind(s);return s.end=t=>{clearTimeout(a),r(t),this.endSpan(s)},s}endSpan(t){t.isEnded()||t.end(),this.activeSpans.delete(t.spanId);const e=t.toData();this.completedSpans.push(e),this.completedSpans.length>this.maxSpans&&this.completedSpans.shift()}getCompletedSpans(){return[...this.completedSpans]}getActiveSpans(){return Array.from(this.activeSpans.values())}clearCompletedSpans(){this.completedSpans=[]}getSpanCount(){return{active:this.activeSpans.size,completed:this.completedSpans.length}}findSpansByTraceId(t){return this.completedSpans.filter(e=>e.traceId===t)}buildTraceTree(t){const e=this.findSpansByTraceId(t);if(0===e.length)return null;const n=e.find(t=>!t.parentSpanId);return n?buildSpanTreeNode(n,e):null}}function buildSpanTreeNode(t,e){const n=e.filter(e=>e.parentSpanId===t.spanId).map(t=>buildSpanTreeNode(t,e));return{span:t,children:n}}async function measureAsync(t,e,n,s){const a=t.startSpan(e,s);try{const t=await n();return a.setStatus(SpanStatusCode.OK),t}catch(t){throw a.recordException(t),t}finally{a.end()}}function measureSync(t,e,n,s){const a=t.startSpan(e,s);try{const t=n();return a.setStatus(SpanStatusCode.OK),t}catch(t){throw a.recordException(t),t}finally{a.end()}}exports.SpanRecorder=SpanRecorder;

package/dist-standalone/cjs/transport.js

@@ -1,63 +1 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.HttpsTransportAdapter = void 0;
-const shared_1 = require("../_deps/shared/index.js");
-/**
- * HTTPS transport adapter — sends envelopes as JSON POST requests.
- *
- * Recipient URL resolved as: baseUrl/deliver/{recipientDid}
- * This is the SDK's default transport for server-to-server delivery.
- */
-class HttpsTransportAdapter {
-    baseUrl;
-    timeoutMs;
-    fetchFn;
-    handlers = [];
-    constructor(opts) {
-        this.baseUrl = opts.baseUrl.replace(/\/$/, '');
-        this.timeoutMs = opts.timeoutMs ?? 10_000;
-        this.fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
-    }
-    async send(envelope, recipientDid) {
-        const url = `${this.baseUrl}/deliver/${encodeURIComponent(recipientDid)}`;
-        try {
-            const controller = new AbortController();
-            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
-            const response = await this.fetchFn(url, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify(envelope),
-                signal: controller.signal,
-            });
-            clearTimeout(timer);
-            if (!response.ok) {
-                return (0, shared_1.err)(response.status === 404
-                    ? 'RECIPIENT_UNREACHABLE'
-                    : 'SEND_FAILED');
-            }
-            return (0, shared_1.ok)(undefined);
-        }
-        catch (e) {
-            if (e instanceof DOMException && e.name === 'AbortError') {
-                return (0, shared_1.err)('TIMEOUT');
-            }
-            return (0, shared_1.err)('NETWORK_ERROR');
-        }
-    }
-    onReceive(handler) {
-        this.handlers.push(handler);
-    }
-    /**
-     * Dispatch a received envelope to all handlers.
-     * Called by the server when an incoming POST is received.
-     */
-    dispatch(envelope) {
-        for (const handler of this.handlers) {
-            handler(envelope);
-        }
-    }
-    dispose() {
-        this.handlers = [];
-    }
-}
-exports.HttpsTransportAdapter = HttpsTransportAdapter;
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.HttpsTransportAdapter=void 0;const shared_1=require("../_deps/shared/index.js");class HttpsTransportAdapter{baseUrl;timeoutMs;fetchFn;handlers=[];constructor(t){if(!t.baseUrl||"string"!=typeof t.baseUrl)throw new TypeError("HttpsTransportOptions.baseUrl is required and must be a string");if(0===t.baseUrl.trim().length)throw new TypeError("HttpsTransportOptions.baseUrl cannot be empty");this.baseUrl=t.baseUrl.replace(/\/$/,""),this.timeoutMs=t.timeoutMs??1e4,this.fetchFn=t.fetch??globalThis.fetch.bind(globalThis)}async send(t,e){try{const t=new URL(this.baseUrl),e=t.hostname.toLowerCase(),r="127.0.0.1"===e||"localhost"===e||"[::1]"===e||"::1"===e||e.startsWith("127.")||e.endsWith(".localhost");if("https:"!==t.protocol&&!r)return(0,shared_1.err)("HTTPS_REQUIRED")}catch{return(0,shared_1.err)("INVALID_URL")}const r=`${this.baseUrl}/deliver/${encodeURIComponent(e)}`;try{const e=new AbortController,s=setTimeout(()=>e.abort(),this.timeoutMs),o=await this.fetchFn(r,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(t),signal:e.signal});return clearTimeout(s),o.ok?(0,shared_1.ok)(void 0):(0,shared_1.err)(404===o.status?"RECIPIENT_UNREACHABLE":"SEND_FAILED")}catch(t){return t instanceof DOMException&&"AbortError"===t.name?(0,shared_1.err)("TIMEOUT"):(0,shared_1.err)("NETWORK_ERROR")}}onReceive(t){this.handlers.push(t)}dispatch(t){for(const e of this.handlers)e(t)}dispose(){this.handlers=[]}}exports.HttpsTransportAdapter=HttpsTransportAdapter;