effect 4.0.0-beta.71 → 4.0.0-beta.73

package/src/unstable/cluster/RunnerServer.ts

@@ -46,8 +46,8 @@ import { ShardingConfig } from "./ShardingConfig.ts"
 const constVoid = constant(Effect.void)
 
 /**
- * Layer of RPC handlers for the runner protocol, forwarding ping, notify, effect,
- * stream, and envelope requests to `Sharding` and `MessageStorage`.
+ * Layer that handles runner protocol RPCs by forwarding requests to `Sharding`
+ * and `MessageStorage`.
  *
  * @category layers
  * @since 4.0.0
@@ -187,7 +187,8 @@ export const layer: Layer.Layer<
 }).pipe(Layer.provide(layerHandlers))
 
 /**
- * A `RunnerServer` layer that includes the `Runners` & `Sharding` clients.
+ * Layer that provides `RunnerServer` together with `Runners` and `Sharding`
+ * clients.
  *
  * @category layers
  * @since 4.0.0

package/src/unstable/cluster/Runners.ts

@@ -67,7 +67,7 @@ import * as Snowflake from "./Snowflake.ts"
  */
 export class Runners extends Context.Service<Runners, {
   /**
-   * Checks if a Runner is responsive.
+   * Checks whether a Runner is responsive.
    */
   readonly ping: (address: RunnerAddress) => Effect.Effect<void, RunnerUnavailable>
 

package/src/unstable/cluster/ShardId.ts

@@ -55,8 +55,8 @@ export interface ShardId extends Equal.Equal, Hash.Hash, PrimaryKey.PrimaryKey {
 export const isShardId = (u: unknown): u is ShardId => hasProperty(u, TypeId)
 
 /**
- * Schema for `ShardId` values encoded as `{ group, id }` objects and decoded via
- * `make`.
+ * Schema for shard identifiers encoded as `{ group, id }` objects and decoded
+ * via `make`.
  *
  * @category schemas
  * @since 4.0.0

package/src/unstable/cluster/Sharding.ts

@@ -103,11 +103,16 @@ import { SingletonAddress } from "./SingletonAddress.ts"
 import * as Snowflake from "./Snowflake.ts"
 
 /**
- * Cluster sharding service for registering entities and singletons, routing
- * messages to owned shards, generating runner-local snowflake ids, and polling
+ * Service that registers entities and singletons, routes messages to owned
+ * shards, generates runner-local snowflake ids, and polls
  * storage for persisted work.
  *
- * @category models
+ * **When to use**
+ *
+ * Use to access or provide cluster routing, shard ownership, entity
+ * registration, singleton registration, and persisted-work polling.
+ *
+ * @category tags
  * @since 4.0.0
  */
 export class Sharding extends Context.Service<Sharding, {

package/src/unstable/cluster/ShardingConfig.ts

@@ -239,10 +239,10 @@ export const layer = (options?: Partial<ShardingConfig["Service"]>): Layer.Layer
 export const layerDefaults: Layer.Layer<ShardingConfig> = layer()
 
 /**
- * Config descriptor for loading `ShardingConfig` values, applying the same
+ * Describes how to load `ShardingConfig` values, applying the same
  * defaults used by the in-memory `defaults` object.
  *
- * @category Config
+ * @category configuration
  * @since 4.0.0
  */
 export const config: Config.Config<ShardingConfig["Service"]> = Config.all({
@@ -345,7 +345,7 @@ export const config: Config.Config<ShardingConfig["Service"]> = Config.all({
  * Effect that loads `ShardingConfig` from environment variables using the
  * constant-case config provider.
  *
- * @category Config
+ * @category configuration
  * @since 4.0.0
  */
 export const configFromEnv = config.pipe(

package/src/unstable/cluster/ShardingRegistrationEvent.ts

@@ -67,8 +67,7 @@ export interface SingletonRegistered {
 }
 
 /**
- * Generated helpers for pattern matching and constructing sharding registration
- * events.
+ * Constructors and matchers for sharding registration events.
  *
  * @category pattern matching
  * @since 4.0.0

package/src/unstable/cluster/SingleRunner.ts

@@ -36,7 +36,7 @@ import * as SqlMessageStorage from "./SqlMessageStorage.ts"
 import * as SqlRunnerStorage from "./SqlRunnerStorage.ts"
 
 /**
- * A sql backed single-node cluster, that can be used for running durable
+ * Provides a SQL-backed single-node cluster for running durable
  * entities and workflows.
  *
  * **When to use**

package/src/unstable/cluster/Snowflake.ts

@@ -56,9 +56,10 @@ export type TypeId = typeof TypeId
 export type Snowflake = Brand.Branded<bigint, TypeId>
 
 /**
- * Constructs a branded `Snowflake` from a bigint or bigint-compatible string.
+ * Constructs a branded cluster snowflake id from a bigint or bigint-compatible
+ * string.
  *
- * @category models
+ * @category constructors
  * @since 4.0.0
  */
 export const Snowflake = (input: string | bigint): Snowflake =>
@@ -132,9 +133,9 @@ export const SnowflakeFromString: SnowflakeFromString = Schema.String.pipe(
 )
 
 /**
- * Custom snowflake epoch in Unix milliseconds, set to January 1, 2025 UTC.
+ * Defines the custom snowflake epoch in Unix milliseconds.
  *
- * @category Epoch
+ * @category constants
  * @since 4.0.0
  */
 export const constEpochMillis: number = Date.UTC(2025, 0, 1)
@@ -146,7 +147,7 @@ const constBigInt1024 = BigInt(1024)
 const constBigInt4096 = BigInt(4096)
 
 /**
- * Packs a timestamp, machine id, and sequence number into a branded snowflake id,
+ * Creates a branded snowflake id from a timestamp, machine id, and sequence number,
  * using the custom snowflake epoch and 10-bit machine id and 12-bit sequence
  * fields.
  *

package/src/unstable/cluster/SocketRunner.ts

@@ -91,9 +91,14 @@ export const layer: Layer.Layer<
 )
 
 /**
- * Client-only socket runner layer that provides `Sharding` and `Runners` clients
+ * Provides a client-only socket runner layer that provides `Sharding` and `Runners` clients
  * without starting a runner server or receiving shard assignments.
  *
+ * **When to use**
+ *
+ * Use to join a socket-based cluster as a client-only participant that can send
+ * messages without hosting shards.
+ *
  * @category layers
  * @since 4.0.0
  */

package/src/unstable/cluster/TestRunner.ts

@@ -38,7 +38,7 @@ import * as Sharding from "./Sharding.ts"
 import * as ShardingConfig from "./ShardingConfig.ts"
 
 /**
- * An in-memory cluster that can be used for testing purposes.
+ * Layer that provides an in-memory cluster for testing.
  *
  * **Details**
  *

package/src/unstable/encoding/Msgpack.ts

@@ -377,7 +377,8 @@ export const duplexSchema: {
 export interface schema<S extends Schema.Top> extends Schema.decodeTo<S, Schema.instanceOf<Uint8Array<ArrayBuffer>>> {}
 
 /**
- * Schema transformation between MessagePack bytes and decoded values.
+ * Schema for decoding MessagePack bytes into values and encoding values back to
+ * MessagePack bytes.
  *
  * **Details**
  *

package/src/unstable/encoding/Sse.ts

@@ -488,8 +488,8 @@ export const Event: Schema.Struct<{
 })
 
 /**
- * Schema transformation between the untagged SSE event shape and the tagged
- * `Event` model.
+ * Schema for transforming untagged SSE event payloads into tagged `Event`
+ * models.
  *
  * @category models
  * @since 4.0.0
@@ -528,7 +528,7 @@ export interface EventEncoded {
 const RetryTypeId = "~effect/encoding/Sse/Retry" as const
 
 /**
- * Server-Sent Events retry directive.
+ * Represents a Server-Sent Events retry directive.
  *
  * **Details**
  *

package/src/unstable/eventlog/EventGroup.ts

@@ -195,7 +195,7 @@ const makeProto = <
 }
 
 /**
- * Empty event group used as the starting point for defining a group.
+ * Creates an empty event group used as the starting point for defining a group.
  *
  * **When to use**
  *

package/src/unstable/eventlog/EventJournal.ts

@@ -156,7 +156,7 @@ export class EventJournalError extends Data.TaggedError("EventJournalError")<{
 /**
  * Brand identifier used for `RemoteId` values.
  *
- * @category remote
+ * @category type IDs
  * @since 4.0.0
  */
 export type RemoteIdTypeId = "effect/eventlog/EventJournal/RemoteId"
@@ -164,7 +164,7 @@ export type RemoteIdTypeId = "effect/eventlog/EventJournal/RemoteId"
 /**
  * Runtime brand identifier used for `RemoteId` values.
  *
- * @category remote
+ * @category type IDs
  * @since 4.0.0
  */
 export const RemoteIdTypeId: RemoteIdTypeId = "effect/eventlog/EventJournal/RemoteId"
@@ -201,7 +201,7 @@ export const makeRemoteIdUnsafe = (): RemoteId => Uuid.v4({}, new globalThis.Uin
 /**
  * Runtime brand identifier used for `EntryId` values.
  *
- * @category entry
+ * @category type IDs
  * @since 4.0.0
  */
 export const EntryIdTypeId: EntryIdTypeId = "effect/eventlog/EventJournal/EntryId"
@@ -209,7 +209,7 @@ export const EntryIdTypeId: EntryIdTypeId = "effect/eventlog/EventJournal/EntryI
 /**
  * Brand identifier used for `EntryId` values.
  *
- * @category entry
+ * @category type IDs
  * @since 4.0.0
  */
 export type EntryIdTypeId = "effect/eventlog/EventJournal/EntryId"
@@ -233,7 +233,7 @@ export const EntryId = (Schema.Uint8Array as Schema.instanceOf<Uint8Array<ArrayB
 )
 
 /**
- * Ordering for `EntryId` values based on their raw UUID bytes.
+ * Provides an Ordering instance for entry identifiers based on their raw UUID bytes.
  *
  * @category entry
  * @since 4.0.0
@@ -275,7 +275,7 @@ export const entryIdMillis = (entryId: EntryId): number => {
 }
 
 /**
- * Schema model for a committed event journal entry.
+ * Schema for a committed event journal entry.
  *
  * **Details**
  *
@@ -348,7 +348,7 @@ export class Entry extends Schema.Class<Entry>("effect/eventlog/EventJournal/Ent
 }
 
 /**
- * Schema model for an event journal entry received from a remote source.
+ * Schema for an event journal entry received from a remote source.
  *
  * **Details**
  *

package/src/unstable/eventlog/EventLog.ts

@@ -83,10 +83,10 @@ export class EventLog extends Context.Service<EventLog, {
 }>()("effect/eventlog/EventLog") {}
 
 /**
- * Scoped registry used by `EventLog` to collect event handlers, compaction
- * handlers, remote replicas, and reactivity invalidation keys.
+ * Service that collects event handlers, compaction handlers, remote replicas,
+ * and reactivity invalidation keys.
  *
- * @category Registry
+ * @category services
  * @since 4.0.0
  */
 export class Registry extends Context.Service<Registry, {
@@ -125,7 +125,7 @@ export class Registry extends Context.Service<Registry, {
  * Provides an in-memory `Registry` for event handlers, compactors, remote
  * replicas, and reactivity keys.
  *
- * @category Registry
+ * @category layers
  * @since 4.0.0
  */
 export const layerRegistry = Layer.effect(
@@ -189,14 +189,15 @@ export const layerRegistry = Layer.effect(
 )
 
 /**
- * Event-log identity containing a public key and redacted private key material.
+ * Context service for an event-log identity containing a public key and redacted
+ * private key material.
  *
  * **Details**
  *
  * The identity is used by remote replication for authentication and by the
  * encryption service to derive signing and encryption keys.
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export class Identity extends Context.Service<Identity, {
@@ -207,7 +208,7 @@ export class Identity extends Context.Service<Identity, {
 /**
  * Type-level identifier used to brand `EventLogSchema` values.
  *
- * @category schemas
+ * @category type IDs
  * @since 4.0.0
  */
 export type SchemaTypeId = "~effect/eventlog/EventLog/Schema"
@@ -215,7 +216,7 @@ export type SchemaTypeId = "~effect/eventlog/EventLog/Schema"
 /**
  * Runtime property key used to identify `EventLogSchema` values.
  *
- * @category schemas
+ * @category type IDs
  * @since 4.0.0
  */
 export const SchemaTypeId: SchemaTypeId = "~effect/eventlog/EventLog/Schema"
@@ -259,7 +260,7 @@ export const schema = <Groups extends ReadonlyArray<EventGroup.Any>>(
 /**
  * Type-level identifier used to brand `Handlers` values.
  *
- * @category handlers
+ * @category type IDs
  * @since 4.0.0
  */
 export type HandlersTypeId = "~effect/eventlog/EventLog/Handlers"
@@ -267,7 +268,7 @@ export type HandlersTypeId = "~effect/eventlog/EventLog/Handlers"
 /**
  * Runtime property key used to identify `Handlers` values.
  *
- * @category handlers
+ * @category type IDs
  * @since 4.0.0
  */
 export const HandlersTypeId: HandlersTypeId = "~effect/eventlog/EventLog/Handlers"

package/src/unstable/eventlog/EventLogEncryption.ts

@@ -74,10 +74,15 @@ const toArrayBuffer = (data: Uint8Array): ArrayBuffer => {
 const toBufferSource = (data: Uint8Array): ArrayBufferView<ArrayBuffer> => new Uint8Array(toArrayBuffer(data))
 
 /**
- * Service used by event-log replication for identity generation, entry
- * encryption and decryption, and SHA-256 hashing.
+ * Service that provides identity generation, entry
+ * encryption and decryption, and SHA-256 hashing for event-log replication.
  *
- * @category services
+ * **When to use**
+ *
+ * Use to provide cryptographic operations required by encrypted event-log
+ * replication.
+ *
+ * @category tags
  * @since 4.0.0
  */
 export class EventLogEncryption extends Context.Service<EventLogEncryption, {

package/src/unstable/eventlog/EventLogMessage.ts

@@ -39,7 +39,7 @@ import { EncryptedEntry, EncryptedRemoteEntry } from "./EventLogEncryption.ts"
 /**
  * Type-level identifier used to brand event-log store ids.
  *
- * @category StoreId
+ * @category type IDs
  * @since 4.0.0
  */
 export type StoreIdTypeId = "effect/eventlog/EventLog/StoreId"
@@ -47,7 +47,7 @@ export type StoreIdTypeId = "effect/eventlog/EventLog/StoreId"
 /**
  * Runtime brand identifier for event-log store ids.
  *
- * @category StoreId
+ * @category type IDs
  * @since 4.0.0
  */
 export const StoreIdTypeId: StoreIdTypeId = "effect/eventlog/EventLog/StoreId"
@@ -69,14 +69,14 @@ export type StoreId = string & Brand<StoreIdTypeId>
 export const StoreId = Schema.String.pipe(Schema.brand(StoreIdTypeId))
 
 /**
- * Structured error returned by event-log remote RPCs.
+ * Error returned by event-log remote RPCs.
  *
  * **Details**
  *
  * It records the request tag, optional identity and store information, a protocol
  * error code, and a human-readable message.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class EventLogProtocolError extends Schema.TaggedErrorClass<EventLogProtocolError>(
@@ -93,7 +93,7 @@ export class EventLogProtocolError extends Schema.TaggedErrorClass<EventLogProto
  * RPC middleware that authenticates event-log requests and provides the client
  * `Identity` to authenticated handlers.
  *
- * @category Middleware
+ * @category middleware
  * @since 4.0.0
  */
 export class EventLogAuthentication extends RpcMiddleware.Service<EventLogAuthentication, {
@@ -110,7 +110,7 @@ export class EventLogAuthentication extends RpcMiddleware.Service<EventLogAuthen
  * It contains the server remote id and a challenge that must be signed by the
  * client.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class HelloResponse extends Schema.Class<HelloResponse>("effect/eventlog/EventLogRemote/HelloResponse")({
@@ -121,7 +121,7 @@ export class HelloResponse extends Schema.Class<HelloResponse>("effect/eventlog/
 /**
  * RPC used to start an event-log remote session and receive a `HelloResponse`.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class HelloRpc extends Rpc.make("EventLog.Hello", {
@@ -129,10 +129,11 @@ export class HelloRpc extends Rpc.make("EventLog.Hello", {
 }) {}
 
 /**
- * Authentication request containing the client public key, Ed25519 signing public
- * key, signature over the session challenge payload, and algorithm name.
+ * Schema for an authentication request containing the client public key,
+ * Ed25519 signing public key, signature over the session challenge payload, and
+ * algorithm name.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class Authenticate extends Schema.Class<Authenticate>("effect/eventlog/EventLogRemote/Authenticate")({
@@ -145,7 +146,7 @@ export class Authenticate extends Schema.Class<Authenticate>("effect/eventlog/Ev
 /**
  * RPC used to authenticate a remote event-log session after `HelloRpc`.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class AuthenticateRpc extends Rpc.make("EventLog.Authenticate", {
@@ -154,9 +155,9 @@ export class AuthenticateRpc extends Rpc.make("EventLog.Authenticate", {
 }) {}
 
 /**
- * Transport message containing an entire encoded event-log payload in one frame.
+ * Represents an entire encoded event-log payload in one transport frame.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class SingleMessage
@@ -166,14 +167,14 @@ export class SingleMessage
 {}
 
 /**
- * Transport message for one part of a large encoded event-log payload.
+ * Represents one part of a large encoded event-log payload.
  *
  * **When to use**
  *
  * Use to divide data into chunks and `join` to reassemble all chunks with
  * the same id once every part has arrived.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class ChunkedMessage
@@ -254,9 +255,9 @@ export class ChunkedMessage
 }
 
 /**
- * Authenticated RPC for sending one chunk of a large encoded write payload.
+ * RPC used to send one chunk of a large encoded write payload.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class WriteChunkedRpc extends Rpc.make("EventLog.WriteChunked", {
@@ -265,14 +266,14 @@ export class WriteChunkedRpc extends Rpc.make("EventLog.WriteChunked", {
 }).middleware(EventLogAuthentication) {}
 
 /**
- * Msgpack-encodable payload for writing encrypted entries to a remote store.
+ * Schema for encrypted event-log write payloads sent to a remote store.
  *
  * **Details**
  *
  * It includes the client public key, target store id, AES-GCM initialization
  * vector, and encrypted entries.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class WriteEntries extends Schema.Class<WriteEntries>("effect/eventlog/EventLogRemote/WriteEntries")({
@@ -290,9 +291,9 @@ export class WriteEntries extends Schema.Class<WriteEntries>("effect/eventlog/Ev
 }
 
 /**
- * Msgpack-encodable payload for writing plaintext entries to a remote store.
+ * Schema for plaintext event-log write payloads sent to a remote store.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class WriteEntriesUnencrypted
@@ -311,10 +312,9 @@ export class WriteEntriesUnencrypted
 }
 
 /**
- * Authenticated RPC for sending an encoded write payload that fits in one
- * message.
+ * RPC used to send an encoded write payload that fits in one message.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class WriteSingleRpc extends Rpc.make("EventLog.WriteSingle", {
@@ -325,15 +325,15 @@ export class WriteSingleRpc extends Rpc.make("EventLog.WriteSingle", {
 }).middleware(EventLogAuthentication) {}
 
 /**
- * Authenticated streaming RPC for reading remote event-log changes for a public
- * key and store id starting at a sequence number.
+ * RPC used to stream remote event-log changes for a public key and store id
+ * starting at a sequence number.
  *
  * **Details**
  *
  * Responses are encoded as either `SingleMessage` values or `ChunkedMessage`
  * parts.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class ChangesRpc extends Rpc.make("EventLog.Changes", {
@@ -358,7 +358,7 @@ export class ChangesRpc extends Rpc.make("EventLog.Changes", {
  * RPC group containing the event-log remote handshake, authentication, write, and
  * changes endpoints.
  *
- * @category protocol
+ * @category protocols
  * @since 4.0.0
  */
 export class EventLogRemoteRpcs extends RpcGroup.make(

package/src/unstable/eventlog/EventLogRemote.ts

@@ -51,14 +51,19 @@ import { encodeSessionAuthPayload, signSessionAuthPayloadBytes } from "./EventLo
 import { makeGetIdentityRootSecretMaterial } from "./internal/identityRootSecretDerivation.ts"
 
 /**
- * Service representing a remote event-log replica.
+ * Service that represents a remote event-log replica.
+ *
+ * **When to use**
+ *
+ * Use to access or provide a remote event-log replica that can write local
+ * entries and stream remote changes.
  *
  * **Details**
  *
  * It can write local entries to the remote, stream remote changes from a sequence
  * number, and run effects only after the supplied identity has authenticated.
  *
- * @category models
+ * @category tags
  * @since 4.0.0
  */
 export class EventLogRemote extends Context.Service<EventLogRemote, {
@@ -117,9 +122,14 @@ const makeAuthenticate = Effect.fnUntraced(function*(options: {
 })
 
 /**
- * Typed RPC client service for the `EventLogRemoteRpcs` protocol.
+ * Service that provides a typed RPC client for the `EventLogRemoteRpcs` protocol.
+ *
+ * **When to use**
+ *
+ * Use to provide the RPC client used by remote event-log replicas to
+ * authenticate, write entries, and subscribe to changes.
  *
- * @category RpcClient
+ * @category RPC client
  * @since 4.0.0
  */
 export class EventLogRemoteClient extends Context.Service<

package/src/unstable/eventlog/EventLogServer.ts

@@ -229,10 +229,15 @@ export const layerRpcHandlers = (options: {
   )
 
 /**
- * Client annotation storing partial `ChunkedMessage` data while chunked writes are
+ * Annotation that stores partial `ChunkedMessage` data while chunked writes are
  * being reassembled.
  *
- * @category ChunkedMessage state
+ * **When to use**
+ *
+ * Use to keep per-client chunk assembly state while handling chunked event-log
+ * writes.
+ *
+ * @category chunked message state
  * @since 4.0.0
  */
 export class ChunkedMessageState extends Context.Reference<

package/src/unstable/eventlog/EventLogServerEncrypted.ts

@@ -126,7 +126,7 @@ export const layer: Layer.Layer<never, never, RpcServer.Protocol | Storage> = Rp
 )
 
 /**
- * Encrypted entry representation persisted by the encrypted event-log server.
+ * Schema for encrypted entries persisted by the encrypted event-log server.
  *
  * @category storage
  * @since 4.0.0
@@ -149,7 +149,12 @@ export class PersistedEntry extends Schema.Class<PersistedEntry>(
 }
 
 /**
- * Storage service used by the encrypted event-log server.
+ * Defines the backing store service used by the encrypted event-log server.
+ *
+ * **When to use**
+ *
+ * Use to provide durable encrypted event-log persistence for an encrypted
+ * event-log server layer.
  *
  * **Details**
  *