effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/unstable/eventlog/EventGroup.ts

@@ -1,4 +1,19 @@
 /**
+ * Defines typed groups of event-log event definitions.
+ *
+ * Event groups describe the events that belong to one event-log domain, such as
+ * commands for an aggregate, application workflow, or synced local store. Start
+ * from `empty`, add event tags with their payload, success, and error schemas,
+ * then use the group with `EventLog.group` to provide the handlers that execute
+ * and commit those events.
+ *
+ * Each event tag becomes the key in the group's events record, so tags should be
+ * unique within a group. The `primaryKey` function is part of the event
+ * definition and should derive the stable partition key from the decoded
+ * payload. Omitted schemas default to `Schema.Void` for payload and success, and
+ * `Schema.Never` for errors; use `addError` when every event in the group shares
+ * an additional error schema.
+ *
  * @since 4.0.0
  */
 import { type Pipeable, pipeArguments } from "../../Pipeable.ts"
@@ -8,31 +23,38 @@ import type * as Schema from "../../Schema.ts"
 import * as Event from "./Event.ts"
 
 /**
- * @since 4.0.0
+ * Unique type identifier used to mark event log event groups.
+ *
  * @category type ids
+ * @since 4.0.0
  */
 export type TypeId = "~effect/eventlog/EventGroup"
 
 /**
- * @since 4.0.0
+ * Runtime type identifier used to mark event log event groups.
+ *
  * @category type ids
+ * @since 4.0.0
  */
 export const TypeId: TypeId = "~effect/eventlog/EventGroup"
 
 /**
- * @since 4.0.0
+ * Returns `true` when a value is an event log event group.
+ *
  * @category guards
+ * @since 4.0.0
  */
 export const isEventGroup = (u: unknown): u is Any => Predicate.hasProperty(u, TypeId)
 
 /**
- * An `EventGroup` is a collection of `Event`s. You can use an `EventGroup` to
- * represent a portion of your domain.
+ * Typed collection of event definitions that represents a portion of an event log
+ * domain.
  *
- * The events can be implemented later using the `EventLogBuilder.group` api.
+ * Build groups from `empty.add(...)`, then provide implementations for the events
+ * with `EventLog.group`.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface EventGroup<
   out Events extends Event.Any = Event.Any
@@ -63,42 +85,54 @@ export interface EventGroup<
 }
 
 /**
- * @since 4.0.0
+ * Type-erased marker for an event log event group.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Any {
   readonly [TypeId]: TypeId
 }
 
 /**
- * @since 4.0.0
+ * Type-erased event group with its events record available structurally.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type AnyWithProps = EventGroup<Event.Any>
 
 /**
- * @since 4.0.0
+ * Derives the handler service markers required for all events in an event group.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ToService<A> = A extends EventGroup<infer _Events> ? Event.ToService<_Events>
   : never
 
 /**
- * @since 4.0.0
+ * Extracts the union of event definitions contained in an event group.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Events<Group> = Group extends EventGroup<infer _Events> ? _Events
   : never
 
 /**
- * @since 4.0.0
+ * Client-side schema services required by all events in an event group.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ServicesClient<Group> = Event.ServicesClient<Events<Group>>
 
 /**
- * @since 4.0.0
+ * Server-side schema services required by all events in an event group.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ServicesServer<Group> = Event.ServicesServer<Events<Group>>
 
@@ -151,12 +185,11 @@ const makeProto = <
 }
 
 /**
- * An `EventGroup` is a collection of `Event`s. You can use an `EventGroup` to
- * represent a portion of your domain.
+ * Empty event group used as the starting point for defining a group.
  *
- * The events can be implemented later using the `EventLog.group` api.
+ * Call `.add(...)` to add event definitions and build a typed `EventGroup`.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const empty: EventGroup<never> = makeProto({ events: Record.empty() })

package/src/unstable/eventlog/EventJournal.ts

@@ -1,4 +1,20 @@
 /**
+ * Low-level storage and replay primitives for the unstable event-log system.
+ *
+ * An `EventJournal` records committed event entries, exposes them for replay,
+ * and tracks the replication state needed to exchange entries with remote
+ * journals. It is the persistence boundary used by higher-level event-log
+ * schemas and handlers for workflows such as rebuilding projections, syncing
+ * offline clients, importing remote changes, and coordinating per-store writes.
+ *
+ * Journal entries are ordered by their UUID v7 entry ids, so persistence and
+ * replay code should account for clock-derived ordering when detecting
+ * conflicts. Payloads are stored as encoded bytes and must remain compatible
+ * with the event schemas that will decode them later. Remote writes may include
+ * duplicate entries, compaction can rewrite the set of imported entries before
+ * effects run, and replay handlers should be prepared for entries that arrive
+ * after local changes for the same event and primary key.
+ *
  * @since 4.0.0
  */
 import * as Uuid from "uuid"
