Reference

leylines

Types

`CollapsedValue`

Stored value that was collapsed out of a default entry payload.

export interface CollapsedValue {
  id: string;
  entryId: string;
  path: string;
  value: JsonValue;
}

Properties

id Stable identifier used with expand.
entryId Entry id that owns the collapsed value.
path Path inside the entry where the value was collapsed.
value Full JSON-compatible collapsed value.

^{🔍 CollapsedValue on GitHub}

`ErrorDetails`

Normalized error details stored with an error-level or error-bearing entry.

export interface ErrorDetails {
  name?: string;
  message: string;
  stack?: string;
  cause?: JsonValue;
}

Properties

name Error class or constructor name when available.
message Human-readable error message.
stack Stack trace when available and safe to persist.
cause JSON-compatible representation of the error cause when present.

^{🔍 ErrorDetails on GitHub}

`JsonObject`

JSON object used for structured metadata and queryable properties.

export type JsonObject = {
  [key: string]: JsonValue;
};

^{🔍 JsonObject on GitHub}

`JsonPrimitive`

JSON scalar value accepted by Leylines metadata and properties.

export type JsonPrimitive = string | number | boolean | null;

^{🔍 JsonPrimitive on GitHub}

`JsonValue`

JSON-compatible value accepted by Leylines metadata and properties.

export type JsonValue = JsonPrimitive | JsonValue[] | {
  [key: string]: JsonValue;
};

^{🔍 JsonValue on GitHub}

`LogEntry`

Persisted log entry returned from writes, queries, and tails.

export interface LogEntry {
  id: string;
  sequence: number;
  timestamp: string;
  level: LogLevel;
  scope: string;
  message: string;
  metadata: JsonObject;
  properties: JsonObject;
  error?: ErrorDetails;
}

Properties

id Stable unique identifier for this entry.
sequence Monotonic store-local sequence used to make ordering deterministic.
timestamp ISO timestamp for when the entry occurred.
level Entry severity.
scope Dotted domain scope that produced the entry.
message Short human-readable event message.
metadata Runtime context that is useful for display but not the primary query model.
properties Structured event properties intended for filtering and correlation.
error Normalized error details when an error was attached.

^{🔍 LogEntry on GitHub}

`LogEntryInput`

Input accepted by store-level append operations.

export interface LogEntryInput {
  id?: string;
  timestamp?: Date | string;
  level: LogLevel;
  scope: string;
  message: string;
  metadata?: JsonObject;
  properties?: JsonObject;
  error?: unknown;
}

Properties

id Optional caller-provided entry identifier. A generated UUID is used when omitted.
timestamp Optional occurrence time. The current time is used when omitted.
level Entry severity.
scope Dotted domain scope that produced the entry.
message Short human-readable event message.
metadata Runtime context that is useful for display but not the primary query model.
properties Structured event properties intended for filtering and correlation.
error Error-like value to normalize and persist with the entry.

^{🔍 LogEntryInput on GitHub}

`LoggerOptions`

Base scope and inherited context for a scoped logger.

export interface LoggerOptions {
  scope: string;
  properties?: JsonObject;
  metadata?: JsonObject;
}

Properties

scope Dotted domain scope assigned to entries from this logger.
properties Structured properties inherited by every entry from this logger.
metadata Metadata inherited by every entry from this logger.

^{🔍 LoggerOptions on GitHub}

`LoggerWriteOptions`

Per-entry options accepted by ScopedLogger write methods.

export interface LoggerWriteOptions {
  properties?: JsonObject;
  metadata?: JsonObject;
  error?: unknown;
  timestamp?: Date | string;
}

Properties

properties Structured properties merged over the logger's inherited properties.
metadata Metadata merged over the logger's inherited metadata.
error Error-like value to normalize and persist with the entry.
timestamp Occurrence time. The current time is used when omitted.

^{🔍 LoggerWriteOptions on GitHub}

