effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/unstable/cluster/ClusterSchema.ts

@@ -1,4 +1,30 @@
 /**
+ * The `ClusterSchema` module defines the schema annotations used by Effect
+ * Cluster protocols. These annotations attach cluster-specific behavior to
+ * RPCs and entities without changing the request or response schemas
+ * themselves.
+ *
+ * **Common tasks**
+ *
+ * - Mark requests as persisted so mailbox storage can replay them after
+ *   interruption or restart
+ * - Run server-side handling inside a storage transaction when durable state
+ *   and SQL updates must commit together
+ * - Control whether client sending, server handling, or both are treated as
+ *   uninterruptible
+ * - Route entity ids into shard groups
+ * - Disable client tracing for internal protocols such as cron dispatch
+ * - Derive per-request annotations from the encoded request with {@link Dynamic}
+ *
+ * **Protocol notes**
+ *
+ * Cluster transports serialize the RPC payloads, not arbitrary runtime
+ * annotation values. Prefer static, deterministic annotations, and use
+ * {@link Dynamic} when a persisted or transactional decision depends on the
+ * request value that is already part of the protocol. Persisted requests require
+ * message storage support, and shard group selection must remain stable for a
+ * given entity id so routing is consistent across cluster members.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -8,8 +34,13 @@ import type { EntityId } from "./EntityId.ts"
 import type { Request } from "./Envelope.ts"
 
 /**
+ * Annotation that marks whether a cluster request should be persisted in mailbox
+ * storage.
+ *
+ * The default value is `false`.
+ *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const Persisted = Context.Reference<boolean>("effect/cluster/ClusterSchema/Persisted", {
   defaultValue: constFalse
@@ -19,8 +50,8 @@ export const Persisted = Context.Reference<boolean>("effect/cluster/ClusterSchem
  * Whether to wrap the request with a storage transaction, so sql queries are
  * committed atomically.
  *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const WithTransaction = Context.Reference<boolean>(
   "effect/cluster/ClusterSchema/WithTransaction",
@@ -28,8 +59,15 @@ export const WithTransaction = Context.Reference<boolean>(
 )
 
 /**
+ * Annotation that controls whether a cluster request is treated as
+ * uninterruptible.
+ *
+ * Use `true` for both client and server handling, `"client"` for client-side
+ * handling only, `"server"` for server-side handling only, or `false` to allow
+ * interruption.
+ *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const Uninterruptible = Context.Reference<boolean | "client" | "server">(
   "effect/cluster/ClusterSchema/Uninterruptible",
@@ -37,8 +75,11 @@ export const Uninterruptible = Context.Reference<boolean | "client" | "server">(
 )
 
 /**
+ * Returns whether the `Uninterruptible` annotation applies to server-side
+ * request handling for the provided context.
+ *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const isUninterruptibleForServer = (context: Context.Context<never>): boolean => {
   const value = Context.get(context, Uninterruptible)
@@ -46,8 +87,11 @@ export const isUninterruptibleForServer = (context: Context.Context<never>): boo
 }
 
 /**
+ * Returns whether the `Uninterruptible` annotation applies to client-side
+ * request handling for the provided context.
+ *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const isUninterruptibleForClient = (context: Context.Context<never>): boolean => {
   const value = Context.get(context, Uninterruptible)
@@ -55,8 +99,12 @@ export const isUninterruptibleForClient = (context: Context.Context<never>): boo
 }
 
 /**
+ * Annotation that selects the shard group for an entity id.
+ *
+ * By default, every entity id is assigned to the `"default"` shard group.
+ *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const ShardGroup = Context.Reference<(entityId: EntityId) => string>(
   "effect/cluster/ClusterSchema/ShardGroup",
@@ -64,8 +112,13 @@ export const ShardGroup = Context.Reference<(entityId: EntityId) => string>(
 )
 
 /**
+ * Annotation that controls whether client-side cluster request tracing is
+ * enabled.
+ *
+ * The default value is `true`.
+ *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const ClientTracingEnabled = Context.Reference<boolean>("effect/cluster/ClusterSchema/ClientTracingEnabled", {
   defaultValue: constTrue
@@ -75,8 +128,8 @@ export const ClientTracingEnabled = Context.Reference<boolean>("effect/cluster/C
  * Dynamically transform the request annotations based on the request.
  * This only applies to the requests handled by the Entity, not the client.
  *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const Dynamic = Context.Reference<
   (annotations: Context.Context<never>, request: Request<Rpc.AnyWithProps>) => Context.Context<never>

package/src/unstable/cluster/ClusterWorkflowEngine.ts

@@ -1,4 +1,25 @@
 /**
+ * The cluster workflow engine runs durable workflows on top of cluster sharding
+ * and message storage. It adapts `WorkflowEngine.WorkflowEngine` so workflow
+ * executions, activities, deferred completions, resumes, interrupts, and durable
+ * clock wakeups are represented as persisted cluster entity messages.
+ *
+ * **Common tasks**
+ *
+ * - Provide a workflow engine for services that already use cluster sharding
+ * - Execute workflows by stable execution id and poll their persisted result
+ * - Resume suspended workflows after activities, deferreds, or durable clock wakeups
+ * - Interrupt workflow executions and propagate resume signals to parent workflows
+ *
+ * **Gotchas**
+ *
+ * - Workflow names and execution ids determine the cluster entity address used
+ *   for persistence, so they must remain stable across deploys
+ * - Activities are persisted by activity name and attempt; retries and suspended
+ *   activity resumes depend on those primary keys
+ * - Durable clock wakeups are scheduled through a separate clock entity and are
+ *   cleared when an interrupted workflow stops waiting
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -38,8 +59,14 @@ import * as Sharding from "./Sharding.ts"
 import * as Snowflake from "./Snowflake.ts"
 
 /**
+ * Creates a `WorkflowEngine` implementation backed by cluster sharding and
+ * message storage.
+ *
+ * Workflow executions, activities, deferred completions, resumes, interrupts,
+ * and durable clock wakeups are coordinated through persisted cluster entities.
+ *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const make = Effect.gen(function*() {
   const sharding = yield* Sharding.Sharding
@@ -693,8 +720,14 @@ const ClockEntityLayer = ClockEntity.toLayer(Effect.gen(function*() {
 const InterruptSignal = DurableDeferred.make("Workflow/InterruptSignal")
 
 /**
+ * Layer that provides `WorkflowEngine.WorkflowEngine` using the cluster workflow
+ * engine implementation.
+ *
+ * It requires cluster sharding and message storage, and also registers the
+ * durable clock entity used for workflow wakeups.
+ *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layer: Layer.Layer<
   WorkflowEngine.WorkflowEngine,

package/src/unstable/cluster/DeliverAt.ts

@@ -1,32 +1,67 @@
 /**
+ * The `DeliverAt` module defines the protocol used by cluster message payloads
+ * that carry their own scheduled delivery time. A value implements the protocol
+ * by exposing a method at the `DeliverAt` symbol that returns the target
+ * `DateTime`.
+ *
+ * **Common tasks**
+ *
+ * - Mark a message payload as deliverable at a specific time by implementing
+ *   {@link DeliverAt}
+ * - Check whether an arbitrary value carries a scheduled delivery time with
+ *   {@link isDeliverAt}
+ * - Convert a scheduled delivery time to epoch milliseconds with
+ *   {@link toMillis}
+ *
+ * **Gotchas**
+ *
+ * - The protocol records the requested delivery instant; cluster infrastructure
+ *   may still deliver later because of clock skew, queue latency, or worker
+ *   availability
+ * - Values that do not implement the symbol method are treated as unscheduled;
+ *   {@link toMillis} returns `null` for those values
+ *
  * @since 4.0.0
  */
 import type { DateTime } from "../../DateTime.ts"
 import { hasProperty } from "../../Predicate.ts"
 
 /**
- * @since 4.0.0
+ * Property key used by values that provide a scheduled delivery time.
+ *
  * @category symbols
+ * @since 4.0.0
  */
 export const symbol = "~effect/cluster/DeliverAt"
 
 /**
- * @since 4.0.0
+ * Interface for payloads that specify when a cluster message should be delivered.
+ *
+ * Implementations return the target delivery `DateTime` through the `DeliverAt`
+ * symbol method.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface DeliverAt {
   [symbol](): DateTime
 }
 
 /**
- * @since 4.0.0
+ * Returns `true` if the value implements the `DeliverAt` scheduled-delivery
+ * protocol.
+ *
  * @category guards
+ * @since 4.0.0
  */
 export const isDeliverAt = (self: unknown): self is DeliverAt => hasProperty(self, symbol)
 
 /**
- * @since 4.0.0
+ * Returns the scheduled delivery time in epoch milliseconds when the value
+ * implements `DeliverAt`, or `null` otherwise.
+ *
  * @category accessors
+ * @since 4.0.0
  */
 export const toMillis = (self: unknown): number | null => {
   if (isDeliverAt(self)) {

package/src/unstable/cluster/Entity.ts

@@ -1,4 +1,36 @@
 /**
+ * The `Entity` module defines sharded, addressable actors for Effect Cluster.
+ * An entity type pairs a stable entity name with an RPC protocol and describes
+ * how requests for individual entity ids are routed to shard groups and
+ * runners.
+ *
+ * **Mental model**
+ *
+ * - An `Entity` is the cluster-facing definition for one logical actor type
+ * - Each entity id maps deterministically to a shard group and shard id
+ * - Clients are created per entity id and send typed RPC messages through the
+ *   cluster sharding layer
+ * - Server layers register handlers or mailbox processors for the entity type
+ *
+ * **Common tasks**
+ *
+ * - Define an entity protocol with RPCs and create an entity with {@link make}
+ * - Send messages to a specific entity id with {@link Entity.client}
+ * - Register typed RPC handlers with {@link Entity.toLayer}
+ * - Process envelopes directly with {@link Entity.toLayerQueue}
+ * - Access the current entity or runner address with {@link CurrentAddress} and
+ *   {@link CurrentRunnerAddress}
+ *
+ * **Gotchas**
+ *
+ * - Entity ids are part of routing: changing id formats can move work to
+ *   different shards
+ * - Entity type names should be stable and unique within a cluster deployment
+ * - Mailbox capacity and concurrency determine back pressure and duplicate
+ *   processing behavior
+ * - Persistence, mailbox, and already-processing failures are surfaced through
+ *   the generated clients
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -44,8 +76,13 @@ import * as Snowflake from "./Snowflake.ts"
 const TypeId = "~effect/cluster/Entity"
 
 /**
- * @since 4.0.0
+ * Represents a cluster entity type and the RPC protocol it can handle.
+ *
+ * An entity defines how ids map to shard groups, exposes a sharded client, and
+ * can be registered as a layer using RPC handlers or a mailbox queue.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Entity<
   in out Type extends string,
@@ -179,14 +216,23 @@ export interface Entity<
   >
 }
 /**
- * @since 4.0.0
+ * Type alias for any cluster `Entity`, regardless of entity type or RPC
+ * protocol.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Any = Entity<string, Rpc.Any>
 
 /**
- * @since 4.0.0
+ * Maps each RPC in an entity protocol to the handler function expected by
+ * `Entity.toLayer`.
+ *
+ * Each handler receives the entity request envelope for that RPC and returns the
+ * RPC result or a supported RPC wrapper.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type HandlersFrom<Rpc extends Rpc.Any> = {
   readonly [Current in Rpc as Current["_tag"]]: (
@@ -195,8 +241,12 @@ export type HandlersFrom<Rpc extends Rpc.Any> = {
 }
 
 /**
- * @since 4.0.0
+ * Returns `true` when the supplied value is a cluster `Entity`.
+ *
+ * The check is based on the internal entity type identifier.
+ *
  * @category refinements
+ * @since 4.0.0
  */
 export const isEntity = (u: unknown): u is Any => Predicate.hasProperty(u, TypeId)
 
@@ -362,8 +412,8 @@ const Proto = {
  * Creates a new `Entity` of the specified `type` which will accept messages
  * that adhere to the provided `RpcGroup`.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromRpcGroup = <const Type extends string, Rpcs extends Rpc.Any>(
   /**
@@ -387,8 +437,8 @@ export const fromRpcGroup = <const Type extends string, Rpcs extends Rpc.Any>(
  * Creates a new `Entity` of the specified `type` which will accept messages
  * that adhere to the provided schemas.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = <const Type extends string, Rpcs extends ReadonlyArray<Rpc.Any>>(
   /**
@@ -405,8 +455,8 @@ export const make = <const Type extends string, Rpcs extends ReadonlyArray<Rpc.A
 /**
  * A Context.Tag to access the current entity address.
  *
- * @since 4.0.0
  * @category context
+ * @since 4.0.0
  */
 export class CurrentAddress extends Context.Service<
   CurrentAddress,
@@ -416,8 +466,8 @@ export class CurrentAddress extends Context.Service<
 /**
  * A Context.Tag to access the current Runner address.
  *
- * @since 4.0.0
  * @category context
+ * @since 4.0.0
  */
 export class CurrentRunnerAddress extends Context.Service<
   CurrentRunnerAddress,
@@ -425,8 +475,13 @@ export class CurrentRunnerAddress extends Context.Service<
 >()("effect/cluster/Entity/RunnerAddress") {}
 
 /**
- * @since 4.0.0
+ * Reply API passed to queue-based entity handlers.
+ *
+ * Use it to complete an entity request by succeeding, failing, failing with a
+ * cause, or supplying an explicit `Exit`.
+ *
  * @category Replier
+ * @since 4.0.0
  */
 export interface Replier<Rpcs extends Rpc.Any> {
   readonly succeed: <R extends Rpcs>(
@@ -451,13 +506,19 @@ export interface Replier<Rpcs extends Rpc.Any> {
 }
 
 /**
+ * Helper types used by the `Replier` API.
+ *
  * @since 4.0.0
- * @category Replier
  */
 export declare namespace Replier {
   /**
-   * @since 4.0.0
+   * Success value accepted by a `Replier` for a single RPC.
+   *
+   * For streaming RPCs this may be either a stream of success chunks or a dequeue
+   * of success chunks. For non-streaming RPCs it is the RPC success value.
+   *
    * @category Replier
+   * @since 4.0.0
    */
   export type Success<R extends Rpc.Any> = Rpc.Success<R> extends Stream.Stream<infer _A, infer _E, infer _R> ?
     Stream.Stream<_A, _E | Rpc.Error<R>, _R> | Queue.Dequeue<_A, _E | Rpc.Error<R> | Cause.Done>
@@ -465,8 +526,13 @@ export declare namespace Replier {
 }
 
 /**
- * @since 4.0.0
+ * Entity request envelope delivered to entity handlers.
+ *
+ * It includes the underlying request envelope plus the last stream reply chunk
+ * that was sent, allowing handlers to resume chunk sequencing after a restart.
+ *
  * @category Request
+ * @since 4.0.0
  */
 export class Request<Rpc extends Rpc.Any> extends Data.Class<
   Envelope.Request<Rpc> & {
@@ -474,6 +540,8 @@ export class Request<Rpc extends Rpc.Any> extends Data.Class<
   }
 > {
   /**
+   * Most recent success chunk value sent by the entity, when one exists.
+   *
    * @since 4.0.0
    */
   get lastSentChunkValue(): Option.Option<Rpc.SuccessChunk<Rpc>> {
@@ -481,6 +549,8 @@ export class Request<Rpc extends Rpc.Any> extends Data.Class<
   }
 
   /**
+   * Sequence number to use for the entity's next outgoing success chunk.
+   *
    * @since 4.0.0
    */
   get nextSequence(): number {
@@ -494,8 +564,13 @@ export class Request<Rpc extends Rpc.Any> extends Data.Class<
 const shardingTag = Context.Service<Sharding, Sharding["Service"]>("effect/cluster/Sharding")
 
 /**
- * @since 4.0.0
+ * Builds an in-memory test client for an entity layer.
+ *
+ * The returned function creates a no-serialization RPC client for each entity ID,
+ * using a test sharding service instead of the cluster transport.
+ *
  * @category Testing
+ * @since 4.0.0
  */
 export const makeTestClient: <Type extends string, Rpcs extends Rpc.Any, LA, LE, LR>(
   entity: Entity<Type, Rpcs>,
@@ -596,8 +671,13 @@ export const makeTestClient: <Type extends string, Rpcs extends Rpc.Any, LA, LE,
 })
 
 /**
- * @since 4.0.0
+ * Enables or disables keep-alive for the current entity.
+ *
+ * When enabled it sends the internal keep-alive RPC for the current address; when
+ * disabled it releases the keep-alive latch if one is present.
+ *
  * @category Keep alive
+ * @since 4.0.0
  */
 export const keepAlive: (
   enabled: boolean
@@ -645,16 +725,26 @@ export const keepAlive: (
   ))
 
 /**
- * @since 4.0.0
+ * Internal persisted RPC used to keep an entity active while a resource is held.
+ *
+ * The RPC is marked as persisted and uninterruptible so the keep-alive signal
+ * survives normal entity restarts.
+ *
  * @category Keep alive
+ * @since 4.0.0
  */
 export const KeepAliveRpc = Rpc.make("Cluster/Entity/keepAlive")
   .annotate(Persisted, true)
   .annotate(Uninterruptible, true)
 
 /**
- * @since 4.0.0
+ * Service tag for the latch that coordinates entity keep-alive state.
+ *
+ * `keepAlive` closes the latch when keep-alive is active and opens it again when
+ * the resource no longer needs to keep the entity alive.
+ *
  * @category Keep alive
+ * @since 4.0.0
  */
 export class KeepAliveLatch extends Context.Service<KeepAliveLatch, Latch.Latch>()(
   "effect/cluster/Entity/KeepAliveLatch"

package/src/unstable/cluster/EntityAddress.ts

@@ -1,4 +1,22 @@
 /**
+ * The `EntityAddress` module defines the value used to locate an entity within
+ * a cluster. An address combines the entity type, entity id, and shard id so
+ * messages, persisted envelopes, workflow executions, and entity managers can
+ * agree on the same routing target.
+ *
+ * **Common tasks**
+ *
+ * - Build an address after resolving an entity id to a shard with `Sharding`
+ * - Attach an address to cluster envelopes and persisted messages
+ * - Compare or hash addresses when tracking active or resuming entities
+ *
+ * **Gotchas**
+ *
+ * - The shard id is part of the address identity; the same entity type and id
+ *   on a different shard is a different address.
+ * - Entity ids should be routed through the same shard group logic used by the
+ *   entity definition so messages are sent to the runner that owns the shard.
+ *
  * @since 4.0.0
  */
 import * as Equal from "../../Equal.ts"
@@ -13,8 +31,8 @@ const TypeId = "~effect/cluster/EntityAddress"
 /**
  * Represents the unique address of an entity within the cluster.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class EntityAddress extends Schema.Class<EntityAddress>(TypeId)({
   shardId: ShardId,
@@ -22,11 +40,15 @@ export class EntityAddress extends Schema.Class<EntityAddress>(TypeId)({
   entityId: EntityId
 }) {
   /**
+   * Marks this value as a cluster entity address for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [TypeId] = TypeId
 
   /**
+   * Formats the entity type, entity id, and shard id as a readable address.
+   *
    * @since 4.0.0
    */
   override toString() {
@@ -34,6 +56,8 @@ export class EntityAddress extends Schema.Class<EntityAddress>(TypeId)({
   }
 
   /**
+   * Compares entity addresses by entity type, entity id, and shard id.
+   *
    * @since 4.0.0
    */
   [Equal.symbol](that: EntityAddress): boolean {
@@ -42,6 +66,8 @@ export class EntityAddress extends Schema.Class<EntityAddress>(TypeId)({
   }
 
   /**
+   * Computes a structural hash from the entity type, entity id, and shard id.
+   *
    * @since 4.0.0
    */
   [Hash.symbol]() {
@@ -49,8 +75,10 @@ export class EntityAddress extends Schema.Class<EntityAddress>(TypeId)({
   }
 }
 /**
- * @since 4.0.0
+ * Constructs an `EntityAddress` from a shard ID, entity type, and entity ID.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = (options: {
   readonly shardId: ShardId

package/src/unstable/cluster/EntityId.ts

@@ -1,22 +1,37 @@
 /**
+ * The `EntityId` module provides a branded string identifier for addressing a
+ * specific entity instance inside the cluster. Entity ids are commonly used as
+ * stable routing keys when sending messages to an entity, looking up its state,
+ * or deriving the shard responsible for that entity.
+ *
+ * Because routing is based on the exact string value, choose ids that are
+ * deterministic, normalized, and unique within the entity type you are
+ * addressing. Avoid display names or other values that may change over time.
+ *
  * @since 4.0.0
  */
 import * as Schema from "../../Schema.ts"
 
 /**
- * @since 4.0.0
+ * Schema for branded string entity identifiers used inside the cluster.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const EntityId = Schema.String.pipe(Schema.brand("~effect/cluster/EntityId"))
 
 /**
- * @since 4.0.0
+ * Branded string type representing the ID of an entity instance.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type EntityId = typeof EntityId.Type
 
 /**
- * @since 4.0.0
+ * Brands a string as an `EntityId`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = (id: string): EntityId => id as EntityId