Local history API

Generated public TypeScript reference for @relkit/observability-local.

For configuration and examples, read inspector.

Public imports

• @relkit/observability-local — 27 exports
• @relkit/observability-local/worker — 4 exports

All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API’s inline sample, a maintained repository usage, or the shared module walkthrough.

index.ts

Optional native history API; importing this package explicitly selects local storage.

“./local/duckdb-database-effect.js” (namespace export)

Re-exports all named exports from the “./local/duckdb-database-effect.js” module.

Signature

export * from "./local/duckdb-database-effect.js";

Source

“./local/duckdb-database.js” (namespace export)

Re-exports all named exports from the “./local/duckdb-database.js” module.

Signature

export * from "./local/duckdb-database.js";

Source

“./local/duckdb-driver.js” (namespace export)

Re-exports all named exports from the “./local/duckdb-driver.js” module.

Signature

export * from "./local/duckdb-driver.js";

Source

“./local/duckdb-error.js” (namespace export)

Re-exports all named exports from the “./local/duckdb-error.js” module.

Signature

export * from "./local/duckdb-error.js";

Source

“./local/duckdb-worker-effect.js” (namespace export)

Re-exports all named exports from the “./local/duckdb-worker-effect.js” module.

Signature

export * from "./local/duckdb-worker-effect.js";

Source

“./local/worker-client.js” (namespace export)

Re-exports all named exports from the “./local/worker-client.js” module.

Signature

export * from "./local/worker-client.js";

Source

“@relkit/observability/local/record” (namespace export)

Re-exports all named exports from the “@relkit/observability/local/record” module.

Signature

export * from "@relkit/observability/local/record";

Source

duckdb-database-effect.ts

Owns duckdb database effect for the optional local history store. Shared records and query contracts come from lightweight observability; native handles and worker lifetimes remain owned by this storage package.

DuckdbDatabaseService (class)

Database operations provided for one owned Effect Scope.

Example

const database = yield * DuckdbDatabaseService;
yield * database.flush();

Signature

declare class DuckdbDatabaseService

Source

duckdbDatabaseLayer

Provides a scoped database service using an injectable DuckdbDriverService.

Example

const program = Effect.gen(function* () {
  return yield* DuckdbDatabaseService;
});
const layer = duckdbDatabaseLayer(root);

Signature

declare const duckdbDatabaseLayer: (
  root: string,
  configured?: TelemetryLocalRetentionPolicy,
  redaction?: RedactionPolicy,
) => Layer.Layer<DuckdbDatabaseService, DuckdbError, DuckdbDriverService>;

Source

openDuckdbDatabaseEffect

Acquires an instance and connection in the caller’s Scope, initializes schema, and returns Effect operations. Scope finalizers close the connection first, then the instance, including on setup failure or interruption.

Example

const database = yield * openDuckdbDatabaseEffect(root);
yield * database.flush();

Signature

declare const openDuckdbDatabaseEffect: (
  root: string,
  configured?: TelemetryLocalRetentionPolicy | undefined,
  redaction?: RedactionPolicy | undefined,
) => Effect.Effect<
  {
    imported: { records: number; malformed: number };
    append: (records: readonly LocalRecord[]) => Effect.Effect<StoredLocalRecord[], DuckdbError>;
    configure: (
      retention: TelemetryLocalRetentionPolicy,
      redaction?: RedactionPolicy,
    ) => Effect.Effect<void, DuckdbError>;
    flush: () => Effect.Effect<void, DuckdbError>;
    list: (
      kind: "logs" | "requests" | "traces",
      input?: ObservabilityQueryRequest | undefined,
    ) => Effect.Effect<
      ObservabilityQueryPage<StoredLocalRecord>,
      DuckdbError | DuckdbQueryError,
      never
    >;
    detail: (
      kind: "request" | "log" | "trace",
      id: string,
    ) => Effect.Effect<
      | {
          log: StoredLocalRecord;
          items: ReadonlyArray<never>;
          nextCursor?: string;
          protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
          version: typeof OBSERVABILITY_QUERY_VERSION;
        }
      | {
          request: RequestRecord;
          spans: readonly SpanRecord[];
          roots: readonly SpanNode[];
          continuations: readonly { readonly traceId: string; readonly active: boolean }[];
          records: readonly ObservabilityRecord[];
          counts: {
            readonly records: number;
            readonly spans: number;
            readonly continuations: number;
          };
          incomplete: readonly string[];
          items: ReadonlyArray<never>;
          nextCursor?: string;
          protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
          version: typeof OBSERVABILITY_QUERY_VERSION;
        }
      | {
          trace: StoredLocalRecord | undefined;
          spans: Array<SpanRecord>;
          records: ReadonlyArray<StoredLocalRecord>;
          items: ReadonlyArray<StoredLocalRecord>;
          nextCursor?: string;
          protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
          version: typeof OBSERVABILITY_QUERY_VERSION;
        }
      | undefined,
      DuckdbError | DuckdbQueryError,
      never
    >;
  },
  DuckdbError,
  Scope | DuckdbDriverService