`LogLevel`

Severity assigned to a log entry.

export type LogLevel = 'debug' | 'info' | 'warn' | 'error';

^{🔍 LogLevel on GitHub}

`LogPage`

Page of query results with stable entry-id cursors.

export interface LogPage {
  entries: LogEntry[];
  nextBefore?: string;
  nextAfter?: string;
}

Properties

entries Entries matched by the query in chronological order.
nextBefore Cursor for entries before the first returned entry.
nextAfter Cursor for entries after the last returned entry.

^{🔍 LogPage on GitHub}

`LogQuery`

Query criteria shared by the Node API and CLI.

export interface LogQuery {
  since?: Date | string;
  until?: Date | string;
  before?: string;
  after?: string;
  levels?: LogLevel[];
  minLevel?: LogLevel;
  scope?: string;
  scopePrefix?: string;
  text?: string;
  regex?: string | RegExp;
  properties?: PropertyFilter[];
  includeDebug?: boolean;
  limit?: number;
}

Properties

since Include entries at or after this timestamp.
until Include entries at or before this timestamp.
before Return entries that sort before this entry id.
after Return entries that sort after this entry id.
levels Exact levels to include.
minLevel Include entries at this severity or higher.
scope Exact scope to include.
scopePrefix Scope prefix to include, matching both the prefix itself and dotted children.
text Case-sensitive message substring filter.
regex Regular expression tested against entry messages.
properties Equality filters over structured properties.
includeDebug Include debug entries, which are hidden by default.
limit Maximum number of entries to return.

^{🔍 LogQuery on GitHub}

`OpenLogStoreOptions`

Options for opening the low-level durable log store.

interface OpenLogStoreOptions {
  path: string;
  retention?: RetentionOptions;
  redaction?: RedactionOptions;
  collapseAboveBytes?: number;
}

Properties

path SQLite store path. Parent directories are created automatically.
retention Retention policy applied during store maintenance.
redaction Redaction rules applied before entries are persisted.
collapseAboveBytes Byte threshold above which large JSON values are collapsed for default views.

^{🔍 OpenLogStoreOptions on GitHub}

`OpenScopedLogsOptions`

Options for opening the high-level Scoped Logs API.

export interface OpenScopedLogsOptions {
  path?: string;
  production?: boolean;
  retention?: RetentionOptions;
  redaction?: RedactionOptions;
  collapseAboveBytes?: number;
}

Properties

production Enable logging when NODE_ENV is production. Disabled by default.
retention Retention policy applied during store maintenance.
redaction Redaction rules applied before entries are persisted.
collapseAboveBytes Byte threshold above which large JSON values are collapsed for default views.

^{🔍 OpenScopedLogsOptions on GitHub}

`PropertyFilter`

Equality filter against a top-level or dotted path inside entry properties.

export interface PropertyFilter {
  path: string;
  equals: JsonValue;
}

Properties

path Property name or dotted path such as request.id.
equals JSON value that must equal the value at path.

^{🔍 PropertyFilter on GitHub}

`RedactionOptions`

Redaction configuration applied before entries are persisted.

export interface RedactionOptions {
  rules?: RedactionRule[];
}

Properties

rules Additional rules appended to Leylines' built-in secret-looking defaults.

^{🔍 RedactionOptions on GitHub}

`RedactionRule`

Rule that replaces sensitive property names or string values before persistence.

export interface RedactionRule {
  name?: string | RegExp;
  value?: string | RegExp;
  replacement?: string;
}

Properties

name Property name or name pattern to redact.
value String value or value pattern to redact.
replacement Replacement text. Defaults to [REDACTED].

^{🔍 RedactionRule on GitHub}

`RetentionOptions`

Retention policy applied during store maintenance.

export interface RetentionOptions {
  maxEntries?: number;
  maxAgeMs?: number;
}

Properties

