cfw-logging/packages/shared-schema/README.md

@logger/shared-schema

Structured log record schema: types, normalization, redaction, error serialization, and JSONL line parsing. The shared foundation consumed by @logger/sdk, @logger/collector, and @logger/cli. Zero runtime dependencies.

Install

npm install @logger/shared-schema --registry=http://192.168.0.15:4873

LogRecord

A normalized record carries version: 1:

import type {LogRecord, LogLevel, LogRuntime} from '@logger/shared-schema';

const record: LogRecord = {
  id: 'uuid',
  timestamp: '2026-07-06T16:30:00.000Z',
  observedTimestamp: '2026-07-06T16:30:00.001Z',
  level: 'error',                              // 'debug' | 'info' | 'warn' | 'error'
  message: 'payment timeout',
  app: 'shop',
  service: 'orders',
  scope: 'orders.refund',
  attributes: {orderId: 'o-1'},
  error: {name: 'Error', message: 'card declined', stack: '...'},
  traceId: '...', spanId: '...', sessionId: '...', userId: '...',
  runtime: 'server',                           // 'browser' | 'node' | 'server' | 'worker' | 'electron' | 'cli'
  source: {host: 'host', pid: 1234, file: 'pay.ts', line: 42},
  version: 1,
};

API

createLogRecord(input, options?)

Normalizes a LogRecordInput into a LogRecord: assigns id/timestamp/observedTimestamp, serializes error, and redacts attributes.

import {createLogRecord} from '@logger/shared-schema';

const record = createLogRecord({
  level: 'error',
  message: 'payment timeout',
  app: 'shop',
  scope: 'orders.refund',
  runtime: 'server',
  error: new Error('card declined'),
  attributes: {orderId: 'o-1', token: 'secret'},
});
// record.attributes.token === '[REDACTED]'

options: { id?, now?, observedNow?, redactKeys? }. Provide now/observedNow for deterministic timestamps in tests.

serializeError(error)

Converts any value into a SerializedError. Handles Error (with name/message/stack/cause), strings, and arbitrary objects.

redactValue(value, keys?)

Deep-clones value with sensitive keys masked to '[REDACTED]' (case-insensitive match). Default keys: password, token, secret, apiKey, api_key, authorization, cookie, set-cookie. Pass a custom iterable to override.

parseLogLine(line)

Parses one JSONL line into a validated LogRecord. Throws if the line is not a valid record.

import {parseLogLine} from '@logger/shared-schema';
const record = parseLogLine(lineFromJsonlFile);

Notes

• Usually consumed indirectly through @logger/sdk (writing) or @logger/cli / @logger/collector (reading).
• All fields except id, timestamp, level, message, app, scope, runtime, version are optional.