effect 4.0.3 → 4.0.5

package/src/Stream.ts

@@ -20767,6 +20767,9 @@ export const mkUint8Array = <E, R>(self: Stream<Uint8Array, E, R>): Effect.Effec
  *
  * See https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream.
  *
+ * When `signal` aborts, the stream is interrupted even if the reader has
+ * stopped pulling, and the `ReadableStream` closes.
+ *
  * **Example** (Converting to a ReadableStream with services)
  *
  * ```ts import.meta.vitest
@@ -20795,6 +20798,9 @@ export const toReadableStreamWith: {
    *
    * See https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream.
    *
+   * When `signal` aborts, the stream is interrupted even if the reader has
+   * stopped pulling, and the `ReadableStream` closes.
+   *
    * **Example** (Converting to a ReadableStream with services)
    *
    * ```ts import.meta.vitest
@@ -20812,7 +20818,10 @@ export const toReadableStreamWith: {
    */
   <A, XR>(
     context: Context.Context<XR>,
-    options?: { readonly strategy?: QueuingStrategy<A> | undefined }
+    options?: {
+      readonly strategy?: QueuingStrategy<A> | undefined
+      readonly signal?: AbortSignal | undefined
+    }
   ): <E, R extends XR>(self: Stream<A, E, R>) => ReadableStream<A>
   /**
    * Converts the stream to a `ReadableStream` using the provided services.
@@ -20826,6 +20835,9 @@ export const toReadableStreamWith: {
    *
    * See https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream.
    *
+   * When `signal` aborts, the stream is interrupted even if the reader has
+   * stopped pulling, and the `ReadableStream` closes.
+   *
    * **Example** (Converting to a ReadableStream with services)
    *
    * ```ts import.meta.vitest
@@ -20844,18 +20856,28 @@ export const toReadableStreamWith: {
   <A, E, XR, R extends XR>(
     self: Stream<A, E, R>,
     context: Context.Context<XR>,
-    options?: { readonly strategy?: QueuingStrategy<A> | undefined }
+    options?: {
+      readonly strategy?: QueuingStrategy<A> | undefined
+      readonly signal?: AbortSignal | undefined
+    }
   ): ReadableStream<A>
 } = dual(
   (args) => isStream(args[0]),
   <A, E, XR, R extends XR>(
     self: Stream<A, E, R>,
     context: Context.Context<XR>,
-    options?: { readonly strategy?: QueuingStrategy<A> | undefined }
+    options?: {
+      readonly strategy?: QueuingStrategy<A> | undefined
+      readonly signal?: AbortSignal | undefined
+    }
   ): ReadableStream<A> => {
     let currentResolve: (() => void) | undefined = undefined
     let fiber: Fiber.Fiber<void, E> | undefined = undefined
+    let cancelled = false
     const latch = Latch.makeUnsafe(false)
+    const signal = options?.signal
+    // Interrupting the fiber directly also stops a consumer waiting for a pull.
+    const onAbort = () => fiber!.interruptUnsafe()
 
     return new ReadableStream<A>({
       start(controller) {
@@ -20872,12 +20894,18 @@ export const toReadableStreamWith: {
           context
         ))
         fiber.addObserver((exit) => {
-          if (exit._tag === "Failure") {
+          signal?.removeEventListener("abort", onAbort)
+          if (cancelled) return
+          if (exit._tag === "Failure" && signal?.aborted !== true) {
             controller.error(Cause.squash(exit.cause))
           } else {
             controller.close()
           }
         })
+        if (signal !== undefined && fiber.pollUnsafe() === undefined) {
+          if (signal.aborted) onAbort()
+          else signal.addEventListener("abort", onAbort, { once: true })
+        }
       },
       pull() {
         return new Promise<void>((resolve) => {
@@ -20887,6 +20915,7 @@ export const toReadableStreamWith: {
       },
       cancel() {
         if (!fiber) return
+        cancelled = true
         return Effect.runPromise(Effect.asVoid(Fiber.interrupt(fiber)))
       }
     }, options?.strategy)

package/src/String.ts

@@ -1441,6 +1441,12 @@ export const stripMargin = (self: string): string => stripMarginWith(self, "|")
 /**
  * Converts a snake_case string to camelCase.
  *
+ * **Details**
+ *
+ * Keeps the first character, then replaces each later underscore and the
+ * character after it with that character uppercased. A trailing underscore is
+ * dropped. Input made only of an even number of underscores returns `""`.
+ *
  * **Example** (Converting snake_case to camelCase)
  *
  * ```ts import.meta.vitest
@@ -1455,10 +1461,10 @@ export const stripMargin = (self: string): string => stripMarginWith(self, "|")
  * @since 2.0.0
  */
 export const snakeToCamel = (self: string): string => {
-  if (self.length === 0) return self
+  if (self.length === 0 || (self.length % 2 === 0 && self[0] === "_" && /^_+$/.test(self))) return ""
   let str = self[0]
   for (let i = 1; i < self.length; i++) {
-    str += self[i] === "_" ? self[++i].toUpperCase() : self[i]
+    str += self[i] === "_" ? self.charAt(++i).toUpperCase() : self[i]
   }
   return str
 }
@@ -1466,6 +1472,12 @@ export const snakeToCamel = (self: string): string => {
 /**
  * Converts a snake_case string to PascalCase.
  *
+ * **Details**
+ *
+ * Uppercases the first character, then replaces each later underscore and the
+ * character after it with that character uppercased. A trailing underscore is
+ * dropped. Input made only of an even number of underscores returns `""`.
+ *
  * **Example** (Converting snake_case to PascalCase)
  *
  * ```ts import.meta.vitest
@@ -1480,10 +1492,10 @@ export const snakeToCamel = (self: string): string => {
  * @since 2.0.0
  */
 export const snakeToPascal = (self: string): string => {
-  if (self.length === 0) return self
+  if (self.length === 0 || (self.length % 2 === 0 && self[0] === "_" && /^_+$/.test(self))) return ""
   let str = self[0].toUpperCase()
   for (let i = 1; i < self.length; i++) {
-    str += self[i] === "_" ? self[++i].toUpperCase() : self[i]
+    str += self[i] === "_" ? self.charAt(++i).toUpperCase() : self[i]
   }
   return str
 }
@@ -1739,6 +1751,7 @@ const normalizeCase = (
   while (result.charAt(end - 1) === "\0") {
     end--
   }
+  if (start >= end) return ""
 
   // Transform each token independently.
   return result.slice(start, end).split("\0").map(transform).join(delimiter)

package/src/TxRef.ts

@@ -13,6 +13,7 @@
  * @since 4.0.0
  */
 import * as Effect from "./Effect.ts"
+import type { TransactionMetaInner } from "./Effect.ts"
 import { dual } from "./Function.ts"
 import { pipeArguments } from "./Pipeable.ts"
 import type { Pipeable } from "./Pipeable.ts"
@@ -140,10 +141,11 @@ export const makeUnsafe = <A>(initial: A): TxRef<A> => ({
 })
 
 const journalEntry = <A>(state: Effect.Transaction["Service"], self: TxRef<A>) => {
-  let entry = state.journal.get(self)
+  const journal = (state as TransactionMetaInner).journal
+  let entry = journal.get(self)
   if (entry === undefined) {
     entry = { version: self.version, value: self.value, written: false }
-    state.journal.set(self, entry)
+    journal.set(self, entry)
   }
   return entry
 }

package/src/Utils.ts

@@ -12,7 +12,7 @@
  * @since 2.0.0
  */
 import type { Kind, TypeLambda } from "./HKT.ts"
-import { getStackTraceLimit } from "./internal/stackTraceLimit.ts"
+import { getStackTraceLimit, setStackTraceLimit } from "./internal/stackTraceLimit.ts"
 import type * as Types from "./Types.ts"
 
 /**
@@ -209,10 +209,13 @@ const pickInternalCall = (): <A>(body: () => A) => A => {
     }
   }
 
-  const isNotOptimizedAway = getStackTraceLimit() !== 0 &&
-    standard[InternalTypeId](() => new Error().stack)?.includes(InternalTypeId) === true
-
-  return isNotOptimizedAway ? standard[InternalTypeId] : forced[InternalTypeId]
+  const limit = getStackTraceLimit()
+  if (limit === 0) return forced[InternalTypeId]
+  // Only the callback and internal call frames are needed for detection.
+  setStackTraceLimit(2)
+  const error = standard[InternalTypeId](() => new Error())
+  setStackTraceLimit(limit)
+  return error.stack?.includes(InternalTypeId) === true ? standard[InternalTypeId] : forced[InternalTypeId]
 }
 
 /** @internal */

package/src/ai/AiError.ts

@@ -47,7 +47,9 @@ import * as Schema from "../Schema.ts"
 export const HttpRequestDetails = Schema.Struct({
   method: Schema.Literals(["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE", "QUERY"]),
   url: Schema.String,
-  urlParams: Schema.Array(Schema.Tuple([Schema.String, Schema.String])),
+  urlParams: Schema.Array(
+    Schema.Tuple([Schema.String, Schema.Union([Schema.String, Schema.Redacted(Schema.String)])])
+  ),
   hash: Schema.optional(Schema.String),
   headers: Schema.Record(
     Schema.String,

package/src/ai/AnthropicStructuredOutput.ts

@@ -14,8 +14,8 @@ import type * as JsonSchema from "../JsonSchema.ts"
 import * as Rec from "../Record.ts"
 import * as Schema from "../Schema.ts"
 import * as InternalStructuredOutput from "./internal/structured-output.ts"
-import * as LanguageModel from "./LanguageModel.ts"
-import * as OpenAiStructuredOutput from "./OpenAiStructuredOutput.ts"
+import type * as LanguageModel from "./LanguageModel.ts"
+import type * as OpenAiStructuredOutput from "./OpenAiStructuredOutput.ts"
 
 /**
  * Converts a `Schema.Codec` to Anthropic structured-output JSON Schema and a

package/src/ai/Chat.ts

@@ -228,7 +228,7 @@ export interface Chat {
     <Options extends NoExcessProperties<LanguageModel.GenerateTextOptions<{}>, Options>>(
       options: Options & { readonly toolkit?: undefined } & LanguageModel.GenerateTextOptions<{}>
     ): Effect.Effect<
-      LanguageModel.GenerateTextResponse<{}>,
+      LanguageModel.GenerateTextResponse<{}, LanguageModel.ExtractToolParametersModeWithoutToolkit<Options>>,
       LanguageModel.ExtractError<Options>,
       LanguageModel.LanguageModel | LanguageModel.ExtractServices<Options>
     >
@@ -310,7 +310,7 @@ export interface Chat {
     <Options extends NoExcessProperties<LanguageModel.GenerateTextOptions<{}>, Options>>(
       options: Options & { readonly toolkit?: undefined } & LanguageModel.GenerateTextOptions<{}>
     ): Stream.Stream<
-      Response.StreamPart<{}>,
+      Response.StreamPart<{}, LanguageModel.ExtractToolParametersModeWithoutToolkit<Options>>,
       LanguageModel.ExtractError<Options>,
       LanguageModel.LanguageModel | LanguageModel.ExtractServices<Options>
     >

package/src/ai/Decision.ts

@@ -28,9 +28,23 @@ export type TypeId = "~effect/ai/Decision"
  */
 export const TypeId: TypeId = "~effect/ai/Decision"
 
+/**
+ * Decision instructions or descriptions: a string, JSON object, or JSON array.
+ *
+ * **Details**
+ *
+ * TypeScript interfaces lack the index signature required by `Schema.JsonObject`;
+ * use object literals, type aliases, or Schema types instead.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.5
+ */
+export type Description = string | Schema.JsonObject | Schema.JsonArray
+
 /**
  * Decision that assigns the input one label out of a set of criteria.
- * `criteria` maps labels to descriptions.
+ * `criteria` maps labels to descriptions; use `null` for a label without a description.
  *
  * @see {@link classify} for the constructor
  * @see {@link ClassifyAnswer} for the answer produced by this decision
@@ -41,13 +55,14 @@ export const TypeId: TypeId = "~effect/ai/Decision"
  */
 export interface Classify<Label extends string> {
   readonly _tag: "Classify"
-  readonly instructions: string
-  readonly criteria: { readonly [L in Label]: string }
+  readonly instructions: Description
+  readonly criteria: { readonly [L in Label]: Description | null }
 }
 
 /**
  * Decision that places the input on an ordered scale of criteria.
- * `criteria` lists levels from lowest to highest.
+ * `criteria` lists levels from lowest to highest, with labels for answers and
+ * descriptions for the provider.
  *
  * @see {@link rate} for the constructor
  * @see {@link RateAnswer} for the answer produced by this decision
@@ -58,8 +73,8 @@ export interface Classify<Label extends string> {
  */
 export interface Rate<Level extends string> {
   readonly _tag: "Rate"
-  readonly instructions: string
-  readonly criteria: ReadonlyArray<Level>
+  readonly instructions: Description
+  readonly criteria: ReadonlyArray<{ readonly label: Level; readonly description: Description }>
 }
 
 /**
@@ -76,10 +91,10 @@ export interface Rate<Level extends string> {
  */
 export interface Probability {
   readonly _tag: "Probability"
-  readonly instructions: string
+  readonly instructions: Description
   readonly criteria?: {
-    readonly false: string
-    readonly true: string
+    readonly false: Description
+    readonly true: Description
   } | undefined
 }
 
@@ -110,8 +125,9 @@ export interface ClassifyAnswer<Label extends string> {
 /**
  * Answer to a {@link Rate} decision.
  * `rating` is the probability-weighted position on the scale and may fall
- * between two levels, within `[0, criteria.length - 1]`. `label` is the level
- * with the highest probability, choosing the first criteria entry on ties.
+ * between two levels, within `[0, criteria.length - 1]`. `label` is the label
+ * of the level with the highest probability, choosing the first criteria entry
+ * on ties.
  * `confidence` is an optional, provider-defined measure in `[0, 1]`.
  *
  * @stability unstable
@@ -176,6 +192,7 @@ export interface Definition<Input extends Schema.Constraint, Decisions extends R
 
 /**
  * Creates a classification decision from labelled criteria.
+ * Descriptions can be `null` when the label needs no explanation.
  * Throws if fewer than two labels are supplied.
  *
  * **Example** (Choosing a department)
@@ -201,8 +218,8 @@ export interface Definition<Input extends Schema.Constraint, Decisions extends R
  * @since 4.0.0
  */
 export const classify = <Label extends string>(options: {
-  readonly instructions: string
-  readonly criteria: { readonly [L in Label]: string }
+  readonly instructions: Description
+  readonly criteria: { readonly [L in Label]: Description | null }
 }): Classify<Label> => {
   if (Object.keys(options.criteria).length < 2) {
     throw new Error("Decision.classify: criteria must contain at least two labels")
@@ -216,7 +233,9 @@ export const classify = <Label extends string>(options: {
 
 /**
  * Creates a rating decision from an ordered list of criteria.
- * Throws if fewer than two levels or duplicate levels are supplied.
+ * Strings serve as both label and description; use `{ label, description }`
+ * to separate them. Answers use the label.
+ * Throws if fewer than two levels or duplicate labels are supplied.
  *
  * **Example** (Rating frustration)
  *
@@ -229,6 +248,33 @@ export const classify = <Label extends string>(options: {
  * })
  * ```
  *
+ * **Example** (Describing levels with structure)
+ *
+ * ```ts
+ * import { Decision } from "effect/ai"
+ *
+ * const severity = Decision.rate({
+ *   instructions: "How severe is the reported issue?",
+ *   criteria: [
+ *     "cosmetic",
+ *     {
+ *       label: "degraded",
+ *       description: {
+ *         what: "Broken or degraded feature, but workaround exists",
+ *         examples: ["export fails in one browser but works in another"]
+ *       }
+ *     },
+ *     {
+ *       label: "blocking",
+ *       description: {
+ *         what: "Blocking issue; no workaround exists",
+ *         examples: ["cannot log in", "data loss"]
+ *       }
+ *     }
+ *   ]
+ * })
+ * ```
+ *
  * @see {@link classify} for unordered labels
  *
  * @stability unstable
@@ -236,19 +282,22 @@ export const classify = <Label extends string>(options: {
  * @since 4.0.0
  */
 export const rate = <const Level extends string>(options: {
-  readonly instructions: string
-  readonly criteria: ReadonlyArray<Level>
+  readonly instructions: Description
+  readonly criteria: ReadonlyArray<Level | { readonly label: Level; readonly description: Description }>
 }): Rate<Level> => {
   if (options.criteria.length < 2) {
     throw new Error("Decision.rate: criteria must contain at least two levels")
   }
-  if (new Set(options.criteria).size !== options.criteria.length) {
+  const criteria = options.criteria.map((level) =>
+    typeof level === "string" ? { label: level, description: level } : level
+  )
+  if (new Set(criteria.map((level) => level.label)).size !== criteria.length) {
     throw new Error("Decision.rate: criteria must contain distinct levels")
   }
   return {
     _tag: "Rate",
     instructions: options.instructions,
-    criteria: options.criteria
+    criteria
   }
 }
 
@@ -287,10 +336,10 @@ export const rate = <const Level extends string>(options: {
  * @since 4.0.0
  */
 export const probability = (options: {
-  readonly instructions: string
+  readonly instructions: Description
   readonly criteria?: {
-    readonly false: string
-    readonly true: string
+    readonly false: Description
+    readonly true: Description
   } | undefined
 }): Probability => ({
   _tag: "Probability",

package/src/ai/DecisionModel.ts

@@ -290,7 +290,7 @@ const validateAnswer = (
       return { label: answer.label, probabilities, ...(confidence === undefined ? undefined : { confidence }) }
     }
     case "Rate": {
-      const levels = decision.criteria
+      const levels = decision.criteria.map((level) => level.label)
       if (!isFiniteNumber(answer.rating) || answer.rating < 0 || answer.rating > levels.length - 1) {
         return invalidOutput(`Provider returned a rating outside [0, ${levels.length - 1}] for decision "${key}"`)
       }