>;

Source

duckdb-database.ts

Owns duckdb database for the optional local history store. Shared records and query contracts come from lightweight observability; native handles and worker lifetimes remain owned by this storage package.

openDuckdbDatabase

Opens a private DuckDB database and owns its Effect Scope until close. The scoped Effect implementation contains acquisition and operation logic.

Throws

If acquisition, storage, or import fails.

Example

const database = await openDuckdbDatabase(root);
await database.close();

Signature

declare const openDuckdbDatabase: (
  root: string,
  configured?: TelemetryLocalRetentionPolicy,
  redaction?: RedactionPolicy,
) => Promise<{
  imported: { records: number; malformed: number };
  append: (
    records: Parameters<
      (records: readonly LocalRecord[]) => Effect.Effect<StoredLocalRecord[], DuckdbError>
    >[0],
  ) => Promise<Array<StoredLocalRecord>>;
  list: (
    kind: Parameters<
      (
        kind: "logs" | "requests" | "traces",
        input?: ObservabilityQueryRequest | undefined,
      ) => Effect.Effect<
        ObservabilityQueryPage<StoredLocalRecord>,
        DuckdbError | DuckdbQueryError,
        never
      >
    >[0],
    input?: Parameters<
      (
        kind: "logs" | "requests" | "traces",
        input?: ObservabilityQueryRequest | undefined,
      ) => Effect.Effect<
        ObservabilityQueryPage<StoredLocalRecord>,
        DuckdbError | DuckdbQueryError,
        never
      >
    >[1],
  ) => Promise<ObservabilityQueryPage<StoredLocalRecord>>;
  detail: (
    kind: Parameters<
      (
        kind: "request" | "log" | "trace",
        id: string,
      ) => Effect.Effect<
        | {
            log: StoredLocalRecord;
            items: ReadonlyArray<never>;
            nextCursor?: string;
            protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
            version: typeof OBSERVABILITY_QUERY_VERSION;
          }
        | {
            request: RequestRecord;
            spans: readonly SpanRecord[];
            roots: readonly SpanNode[];
            continuations: readonly { readonly traceId: string; readonly active: boolean }[];
            records: readonly ObservabilityRecord[];
            counts: {
              readonly records: number;
              readonly spans: number;
              readonly continuations: number;
            };
            incomplete: readonly string[];
            items: ReadonlyArray<never>;
            nextCursor?: string;
            protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
            version: typeof OBSERVABILITY_QUERY_VERSION;
          }
        | {
            trace: StoredLocalRecord | undefined;
            spans: Array<SpanRecord>;
            records: ReadonlyArray<StoredLocalRecord>;
            items: ReadonlyArray<StoredLocalRecord>;
            nextCursor?: string;
            protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
            version: typeof OBSERVABILITY_QUERY_VERSION;
          }
        | undefined,
        DuckdbError | DuckdbQueryError,
        never
      >
    >[0],
    id: string,
  ) => Promise<
    | {
        log: StoredLocalRecord;
        items: ReadonlyArray<never>;
        nextCursor?: string;
        protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
        version: typeof OBSERVABILITY_QUERY_VERSION;
      }
    | {
        request: RequestRecord;
        spans: readonly SpanRecord[];
        roots: readonly SpanNode[];
        continuations: readonly { readonly traceId: string; readonly active: boolean }[];
        records: readonly ObservabilityRecord[];
        counts: {
          readonly records: number;
          readonly spans: number;
          readonly continuations: number;
        };
        incomplete: readonly string[];
        items: ReadonlyArray<never>;
        nextCursor?: string;
        protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
        version: typeof OBSERVABILITY_QUERY_VERSION;
      }
    | {
        trace: StoredLocalRecord | undefined;
        spans: Array<SpanRecord>;
        records: ReadonlyArray<StoredLocalRecord>;
        items: ReadonlyArray<StoredLocalRecord>;
        nextCursor?: string;
        protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
        version: typeof OBSERVABILITY_QUERY_VERSION;
      }
    | undefined
  >;
  configure: (
    value: TelemetryLocalRetentionPolicy,
    nextRedaction?: RedactionPolicy,
  ) => Promise<void>;
  flush: () => Promise<void>;
  close: () => Promise<void>;
}>;

