effect 4.0.0-beta.71 → 4.0.0-beta.72

package/src/unstable/ai/McpServer.ts

@@ -581,7 +581,7 @@ export const layer = (options: {
   )
 
 /**
- * Run the McpServer, using stdio for input and output.
+ * Runs the McpServer, using stdio for input and output.
  *
  * **Example** (Running an MCP server over stdio)
  *
@@ -679,7 +679,7 @@ export const layerHttp = (options: {
   )
 
 /**
- * Register a `Toolkit` with the `McpServer`.
+ * Registers a `Toolkit` with the `McpServer`.
  *
  * @category tools
  * @since 4.0.0
@@ -755,7 +755,7 @@ export const registerToolkit: <Tools extends Record<string, Tool.Any>>(
 })
 
 /**
- * Register an AiToolkit with the McpServer.
+ * Registers an `AiToolkit` with the `McpServer`.
  *
  * @category tools
  * @since 4.0.0
@@ -804,14 +804,26 @@ export type ResourceCompletions<Schemas extends ReadonlyArray<Schema.Top>> = {
 }
 
 /**
- * Register a resource with the McpServer.
+ * Registers an MCP resource or resource template from an Effect program.
+ *
+ * **When to use**
+ *
+ * Use to add a resource to an existing MCP server from an Effect program.
+ *
+ * @see {@link resource} for the layer-based resource registration wrapper
  *
  * @category resources
  * @since 4.0.0
  */
 export const registerResource: {
   /**
-   * Register a resource with the McpServer.
+   * Registers an MCP resource or resource template from an Effect program.
+   *
+   * **When to use**
+   *
+   * Use to add a resource to an existing MCP server from an Effect program.
+   *
+   * @see {@link resource} for the layer-based resource registration wrapper
    *
    * @category resources
    * @since 4.0.0
@@ -833,7 +845,13 @@ export const registerResource: {
     }
   ): Effect.Effect<void, never, Exclude<R, McpServerClient> | McpServer>
   /**
-   * Register a resource with the McpServer.
+   * Registers an MCP resource or resource template from an Effect program.
+   *
+   * **When to use**
+   *
+   * Use to add a resource to an existing MCP server from an Effect program.
+   *
+   * @see {@link resource} for the layer-based resource registration wrapper
    *
    * @category resources
    * @since 4.0.0
@@ -974,14 +992,26 @@ export const registerResource: {
 } as any
 
 /**
- * Register a resource with the McpServer.
+ * Creates a layer that registers an MCP resource or resource template.
+ *
+ * **When to use**
+ *
+ * Use to compose resource registration into an MCP server layer.
+ *
+ * @see {@link registerResource} for the Effect-level resource registration API
  *
  * @category resources
  * @since 4.0.0
  */
 export const resource: {
   /**
-   * Register a resource with the McpServer.
+   * Creates a layer that registers an MCP resource or resource template.
+   *
+   * **When to use**
+   *
+   * Use to compose resource registration into an MCP server layer.
+   *
+   * @see {@link registerResource} for the Effect-level resource registration API
    *
    * @category resources
    * @since 4.0.0
@@ -1002,7 +1032,13 @@ export const resource: {
     }
   ): Layer.Layer<never, never, Exclude<R, McpServerClient>>
   /**
-   * Register a resource with the McpServer.
+   * Creates a layer that registers an MCP resource or resource template.
+   *
+   * **When to use**
+   *
+   * Use to compose resource registration into an MCP server layer.
+   *
+   * @see {@link registerResource} for the Effect-level resource registration API
    *
    * @category resources
    * @since 4.0.0
@@ -1048,7 +1084,7 @@ export const resource: {
 } as any
 
 /**
- * Register a prompt with the McpServer.
+ * Registers an MCP prompt from an Effect program.
  *
  * **When to use**
  *
@@ -1155,7 +1191,7 @@ export const registerPrompt = <
 }
 
 /**
- * Register a prompt with the McpServer.
+ * Creates a layer that registers an MCP prompt.
  *
  * **When to use**
  *
@@ -1196,7 +1232,7 @@ export const prompt = <
   )
 
 /**
- * Requests structured input from the current MCP client and decodes the
+ * Collects structured input from the current MCP client and decodes the
  * accepted response with `schema`.
  *
  * **Details**
@@ -1239,7 +1275,7 @@ export const elicit: <S extends Schema.Encoder<Record<string, unknown>, unknown>
 }, Effect.scoped)
 
 /**
- * Access the current client's capabilities.
+ * Accesses the current client's capabilities.
  *
  * @category capabilities
  * @since 4.0.0

package/src/unstable/ai/Prompt.ts

@@ -1770,7 +1770,7 @@ const $Prompt = Schema.declare((u) => isPrompt(u), { identifier: "Prompt" })
 // TODO: shoudn't the name be `PromptFrom...`?
 // TODO: is the explicit encoding necessary? maybe use the default JSON serializer?
 /**
- * Describes a schema that represents a `Prompt` instance.
+ * Schema for AI prompt instances.
  *
  * @category schemas
  * @since 4.0.0

package/src/unstable/ai/Response.ts

@@ -2514,7 +2514,7 @@ export interface FinishPartEncoded extends BasePartEncoded<"finish", FinishPartM
 export interface FinishPartMetadata extends ProviderMetadata {}
 
 /**
- * Runtime schema and codec for finish response parts.
+ * Schema for finish response parts.
  *
  * **Details**
  *

package/src/unstable/ai/Tokenizer.ts

@@ -55,7 +55,12 @@ import type * as AiError from "./AiError.ts"
 import * as Prompt from "./Prompt.ts"
 
 /**
- * The `Tokenizer` service tag for dependency injection.
+ * Service tag for model tokenization services.
+ *
+ * **When to use**
+ *
+ * Use to access or provide model-specific token counting and prompt truncation
+ * operations.
  *
  * **Details**
  *
@@ -75,7 +80,7 @@ import * as Prompt from "./Prompt.ts"
  * })
  * ```
  *
- * @category services
+ * @category tags
  * @since 4.0.0
  */
 export class Tokenizer extends Context.Service<Tokenizer, Service>()(

package/src/unstable/ai/Tool.ts

@@ -1585,8 +1585,8 @@ export const providerDefined = <
 // =============================================================================
 
 /**
- * A utility which allows mapping between a provider-defined name for a tool
- * and the name given to the tool by the Effect AI SDK.
+ * Maps between a provider-defined tool name and the name given to the tool by
+ * the Effect AI SDK.
  *
  * **Details**
  *
@@ -2064,7 +2064,7 @@ export const unsafeSecureJsonParse = (text: string): unknown => {
 export interface EmptyParams extends Schema.$Record<Schema.String, Schema.Never> {}
 
 /**
- * A schema for tools that accept no parameters.
+ * Schema for tools that accept no parameters.
  *
  * **When to use**
  *

package/src/unstable/cli/CliError.ts

@@ -30,7 +30,7 @@ import * as Runtime from "../../Runtime.ts"
 import * as Schema from "../../Schema.ts"
 
 /**
- * @category type id
+ * @category type IDs
  * @since 4.0.0
  */
 const TypeId = "~effect/cli/CliError"
@@ -444,7 +444,7 @@ export class UnknownSubcommand extends Schema.ErrorClass<UnknownSubcommand>(`${T
 }
 
 /**
- * Wrapper for user (handler) errors to unify under CLI error channel when desired.
+ * Error wrapper for user handler failures in the CLI error channel.
  *
  * **Example** (Wrapping user errors)
  *
@@ -537,7 +537,7 @@ export const NonShowHelpErrors: Schema.Union<
 export type NonShowHelpErrors = typeof NonShowHelpErrors.Type
 
 /**
- * Control-flow value that asks the CLI runner to render help for a command path.
+ * Error data requesting CLI help rendering for a command path.
  *
  * **Details**
  *

package/src/unstable/cli/CliOutput.ts

@@ -30,7 +30,7 @@ import type * as CliError from "./CliError.ts"
 import type { HelpDoc } from "./HelpDoc.ts"
 
 /**
- * Service interface for formatting CLI output including help, errors, and version info.
+ * Defines the service interface for formatting CLI output including help, errors, and version info.
  * This allows customization of output formatting, including color support.
  *
  * **Example** (Customizing CLI output formatting)

package/src/unstable/cli/Command.ts

@@ -1226,7 +1226,7 @@ export const withSharedFlags: {
 )
 
 /**
- * Declares global flags for a command scope.
+ * Adds global flags to a command scope.
  *
  * **Details**
  *
@@ -1237,7 +1237,7 @@ export const withSharedFlags: {
  */
 export const withGlobalFlags: {
   /**
-   * Declares global flags for a command scope.
+   * Adds global flags to a command scope.
    *
    * **Details**
    *
@@ -1250,7 +1250,7 @@ export const withGlobalFlags: {
     self: Command<Name, Input, ContextInput, E, R>
   ) => Command<Name, Input, ContextInput, E, Exclude<R, ExtractGlobalFlagContext<GlobalFlags>>>
   /**
-   * Declares global flags for a command scope.
+   * Adds global flags to a command scope.
    *
    * **Details**
    *

package/src/unstable/cli/Flag.ts

@@ -1148,7 +1148,7 @@ export const mapTryCatch: {
 ) => Param.mapTryCatch(self, f, onError))
 
 /**
- * Requires a flag to be specified at least a minimum number of times.
+ * Ensures a flag is specified at least a minimum number of times.
  *
  * **Example** (Requiring repeated values)
  *
@@ -1170,7 +1170,7 @@ export const mapTryCatch: {
  */
 export const atLeast: {
   /**
-   * Requires a flag to be specified at least a minimum number of times.
+   * Ensures a flag is specified at least a minimum number of times.
    *
    * **Example** (Requiring repeated values)
    *
@@ -1192,7 +1192,7 @@ export const atLeast: {
    */
   <A>(min: number): (self: Flag<A>) => Flag<ReadonlyArray<A>>
   /**
-   * Requires a flag to be specified at least a minimum number of times.
+   * Ensures a flag is specified at least a minimum number of times.
    *
    * **Example** (Requiring repeated values)
    *
@@ -1216,7 +1216,7 @@ export const atLeast: {
 } = dual(2, <A>(self: Flag<A>, min: number) => Param.atLeast(self, min))
 
 /**
- * Limits a flag to be specified at most a maximum number of times.
+ * Ensures a flag is specified at most a maximum number of times.
  *
  * **Example** (Limiting repeated values)
  *
@@ -1238,7 +1238,7 @@ export const atLeast: {
  */
 export const atMost: {
   /**
-   * Limits a flag to be specified at most a maximum number of times.
+   * Ensures a flag is specified at most a maximum number of times.
    *
    * **Example** (Limiting repeated values)
    *
@@ -1260,7 +1260,7 @@ export const atMost: {
    */
   <A>(max: number): (self: Flag<A>) => Flag<ReadonlyArray<A>>
   /**
-   * Limits a flag to be specified at most a maximum number of times.
+   * Ensures a flag is specified at most a maximum number of times.
    *
    * **Example** (Limiting repeated values)
    *
@@ -1284,7 +1284,7 @@ export const atMost: {
 } = dual(2, <A>(self: Flag<A>, max: number) => Param.atMost(self, max))
 
 /**
- * Constrains a flag to be specified between a minimum and maximum number of times.
+ * Ensures a flag is specified between a minimum and maximum number of times.
  *
  * **Example** (Bounding repeated values)
  *
@@ -1306,7 +1306,7 @@ export const atMost: {
  */
 export const between: {
   /**
-   * Constrains a flag to be specified between a minimum and maximum number of times.
+   * Ensures a flag is specified between a minimum and maximum number of times.
    *
    * **Example** (Bounding repeated values)
    *
@@ -1328,7 +1328,7 @@ export const between: {
    */
   <A>(min: number, max: number): (self: Flag<A>) => Flag<ReadonlyArray<A>>
   /**
-   * Constrains a flag to be specified between a minimum and maximum number of times.
+   * Ensures a flag is specified between a minimum and maximum number of times.
    *
    * **Example** (Bounding repeated values)
    *

package/src/unstable/cli/GlobalFlag.ts

@@ -156,7 +156,7 @@ let settingIdCounter = 0
 /* ========================================================================== */
 
 /**
- * The `--help` / `-h` global flag, which shows help documentation for the
+ * Defines the `--help` / `-h` global flag, which shows help documentation for the
  * active command path.
  *
  * @see {@link BuiltIns} for the default list containing this flag
@@ -179,8 +179,11 @@ export const Help: Action<boolean> = action({
 })
 
 /**
- * The `--version` global flag.
- * Shows version information for the command.
+ * Defines the global action flag for showing command version information.
+ *
+ * **When to use**
+ *
+ * Use to add a built-in `--version` flag to a command runner.
  *
  * @category references
  * @since 4.0.0
@@ -197,7 +200,7 @@ export const Version: Action<boolean> = action({
 })
 
 /**
- * The `--completions` global flag, which prints a shell completion script for
+ * Defines the `--completions` global flag, which prints a shell completion script for
  * the given shell.
  *
  * **Details**
@@ -226,8 +229,12 @@ export const Completions: Action<Option.Option<"bash" | "zsh" | "fish">> = actio
 })
 
 /**
- * The `--log-level` global flag.
- * Sets the minimum log level for the command.
+ * Defines the global setting flag for command log level.
+ *
+ * **When to use**
+ *
+ * Use to add a built-in `--log-level` option that configures the minimum log
+ * level for the command.
  *
  * @category references
  * @since 4.0.0

package/src/unstable/cli/Param.ts

@@ -83,7 +83,7 @@ export type ParamKind = "argument" | "flag"
 export type Environment = FileSystem.FileSystem | Path.Path | Terminal.Terminal | ChildProcessSpawner
 
 /**
- * Kind discriminator for positional argument parameters.
+ * Defines the kind discriminator for positional argument parameters.
  *
  * **When to use**
  *
@@ -99,7 +99,7 @@ export type Environment = FileSystem.FileSystem | Path.Path | Terminal.Terminal
 export const argumentKind: "argument" = "argument" as const
 
 /**
- * Kind discriminator for flag parameters.
+ * Defines the kind discriminator for flag parameters.
  *
  * **When to use**
  *

package/src/unstable/cli/Primitive.ts

@@ -724,7 +724,7 @@ export const keyValuePair: Primitive<Record<string, string>> = makePrimitive(
 )
 
 /**
- * A sentinel primitive that always fails to parse a value.
+ * Creates a sentinel primitive that always fails to parse a value.
  *
  * **When to use**
  *

package/src/unstable/cli/Prompt.ts

@@ -278,6 +278,10 @@ export interface IntegerOptions {
    * The message to display in the prompt.
    */
   readonly message: string
+  /**
+   * The default value of the integer prompt.
+   */
+  readonly default?: number
   /**
    * The minimum value that can be entered by the user (defaults to `-Infinity`).
    */
@@ -360,6 +364,10 @@ export interface FileOptions {
    * to the current working directory.
    */
   readonly startingPath?: string
+  /**
+   * The default path to select when the prompt is first displayed.
+   */
+  readonly default?: string
   /**
    * The number of choices to display at one time, defaulting to `10`.
    */
@@ -838,6 +846,7 @@ export const file = (options: FileOptions = {}): Prompt<string> => {
     type: options.type ?? "file",
     message: options.message ?? `Choose a file`,
     startingPath: Option.fromUndefinedOr(options.startingPath),
+    default: Option.fromUndefinedOr(options.default),
     maxPerPage: options.maxPerPage ?? 10,
     filter: options.filter ?? (() => Effect.succeed(true))
   }
@@ -847,9 +856,22 @@ export const file = (options: FileOptions = {}): Prompt<string> => {
     Environment
   > = Effect.gen(function*() {
     const currentPath = yield* resolveCurrentPath(Option.none(), opts)
-    const files = yield* getFileList(currentPath, opts)
+    const path = yield* Path.Path
+    const defaultPath = Option.map(opts.default, (defaultValue) => path.resolve(currentPath, defaultValue))
+    const initialPath = Option.match(defaultPath, {
+      onNone: () => currentPath,
+      onSome: (defaultPath) => path.dirname(defaultPath)
+    })
+    const files = yield* getFileList(initialPath, opts)
+    const cursor = Option.match(defaultPath, {
+      onNone: () => 0,
+      onSome: (defaultPath) => {
+        const index = files.indexOf(path.basename(defaultPath))
+        return index === -1 ? 0 : index
+      }
+    })
     const confirm = Confirm.Hide()
-    return { cursor: 0, files, allFiles: files, query: "", path: Option.none(), confirm }
+    return { cursor, files, allFiles: files, query: "", path: Option.map(defaultPath, path.dirname), confirm }
   })
   return custom(initialState, {
     render: handleFileRender(opts),
@@ -859,24 +881,21 @@ export const file = (options: FileOptions = {}): Prompt<string> => {
 }
 
 /**
- * Sequences prompts by using the output of this prompt to create the next
- * prompt.
+ * Composes prompts by using the output of this prompt to create the next prompt.
  *
  * @category combinators
  * @since 4.0.0
  */
 export const flatMap: {
   /**
-   * Sequences prompts by using the output of this prompt to create the next
-   * prompt.
+   * Composes prompts by using the output of this prompt to create the next prompt.
    *
    * @category combinators
    * @since 4.0.0
    */
   <Output, Output2>(f: (output: Output) => Prompt<Output2>): (self: Prompt<Output>) => Prompt<Output2>
   /**
-   * Sequences prompts by using the output of this prompt to create the next
-   * prompt.
+   * Composes prompts by using the output of this prompt to create the next prompt.
    *
    * @category combinators
    * @since 4.0.0
@@ -906,6 +925,7 @@ export const flatMap: {
  */
 export const float = (options: FloatOptions): Prompt<number> => {
   const opts: FloatOptionsReq = {
+    default: 0,
     min: Number.NEGATIVE_INFINITY,
     max: Number.POSITIVE_INFINITY,
     incrementBy: 1,
@@ -922,9 +942,10 @@ export const float = (options: FloatOptions): Prompt<number> => {
     },
     ...options
   }
+  const initialValue = options.default === undefined ? "" : `${opts.default}`
   const initialState: NumberState = {
-    cursor: 0,
-    value: "",
+    cursor: initialValue.length,
+    value: initialValue,
     error: Option.none()
   }
   return custom(initialState, {
@@ -957,6 +978,7 @@ export const hidden = (
  */
 export const integer = (options: IntegerOptions): Prompt<number> => {
   const opts: IntegerOptionsReq = {
+    default: 0,
     min: Number.NEGATIVE_INFINITY,
     max: Number.POSITIVE_INFINITY,
     incrementBy: 1,
@@ -972,9 +994,10 @@ export const integer = (options: IntegerOptions): Prompt<number> => {
     },
     ...options
   }
+  const initialValue = options.default === undefined ? "" : `${opts.default}`
   const initialState: NumberState = {
-    cursor: 0,
-    value: "",
+    cursor: initialValue.length,
+    value: initialValue,
     error: Option.none()
   }
   return custom(initialState, {
@@ -2024,8 +2047,9 @@ class Meridiem extends DatePart {
   }
 }
 
-interface FileOptionsReq extends Required<Omit<FileOptions, "startingPath">> {
+interface FileOptionsReq extends Required<Omit<FileOptions, "startingPath" | "default">> {
   readonly startingPath: Option.Option<string>
+  readonly default: Option.Option<string>
 }
 
 interface FileState {

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

@@ -381,7 +381,7 @@ const invalidNegatedFlagValue = (
   })
 
 /**
- * Checks if a token is a boolean literal value.
+ * Checks whether a token is a boolean literal value.
  * Recognizes: true/false, yes/no, on/off, 1/0
  */
 const asBooleanLiteral = (token: Token | undefined): string | undefined =>

package/src/unstable/cluster/ClusterMetrics.ts

@@ -26,7 +26,7 @@
 import * as Metric from "../../Metric.ts"
 
 /**
- * Gauge tracking the number of active entity instances for each entity type on
+ * Creates a gauge tracking the number of active entity instances for each entity type on
  * the current runner.
  *
  * **Details**
@@ -48,7 +48,7 @@ import * as Metric from "../../Metric.ts"
 export const entities = Metric.gauge("effect_cluster_entities", { bigint: true })
 
 /**
- * Gauge tracking the number of singleton processes currently running on the
+ * Creates a gauge tracking the number of singleton processes currently running on the
  * current runner.
  *
  * @category metrics
@@ -57,7 +57,7 @@ export const entities = Metric.gauge("effect_cluster_entities", { bigint: true }
 export const singletons = Metric.gauge("effect_cluster_singletons", { bigint: true })
 
 /**
- * Gauge tracking the number of registered cluster runners.
+ * Represents a gauge tracking the number of registered cluster runners.
  *
  * **When to use**
  *
@@ -75,7 +75,7 @@ export const singletons = Metric.gauge("effect_cluster_singletons", { bigint: tr
 export const runners = Metric.gauge("effect_cluster_runners", { bigint: true })
 
 /**
- * Gauge tracking the number of cluster runners currently considered healthy.
+ * Represents a gauge tracking the number of cluster runners currently considered healthy.
  *
  * **When to use**
  *
@@ -98,7 +98,7 @@ export const runners = Metric.gauge("effect_cluster_runners", { bigint: true })
 export const runnersHealthy = Metric.gauge("effect_cluster_runners_healthy", { bigint: true })
 
 /**
- * Gauge tracking the number of shards currently acquired by the current runner.
+ * Represents a gauge tracking the number of shards currently acquired by the current runner.
  *
  * **When to use**
  *

package/src/unstable/cluster/ClusterSchema.ts

@@ -185,8 +185,17 @@ 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.
+ * Context reference for deriving request annotations from a cluster request.
+ *
+ * **When to use**
+ *
+ * Use to customize server-side request annotations based on the decoded
+ * request value.
+ *
+ * **Gotchas**
+ *
+ * This only applies to requests handled by the entity, not to the generated
+ * client.
  *
  * @category annotations
  * @since 4.0.0