maxEntries Maximum number of newest entries to retain.
maxAgeMs Maximum entry age in milliseconds.

^{🔍 RetentionOptions on GitHub}

`ScopedLogs`

High-level handle for writing, querying, tailing, and closing a log store.

export interface ScopedLogs {
  readonly enabled: boolean;
  readonly store: LogStore | undefined;
  logger(options: LoggerOptions | string): ScopedLogger;
  query(query?: LogQuery): ReturnType<LogStore['query']>;
  tail(query?: LogQuery, options?: {
    signal?: AbortSignal;
  }): AsyncIterable<LogEntry>;
  expand(id: string): ReturnType<LogStore['expand']>;
  listScopes(): string[];
  close(): void;
}

Properties

enabled Whether this handle writes to a durable store.
store Underlying durable store, absent when production logging is disabled.
logger Create a logger for a scope or full logger options.
query Query stored entries.
tail Stream entries appended after subscription that match the query.
expand Retrieve a full collapsed value by collapsed value id.
listScopes List scopes observed in the store.
close Close the underlying store.

^{🔍 ScopedLogs on GitHub}

Functions

`defaultStorePath`

Resolve the inferred local store path.

export function defaultStorePath(): string;

^{🔍 defaultStorePath on GitHub}

`openLogStore`

Open or create a low-level durable log store.

export function openLogStore(options: OpenLogStoreOptions): LogStore;

^{🔍 openLogStore on GitHub}

`openScopedLogs`

Open the high-level Scoped Logs API around a durable local store.

export function openScopedLogs(options?: OpenScopedLogsOptions): ScopedLogs;

^{🔍 openScopedLogs on GitHub}

Classes

`LogStore`

Durable local log store backed by SQLite.

export class LogStore {
  #private;
  /** Absolute SQLite database path backing this store. */
  readonly path: string;
  /** Open or create a SQLite log store. */
  constructor(options: OpenLogStoreOptions);
  /** Append an entry, apply redaction, and return the persisted entry. */
  write(input: LogEntryInput): LogEntry;
  /** Query entries in chronological order with stable pagination cursors. */
  query(query?: LogQuery): LogPage;
  /** List all observed scopes in lexical order. */
  listScopes(): string[];
  /** Retrieve a collapsed value by id, or `undefined` when it is not present. */
  expand(id: string): CollapsedValue | undefined;
  /** Stream entries appended after subscription that match the query. */
  tail(query?: LogQuery, options?: {
    signal?: AbortSignal;
  }): AsyncIterable<LogEntry>;
  /** Close the SQLite database. Subsequent store operations throw. */
  close(): void;
}

^{🔍 LogStore on GitHub}

`ScopedLogger`

Logger that writes entries to a LogStore under a stable domain scope.

export class ScopedLogger {
  #private;
  /** Dotted domain scope assigned to entries from this logger. */
  readonly scope: string;
  /** Create a logger backed by `store` with inherited scope, properties, and metadata. */
  constructor(store: LogStore | undefined, options: LoggerOptions);
  /** Create a child logger with merged inherited context and a nested scope. */
  child(options?: Partial<LoggerOptions> & {
    scope?: string;
  }): ScopedLogger;
  /** Write a debug entry. Debug entries are hidden from default queries unless requested. */
  debug(message: string, options?: LoggerWriteOptions): LogEntry | undefined;
  /** Write an info entry. */
  info(message: string, options?: LoggerWriteOptions): LogEntry | undefined;
  /** Write a warning entry. */
  warn(message: string, options?: LoggerWriteOptions): LogEntry | undefined;
  /** Write an error entry, optionally with normalized error details. */
  error(message: string, options?: LoggerWriteOptions): LogEntry | undefined;
  /** Write an entry at an explicit level. */
  write(level: LogLevel, message: string, options?: LoggerWriteOptions): LogEntry | undefined;
}

^{🔍 ScopedLogger on GitHub}