@effected/jsonl 0.1.0

package/index.js

@@ -0,0 +1,8 @@
+import { LineSlice } from "./LineSlice.js";
+import { InvalidData, JournalClosed, JournalNotFound, JournalResync, MalformedLine, TerminalViolation, UnknownEvent, UnserializableData } from "./JsonlError.js";
+import { Line, ParsedLine } from "./Line.js";
+import { Envelope, EnvelopeFrame } from "./Envelope.js";
+import { Journal } from "./Journal.js";
+import { JsonlEvent, JsonlEventTypeId } from "./JsonlEvent.js";
+
+export { Envelope, EnvelopeFrame, InvalidData, Journal, JournalClosed, JournalNotFound, JournalResync, JsonlEvent, JsonlEventTypeId, Line, LineSlice, MalformedLine, ParsedLine, TerminalViolation, UnknownEvent, UnserializableData };

package/internal/merge.js

@@ -0,0 +1,112 @@
+//#region src/internal/merge.ts
+/**
+* Pollution-safe shallow merge for `appendPatch`.
+*
+* Ported from `@effected/config-file`'s `internal/deepMerge.ts` recipe, minus
+* the recursion: `appendPatch` is a **shallow** merge by decision, so a nested
+* object in the patch replaces the one beneath it rather than merging into it.
+*
+* @internal
+*/
+/**
+* Keys that must never be copied from either side.
+*
+* `__proto__` reaches `Object.prototype`'s inherited accessor; `constructor`
+* and `prototype` are the neighbouring escape hatches. Filtering only the
+* *patch* would not be enough — the base is decoded journal data, which an
+* external writer controls just as directly.
+*
+* @internal
+*/
+const FORBIDDEN = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+/**
+* Create an own data property, never invoking a setter inherited from the
+* prototype chain.
+*
+* @internal
+*/
+const define = (target, key, value) => {
+	Object.defineProperty(target, key, {
+		value,
+		writable: true,
+		enumerable: true,
+		configurable: true
+	});
+};
+/**
+* Whether a value can take part in a merge at all.
+*
+* Record-**like**, deliberately: a decoded `Schema.Class` payload is a class
+* instance, and excluding those would make the kit's dominant payload idiom
+* silently unpatchable. Arrays, `Date`s, scalars and `null` are excluded —
+* `Object.prototype.toString` distinguishes them where a `typeof` check does
+* not.
+*
+* @internal
+*/
+const isRecordLike = (value) => typeof value === "object" && value !== null && Object.prototype.toString.call(value) === "[object Object]";
+/**
+* Whether `patch` may be merged into `base`.
+*
+* **Asymmetric, and deliberately unlike `@effected/config-file`'s `canMerge`.**
+* There, two *peer documents* are merged and requiring an identical prototype
+* keeps the merge honest. Here the patch is a caller-supplied **partial** —
+* `{ round: 2 }` written at the call site — so it is a plain literal even when
+* the base is a decoded `Schema.Class` instance. A symmetric same-prototype
+* test would therefore reject exactly the case that matters most and fall back
+* to replacement, which is the silent-loss trap this guard exists to close.
+*
+* So: both must be record-like, and the patch must not bring a *conflicting*
+* prototype — it is either a plain object (the normal case) or shares the
+* base's. Two instances of different classes do not merge.
+*
+* @internal
+*/
+const canMerge = (base, patch) => {
+	if (!isRecordLike(base) || !isRecordLike(patch)) return false;
+	const patchProto = Object.getPrototypeOf(patch);
+	return patchProto === Object.prototype || patchProto === null || patchProto === Object.getPrototypeOf(base);
+};
+/**
+* Shallow-merge `patch` over `base`, with `patch` winning.
+*
+* **Assignment is the hazard, not the keys.** `result[key] = value` and
+* `Object.assign` both use `[[Set]]`, which for a key named `__proto__` reaches
+* `Object.prototype`'s inherited accessor and reassigns the result's prototype
+* to attacker-controlled data — defeating the key filter that appears to be
+* guarding it. `Object.defineProperty` defines an own data property and never
+* consults the prototype chain, so it is the only safe copy primitive here.
+*
+* The result is built on `base`'s prototype so a decoded payload survives as
+* whatever it was, rather than being flattened into a bare object literal.
+*
+* **The merged value is TRANSIENT, and that is what makes this safe.** Building
+* on `base`'s prototype means a class-based payload passes `instanceof`
+* **without its constructor having run** — the object was assembled by
+* `Object.create` plus `defineProperty`, not by `new`. That is acceptable here
+* only because the value's sole use is to be encoded: the caller receives a
+* genuine instance produced by the subsequent decode, never this one. If a
+* future refactor ever returns the merged value to a caller directly, any
+* invariant a constructor establishes is silently bypassed.
+*
+* @internal
+*/
+const shallowMerge = (base, patch) => {
+	const result = Object.create(Object.getPrototypeOf(base));
+	for (const key of Object.keys(base)) {
+		if (FORBIDDEN.has(key)) continue;
+		define(result, key, base[key]);
+	}
+	for (const key of Object.keys(patch)) {
+		if (FORBIDDEN.has(key)) continue;
+		define(result, key, patch[key]);
+	}
+	return result;
+};
+
+//#endregion
+export { canMerge, isRecordLike, shallowMerge };

