@effected/jsonl 0.9.0 → 0.11.0

package/Envelope.js

@@ -1,22 +1,14 @@
-import { LineSlice } from "./LineSlice.js";
 import { InvalidData, UnknownEvent, UnserializableData } from "./JsonlError.js";
-import { Line } from "./Line.js";
-import { Effect, Option, Result, Schema } from "effect";
+import { Line, isBlank } from "./Line.js";
+import { DateTime, Option, Result, Schema } from "effect";
 
 //#region src/Envelope.ts
 /**
-* Stage one of the read path: the envelope with its payload left undecoded.
+* Stage one: the envelope with its payload left undecoded.
 *
-* A `Schema.Struct` rather than a `Schema.Class` deliberately. This is the hot
-* path — it runs for every line of every read, including the lines a `Slice` is
-* about to discard — and it is a transient the caller never holds, so there is
-* nothing to gain from wrapping each one in a class instance.
-*
-* `data` is `Schema.Unknown`, which passes the payload through without
-* traversing it. That is what keeps frame decoding independent of payload
-* depth, and what lets filtering happen before any payload schema runs.
-*
-* @public
+* A `Schema.Struct`, not a class: it runs for every line of every read,
+* including the lines a slice is about to discard. `data` is `Schema.Unknown`,
+* which passes the payload through without traversing it.
 */
 const EnvelopeFrame = Schema.Struct({
 	at: Schema.DateTimeUtcFromString,
@@ -27,36 +19,47 @@ const EnvelopeFrame = Schema.Struct({
 /**
 * The tag→definition lookup, built once per registry rather than once per line.
 *
-* A registry is a frozen array declared at module scope and handed to every
-* call, so it is a legitimate cache key: the same array always indexes to the
-* same map. Building the map per call was measured at 1.23x the cost of this on
-* the per-line decode path — small, but paid once per line of every read, which
-* is exactly the shape of cost this package exists to keep down.
-*
-* `WeakMap` so a registry that goes out of scope takes its index with it.
+* A registry is an array declared at module scope and handed to every call, so
+* it is a legitimate cache key; `WeakMap` so a registry that goes out of scope
+* takes its index with it.
 */
 const registryIndex = /* @__PURE__ */ new WeakMap();
 const indexRegistry = (events) => {
-	const cached = registryIndex.get(events);
-	if (cached !== void 0) return cached;
-	Object.freeze(events);
-	const index = new Map(events.map((event) => [event.tag, event]));
-	registryIndex.set(events, index);
+	let index = registryIndex.get(events);
+	if (index === void 0) {
+		Object.freeze(events);
+		index = new Map(events.map((event) => [event.tag, event]));
+		registryIndex.set(events, index);
+	}
 	return index;
 };
 const decodeFrame = Schema.decodeUnknownResult(EnvelopeFrame);
-const encodeAt = Schema.encodeUnknownResult(Schema.DateTimeUtcFromString);
+const positionOf = (line) => ({
+	offset: line.offset,
+	end: line.end
+});
+/**
+* Stage one only: parse a line and decode its frame, leaving `data` untouched.
+*
+* @internal
+*/
+const frameResult = (line) => {
+	const parsed = Line.parseResult(line);
+	if (Result.isFailure(parsed)) return Result.fail(parsed.failure);
+	const frame = decodeFrame(parsed.success);
+	if (Result.isFailure(frame)) return Result.fail(new InvalidData({
+		line,
+		event: Option.none(),
+		error: frame.failure
+	}));
+	return Result.succeed(frame.success);
+};
 /**
 * Stage two: apply the registered payload schema to an already-decoded frame.
 *
-* A module-level const rather than a member of the exported `Envelope` object,
-* and deliberately not exported. API Extractor honours release tags on
-* top-level declarations, not on members of an exported object literal — so an
-* `@internal` tag down there is inert text and the member ships as supported
-* public API. Hoisting is what actually keeps it off the surface.
+* The one payload-decode path; every decode, filtered or not, goes through it.
 *
-* Both `decodeResult` and `decodeSelectedResult` call this, so there is exactly
-* one payload-decode path and the filtered and unfiltered forms cannot drift.
+* @internal
 */
 const completeResult = (events, line, frame) => {
 	const { at, event, scope, data } = frame;
@@ -77,30 +80,29 @@ const completeResult = (events, line, frame) => {
 		event,
 		...scope === void 0 ? {} : { scope },
 		data: decoded.success,
-		line
+		position: positionOf(line)
 	});
 };
 /**
 * Decoding, encoding and the envelope-level walk-back.
 *
-* Every operation here is synchronous and `Result`-based; the `Effect` forms are
-* defined **in terms of** the sync ones via `Effect.fromResult`, so the two can
-* never drift into two implementations of the same rule.
+* Every operation is synchronous and `Result`-based, so a hook script can read
+* a journal with no Effect runtime. Lift one into an `Effect` with
+* `Effect.fromResult` where a program needs it.
 *
 * @example
 * ```ts
-* import { Envelope, JsonlEvent, Line } from "@effected/jsonl";
-* import { Result, Schema } from "effect";
+* import { Envelope, JsonlEvent } from "@effected/jsonl";
+* import { Option, Schema } from "effect";
 *
-* const events = [JsonlEvent.make("started", { data: Schema.Struct({ id: Schema.String }) })] as const;
+* const events = [JsonlEvent.make("state", { data: Schema.Struct({ round: Schema.Number }) })] as const;
 *
 * declare const sourceText: string;
 *
-* for (const line of Line.split(sourceText)) {
-*   const decoded = Envelope.decodeResult(events, line);
-*   if (Result.isSuccess(decoded) && decoded.success.event === "started") {
-*     decoded.success.data.id; // typed from the registered payload schema
-*   }
+* // The whole read path for a snapshot journal, with no runtime.
+* const current = Envelope.lastValid(events, sourceText);
+* if (Option.isSome(current)) {
+*   current.value.data.round; // typed from the registered payload schema
 * }
 * ```
 *
@@ -108,109 +110,50 @@ const completeResult = (events, line, frame) => {
 */
 const Envelope = {
 	/**
-	* Stage one only: decode the frame, leaving `data` untouched.
-	*
-	* This is what filtering reads. It never runs a payload schema, so its cost
-	* is independent of payload size and depth, and a line destined to be
-	* filtered out never pays for its payload at all.
-	*
-	* @param line - A slice from `Line.split`.
-	* @returns The frame with its source `line` attached, or `MalformedLine`
-	*   when the line is not JSON, or `InvalidData` when it is JSON that is not
-	*   an envelope frame.
-	*/
-	frameResult: (line) => {
-		const parsed = Line.parseResult(line);
-		if (Result.isFailure(parsed)) return Result.fail(parsed.failure);
-		const frame = decodeFrame(parsed.success.value);
-		if (Result.isFailure(frame)) return Result.fail(new InvalidData({
-			line,
-			event: Option.none(),
-			error: frame.failure
-		}));
-		return Result.succeed({
-			...frame.success,
-			line
-		});
-	},
-	/**
-	* Decode one line into a fully validated envelope, running both stages.
+	* Decode one line into a fully validated envelope.
 	*
 	* @param events - The registry defining which tags are legal and what their
 	*   payloads must look like.
 	* @param line - A slice from `Line.split`.
-	* @returns The envelope, or the typed reason it is not one: not JSON
-	*   (`MalformedLine`), not an envelope or a bad payload (`InvalidData`), or
-	*   a tag this registry does not define (`UnknownEvent`).
+	* @returns The envelope, or why the line is not one.
 	*/
 	decodeResult: (events, line) => {
-		const frame = Envelope.frameResult(line);
-		if (Result.isFailure(frame)) return Result.fail(frame.failure);
-		return completeResult(events, line, frame.success);
-	},
-	/**
-	* Decode a line only if its **frame** is selected, running the payload schema
-	* for selected lines only.
-	*
-	* This is the structural form of the filter-before-decode guarantee: when
-	* `select` rejects the frame, the registered `data` schema is never reached,
-	* so a consumer reading a journal it shares with a noisy neighbour pays
-	* nothing for the neighbour's payloads. Writing the filter *after* a full
-	* decode would produce identical output while charging for every line — which
-	* is why this exists as its own operation rather than as advice.
-	*
-	* @param events - The registry to validate against.
-	* @param line - A slice from `Line.split`.
-	* @param select - Predicate over the decoded frame — `at`, `event`, `scope`
-	*   and the raw undecoded `data`.
-	* @returns `Option.none()` when the frame is not selected; otherwise the
-	*   fully decoded envelope, or the typed reason it is not one.
-	*/
-	decodeSelectedResult: (events, line, select) => {
-		const frame = Envelope.frameResult(line);
-		if (Result.isFailure(frame)) return Option.some(Result.fail(frame.failure));
-		if (!select(frame.success)) return Option.none();
-		return Option.some(completeResult(events, line, frame.success));
+		const frame = frameResult(line);
+		return Result.isFailure(frame) ? Result.fail(frame.failure) : completeResult(events, line, frame.success);
 	},
 	/**
 	* Decode every non-blank line, reporting failures rather than dropping them.
 	*
-	* Same contract as `Line.parseAll` one layer down: a line that is not a
-	* legal envelope is a `Result` in the array, never a gap in it.
+	* A line that is not a legal envelope is a `Result` in the array, never a gap
+	* in it: whether a hole is tolerable is the caller's decision.
 	*
 	* @param events - The registry to validate against.
 	* @param text - JSONL source text.
+	* @param base - The byte offset `text` starts at in its file.
 	* @returns One `Result` per non-blank line, in file order.
 	*/
-	decodeAllResult: (events, text) => {
-		const results = [];
-		for (const line of Line.split(text)) if (line.text.trim() !== "") results.push(Envelope.decodeResult(events, line));
-		return results;
-	},
+	decodeAllResult: (events, text, base = 0) => Line.split(text, base).filter((line) => !isBlank(line)).map((line) => Envelope.decodeResult(events, line)),
 	/**
-	* Walk back from the end to the last valid **envelope**.
-	*
-	* This is the binding definition of "the last valid line", and the envelope
-	* layer is where it has to live. `Line.lastValid` stops at JSON validity,
-	* which is not enough: a torn scalar tail (`42` cut mid-write leaves `4`)
-	* parses cleanly as a different value, so a JSON-level walk-back would hand
-	* back corruption as the current state. An envelope is always an object,
-	* every strict prefix of an object text is invalid JSON, and a bare `4` is
-	* not an envelope — so this walk-back detects the torn tail that the one
-	* below it structurally cannot.
+	* Walk back from the end to the last valid **envelope** — the journal's
+	* current state.
 	*
-	* Decoding stops at the first success, so the cost tracks the damage at the
-	* tail rather than the age of the file.
+	* A torn tail is stepped over, and so is any number of malformed, foreign or
+	* blank trailing lines. Validity is judged at the envelope, not merely as
+	* JSON: a torn *scalar* (`42` cut mid-write leaves `4`) parses cleanly as a
+	* different value, but is not an envelope. Decoding stops at the first
+	* success, so the cost tracks the damage at the tail, not the file's age.
 	*
 	* @param events - The registry to validate against.
-	* @param text - JSONL source text.
+	* @param text - JSONL source text — the whole file, or a tail of it that
+	*   begins at a line boundary.
+	* @param base - The byte offset `text` starts at in its file.
 	* @returns The last valid envelope, or `Option.none()` if there is none.
 	*/
-	lastValidResult: (events, text) => {
-		const lines = Line.split(text);
+	lastValid: (events, text, base = 0) => {
+		const lines = Line.split(text, base);
 		for (let index = lines.length - 1; index >= 0; index--) {
 			const line = lines[index];
-			if (line === void 0 || line.text.trim() === "") continue;
+			if (isBlank(line)) continue;
 			const decoded = Envelope.decodeResult(events, line);
 			if (Result.isSuccess(decoded)) return Option.some(decoded.success);
 		}
@@ -220,80 +163,45 @@ const Envelope = {
 	* Encode one envelope into a complete JSONL line, terminator included.
 	*
 	* The trailing `\n` is part of the returned string on purpose: the
-	* cooperative-writer contract is one `writeAll` of a *complete line*, and an
-	* API that returned the text without its terminator would invite a caller to
-	* write the two separately — which is exactly the interleaving the contract
-	* exists to prevent.
-	*
-	* No `Schema.Union` is involved. The tag is known, so the payload schema is
-	* a direct registry lookup; a union would buy nothing and decode eagerly.
+	* cooperative-writer contract is one write of a *complete line*, and an API
+	* returning the text without its terminator would invite writing the two
+	* separately.
 	*
 	* @param events - The registry to validate against.
-	* @param envelope - The event tag, its payload, the service-assigned
-	*   timestamp, and an optional scope.
-	* @returns The encoded line, or `UnknownEvent` for a tag the registry does
-	*   not define, `InvalidData` when the payload does not satisfy its schema,
-	*   or `UnserializableData` when the encoded payload cannot be turned into
-	*   JSON (a bigint or a reference cycle).
+	* @param envelope - The event tag, its payload, the timestamp, and an
+	*   optional scope.
+	* @returns The encoded line, or `InvalidData` when the payload does not
+	*   satisfy its schema, `UnserializableData` when the encoded payload is not
+	*   JSON (a bigint or a reference cycle), or `UnknownEvent` for a tag the
+	*   registry does not define.
 	*/
 	encodeResult: (events, envelope) => {
-		const empty = new LineSlice({
-			offset: 0,
-			end: 0,
-			length: 0,
-			text: "",
-			terminated: false
-		});
 		const definition = indexRegistry(events).get(envelope.event);
 		if (definition === void 0) return Result.fail(new UnknownEvent({
-			line: empty,
 			event: envelope.event,
 			known: events.map((e) => e.tag)
 		}));
 		const data = Schema.encodeUnknownResult(definition.data)(envelope.data);
 		if (Result.isFailure(data)) return Result.fail(new InvalidData({
-			line: empty,
 			event: Option.some(envelope.event),
 			error: data.failure
 		}));
-		const at = encodeAt(envelope.at);
-		if (Result.isFailure(at)) return Result.fail(new InvalidData({
-			line: empty,
-			event: Option.some(envelope.event),
-			error: at.failure
-		}));
-		let text;
 		try {
-			text = JSON.stringify({
-				at: at.success,
+			const text = JSON.stringify({
+				at: DateTime.formatIso(envelope.at),
 				event: envelope.event,
 				...envelope.scope === void 0 ? {} : { scope: envelope.scope },
 				data: data.success === void 0 ? null : data.success
 			});
+			return Result.succeed(`${text}\n`);
 		} catch (cause) {
 			return Result.fail(new UnserializableData({
 				event: envelope.event,
 				cause
 			}));
 		}
-		return Result.succeed(`${text}\n`);
-	},
-	/**
-	* `Envelope.decodeResult` in the `Effect` channel.
-	*
-	* Prefer the sync form in a hook or any caller that has no runtime; this
-	* exists for programs that already are one. Fails with `MalformedLine`,
-	* `InvalidData` or `UnknownEvent`; requires nothing.
-	*/
-	decode: (events, line) => Effect.fromResult(Envelope.decodeResult(events, line)),
-	/**
-	* `Envelope.encodeResult` in the `Effect` channel.
-	*
-	* Fails with `UnknownEvent`, `InvalidData` or `UnserializableData`; requires
-	* nothing.
-	*/
-	encode: (events, envelope) => Effect.fromResult(Envelope.encodeResult(events, envelope))
+	}
 };
 
 //#endregion
-export { Envelope, EnvelopeFrame };
+export { Envelope, completeResult, frameResult };