@kar-mi/spirit-vale-tools-logging 0.9.0

package/dist/jsonl-tail-reader.d.ts

@@ -0,0 +1,38 @@
+export interface JsonlTailReadResult {
+    missing: boolean;
+    reset: boolean;
+    lines: string[];
+    size: number;
+    /** Bytes taken from the file by this read, including any that only formed a partial line. */
+    bytesRead: number;
+}
+export interface JsonlTailReaderOptions {
+    /** Chooses the decoder from the first available chunk (e.g. for BOM sniffing). Defaults to plain UTF-8. */
+    createDecoder?: (firstChunk: Uint8Array) => TextDecoder;
+    /** Byte offset to resume from, e.g. one persisted by an earlier process. */
+    startOffset?: number;
+    /** Most bytes to take in one {@link JsonlTailReader.read}. */
+    maxReadBytes?: number;
+}
+/** Incrementally tails a growing JSON Lines file: stat, detect truncation, read the new bytes, and split them into complete lines. */
+export declare class JsonlTailReader {
+    private readonly path;
+    private readOffset;
+    private partialBytes;
+    private pending;
+    private decoder?;
+    private readonly createDecoder;
+    private readonly maxReadBytes;
+    constructor(path: string, options?: JsonlTailReaderOptions);
+    /** Byte position just past the last complete line, excluding any buffered partial line. */
+    get offset(): number;
+    /** Byte position of the next read, including any buffered partial line. */
+    get bytePosition(): number;
+    /** a catch-up read exactly at another reader's position rather than at end of file. */
+    read(limitBytes?: number): Promise<JsonlTailReadResult>;
+    reset(): void;
+    /** Measures the trailing partial line in raw bytes, so {@link offset} never lands mid-record. */
+    private trackPartial;
+    private consume;
+}
+//# sourceMappingURL=jsonl-tail-reader.d.ts.map

package/dist/jsonl-tail-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl-tail-reader.d.ts","sourceRoot":"","sources":["../src/jsonl-tail-reader.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,2GAA2G;IAC3G,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,WAAW,CAAC;IACxD,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,sIAAsI;AACtI,qBAAa,eAAe;IAQd,OAAO,CAAC,QAAQ,CAAC,IAAI;IAPjC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,OAAO,CAAM;IACrB,OAAO,CAAC,OAAO,CAAC,CAAc;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA0C;IACxE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC,YAA6B,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,EAU9E;IAED,2FAA2F;IAC3F,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,2EAA2E;IAC3E,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,uFAAuF;IACjF,IAAI,CAAC,UAAU,SAA2B,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA0B9E;IAED,KAAK,IAAI,IAAI,CAKZ;IAED,iGAAiG;IACjG,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,OAAO;CAOhB"}

package/dist/logger.d.ts

