@effected/jsonl 0.1.0

package/JsonlError.js

@@ -0,0 +1,246 @@
+import { LineSlice } from "./LineSlice.js";
+import { Option, Schema, SchemaError } from "effect";
+
+//#region src/JsonlError.ts
+/**
+* The `@effected/jsonl` error taxonomy.
+*
+* Every tag names a distinct recovery a caller would actually make, and every
+* cause is carried structurally rather than stringified. Core's `PlatformError`
+* passes through untranslated rather than being wrapped.
+*
+* @since 0.1.0
+*/
+/**
+* `Schema.SchemaError` as a schema of itself.
+*
+* A schema issue tree is a live object graph, not something with a wire form,
+* so it is declared by its type guard rather than given an encoding. That is
+* what lets {@link InvalidData} be an ordinary schema-backed tagged error while
+* still carrying the failure **structurally** — `error.issue` keeps its paths
+* and expected types — instead of flattening it to a string at the boundary.
+*/
+const SchemaErrorFromSelf = Schema.declare(SchemaError.isSchemaError);
+/**
+* A journal line that is not valid JSON.
+*
+* **This is the expected steady state at the tail of a live journal**, not
+* necessarily corruption: a writer caught mid-`write` leaves a partial final
+* line, and `LineSlice.terminated` is what distinguishes the two cases. An
+* unterminated malformed line is a torn tail that the next append completes; a
+* *terminated* malformed line is a hole in the history that will never heal.
+*
+* Malformed input always fails through this typed channel — never as a defect,
+* and never by being silently dropped from a read.
+*
+* @example
+* ```ts
+* import { Line } from "@effected/jsonl";
+* import { Result } from "effect";
+*
+* const [line] = Line.split('{"a":');
+* const parsed = Line.parseResult(line!);
+* if (Result.isFailure(parsed)) {
+*   parsed.failure.line.terminated; // false — a torn tail, not a hole
+* }
+* ```
+*
+* @public
+*/
+var MalformedLine = class extends Schema.TaggedErrorClass()("MalformedLine", { 
+/** The offending line, with its byte offsets into the source. */
+line: LineSlice }) {
+	get message() {
+		return `JSONL ${this.line.terminated ? "malformed line" : "unterminated final line"} at byte offset ${this.line.offset}`;
+	}
+};
+/**
+* A line whose `event` tag is not in the registry.
+*
+* Typed rather than a defect on purpose: a journal written by an older or newer
+* version of the same application is hostile input in the technical sense, and
+* a reader that crashed on an unrecognized tag would be unable to skip forward
+* past one. The known tags travel with the error so a caller can report the
+* mismatch without reaching back for the registry.
+*
+* @public
+*/
+var UnknownEvent = class extends Schema.TaggedErrorClass()("UnknownEvent", {
+	/** The offending line, with its byte offsets into the source. */
+	line: LineSlice,
+	/** The unrecognized tag as it appeared on the envelope. */
+	event: Schema.String,
+	/** The tags this journal's registry does define. */
+	known: Schema.Array(Schema.String)
+}) {
+	get message() {
+		return `unknown JSONL event ${JSON.stringify(this.event)} at byte offset ${this.line.offset}`;
+	}
+};
+/**
+* A line whose envelope or payload failed schema validation.
+*
+* Covers both stages of the two-stage decode, distinguished by `event`: the
+* frame itself (`Option.none()` — the line is JSON but not an envelope) and a
+* registered payload (`Option.some(tag)` — the envelope is well-formed but its
+* `data` does not match the schema registered for that tag).
+*
+* The `SchemaError` is carried **whole**, so `error.issue` is the full issue
+* tree with its paths and expected types intact. Nothing here is stringified;
+* `message` renders lazily and only when something asks for it.
+*
+* @public
+*/
+var InvalidData = class extends Schema.TaggedErrorClass()("InvalidData", {
+	/** The offending line, with its byte offsets into the source. */
+	line: LineSlice,
+	/**
+	* The event tag whose payload schema rejected the data, or `none` when it
+	* was the envelope frame itself that failed.
+	*/
+	event: Schema.Option(Schema.String),
+	/** The schema failure, carried structurally — `issue` is the full tree. */
+	error: SchemaErrorFromSelf
+}) {
+	get message() {
+		return `invalid JSONL ${Option.isSome(this.event) ? `payload for event ${JSON.stringify(this.event.value)}` : "envelope"} at byte offset ${this.line.offset}: ${this.error.message}`;
+	}
+};
+/**
+* An append attempted after a terminal event, by an event not marked `reopen`.
+*
+* A journal whose tail is terminal is quiescent: it is finished, and appending
+* to it would silently resurrect a closed loop. Reopening is legal but must be
+* declared, which is what `reopen` marks.
+*
+* @public
+*/
+var TerminalViolation = class extends Schema.TaggedErrorClass()("TerminalViolation", {
+	/** The tag of the event whose append was refused. */
+	event: Schema.String,
+	/** The terminal event currently at the tail of the journal. */
+	terminal: Schema.String
+}) {
+	get message() {
+		return `cannot append ${JSON.stringify(this.event)}: the journal is terminal at ${JSON.stringify(this.terminal)}`;
+	}
+};
+/**
+* An operation against a journal file that does not exist.
+*
+* A missing journal is a **legal state** — building the layer over a path that
+* does not exist yet succeeds, and the watcher activates once the file appears.
+* What is not legal is materializing it implicitly: `append`, `query` and
+* `latest` fail with this rather than creating the file, so a typo in a path
+* cannot quietly produce a second, empty journal that looks like a working
+* system with no history. Creation is always explicit, via `create`.
+*
+* @public
+*/
+var JournalNotFound = class extends Schema.TaggedErrorClass()("JournalNotFound", { 
+/** The path that does not exist. */
+path: Schema.String }) {
+	get message() {
+		return `journal not found: ${this.path}`;
+	}
+};
+/**
+* A payload that validated against its schema but cannot be serialized to JSON.
+*
+* The two reachable causes are a `bigint` anywhere in the encoded value and a
+* reference cycle; `JSON.stringify` throws a `TypeError` for both. A payload
+* schema is free to permit either — `Schema.Unknown` permits everything — so
+* schema validity does not imply serializability and the encode path has to
+* treat them as separate questions.
+*
+* This is its own tag rather than a flavour of {@link InvalidData} because the
+* recovery differs: `InvalidData` means the value is wrong and the caller
+* should fix the value, while this means the value is fine but unrepresentable
+* in this format and the caller must change the *shape* they are journaling.
+*
+* The thrown value is carried as-is under `cause` — never stringified, and
+* never re-thrown. A raw `TypeError` escaping the encode path would be
+* especially bad here: `Effect.fromResult` evaluates its argument eagerly, so
+* an unguarded throw happens at **construction** of the `Effect`, before any
+* fiber exists, where not even `Effect.runSyncExit` can catch it.
+*
+* @public
+*/
+var UnserializableData = class extends Schema.TaggedErrorClass()("UnserializableData", {
+	/** The event tag whose payload could not be serialized. */
+	event: Schema.String,
+	/** The value `JSON.stringify` threw, carried structurally. */
+	cause: Schema.Unknown
+}) {
+	get message() {
+		const detail = this.cause instanceof Error ? this.cause.message : "value is not JSON-serializable";
+		return `cannot serialize payload for event ${JSON.stringify(this.event)}: ${detail}`;
+	}
+};
+/**
+* An append refused because the journal's scope has closed.
+*
+* Its own tag rather than a flavour of {@link TerminalViolation}, because the
+* recoveries have nothing in common: a terminal journal is a *state* the
+* consumer can reason about and reopen from with a `reopen` event, while a
+* closed one is a *lifecycle* fact — this service is gone, and the only moves
+* are to build a new layer or stop.
+*
+* Refusal is deliberately a typed failure rather than a wait. A `Latch` would
+* suspend the late append with no failure channel, turning "the journal is
+* closing" into a hang; failing fast is what lets a caller react.
+*
+* @public
+*/
+var JournalClosed = class extends Schema.TaggedErrorClass()("JournalClosed", { 
+/** The tag of the event whose append was refused. */
+event: Schema.String }) {
+	get message() {
+		return `cannot append ${JSON.stringify(this.event)}: the journal is closed`;
+	}
+};
+/**
+* The journal file was truncated or replaced beneath a reader.
+*
+* The cooperative-writer contract is append-only: a journal only ever grows,
+* and every cursor this package hands out depends on that. When the file shrinks
+* below a tracked offset, or the path comes to name a different file entirely,
+* the contract has been broken by something outside the package and every
+* offset-derived belief is now meaningless.
+*
+* Surfaced rather than repaired, deliberately. Silently re-reading from zero
+* would paper over a real operational fault — a rotating log shipper, a
+* `>` where `>>` was meant — and leave projections quietly inconsistent with
+* the file. The recovery is the consumer's: discard cursor-derived state,
+* re-read, and tell somebody.
+*
+* One tag rather than two, though `reason` distinguishes the causes: truncation
+* and replacement have the **same** recovery, and a tag per cause would split
+* one recovery across two tags.
+*
+* @remarks
+* Detection is as complete as the platform allows and no more. Truncation is
+* caught by size; replacement is caught by inode identity, which
+* `FileSystem.File.Info` exposes as an **`Option`** — on a platform that does
+* not report it, a replacement at equal or greater size is undetectable and
+* only truncation is caught.
+*
+* @public
+*/
+var JournalResync = class extends Schema.TaggedErrorClass()("JournalResync", {
+	/** The journal path whose file changed identity or shrank. */
+	path: Schema.String,
+	/** Which contract breach was detected. Diagnostic; the recovery is the same. */
+	reason: Schema.Literals(["truncated", "replaced"]),
+	/** The logical offset the reader had consumed to. */
+	expected: Schema.Number,
+	/** The file's logical size when the breach was noticed. */
+	actual: Schema.Number
+}) {
+	get message() {
+		return `journal ${this.reason} beneath the reader at ${this.path}: consumed ${this.expected}, file is now ${this.actual}`;
+	}
+};
+
+//#endregion
+export { InvalidData, JournalClosed, JournalNotFound, JournalResync, MalformedLine, TerminalViolation, UnknownEvent, UnserializableData };

