@sharetech-labs/logtree

Structured decision tracing with nested log trees for Node.js + TypeScript.

Capture execution paths once, then export them as JSON, flat events, ASCII trees, or Mermaid diagrams.

Why logtree

• Minimal API: one log() method at every level.
• Automatic nesting: each returned context keeps trace depth for you.
• Multiple outputs from the same trace:
  • toJSON() for APIs and storage.
  • flat() for event pipelines.
  • summary() for terminal debugging.
  • mermaid() for diagrams in docs and PRs.
• Works in both ESM and CommonJS builds.

Install

npm install @sharetech-labs/logtree

Quick Start

import { Trace } from '@sharetech-labs/logtree';

const trace = new Trace('order-123', { customer: 'C-2041' });

const pricing = trace.log('pricing', { subtotal: 284.97 });
pricing.log('apply-discount', { code: 'SAVE20' });
trace.log('payment', { amount: 227.98 });

console.log(trace.summary());

Output:

order-123
├─ pricing (subtotal=284.97)
│  └─ apply-discount (code=SAVE20)
└─ payment (amount=227.98)

npm + GitHub Friendly Outputs

1. Nested JSON (toJSON)

const json = trace.toJSON();

Good for API responses, snapshots, or writing trace artifacts in CI.

2. Flat Events (flat)

const events = trace.flat();

Good for analytics/event pipelines where each entry needs an id, timestamp, and _depth.

3. Mermaid Diagrams (mermaid)

const diagram = trace.mermaid();
console.log(diagram);

Output:

graph LR
    root["order-123"]
    n1["pricing"]
    n2["apply-discount"]
    n3["payment"]
    root --> n1
    root --> n3
    n1 --> n2

Use this directly in GitHub Markdown docs, issues, and PR descriptions.

API At A Glance

new Trace(id: string, data?: Record<string, unknown>, options?: { consoleLogging?: boolean })

trace.log(label: string, data?: Record<string, unknown>): TraceContext
trace.toJSON(): TraceJSON
trace.flat(): FlatEntry[]
trace.summary(): string
trace.mermaid(options?: { direction?: 'TD' | 'LR' | 'BT' | 'RL'; order?: boolean }): string

trace.setConsoleLogging({ enabled: boolean }): Trace

// The returned context from log() supports:
context.log(label: string, data?: Record<string, unknown>): TraceContext

Module Usage

ESM

import { Trace } from '@sharetech-labs/logtree';

CommonJS

const { Trace } = require('@sharetech-labs/logtree');

Development Scripts

npm run dev            # vitest watch
npm run test           # run tests once
npm run test:coverage  # coverage report
npm run lint           # type check
npm run build          # tsup build
npm run ci             # full CI checks
npm run check-exports  # verify package type exports

Release + Publish

The GitHub publish workflow runs on pushes to main, performs CI, bumps patch version, tags, and publishes to npm.

Contributing

1. Fork and create a branch.
2. Run npm ci.
3. Add tests in tests/ for behavior changes.
4. Run npm run ci before opening a PR.

License

MIT © Sharetech Labs