@@ -0,0 +1,98 @@
+import { appendFile } from "node:fs/promises";
+import type { CurrentLogStream, JsonObject, LogSession, LogStream } from "./types.ts";
+export interface LoggerTuning {
+    /** Records accumulate until a batch reaches this many bytes. Defaults to 256 KiB. */
+    batchBytes?: number;
+    /** A partial batch is written after this long. Defaults to 50 ms. */
+    flushIntervalMs?: number;
+    /** Hard cap on bytes held in memory (buffered plus queued). Defaults to 8 MiB. */
+    maxBufferedBytes?: number;
+}
+export interface CreateLogSessionOptions extends LoggerTuning {
+    producer: string;
+    streams: readonly LogStream[];
+    logDirectory?: string;
+    outputPaths?: Partial<Record<LogStream, string>>;
+    onWriteError?: (failure: LogWriteFailure) => void;
+    activate?: boolean;
+}
+export interface LogWriteFailure {
+    stream: LogStream;
+    path: string;
+    error: Error;
+}
+export interface JsonLinesLoggerOptions extends LoggerTuning {
+    stream: LogStream;
+    onWriteError?: (failure: LogWriteFailure) => void;
+    /** Sink override, mainly for tests. Defaults to a lazily opened append-mode file handle. */
+    append?: typeof appendFile;
+}
+export interface JsonLinesLoggerStats {
+    /** Bytes held in memory: the partial batch plus every batch still queued for the disk. */
+    bufferedBytes: number;
+    queuedBatches: number;
+    /** True once a write has failed; the logger keeps accepting and attempting records. */
+    failed: boolean;
+    /** Records refused because the byte cap was reached, or logged after close(). */
+    droppedRecords: number;
+}
+/** Buffers records into byte-bounded batches and appends them through one file handle per stream. */
+export declare class JsonLinesLogger {
+    readonly path: string;
+    private readonly sessionId;
+    private readonly source;
+    private readonly options;
+    private sequence;
+    private lines;
+    private currentBytes;
+    private bufferedBytes;
+    private queuedBatches;
+    private droppedRecords;
+    private timer?;
+    private tail;
+    private firstFailure?;
+    private reportedFailure;
+    private overflowing;
+    private closed;
+    private headerWritten;
+    private handle?;
+    private readonly batchBytes;
+    private readonly flushIntervalMs;
+    private readonly maxBufferedBytes;
+    constructor(path: string, sessionId: string, source: string, options?: JsonLinesLoggerOptions);
+    log(type: string, data: JsonObject): void;
+    /** Resolves once every record logged before this call has reached the disk. */
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    stats(): JsonLinesLoggerStats;
+    /**
+     * Emits the stream header ahead of the first record.
+     *
+     * Written here rather than by whoever created the file so that every stream file is
+     * self-describing however it was produced — including a bare `--output name.jsonl` from the CLI.
+     * Sessions have no metadata file of their own; v2 records carry no session id or producer either,
+     * so without this line a stream read in isolation would have no provenance at all.
+     */
+    private ensureHeader;
+    private scheduleFlush;
+    private enqueueCurrent;
+    private write;
+    private notify;
+}
+export declare function createLogSession(options: CreateLogSessionOptions): Promise<LogSession>;
+/** Writes a single stream's "current" pointer verbatim, e.g. to roll a stream back to a known-good pointer. */
+export declare function writeCurrentLogStreamPointer(pointer: CurrentLogStream, logDirectory?: string): Promise<void>;
+/**
+ * Switches the shared "current stream" pointers for the given streams onto an already-created,
+ * not-yet-activated session (see {@link CreateLogSessionOptions.activate}). Callers that need
+ * several streams to change over as one logical moment should await this once. The session is
+ * flushed first, so a follower that picks up a new pointer immediately sees the records already
+ * written to that session. Streams are switched one at a time (there is no cross-file
+ * transaction), so a caller that must not leave streams split across sessions should capture each
+ * stream's prior pointer first and roll back to it if this throws partway through.
+ */
+export declare function activateLogSession(session: Pick<LogSession, "id"> & Partial<Pick<LogSession, "flush">>, streams: readonly LogStream[], logDirectory?: string): Promise<void>;
+export declare function readCurrentLogStream(stream: LogStream, logDirectory?: string): Promise<(CurrentLogStream & {
+    path: string;
+}) | undefined>;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/dist/paths.d.ts

