@effected/jsonl 0.9.0 → 0.11.0

package/Line.js

@@ -1,50 +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
 /**
-* A line that parsed as JSON, paired with the slice it came from.
+* Whether a line carries nothing but whitespace.
 *
-* `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
@@ -60,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

@@ -5,16 +5,19 @@ import { Schema } from "effect";
 * 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";
@@ -29,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,
 	/**
@@ -39,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,
@@ -47,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/NodeJournalWatcher.js

@@ -0,0 +1,104 @@
+import { JournalWatcher } from "./JournalWatcher.js";
+import { Cause, Effect, Layer, PlatformError, Queue, Stream } from "effect";
+import * as NFS from "node:fs";
+
+//#region src/NodeJournalWatcher.ts
+/** The `SystemErrorTag` an errno code maps to, after core's Node filesystem mapping. */
+const reasonOf = (code) => {
+	switch (code) {
+		case "ENOENT": return "NotFound";
+		case "EACCES":
+		case "EPERM": return "PermissionDenied";
+		case "ENOTDIR":
+		case "ELOOP": return "BadResource";
+		default: return "Unknown";
+	}
+};
+const watchError = (path, cause) => PlatformError.systemError({
+	_tag: reasonOf(cause?.code),
+	module: "FileSystem",
+	method: "watch",
+	pathOrDescriptor: path,
+	syscall: "watch",
+	cause
+});
+/** The identity a watched file is armed on, or `undefined` once the path names nothing. */
+const identityAt = (path) => {
+	try {
+		const info = NFS.statSync(path);
+		return `${info.dev}:${info.ino}`;
+	} catch {
+		return;
+	}
+};
+/**
+* Register `fs.watch` synchronously, inside the acquire — so when the effect
+* succeeds the platform watch is live, which is the contract
+* {@link Jsonl.JournalWatcherShape.watch} states and core's
+* `FileSystem.watch` cannot.
+*
+* A file watch follows the inode it was armed on, and Node emits neither
+* `close` nor `error` when that inode is unlinked or renamed over: left
+* alone, the stream would outlive the file and the journal would follow a
+* dead inode forever. So every event on a file re-checks the path's identity,
+* and the stream ends — after delivering the event — once the path is gone or
+* names a different file. A directory watch never ends that way: a sibling
+* appearing or vanishing is routine there.
+*/
+const watch = (path) => Effect.gen(function* () {
+	const queue = yield* Queue.unbounded();
+	yield* Effect.acquireRelease(Effect.try({
+		try: () => {
+			const armed = NFS.statSync(path);
+			const identity = armed.isDirectory() ? void 0 : `${armed.dev}:${armed.ino}`;
+			const watcher = NFS.watch(path, (_event, name) => {
+				Queue.offerUnsafe(queue, name ?? void 0);
+				if (identity !== void 0 && identityAt(path) !== identity) Queue.endUnsafe(queue);
+			});
+			watcher.on("error", (cause) => {
+				Queue.failCauseUnsafe(queue, Cause.fail(watchError(path, cause)));
+			});
+			watcher.on("close", () => {
+				Queue.endUnsafe(queue);
+			});
+			return watcher;
+		},
+		catch: (cause) => watchError(path, cause)
+	}), (watcher) => Effect.sync(() => watcher.close()));
+	return Stream.fromQueue(queue);
+});
+/**
+* The Node implementation of {@link Jsonl.JournalWatcher}, over `node:fs`'s
+* `watch`.
+*
+* Registration happens synchronously while the watch effect runs, so a
+* journal's catch-up read after arming can never miss an append that the
+* watch also fails to report.
+*
+* @example
+* ```ts
+* import { Journal, JsonlEvent } from "@effected/jsonl";
+* import { NodeJournalWatcher } from "@effected/jsonl/node";
+* import { NodeFileSystem } from "@effect/platform-node";
+* import { Effect, Schema } from "effect";
+*
+* const events = [JsonlEvent.make("mail", { data: Schema.Struct({ round: Schema.Number }) })] as const;
+*
+* class Mail extends Journal.Service<Mail>()("app/Mail", { events, config: { path: ".app/mail.jsonl" } }) {}
+*
+* const program = Effect.gen(function* () {
+*   const mail = yield* Mail;
+*   yield* mail.append("mail", { round: 1 });
+* }).pipe(Effect.provide(Mail.layer), Effect.provide([NodeFileSystem.layer, NodeJournalWatcher.layer]));
+* ```
+*
+* @public
+*/
+var NodeJournalWatcher = class {
+	constructor() {}
+	/** Provides {@link Jsonl.JournalWatcher} over `node:fs`. */
+	static layer = Layer.succeed(JournalWatcher, { watch });
+};
+
+//#endregion
+export { NodeJournalWatcher };

package/README.md

@@ -41,7 +41,7 @@ Requires Node.js >=24.11.0. `effect` v4 is the only peer dependency, and the onl
 
 All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` — including tools that resolve in CJS mode — fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than loading a CJS build that does not exist. Import from an ES module.
 
-`FileSystem` comes from `effect` core, not from a platform package, so a consumer provides it once at the edge (`NodeFileSystem.layer` from `@effect/platform-node` on Node). `Path` is deliberately not required — every path is an opaque string handed straight to `FileSystem`, and this package never joins, resolves or splits one.
+`FileSystem` comes from `effect` core, not from a platform package, so a consumer provides it once at the edge (`NodeFileSystem.layer` from `@effect/platform-node` on Node). The journal also needs a `JournalWatcher` — a file watch that reports when it is armed, so an append cannot land unseen while the watch is being set up; on Node that is `NodeJournalWatcher.layer` from the `@effected/jsonl/node` subpath, the only part of the package that touches `node:*`. `Path` is deliberately not required — every path is an opaque string handed straight to `FileSystem`, and this package never joins, resolves or splits one.
 
 ## Quick start
 
@@ -49,6 +49,7 @@ Declare the events a journal may contain, mint a service class for that registry
 
 ```ts
 import { Journal, JsonlEvent } from "@effected/jsonl";
+import { NodeJournalWatcher } from "@effected/jsonl/node";
 import { NodeFileSystem } from "@effect/platform-node";
 import { Effect, Option, Schema, Stream, SubscriptionRef } from "effect";
 
@@ -90,7 +91,7 @@ const program = Effect.gen(function* () {
   );
 });
 
-Effect.runPromise(program.pipe(Effect.provide(MailJournalLive), Effect.provide(NodeFileSystem.layer)));
+Effect.runPromise(program.pipe(Effect.provide(MailJournalLive), Effect.provide([NodeFileSystem.layer, NodeJournalWatcher.layer])));
 ```
 
 `events: ["mail-received"]` narrows the stream's element type to that variant, so a projection over a slice is exhaustively checkable rather than a cast. An event marked `terminal` makes the journal quiescent once it reaches the tail: further appends fail typed unless the event is marked `reopen`, and every `changes` stream ends rather than hanging — including one whose slice excludes the terminal event, and including a subscriber that attaches after the fact.

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