@redthreadlabs/tracelog-client 2.1.0 → 2.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redthreadlabs/tracelog-client",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Lightweight logging client for tracelog — works in React Native and browsers",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -12,7 +12,8 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc",
     "prepublishOnly": "npm run build",
     "pretest": "npm run build",
     "test": "node --test"

package/dist/LogClient.d.ts

@@ -1,71 +0,0 @@
-import { EventBuilder } from './EventBuilder';
-import { EndOptions, LogClientOptions, RecordOptions, StartOptions } from './types';
-export declare class LogClient {
-    private _opts;
-    private _eventBuffer;
-    private _transactionBuffer;
-    private _spanBuffer;
-    private _activeSpans;
-    /** Per-launch id; the join key between records and this lifetime's origin. */
-    private readonly _lifetimeId;
-    /** JSON of the last origin sent, to detect changes (null ⇒ not yet sent). */
-    private _lastOriginJson;
-    private _flushHandle;
-    private _persistHandle;
-    private _disposed;
-    private _flushing;
-    constructor(opts: LogClientOptions);
-    /** This LogClient's lifetime id (one per launch / process run). */
-    get lifetimeId(): string;
-    event(type?: string): EventBuilder;
-    /** Start a root timed operation (a trace root). Recorded as a transaction. */
-    startTransaction(name: string, opts?: StartOptions): Transaction;
-    /** Start a sub-operation under a transaction or span. Recorded as a span. */
-    startSpan(name: string, parent: Transaction | Span, opts?: StartOptions): Span;
-    /** Internal: end a live transaction/span by id (called by the handles). */
-    _end(id: string, opts?: EndOptions): void;
-    /** Record a complete root operation timed elsewhere → a transaction. */
-    recordTransaction(name: string, durationMs: number, opts?: RecordOptions): void;
-    /** Record a complete sub-operation timed elsewhere → a span under `parent`. */
-    recordSpan(name: string, durationMs: number, parent: Transaction | Span, opts?: RecordOptions): void;
-    private _belowThreshold;
-    private _buildOneShot;
-    flush(): Promise<void>;
-    dispose(): void;
-    private _enqueueEvent;
-    private _enqueueTransaction;
-    private _enqueueSpan;
-    private _afterEnqueue;
-    /** The origin to attach to this flush, or undefined if unchanged since last sent. */
-    private _takeOriginIfChanged;
-    private _sendInChunks;
-    private _sendChunkWithRetry;
-    private _sendChunk;
-    private _schedulePersist;
-    private _persistNow;
-    private _loadPersistedLogs;
-}
-/** A live root operation. Recorded as a `transaction` when ended. */
-export declare class Transaction {
-    private readonly _client;
-    readonly id: string;
-    readonly traceId: string;
-    readonly type: string;
-    constructor(_client: LogClient, id: string, traceId: string, type: string);
-    /** A transaction is its own trace root. */
-    get transactionId(): string;
-    startSpan(name: string, opts?: StartOptions): Span;
-    end(opts?: EndOptions): void;
-}
-/** A live sub-operation. Recorded as a `span` when ended. */
-export declare class Span {
-    private readonly _client;
-    readonly id: string;
-    readonly traceId: string;
-    readonly transactionId: string;
-    readonly parentId: string;
-    readonly type: string;
-    constructor(_client: LogClient, id: string, traceId: string, transactionId: string, parentId: string, type: string);
-    startSpan(name: string, opts?: StartOptions): Span;
-    end(opts?: EndOptions): void;
-}

package/dist/LogClient.js

