@effected/jsonl 0.7.1-dogfood-20260927171341 → 0.9.0

package/Envelope.js

@@ -87,6 +87,23 @@ const completeResult = (events, line, frame) => {
 * defined **in terms of** the sync ones via `Effect.fromResult`, so the two can
 * never drift into two implementations of the same rule.
 *
+* @example
+* ```ts
+* import { Envelope, JsonlEvent, Line } from "@effected/jsonl";
+* import { Result, Schema } from "effect";
+*
+* const events = [JsonlEvent.make("started", { data: Schema.Struct({ id: Schema.String }) })] as const;
+*
+* declare const sourceText: string;
+*
+* for (const line of Line.split(sourceText)) {
+*   const decoded = Envelope.decodeResult(events, line);
+*   if (Result.isSuccess(decoded) && decoded.success.event === "started") {
+*     decoded.success.data.id; // typed from the registered payload schema
+*   }
+* }
+* ```
+*
 * @public
 */
 const Envelope = {
@@ -98,6 +115,9 @@ const Envelope = {
 	* filtered out never pays for its payload at all.
 	*
 	* @param line - A slice from `Line.split`.
+	* @returns The frame with its source `line` attached, or `MalformedLine`
+	*   when the line is not JSON, or `InvalidData` when it is JSON that is not
+	*   an envelope frame.
 	*/
 	frameResult: (line) => {
 		const parsed = Line.parseResult(line);
@@ -157,6 +177,10 @@ const Envelope = {
 	*
 	* 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.
+	*
+	* @param events - The registry to validate against.
+	* @param text - JSONL source text.
+	* @returns One `Result` per non-blank line, in file order.
 	*/
 	decodeAllResult: (events, text) => {
 		const results = [];
@@ -207,6 +231,10 @@ const Envelope = {
 	* @param events - The registry to validate against.
 	* @param envelope - The event tag, its payload, the service-assigned
 	*   timestamp, and an optional scope.
+	* @returns The encoded line, or `UnknownEvent` for a tag the registry does
+	*   not define, `InvalidData` when the payload does not satisfy its schema,
+	*   or `UnserializableData` when the encoded payload cannot be turned into
+	*   JSON (a bigint or a reference cycle).
 	*/
 	encodeResult: (events, envelope) => {
 		const empty = new LineSlice({
@@ -251,14 +279,18 @@ const Envelope = {
 		return Result.succeed(`${text}\n`);
 	},
 	/**
-	* {@link (Envelope:variable).decodeResult} in the `Effect` channel.
+	* `Envelope.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.
+	* exists for programs that already are one. Fails with `MalformedLine`,
+	* `InvalidData` or `UnknownEvent`; requires nothing.
 	*/
 	decode: (events, line) => Effect.fromResult(Envelope.decodeResult(events, line)),
 	/**
-	* {@link (Envelope:variable).encodeResult} in the `Effect` channel.
+	* `Envelope.encodeResult` in the `Effect` channel.
+	*
+	* Fails with `UnknownEvent`, `InvalidData` or `UnserializableData`; requires
+	* nothing.
 	*/
 	encode: (events, envelope) => Effect.fromResult(Envelope.encodeResult(events, envelope))
 };

package/Journal.js

@@ -120,7 +120,7 @@ const makeEngine = (events, config, fs) => Effect.gen(function* () {
 	const latest = yield* SubscriptionRef.make(Option.none());
 	/** Refusal state. Read before the permit so a late append fails fast. */
 	let closed = false;
-	/** Logical bytes decoded so far — the resume cursor the watcher (P5) advances. */
+	/** Logical bytes decoded so far — the resume cursor the watcher advances. */
 	let consumed = 0;
 	const exists = () => fs.exists(config.path);
 	const requireFile = Effect.gen(function* () {
@@ -446,6 +446,9 @@ const makeEngine = (events, config, fs) => Effect.gen(function* () {
 * one layer graph with each one's operations typed by *its* registry. This
 * mirrors `ConfigFile.Service<Self, A>()(id)`.
 *
+* Pass the registry as `options.events`; the returned class exposes it as
+* `events` and builds the scoped layer with `.layer(config)`.
+*
 * @example
 * ```ts
 * import { Journal, JsonlEvent } from "@effected/jsonl";
@@ -453,9 +456,9 @@ const makeEngine = (events, config, fs) => Effect.gen(function* () {
 *
 * const events = [JsonlEvent.make("started", { data: Schema.Void })] as const;
 *
-* class MailJournal extends Journal.Service<MailJournal>()("dogfood/MailJournal", { events }) {}
+* class MailJournal extends Journal.Service<MailJournal>()("app/MailJournal", { events }) {}
 *
-* export const layer = MailJournal.layer({ path: ".claude/dogfood/silk.jsonl" });
+* export const layer = MailJournal.layer({ path: ".app/mail.jsonl" });
 * ```
 *
 * @public

package/JsonlError.js

@@ -3,15 +3,6 @@ import { Option, Schema } 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,

package/Line.js

@@ -5,16 +5,6 @@ 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.

package/LineSlice.js

@@ -2,11 +2,6 @@ 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**.
 *

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/index.d.ts

@@ -490,6 +490,23 @@ type EnvelopeWithTag<R extends JsonlEvent.Registry, T extends string> = Extract<
  * defined **in terms of** the sync ones via `Effect.fromResult`, so the two can
  * never drift into two implementations of the same rule.
  *
+ * @example
+ * ```ts
+ * import { Envelope, JsonlEvent, Line } from "@effected/jsonl";
+ * import { Result, Schema } from "effect";
+ *
+ * const events = [JsonlEvent.make("started", { data: Schema.Struct({ id: Schema.String }) })] as const;
+ *
+ * declare const sourceText: string;
+ *
+ * for (const line of Line.split(sourceText)) {
+ *   const decoded = Envelope.decodeResult(events, line);
+ *   if (Result.isSuccess(decoded) && decoded.success.event === "started") {
+ *     decoded.success.data.id; // typed from the registered payload schema
+ *   }
+ * }
+ * ```
+ *
  * @public
  */
 export declare const Envelope: {
@@ -501,6 +518,9 @@ export declare const Envelope: {
    * filtered out never pays for its payload at all.
    *
    * @param line - A slice from `Line.split`.
+   * @returns The frame with its source `line` attached, or `MalformedLine`
+   *   when the line is not JSON, or `InvalidData` when it is JSON that is not
+   *   an envelope frame.
    */
   readonly frameResult: (line: LineSlice) => Result.Result<typeof EnvelopeFrame.Type & {
     readonly line: LineSlice;
@@ -540,6 +560,10 @@ export declare const Envelope: {
    *
    * 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.
+   *
+   * @param events - The registry to validate against.
+   * @param text - JSONL source text.
+   * @returns One `Result` per non-blank line, in file order.
    */
   readonly decodeAllResult: <const R extends JsonlEvent.Registry>(events: R, text: string) => ReadonlyArray<Result.Result<EnvelopeUnion<R>, MalformedLine | InvalidData | UnknownEvent>>;
   /**
@@ -577,6 +601,10 @@ export declare const Envelope: {
    * @param events - The registry to validate against.
    * @param envelope - The event tag, its payload, the service-assigned
    *   timestamp, and an optional scope.
+   * @returns The encoded line, or `UnknownEvent` for a tag the registry does
+   *   not define, `InvalidData` when the payload does not satisfy its schema,
+   *   or `UnserializableData` when the encoded payload cannot be turned into
+   *   JSON (a bigint or a reference cycle).
    */
   readonly encodeResult: <const R extends JsonlEvent.Registry, const T extends JsonlEvent.Tag<R>>(events: R, envelope: {
     readonly event: T;
@@ -585,14 +613,18 @@ export declare const Envelope: {
     readonly scope?: string | undefined;
   }) => Result.Result<string, UnknownEvent | InvalidData | UnserializableData>;
   /**
-   * {@link (Envelope:variable).decodeResult} in the `Effect` channel.
+   * `Envelope.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.
+   * exists for programs that already are one. Fails with `MalformedLine`,
+   * `InvalidData` or `UnknownEvent`; requires nothing.
    */
   readonly decode: <const R extends JsonlEvent.Registry>(events: R, line: LineSlice) => Effect.Effect<EnvelopeUnion<R>, MalformedLine | InvalidData | UnknownEvent>;
   /**
-   * {@link (Envelope:variable).encodeResult} in the `Effect` channel.
+   * `Envelope.encodeResult` in the `Effect` channel.
+   *
+   * Fails with `UnknownEvent`, `InvalidData` or `UnserializableData`; requires
+   * nothing.
    */
   readonly encode: <const R extends JsonlEvent.Registry, const T extends JsonlEvent.Tag<R>>(events: R, envelope: {
     readonly event: T;
@@ -781,8 +813,8 @@ interface JournalShape<R extends JsonlEvent.Registry> {
    * Elements are `Take` chunks and end-of-stream is a published `Exit`, which
    * is what lets quiescence and graceful shutdown arrive at a subscriber as a
    * normal stream end. Never shut this down to signal completion —
-   * `PubSub.shutdown` *interrupts* subscribers, which is the tear the design
-   * forbids.
+   * `PubSub.shutdown` *interrupts* subscribers, which tears an in-flight
+   * stream instead of ending it.
    *
    * @internal
    */
@@ -871,6 +903,9 @@ interface JournalClass<Self, Id extends string, R extends JsonlEvent.Registry> e
  * one layer graph with each one's operations typed by *its* registry. This
  * mirrors `ConfigFile.Service<Self, A>()(id)`.
  *
+ * Pass the registry as `options.events`; the returned class exposes it as
+ * `events` and builds the scoped layer with `.layer(config)`.
+ *
  * @example
  * ```ts
  * import { Journal, JsonlEvent } from "@effected/jsonl";
@@ -878,9 +913,9 @@ interface JournalClass<Self, Id extends string, R extends JsonlEvent.Registry> e
  *
  * const events = [JsonlEvent.make("started", { data: Schema.Void })] as const;
  *
- * class MailJournal extends Journal.Service<MailJournal>()("dogfood/MailJournal", { events }) {}
+ * class MailJournal extends Journal.Service<MailJournal>()("app/MailJournal", { events }) {}
  *
- * export const layer = MailJournal.layer({ path: ".claude/dogfood/silk.jsonl" });
+ * export const layer = MailJournal.layer({ path: ".app/mail.jsonl" });
  * ```
  *
  * @public

package/internal/merge.js

@@ -1,14 +1,5 @@
 //#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`

package/internal/utf8.js

@@ -1,14 +1,5 @@
 //#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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/jsonl",
-	"version": "0.7.1-dogfood-20260927171341",
+	"version": "0.9.0",
 	"private": false,
 	"description": "Append-only, schema-validated JSONL journals as a definable Effect service.",
 	"keywords": [
@@ -37,7 +37,7 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"effect": "4.0.0-rc.117"
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"