Source

duckdb-driver.ts

Owns duckdb driver for the optional local history store. Shared records and query contracts come from lightweight observability; native handles and worker lifetimes remain owned by this storage package.

DuckdbDriverService (class)

Injectable native DuckDB instance factory.

Example

const driver = yield * DuckdbDriverService;
const instance = yield * driver.create(path);

Signature

declare class DuckdbDriverService

Source

duckdbDriverLayer

Live native driver for local observability storage.

Example

const database = yield * openDuckdbDatabaseEffect(root).pipe(Effect.provide(duckdbDriverLayer));

Signature

declare const duckdbDriverLayer: Layer.Layer<DuckdbDriverService, never, never>;

Source

duckdb-error.ts

Owns duckdb error for the optional local history store. Shared records and query contracts come from lightweight observability; native handles and worker lifetimes remain owned by this storage package.

DuckdbError (class)

Expected local DuckDB IO or schema failure with a stable operation label.

Example

const failure = new DuckdbError({ operation: "connect", message: "failed", cause });

Signature

declare class DuckdbError

Source

duckdbError

Converts a native DuckDB failure to the local storage error channel.

Example

const error = duckdbError("connect", cause);

Signature

declare const duckdbError: <Cause>(operation: string, cause: Cause) => DuckdbError;

Source

duckdb-worker-effect.ts

Composes serialized storage commands behind an injectable worker service. Its scope owns the explicit database scope until close, failure or interruption.

DuckdbWorkerService (class)

Injectable command executor whose owner must close its database.

Signature

declare class DuckdbWorkerService

Source

duckdbWorkerLayer

Owns the command service and releases native state on every scope exit.

Signature

declare const duckdbWorkerLayer: Layer.Layer<DuckdbWorkerService, never, DuckdbDriverService>;

Source

makeDuckdbWorkerEffect

Signature

declare const makeDuckdbWorkerEffect: () => Effect.Effect<
  {
    execute: (
      command: LocalWorkerCommand,
    ) => Effect.Effect<
      | void
      | Array<StoredLocalRecord>
      | ObservabilityQueryPage<StoredLocalRecord>
      | { records: number; malformed: number },
      DuckdbError | DuckdbQueryError,
      never
    >;
    close: () => Effect.Effect<void, DuckdbError, never>;
  },
  never,
  DuckdbDriverService
>;

Source

duckdb-worker.ts

Owns duckdb worker for the optional local history store. Shared records and query contracts come from lightweight observability; native handles and worker lifetimes remain owned by this storage package.

worker-client-effect.ts

Acquires the optional isolated Node worker and exposes shared structural effects. Its caller owns close; neither record producers nor console logging import it.

startLocalWorkerEffect

Starts one child without opening a database until the caller sends open.

Signature

declare const startLocalWorkerEffect: (
  onFailure?: ((error: Error) => void) | undefined,
) => Effect.Effect<LocalWorkerEffects, LocalWorkerError, never>;