@@ -0,0 +1,6 @@
+import type { LogStream } from "./types.ts";
+export declare function defaultLogDirectory(workingDirectory?: string): string;
+export declare function streamCategoryDirectory(stream: LogStream, logDirectory?: string): string;
+export declare function streamSessionPath(stream: LogStream, sessionId: string, logDirectory?: string): string;
+export declare function currentStreamPointerPath(stream: LogStream, logDirectory?: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,wBAAgB,mBAAmB,CAAC,gBAAgB,SAAgB,GAAG,MAAM,CAE5E;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,YAAY,SAAwB,GAAG,MAAM,CAEvG;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,SAAwB,GAAG,MAAM,CAEpH;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,EAAE,YAAY,SAAwB,GAAG,MAAM,CAExG"}

package/dist/predicates.d.ts

@@ -0,0 +1,6 @@
+export type LiveLogStatus = "waiting" | "watching" | "ready" | "stopped" | "error";
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isMissing(error: unknown): boolean;
+export declare function decimal(value: unknown): value is string;
+export declare function nullableString(value: unknown): value is string | null;
+//# sourceMappingURL=predicates.d.ts.map

package/dist/predicates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"predicates.d.ts","sourceRoot":"","sources":["../src/predicates.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEjD;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEvD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,GAAG,IAAI,CAErE"}

package/dist/record-codec.d.ts

@@ -0,0 +1,10 @@
+import type { JsonObject, LogRecord, LogStreamHeader } from "./types.ts";
+/** Encodes one record from its parts. */
+export declare function encodeLogRecord(sequence: number, atMs: number, type: string, data: JsonObject): string;
+export declare function encodeLogStreamHeader(header: LogStreamHeader): string;
+/** True for the metadata line a v2 stream file opens with, which carries no record of its own. */
+export declare function isLogStreamHeader(value: unknown): value is LogStreamHeader;
+export declare function parseLogStreamHeader(value: unknown): LogStreamHeader | undefined;
+/** Decodes one line's parsed JSON into a record, accepting both encodings. */
+export declare function parseLogRecord(value: unknown, header?: LogStreamHeader): LogRecord | undefined;
+//# sourceMappingURL=record-codec.d.ts.map

package/dist/record-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-codec.d.ts","sourceRoot":"","sources":["../src/record-codec.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAa,eAAe,EAAE,MAAM,YAAY,CAAC;AAMpF,yCAAyC;AACzC,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAOtG;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAErE;AAED,kGAAkG;AAClG,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAMhF;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,SAAS,GAAG,SAAS,CAK9F"}

package/dist/session-follower.d.ts

@@ -0,0 +1,42 @@
+import type { JsonlTailReadResult } from "./jsonl-tail-reader.ts";
+import type { LogStreamSourceOptions } from "./stream-source.ts";
+import type { LogStream } from "./types.ts";
+type WithSource<TBatch> = TBatch & {
+    path?: string;
+    sessionId?: string;
+};
+/** A domain follower: it can read its own file, and it can be handed lines read on its behalf. */
+export interface LiveLogLineConsumer<TBatch> {
+    poll(): Promise<TBatch>;
+    /** Folds an already-performed read into the follower's state. */
+    consumeRead(result: JsonlTailReadResult): TBatch;
+}
+export interface LiveLogSessionFollowerOptions<TFollower extends LiveLogLineConsumer<TBatch>, TBatch> extends Pick<LogStreamSourceOptions, "logDirectory" | "fallbackPollMs" | "debounceMs" | "persistent" | "readerOptions"> {
+    stream: LogStream;
+    createFollower: (path: string) => TFollower;
+    /** Merges the "did the active session change" signal into a domain batch's own reset/changed fields. */
+    mergeSessionChange: (batch: TBatch, changedSession: boolean) => TBatch;
+    /** Builds the batch returned when there is no current session for this stream. */
+    noStreamBatch: (reset: boolean) => TBatch;
+}
+/** Follows whichever session the shared current-stream pointer names. */
+export declare class LiveLogSessionFollower<TFollower extends LiveLogLineConsumer<TBatch>, TBatch> {
+    private readonly options;
+    private sessionId?;
+    private follower?;
+    private subscription?;
+    private closed;
+    constructor(options: LiveLogSessionFollowerOptions<TFollower, TBatch>);
+    /** Drains whatever has arrived, returning an unchanged batch when nothing has. */
+    poll(): Promise<WithSource<TBatch>>;
+    /** Waits for the next batch that actually carries something, instead of polling for it. */
+    next(): Promise<WithSource<TBatch>>;
+    /** Ends when {@link close} is called, so a follow loop unwinds instead of spinning on empty reads. */
+    [Symbol.asyncIterator](): AsyncIterator<WithSource<TBatch>>;
+    /** Releases this consumer's hold on the shared source, stopping it once no consumer is left. */
+    close(): void;
+    private source;
+    private apply;
+}
+export {};
+//# sourceMappingURL=session-follower.d.ts.map

package/dist/session-follower.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-follower.d.ts","sourceRoot":"","sources":["../src/session-follower.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE,OAAO,KAAK,EAAiB,sBAAsB,EAAyB,MAAM,oBAAoB,CAAC;AACvG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,KAAK,UAAU,CAAC,MAAM,IAAI,MAAM,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzE,kGAAkG;AAClG,MAAM,WAAW,mBAAmB,CAAC,MAAM;IACzC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,iEAAiE;IACjE,WAAW,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAAC;CAClD;AAED,MAAM,WAAW,6BAA6B,CAAC,SAAS,SAAS,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,CAClG,SAAQ,IAAI,CAAC,sBAAsB,EAAE,cAAc,GAAG,gBAAgB,GAAG,YAAY,GAAG,YAAY,GAAG,eAAe,CAAC;IACvH,MAAM,EAAE,SAAS,CAAC;IAClB,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,CAAC;IAC5C,wGAAwG;IACxG,kBAAkB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,KAAK,MAAM,CAAC;IACvE,kFAAkF;IAClF,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;CAC3C;AAED,yEAAyE;AACzE,qBAAa,sBAAsB,CAAC,SAAS,SAAS,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM;IAM3E,OAAO,CAAC,QAAQ,CAAC,OAAO;IALpC,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,CAAY;IAC7B,OAAO,CAAC,YAAY,CAAC,CAAwB;IAC7C,OAAO,CAAC,MAAM,CAAS;IAEvB,YAA6B,OAAO,EAAE,6BAA6B,CAAC,SAAS,EAAE,MAAM,CAAC,EAAI;IAE1F,kFAAkF;IAC5E,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAExC;IAED,2FAA2F;IACrF,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAExC;IAED,sGAAsG;IAC/F,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAOjE;IAED,gGAAgG;IAChG,KAAK,IAAI,IAAI,CAIZ;IAED,OAAO,CAAC,MAAM;IAad,OAAO,CAAC,KAAK;CAgBd"}

package/dist/sessions.d.ts

@@ -0,0 +1,3 @@
+import type { ListedLogSession, LogStream } from "./types.ts";
+export declare function listLogSessions(stream: LogStream, logDirectory?: string, limit?: number): Promise<ListedLogSession[]>;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../src/sessions.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAoB,gBAAgB,EAAE,SAAS,EAAmB,MAAM,YAAY,CAAC;AAIjG,wBAAsB,eAAe,CACnC,MAAM,EAAE,SAAS,EACjB,YAAY,SAAwB,EACpC,KAAK,SAAK,GACT,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAqC7B"}

package/dist/stream-source.d.ts

@@ -0,0 +1,39 @@
+import type { JsonlTailReadResult, JsonlTailReaderOptions } from "./jsonl-tail-reader.ts";
+import type { LogStream } from "./types.ts";
+/** Quiet period a burst of watcher events is collapsed into before the file is drained. */
+export declare const DEFAULT_STREAM_DEBOUNCE_MS = 20;
+/** Longest the source goes without a stat even when no watcher event arrives. */
+export declare const DEFAULT_STREAM_FALLBACK_POLL_MS = 1000;
+/** Most bytes a live follower takes from disk in one drain, matching the read model's indexing batch. */
+export declare const DEFAULT_STREAM_BATCH_BYTES: number;
+export interface LogStreamSourceOptions {
+    stream: LogStream;
+    logDirectory?: string;
+    fallbackPollMs?: number;
+    debounceMs?: number;
+    /** Whether the watchers and fallback timer hold the process open even while nothing is waiting on them. */
+    persistent?: boolean;
+    /** Applied to the shared reader. Only the first subscriber of a stream gets to set these. */
+    readerOptions?: Pick<JsonlTailReaderOptions, "createDecoder" | "maxReadBytes">;
+}
+export interface LogStreamRead extends JsonlTailReadResult {
+    /** The session named by the current-stream pointer, or undefined while no session is active. */
+    current?: {
+        path: string;
+        sessionId: string;
+    };
+    /** Whether {@link current} differs from the one this subscriber last saw. */
+    changedSession: boolean;
+    /** Whether the read stopped at its byte cap with more bytes already on disk. */
+    capped: boolean;
+}
+export interface LogStreamSubscription extends AsyncIterable<LogStreamRead> {
+    /** Drains now and returns whatever has accumulated, empty batch included. */
+    poll(): Promise<LogStreamRead>;
+    /** Resolves only once there is something to report, so an idle stream costs nothing. */
+    next(): Promise<LogStreamRead>;
+    close(): void;
+}
+/** Subscribes to the shared tail of a stream, creating it on first use. */
+export declare function subscribeToLogStream(options: LogStreamSourceOptions): LogStreamSubscription;
+//# sourceMappingURL=stream-source.d.ts.map

package/dist/stream-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-source.d.ts","sourceRoot":"","sources":["../src/stream-source.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAI1F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,2FAA2F;AAC3F,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAC7C,iFAAiF;AACjF,eAAO,MAAM,+BAA+B,OAAQ,CAAC;AACrD,yGAAyG;AACzG,eAAO,MAAM,0BAA0B,QAAc,CAAC;AAEtD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,SAAS,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2GAA2G;IAC3G,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,6FAA6F;IAC7F,aAAa,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,eAAe,GAAG,cAAc,CAAC,CAAC;CAChF;AAED,MAAM,WAAW,aAAc,SAAQ,mBAAmB;IACxD,gGAAgG;IAChG,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,6EAA6E;IAC7E,cAAc,EAAE,OAAO,CAAC;IACxB,gFAAgF;IAChF,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,qBAAsB,SAAQ,aAAa,CAAC,aAAa,CAAC;IACzE,6EAA6E;IAC7E,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;IAC/B,wFAAwF;IACxF,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;IAC/B,KAAK,IAAI,IAAI,CAAC;CACf;AA8SD,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAS3F"}

package/dist/types.d.ts

@@ -0,0 +1,45 @@
+export type LogStream = "capture" | "combat" | "market" | "rewards" | "other";
+export type JsonData = null | boolean | number | string | JsonData[] | JsonObject;
+export interface JsonObject {
+    [key: string]: JsonData | undefined;
+}
+/** A decoded record, in the shape every consumer sees regardless of how it was stored. */
+export interface LogRecord<T extends JsonObject = JsonObject> {
+    schemaVersion: 1 | 2;
+    sessionId: string;
+    sequence: number;
+    recordedAt: string;
+    source: string;
+    type: string;
+    data: T;
+}
+/** First line of a v2 stream file, carrying what v1 repeated on every record. */
+export interface LogStreamHeader {
+    schemaVersion: 2;
+    stream: LogStream;
+    sessionId: string;
+    producer: string;
+    startedAt: string;
+}
+export interface ListedLogSession {
+    id: string;
+    createdAt: string;
+    path: string;
+    active: boolean;
+}
+export interface CurrentLogStream {
+    schemaVersion: 1;
+    stream: LogStream;
+    sessionId: string;
+    startedAt: string;
+    relativePath: string;
+}
+export interface LogSession {
+    id: string;
+    logger(stream: LogStream): JsonLinesLogger;
+    /** Resolves once every record logged before this call has reached the disk on every stream. */
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+import type { JsonLinesLogger } from "./logger.ts";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAC9E,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,EAAE,GAAG,UAAU,CAAC;AAClF,MAAM,WAAW,UAAU;IAAG,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAA;CAAE;AAEnE,0FAA0F;AAC1F,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU;IAC1D,aAAa,EAAE,CAAC,GAAG,CAAC,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,CAAC,CAAC;CACT;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,CAAC,CAAC;IACjB,MAAM,EAAE,SAAS,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,CAAC,CAAC;IACjB,MAAM,EAAE,SAAS,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,eAAe,CAAC;IAC3C,+FAA+F;IAC/F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@kar-mi/spirit-vale-tools-logging",
+  "version": "0.9.0",
+  "description": "Session-oriented logging utilities for Spirit Vale tools.",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kar-mi/spirit-vale-tools.git",
+    "directory": "packages/logging"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun --format esm && bunx tsc --project ./tsconfig.build.json"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  }
+}