effect 4.0.5 → 4.0.7

package/dist/eventlog/EventLog.js

@@ -10,6 +10,8 @@
  * @stability unstable
  * @since 4.0.0
  */
+import * as Arr from "../Array.js";
+import * as Cause from "../Cause.js";
 import * as Context from "../Context.js";
 import * as Effect from "../Effect.js";
 import * as FiberMap from "../FiberMap.js";
@@ -23,12 +25,15 @@ import * as Queue from "../Queue.js";
 import { Reactivity } from "../reactivity/Reactivity.js";
 import * as ReactivityLayer from "../reactivity/Reactivity.js";
 import * as Redacted from "../Redacted.js";
+import { CurrentLogAnnotations } from "../References.js";
+import * as Result from "../Result.js";
 import * as Schedule from "../Schedule.js";
 import * as Schema from "../Schema.js";
 import * as SchemaGetter from "../SchemaGetter.js";
 import { Entry, EventJournal, makeEntryIdUnsafe } from "./EventJournal.js";
 import * as EventLogEncryption from "./EventLogEncryption.js";
 import { StoreId } from "./EventLogMessage.js";
+import { setAnchor } from "./internal/conflicts.js";
 /**
  * Service for writing typed event-log events through registered handlers.
  *
@@ -171,6 +176,65 @@ export const HandlersTypeId = "~effect/eventlog/EventLog/Handlers";
 export class CurrentStoreId extends /*#__PURE__*/Context.Reference("effect/eventlog/EventLog/CurrentStoreId", {
   defaultValue: /*#__PURE__*/constant(/*#__PURE__*/StoreId.make("default"))
 }) {}
+/**
+ * Context reference for a transaction that wraps the event handlers of each
+ * batch replayed from a remote and of each local `write` or `writeMany`.
+ *
+ * **When to use**
+ *
+ * Use when handlers project into a store with transactions, such as
+ * `sql.withTransaction` or an IndexedDB transaction over the projection
+ * tables, so a batch of N events commits once instead of N times.
+ *
+ * **Details**
+ *
+ * The journal performs no I/O while the transaction is open: it reads replay
+ * conflicts before the transaction starts and commits the batch after it
+ * completes. Defaults to running the handlers without a transaction.
+ *
+ * If the transaction fails, the journal commits nothing from the batch. For a
+ * replayed batch, the remote is subscribed again after a backoff of up to 10
+ * seconds and the batch is delivered again, so later batches from that remote
+ * wait until it succeeds; local writes and other remotes are not blocked. A
+ * local write fails with the error and is not retried.
+ *
+ * **Gotchas**
+ *
+ * - A replayed entry that fails to decode, or whose handler fails or dies,
+ *   fails the whole batch, which is retried as above. A failure that repeats
+ *   on every attempt, such as a payload written by a newer schema, stops sync
+ *   from that remote until the app is updated to handle it.
+ * - In a local write, an error returned by a handler fails the transaction
+ *   and the write, and the journal commits none of its events.
+ * - Failures that abort the underlying transaction fail the whole batch, even
+ *   when the handler recovers from them. In IndexedDB, any failed request that
+ *   is not prevented aborts the whole transaction, and in PostgreSQL so does a
+ *   failed statement outside a savepoint.
+ * - Failing the batch does not undo side effects of handlers that already ran.
+ *   Only changes made inside a transaction that rolls back are undone.
+ * - Replay handlers must tolerate running more than once for the same entry.
+ * - Unless the transaction and the journal share a database connection, the
+ *   transaction commits before the journal does, and the two commits are not
+ *   atomic. A crash between them replays a remote batch on restart, but a
+ *   local write is lost from the journal while its projection changes remain.
+ * - An IndexedDB transaction commits once it has no pending requests and
+ *   control returns to the event loop. A custom wrapper must stop the fiber
+ *   from yielding to the scheduler while it is open, by providing
+ *   `References.PreventSchedulerYield` as `withTransaction` from
+ *   `@effect/platform-browser` does. Otherwise it can commit partway through a
+ *   batch, and the remaining handlers fail.
+ * - The transaction stays open for the whole batch, so other read-write
+ *   transactions on the same tables wait for it.
+ * - The transaction must not change the error or success of the wrapped
+ *   effect. Convert its own failures into defects.
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.6
+ */
+export class HandlerTransaction extends /*#__PURE__*/Context.Reference("effect/eventlog/EventLog/HandlerTransaction", {
+  defaultValue: /*#__PURE__*/constant(identity)
+}) {}
 const RedactedUint8Array = /*#__PURE__*/Schema.Uint8ArrayFromBase64.pipe(/*#__PURE__*/Schema.decodeTo(/*#__PURE__*/Schema.Redacted(Schema.Uint8Array), {
   decode: /*#__PURE__*/SchemaGetter.transform(value => Redacted.make(value)),
   encode: /*#__PURE__*/SchemaGetter.transform(value => Redacted.value(value))
@@ -282,19 +346,7 @@ export const group = (group, f) => Layer.effectDiscard(Effect.gen(function* () {
     });
   }
 }));