package/JsonlEvent.js

@@ -0,0 +1,45 @@
+//#region src/JsonlEvent.ts
+/**
+* Runtime type identifier marking a JSONL event definition.
+*
+* @public
+*/
+const JsonlEventTypeId = "~effected/jsonl/JsonlEvent";
+/**
+* Defines an event.
+*
+* The `const` type parameters are load-bearing: they keep `"unlinked"` a
+* literal rather than widening it to `string`, and keep `terminal: true` a
+* literal `true`, so both survive into the derived envelope union where the
+* narrowing and the terminal/reopen state machine depend on them.
+*
+* `data` is required rather than defaulted. A payload-less event says so
+* explicitly with `Schema.Void`, because a silent default would make a typo in
+* the options object look like a deliberate void payload.
+*
+* @example
+* ```ts
+* import { JsonlEvent } from "@effected/jsonl";
+* import { Schema } from "effect";
+*
+* const MailReceived = JsonlEvent.make("mail-received", {
+*   data: Schema.Struct({ round: Schema.Number }),
+* });
+* const Unlinked = JsonlEvent.make("unlinked", { data: Schema.Void, terminal: true });
+* const Relinked = JsonlEvent.make("relinked", { data: Schema.Void, reopen: true });
+*
+* const registry = [MailReceived, Unlinked, Relinked] as const;
+* ```
+*
+* @public
+*/
+const JsonlEvent = { make: (tag, options) => ({
+	[JsonlEventTypeId]: JsonlEventTypeId,
+	tag,
+	data: options.data,
+	terminal: options.terminal ?? false,
+	reopen: options.reopen ?? false
+}) };
+
+//#endregion
+export { JsonlEvent, JsonlEventTypeId };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Line.js