Source

worker-client-service.ts

Owns worker client service for the optional local history store. Shared records and query contracts come from lightweight observability; native handles and worker lifetimes remain owned by this storage package.

LocalWorkerService (class)

Injectable local worker operations. A Layer owns the worker process until its scope closes, so callers can substitute a deterministic service in tests.

Example

const program = Effect.gen(function* () {
  const worker = yield* LocalWorkerService;
  return worker.pid;
});

Signature

declare class LocalWorkerService

Source

localWorkerLayer

Acquires a worker for the Layer scope and releases it on every exit.

Example

const result = await Effect.runPromise(program.pipe(Effect.provide(localWorkerLayer())));

Signature

declare const localWorkerLayer: (
  onFailure?: (error: Error) => void,
) => Layer.Layer<LocalWorkerService, LocalWorkerError, never>;

Source

worker-client.ts

Owns worker client for the optional local history store. Shared records and query contracts come from lightweight observability; native handles and worker lifetimes remain owned by this storage package.

LocalWorkerEffects

Signature

declare const LocalWorkerEffects: LocalWorkerEffects;

Source

LocalWorkerError

Signature

declare const LocalWorkerError: typeof LocalWorkerError;

Source

LocalWorkerService

Signature

declare const LocalWorkerService: typeof LocalWorkerService;

Source

localWorkerLayer

Signature

declare const localWorkerLayer: (
  onFailure?: (error: Error) => void,
) => Layer<LocalWorkerService, LocalWorkerError, never>;

Source

startLocalWorker

Starts a local worker with the existing Promise API.

Throws

If process creation fails.

Example

const worker = startLocalWorker();
try {
  await worker.call({ type: "flush" });
} finally {
  await worker.close();
}

Signature

declare const startLocalWorker: (onFailure?: (error: Error) => void) => {
  pid: number | undefined;
  call: <T>(command: LocalWorkerCommand) => Promise<T>;
  close: () => Promise<void>;
};

Source

startLocalWorkerEffect

Signature

declare const startLocalWorkerEffect: (
  onFailure?: ((error: Error) => void) | undefined,
) => Effect.Effect<LocalWorkerEffects, LocalWorkerError, never>;

Source

worker.ts

Exposes IPC transport without evaluating the native DuckDB driver in its caller. The isolated Node worker imports that driver in its own process. Its caller retains the transport’s explicit close operation and physical child identity.

LocalWorkerCommand

Signature

declare const LocalWorkerCommand: LocalWorkerCommand;

Source

LocalWorkerEffects

Signature

declare const LocalWorkerEffects: LocalWorkerEffects;

Source

LocalWorkerError

Signature

declare const LocalWorkerError: LocalWorkerError;

Source

startLocalWorkerEffect

Signature

declare const startLocalWorkerEffect: (
  onFailure?: ((error: Error) => void) | undefined,
) => Effect<LocalWorkerEffects, LocalWorkerError, never>;

Source

types.ts

Validates diagnostic transport envelopes before any queue, IPC, or storage boundary.

“./types.types.js” (namespace export)

Re-exports all named exports from the “./types.types.js” module.

Signature

export * from "./types.types.js";

Source

LocalRecordValidationError (class)

Invalid local record envelope at the persistent storage boundary.

Example

Effect.runSync(
  validateLocalRecordEffect(null).pipe(
    Effect.catchTag("LocalRecordValidationError", (error) => Effect.succeed(error.reason)),
  ),
);

Signature

declare class LocalRecordValidationError

Source

recordTime

Synchronous compatibility adapter for local record time parsing.

Example

recordTime(logRecord);

Signature

declare const recordTime: (record: ObservabilityRecord) => number;

Source

recordTimeEffect

Reads the canonical time field for a local record.

Example

Effect.runSync(recordTimeEffect(logRecord));

Signature

declare const recordTimeEffect: (
  record: ObservabilityRecord,
) => Effect.Effect<number, never, never>;

Source

validateLocalRecord

Synchronous compatibility adapter for local record validation.

Throws

If the envelope or record is invalid.

Example

