effect 4.0.0-beta.73 → 4.0.0-beta.74

package/src/Tuple.ts

@@ -224,7 +224,7 @@ type PickTuple<T extends ReadonlyArray<unknown>, K> = _BuildTuple<T, K>
  *
  * @see {@link omit} – the inverse (exclude indices instead)
  * @see {@link get} – extract a single element
- * @category utils
+ * @category filtering
  * @since 4.0.0
  */
 export const pick: {
@@ -250,7 +250,7 @@ export const pick: {
    *
    * @see {@link omit} – the inverse (exclude indices instead)
    * @see {@link get} – extract a single element
-   * @category utils
+   * @category filtering
    * @since 4.0.0
    */
   <const T extends ReadonlyArray<unknown>, const I extends ReadonlyArray<Indices<T>>>(indices: I): (self: T) => PickTuple<T, I[number]>
@@ -276,7 +276,7 @@ export const pick: {
    *
    * @see {@link omit} – the inverse (exclude indices instead)
    * @see {@link get} – extract a single element
-   * @category utils
+   * @category filtering
    * @since 4.0.0
    */
   <const T extends ReadonlyArray<unknown>, const I extends ReadonlyArray<Indices<T>>>(self: T, indices: I): PickTuple<T, I[number]>
@@ -313,7 +313,7 @@ type OmitTuple<T extends ReadonlyArray<unknown>, K> = _BuildTuple<T, Exclude<Ind
  * ```
  *
  * @see {@link pick} – the inverse (keep only specified indices)
- * @category utils
+ * @category filtering
  * @since 4.0.0
  */
 export const omit: {
@@ -338,7 +338,7 @@ export const omit: {
    * ```
    *
    * @see {@link pick} – the inverse (keep only specified indices)
-   * @category utils
+   * @category filtering
    * @since 4.0.0
    */
   <const T extends ReadonlyArray<unknown>, const I extends ReadonlyArray<Indices<T>>>(indices: I): (self: T) => OmitTuple<T, I[number]>
@@ -363,7 +363,7 @@ export const omit: {
    * ```
    *
    * @see {@link pick} – the inverse (keep only specified indices)
-   * @category utils
+   * @category filtering
    * @since 4.0.0
    */
   <const T extends ReadonlyArray<unknown>, const I extends ReadonlyArray<Indices<T>>>(self: T, indices: I): OmitTuple<T, I[number]>
@@ -399,7 +399,7 @@ export const omit: {
  * ```
  *
  * @see {@link appendElements} – append multiple elements (another tuple)
- * @category Concatenating
+ * @category combining
  * @since 2.0.0
  */
 export const appendElement: {
@@ -424,7 +424,7 @@ export const appendElement: {
    * ```
    *
    * @see {@link appendElements} – append multiple elements (another tuple)
-   * @category Concatenating
+   * @category combining
    * @since 2.0.0
    */
   <const E>(element: E): <const T extends ReadonlyArray<unknown>>(self: T) => [...T, E]
@@ -449,7 +449,7 @@ export const appendElement: {
    * ```
    *
    * @see {@link appendElements} – append multiple elements (another tuple)
-   * @category Concatenating
+   * @category combining
    * @since 2.0.0
    */
   <const T extends ReadonlyArray<unknown>, const E>(self: T, element: E): [...T, E]
@@ -477,7 +477,7 @@ export const appendElement: {
  * ```
  *
  * @see {@link appendElement} – append a single element
- * @category Concatenating
+ * @category combining
  * @since 4.0.0
  */
 export const appendElements: {
@@ -503,7 +503,7 @@ export const appendElements: {
    * ```
    *
    * @see {@link appendElement} – append a single element
-   * @category Concatenating
+   * @category combining
    * @since 4.0.0
    */
   <const T2 extends ReadonlyArray<unknown>>(that: T2): <const T1 extends ReadonlyArray<unknown>>(self: T1) => [...T1, ...T2]
@@ -529,7 +529,7 @@ export const appendElements: {
    * ```
    *
    * @see {@link appendElement} – append a single element
-   * @category Concatenating
+   * @category combining
    * @since 4.0.0
    */
   <const T1 extends ReadonlyArray<unknown>, const T2 extends ReadonlyArray<unknown>>(self: T1, that: T2): [...T1, ...T2]
@@ -1146,7 +1146,7 @@ export const mapOmit: {
  * ```
  *
  * @see {@link makeOrder} – create an `Order` for tuples
- * @category Equivalence
+ * @category instances
  * @since 4.0.0
  */
 export const makeEquivalence = Equivalence.Tuple
@@ -1176,7 +1176,7 @@ export const makeEquivalence = Equivalence.Tuple
  * ```
  *
  * @see {@link makeEquivalence} – create an `Equivalence` for tuples
- * @category Ordering
+ * @category ordering
  * @since 4.0.0
  */
 export const makeOrder = order.Tuple

package/src/TxHashMap.ts

@@ -164,7 +164,7 @@ export declare namespace TxHashMap {
    * })
    * ```
    *
-   * @category type-level
+   * @category utility types
    * @since 4.0.0
    */
   export type Key<T extends TxHashMap<any, any>> = T extends TxHashMap<infer K, any> ? K : never
@@ -197,7 +197,7 @@ export declare namespace TxHashMap {
    * })
    * ```
    *
-   * @category type-level
+   * @category utility types
    * @since 4.0.0
    */
   export type Value<T extends TxHashMap<any, any>> = T extends TxHashMap<any, infer V> ? V : never
@@ -233,7 +233,7 @@ export declare namespace TxHashMap {
    * })
    * ```
    *
-   * @category type-level
+   * @category utility types
    * @since 4.0.0
    */
   export type Entry<T extends TxHashMap<any, any>> = T extends TxHashMap<infer K, infer V> ? readonly [K, V] : never

package/src/TxHashSet.ts

@@ -146,7 +146,7 @@ export declare namespace TxHashSet {
    * console.log(processFruit("apple")) // Processing apple
    * ```
    *
-   * @category type-level
+   * @category utility types
    * @since 4.0.0
    */
   export type Value<T> = T extends TxHashSet<infer V> ? V : never

package/src/Unify.ts

@@ -289,7 +289,7 @@ export type Unify<A> = Values<
  *
  * @see {@link Unify} for the type-level normalization applied by this helper
  *
- * @category utils
+ * @category utility types
  * @since 2.0.0
  */
 export const unify: {
@@ -334,7 +334,7 @@ export const unify: {
    *
    * @see {@link Unify} for the type-level normalization applied by this helper
    *
-   * @category utils
+   * @category utility types
    * @since 2.0.0
    */
   <
@@ -388,7 +388,7 @@ export const unify: {
    *
    * @see {@link Unify} for the type-level normalization applied by this helper
    *
-   * @category utils
+   * @category utility types
    * @since 2.0.0
    */
   <
@@ -441,7 +441,7 @@ export const unify: {
    *
    * @see {@link Unify} for the type-level normalization applied by this helper
    *
-   * @category utils
+   * @category utility types
    * @since 2.0.0
    */
   <
@@ -491,7 +491,7 @@ export const unify: {
    *
    * @see {@link Unify} for the type-level normalization applied by this helper
    *
-   * @category utils
+   * @category utility types
    * @since 2.0.0
    */
   <
@@ -540,7 +540,7 @@ export const unify: {
    *
    * @see {@link Unify} for the type-level normalization applied by this helper
    *
-   * @category utils
+   * @category utility types
    * @since 2.0.0
    */
   <
@@ -588,7 +588,7 @@ export const unify: {
    *
    * @see {@link Unify} for the type-level normalization applied by this helper
    *
-   * @category utils
+   * @category utility types
    * @since 2.0.0
    */
   <T>(x: T): Unify<T>

package/src/testing/TestClock.ts

@@ -167,7 +167,7 @@ export declare namespace TestClock {
    * })
    * ```
    *
-   * @category models
+   * @category options
    * @since 4.0.0
    */
   export interface Options {
@@ -419,7 +419,7 @@ export const layer: (options?: TestClock.Options) => Layer.Layer<TestClock> = fl
  * })
  * ```
  *
- * @category utils
+ * @category testing
  * @since 2.0.0
  */
 export const testClockWith = <A, E, R>(
@@ -454,7 +454,7 @@ export const testClockWith = <A, E, R>(
  * })
  * ```
  *
- * @category utils
+ * @category testing
  * @since 2.0.0
  */
 export const adjust = (duration: Duration.Input): Effect.Effect<void> =>
@@ -488,7 +488,7 @@ export const adjust = (duration: Duration.Input): Effect.Effect<void> =>
  * })
  * ```
  *
- * @category utils
+ * @category testing
  * @since 2.0.0
  */
 export const setTime = (timestamp: number): Effect.Effect<void> =>
@@ -522,7 +522,7 @@ export const setTime = (timestamp: number): Effect.Effect<void> =>
  * })
  * ```
  *
- * @category utils
+ * @category testing
  * @since 4.0.0
  */
 export const withLive = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>

package/src/testing/TestConsole.ts

@@ -276,7 +276,7 @@ export const make = Effect.gen(function*() {
  * @see {@link logLines} for reading captured `Console.log` calls directly
  * @see {@link errorLines} for reading captured `Console.error` calls directly
  *
- * @category utils
+ * @category testing
  * @since 4.0.0
  */
 export const testConsoleWith = <A, E, R>(f: (console: TestConsole) => Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
@@ -351,7 +351,7 @@ export const layer: Layer.Layer<TestConsole> = Layer.effect(Console.Console)(mak
  * @see {@link errorLines} for reading captured `Console.error` output
  * @see {@link layer} for capturing console calls during a test
  *
- * @category utils
+ * @category testing
  * @since 4.0.0
  */
 export const logLines: Effect.Effect<ReadonlyArray<unknown>, never, never> = testConsoleWith(
@@ -390,7 +390,7 @@ export const logLines: Effect.Effect<ReadonlyArray<unknown>, never, never> = tes
  * @see {@link logLines} for reading captured `Console.log` output
  * @see {@link layer} for capturing console calls during a test
  *
- * @category utils
+ * @category testing
  * @since 4.0.0
  */
 export const errorLines: Effect.Effect<ReadonlyArray<unknown>, never, never> = testConsoleWith(

package/src/unstable/ai/Chat.ts

@@ -107,7 +107,7 @@ import type * as Tool from "./Tool.ts"
  * })
  * ```
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class Chat extends Context.Service<Chat, Service>()(
@@ -725,7 +725,7 @@ export class ChatNotFoundError extends Schema.ErrorClass<ChatNotFoundError>(
  * Use to provide the storage operations needed by persisted conversation
  * sessions.
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 // @effect-diagnostics effect/leakingRequirements:off

package/src/unstable/ai/EmbeddingModel.ts

@@ -146,7 +146,7 @@ export class EmbedManyResponse extends Schema.Class<EmbedManyResponse>(
 /**
  * Provider input options for embedding requests.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface ProviderOptions {

package/src/unstable/ai/IdGenerator.ts

@@ -81,7 +81,7 @@ import * as Random from "../../Random.ts"
  * })
  * ```
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class IdGenerator extends Context.Service<IdGenerator, Service>()(
@@ -142,7 +142,7 @@ export interface Service {
  * // This will generate IDs like: "tool_A1B2C3D4"
  * ```
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface MakeOptions {

package/src/unstable/ai/LanguageModel.ts

@@ -104,7 +104,7 @@ import * as Toolkit from "./Toolkit.ts"
  * })
  * ```
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class LanguageModel extends Context.Service<LanguageModel, Service>()(
@@ -261,7 +261,7 @@ export const defaultCodecTransformer: CodecTransformer = InternalCodecTransforme
 /**
  * Configuration options for text generation.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface GenerateTextOptions<Tools extends Record<string, Tool.Any>> {
@@ -319,7 +319,7 @@ type GenerateTextOptionsWithoutToolkit = Omit<GenerateTextOptions<{}>, "toolkit"
 /**
  * Configuration options for structured object generation.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface GenerateObjectOptions<
@@ -684,7 +684,7 @@ export type ExtractServices<Options> = Options extends {
  * underlying provider implementation, regardless of the specific provider being
  * used.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface ProviderOptions {

package/src/unstable/ai/Prompt.ts

@@ -78,7 +78,7 @@ import type * as Response from "./Response.ts"
  * Provider-specific options are keyed by provider-specific names, and each
  * value is JSON or `null`.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export const ProviderOptions: Schema.$Record<
@@ -90,7 +90,7 @@ export const ProviderOptions: Schema.$Record<
  * Type of provider-specific options that can be attached to prompt messages
  * and content parts.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export type ProviderOptions = typeof ProviderOptions.Type
@@ -239,7 +239,7 @@ export const makePart = <const Type extends Part["type"]>(
  * A utility type for specifying the parameters required to construct a
  * specific part of a prompt.
  *
- * @category Utility Types
+ * @category utility types
  * @since 4.0.0
  */
 export type PartConstructorParams<P extends Part> = Omit<P, typeof PartTypeId | "type" | "options"> & {
@@ -298,7 +298,7 @@ export interface TextPartEncoded extends BasePartEncoded<"text", TextPartOptions
  * Represents provider-specific options that can be associated with a
  * `TextPart` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface TextPartOptions extends ProviderOptions {}
@@ -381,7 +381,7 @@ export interface ReasoningPartEncoded extends BasePartEncoded<"reasoning", Reaso
  * Represents provider-specific options that can be associated with a
  * `ReasoningPart` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface ReasoningPartOptions extends ProviderOptions {}
@@ -490,7 +490,7 @@ export interface FilePartEncoded extends BasePartEncoded<"file", FilePartOptions
  * Represents provider-specific options that can be associated with a
  * `FilePart` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface FilePartOptions extends ProviderOptions {}
@@ -607,7 +607,7 @@ export interface ToolCallPartEncoded extends BasePartEncoded<"tool-call", ToolCa
  * Represents provider-specific options that can be associated with a
  * `ToolCallPart` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface ToolCallPartOptions extends ProviderOptions {}
@@ -724,7 +724,7 @@ export interface ToolResultPartEncoded extends BasePartEncoded<"tool-result", To
  * Represents provider-specific options that can be associated with a
  * `ToolResultPart` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface ToolResultPartOptions extends ProviderOptions {}
@@ -846,7 +846,7 @@ export interface ToolApprovalResponsePartEncoded
  * Represents provider-specific options that can be associated with a
  * `ToolApprovalResponsePart` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface ToolApprovalResponsePartOptions extends ProviderOptions {}
@@ -951,7 +951,7 @@ export interface ToolApprovalRequestPartEncoded
  * Represents provider-specific options that can be associated with a
  * `ToolApprovalRequestPart` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface ToolApprovalRequestPartOptions extends ProviderOptions {}
@@ -1087,7 +1087,7 @@ export const makeMessage = <const Role extends Message["role"]>(
  * A utility type for specifying the parameters required to construct a
  * specific message for a prompt.
  *
- * @category Utility Types
+ * @category utility types
  * @since 4.0.0
  */
 export type MessageConstructorParams<M extends Message> = Omit<M, typeof MessageTypeId | "role" | "options"> & {
@@ -1176,7 +1176,7 @@ export interface SystemMessageEncoded extends BaseMessageEncoded<"system", Syste
  * Represents provider-specific options that can be associated with a
  * `SystemMessage` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface SystemMessageOptions extends ProviderOptions {}
@@ -1289,7 +1289,7 @@ export type UserMessagePartEncoded = TextPartEncoded | FilePartEncoded
  * Represents provider-specific options that can be associated with a
  * `UserMessage` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface UserMessageOptions extends ProviderOptions {}
@@ -1475,7 +1475,7 @@ export type AssistantMessagePartEncoded =
  * Represents provider-specific options that can be associated with a
  * `AssistantMessage` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface AssistantMessageOptions extends ProviderOptions {}
@@ -1644,7 +1644,7 @@ export type ToolMessagePartEncoded = ToolResultPartEncoded | ToolApprovalRespons
  * Represents provider-specific options that can be associated with a
  * `ToolMessage` through module augmentation.
  *
- * @category ProviderOptions
+ * @category options
  * @since 4.0.0
  */
 export interface ToolMessageOptions extends ProviderOptions {}

package/src/unstable/ai/Telemetry.ts

@@ -335,7 +335,7 @@ export type FormatAttributeName<T extends string | number | symbol> = T extends
  * // Results in attributes: "custom.ai.model_name" and "custom.ai.max_tokens"
  * ```
  *
- * @category utils
+ * @category annotations
  * @since 4.0.0
  */
 export const addSpanAttributes = (
@@ -407,7 +407,7 @@ const addSpanUsageAttributes = addSpanAttributes("gen_ai.usage", String.camelToS
  * }
  * ```
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export type GenAITelemetryAttributeOptions = BaseAttributes & {
@@ -462,7 +462,7 @@ export type GenAITelemetryAttributeOptions = BaseAttributes & {
  * })
  * ```
  *
- * @category utils
+ * @category annotations
  * @since 4.0.0
  */
 export const addGenAIAnnotations: {
@@ -495,7 +495,7 @@ export const addGenAIAnnotations: {
    * })
    * ```
    *
-   * @category utils
+   * @category annotations
    * @since 4.0.0
    */
   (options: GenAITelemetryAttributeOptions): (span: Span) => void
@@ -528,7 +528,7 @@ export const addGenAIAnnotations: {
    * })
    * ```
    *
-   * @category utils
+   * @category annotations
    * @since 4.0.0
    */
   (span: Span, options: GenAITelemetryAttributeOptions): void

package/src/unstable/ai/Tokenizer.ts

@@ -80,7 +80,7 @@ import * as Prompt from "./Prompt.ts"
  * })
  * ```
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class Tokenizer extends Context.Service<Tokenizer, Service>()(

package/src/unstable/ai/Tool.ts

@@ -1595,7 +1595,7 @@ export const providerDefined = <
  * naming conflicts (i.e. `"web_search"`) to instead use custom names (i.e.
  * `"OpenAiWebSearch"`).
  *
- * @category utils
+ * @category models
  * @since 4.0.0
  */
 export class NameMapper<Tools extends ReadonlyArray<Any>> {
@@ -1673,7 +1673,7 @@ export class NameMapper<Tools extends ReadonlyArray<Any>> {
  * console.log(description) // "This is an example tool"
  * ```
  *
- * @category utils
+ * @category getters
  * @since 4.0.0
  */
 export const getDescription = <Tool extends Any>(tool: Tool): string | undefined => {
@@ -1724,7 +1724,7 @@ export const getDescription = <Tool extends Any>(tool: Tool): string | undefined
  * // }
  * ```
  *
- * @category utils
+ * @category getters
  * @since 4.0.0
  */
 export const getJsonSchema = <Tool extends Any>(tool: Tool, options?: {
@@ -1746,7 +1746,7 @@ export const getJsonSchema = <Tool extends Any>(tool: Tool, options?: {
  * `Schema.toJsonSchemaDocument` and any generated definitions are attached as
  * `$defs`.
  *
- * @category utils
+ * @category converting
  * @since 4.0.0
  */
 export const getJsonSchemaFromSchema = <S extends Schema.Top>(schema: S, options?: {
@@ -1942,7 +1942,7 @@ export const Strict = Context.Reference<boolean | undefined>("effect/ai/Tool/Str
  *
  * @see {@link Strict} for the annotation read by this helper
  *
- * @category utils
+ * @category getters
  * @since 4.0.0
  */
 export const getStrictMode = <T extends Any>(tool: T): boolean | undefined => Context.get(tool.annotations, Strict)
@@ -2036,7 +2036,7 @@ function filter(obj: any) {
  * `__proto__` property or a dangerous `constructor.prototype` shape throw a
  * `SyntaxError`.
  *
- * @category utils
+ * @category unsafe
  * @since 4.0.0
  */
 export const unsafeSecureJsonParse = (text: string): unknown => {

package/src/unstable/cli/Command.ts

@@ -2299,7 +2299,11 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
       // 2. Extract global flag tokens
       const allFlagParams = allFlags.flatMap((f) => Param.extractSingleParams(f.flag))
       const globalRegistry = Parser.createFlagRegistry(allFlagParams.filter(Param.isFlagParam))
-      const { flagMap, remainder, errors: globalFlagErrors } = Parser.consumeKnownFlags(tokens, globalRegistry)
+      const { flagMap, remainder, errors: globalFlagErrors } = Parser.consumeGlobalFlags(
+        tokens,
+        command,
+        globalRegistry
+      )
       const emptyArgs: Param.ParsedArgs = { flags: flagMap, arguments: [] }
 
       // 3. Parse command arguments from remaining tokens

package/src/unstable/cli/Param.ts

@@ -1866,7 +1866,7 @@ export const withFallbackPrompt: {
 /**
  * Represent options which can be used to configure variadic parameters.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export type VariadicParamOptions = {

package/src/unstable/cli/Primitive.ts

@@ -561,7 +561,7 @@ export const fileText: Primitive<string> = makePrimitive(
  * Represents options which can be provided to methods that deal with parsing
  * file content.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export type FileParseOptions = {
@@ -625,7 +625,7 @@ export const fileParse = (options?: FileParseOptions): Primitive<unknown> => {
  * Represents options which can be provided to methods that deal with parsing
  * file content and decoding the file content with a `Schema`.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export type FileSchemaOptions = Struct.Simplify<
@@ -774,7 +774,7 @@ export const none: Primitive<never> = makePrimitive("None", () => Effect.fail("T
  * console.log(Primitive.getTypeName(logLevelChoice)) // "choice"
  * ```
  *
- * @category utils
+ * @category getters
  * @since 4.0.0
  */
 export const getTypeName = <A>(primitive: Primitive<A>): string => {