package/internal/tail.js

@@ -0,0 +1,143 @@
+import { Effect, Option } from "effect";
+
+//#region src/internal/tail.ts
+/** UTF-8 BOM, as bytes. `U+FEFF` encodes to these three. */
+const BOM = [
+	239,
+	187,
+	191
+];
+/** Byte value of `\n`. Cannot occur inside a UTF-8 multi-byte sequence. */
+const LF = 10;
+/**
+* The default tail window.
+*
+* Large enough that a snapshot journal's last line is almost always inside it
+* on the first read, small enough that reading it is cheap against a journal of
+* any age. When it misses, {@link readTail} widens rather than failing.
+*
+* @internal
+*/
+const DEFAULT_WINDOW = 8192;
+/** Does the buffer begin with a UTF-8 BOM? */
+const hasBom = (bytes) => bytes.length >= 3 && bytes[0] === BOM[0] && bytes[1] === BOM[1] && bytes[2] === BOM[2];
+/**
+* Probe the first three bytes of a file for a BOM.
+*
+* This is a property of the FILE, so it is read once from the start rather than
+* inferred from whatever window happens to be in hand. Inferring it from window
+* position was a real defect: a BOM'd journal larger than the window never has
+* a window at offset 0, so every offset it emitted was physical — silently off
+* by three against a file the package itself had described as post-BOM.
+*
+* @internal
+*/
+const probeBomBytes = (fs, path) => Effect.gen(function* () {
+	const head = yield* (yield* fs.open(path, { flag: "r" })).readAlloc(BOM.length);
+	const bytes = Option.getOrElse(head, () => /* @__PURE__ */ new Uint8Array(0));
+	return hasBom(bytes) ? BOM.length : 0;
+}).pipe(Effect.scoped);
+/**
+* Read the last `window` bytes of a journal, decoded from a line boundary.
+*
+* Three disciplines, each load-bearing:
+*
+* 1. **Start at a line boundary.** Unless the window reaches offset 0, the
+*    leading partial line is discarded — everything up to and including the
+*    first `\n`. This is also what makes the decode safe across a chunk
+*    boundary: `\n` is `0x0A` and **cannot** appear inside a UTF-8 multi-byte
+*    sequence, so a window that starts just past one starts on a character
+*    boundary too. No separate mid-character guard is needed.
+* 2. **Strip exactly one leading BOM, at the byte level**, and only when the
+*    window genuinely starts at file offset 0. Reads here are offset-based, so
+*    an implicit strip (as `readFileString` performs) would desynchronize every
+*    offset the package emits; doing it explicitly keeps the convention stated.
+*    A `U+FEFF` anywhere else is content and is left alone.
+* 3. **Never read the whole file** unless the file is smaller than the window.
+*
+* **`window` is not clamped**, deliberately. `Journal`'s historical read sizes
+* its window to the region it has to return, so a clamp here would silently
+* truncate that read rather than bound it. The clamp belongs with the paged
+* rewrite of that read — one that emits per window and can therefore honour a
+* maximum — and is carried on spencerbeggs/effected#233, not added underneath
+* it.
+*
+* @internal
+*/
+const readTail = (fs, path, window, bomBytes) => Effect.gen(function* () {
+	const info = yield* fs.stat(path);
+	const physicalSize = Number(info.size);
+	const logicalSize = physicalSize - bomBytes;
+	const from = Math.max(bomBytes, physicalSize - window);
+	const file = yield* fs.open(path, { flag: "r" });
+	yield* file.seek(from, "start");
+	const read = yield* file.readAlloc(physicalSize - from);
+	const bytes = Option.getOrElse(read, () => /* @__PURE__ */ new Uint8Array(0));
+	const windowAtFileStart = from === bomBytes;
+	let cursor = 0;
+	if (!windowAtFileStart) {
+		const newline = bytes.indexOf(LF);
+		cursor = newline === -1 ? bytes.length : newline + 1;
+	}
+	return {
+		text: new TextDecoder().decode(bytes.subarray(cursor)),
+		start: from + cursor - bomBytes,
+		atFileStart: windowAtFileStart,
+		size: logicalSize
+	};
+}).pipe(Effect.scoped);
+/**
+* Read widening windows until `decode` finds something, or the whole file has
+* been seen.
+*
+* The widening is what makes the bounded read *correct* rather than merely
+* cheap: a journal whose last line is longer than the initial window would
+* otherwise report "no valid envelope" for a perfectly healthy file.
+*
+* @internal
+*/
+const readTailUntil = (fs, path, bomBytes, decode, initialWindow = DEFAULT_WINDOW) => Effect.gen(function* () {
+	let window = initialWindow;
+	for (;;) {
+		const tail = yield* readTail(fs, path, window, bomBytes);
+		const found = decode(tail);
+		if (Option.isSome(found)) return found;
+		if (tail.atFileStart) return Option.none();
+		window *= 4;
+	}
+});
+/**
+* Read a byte range and decode it as text, safely across chunk boundaries.
+*
+* The byte→string seam lives here, in the service layer, because `Line.split`
+* is string-in by design and the pure core must never learn about buffers.
+*
+* `TextDecoder` is used in **streaming mode** (`{ stream: true }`) so a
+* multi-byte character split across two reads is reassembled rather than
+* mangled. A naive per-chunk `decode` corrupts any such character — a bug that
+* appears only with non-ASCII payloads at specific sizes, which is exactly the
+* kind that reaches production. The final `decode()` with no argument flushes
+* any trailing partial sequence.
+*
+* @internal
+*/
+const readRangeText = (fs, path, from, length) => Effect.gen(function* () {
+	if (length <= 0) return "";
+	const file = yield* fs.open(path, { flag: "r" });
+	yield* file.seek(from, "start");
+	const decoder = new TextDecoder();
+	let text = "";
+	let remaining = length;
+	while (remaining > 0) {
+		const chunk = yield* file.readAlloc(Math.min(remaining, CHUNK));
+		if (Option.isNone(chunk) || chunk.value.length === 0) break;
+		text += decoder.decode(chunk.value, { stream: true });
+		remaining -= chunk.value.length;
+	}
+	return text + decoder.decode();
+}).pipe(Effect.scoped);
+/** Read granularity for incremental tail reads. */
+const CHUNK = 65536;
+
+//#endregion
+export { DEFAULT_WINDOW, probeBomBytes, readRangeText, readTail, readTailUntil };

