@lp-labs/trace-context 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Libin Prasanth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# @lp-labs/trace-context
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Bounded trace identifiers and span lifetimes with an injected context adapter. Independent,
+zero runtime/peer dependencies, MIT, Node >=18; ESM and CommonJS with strict declarations.
+
+## Install and quickstart
+
+```sh
+npm install @lp-labs/trace-context
+```
+
+```js
+import { webcrypto } from 'node:crypto';
+import { createTracer, parseTraceparent, formatTraceparent } from '@lp-labs/trace-context';
+
+let current;
+let time = 0;
+const tracer = createTracer({
+  randomFill: (bytes) => webcrypto.getRandomValues(bytes),
+  clock: () => time++,
+  adapter: {
+    get: () => current,
+    run(context, work) {
+      const previous = current;
+      current = context;
+      try {
+        return work();
+      } finally {
+        current = previous;
+      }
+    },
+  },
+});
+const parent = parseTraceparent('00-1234567890abcdef1234567890abcdef-1234567890abcdef-01');
+const span = tracer.start('订单', parent);
+tracer.run(span, () => console.log(formatTraceparent(tracer.current())));
+console.log(span.end().durationMs);
+```
+
+CommonJS: `const { createTracer } = require('@lp-labs/trace-context')`.
+
+## API and types
+
+- `parseTraceparent(header: string): TraceContext` accepts **only** the 55-character W3C
+  version-00 subset: lowercase hexadecimal, nonzero 32-digit trace ID, nonzero 16-digit
+  span ID, flags `00` or `01`. Whitespace, future versions, additional fields and other
+  flag bits are rejected. No tracestate or baggage implementation.
+- `formatTraceparent(context: TraceContext): string` validates and serializes that subset.
+- `TraceContext`: readonly `traceId: string`, `spanId: string`, `sampled: boolean`.
+- `createTracer(options: TracerOptions): Tracer`: requires `adapter: ContextAdapter`;
+  optional `clock: () => number` defaults to `performance.now()`, optional
+  `randomFill: (bytes: Uint8Array) => void` defaults to platform `crypto.getRandomValues`.
+- `ContextAdapter`: `get(): TraceContext | undefined`, generic
+  `run<T>(context: TraceContext, work: () => T): T`. Supply your own async-local adapter
+  if needed. The quickstart adapter is **synchronous only**; the package does not
+  guarantee async propagation or implicitly end spans.
+- `Tracer.current()` returns an immutable validated snapshot or undefined.
+  `start(name: string, parent?: TraceContext): Span` inherits current context by default,
+  retains trace ID/sampling and generates a child span ID. Root spans are unsampled.
+  Names accept 1–256 UTF-16 units, Unicode preserved exactly.
+  `run<T>(span: Span, work: () => T): T` delegates to the adapter.
+- `Span`: readonly `name`, `context`, `parentSpanId: string | undefined`, `startedAt: number`;
+  `end(): SpanResult` caches the first successful immutable result.
+- `SpanResult`: the same fields plus `endedAt: number`, `durationMs: number`.
+  Clock values must be finite and end cannot precede start.
+
+## Errors, customization and limits
+
+Invalid contexts, callbacks, adapters, names or clocks throw `TypeError`; backwards clocks
+and duration overflow throw `RangeError`. Missing secure platform randomness or an all-zero
+generated ID throws `Error`. Injected adapter, clock and random-source exceptions propagate;
+do not put sensitive data in their errors. Invalid span end attempts may be retried.
+
+Custom random fillers **must fill every byte cryptographically securely**. No `Math.random`
+fallback, retries or uniqueness guarantee. Node runtimes without global crypto should inject
+`node:crypto` as shown. No exporter, network calls, sampling engine, active span registry or
+background tasks. Per-span storage is constant; callers own span/context retention.
+Identifiers and names can be linkable: never encode personal data, secrets or baggage.
+Only identifiers propagate; this is not a privacy filter or complete W3C implementation.
+
+## Development
+
+`npm ci --offline`, `npm run build`, `npm run typecheck`, `npm test`,
+`npm run format`, `npm run format:check`. `npm run prepack` rebuilds.
+TypeScript ^5.9.3 and Prettier ^3.6.2 are development-only. Dual output is in `dist/esm`
+and `dist/cjs`; both bare-import `.mts`/`.cts` consumers are checked.
+
+## Support
+
+If this library is useful to you, consider supporting its maintenance with a [donation via PayPal](https://www.paypal.me/LibinPrasanth).
+
+## Author
+
+Created by [Libin Prasanth](https://www.linkedin.com/in/libinprasanth/). Connect on LinkedIn for updates and discussion.

package/dist/cjs/index.d.ts

@@ -0,0 +1,39 @@
+export interface TraceContext {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly sampled: boolean;
+}
+export interface ContextAdapter {
+    get(): TraceContext | undefined;
+    run<T>(context: TraceContext, work: () => T): T;
+}
+export interface Span {
+    readonly name: string;
+    readonly context: TraceContext;
+    readonly parentSpanId: string | undefined;
+    readonly startedAt: number;
+    end(): SpanResult;
+}
+export interface SpanResult {
+    readonly name: string;
+    readonly context: TraceContext;
+    readonly parentSpanId: string | undefined;
+    readonly startedAt: number;
+    readonly endedAt: number;
+    readonly durationMs: number;
+}
+export interface TracerOptions {
+    readonly adapter: ContextAdapter;
+    readonly clock?: () => number;
+    /** Must fill every byte with cryptographically secure randomness. */
+    readonly randomFill?: (bytes: Uint8Array) => void;
+}
+export interface Tracer {
+    current(): TraceContext | undefined;
+    start(name: string, parent?: TraceContext): Span;
+    run<T>(span: Span, work: () => T): T;
+}
+/** Only version 00, lowercase hex, and flags 00/01 are supported. */
+export declare function parseTraceparent(header: string): TraceContext;
+export declare function formatTraceparent(value: TraceContext): string;
+export declare function createTracer(options: TracerOptions): Tracer;

package/dist/cjs/index.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTraceparent = parseTraceparent;
+exports.formatTraceparent = formatTraceparent;
+exports.createTracer = createTracer;
+function context(value) {
+    if (!value ||
+        typeof value.traceId !== 'string' ||
+        typeof value.spanId !== 'string' ||
+        !/^[0-9a-f]{32}$/.test(value.traceId) ||
+        /^0+$/.test(value.traceId) ||
+        !/^[0-9a-f]{16}$/.test(value.spanId) ||
+        /^0+$/.test(value.spanId) ||
+        typeof value.sampled !== 'boolean')
+        throw new TypeError('Invalid trace context.');
+    return Object.freeze({ traceId: value.traceId, spanId: value.spanId, sampled: value.sampled });
+}
+/** Only version 00, lowercase hex, and flags 00/01 are supported. */
+function parseTraceparent(header) {
+    if (typeof header !== 'string' || !/^00-[0-9a-f]{32}-[0-9a-f]{16}-0[01]$/.test(header))
+        throw new TypeError('Unsupported or invalid traceparent.');
+    return context({
+        traceId: header.slice(3, 35),
+        spanId: header.slice(36, 52),
+        sampled: header.slice(53) === '01',
+    });
+}
+function formatTraceparent(value) {
+    const validated = context(value);
+    return `00-${validated.traceId}-${validated.spanId}-${validated.sampled ? '01' : '00'}`;
+}
+function createTracer(options) {
+    if (!options ||
+        typeof options.adapter?.get !== 'function' ||
+        typeof options.adapter.run !== 'function')
+        throw new TypeError('A context adapter is required.');
+    if (options.clock !== undefined && typeof options.clock !== 'function')
+        throw new TypeError('Invalid clock.');
+    if (options.randomFill !== undefined && typeof options.randomFill !== 'function')
+        throw new TypeError('Invalid random source.');
+    const adapter = options.adapter;
+    const clock = options.clock ?? (() => performance.now());
+    const fill = options.randomFill ??
+        ((bytes) => {
+            if (!globalThis.crypto?.getRandomValues)
+                throw new Error('Secure randomness is unavailable.');
+            globalThis.crypto.getRandomValues(bytes);
+        });
+    const now = () => {
+        const value = clock();
+        if (typeof value !== 'number' || !Number.isFinite(value))
+            throw new TypeError('Clock must return a finite number.');
+        return value;
+    };
+    const id = (length) => {
+        const bytes = new Uint8Array(length);
+        fill(bytes);
+        if (bytes.every((byte) => byte === 0))
+            throw new Error('Random source produced an all-zero ID.');
+        return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+    };
+    const current = () => {
+        const value = adapter.get();
+        return value === undefined ? undefined : context(value);
+    };
+    return {
+        current,
+        start(name, parent = current()) {
+            if (typeof name !== 'string' || name.length === 0 || name.length > 256)
+                throw new TypeError('Span name must contain 1 to 256 UTF-16 units.');
+            const ancestor = parent === undefined ? undefined : context(parent);
+            const child = context({
+                traceId: ancestor?.traceId ?? id(16),
+                spanId: id(8),
+                sampled: ancestor?.sampled ?? false,
+            });
+            const startedAt = now();
+            let result;
+            return Object.freeze({
+                name,
+                context: child,
+                parentSpanId: ancestor?.spanId,
+                startedAt,
+                end() {
+                    if (result)
+                        return result;
+                    const endedAt = now();
+                    if (endedAt < startedAt || !Number.isFinite(endedAt - startedAt))
+                        throw new RangeError('Clock moved backwards or duration overflowed.');
+                    result = Object.freeze({
+                        name,
+                        context: child,
+                        parentSpanId: ancestor?.spanId,
+                        startedAt,
+                        endedAt,
+                        durationMs: endedAt - startedAt,
+                    });
+                    return result;
+                },
+            });
+        },
+        run(span, work) {
+            if (!span || typeof work !== 'function')
+                throw new TypeError('Span and callback are required.');
+            return adapter.run(context(span.context), work);
+        },
+    };
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,39 @@
+export interface TraceContext {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly sampled: boolean;
+}
+export interface ContextAdapter {
+    get(): TraceContext | undefined;
+    run<T>(context: TraceContext, work: () => T): T;
+}
+export interface Span {
+    readonly name: string;
+    readonly context: TraceContext;
+    readonly parentSpanId: string | undefined;
+    readonly startedAt: number;
+    end(): SpanResult;
+}
+export interface SpanResult {
+    readonly name: string;
+    readonly context: TraceContext;
+    readonly parentSpanId: string | undefined;
+    readonly startedAt: number;
+    readonly endedAt: number;
+    readonly durationMs: number;
+}
+export interface TracerOptions {
+    readonly adapter: ContextAdapter;
+    readonly clock?: () => number;
+    /** Must fill every byte with cryptographically secure randomness. */
+    readonly randomFill?: (bytes: Uint8Array) => void;
+}
+export interface Tracer {
+    current(): TraceContext | undefined;
+    start(name: string, parent?: TraceContext): Span;
+    run<T>(span: Span, work: () => T): T;
+}
+/** Only version 00, lowercase hex, and flags 00/01 are supported. */
+export declare function parseTraceparent(header: string): TraceContext;
+export declare function formatTraceparent(value: TraceContext): string;
+export declare function createTracer(options: TracerOptions): Tracer;

package/dist/esm/index.js

@@ -0,0 +1,103 @@
+function context(value) {
+    if (!value ||
+        typeof value.traceId !== 'string' ||
+        typeof value.spanId !== 'string' ||
+        !/^[0-9a-f]{32}$/.test(value.traceId) ||
+        /^0+$/.test(value.traceId) ||
+        !/^[0-9a-f]{16}$/.test(value.spanId) ||
+        /^0+$/.test(value.spanId) ||
+        typeof value.sampled !== 'boolean')
+        throw new TypeError('Invalid trace context.');
+    return Object.freeze({ traceId: value.traceId, spanId: value.spanId, sampled: value.sampled });
+}
+/** Only version 00, lowercase hex, and flags 00/01 are supported. */
+export function parseTraceparent(header) {
+    if (typeof header !== 'string' || !/^00-[0-9a-f]{32}-[0-9a-f]{16}-0[01]$/.test(header))
+        throw new TypeError('Unsupported or invalid traceparent.');
+    return context({
+        traceId: header.slice(3, 35),
+        spanId: header.slice(36, 52),
+        sampled: header.slice(53) === '01',
+    });
+}
+export function formatTraceparent(value) {
+    const validated = context(value);
+    return `00-${validated.traceId}-${validated.spanId}-${validated.sampled ? '01' : '00'}`;
+}
+export function createTracer(options) {
+    if (!options ||
+        typeof options.adapter?.get !== 'function' ||
+        typeof options.adapter.run !== 'function')
+        throw new TypeError('A context adapter is required.');
+    if (options.clock !== undefined && typeof options.clock !== 'function')
+        throw new TypeError('Invalid clock.');
+    if (options.randomFill !== undefined && typeof options.randomFill !== 'function')
+        throw new TypeError('Invalid random source.');
+    const adapter = options.adapter;
+    const clock = options.clock ?? (() => performance.now());
+    const fill = options.randomFill ??
+        ((bytes) => {
+            if (!globalThis.crypto?.getRandomValues)
+                throw new Error('Secure randomness is unavailable.');
+            globalThis.crypto.getRandomValues(bytes);
+        });
+    const now = () => {
+        const value = clock();
+        if (typeof value !== 'number' || !Number.isFinite(value))
+            throw new TypeError('Clock must return a finite number.');
+        return value;
+    };
+    const id = (length) => {
+        const bytes = new Uint8Array(length);
+        fill(bytes);
+        if (bytes.every((byte) => byte === 0))
+            throw new Error('Random source produced an all-zero ID.');
+        return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+    };
+    const current = () => {
+        const value = adapter.get();
+        return value === undefined ? undefined : context(value);
+    };
+    return {
+        current,
+        start(name, parent = current()) {
+            if (typeof name !== 'string' || name.length === 0 || name.length > 256)
+                throw new TypeError('Span name must contain 1 to 256 UTF-16 units.');
+            const ancestor = parent === undefined ? undefined : context(parent);
+            const child = context({
+                traceId: ancestor?.traceId ?? id(16),
+                spanId: id(8),
+                sampled: ancestor?.sampled ?? false,
+            });
+            const startedAt = now();
+            let result;
+            return Object.freeze({
+                name,
+                context: child,
+                parentSpanId: ancestor?.spanId,
+                startedAt,
+                end() {
+                    if (result)
+                        return result;
+                    const endedAt = now();
+                    if (endedAt < startedAt || !Number.isFinite(endedAt - startedAt))
+                        throw new RangeError('Clock moved backwards or duration overflowed.');
+                    result = Object.freeze({
+                        name,
+                        context: child,
+                        parentSpanId: ancestor?.spanId,
+                        startedAt,
+                        endedAt,
+                        durationMs: endedAt - startedAt,
+                    });
+                    return result;
+                },
+            });
+        },
+        run(span, work) {
+            if (!span || typeof work !== 'function')
+                throw new TypeError('Span and callback are required.');
+            return adapter.run(context(span.context), work);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@lp-labs/trace-context",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Bounded, explicit trace-context utilities with injected adapters and deterministic policies.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": "\u003e=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "npm run build \u0026\u0026 node scripts/check-types.mjs",
+    "test": "npm run build \u0026\u0026 node --test tests/*.test.mjs",
+    "format": "prettier --write src scripts tests *.json README.md",
+    "format:check": "prettier --check src scripts tests *.json README.md",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "prettier": "^3.6.2"
+  },
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "all",
+    "printWidth": 100,
+    "endOfLine": "lf"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": {
+    "name": "Libin Prasanth",
+    "url": "https://www.linkedin.com/in/libinprasanth/"
+  },
+  "funding": {
+    "type": "paypal",
+    "url": "https://www.paypal.me/LibinPrasanth"
+  }
+}