@@ -0,0 +1,219 @@
+import { LineSlice } from "./LineSlice.js";
+import { MalformedLine } from "./JsonlError.js";
+import { utf8Length } from "./internal/utf8.js";
+import { Option, Result, Schema } from "effect";
+
+//#region src/Line.ts
+/**
+* The pure, synchronous line layer of a JSONL journal.
+*
+* Nothing here touches `FileSystem`, builds an `Effect`, or needs a runtime —
+* a `PreToolUse` hook script reads the current state of a journal with one
+* call. That is a contract, not a convenience: a hook that had to construct an
+* Effect runtime to read one line would not adopt this package.
+*
+* @since 0.1.0
+*/
+/**
+* A line that parsed as JSON, paired with the slice it came from.
+*
+* `value` is deliberately `unknown`: this layer knows JSON, not envelopes.
+* Validating `event`, `at`, `scope` and the registered payload schema is the
+* envelope layer's job, and keeping the split means a malformed *envelope* and
+* a malformed *line* stay distinguishable failures.
+*
+* @public
+*/
+var ParsedLine = class extends Schema.Class("ParsedLine")({
+	/** Where this line lives in the source. */
+	line: LineSlice,
+	/** The parsed JSON value — any JSON value, not necessarily an object. */
+	value: Schema.Unknown
+}) {};
+/** Whether a line carries nothing but whitespace. */
+const isBlank = (line) => line.text.trim() === "";
+/**
+* Splitting, parsing and corrupt-tail walk-back over JSONL text.
+*
+* Every operation is total and synchronous: it returns a value for every
+* input, including empty text, torn tails, and text that is not JSONL at all.
+* Nothing here throws — a `JSON.parse` failure becomes a {@link MalformedLine}
+* in the returned `Result`, because a journal is untrusted input and untrusted
+* input fails typed.
+*
+* @public
+*/
+var Line = class Line {
+	/**
+	* The UTF-8 byte length of a string.
+	*
+	* Exposed because callers doing their own offset arithmetic must measure
+	* the same way this module does. `String.length` is a different number for
+	* any non-ASCII line.
+	*
+	* An unpaired surrogate counts as the 3 bytes of U+FFFD, matching what a
+	* UTF-8 write actually emits. The offsets therefore stay true to the file
+	* even though the character itself cannot survive the round trip — text
+	* read back from a UTF-8 journal never contains one.
+	*
+	* @example
+	* ```ts
+	* import { Line } from "@effected/jsonl";
+	*
+	* Line.byteLength("\u{1F600}"); // 4
+	* "\u{1F600}".length;           // 2 — the trap
+	* ```
+	*/
+	static byteLength(text) {
+		return utf8Length(text);
+	}
+	/**
+	* Split text into candidate lines with byte-exact offsets.
+	*
+	* Lines are separated by `\n`; a `\r` immediately preceding it is treated as
+	* part of the terminator, so CRLF journals split identically to LF ones. A
+	* bare `\r` is ordinary content, because only `\n` terminates.
+	*
+	* A trailing terminator does **not** produce a phantom empty final line, so
+	* a well-formed journal yields exactly as many slices as it has entries.
+	* Interior blank lines *are* returned — they are real bytes at real offsets,
+	* and hiding them would make the offsets lie.
+	*
+	* Only the final slice can have `terminated: false`.
+	*
+	* @param text - JSONL source text.
+	* @returns One {@link LineSlice} per candidate line, in source order.
+	*/
+	static split(text) {
+		const lines = [];
+		let offset = 0;
+		let start = 0;
+		for (;;) {
+			const newline = text.indexOf("\n", start);
+			if (newline === -1) break;
+			const raw = text.slice(start, newline);
+			const hadCarriageReturn = raw.endsWith("\r");
+			const content = hadCarriageReturn ? raw.slice(0, -1) : raw;
+			const length = utf8Length(content);
+			const end = offset + length + (hadCarriageReturn ? 2 : 1);
+			lines.push(new LineSlice({
+				offset,
+				end,
+				length,
+				text: content,
+				terminated: true
+			}));
+			offset = end;
+			start = newline + 1;
+		}
+		if (start < text.length) {
+			const content = text.slice(start);
+			const length = utf8Length(content);
+			lines.push(new LineSlice({
+				offset,
+				end: offset + length,
+				length,
+				text: content,
+				terminated: false
+			}));
+		}
+		return lines;
+	}
+	/**
+	* The byte offset up to which this text has been fully consumed.
+	*
+	* This is the offset past the last **terminated** line. An unterminated
+	* final line is left unconsumed on purpose: it may be a writer caught
+	* mid-append, and re-reading from this offset once the file grows sees the
+	* completed line rather than gluing a stale fragment to fresh bytes.
+	*
+	* @param text - JSONL source text.
+	* @returns The resume cursor, in UTF-8 bytes.
+	*/
+	static consumedOffset(text) {
+		const last = Line.split(text).at(-1);
+		if (last === void 0) return 0;
+		return last.terminated ? last.end : last.offset;
+	}
+	/**
+	* Parse one candidate line's JSON.
+	*
+	* Any JSON value succeeds — objects, arrays and scalars alike. This layer
+	* does not know what an envelope is.
+	*
+	* @param line - A slice from {@link Line.split}.
+	* @returns The {@link ParsedLine}, or a {@link MalformedLine} carrying the
+	*   slice so the caller can locate the damage and decide whether an
+	*   unterminated line is a torn tail worth waiting for.
+	*/
+	static parseResult(line) {
+		let value;
+		try {
+			value = JSON.parse(line.text);
+		} catch {
+			return Result.fail(new MalformedLine({ line }));
+		}
+		return Result.succeed(new ParsedLine({
+			line,
+			value
+		}));
+	}
+	/**
+	* Parse every non-blank line, reporting failures rather than dropping them.
+	*
+	* There is deliberately no "valid lines only" variant. A hole in the middle
+	* of a journal is information — it means a line was written that no reader
+	* can interpret — and whether that is tolerable is the caller's decision,
+	* not this module's. Filter the `Result`s yourself and the choice stays
+	* visible at the call site.
+	*
+	* Whitespace-only lines are skipped rather than reported: they carry no
+	* information to lose, and reporting them would make a hand-edited journal
+	* look corrupt.
+	*
+	* @param text - JSONL source text.
+	* @returns One `Result` per non-blank line, in source order.
+	*/
+	static parseAll(text) {
+		const results = [];
+		for (const line of Line.split(text)) if (!isBlank(line)) results.push(Line.parseResult(line));
+		return results;
+	}
+	/**
+	* Walk back from the end to the last line that parses.
+	*
+	* This is the whole read path for a snapshot-style journal, where the
+	* current state *is* the last valid line: a session killed mid-append leaves
+	* a partial final line, and the walk-back steps over it — and over any
+	* number of malformed or blank trailing lines — to the last line that means
+	* something.
+	*
+	* Parsing stops at the first success, so the cost is proportional to the
+	* damage at the tail rather than to the age of the file.
+	*
+	* **A torn tail is only detectable when its fragment fails to parse.**
+	* Every strict prefix of a JSON *object* is invalid JSON, so a truncated
+	* `{"event":"unlinked"}` is always caught. A truncated *scalar* is not:
+	* `42` cut mid-write leaves `4`, which parses cleanly as a different value.
+	* The JSON layer cannot close that hole — the envelope layer can, because
+	* `4` is not an envelope, which is one more reason the envelope is the
+	* package's contract rather than an option. Check `LineSlice.terminated` on
+	* the result when it matters.
+	*
+	* @param text - JSONL source text.
+	* @returns The last parseable line, or `Option.none()` if none parses.
+	*/
+	static lastValid(text) {
+		const lines = Line.split(text);
+		for (let index = lines.length - 1; index >= 0; index--) {
+			const line = lines[index];
+			if (line === void 0 || isBlank(line)) continue;
+			const parsed = Line.parseResult(line);
+			if (Result.isSuccess(parsed)) return Option.some(parsed.success);
+		}
+		return Option.none();
+	}
+};
+
+//#endregion
+export { Line, ParsedLine };

