@effected/jsonl 0.1.0

package/Envelope.js

@@ -0,0 +1,267 @@
+import { LineSlice } from "./LineSlice.js";
+import { InvalidData, UnknownEvent, UnserializableData } from "./JsonlError.js";
+import { Line } from "./Line.js";
+import { Effect, Option, Result, Schema } from "effect";
+
+//#region src/Envelope.ts
+/**
+* Stage one of the read path: 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
+*/
+const EnvelopeFrame = Schema.Struct({
+	at: Schema.DateTimeUtcFromString,
+	event: Schema.String,
+	scope: Schema.optionalKey(Schema.String),
+	data: Schema.Unknown
+});
+/**
+* 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.
+*/
+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);
+	return index;
+};
+const decodeFrame = Schema.decodeUnknownResult(EnvelopeFrame);
+const encodeAt = Schema.encodeUnknownResult(Schema.DateTimeUtcFromString);
+/**
+* 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.
+*
+* Both `decodeResult` and `decodeSelectedResult` call this, so there is exactly
+* one payload-decode path and the filtered and unfiltered forms cannot drift.
+*/
+const completeResult = (events, line, frame) => {
+	const { at, event, scope, data } = frame;
+	const definition = indexRegistry(events).get(event);
+	if (definition === void 0) return Result.fail(new UnknownEvent({
+		line,
+		event,
+		known: events.map((e) => e.tag)
+	}));
+	const decoded = Schema.decodeUnknownResult(definition.data)(data);
+	if (Result.isFailure(decoded)) return Result.fail(new InvalidData({
+		line,
+		event: Option.some(event),
+		error: decoded.failure
+	}));
+	return Result.succeed({
+		at,
+		event,
+		...scope === void 0 ? {} : { scope },
+		data: decoded.success,
+		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.
+*
+* @public
+*/
+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`.
+	*/
+	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.
+	*
+	* @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`).
+	*/
+	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));
+	},
+	/**
+	* 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.
+	*/
+	decodeAllResult: (events, text) => {
+		const results = [];
+		for (const line of Line.split(text)) if (line.text.trim() !== "") results.push(Envelope.decodeResult(events, line));
+		return results;
+	},
+	/**
+	* 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.
+	*
+	* Decoding stops at the first success, so the cost tracks the damage at the
+	* tail rather than the age of the file.
+	*
+	* @param events - The registry to validate against.
+	* @param text - JSONL source text.
+	* @returns The last valid envelope, or `Option.none()` if there is none.
+	*/
+	lastValidResult: (events, text) => {
+		const lines = Line.split(text);
+		for (let index = lines.length - 1; index >= 0; index--) {
+			const line = lines[index];
+			if (line === void 0 || line.text.trim() === "") continue;
+			const decoded = Envelope.decodeResult(events, line);
+			if (Result.isSuccess(decoded)) return Option.some(decoded.success);
+		}
+		return Option.none();
+	},
+	/**
+	* 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.
+	*
+	* @param events - The registry to validate against.
+	* @param envelope - The event tag, its payload, the service-assigned
+	*   timestamp, and an optional scope.
+	*/
+	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,
+				event: envelope.event,
+				...envelope.scope === void 0 ? {} : { scope: envelope.scope },
+				data: data.success === void 0 ? null : data.success
+			});
+		} catch (cause) {
+			return Result.fail(new UnserializableData({
+				event: envelope.event,
+				cause
+			}));
+		}
+		return Result.succeed(`${text}\n`);
+	},
+	/**
+	* {@link (Envelope:variable).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.
+	*/
+	decode: (events, line) => Effect.fromResult(Envelope.decodeResult(events, line)),
+	/**
+	* {@link (Envelope:variable).encodeResult} in the `Effect` channel.
+	*/
+	encode: (events, envelope) => Effect.fromResult(Envelope.encodeResult(events, envelope))
+};
+
+//#endregion
+export { Envelope, EnvelopeFrame };