effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/unstable/cluster/MessageStorage.ts

@@ -51,6 +51,8 @@ import * as Snowflake from "./Snowflake.ts"
 /**
  * Service for cluster mailbox persistence and reply delivery.
  *
+ * **Details**
+ *
  * It stores outgoing requests, control envelopes, and replies; reads unprocessed
  * messages; manages reply handlers; and provides transaction wrapping for storage
  * operations.
@@ -88,8 +90,12 @@ export class MessageStorage extends Context.Service<MessageStorage, {
   /**
    * Retrieves the replies for the specified requests.
    *
+   * **Details**
+   *
+   * This returns:
+   *
    * - Un-acknowledged chunk replies
-   * - WithExit replies
+   * - `WithExit` replies
    */
   readonly repliesFor: <R extends Rpc.Any>(
     requests: Iterable<Message.OutgoingRequest<R>>
@@ -133,12 +139,13 @@ export class MessageStorage extends Context.Service<MessageStorage, {
   /**
    * Retrieves the unprocessed messages for the specified shards.
    *
+   * **Details**
+   *
    * A message is unprocessed when:
    *
-   * - Requests that have no WithExit replies
-   *   - Or they have no unacknowledged chunk replies
-   * - The latest AckChunk envelope
-   * - All Interrupt's for unprocessed requests
+   * - Requests that have no `WithExit` replies or no unacknowledged chunk replies
+   * - The latest `AckChunk` envelope
+   * - All `Interrupt` envelopes for unprocessed requests
    */
   readonly unprocessedMessages: (
     shardIds: Iterable<ShardId.ShardId>
@@ -183,6 +190,8 @@ export class MessageStorage extends Context.Service<MessageStorage, {
 /**
  * Result of saving a request or envelope into message storage.
  *
+ * **Details**
+ *
  * A duplicate result carries the original request ID and the last reply already
  * received for the duplicated request.
  *
@@ -217,6 +226,8 @@ export declare namespace SaveResult {
   /**
    * Encoded storage-driver form of `SaveResult`.
    *
+   * **Details**
+   *
    * Duplicate results contain an encoded last received reply instead of a decoded
    * reply.
    *
@@ -238,6 +249,8 @@ export declare namespace SaveResult {
   /**
    * Variant indicating that the request duplicates an existing stored request.
    *
+   * **Details**
+   *
    * It carries the original request ID and the latest decoded reply, when one is
    * available.
    *
@@ -253,6 +266,8 @@ export declare namespace SaveResult {
   /**
    * Encoded duplicate-save variant returned by lower-level storage drivers.
    *
+   * **Details**
+   *
    * It carries the original request ID and the latest encoded reply, when one is
    * available.
    *
@@ -279,6 +294,8 @@ export declare namespace SaveResult {
 /**
  * Low-level storage-driver contract for encoded envelopes and replies.
  *
+ * **Details**
+ *
  * Implementations persist encoded messages, track primary keys and delayed
  * delivery, read unprocessed messages, and provide transaction wrapping.
  *
@@ -317,8 +334,12 @@ export type Encoded = {
   /**
    * Retrieves the replies for the specified requests.
    *
+   * **Details**
+   *
+   * This returns:
+   *
    * - Un-acknowledged chunk replies
-   * - WithExit replies
+   * - `WithExit` replies
    */
   readonly repliesFor: (requestIds: Arr.NonEmptyArray<string>) => Effect.Effect<
     Array<Reply.Encoded>,
@@ -336,12 +357,13 @@ export type Encoded = {
   /**
    * Retrieves the unprocessed messages for the given shards.
    *
+   * **Details**
+   *
    * A message is unprocessed when:
    *
-   * - Requests that have no WithExit replies
-   *   - Or they have no unacknowledged chunk replies
-   * - The latest AckChunk envelope
-   * - All Interrupt's for unprocessed requests
+   * - Requests that have no `WithExit` replies or no unacknowledged chunk replies
+   * - The latest `AckChunk` envelope
+   * - All `Interrupt` envelopes for unprocessed requests
    */
   readonly unprocessedMessages: (
     shardIds: Arr.NonEmptyArray<string>,
@@ -400,6 +422,8 @@ export type Encoded = {
 /**
  * Cursor options for reading encoded unprocessed messages across shard sets.
  *
+ * **Details**
+ *
  * The fields distinguish existing shards from newly assigned shards and carry the
  * driver-specific pagination cursor.
  *
@@ -415,6 +439,8 @@ export type EncodedUnprocessedOptions<A> = {
 /**
  * Cursor options for reading encoded replies across request sets.
  *
+ * **Details**
+ *
  * The fields distinguish existing requests from new requests and carry the
  * driver-specific pagination cursor.
  *
@@ -430,6 +456,8 @@ export type EncodedRepliesOptions<A> = {
 /**
  * Wraps a concrete message storage implementation with reply-handler management.
  *
+ * **Details**
+ *
  * The returned service can register waiting reply handlers, notify them when
  * replies are saved, and fail them when a request or shard is unregistered.
  *
@@ -537,6 +565,8 @@ export const make = (
 /**
  * Builds a `MessageStorage` service from an encoded storage driver.
  *
+ * **Details**
+ *
  * The adapter handles envelope and reply encoding and decoding, primary-key
  * generation, delayed delivery checks, duplicate decoding, and malformed-message
  * defect replies.
@@ -773,6 +803,8 @@ export const noop: MessageStorage["Service"] = Effect.runSync(make({
 /**
  * In-memory storage entry for a request envelope.
  *
+ * **Details**
+ *
  * It stores the encoded envelope, last acknowledged chunk, accumulated replies,
  * and optional delivery time.
  *
@@ -799,6 +831,8 @@ export const MemoryTransaction = Context.Reference<boolean>("effect/cluster/Mess
 /**
  * In-memory message storage driver with inspectable backing state.
  *
+ * **Details**
+ *
  * It provides a `MessageStorage` service, the encoded driver implementation, and
  * maps used to track requests, primary keys, unprocessed envelopes, reply IDs,
  * and the journal.

package/src/unstable/cluster/Reply.ts

@@ -43,9 +43,8 @@ import { Snowflake, SnowflakeFromBigInt } from "./Snowflake.ts"
 const TypeId = "~effect/cluster/Reply"
 
 /**
- * Returns `true` when the supplied value is a runtime cluster reply.
- *
- * The check is based on the reply type identifier.
+ * Returns `true` when the supplied value is a runtime cluster reply, based on the
+ * reply type identifier.
  *
  * @category guards
  * @since 4.0.0
@@ -53,9 +52,8 @@ const TypeId = "~effect/cluster/Reply"
 export const isReply = (u: unknown): u is Reply<Rpc.Any> => hasProperty(u, TypeId)
 
 /**
- * Runtime reply sent for an RPC request.
- *
- * A reply is either a final exit or a chunk of a streaming success value.
+ * Runtime reply sent for an RPC request, either as a final exit or a chunk of a
+ * streaming success value.
  *
  * @category models
  * @since 4.0.0
@@ -73,6 +71,8 @@ export type Encoded = WithExitEncoded | ChunkEncoded
 /**
  * Codec used for reply values that are already in encoded form.
  *
+ * **Details**
+ *
  * Per-RPC payload validation is performed by `Reply(rpc)`.
  *
  * @category models

package/src/unstable/cluster/Runner.ts

@@ -36,6 +36,8 @@ const TypeId = "~effect/cluster/Runner"
 /**
  * A cluster runner that can host entities.
  *
+ * **Details**
+ *
  * Each runner has a unique network `address`, the shard `groups` it participates
  * in, and a relative `weight` used when assigning shards across runners.
  *

package/src/unstable/cluster/RunnerHealth.ts

@@ -33,6 +33,8 @@ import * as Runners from "./Runners.ts"
 /**
  * Represents the service used to check if a Runner is healthy.
  *
+ * **Details**
+ *
  * If a Runner is responsive, shards will not be re-assigned because the Runner may
  * still be processing messages. If a Runner is not responsive, then its
  * associated shards can and will be re-assigned to a different Runner.
@@ -50,6 +52,8 @@ export class RunnerHealth extends Context.Service<
 /**
  * A layer which will **always** consider a Runner healthy.
  *
+ * **When to use**
+ *
  * This is useful for testing.
  *
  * @category layers
@@ -102,6 +106,8 @@ export const layerPing: Layer.Layer<
  * Creates a `RunnerHealth` service that checks Kubernetes pod readiness for a
  * runner host, optionally scoped by namespace and label selector.
  *
+ * **Gotchas**
+ *
  * If the Kubernetes API check fails, the runner is treated as healthy.
  *
  * @category constructors
@@ -126,9 +132,14 @@ export const makeK8s = Effect.fnUntraced(function*(options?: {
  * A layer which checks Kubernetes pod readiness to determine whether a runner is
  * healthy.
  *
+ * **Details**
+ *
  * The provided `HttpClient` must trust the pod CA certificate and the pod service
- * account must be allowed to list pods. If the Kubernetes API check fails, the
- * runner is treated as healthy.
+ * account must be allowed to list pods.
+ *
+ * **Gotchas**
+ *
+ * If the Kubernetes API check fails, the runner is treated as healthy.
  *
  * @category layers
  * @since 4.0.0

package/src/unstable/cluster/RunnerServer.ts

@@ -156,10 +156,9 @@ export const layerHandlers = Runners.Rpcs.toLayer(Effect.gen(function*() {
 const constWaitUntilRead = { waitUntilRead: true } as const
 
 /**
- * The `RunnerServer` recieves messages from other Runners and forwards them to the
- * `Sharding` layer.
- *
- * It also responds to `Ping` requests.
+ * Creates the runner RPC server layer, which receives messages from other
+ * runners, forwards them to the `Sharding` layer, and responds to `Ping`
+ * requests.
  *
  * @category layers
  * @since 4.0.0
@@ -194,11 +193,12 @@ export const layerWithClients: Layer.Layer<
 )
 
 /**
- * A `Runners` layer that is client only.
+ * Creates a client-only `Runners` layer.
+ *
+ * **When to use**
  *
- * It will not register with the ShardManager and recieve shard assignments,
- * so this layer can be used to embed a cluster client inside another effect
- * application.
+ * Use this layer to embed a cluster client inside another Effect application
+ * without registering with the ShardManager or receiving shard assignments.
  *
  * @category layers
  * @since 4.0.0

package/src/unstable/cluster/RunnerStorage.ts

@@ -208,6 +208,8 @@ export const makeEncoded = (encoded: Encoded) =>
 /**
  * Creates an in-memory `RunnerStorage` implementation for tests and local use.
  *
+ * **Details**
+ *
  * Registered runners are treated as healthy and shard acquisition is kept only in
  * process memory.
  *

package/src/unstable/cluster/ShardId.ts

@@ -132,6 +132,8 @@ export const toString = (shardId: {
 /**
  * Parses a `group:id` string into plain shard id parts.
  *
+ * **Details**
+ *
  * Throws an `Error` when the string has no colon separator or the id segment is
  * not numeric.
  *
@@ -157,6 +159,8 @@ export function fromStringEncoded(s: string): {
 /**
  * Parses a `group:id` string into a cached `ShardId`.
  *
+ * **Details**
+ *
  * Throws an `Error` when the string has no colon separator or the id segment is
  * not numeric.
  *

package/src/unstable/cluster/Snowflake.ts

@@ -210,6 +210,8 @@ export const toParts = (snowflake: Snowflake): Snowflake.Parts => ({
 /**
  * Creates a stateful snowflake generator using `Clock`.
  *
+ * **Details**
+ *
  * The generator starts with a random machine id, never moves generated timestamps
  * backward, resets the sequence each millisecond, and advances the timestamp when
  * more than 4096 ids are requested in the same millisecond.

package/src/unstable/cluster/TestRunner.ts

@@ -29,8 +29,9 @@ import * as ShardingConfig from "./ShardingConfig.ts"
 /**
  * An in-memory cluster that can be used for testing purposes.
  *
- * MessageStorage is backed by an in-memory driver, and RunnerStorage is backed
- * by an in-memory driver.
+ * **Details**
+ *
+ * `MessageStorage` and `RunnerStorage` are backed by in-memory drivers.
  *
  * @category layers
  * @since 4.0.0

package/src/unstable/devtools/DevToolsSchema.ts

@@ -297,6 +297,8 @@ export const Counter = metric(
 /**
  * Type of a devtools counter metric snapshot.
  *
+ * **Details**
+ *
  * The state contains the current count and whether the counter reports
  * incremental updates.
  *
@@ -308,6 +310,8 @@ export type Counter = Schema.Schema.Type<typeof Counter>
 /**
  * Schema for a devtools frequency metric snapshot.
  *
+ * **Details**
+ *
  * The metric state records occurrence counts by string key.
  *
  * @category schemas
@@ -323,6 +327,8 @@ export const Frequency = metric(
 /**
  * Type of a devtools frequency metric snapshot.
  *
+ * **Details**
+ *
  * The state maps observed string values to occurrence counts.
  *
  * @category schemas
@@ -333,6 +339,8 @@ export type Frequency = Schema.Schema.Type<typeof Frequency>
 /**
  * Schema for a devtools gauge metric snapshot.
  *
+ * **Details**
+ *
  * The metric state contains the current numeric or bigint value.
  *
  * @category schemas
@@ -348,6 +356,8 @@ export const Gauge = metric(
 /**
  * Type of a devtools gauge metric snapshot.
  *
+ * **Details**
+ *
  * The state contains the current numeric or bigint value.
  *
  * @category schemas
@@ -358,6 +368,8 @@ export type Gauge = Schema.Schema.Type<typeof Gauge>
 /**
  * Schema for a devtools histogram metric snapshot.
  *
+ * **Details**
+ *
  * The metric state includes bucket counts plus the total count, minimum,
  * maximum, and sum.
  *
@@ -378,6 +390,8 @@ export const Histogram = metric(
 /**
  * Type of a devtools histogram metric snapshot.
  *
+ * **Details**
+ *
  * The state includes bucket counts plus the total count, minimum, maximum, and
  * sum.
  *
@@ -389,6 +403,8 @@ export type Histogram = Schema.Schema.Type<typeof Histogram>
 /**
  * Schema for a devtools summary metric snapshot.
  *
+ * **Details**
+ *
  * The metric state contains quantile values plus the total count, minimum,
  * maximum, and sum.
  *
@@ -409,6 +425,8 @@ export const Summary = metric(
 /**
  * Type of a devtools summary metric snapshot.
  *
+ * **Details**
+ *
  * The state contains quantile values plus the total count, minimum, maximum,
  * and sum.
  *
@@ -420,6 +438,8 @@ export type Summary = Schema.Schema.Type<typeof Summary>
 /**
  * Schema for any devtools metric snapshot.
  *
+ * **Details**
+ *
  * Accepted metric kinds are counters, frequencies, gauges, histograms, and
  * summaries.
  *
@@ -431,6 +451,8 @@ export const Metric = Schema.Union([Counter, Frequency, Gauge, Histogram, Summar
 /**
  * Type of any devtools metric snapshot.
  *
+ * **Details**
+ *
  * The union covers counters, frequencies, gauges, histograms, and summaries.
  *
  * @category schemas
@@ -461,6 +483,8 @@ export type MetricsSnapshot = Schema.Schema.Type<typeof MetricsSnapshot>
 /**
  * Schema for devtools protocol requests accepted by the server.
  *
+ * **Details**
+ *
  * Requests include heartbeat pings, spans, span events, and metric snapshots.
  *
  * @category schemas
@@ -471,6 +495,8 @@ export const Request = Schema.Union([Ping, Span, SpanEvent, MetricsSnapshot])
 /**
  * Type of devtools protocol requests accepted by the server.
  *
+ * **Details**
+ *
  * Requests include heartbeat pings, spans, span events, and metric snapshots.
  *
  * @category schemas
@@ -487,10 +513,11 @@ export declare namespace Request {
   /**
    * Devtools request messages excluding heartbeat pings.
    *
+   * **Details**
+   *
    * `DevToolsServer` handles `Ping` internally and exposes only these requests
    * to client handlers.
    *
-   * @category schemas
    * @since 4.0.0
    */
   export type WithoutPing = Exclude<Request, { readonly _tag: "Ping" }>
@@ -499,6 +526,8 @@ export declare namespace Request {
 /**
  * Schema for devtools protocol responses sent by the server.
  *
+ * **Details**
+ *
  * Responses include heartbeat pongs and requests for metric snapshots.
  *
  * @category schemas
@@ -509,6 +538,8 @@ export const Response = Schema.Union([Pong, MetricsRequest])
 /**
  * Type of devtools protocol responses sent by the server.
  *
+ * **Details**
+ *
  * Responses include heartbeat pongs and requests for metric snapshots.
  *
  * @category schemas
@@ -525,10 +556,11 @@ export declare namespace Response {
   /**
    * Devtools response messages excluding heartbeat pongs.
    *
+   * **Details**
+   *
    * `DevToolsServer` sends `Pong` internally and accepts only these responses
    * from client handlers.
    *
-   * @category schemas
    * @since 4.0.0
    */
   export type WithoutPong = Exclude<Response, { readonly _tag: "Pong" }>

package/src/unstable/devtools/DevToolsServer.ts

@@ -30,6 +30,8 @@ const ResponseSchema = Schema.toCodecJson(DevToolsSchema.Response)
 /**
  * Handle for a connected devtools client.
  *
+ * **Details**
+ *
  * It exposes a queue of non-ping requests received from the socket and a
  * `send` function for non-pong responses.
  *
@@ -44,6 +46,8 @@ export interface Client {
 /**
  * Runs the devtools socket server.
  *
+ * **Details**
+ *
  * Each connection is decoded as NDJSON devtools protocol messages, `Ping`
  * requests are answered with `Pong`, and all other requests are delivered
  * through the `Client` passed to the handler.

package/src/unstable/encoding/Msgpack.ts

@@ -37,6 +37,8 @@ const MsgPackErrorTypeId = "~effect/encoding/MsgPack/MsgPackError"
 /**
  * Error raised when MessagePack encoding or decoding fails.
  *
+ * **Details**
+ *
  * The `kind` field identifies whether the failure happened while packing or
  * unpacking, and `cause` preserves the original error.
  *
@@ -68,6 +70,8 @@ export class MsgPackError extends Data.TaggedError("MsgPackError")<{
  * Creates a channel that encodes non-empty chunks of values as MessagePack byte
  * arrays.
  *
+ * **Details**
+ *
  * The channel fails with `MsgPackError` when any value cannot be packed.
  *
  * @category constructors
@@ -97,6 +101,8 @@ export const encode = <IE = never, Done = unknown>(): Channel.Channel<
 /**
  * Creates a MessagePack encoder channel for values of a schema.
  *
+ * **Details**
+ *
  * Values are first encoded with the schema and then packed as MessagePack bytes,
  * so the channel can fail with either schema errors or `MsgPackError`.
  *
@@ -119,6 +125,8 @@ export const encodeSchema = <S extends Schema.Top>(
 /**
  * Creates a channel that decodes MessagePack byte chunks into values.
  *
+ * **Details**
+ *
  * Incomplete frames are buffered across chunks, and invalid MessagePack data
  * fails with `MsgPackError`.
  *
@@ -173,6 +181,8 @@ export const decode = <IE = never, Done = unknown>(): Channel.Channel<
 /**
  * Creates a MessagePack decoder channel for values of a schema.
  *
+ * **Details**
+ *
  * The channel unpacks bytes into unknown values and then decodes each value with
  * the schema.
  *
@@ -195,6 +205,8 @@ export const decodeSchema = <S extends Schema.Top>(
 /**
  * Wraps a bidirectional byte channel with MessagePack encoding and decoding.
  *
+ * **Details**
+ *
  * Outgoing values are packed as MessagePack bytes before reaching the wrapped
  * channel, and incoming bytes are unpacked into values.
  *
@@ -229,6 +241,8 @@ export const duplex = <R, IE, OE, OutDone, InDone>(
  * Wraps a bidirectional byte channel with schema-aware MessagePack encoding and
  * decoding.
  *
+ * **Details**
+ *
  * Values sent to the wrapped channel are encoded with `inputSchema` and packed
  * as MessagePack bytes; bytes received from it are unpacked and decoded with
  * `outputSchema`.
@@ -241,6 +255,8 @@ export const duplexSchema: {
    * Wraps a bidirectional byte channel with schema-aware MessagePack encoding and
    * decoding.
    *
+   * **Details**
+   *
    * Values sent to the wrapped channel are encoded with `inputSchema` and packed
    * as MessagePack bytes; bytes received from it are unpacked and decoded with
    * `outputSchema`.
@@ -276,6 +292,8 @@ export const duplexSchema: {
    * Wraps a bidirectional byte channel with schema-aware MessagePack encoding and
    * decoding.
    *
+   * **Details**
+   *
    * Values sent to the wrapped channel are encoded with `inputSchema` and packed
    * as MessagePack bytes; bytes received from it are unpacked and decoded with
    * `outputSchema`.
@@ -333,6 +351,8 @@ export const duplexSchema: {
 /**
  * Schema type for values encoded as MessagePack bytes.
  *
+ * **Details**
+ *
  * It decodes a `Uint8Array` MessagePack payload to the target schema type and
  * encodes the target type back to bytes.
  *
@@ -344,6 +364,8 @@ export interface schema<S extends Schema.Top> extends Schema.decodeTo<S, Schema.
 /**
  * Schema transformation between MessagePack bytes and decoded values.
  *
+ * **Details**
+ *
  * MessagePack codec failures are converted to `InvalidValue` schema issues.
  *
  * @category schemas
@@ -380,6 +402,8 @@ export const transformation: Transformation.Transformation<
 /**
  * Builds a schema that stores values as MessagePack bytes.
  *
+ * **Details**
+ *
  * The resulting schema decodes `Uint8Array` payloads with MessagePack and the
  * provided schema, and encodes values back to MessagePack bytes.
  *