package/LineSlice.js

@@ -0,0 +1,62 @@
+import { Schema } from "effect";
+
+//#region src/LineSlice.ts
+/**
+* One candidate line of a JSONL journal, located in the source by byte.
+*
+* @since 0.1.0
+*/
+/**
+* A single candidate line: its text, and where it lives in the source **in
+* bytes**.
+*
+* Every offset on this class is a UTF-8 byte offset, never a UTF-16 code-unit
+* index, because these values are cursors into a file: they are handed to
+* `FileSystem.stream`'s `offset` option and persisted across process restarts.
+* A `String.length`-derived offset is correct only for ASCII journals and is
+* the single most likely bug in this module.
+*
+* The terminator is **not** part of the content: `text` and `length` exclude
+* the trailing `\n`, and exclude the `\r` of a `\r\n` pair. `end` includes it,
+* which is why `end - offset` is not always `length`.
+*
+* @example
+* ```ts
+* import { Line } from "@effected/jsonl";
+*
+* const [first] = Line.split('{"a":1}\r\n{"b":2}\n');
+* first?.text;       // '{"a":1}'
+* first?.offset;     // 0
+* first?.length;     // 7  — content bytes, no terminator
+* first?.end;        // 9  — past the CR and the LF
+* first?.terminated; // true
+* ```
+*
+* @public
+*/
+var LineSlice = class extends Schema.Class("LineSlice")({
+	/** UTF-8 byte offset of this line's first content byte. */
+	offset: Schema.Number,
+	/**
+	* UTF-8 byte offset just past this line's terminator — the offset at which
+	* the next line begins, and the resume cursor for an incremental read.
+	*
+	* Equal to `offset + length` when the line is unterminated.
+	*/
+	end: Schema.Number,
+	/** UTF-8 byte length of `LineSlice.text`, excluding any terminator. */
+	length: Schema.Number,
+	/** The line's content, with its terminator and any paired `\r` removed. */
+	text: Schema.String,
+	/**
+	* Whether a `\n` terminated this line in the source.
+	*
+	* `false` can only occur on the final line, and means the line **may be a
+	* torn tail** — a writer caught mid-append. A reader walks back over it and
+	* leaves its bytes unconsumed so the next read sees the completed line.
+	*/
+	terminated: Schema.Boolean
+}) {};
+
+//#endregion
+export { LineSlice };