effect 4.0.5 → 4.0.6

package/dist/eventlog/EventRow.js

@@ -0,0 +1,435 @@
+/**
+ * Mutable rows that converge across event-log replicas.
+ *
+ * Each row type has one event with `set`, `patch` and `remove` payloads, keyed
+ * by one or more of its fields. Pass the result of `make` to `EventGroup.add`.
+ * Its `set`, `patch` and `remove` constructors return `{ event, payload }`,
+ * which spreads into `EventLog.write` and serves as an item of
+ * `EventLog.writeMany` or an argument of an `EventLog.makeClient` client.
+ *
+ * `handler` resolves conflicts per top-level field and calls at most one
+ * storage callback. Replicas converge to the result of applying entries in
+ * id order. `compaction` drops entries that newer ones shadow.
+ *
+ * **Details**
+ *
+ * Replay decodes entries and stored conflicts with the current row schema,
+ * which must accept every encoding previously written:
+ *
+ * - New fields must accept absence, for example with
+ *   `Schema.withDecodingDefaultKey`. Nullable fields alone reject old `set`
+ *   entries. Patches never apply defaults.
+ * - Removing a field is safe. Old entries decode without it.
+ * - To change a field's type, keep its encoded type and change its decoded
+ *   type with a transformation, such as `Schema.NumberFromString` for a field
+ *   that used to be a string.
+ * - Making a field required, renaming it, narrowing its type, changing its
+ *   encoded type or changing the key breaks old entries. That includes
+ *   widening a field to a union of its old and new types, because union
+ *   encodings are tagged. A rename keeps old entries readable only if the
+ *   field has an explicit `SchemaBinary.fieldId`.
+ * - Key-field schemas must decode written values to ones with the same
+ *   primary key, since replicas derive the key from decoded values.
+ *
+ * Conflicts are scoped to one row; parent removal does not resolve concurrent
+ * child writes. For cascading deletion, retain a removed-parent marker and
+ * delete its children in the parent `remove` callback. The `remove` callback
+ * writes the marker even when the parent was never stored, since compaction
+ * or a newer `remove` can skip its `set`, and the marker must not depend on
+ * the old row. A parent `patch` treats a marker as a missing row. Child `set`
+ * and `patch` callbacks must skip marked parents but allow parents not yet
+ * received. Make the parent id part of the child key, as in
+ * `fields: ["parentId", "id"]`, so a child cannot move between parents. This
+ * converges only if parent deletion is final (no key reuse). Queries must
+ * exclude marked parents. Retain markers unless the app defines a safe cutoff
+ * for removing them.
+ *
+ * **Example** (Syncing grocery rows)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { EventGroup, EventLog, EventRow } from "effect/eventlog"
+ *
+ * const Grocery = EventRow.make("grocery", {
+ *   key: "id",
+ *   schema: Schema.Struct({
+ *     id: Schema.String,
+ *     name: Schema.String,
+ *     completed: Schema.Boolean
+ *   })
+ * })
+ *
+ * const Groceries = EventGroup.empty.add(Grocery)
+ *
+ * const store = new Map<string, typeof Grocery.schema.Type>()
+ *
+ * export const GroceriesLive = EventLog.group(Groceries, (handlers) =>
+ *   handlers.handle(
+ *     "grocery",
+ *     EventRow.handler(Grocery, {
+ *       set: (row) => Effect.sync(() => store.set(row.id, row)),
+ *       patch: (id, fields) =>
+ *         Effect.sync(() => {
+ *           const row = store.get(id)
+ *           if (row !== undefined) store.set(id, { ...row, ...fields })
+ *         }),
+ *       remove: (id) => Effect.sync(() => store.delete(id))
+ *     })
+ *   ))
+ *
+ * export const complete = Effect.fnUntraced(function*(id: string) {
+ *   const log = yield* EventLog.EventLog
+ *   yield* log.write({
+ *     schema: EventLog.schema(Groceries),
+ *     ...Grocery.patch(id, { completed: true })
+ *   })
+ * })
+ * ```
+ *
+ * **Example** (Evolving a row schema)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Schema } from "effect"
+ * import { EventGroup, EventRow } from "effect/eventlog"
+ *
+ * const ItemV1 = EventRow.make("item", {
+ *   key: "id",
+ *   schema: Schema.Struct({ id: Schema.String, quantity: Schema.String })
+ * })
+ *
+ * // Adds a nullable field and reads the old string quantity as a number.
+ * const ItemV2 = EventRow.make("item", {
+ *   key: "id",
+ *   schema: Schema.Struct({
+ *     id: Schema.String,
+ *     quantity: Schema.NumberFromString,
+ *     note: Schema.NullOr(Schema.String).pipe(
+ *       Schema.withDecodingDefaultKey(Effect.succeed(null))
+ *     )
+ *   })
+ * })
+ *
+ * const v1 = EventGroup.empty.add(ItemV1).events.item.payloadSchemaBinary
+ * const v2 = EventGroup.empty.add(ItemV2).events.item.payloadSchemaBinary
+ *
+ * const written = Schema.encodeUnknownSync(v1)(ItemV1.set({ id: "a", quantity: "3" }).payload)
+ * const decoded = Schema.decodeUnknownSync(v2)(written)
+ * decoded // => { _tag: "set", row: { id: "a", quantity: 3, note: null } }
+ * ```
+ *
+ * @stability unstable
+ * @since 4.0.6
+ */
+import * as Context from "../Context.js";
+import * as Effect from "../Effect.js";
+import * as SchemaBinary from "../encoding/SchemaBinary.js";
+import * as Layer from "../Layer.js";
+import * as Result from "../Result.js";
+import * as Schema from "../Schema.js";
+import * as SchemaGetter from "../SchemaGetter.js";
+import * as SchemaIssue from "../SchemaIssue.js";
+import * as SchemaParser from "../SchemaParser.js";
+import * as Struct from "../Struct.js";
+import { Entry } from "./EventJournal.js";
+import * as EventLog from "./EventLog.js";
+/**
+ * Defines a row type as a single event.
+ *
+ * **Details**
+ *
+ * `key` names a required field, or declares required fields with an
+ * optional `derive` function. `patch`, `remove` and the handler callbacks take
+ * the key as typed values: the field's value for a single field, and a struct
+ * of the fields for a declaration. Key fields cannot be patched. To move a
+ * row, remove it and set it again.
+ *
+ * A single-field key must be a {@link DefaultKeyField}. Declare other fields
+ * with a `derive` function.
+ *
+ * `keyOf` computes the primary key that conflicts are grouped by: the value
+ * of a string single-field key, the result of `derive`, or else the JSON
+ * tuple of the key fields' JSON encodings. `-0` and `0` are the same key.
+ *
+ * Last-writer-wins applies to top-level fields. Nested values are atomic, so
+ * concurrent updates within one nested value do not merge.
+ *
+ * `error` is the error schema of the event. Handler callbacks can fail with it.
+ *
+ * **Gotchas**
+ *
+ * Do not compact row events with `EventLog.groupCompaction` or
+ * `EventLog.groupBatchCompaction`. Compaction runs before stored conflicts
+ * are read, so merging row ops loses or misapplies writes. Use
+ * {@link compaction}, which only drops entries that newer ones shadow.
+ *
+ * For multi-row operations, use `EventLog.writeMany` with one op per row.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.6
+ */
+export const make = (tag, options) => {
+  const fields = options.schema.fields;
+  const key = typeof options.key === "string" ? scalarKey(options.key, fields[options.key]) : declaredKey(options.key, fields);
+  const patchFields = {};
+  for (const name of Object.keys(fields)) {
+    if (!key.fields.includes(name)) patchFields[name] = patchField(fields[name]);
+  }
+  const payload = Schema.Union([Schema.TaggedStruct("set", {
+    row: options.schema
+  }), Schema.TaggedStruct("patch", {
+    key: key.schema,
+    fields: Schema.Struct(patchFields)
+  }), Schema.TaggedStruct("remove", {
+    key: key.schema
+  })]);
+  return {
+    tag,
+    keyFields: key.fields,
+    schema: options.schema,
+    keyOf: key.primaryKey,
+    [keyFromId]: key.fromRow,
+    primaryKey: payload => key.primaryKey(payload._tag === "set" ? payload.row : key.toValues(payload.key)),
+    payload,
+    success: Schema.Void,
+    error: options.error ?? Schema.Never,
+    set: row => ({
+      event: tag,
+      payload: {
+        _tag: "set",
+        row
+      }
+    }),
+    patch: (key, fields) => ({
+      event: tag,
+      payload: {
+        _tag: "patch",
+        key,
+        fields
+      }
+    }),
+    remove: key => ({
+      event: tag,
+      payload: {
+        _tag: "remove",
+        key
+      }
+    })
+  };
+};
+/**
+ * Builds the handler for a row event, to pass to `handlers.handle`.
+ *
+ * **Details**
+ *
+ * Resolves newer conflicts in id order and calls at most one callback with
+ * typed values and key, never conflicts.
+ *
+ * Newer writes take precedence per top-level field. Empty patches and entries
+ * with nothing left to write skip the callback but are still journaled and synced.
+ * A late `set` retains newer patches, including when the row is missing.
+ *
+ * Decodes stored entry bytes so local writes and replay pass the same values
+ * to callbacks, stripping keys outside the schema at any depth. Requires the
+ * payload schema's decoding services, plus any services the callbacks require.
+ * Callbacks may fail with the event's error type; success is always `void`.
+ *
+ * **Gotchas**
+ *
+ * Convergence requires this callback contract:
+ *
+ * - `set` replaces the whole row, creating it if it is missing.
+ * - `patch` updates an existing row and does nothing if the row is missing.
+ *   Upserting can resurrect removed rows on only some replicas.
+ * - `remove` is idempotent.
+ *
+ * @stability unstable
+ * @category handlers
+ * @since 4.0.6
+ */
+export const handler = (row, callbacks) => {
+  const decode = Schema.decodeUnknownEffect(SchemaBinary.toCodec(row.payload));
+  const keyFrom = row[keyFromId];
+  return options => Effect.flatMap(Effect.orDie(decode(options.entry.payload)), payload => {
+    const op = resolve(payload, options.conflicts);
+    if (op === undefined) return Effect.void;
+    switch (op._tag) {
+      case "set":
+        return callbacks.set(op.row, keyFrom(op.row));
+      case "patch":
+        return Object.keys(op.fields).length === 0 ? Effect.void : callbacks.patch(op.key, op.fields);
+      case "remove":
+        return callbacks.remove(op.key);
+    }
+  }).pipe(Effect.asVoid);
+};
+/**
+ * Registers a compactor for one row event of a group.
+ *
+ * **Details**
+ *
+ * Drops entries superseded within the same remote batch and row by a newer
+ * `set` or `remove`. A `patch` is also dropped when newer patches together
+ * overwrite all its fields. Kept entries retain their ids and stored conflicts.
+ *
+ * A `set` or `remove` followed only by patches is kept: without it, the
+ * patches would apply to a different row, or to none. Entries that fail to
+ * decode are kept.
+ *
+ * Leaves other events' compactors unchanged. Register one compactor per row
+ * event.
+ *
+ * @stability unstable
+ * @category compaction
+ * @since 4.0.6
+ */
+export const compaction = (group, row) => Layer.effectDiscard(Effect.gen(function* () {
+  const registry = yield* EventLog.Registry;
+  const services = yield* Effect.context();
+  const decode = Schema.decodeUnknownEffect(group.events[row.tag].payloadSchemaBinary);
+  yield* registry.registerCompaction({
+    events: [row.tag],
+    effect: Effect.fnUntraced(function* ({
+      entries,
+      write
+    }) {
+      const ops = new Map();
+      for (const entry of entries) {
+        const payload = yield* Effect.result(decode(entry.payload).pipe(Effect.updateContext(input => Context.merge(services, input))));
+        if (Result.isSuccess(payload)) ops.set(entry, payload.success);
+      }
+      const shadowed = shadowedEntries(entries, ops);
+      for (const entry of entries) {
+        if (!shadowed.has(entry)) yield* write(entry);
+      }
+    })
+  });
+}));
+const shadowedEntries = (entries, ops) => {
+  const shadowed = new Set();
+  const byKey = new Map();
+  for (const entry of entries) {
+    const row = byKey.get(entry.primaryKey);
+    if (row === undefined) byKey.set(entry.primaryKey, [entry]);else row.push(entry);
+  }
+  for (const row of byKey.values()) {
+    row.sort(Entry.Order);
+    let replaced = false;
+    let patched = false;
+    const written = new Set();
+    for (let i = row.length - 1; i >= 0; i--) {
+      const op = ops.get(row[i]);
+      if (op === undefined) continue;
+      if (op._tag !== "patch") {
+        if (replaced) shadowed.add(row[i]);
+        replaced = true;
+        continue;
+      }
+      const names = Object.keys(op.fields);
+      if (replaced || patched && names.every(name => written.has(name))) shadowed.add(row[i]);
+      patched = true;
+      for (const name of names) written.add(name);
+    }
+  }
+  return shadowed;
+};
+const keyFromId = "~effect/eventlog/EventRow/keyFrom";
+const scalarKey = (name, field) => ({
+  fields: [name],
+  schema: field,
+  fromRow: row => row[name],
+  toValues: key => ({
+    [name]: key
+  }),
+  primaryKey: jsonKey([[name, field]], true)
+});
+const declaredKey = (declaration, fields) => {
+  const names = declaration.fields;
+  const derive = declaration.derive;
+  return {
+    fields: names,
+    schema: Schema.Struct(Struct.pick(fields, names)),
+    fromRow: row => Struct.pick(row, names),
+    toValues: key => key,
+    primaryKey: derive !== undefined ? row => derive(Struct.pick(row, names)) : jsonKey(names.map(name => [name, fields[name]]), false)
+  };
+};
+// A string single-field key is its own primary key. Otherwise the key is the
+// JSON tuple of the fields' JSON encodings, distinct for distinct values of
+// `DefaultKeyField`s. A field holds one kind of value, so a raw string never
+// meets a tuple from the same field.
+const jsonKey = (fields, single) => {
+  let encoders;
+  return row => {
+    if (single && typeof row[fields[0][0]] === "string") return row[fields[0][0]];
+    encoders ??= fields.map(([name, field]) => [name, Schema.encodeUnknownSync(Schema.toCodecJson(field))]);
+    return JSON.stringify(encoders.map(([name, encode]) => encode(row[name])));
+  };
+};
+// Run the field codec only for present keys, bypassing missing-key defaults.
+const patchField = field => {
+  const decode = SchemaParser.decodeUnknownEffect(field);
+  // The struct wrapper detects encodings that drop a written key.
+  const encode = SchemaParser.encodeUnknownEffect(Schema.Struct({
+    value: field
+  }));
+  return Schema.optionalKey(Schema.toEncoded(field)).pipe(Schema.decodeTo(Schema.optionalKey(Schema.toType(field)), {
+    decode: SchemaGetter.transformEffect(decode),
+    encode: SchemaGetter.transformEffect((value, options) => Effect.flatMap(encode({
+      value
+    }, options), encoded => Object.hasOwn(encoded, "value") ? Effect.succeed(encoded.value) : Effect.fail(new SchemaIssue.Forbidden({
+      message: "A patch cannot write a value whose encoding omits the key"
+    }, value))))
+  }));
+};
+const compose = (x, y) => {
+  if (y._tag !== "patch") return y;
+  switch (x._tag) {
+    case "set":
+      return {
+        _tag: "set",
+        row: {
+          ...x.row,
+          ...y.fields
+        }
+      };
+    case "patch":
+      return {
+        _tag: "patch",
+        key: y.key,
+        fields: {
+          ...x.fields,
+          ...y.fields
+        }
+      };
+    case "remove":
+      return x;
+  }
+};
+const resolve = (entry, conflicts) => {
+  if (conflicts.length === 0) return entry;
+  let newer = conflicts[0].payload;
+  for (let i = 1; i < conflicts.length; i++) {
+    newer = compose(newer, conflicts[i].payload);
+  }
+  if (newer._tag !== "patch") return undefined;
+  switch (entry._tag) {
+    case "set":
+      return {
+        _tag: "set",
+        row: {
+          ...entry.row,
+          ...newer.fields
+        }
+      };
+    case "patch":
+      return {
+        _tag: "patch",
+        key: entry.key,
+        fields: Struct.omit(entry.fields, Object.keys(newer.fields))
+      };
+    case "remove":
+      return entry;
+  }
+};
+//# sourceMappingURL=EventRow.js.map