-/**
- * Registers a compaction handler for an event group.
- *
- * **Details**
- *
- * During remote replay, matching entries are decoded, grouped by primary key, and
- * passed to the compaction effect, which may write replacement entries.
- *
- * @stability unstable
- * @category compaction
- * @since 4.0.0
- */
-export const groupCompaction = (group, effect) => Layer.effectDiscard(Effect.gen(function* () {
+const registerBatchCompaction = (group, effect) => Layer.effectDiscard(Effect.gen(function* () {
   const registry = yield* Registry;
   const services = yield* Effect.context();
   yield* registry.registerCompaction({
@@ -304,12 +356,12 @@ export const groupCompaction = (group, effect) => Layer.effectDiscard(Effect.gen
       write
     }) {
       const isEventTag = tag => Object.hasOwn(group.events, tag);
-      const decodePayload = (tag, payload) => Schema.decodeUnknownEffect(group.events[tag].payloadSchemaBinary)(payload).pipe(Effect.updateContext(input => Context.merge(services, input)), Effect.orDie);
-      const writePayload = Effect.fnUntraced(function* (timestamp, tag, payload) {
+      const decodePayload = (tag, payload) => Schema.decodeUnknownEffect(group.events[tag].payloadSchemaBinary)(payload).pipe(Effect.updateContext(input => Context.merge(services, input)));
+      const writeFrom = Effect.fnUntraced(function* (source, tag, payload) {
         const event = Object.hasOwn(group.events, tag) ? group.events[tag] : undefined;
         const entry = new Entry({
           id: makeEntryIdUnsafe({
-            msecs: timestamp
+            msecs: source.createdAtMillis
           }),
           event: tag,
           payload: yield* Schema.encodeUnknownEffect(event.payloadSchemaBinary)(payload).pipe(Effect.orDie),
@@ -317,45 +369,150 @@ export const groupCompaction = (group, effect) => Layer.effectDiscard(Effect.gen
         }, {
           disableChecks: true
         });
-        yield* write(entry);
+        yield* write(entry, source);
       });
-      const byPrimaryKey = new Map();
+      const forward = entry => write(entry);
+      const batch = [];
       for (const entry of entries) {
         if (!isEventTag(entry.event)) {
           continue;
         }
-        const payload = yield* decodePayload(entry.event, entry.payload);
-        const record = byPrimaryKey.get(entry.primaryKey);
-        const taggedPayload = {
-          _tag: entry.event,
-          payload
-        };
-        if (record) {
-          record.entries.push(entry);
-          record.taggedPayloads.push(taggedPayload);
-        } else {
-          byPrimaryKey.set(entry.primaryKey, {
-            entries: [entry],
-            taggedPayloads: [taggedPayload]
-          });
-        }
-      }
-      for (const [primaryKey, {
-        entries,
-        taggedPayloads
-      }] of byPrimaryKey) {
-        yield* Effect.orDie(effect({
-          primaryKey,
-          entries,
-          events: taggedPayloads,
-          write(tag, payload) {
-            return Effect.orDie(writePayload(entries[0].createdAtMillis, tag, payload));
+        const payload = yield* Effect.result(decodePayload(entry.event, entry.payload));
+        batch.push({
+          entry,
+          event: Result.isFailure(payload) ? undefined : {
+            _tag: entry.event,
+            payload: payload.success
           }
-        }).pipe(Effect.updateContext(input => Context.merge(services, input))));
+        });
       }
+      yield* Effect.orDie(effect({
+        entries: batch,
+        writeFrom,
+        forward
+      }).pipe(Effect.updateContext(input => Context.merge(services, input))));
     })
   });
 }));
+/**
+ * Registers a batch compaction handler for an event group.
+ *
+ * **When to use**
+ *
+ * Use when an event under one primary key affects entries under other keys.
+ *
+ * **Details**
+ *
+ * The compaction effect receives every entry for the group in batch order, with
+ * its decoded event or `event: undefined` if the payload cannot be decoded.
+ *
+ * Only entries that the effect outputs are kept:
+ *
+ * - `forward(entry)` keeps an input entry unchanged, with the same id, payload,
+ *   and primary key.
+ * - `write(tag, payload)` encodes a replacement entry anchored to the first
+ *   entry in the batch, with a fresh id in that entry's millisecond.
+ *
+ * Entries that are neither forwarded nor replaced are dropped, including entries
+ * that could not be decoded. During remote replay, kept entries are replayed in
+ * the id order of their anchors, then in write order, and a replacement's
+ * conflicts are the stored entries newer than its anchor.
+ *
+ * **Gotchas**
+ *
+ * Compaction runs before conflicts are read, so it never sees stored entries.
+ * Collapsing several entries into one is only safe when no stored entry for
+ * the same event and primary key has an id between theirs. Otherwise that
+ * stored entry should have applied between the collapsed ones, and replicas
+ * that received the entries in separate batches end up different.
+ *
+ * @see {@link groupCompaction} for compaction grouped by primary key
+ *
+ * @stability unstable
+ * @category compaction
+ * @since 4.0.0
+ */
+export const groupBatchCompaction = (group, effect) => registerBatchCompaction(group, ({
+  entries,
+  writeFrom,
+  forward
+}) => effect({
+  entries,
+  write: (tag, payload) => writeFrom(entries[0].entry, tag, payload),
+  forward
+}));
+/**
+ * Registers a compaction handler for an event group.
+ *
+ * **Details**
+ *
+ * During remote replay, decoded entries are grouped by primary key and passed to
+ * the compaction effect, which outputs the entries to keep:
+ *
+ * - `forward(entry)` keeps an input entry unchanged, with the same id, payload,
+ *   and primary key.
+ * - `write(tag, payload)` encodes a replacement entry anchored to the first
+ *   decoded entry for the primary key, with a fresh id in that entry's
+ *   millisecond.
+ *
+ * Entries that are neither forwarded nor replaced are dropped. Entries that
+ * cannot be decoded are not passed to the effect and are kept unchanged.
+ * During remote replay, kept entries are replayed in the id order of their
+ * anchors, then in write order, and a replacement's conflicts are the stored
+ * entries newer than its anchor.
+ *
+ * **Gotchas**
+ *
+ * Compaction runs before conflicts are read, so it never sees stored entries.
+ * Collapsing several entries into one is only safe when no stored entry for
+ * the same event and primary key has an id between theirs. Otherwise that
+ * stored entry should have applied between the collapsed ones, and replicas
+ * that received the entries in separate batches end up different.
+ *
+ * @see {@link groupBatchCompaction} for compaction across primary keys
+ *
+ * @stability unstable
+ * @category compaction
+ * @since 4.0.0
+ */
+export const groupCompaction = (group, effect) => registerBatchCompaction(group, Effect.fnUntraced(function* ({
+  entries,
+  writeFrom,
+  forward
+}) {
+  const byPrimaryKey = new Map();
+  for (const {
+    entry,
+    event
+  } of entries) {
+    if (event === undefined) {
+      yield* forward(entry);
+      continue;
+    }
+    const record = byPrimaryKey.get(entry.primaryKey);
+    if (record) {
+      record.entries.push(entry);
+      record.events.push(event);
+    } else {
+      byPrimaryKey.set(entry.primaryKey, {
+        entries: [entry],
+        events: [event]
+      });
+    }
+  }
+  for (const [primaryKey, {
+    entries,
+    events
+  }] of byPrimaryKey) {
+    yield* effect({
+      primaryKey,
+      entries,
+      events,
+      write: (tag, payload) => writeFrom(entries[0], tag, payload),
+      forward
+    });
+  }
+}));
 /**
  * Registers reactivity keys to invalidate when events from a group are written or
  * replayed.
@@ -386,49 +543,106 @@ export const groupReactivity = (group, keys) => Effect.gen(function* () {
  * **Details**
  *
  * The returned handler decodes the entry and conflicts with the registered event
- * schema, runs the matching handler with the supplied identity and store id, logs
- * failures, and invalidates configured reactivity keys.
+ * schema, runs the matching handler with the supplied identity and store id, and
+ * invalidates configured reactivity keys. Decode and handler failures are logged
+ * and fail the effect. Invalidations are deferred until the end of an enclosing
+ * `Reactivity.withBatch`.
  *
  * @stability unstable
  * @category handlers
  * @since 4.0.0
  */
-export const makeReplayFromRemote = options => Effect.fnUntraced(function* ({
-  conflicts,
-  entry
-}) {
-  const handler = options.handlers.get(entry.event);
-  if (!handler) {
-    return yield* Effect.logDebug(`Event handler not found for: "${entry.event}"`);
-  }
-  const decodePayload = Schema.decodeUnknownEffect(handler.event.payloadSchemaBinary);
-  const decodedConflicts = new Array(conflicts.length);
-  for (let i = 0; i < conflicts.length; i++) {
-    decodedConflicts[i] = {
-      entry: conflicts[i],
-      payload: yield* decodePayload(conflicts[i].payload).pipe(Effect.updateContext(input => Context.merge(handler.context, input)))
+export const makeReplayFromRemote = options => {
+  const replayBatch = makeReplayBatchFromRemote(options);
+  return input => replayBatch([input]);
+};
+/**
+ * Replays a batch, merging each handler's context with the batch context once
+ * and decoding each conflict entry shared by several entries once. The batch
+ * state is created per execution, so transaction retries start fresh.
+ */
+const makeReplayBatchFromRemote = options => {
+  const replayEntry = makeReplayEntryFromRemote(options);
+  return batch => Effect.contextWith(context => {
+    const state = {
+      context,
+      handlerContexts: new Map(),
+      decodedConflicts: new Map()
     };
-  }
-  yield* decodePayload(entry.payload).pipe(Effect.flatMap(payload => handler.handler({
-    storeId: options.storeId,
-    payload,
-    entry,
-    conflicts: decodedConflicts
-  })), Effect.provideService(Identity, options.identity), Effect.updateContext(input => Context.merge(handler.context, input)), Effect.asVoid);
-  const keys = Object.hasOwn(options.reactivityKeys, entry.event) ? options.reactivityKeys[entry.event] : undefined;
-  if (keys) {
-    for (const key of keys) {
-      options.reactivity.invalidateUnsafe({
-        [key]: [entry.primaryKey]
-      });
+    return Effect.forEach(batch, input => replayEntry(input, state), {
+      discard: true
+    });
+  });
+};
+// An entry's context is the batch context plus its log annotations, so only
+// the annotations need to be copied into the merged handler context.
+const withEntryAnnotations = (context, entryContext) => Context.add(context, CurrentLogAnnotations, Context.get(entryContext, CurrentLogAnnotations));
+const makeReplayEntryFromRemote = options => {
+  // Decoders depend only on the event schema, so they are shared across batches.
+  const decoders = new WeakMap();
+  const decoderFor = handler => {
+    let decoder = decoders.get(handler);
+    if (decoder === undefined) {
+      decoder = Schema.decodeUnknownEffect(handler.event.payloadSchemaBinary);
+      decoders.set(handler, decoder);
     }
-  }
-}, Effect.catchCause(Effect.logError), (effect, {
-  entry
-}) => Effect.annotateLogs(effect, {
-  ...options.logAnnotations,
-  entryId: entry.idString
-}));
+    return decoder;
+  };
+  const contextFor = (batch, handler) => {
+    let context = batch.handlerContexts.get(handler);
+    if (context === undefined) {
+      context = Context.merge(handler.context, batch.context);
+      batch.handlerContexts.set(handler, context);
+    }
+    return context;
+  };
+  return Effect.fnUntraced(function* ({
+    conflicts,
+    entry
+  }, batch) {
+    const handler = options.handlers.get(entry.event);
+    if (!handler) {
+      return yield* Effect.logDebug(`Event handler not found for: "${entry.event}"`);
+    }
+    const decodePayload = decoderFor(handler);
+    const context = contextFor(batch, handler);
+    const conflictPayloads = new Array(conflicts.length);
+    for (let i = 0; i < conflicts.length; i++) {
+      const conflict = conflicts[i];
+      let decoded = batch.decodedConflicts.get(conflict);
+      if (!decoded) {
+        decoded = {
+          entry: conflict,
+          payload: yield* decodePayload(conflict.payload).pipe(Effect.updateContext(input => withEntryAnnotations(context, input)))
+        };
+        batch.decodedConflicts.set(conflict, decoded);
+      }
+      conflictPayloads[i] = decoded;
+    }
+    // Conflicts decode with the caller's Identity; the payload and handler use the log's.
+    yield* decodePayload(entry.payload).pipe(Effect.flatMap(payload => handler.handler({
+      storeId: options.storeId,
+      payload,
+      entry,
+      conflicts: conflictPayloads
+    })), Effect.updateContext(input => Context.add(withEntryAnnotations(context, input), Identity, options.identity)), Effect.asVoid);
+    yield* invalidateEntry(options.reactivity, options.reactivityKeys, entry);
+  }, Effect.tapCauseIf(cause => !Cause.hasInterruptsOnly(cause), Effect.logError), (effect, {
+    entry
+  }) => Effect.annotateLogs(effect, {
+    ...options.logAnnotations,
+    entryId: entry.idString
+  }));
+};
+const invalidateEntry = (reactivity, reactivityKeys, entry) => {
+  const keys = Object.hasOwn(reactivityKeys, entry.event) ? reactivityKeys[entry.event] : undefined;
+  if (!keys) return Effect.void;
+  return Effect.forEach(keys, key => reactivity.invalidate({
+    [key]: [entry.primaryKey]
+  }), {
+    discard: true
+  });
+};
 const remoteRetrySchedule = /*#__PURE__*/Schedule.min([/*#__PURE__*/Schedule.exponential(200, 1.5), /*#__PURE__*/Schedule.spaced({
   seconds: 10
 })]);
@@ -438,7 +652,8 @@ const make = /*#__PURE__*/Effect.gen(function* () {
   const journal = yield* EventJournal;
   const registry = yield* Registry;
   const reactivity = yield* Reactivity;
-  const replayFromRemote = makeReplayFromRemote({
+  const handlerTransaction = yield* HandlerTransaction;
+  const replayFromRemote = makeReplayBatchFromRemote({
     handlers: registry.handlers,
     storeId,
     identity,
@@ -449,66 +664,71 @@ const make = /*#__PURE__*/Effect.gen(function* () {
       effect: "writeFromRemote"
     }
   });
-  const invalidateReactivityEntries = entries => Effect.sync(() => {
-    for (const entry of entries) {
-      const keys = Object.hasOwn(registry.reactivityKeys, entry.event) ? registry.reactivityKeys[entry.event] : undefined;
-      if (!keys) {
-        continue;
-      }
-      for (const key of keys) {
-        reactivity.invalidateUnsafe({
-          [key]: [entry.primaryKey]
-        });
-      }
-    }
+  const invalidateReactivityEntries = entries => Effect.forEach(entries, entry => invalidateEntry(reactivity, registry.reactivityKeys, entry), {
+    discard: true
   });
   const runRemote = Effect.fnUntraced(function* (remote) {
-    const startSequence = yield* journal.nextRemoteSequence(remote.id);
     yield* Effect.gen(function* () {
+      const startSequence = yield* journal.nextRemoteSequence(remote.id);
       const changes = yield* remote.changes({
         identity,
         startSequence,
-        storeId
+        storeId,
+        knownEntries: journal.entriesById
       });
       while (true) {
         const entries = yield* Queue.takeAll(changes);
         yield* journal.writeFromRemote({
           remoteId: remote.id,
-          entries: entries.flat(),
+          entries,
           compact: registry.compactors.size > 0 ? Effect.fnUntraced(function* (remoteEntries) {
-            const finalEntries = [];
+            // The journal sorts the batch by anchor, so output order is irrelevant.
+            const output = [];
+            const inputs = new Map();
+            const outputCounts = new Map();
             const compactable = new Map();
-            for (let i = 0; i < remoteEntries.length; i++) {
-              const remoteEntry = remoteEntries[i];
-              const entry = remoteEntry.entry;
+            for (const {
+              entry
+            } of remoteEntries) {
+              inputs.set(entry.idString, entry);
               const compactor = registry.compactors.get(entry.event);
               if (!compactor) {
-                finalEntries.push(entry);
+                output.push(entry);
                 continue;
               }
-              let arr = compactable.get(compactor.effect);
-              if (!arr) {
-                arr = [];
-                compactable.set(compactor.effect, arr);
+              let group = compactable.get(compactor.effect);
+              if (!group) {
+                group = [];
+                compactable.set(compactor.effect, group);
               }
-              arr.push(entry);
+              group.push(entry);
             }
             for (const [compact, entries] of compactable) {
               yield* compact({
                 entries,
-                write(entry) {
+                write(entry, source) {
                   return Effect.sync(() => {
-                    finalEntries.push(entry);
+                    // Each output is ordered and conflict-checked by its source,
+                    // then by write order, not by its own fresh id. An output
+                    // without a known source stands for the group's first entry.
+                    const anchor = inputs.get((source ?? entry).idString) ?? entries[0];
+                    const index = outputCounts.get(anchor) ?? 0;
+                    outputCounts.set(anchor, index + 1);
+                    setAnchor(entry, anchor, index);
+                    output.push(entry);
                   });
                 }
               });
             }
-            return finalEntries.sort(Entry.Order);
+            return output;
           }) : undefined,
-          effect: replayFromRemote
+          // A failed batch is not committed, so the remote redelivers it on retry.
+          effect: batch => handlerTransaction(replayFromRemote(batch)).pipe(Effect.orDie)
         }).pipe(Effect.tap(({
           duplicateEntries
-        }) => invalidateReactivityEntries(duplicateEntries)), journal.withLock(storeId));
+        }) => invalidateReactivityEntries(duplicateEntries)), journal.withLock(storeId),
+        // Outside the lock, so queries re-run after the journal transaction commits.
+        reactivity.withBatch);
       }
     }).pipe(Effect.scoped, Effect.catchCause(Effect.logError), Effect.repeat(remoteRetrySchedule), Effect.annotateLogs({
       service: "EventLog",
@@ -518,7 +738,11 @@ const make = /*#__PURE__*/Effect.gen(function* () {
       identity,
       entries,
       storeId
-    }));
+    }).pipe(Effect.flatMap(acks => acks === undefined || acks.length === 0 ? Effect.void : journal.writeRemoteAcks({
+      remoteId: remote.id,
+      acks,
+      firstSequence: remote.firstSequence
+    }).pipe(journal.withLock(storeId)))));
     const writeUntilSuccess = write.pipe(Effect.tapCause(Effect.logDebug), Effect.retry(remoteRetrySchedule));
     yield* Effect.addFinalizer(() => Effect.ignore(write));
     const changesSub = yield* journal.changes;
@@ -527,40 +751,45 @@ const make = /*#__PURE__*/Effect.gen(function* () {
     yield* writeUntilSuccess;
     return yield* Queue.take(changes).pipe(Effect.andThen(writeUntilSuccess), Effect.catchCause(Effect.logError), Effect.forever);
   }, Effect.scoped, Effect.provideService(Identity, identity), Effect.orDie);
-  const writeHandler = Effect.fnUntraced(function* (handler, options) {
-    const payload = yield* Schema.encodeUnknownEffect(handler.event.payloadSchemaBinary)(options.payload).pipe(Effect.orDie);
-    return yield* journal.withLock(storeId)(journal.write({
-      event: options.event,
-      primaryKey: handler.event.primaryKey(options.payload),
+  const writeEvents = events => Effect.forEach(events, ({
+    event,
+    payload
+  }) => {
+    const handler = registry.handlers.get(event);
+    if (handler === undefined) {
+      return Effect.die(`Event handler not found for: "${event}"`);
+    }
+    return Schema.encodeUnknownEffect(handler.event.payloadSchemaBinary)(payload).pipe(Effect.orDie, Effect.map(encoded => ({
+      handler,
       payload,
-      effect: entry => handler.handler({
+      entry: {
+        event,
+        primaryKey: handler.event.primaryKey(payload),
+        payload: encoded
+      }
+    })));
+  }).pipe(Effect.flatMap(writes => journal.withLock(storeId)(journal.writeMany({
+    entries: Arr.map(writes, write => write.entry),
+    effect: written => handlerTransaction(Effect.forEach(written, (entry, i) => {
+      const {
+        handler,
+        payload
+      } = writes[i];
+      return handler.handler({
         storeId,
-        payload: options.payload,
+        payload,
         entry,
         conflicts: []
-      }).pipe(Effect.updateContext(input => Context.merge(handler.context, input)), Effect.provideService(Identity, identity), Effect.tap(() => {
-        const keys = Object.hasOwn(registry.reactivityKeys, entry.event) ? registry.reactivityKeys[entry.event] : undefined;
-        if (keys) {
-          for (const key of keys) {
-            reactivity.invalidateUnsafe({
-              [key]: [entry.primaryKey]
-            });
-          }
-        }
-        return Effect.void;
-      }))
-    }));
-  });
-  const eventLogWrite = options => {
-    const handler = registry.handlers.get(options.event);
-    if (handler === undefined) {
-      return Effect.die(`Event handler not found for: "${options.event}"`);
-    }
-    return writeHandler(handler, options);
-  };
+      }).pipe(Effect.updateContext(input => Context.merge(handler.context, input)), Effect.provideService(Identity, identity), Effect.tap(() => invalidateEntry(reactivity, registry.reactivityKeys, entry)));
+    }))
+  }))),
+  // Outside the lock, so queries re-run after the handler transaction and
+  // the journal commit.
+  reactivity.withBatch);
   yield* registry.handleRemote(runRemote);
   return EventLog.of({
-    write: eventLogWrite,
+    write: options => Effect.map(writeEvents([options]), Arr.headNonEmpty),
+    writeMany: options => writeEvents(options.events),
     entries: journal.entries,
     destroy: journal.destroy
   });
@@ -611,8 +840,27 @@ export const layer = (_schema, layer) => layer.pipe(Layer.provideMerge(layerEven
  *
  * **Details**
  *
- * The returned function delegates to the `EventLog` service and preserves each
- * event's success and error types.
+ * The returned function takes one `{ event, payload }` object, typed so the
+ * payload matches the event, as `writeMany` items are. It delegates to the
+ * `EventLog` service and preserves each event's success and error types.
+ *
+ * **Example** (Writing events with a client)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { EventGroup, EventLog } from "effect/eventlog"
+ *
+ * const Users = EventGroup.empty.add({
+ *   tag: "UserCreated",
+ *   primaryKey: (payload) => payload.id,
+ *   payload: Schema.Struct({ id: Schema.String })
+ * })
+ *
+ * export const createUser = Effect.gen(function*() {
+ *   const client = yield* EventLog.makeClient(EventLog.schema(Users))
+ *   yield* client({ event: "UserCreated", payload: { id: "user-1" } })
+ * })
+ * ```
  *
  * @stability unstable
  * @category constructors
@@ -620,10 +868,10 @@ export const layer = (_schema, layer) => layer.pipe(Layer.provideMerge(layerEven
  */
 export const makeClient = schema => Effect.gen(function* () {
   const log = yield* EventLog;
-  return (event, payload) => log.write({
+  return item => log.write({
     schema,
-    event,
-    payload
+    event: item.event,
+    payload: item.payload
   });
 });
 //# sourceMappingURL=EventLog.js.map