@@ -17,8 +33,13 @@ import * as Msgpack from "../encoding/Msgpack.ts"
 import type { StoreId } from "./EventLogMessage.ts"
 
 /**
- * @since 4.0.0
+ * Context service for storing and replaying event journal entries.
+ *
+ * The service writes local entries, imports entries from remote journals, exposes
+ * a stream of local changes, and provides per-store locking.
+ *
  * @category context
+ * @since 4.0.0
  */
 export class EventJournal extends Context.Service<EventJournal, {
   /**
@@ -90,78 +111,107 @@ export class EventJournal extends Context.Service<EventJournal, {
 const TypeId = "effect/eventlog/EventJournal/EventJournalError" as const
 
 /**
- * @since 4.0.0
+ * Error raised by event journal operations.
+ *
+ * The error records the journal method that failed and the underlying cause.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class EventJournalError extends Data.TaggedError("EventJournalError")<{
   readonly method: string
   readonly cause: unknown
 }> {
   /**
+   * Marks this value as an event journal error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [TypeId] = TypeId
 }
 
 /**
- * @since 4.0.0
+ * Brand identifier used for `RemoteId` values.
+ *
  * @category remote
+ * @since 4.0.0
  */
 export type RemoteIdTypeId = "effect/eventlog/EventJournal/RemoteId"
 
 /**
- * @since 4.0.0
+ * Runtime brand identifier used for `RemoteId` values.
+ *
  * @category remote
+ * @since 4.0.0
  */
 export const RemoteIdTypeId: RemoteIdTypeId = "effect/eventlog/EventJournal/RemoteId"
 
 /**
- * @since 4.0.0
+ * Branded byte identifier for a remote event journal source.
+ *
  * @category remote
+ * @since 4.0.0
  */
 export type RemoteId = Uint8Array & Brand<RemoteIdTypeId>
 
 /**
- * @since 4.0.0
+ * Schema for branded remote event journal identifiers.
+ *
  * @category remote
+ * @since 4.0.0
  */
 export const RemoteId = Schema.Uint8Array.pipe(Schema.brand(RemoteIdTypeId))
 
 /**
- * @since 4.0.0
+ * Generates a new random `RemoteId`.
+ *
+ * This is unsafe because the generated UUID bytes are cast to the brand without
+ * schema validation.
+ *
  * @category remote
+ * @since 4.0.0
  */
 export const makeRemoteIdUnsafe = (): RemoteId => Uuid.v4({}, new globalThis.Uint8Array(16)) as RemoteId
 
 /**
- * @since 4.0.0
+ * Runtime brand identifier used for `EntryId` values.
+ *
  * @category entry
+ * @since 4.0.0
  */
 export const EntryIdTypeId: EntryIdTypeId = "effect/eventlog/EventJournal/EntryId"
 
 /**
- * @since 4.0.0
+ * Brand identifier used for `EntryId` values.
+ *
  * @category entry
+ * @since 4.0.0
  */
 export type EntryIdTypeId = "effect/eventlog/EventJournal/EntryId"
 
 /**
- * @since 4.0.0
+ * Branded byte identifier for an event journal entry.
+ *
  * @category entry
+ * @since 4.0.0
  */
 export type EntryId = Uint8Array<ArrayBuffer> & Brand<EntryIdTypeId>
 
 /**
- * @since 4.0.0
+ * Schema for branded event journal entry identifiers.
+ *
  * @category entry
+ * @since 4.0.0
  */
 export const EntryId = (Schema.Uint8Array as Schema.instanceOf<Uint8Array<ArrayBuffer>>).pipe(
   Schema.brand(EntryIdTypeId)
 )
 
 /**
- * @since 4.0.0
+ * Ordering for `EntryId` values based on their raw UUID bytes.
+ *
  * @category entry
+ * @since 4.0.0
  */
 export const EntryIdOrder = Order.make<EntryId>((a, b) => {
   for (let i = 0; i < 16; i++) {
@@ -173,15 +223,23 @@ export const EntryIdOrder = Order.make<EntryId>((a, b) => {
 })
 
 /**
- * @since 4.0.0
+ * Generates a UUID v7 `EntryId`, optionally using the supplied millisecond
+ * timestamp.
+ *
+ * This is unsafe because the generated UUID bytes are cast to the brand without
+ * schema validation.
+ *
  * @category entry
+ * @since 4.0.0
  */
 export const makeEntryIdUnsafe = (options: { msecs?: number } = {}): EntryId =>
   Uuid.v7(options, new globalThis.Uint8Array(16)) as EntryId
 
 /**
- * @since 4.0.0
+ * Extracts the millisecond timestamp encoded in a UUID v7 `EntryId`.
+ *
  * @category entry
+ * @since 4.0.0
  */
 export const entryIdMillis = (entryId: EntryId): number => {
   const bytes = new Uint8Array(8)
@@ -190,8 +248,13 @@ export const entryIdMillis = (entryId: EntryId): number => {
 }
 
 /**
- * @since 4.0.0
+ * Schema model for a committed event journal entry.
+ *
+ * An entry records its ID, event tag, primary key, and MessagePack-encoded
+ * payload, with helpers for array MessagePack encoding and creation timestamps.
+ *
  * @category entry
+ * @since 4.0.0
  */
 export class Entry extends Schema.Class<Entry>("effect/eventlog/EventJournal/Entry")({
   id: EntryId,
@@ -200,26 +263,36 @@ export class Entry extends Schema.Class<Entry>("effect/eventlog/EventJournal/Ent
   payload: Schema.Uint8Array
 }) {
   /**
+   * MessagePack schema for arrays of committed event journal entries.
+   *
    * @since 4.0.0
    */
   static arrayMsgpack = Schema.Array(Msgpack.schema(Entry))
 
   /**
+   * Encodes arrays of committed entries with the MessagePack entry schema.
+   *
    * @since 4.0.0
    */
   static encodeArray = Schema.encodeUnknownEffect(Entry.arrayMsgpack)
 
   /**
+   * Decodes arrays of committed entries with the MessagePack entry schema.
+   *
    * @since 4.0.0
    */
   static decodeArray = Schema.decodeUnknownEffect(Entry.arrayMsgpack)
 
   /**
+   * Ordering for committed entries by their event journal entry id.
+   *
    * @since 4.0.0
    */
   static Order = Order.make<Entry>((a, b) => EntryIdOrder(a.id, b.id))
 
   /**
+   * String representation of the entry id.
+   *
    * @since 4.0.0
    */
   get idString(): string {
@@ -227,6 +300,8 @@ export class Entry extends Schema.Class<Entry>("effect/eventlog/EventJournal/Ent
   }
 
   /**
+   * Creation timestamp encoded in the UUID v7 entry id, in epoch milliseconds.
+   *
    * @since 4.0.0
    */
   get createdAtMillis(): number {
@@ -234,6 +309,8 @@ export class Entry extends Schema.Class<Entry>("effect/eventlog/EventJournal/Ent
   }
 
   /**
+   * Creation timestamp encoded in the UUID v7 entry id, as a UTC date-time.
+   *
    * @since 4.0.0
    */
   get createdAt(): DateTime.Utc {
@@ -242,8 +319,12 @@ export class Entry extends Schema.Class<Entry>("effect/eventlog/EventJournal/Ent
 }
 
 /**
- * @since 4.0.0
+ * Schema model for an event journal entry received from a remote source.
+ *
+ * It pairs the remote sequence number with the journal entry payload.
+ *
  * @category entry
+ * @since 4.0.0
  */
 export class RemoteEntry extends Schema.Class<RemoteEntry>("effect/eventlog/EventJournal/RemoteEntry")({
   remoteSequence: Schema.Number,
@@ -251,8 +332,13 @@ export class RemoteEntry extends Schema.Class<RemoteEntry>("effect/eventlog/Even
 }) {}
 
 /**
- * @since 4.0.0
+ * Creates an in-memory `EventJournal` service.
+ *
+ * Entries, remote tracking state, and locks live only in the current process and
+ * are lost when the service is discarded.
+ *
  * @category memory
+ * @since 4.0.0
  */
 export const makeMemory: Effect.Effect<EventJournal["Service"]> = Effect.gen(function*() {
   const journal: Array<Entry> = []
@@ -384,14 +470,25 @@ export const makeMemory: Effect.Effect<EventJournal["Service"]> = Effect.gen(fun
 })
 
 /**
- * @since 4.0.0
+ * Layer that provides an in-memory `EventJournal`.
+ *
+ * All journal data is stored in process memory and is not persisted across layer
+ * lifetimes.
+ *
  * @category memory
+ * @since 4.0.0
  */
 export const layerMemory: Layer.Layer<EventJournal> = Layer.effect(EventJournal, makeMemory)
 
 /**
- * @since 4.0.0
+ * Creates an `EventJournal` backed by IndexedDB.
+ *
+ * The journal stores entries and remote replication metadata in the configured
+ * browser database, publishes local changes, and requires `Scope` so the database
+ * connection can be closed when the scope ends.
+ *
  * @category indexed db
+ * @since 4.0.0
  */
 export const makeIndexedDb = (options?: {
   readonly database?: string
@@ -648,8 +745,11 @@ const EntryIdbArray = Schema.Array(Entry)
 const decodeEntryIdbArray = Schema.decodeUnknownEffect(EntryIdbArray)
 
 /**
- * @since 4.0.0
+ * Provides `EventJournal` using the IndexedDB-backed implementation created by
+ * `makeIndexedDb`.
+ *
  * @category indexed db
+ * @since 4.0.0
  */
 export const layerIndexedDb = (options?: {
   readonly database?: string