validateLocalRecord(envelope);

Signature

declare const validateLocalRecord: <Input>(value: Input) => asserts value is Input & LocalRecord;

Source

validateLocalRecordEffect

Validates a local transport envelope before persistence.

Example

Effect.runSync(validateLocalRecordEffect(envelope));

Signature

declare const validateLocalRecordEffect: <Input>(
  value: Input,
) => Effect.Effect<Input & LocalRecord, LocalRecordValidationError, never>;

Source

types.types.ts

Redacted telemetry envelopes and the diagnostic worker IPC protocol; no storage resources.

LocalLogOrigin (type alias)

A stable origin assigned to local telemetry records.

Signature

type LocalLogOrigin = "application" | "relkit" | "inspector";

Source

LocalRecord (interface)

Transport envelope accepted by the local worker.

Example

const envelope: LocalRecord = { key: "source:1", origin: "application", record };

Signature

export interface LocalRecord {
  readonly key: string;
  readonly origin: LocalLogOrigin;
  readonly record: ObservabilityRecord;
}

Source

LocalWorkerCommand (type alias)

Commands sent through the local worker IPC channel.

Signature

type LocalWorkerCommand =
  | {
      readonly type: "open";
      readonly root: string;
      readonly retention?: TelemetryLocalRetentionPolicy;
      readonly redaction?: RedactionPolicy;
    }
  | { readonly type: "append"; readonly records: readonly LocalRecord[] }
  | {
      readonly type: "query";
      readonly kind: "logs" | "requests" | "traces";
      readonly query: ObservabilityQueryRequest;
    }
  | { readonly type: "detail"; readonly kind: "log" | "request" | "trace"; readonly id: string }
  | {
      readonly type: "retention";
      readonly retention: TelemetryLocalRetentionPolicy;
      readonly redaction?: RedactionPolicy;
    }
  | { readonly type: "flush" | "close" };

Source

LocalWorkerResponse (interface)

A worker reply carrying a value or a safe error code and message.

Signature

export interface LocalWorkerResponse {
  readonly id: number;
  readonly fatal?: boolean;
  readonly value?: Schema.Json;
  readonly error?: string;
  readonly code?: ObservabilityQueryError["code"];
}

Source

StoredLocalRecord (type alias)

A persisted model record with its local cursor and origin.

Signature

type StoredLocalRecord = ObservabilityRecord & {
  readonly cursor: string;
  readonly origin: LocalLogOrigin;
};

Source

worker-client-error.ts

Typed IPC failures shared with tooling; no worker or database is acquired here.

LocalWorkerError (class)

A local worker creation, IPC, timeout, or response failure.

Example

Effect.runPromise(
  worker
    .call(command)
    .pipe(Effect.catchTag("LocalWorkerError", (error) => Effect.succeed(error.reason))),
);

Signature

declare class LocalWorkerError

Source

WorkerTransportError (class)

Failure raised by the IPC transport before mapping to the Effect channel.

Signature

declare class WorkerTransportError { constructor(
    readonly reason: "send" | "timeout" | "response",
    message: string,
  ) }

Source

workerFailure

Maps an IPC failure to a tagged worker error without losing query codes.

Signature

declare const workerFailure: <Failure>(
  error: Failure,
  reason: LocalWorkerError["reason"],
) => LocalWorkerError;

Source

worker-client.types.ts

Structural worker authority borrowed by telemetry producers without native dependencies.

LocalWorkerEffects (interface)

Effect operations for a live local telemetry worker process. The owning Layer or caller must close the worker after its final call.

Example

const worker = Effect.runSync(startLocalWorkerEffect());
await Effect.runPromise(worker.close());

Signature

export interface LocalWorkerEffects {
  readonly pid: number | undefined;
  /** @param command - Worker IPC command. @returns Its response or a tagged worker error. */
  readonly call: (
    command: LocalWorkerCommand,
  ) => Effect.Effect<Schema.Json | undefined, LocalWorkerError>;
  /** @returns Completion after the worker process and pending calls are released. */
  readonly close: () => Effect.Effect<void, LocalWorkerError>;
}

Source