package/dist/eventlog/EventRow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventRow.js","names":[],"sources":["../../src/eventlog/EventRow.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/eventlog/SqlEventJournal.d.ts

@@ -8,8 +8,20 @@ import * as EventJournal from "./EventJournal.ts";
  *
  * **Details**
  *
- * The constructor creates the entry and remote metadata tables when needed,
- * persists local and remote entries, and uses the configured `SqlClient`.
+ * Maintains `entryTable`, `${entryTable}_sequence`, `${entryTable}_sources`,
+ * `${remotesTable}_checkpoints` and `remoteCursorsTable` (default
+ * `${remotesTable}_cursors`) using the configured `SqlClient`.
+ *
+ * **Gotchas**
+ *
+ * Creating or migrating the schema requires a writable connection. Migrated
+ * databases can be reopened read-only.
+ *
+ * Journals from earlier releases keep one `remotesTable` row per entry per
+ * remote. Opening one replaces those rows with entry sources and drops the
+ * table; an entry known to several remotes keeps one of them as its source.
+ *
+ * Upload acknowledgements do not advance past unseen entries.
  *
  * @stability unstable
  * @category constructors
@@ -18,27 +30,14 @@ import * as EventJournal from "./EventJournal.ts";
 export declare const make: (options?: {
     readonly entryTable?: string;
     readonly remotesTable?: string;
+    readonly remoteCursorsTable?: string;
 }) => Effect.Effect<EventJournal.EventJournal["Service"], SqlError.SqlError, SqlClient.SqlClient>;
 /**
- * Provides `EventJournal` using the SQL-backed implementation created by
- * `make`.
- *
- * **When to use**
- *
- * Use when composing a Layer graph that should provide a persistent SQL-backed
- * `EventJournal` from an existing `SqlClient` service.
- *
- * **Details**
- *
- * The layer delegates to `make(options)`, so the same optional `entryTable` and
- * `remotesTable` settings are used and construction requires `SqlClient` and
- * may fail with `SqlError`.
+ * Provides a SQL-backed `EventJournal` from an existing `SqlClient` service.
  *
  * **Gotchas**
  *
- * Layer construction performs the same minimal `CREATE TABLE IF NOT EXISTS`
- * setup as `make`; manage indexes and schema migrations outside this layer when
- * your SQL schema needs more than the built-in tables.
+ * Creating or migrating the schema requires a writable connection.
  *
  * @see {@link make} for constructing the SQL-backed service directly
  * @see {@link EventJournal.layerMemory} for an in-memory `EventJournal` layer
@@ -51,5 +50,6 @@ export declare const make: (options?: {
 export declare const layer: (options?: {
     readonly entryTable?: string;
     readonly remotesTable?: string;
+    readonly remoteCursorsTable?: string;
 }) => Layer.Layer<EventJournal.EventJournal, SqlError.SqlError, SqlClient.SqlClient>;
 //# sourceMappingURL=SqlEventJournal.d.ts.map

package/dist/eventlog/SqlEventJournal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SqlEventJournal.d.ts","sourceRoot":"","sources":["../../src/eventlog/SqlEventJournal.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,MAAM,MAAM,cAAc,CAAA;AAEtC,OAAO,KAAK,KAAK,MAAM,aAAa,CAAA;AAIpC,OAAO,KAAK,SAAS,MAAM,qBAAqB,CAAA;AAChD,OAAO,KAAK,QAAQ,MAAM,oBAAoB,CAAA;AAE9C,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAIjD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,IAAI,aAAc;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B,KAAG,MAAM,CAAC,MAAM,CACf,YAAY,CAAC,YAAY,CAAC,SAAS,CAAC,EACpC,QAAQ,CAAC,QAAQ,EACjB,SAAS,CAAC,SAAS,CAyPjB,CAAA;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,KAAK,aAAc;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B,KAAG,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,EAAE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,SAAS,CACzB,CAAA"}
+{"version":3,"file":"SqlEventJournal.d.ts","sourceRoot":"","sources":["../../src/eventlog/SqlEventJournal.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,MAAM,MAAM,cAAc,CAAA;AAEtC,OAAO,KAAK,KAAK,MAAM,aAAa,CAAA;AAIpC,OAAO,KAAK,SAAS,MAAM,qBAAqB,CAAA;AAChD,OAAO,KAAK,QAAQ,MAAM,oBAAoB,CAAA;AAE9C,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAKjD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,IAAI,aAAc;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CACrC,KAAG,MAAM,CAAC,MAAM,CACf,YAAY,CAAC,YAAY,CAAC,SAAS,CAAC,EACpC,QAAQ,CAAC,QAAQ,EACjB,SAAS,CAAC,SAAS,CA+gBjB,CAAA;AAEJ;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,KAAK,aAAc;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CACrC,KAAG,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,EAAE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,SAAS,CACzB,CAAA"}