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

package/README.md

@@ -0,0 +1,70 @@
+# @kar-mi/spirit-vale-tools-logging
+
+Session-oriented logging utilities for Spirit Vale tools.
+
+> **Internal package.** This package is published only because the domain
+> packages (`combat`, `rewards`) depend on it at runtime; it is
+> installed automatically alongside them and is not a supported public API.
+
+## Install
+
+```sh
+bun add @kar-mi/spirit-vale-tools-logging
+```
+
+## Usage
+
+```ts
+import { createLogSession } from "@kar-mi/spirit-vale-tools-logging";
+
+const session = await createLogSession({
+  producer: "my-tool",
+  streams: ["capture", "combat"],
+});
+
+const logger = session.logger("combat");
+logger.log("combat.event", { kind: "damage", amount: 42 });
+
+await session.flush(); // records so far are on disk; the session stays usable
+await session.close();
+```
+
+## Buffering
+
+`log()` is synchronous and buffers records into byte-bounded batches, appended through one file
+handle per stream. Tune with `batchBytes` (default 256 KiB), `flushIntervalMs` (default 50 ms), and
+`maxBufferedBytes` (default 8 MiB) on `createLogSession`, or per logger.
+
+- `session.flush()` / `logger.flush()` resolve once everything logged before the call is on disk.
+  Call it before a process exits by any path other than `close()`.
+- A write failure is reported once through `onWriteError` and rethrown by `flush()`/`close()`, but
+  later batches are still attempted — a transient error does not stop logging.
+- Records are only dropped when they would push memory past `maxBufferedBytes` (a stalled disk).
+  Each such episode is reported once through `onWriteError`, counted in `logger.stats()`, and the
+  logger resumes accepting records as soon as the queue drains. Sequence numbers are assigned before
+  the drop, so a dropped record leaves a gap that readers can detect.
+
+```ts
+logger.stats(); // { bufferedBytes, queuedBatches, failed, droppedRecords }
+```
+
+## Reading
+
+`subscribeToLogStream` is the single tail of one stream, shared by every consumer of it: one
+`fs.watch` on the current-stream pointer, one on the active session file, one `JsonlTailReader`,
+and one fallback poll — regardless of how many overlays are attached. The domain packages build
+their followers on it; use it directly only for a stream they do not cover.
+
+```ts
+const subscription = subscribeToLogStream({ stream: "combat" });
+for await (const read of subscription) process(read.lines);
+subscription.close();
+```
+
+`next()` settles only when there is something to report, so an idle stream costs nothing beyond a
+debounced watcher event. `poll()` remains for consumers driving their own clock; unlike `next()` it
+always re-reads the pointer, so it reflects a session switch as of the call. Watcher events on
+Windows can be coalesced or dropped around rotation and rename, so `DEFAULT_STREAM_FALLBACK_POLL_MS`
+bounds how long such a miss can stall a consumer.
+
+See the [package guide](https://github.com/kar-mi/spirit-vale-tools/blob/main/docs/packages.md) for registry setup and usage.

package/dist/combat-sanitizer.d.ts

@@ -0,0 +1,4 @@
+import type { JsonObject } from "./types.ts";
+/** Structural allowlist for shareable combat records. Returns undefined for diagnostics/unknown records. */
+export declare function sanitizeCombatData(type: string, data: JsonObject): JsonObject | undefined;
+//# sourceMappingURL=combat-sanitizer.d.ts.map

package/dist/combat-sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"combat-sanitizer.d.ts","sourceRoot":"","sources":["../src/combat-sanitizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAK7C,4GAA4G;AAC5G,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAMzF"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { JsonLinesLogger, activateLogSession, createLogSession, readCurrentLogStream, writeCurrentLogStreamPointer, } from "./logger.ts";
+export { encodeLogRecord, encodeLogStreamHeader, isLogStreamHeader, parseLogRecord, parseLogStreamHeader, } from "./record-codec.ts";
+export type { CreateLogSessionOptions, JsonLinesLoggerOptions, JsonLinesLoggerStats, LoggerTuning, LogWriteFailure, } from "./logger.ts";
+export { sanitizeCombatData } from "./combat-sanitizer.ts";
+export { defaultLogDirectory, currentStreamPointerPath, streamCategoryDirectory, streamSessionPath, } from "./paths.ts";
+export { listLogSessions } from "./sessions.ts";
+export { decimal, isMissing, isRecord, nullableString } from "./predicates.ts";
+export type { LiveLogStatus } from "./predicates.ts";
+export { JsonlTailReader } from "./jsonl-tail-reader.ts";
+export type { JsonlTailReadResult, JsonlTailReaderOptions } from "./jsonl-tail-reader.ts";
+export { LiveLogSessionFollower } from "./session-follower.ts";
+export type { LiveLogLineConsumer, LiveLogSessionFollowerOptions } from "./session-follower.ts";
+export { DEFAULT_STREAM_BATCH_BYTES, DEFAULT_STREAM_DEBOUNCE_MS, DEFAULT_STREAM_FALLBACK_POLL_MS, subscribeToLogStream, } from "./stream-source.ts";
+export type { LogStreamRead, LogStreamSourceOptions, LogStreamSubscription } from "./stream-source.ts";
+export type { CurrentLogStream, JsonData, JsonObject, LogRecord, LogSession, ListedLogSession, LogStream, LogStreamHeader, } from "./types.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,4BAA4B,GAC7B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,uBAAuB,EACvB,sBAAsB,EACtB,oBAAoB,EACpB,YAAY,EACZ,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC/E,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,YAAY,EAAE,mBAAmB,EAAE,6BAA6B,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,EAC1B,+BAA+B,EAC/B,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,aAAa,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACvG,YAAY,EACV,gBAAgB,EAChB,QAAQ,EACR,UAAU,EACV,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,SAAS,EACT,eAAe,GAChB,MAAM,YAAY,CAAC"}