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

package/src/unstable/cli/internal/parser.ts

@@ -620,7 +620,14 @@ const resolveFirstValue = (
   // Not a subcommand. Check if this looks like a typo.
   const expectsArgs = toImpl(command).config.arguments.length > 0
   if (!expectsArgs && subIndex.size > 0) {
-    const suggestions = suggest(value, Array.from(subIndex.keys()))
+    // Exclude hidden subcommands so a typo cannot reveal a subcommand name
+    // that was intentionally kept out of --help. Hidden commands still
+    // resolve via subIndex when invoked by exact name.
+    const visibleKeys: Array<string> = []
+    for (const [key, sub] of subIndex) {
+      if (!sub.hidden) visibleKeys.push(key)
+    }
+    const suggestions = suggest(value, visibleKeys)
     state.errors.push(
       new CliError.UnknownSubcommand({
         subcommand: value,

package/src/unstable/cluster/ClusterCron.ts

@@ -51,6 +51,8 @@ import * as Singleton from "./Singleton.ts"
 /**
  * Creates a layer that runs a cron job through the cluster sharding system.
  *
+ * **Details**
+ *
  * The job is scheduled as persisted entity messages, with an initial singleton
  * scheduling step and optional controls for shard group, next-run calculation,
  * and skipping stale scheduled runs.
@@ -69,7 +71,10 @@ export const make = <E, R>(options: {
   readonly shardGroup?: string | undefined
 
   /**
-   * Whether to run the next cron job based from the time of the previous run.
+   * Controls whether the next cron job is based on the time of the previous
+   * run.
+   *
+   * **Details**
    *
    * Defaults to `false`, meaning the next run will be calculated from the
    * current time.
@@ -80,9 +85,13 @@ export const make = <E, R>(options: {
    * If set, the cron job will skip execution if the scheduled time is older
    * than this duration.
    *
+   * **When to use**
+   *
    * This is useful to prevent running jobs that were scheduled too far in the
    * past.
    *
+   * **Details**
+   *
    * Defaults to "1 day".
    */
   readonly skipIfOlderThan?: Duration.Input | undefined

package/src/unstable/cluster/ClusterSchema.ts

@@ -37,6 +37,8 @@ import type { Request } from "./Envelope.ts"
  * Annotation that marks whether a cluster request should be persisted in mailbox
  * storage.
  *
+ * **Details**
+ *
  * The default value is `false`.
  *
  * @category annotations
@@ -62,6 +64,8 @@ export const WithTransaction = Context.Reference<boolean>(
  * Annotation that controls whether a cluster request is treated as
  * uninterruptible.
  *
+ * **Details**
+ *
  * 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.
@@ -101,6 +105,8 @@ export const isUninterruptibleForClient = (context: Context.Context<never>): boo
 /**
  * Annotation that selects the shard group for an entity id.
  *
+ * **Details**
+ *
  * By default, every entity id is assigned to the `"default"` shard group.
  *
  * @category annotations
@@ -115,6 +121,8 @@ export const ShardGroup = Context.Reference<(entityId: EntityId) => string>(
  * Annotation that controls whether client-side cluster request tracing is
  * enabled.
  *
+ * **Details**
+ *
  * The default value is `true`.
  *
  * @category annotations

package/src/unstable/cluster/ClusterWorkflowEngine.ts

@@ -62,6 +62,8 @@ import * as Snowflake from "./Snowflake.ts"
  * Creates a `WorkflowEngine` implementation backed by cluster sharding and
  * message storage.
  *
+ * **Details**
+ *
  * Workflow executions, activities, deferred completions, resumes, interrupts,
  * and durable clock wakeups are coordinated through persisted cluster entities.
  *
@@ -723,6 +725,8 @@ const InterruptSignal = DurableDeferred.make("Workflow/InterruptSignal")
  * Layer that provides `WorkflowEngine.WorkflowEngine` using the cluster workflow
  * engine implementation.
  *
+ * **Details**
+ *
  * It requires cluster sharding and message storage, and also registers the
  * durable clock entity used for workflow wakeups.
  *

package/src/unstable/cluster/DeliverAt.ts

@@ -35,10 +35,9 @@ import { hasProperty } from "../../Predicate.ts"
 export const symbol = "~effect/cluster/DeliverAt"
 
 /**
- * Interface for payloads that specify when a cluster message should be delivered.
- *
- * Implementations return the target delivery `DateTime` through the `DeliverAt`
- * symbol method.
+ * Interface for payloads that specify when a cluster message should be delivered
+ * by returning the target delivery `DateTime` through the `DeliverAt` symbol
+ * method.
  *
  * @category models
  * @since 4.0.0

package/src/unstable/cluster/Entity.ts

@@ -78,6 +78,8 @@ const TypeId = "~effect/cluster/Entity"
 /**
  * Represents a cluster entity type and the RPC protocol it can handle.
  *
+ * **Details**
+ *
  * 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.
  *
@@ -147,6 +149,8 @@ export interface Entity<
   /**
    * Create a Layer from an Entity.
    *
+   * **Details**
+   *
    * It will register the entity with the Sharding service.
    */
   toLayer<
@@ -178,6 +182,8 @@ export interface Entity<
   /**
    * Create a Layer from an Entity.
    *
+   * **Details**
+   *
    * It will register the entity with the Sharding service.
    */
   toLayerQueue<
@@ -228,6 +234,8 @@ export type Any = Entity<string, Rpc.Any>
  * Maps each RPC in an entity protocol to the handler function expected by
  * `Entity.toLayer`.
  *
+ * **Details**
+ *
  * Each handler receives the entity request envelope for that RPC and returns the
  * RPC result or a supported RPC wrapper.
  *
@@ -243,6 +251,8 @@ export type HandlersFrom<Rpc extends Rpc.Any> = {
 /**
  * Returns `true` when the supplied value is a cluster `Entity`.
  *
+ * **Details**
+ *
  * The check is based on the internal entity type identifier.
  *
  * @category refinements
@@ -477,6 +487,8 @@ export class CurrentRunnerAddress extends Context.Service<
 /**
  * Reply API passed to queue-based entity handlers.
  *
+ * **When to use**
+ *
  * Use it to complete an entity request by succeeding, failing, failing with a
  * cause, or supplying an explicit `Exit`.
  *
@@ -514,6 +526,8 @@ export declare namespace Replier {
   /**
    * Success value accepted by a `Replier` for a single RPC.
    *
+   * **Details**
+   *
    * 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.
    *
@@ -528,6 +542,8 @@ export declare namespace Replier {
 /**
  * Entity request envelope delivered to entity handlers.
  *
+ * **Details**
+ *
  * It includes the underlying request envelope plus the last stream reply chunk
  * that was sent, allowing handlers to resume chunk sequencing after a restart.
  *
@@ -566,6 +582,8 @@ const shardingTag = Context.Service<Sharding, Sharding["Service"]>("effect/clust
 /**
  * Builds an in-memory test client for an entity layer.
  *
+ * **Details**
+ *
  * The returned function creates a no-serialization RPC client for each entity ID,
  * using a test sharding service instead of the cluster transport.
  *
@@ -673,6 +691,8 @@ export const makeTestClient: <Type extends string, Rpcs extends Rpc.Any, LA, LE,
 /**
  * Enables or disables keep-alive for the current entity.
  *
+ * **Details**
+ *
  * 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.
  *
@@ -727,6 +747,8 @@ export const keepAlive: (
 /**
  * Internal persisted RPC used to keep an entity active while a resource is held.
  *
+ * **Details**
+ *
  * The RPC is marked as persisted and uninterruptible so the keep-alive signal
  * survives normal entity restarts.
  *
@@ -740,6 +762,8 @@ export const KeepAliveRpc = Rpc.make("Cluster/Entity/keepAlive")
 /**
  * Service tag for the latch that coordinates entity keep-alive state.
  *
+ * **Details**
+ *
  * `keepAlive` closes the latch when keep-alive is active and opens it again when
  * the resource no longer needs to keep the entity alive.
  *

package/src/unstable/cluster/EntityProxy.ts

@@ -103,8 +103,11 @@ export const toRpcGroup = <Type extends string, Rpcs extends Rpc.Any>(
 /**
  * Type-level conversion used by `toRpcGroup`.
  *
- * For each entity RPC it creates a prefixed request RPC and a discard RPC whose
- * payload includes `entityId`, and whose errors include cluster client errors.
+ * **Details**
+ *
+ * For each entity RPC, this creates a prefixed request RPC and a discard RPC
+ * whose payload includes `entityId`, and whose errors include cluster client
+ * errors.
  *
  * @category converting
  * @since 4.0.0
@@ -229,8 +232,11 @@ const tagToPath = (tag: string): string =>
 /**
  * Type-level conversion used by `toHttpApiGroup`.
  *
- * For each entity RPC it creates a POST endpoint at `/<tag>/:entityId` and a
- * discard endpoint at `/<tag>/:entityId/discard`, including cluster client errors.
+ * **Details**
+ *
+ * For each entity RPC, this creates a POST endpoint at `/<tag>/:entityId` and a
+ * discard endpoint at `/<tag>/:entityId/discard`, including cluster client
+ * errors.
  *
  * @category converting
  * @since 4.0.0

package/src/unstable/cluster/EntityProxyServer.ts

@@ -35,6 +35,8 @@ import type { Sharding } from "./Sharding.ts"
 /**
  * Creates HTTP API handlers for an entity proxy group.
  *
+ * **Details**
+ *
  * Each generated endpoint reads the `entityId` path parameter and forwards the
  * request payload to the corresponding entity client method, including discard
  * endpoints.
@@ -101,6 +103,8 @@ export const layerHttpApi = <
 /**
  * Creates RPC handlers for the group produced by `EntityProxy.toRpcGroup`.
  *
+ * **Details**
+ *
  * The handlers forward each prefixed proxy RPC to the target entity client using
  * the `entityId` embedded in the proxy payload.
  *
@@ -139,6 +143,8 @@ export const layerRpcHandlers = <
 /**
  * Union of RPC handler services required to serve the proxy RPCs for an entity.
  *
+ * **Details**
+ *
  * Includes both the normal prefixed RPC handler and its discard variant.
  *
  * @category services

package/src/unstable/cluster/EntityResource.ts

@@ -54,6 +54,8 @@ export type TypeId = "~effect/cluster/EntityResource"
 /**
  * A resource acquired inside a cluster entity and kept alive across restarts.
  *
+ * **Details**
+ *
  * `get` acquires or reuses the resource in the caller's scope, while `close`
  * invalidates it so its close scope can be released.
  *
@@ -69,6 +71,8 @@ export interface EntityResource<out A, out E = never> {
 /**
  * A `Scope` that is only closed when the resource is explicitly closed.
  *
+ * **Gotchas**
+ *
  * It is not closed during restarts, due to shard movement or node shutdowns.
  *
  * @category Scope
@@ -83,9 +87,13 @@ export class CloseScope extends Context.Service<
  * A `EntityResource` is a resource that can be acquired inside a cluster
  * entity, which will keep the entity alive even across restarts.
  *
+ * **Details**
+ *
  * The resource will only be fully released when the idle time to live is
  * reached, or when the `close` effect is called.
  *
+ * **Gotchas**
+ *
  * By default, the `idleTimeToLive` is infinite, meaning the resource will only
  * be released when `close` is called.
  *
@@ -144,6 +152,8 @@ export const make: <A, E, R>(options: {
 /**
  * Creates an `EntityResource` backed by a Kubernetes Pod.
  *
+ * **Details**
+ *
  * The pod is created and waited on through `K8sHttpClient`, and is kept alive
  * until the resource is closed or its idle time to live expires.
  *

package/src/unstable/cluster/Envelope.ts

@@ -45,6 +45,8 @@ export const TypeId = "~effect/cluster/Envelope"
 /**
  * Union of cluster envelopes exchanged for an RPC request.
  *
+ * **Details**
+ *
  * An envelope is either a request, an acknowledgement for a streamed reply chunk,
  * or an interrupt signal.
  *
@@ -79,6 +81,8 @@ export declare namespace Envelope {
 /**
  * Runtime envelope for an RPC request addressed to a specific entity.
  *
+ * **Details**
+ *
  * It carries the request ID, entity address, RPC tag, decoded payload, request
  * headers, and optional tracing context.
  *
@@ -101,6 +105,8 @@ export interface Request<in out Rpc extends Rpc.Any> {
 /**
  * Schema for a request envelope before its RPC payload has been decoded.
  *
+ * **Details**
+ *
  * The envelope metadata is decoded, while the payload remains `unknown` until it
  * is decoded with the target RPC payload schema.
  *
@@ -122,6 +128,8 @@ export class PartialRequest extends Schema.Opaque<PartialRequest>()(Schema.Struc
 /**
  * Serialized JSON shape of a request envelope.
  *
+ * **Details**
+ *
  * Identifiers are encoded as strings and the RPC payload remains unknown until
  * decoded with the RPC schema.
  *
@@ -150,6 +158,8 @@ export interface PartialRequestEncoded {
 /**
  * Envelope acknowledging receipt of a streamed reply chunk for a request.
  *
+ * **Details**
+ *
  * The `replyId` identifies the chunk reply that has been received.
  *
  * @category models
@@ -258,6 +268,8 @@ export interface InterruptEncoded {
 /**
  * Schema union for partially decoded cluster envelopes.
  *
+ * **Details**
+ *
  * It accepts `PartialRequest`, `AckChunk`, and `Interrupt` envelope values.
  *
  * @category schemas
@@ -318,6 +330,8 @@ export declare namespace Request {
 /**
  * Returns `true` when the supplied value is a runtime cluster envelope.
  *
+ * **Details**
+ *
  * The check is based on the envelope type identifier.
  *
  * @category refinements
@@ -328,6 +342,8 @@ export const isEnvelope = (u: unknown): u is Envelope<any> => Predicate.hasPrope
 /**
  * Constructs a runtime request envelope and attaches the envelope type identifier.
  *
+ * **Details**
+ *
  * Tracing fields are included only when a `traceId` is provided.
  *
  * @category constructors

package/src/unstable/cluster/HttpRunner.ts

@@ -50,6 +50,8 @@ import type * as ShardingConfig from "./ShardingConfig.ts"
  * Provides a runner RPC client protocol that connects to runner addresses over
  * HTTP.
  *
+ * **Details**
+ *
  * The configured path is appended to each runner address, and `https` switches
  * the generated URL from `http` to `https`.
  *
@@ -97,6 +99,8 @@ export const layerClientProtocolHttpDefault: Layer.Layer<
  * Provides a runner RPC client protocol that connects to runner addresses over
  * WebSocket.
  *
+ * **Details**
+ *
  * The configured path is appended to each runner address, and `https` switches
  * the generated URL from `ws` to `wss`.
  *
@@ -145,6 +149,8 @@ export const layerClientProtocolWebsocketDefault: Layer.Layer<
 /**
  * Builds an HTTP effect that serves runner RPCs over the HTTP protocol.
  *
+ * **Details**
+ *
  * The returned effect is produced from `RunnerServer.layerHandlers` and the
  * cluster runner RPC group.
  *
@@ -166,6 +172,8 @@ export const toHttpEffect: Effect.Effect<
 /**
  * Builds an HTTP effect that serves runner RPCs over WebSocket.
  *
+ * **Details**
+ *
  * The returned effect is produced from `RunnerServer.layerHandlers` and the
  * cluster runner RPC group.
  *
@@ -250,6 +258,8 @@ export const layerWebsocketOptions = (options: {
 /**
  * Complete HTTP runner layer.
  *
+ * **Details**
+ *
  * It serves runner routes at `/` and configures runner clients to communicate
  * over HTTP.
  *
@@ -273,6 +283,8 @@ export const layerHttp: Layer.Layer<
 /**
  * Client-only HTTP runner layer.
  *
+ * **Details**
+ *
  * It configures runner clients to communicate over HTTP without serving runner
  * HTTP routes.
  *
@@ -294,6 +306,8 @@ export const layerHttpClientOnly: Layer.Layer<
 /**
  * Complete WebSocket runner layer.
  *
+ * **Details**
+ *
  * It serves runner routes at `/` and configures runner clients to communicate
  * over WebSocket.
  *
@@ -317,6 +331,8 @@ export const layerWebsocket: Layer.Layer<
 /**
  * Client-only WebSocket runner layer.
  *
+ * **Details**
+ *
  * It configures runner clients to communicate over WebSocket without serving
  * runner WebSocket routes.
  *

package/src/unstable/cluster/K8sHttpClient.ts

@@ -48,6 +48,8 @@ export class K8sHttpClient extends Context.Service<
 /**
  * Layer that configures `K8sHttpClient` for the in-cluster Kubernetes API.
  *
+ * **Details**
+ *
  * It targets `https://kubernetes.default.svc/api`, adds the service-account
  * bearer token when available, requires successful HTTP statuses, and retries
  * transient failures.
@@ -80,6 +82,8 @@ export const layer: Layer.Layer<
 /**
  * Creates a cached effect that fetches running Kubernetes pods.
  *
+ * **Details**
+ *
  * The request can be limited by namespace and label selector, and the result is a
  * map keyed by pod IP address.
  *
@@ -127,6 +131,8 @@ export const makeGetPods: (
  * Creates a scoped function that ensures a Kubernetes pod exists and waits until
  * it is ready.
  *
+ * **Details**
+ *
  * The pod defaults to the `default` namespace and is deleted when the surrounding
  * scope closes.
  *
@@ -251,6 +257,8 @@ export class PodStatus extends Schema.Class<PodStatus>("@effect/cluster/K8sHttpC
 /**
  * Schema for Kubernetes Pod values used by cluster helpers.
  *
+ * **Details**
+ *
  * The model exposes readiness helpers derived from the pod status conditions.
  *
  * @category schemas

package/src/unstable/cluster/Message.ts

@@ -42,6 +42,8 @@ import type { Snowflake } from "./Snowflake.ts"
 /**
  * Message read by a runner from storage or transport.
  *
+ * **Details**
+ *
  * An incoming message is either a persisted request with an encoded payload or an
  * incoming control envelope.
  *
@@ -53,6 +55,8 @@ export type Incoming<R extends Rpc.Any> = IncomingRequest<R> | IncomingEnvelope
 /**
  * Locally decoded incoming message for in-process delivery.
  *
+ * **Details**
+ *
  * It is either a request with a decoded payload or an incoming control envelope.
  *
  * @category incoming
@@ -63,6 +67,8 @@ export type IncomingLocal<R extends Rpc.Any> = IncomingRequestLocal<R> | Incomin
 /**
  * Converts an outgoing message into a locally deliverable incoming message.
  *
+ * **Details**
+ *
  * Request messages keep their decoded payload and response callback, while
  * control envelopes are wrapped as incoming envelopes.
  *
@@ -88,6 +94,8 @@ export const incomingLocalFromOutgoing = <R extends Rpc.Any>(self: Outgoing<R>):
  * Incoming persisted request whose payload has not yet been decoded with the RPC
  * schema.
  *
+ * **Details**
+ *
  * It carries the last reply that was sent and a callback for persisting encoded
  * replies.
  *
@@ -103,6 +111,8 @@ export class IncomingRequest<R extends Rpc.Any> extends Data.TaggedClass("Incomi
 /**
  * Incoming request for local delivery with a decoded payload.
  *
+ * **Details**
+ *
  * It includes dynamic annotations, the last sent reply, and a callback for
  * replying with decoded replies.
  *
@@ -130,6 +140,8 @@ export class IncomingEnvelope extends Data.TaggedClass("IncomingEnvelope")<{
 /**
  * Message produced for storage or transport.
  *
+ * **Details**
+ *
  * An outgoing message is either an entity request or a control envelope.
  *
  * @category outgoing
@@ -140,6 +152,8 @@ export type Outgoing<R extends Rpc.Any> = OutgoingRequest<R> | OutgoingEnvelope
 /**
  * Outgoing entity request with decoded payload and RPC metadata.
  *
+ * **Details**
+ *
  * It carries the service context used for serialization, the last received reply,
  * the reply callback, dynamic annotations, and an optional encoded request cache.
  *
@@ -165,6 +179,8 @@ export class OutgoingRequest<R extends Rpc.Any> extends Data.TaggedClass("Outgoi
 /**
  * Outgoing control envelope paired with RPC metadata.
  *
+ * **When to use**
+ *
  * Use `OutgoingEnvelope.interrupt` to construct an interrupt envelope for an
  * in-flight request.
  *
@@ -201,6 +217,8 @@ const neverRpc = Rpc.make("Never", {
 /**
  * Serializes an outgoing message into a partial envelope.
  *
+ * **Details**
+ *
  * Control envelopes pass through unchanged. Requests are encoded with their RPC
  * payload schema, reusing the cached encoded request when available.
  *
@@ -223,6 +241,8 @@ export const serialize = <Rpc extends Rpc.Any>(
 /**
  * Serializes an outgoing message into its JSON envelope representation.
  *
+ * **Details**
+ *
  * Schema encoding failures are converted to `MalformedMessage`.
  *
  * @category serialization / deserialization
@@ -240,6 +260,8 @@ export const serializeEnvelope = <Rpc extends Rpc.Any>(
  * Encodes the payload of an `OutgoingRequest` with the request's RPC payload
  * schema and service context.
  *
+ * **Details**
+ *
  * The result is a `PartialRequest` suitable for storage or transport.
  *
  * @category serialization / deserialization
@@ -262,6 +284,8 @@ export const serializeRequest = <Rpc extends Rpc.Any>(
 /**
  * Decodes a partial envelope back into a locally deliverable incoming message.
  *
+ * **Details**
+ *
  * Control envelopes pass through directly. Request envelopes require the original
  * `OutgoingRequest` so the payload can be decoded with the correct RPC schema and
  * context.