@@ -1,399 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Span = exports.Transaction = exports.LogClient = void 0;
-const EventBuilder_1 = require("./EventBuilder");
-const util_1 = require("./util");
-// Level ordering for the optional getMinLevel gate. An event is dropped when
-// its level ranks below the host-supplied minimum.
-const LEVEL_RANK = { debug: 0, info: 1, warn: 2, error: 3 };
-const DEFAULT_TYPE = 'app';
-// Defaults (all overridable via LogClientOptions)
-const DEFAULT_FLUSH_CADENCE_MS = 5000;
-const DEFAULT_MAX_BUFFER_SIZE = 100;
-const DEFAULT_MAX_CHUNK_SIZE = 50;
-const DEFAULT_MAX_CHUNK_BYTES = 512 * 1024;
-const INTER_CHUNK_DELAY_MS = 200;
-const MAX_RETRIES = 3;
-const BASE_RETRY_DELAY_MS = 1000;
-const PERSIST_DEBOUNCE_MS = 100;
-class LogClient {
-    constructor(opts) {
-        this._eventBuffer = [];
-        this._transactionBuffer = [];
-        this._spanBuffer = [];
-        this._activeSpans = new Map();
-        /** Per-launch id; the join key between records and this lifetime's origin. */
-        this._lifetimeId = randomHex(16);
-        /** JSON of the last origin sent, to detect changes (null ⇒ not yet sent). */
-        this._lastOriginJson = null;
-        this._flushHandle = null;
-        this._persistHandle = null;
-        this._disposed = false;
-        this._flushing = false;
-        this._opts = opts;
-        this._loadPersistedLogs();
-        this._flushHandle = setInterval(() => this.flush(), opts.flushCadenceMs ?? DEFAULT_FLUSH_CADENCE_MS);
-    }
-    /** This LogClient's lifetime id (one per launch / process run). */
-    get lifetimeId() {
-        return this._lifetimeId;
-    }
-    // ---- Fluent event builder ----
-    event(type = 'client-log') {
-        return new EventBuilder_1.EventBuilder((evt) => this._enqueueEvent(evt), type);
-    }
-    // ---- Live traces: transactions & spans ----
-    /** Start a root timed operation (a trace root). Recorded as a transaction. */
-    startTransaction(name, opts) {
-        const id = randomHex(16);
-        const trace_id = randomHex(32);
-        const type = opts?.type ?? DEFAULT_TYPE;
-        this._activeSpans.set(id, {
-            kind: 'transaction', id, trace_id, name, type,
-            startTime: now(), tzOffset: (0, util_1.tzOffsetMinutes)(), children: [],
-        });
-        return new Transaction(this, id, trace_id, type);
-    }
-    /** Start a sub-operation under a transaction or span. Recorded as a span. */
-    startSpan(name, parent, opts) {
-        const id = randomHex(16);
-        const type = opts?.type ?? DEFAULT_TYPE;
-        this._activeSpans.set(id, {
-            kind: 'span', id,
-            trace_id: parent.traceId,
-            transaction_id: parent.transactionId,
-            parent_id: parent.id,
-            name, type,
-            startTime: now(), tzOffset: (0, util_1.tzOffsetMinutes)(), children: [],
-        });
-        this._activeSpans.get(parent.id)?.children.push(id);
-        return new Span(this, id, parent.traceId, parent.transactionId, parent.id, type);
-    }
-    /** Internal: end a live transaction/span by id (called by the handles). */
-    _end(id, opts) {
-        const active = this._activeSpans.get(id);
-        if (!active)
-            return;
-        // Auto-close any children not yet ended, so a forgotten child can't leak.
-        for (const childId of active.children) {
-            if (this._activeSpans.has(childId))
-                this._end(childId);
-        }
-        const duration = Math.max(0, now() - active.startTime);
-        const base = {
-            id: active.id,
-            trace_id: active.trace_id,
-            name: active.name,
-            type: active.type,
-            timestamp: Math.round(active.startTime * 1000), // ms → µs
-            duration: Math.round(duration),
-            outcome: opts?.outcome ?? 'success',
-            tz_offset: active.tzOffset,
-            ...(opts?.labels && Object.keys(opts.labels).length > 0 ? { context: { labels: opts.labels } } : {}),
-        };
-        this._activeSpans.delete(id);
-        if (active.kind === 'transaction') {
-            this._enqueueTransaction(base);
-        }
-        else {
-            this._enqueueSpan({ ...base, transaction_id: active.transaction_id, parent_id: active.parent_id });
-        }
-    }
-    // ---- One-shot (pre-measured) traces ----
-    /** Record a complete root operation timed elsewhere → a transaction. */
-    recordTransaction(name, durationMs, opts) {
-        if (this._disposed || this._belowThreshold(durationMs, opts))
-            return;
-        const id = randomHex(16);
-        this._enqueueTransaction(this._buildOneShot(id, randomHex(32), name, durationMs, opts));
-    }
-    /** Record a complete sub-operation timed elsewhere → a span under `parent`. */
-    recordSpan(name, durationMs, parent, opts) {
-        if (this._disposed || this._belowThreshold(durationMs, opts))
-            return;
-        const id = randomHex(16);
-        const rec = this._buildOneShot(id, parent.traceId, name, durationMs, opts);
-        rec.transaction_id = parent.transactionId;
-        rec.parent_id = parent.id;
-        this._enqueueSpan(rec);
-    }
-    _belowThreshold(durationMs, opts) {
-        return opts?.minDurationMs !== undefined && durationMs < opts.minDurationMs;
-    }
-    _buildOneShot(id, trace_id, name, durationMs, opts) {
-        const d = isFinite(durationMs) && durationMs > 0 ? durationMs : 0;
-        const rec = {
-            id, trace_id, name,
-            type: opts?.type ?? DEFAULT_TYPE,
-            // No live start, so back-compute it from the measured duration.
-            timestamp: Math.round((now() - d) * 1000), // ms → µs
-            duration: Math.round(d),
-            outcome: opts?.outcome ?? 'success',
-            tz_offset: (0, util_1.tzOffsetMinutes)(),
-        };
-        if (opts?.labels && Object.keys(opts.labels).length > 0)
-            rec.context = { labels: opts.labels };
-        return rec;
-    }
-    // ---- Transport ----
-    async flush() {
-        if (this._disposed || this._flushing)
-            return;
-        if (this._eventBuffer.length === 0 && this._transactionBuffer.length === 0 && this._spanBuffer.length === 0)
-            return;
-        this._flushing = true;
-        try {
-            const events = this._eventBuffer.splice(0);
-            const transactions = this._transactionBuffer.splice(0);
-            const spans = this._spanBuffer.splice(0);
-            const origin = this._takeOriginIfChanged();
-            await this._sendInChunks(events, transactions, spans, origin);
-        }
-        finally {
-            this._flushing = false;
-            this._schedulePersist();
-        }
-    }
-    dispose() {
-        if (this._disposed)
-            return;
-        this._disposed = true;
-        if (this._flushHandle) {
-            clearInterval(this._flushHandle);
-            this._flushHandle = null;
-        }
-        if (this._persistHandle) {
-            clearTimeout(this._persistHandle);
-            this._persistHandle = null;
-        }
-        this._persistNow();
-    }
-    // ---- Internal: buffering ----
-    _enqueueEvent(event) {
-        if (this._disposed)
-            return;
-        // Level gate: drop events below the host-supplied minimum before buffering.
-        const minLevel = this._opts.getMinLevel?.();
-        if (minLevel && LEVEL_RANK[event.level] < LEVEL_RANK[minLevel])
-            return;
-        if (event.locale === undefined) {
-            const locale = this._opts.getLocale?.();
-            if (locale)
-                event.locale = locale;
-        }
-        this._eventBuffer.push(event);
-        this._afterEnqueue();
-    }
-    _enqueueTransaction(rec) {
-        if (this._disposed)
-            return;
-        this._transactionBuffer.push(rec);
-        this._afterEnqueue();
-    }
-    _enqueueSpan(rec) {
-        if (this._disposed)
-            return;
-        this._spanBuffer.push(rec);
-        this._afterEnqueue();
-    }
-    _afterEnqueue() {
-        this._schedulePersist();
-        const total = this._eventBuffer.length + this._transactionBuffer.length + this._spanBuffer.length;
-        if (total >= (this._opts.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE))
-            this.flush();
-    }
-    /** The origin to attach to this flush, or undefined if unchanged since last sent. */
-    _takeOriginIfChanged() {
-        let origin;
-        try {
-            origin = this._opts.getOrigin();
-        }
-        catch {
-            return undefined;
-        }
-        const oj = JSON.stringify(origin);
-        if (oj === this._lastOriginJson)
-            return undefined;
-        this._lastOriginJson = oj;
-        return { ...origin, lifetime_id: this._lifetimeId };
-    }
-    // ---- Internal: chunked sending ----
-    async _sendInChunks(events, transactions, spans, origin) {
-        const maxChunkSize = this._opts.maxChunkSize ?? DEFAULT_MAX_CHUNK_SIZE;
-        const maxChunkBytes = this._opts.maxChunkBytes ?? DEFAULT_MAX_CHUNK_BYTES;
-        const work = [
-            ...events.map((rec) => ({ k: 'e', rec })),
-            ...transactions.map((rec) => ({ k: 't', rec })),
-            ...spans.map((rec) => ({ k: 's', rec })),
-        ];
-        let i = 0;
-        let isFirst = true;
-        while (i < work.length || (isFirst && origin)) {
-            if (!isFirst)
-                await delay(INTER_CHUNK_DELAY_MS);
-            const ce = [];
-            const ct = [];
-            const cs = [];
-            let bytes = 200; // base overhead for the batch envelope
-            while (i < work.length && (ce.length + ct.length + cs.length) < maxChunkSize) {
-                const item = work[i];
-                const itemBytes = estimateJsonSize(item.rec);
-                if (bytes + itemBytes > maxChunkBytes && (ce.length + ct.length + cs.length) > 0)
-                    break;
-                if (item.k === 'e')
-                    ce.push(item.rec);
-                else if (item.k === 't')
-                    ct.push(item.rec);
-                else
-                    cs.push(item.rec);
-                bytes += itemBytes;
-                i++;
-            }
-            const chunkOrigin = isFirst ? origin : undefined;
-            isFirst = false;
-            if (ce.length === 0 && ct.length === 0 && cs.length === 0 && !chunkOrigin)
-                break;
-            await this._sendChunkWithRetry(ce, ct, cs, chunkOrigin);
-        }
-    }
-    async _sendChunkWithRetry(events, transactions, spans, origin) {
-        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-            try {
-                await this._sendChunk(events, transactions, spans, origin);
-                return;
-            }
-            catch {
-                if (attempt < MAX_RETRIES) {
-                    await delay(BASE_RETRY_DELAY_MS * Math.pow(2, attempt));
-                }
-                else {
-                    // Max retries exceeded — put records back for persistence/retry, and
-                    // re-arm the origin so it ships again on the next successful flush.
-                    this._eventBuffer.push(...events);
-                    this._transactionBuffer.push(...transactions);
-                    this._spanBuffer.push(...spans);
-                    if (origin)
-                        this._lastOriginJson = null;
-                    this._schedulePersist();
-                }
-            }
-        }
-    }
-    async _sendChunk(events, transactions, spans, origin) {
-        const batch = { events, transactions, spans };
-        batch.lifetime_id = this._lifetimeId;
-        const userId = this._opts.getUserId?.();
-        const deviceId = this._opts.getDeviceId?.();
-        if (userId)
-            batch.user_id = userId;
-        if (deviceId)
-            batch.device_id = deviceId;
-        if (origin)
-            batch.origin = origin;
-        const headers = await Promise.resolve(this._opts.getAuthHeaders());
-        const response = await fetch(this._opts.endpoint, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json', ...headers },
-            body: JSON.stringify(batch),
-        });
-        if (!response.ok)
-            throw new Error(`Server returned ${response.status}`);
-    }
-    // ---- Internal: persistence ----
-    _schedulePersist() {
-        if (this._persistHandle || !this._opts.persistLogs)
-            return;
-        this._persistHandle = setTimeout(() => {
-            this._persistHandle = null;
-            this._persistNow();
-        }, PERSIST_DEBOUNCE_MS);
-    }
-    _persistNow() {
-        if (!this._opts.persistLogs)
-            return;
-        if (this._eventBuffer.length === 0 && this._transactionBuffer.length === 0 && this._spanBuffer.length === 0) {
-            this._opts.persistLogs('').catch(() => { });
-            return;
-        }
-        const data = JSON.stringify({
-            events: this._eventBuffer,
-            transactions: this._transactionBuffer,
-            spans: this._spanBuffer,
-        });
-        this._opts.persistLogs(data).catch(() => { });
-    }
-    async _loadPersistedLogs() {
-        if (!this._opts.loadPersistedLogs)
-            return;
-        try {
-            const data = await this._opts.loadPersistedLogs();
-            if (!data)
-                return;
-            const parsed = JSON.parse(data);
-            if (Array.isArray(parsed.events))
-                this._eventBuffer.push(...parsed.events);
-            if (Array.isArray(parsed.transactions))
-                this._transactionBuffer.push(...parsed.transactions);
-            if (Array.isArray(parsed.spans))
-                this._spanBuffer.push(...parsed.spans);
-            this._opts.persistLogs?.('').catch(() => { });
-        }
-        catch {
-            // Ignore parse errors from corrupted persisted data
-        }
-    }
-}
-exports.LogClient = LogClient;
-// ---- Trace handles ----
-/** A live root operation. Recorded as a `transaction` when ended. */
-class Transaction {
-    constructor(_client, id, traceId, type) {
-        this._client = _client;
-        this.id = id;
-        this.traceId = traceId;
-        this.type = type;
-    }
-    /** A transaction is its own trace root. */
-    get transactionId() { return this.id; }
-    startSpan(name, opts) { return this._client.startSpan(name, this, opts); }
-    end(opts) { this._client._end(this.id, opts); }
-}
-exports.Transaction = Transaction;
-/** A live sub-operation. Recorded as a `span` when ended. */
-class Span {
-    constructor(_client, id, traceId, transactionId, parentId, type) {
-        this._client = _client;
-        this.id = id;
-        this.traceId = traceId;
-        this.transactionId = transactionId;
-        this.parentId = parentId;
-        this.type = type;
-    }
-    startSpan(name, opts) { return this._client.startSpan(name, this, opts); }
-    end(opts) { this._client._end(this.id, opts); }
-}
-exports.Span = Span;
-// ---- Helpers ----
-function randomHex(length) {
-    const chars = '0123456789abcdef';
-    let result = '';
-    for (let i = 0; i < length; i++) {
-        result += chars[Math.floor(Math.random() * 16)];
-    }
-    return result;
-}
-function now() {
-    if (typeof performance !== 'undefined' && performance.now) {
-        if (!now._offset) {
-            now._offset = Date.now() - performance.now();
-        }
-        return now._offset + performance.now();
-    }
-    return Date.now();
-}
-function delay(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
-}
-function estimateJsonSize(obj) {
-    return JSON.stringify(obj).length;
-}