@effected/jsonl 0.8.0 → 0.10.0

package/Line.js

@@ -1,60 +1,32 @@
-import { LineSlice } from "./LineSlice.js";
 import { MalformedLine } from "./JsonlError.js";
 import { utf8Length } from "./internal/utf8.js";
-import { Option, Result, Schema } from "effect";
+import { Result } from "effect";
 
 //#region src/Line.ts
 /**
-* The pure, synchronous line layer of a JSONL journal.
+* Whether a line carries nothing but whitespace.
 *
-* 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
+* @internal
 */
-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.
+* Splitting and parsing 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.
+* Every operation is total and synchronous: nothing here throws. A `JSON.parse`
+* failure becomes a {@link MalformedLine}, because a journal is untrusted input
+* and untrusted input fails typed.
 *
 * @public
 */
-var Line = class Line {
+var Line = class {
+	constructor() {}
 	/**
 	* 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.
+	* 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 emits.
 	*
 	* @example
 	* ```ts
@@ -70,150 +42,70 @@ var Line = class Line {
 	/**
 	* 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`.
+	* Lines are separated by `\n`; a `\r` immediately preceding it is part of the
+	* terminator, so CRLF journals split identically to LF ones. A bare `\r` is
+	* ordinary content. A trailing terminator does **not** produce a phantom
+	* empty final line; interior blank lines *are* returned, because they are
+	* real bytes at real offsets. Only the final slice can be unterminated.
 	*
 	* @param text - JSONL source text.
-	* @returns One {@link LineSlice} per candidate line, in source order.
+	* @param base - The byte offset `text` starts at in its file. Every offset
+	*   returned is shifted by it, so text read from the middle of a journal
+	*   yields offsets into the journal rather than into the text.
+	* @returns One {@link (LineSlice:type)} per candidate line, in source order.
 	*/
-	static split(text) {
+	static split(text, base = 0) {
 		const lines = [];
-		let offset = 0;
+		let offset = base;
 		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 carriageReturn = newline > start && text.charCodeAt(newline - 1) === 13;
+			const content = text.slice(start, carriageReturn ? newline - 1 : newline);
 			const length = utf8Length(content);
-			const end = offset + length + (hadCarriageReturn ? 2 : 1);
-			lines.push(new LineSlice({
+			const end = offset + length + (carriageReturn ? 2 : 1);
+			lines.push({
 				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({
+			lines.push({
 				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.
+	* Any JSON value succeeds — objects, arrays and scalars alike.
 	*
 	* @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.
+	* @returns The parsed value, or a {@link MalformedLine} carrying the slice so
+	*   the caller can locate the damage. An unterminated malformed line is a
+	*   torn tail; a terminated one is a hole that will never heal.
 	*/
 	static parseResult(line) {
-		let value;
 		try {
-			value = JSON.parse(line.text);
+			return Result.succeed(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 };
+export { Line, isBlank };

package/LineSlice.js

@@ -2,24 +2,22 @@ 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.
+* Every offset here is a UTF-8 byte offset, never a UTF-16 code-unit index,
+* because these values are cursors into a file that persist 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`.
 *
+* A plain record rather than a class: `Line.split` produces one per line of
+* every read, and a class instance costs some forty times a plain object on
+* that path. The schema exists so errors can carry the line structurally.
+*
 * @example
 * ```ts
 * import { Line } from "@effected/jsonl";
@@ -34,7 +32,7 @@ import { Schema } from "effect";
 *
 * @public
 */
-var LineSlice = class extends Schema.Class("LineSlice")({
+const LineSlice = Schema.Struct({
 	/** UTF-8 byte offset of this line's first content byte. */
 	offset: Schema.Number,
 	/**
@@ -44,7 +42,7 @@ var LineSlice = class extends Schema.Class("LineSlice")({
 	* Equal to `offset + length` when the line is unterminated.
 	*/
 	end: Schema.Number,
-	/** UTF-8 byte length of `LineSlice.text`, excluding any terminator. */
+	/** UTF-8 byte length of `text`, excluding any terminator. */
 	length: Schema.Number,
 	/** The line's content, with its terminator and any paired `\r` removed. */
 	text: Schema.String,
@@ -52,11 +50,10 @@ var LineSlice = class extends Schema.Class("LineSlice")({
 	* 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.
+	* torn tail** — a writer caught mid-append.
 	*/
 	terminated: Schema.Boolean
-}) {};
+});
 
 //#endregion
 export { LineSlice };

package/README.md

@@ -7,10 +7,10 @@
 
 Append-only, schema-validated JSONL journals as a definable Effect service. The subject is not the format — one JSON value per line is a two-sentence specification and needs no library — but the file as a live object: a journal that only ever grows, whose current state is its last valid line, whose tail may be torn mid-append, and which several processes read while one writes. Every line is an envelope (`at`, `event`, an optional `scope`, and a `data` payload validated by the schema you registered for that event), so a journal stays greppable, `jq`-able and diffable in a pull request while the reads that matter stay typed.
 
-> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
-> development against a single pinned Effect v4 prerelease. Packages graduate to
-> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
-> exactly the ones the kit is built and tested against, install
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
 >
 > **Stability: unstable.** This package's API surface is not yet considered

package/Slice.js

@@ -1,22 +1,16 @@
 //#region src/Slice.ts
 /**
-* Whether a frame satisfies a slice.
-*
-* Takes the **frame**, never a decoded envelope — that is what keeps matching
-* ahead of the payload schema on the read path.
+* Whether frame fields satisfy a slice.
 *
 * @internal
 */
 const matchesFrame = (frame, slice) => {
 	if (slice === void 0) return true;
 	if (slice.events !== void 0 && !slice.events.includes(frame.event)) return false;
-	if (slice.scopes !== void 0) {
-		if (frame.scope === void 0 || !slice.scopes.includes(frame.scope)) return false;
-	}
+	if (slice.scopes !== void 0 && (frame.scope === void 0 || !slice.scopes.includes(frame.scope))) return false;
 	const millis = frame.at.epochMilliseconds;
 	if (slice.from !== void 0 && millis < slice.from.epochMilliseconds) return false;
-	if (slice.to !== void 0 && millis >= slice.to.epochMilliseconds) return false;
-	return true;
+	return slice.to === void 0 || millis < slice.to.epochMilliseconds;
 };
 
 //#endregion