package/internal/utf8.js

@@ -0,0 +1,43 @@
+//#region src/internal/utf8.ts
+/**
+* UTF-8 byte accounting.
+*
+* A zero-dependency leaf so that both the line splitter and the error taxonomy
+* can measure bytes without either importing the other — the same cycle
+* firewall the other pure-tier packages use.
+*
+* @internal
+*/
+/**
+* The UTF-8 byte length of a JavaScript string.
+*
+* Journal offsets are **bytes**, because that is what `FileSystem.stream`'s
+* `offset` option and every persisted cursor mean. `String.length` counts
+* UTF-16 code units and is wrong for every non-ASCII journal: `"\u{1F600}"` has
+* length 2 and occupies 4 bytes.
+*
+* Matches `TextEncoder#encode(...).length` exactly, including the WHATWG rule
+* that an unpaired surrogate encodes as U+FFFD (3 bytes), but without
+* allocating a buffer per call.
+*
+* @internal
+*/
+const utf8Length = (text) => {
+	let bytes = 0;
+	for (let index = 0; index < text.length; index++) {
+		const code = text.charCodeAt(index);
+		if (code < 128) bytes += 1;
+		else if (code < 2048) bytes += 2;
+		else if (code >= 55296 && code <= 56319) {
+			const next = index + 1 < text.length ? text.charCodeAt(index + 1) : 0;
+			if (next >= 56320 && next <= 57343) {
+				bytes += 4;
+				index++;
+			} else bytes += 3;
+		} else bytes += 3;
+	}
+	return bytes;
+};
+
+//#endregion
+export { utf8Length };

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@effected/jsonl",
+	"version": "0.1.0",
+	"private": false,
+	"description": "Append-only, schema-validated JSONL journals as a definable Effect service.",
+	"keywords": [
+		"jsonl",
+		"journal",
+		"append-only",
+		"watch",
+		"effect",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/jsonl#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/jsonl"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"effect": "4.0.0-beta.101"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.12"
+    }
+  ]
+}