effect 4.0.0-beta.25 → 4.0.0-beta.27

package/src/SchemaAST.ts

@@ -651,7 +651,7 @@ export class Undefined extends Base {
     return fromConst(this, undefined)
   }
   /** @internal */
-  encodeToNull(): AST {
+  toCodecJson(): AST {
     return replaceEncoding(this, [undefinedToNull])
   }
   /** @internal */
@@ -697,7 +697,7 @@ export class Void extends Base {
     return fromConst(this, undefined)
   }
   /** @internal */
-  encodeToNull(): AST {
+  toCodecJson(): AST {
     return replaceEncoding(this, [undefinedToNull])
   }
   /** @internal */
@@ -3369,3 +3369,128 @@ export const resolveTitle: (ast: AST) => string | undefined = InternalAnnotation
  * @since 4.0.0
  */
 export const resolveDescription: (ast: AST) => string | undefined = InternalAnnotations.resolveDescription
+
+/**
+ * Returns true if the value is a JSON value.
+ *
+ * When a cyclic reference is detected, returns false.
+ *
+ * @internal
+ */
+export function isJson(u: unknown): u is Schema.Json {
+  const seen = new Set<unknown>()
+  return recur(u)
+
+  function recur(u: unknown): boolean {
+    if (u === null || typeof u === "string" || typeof u === "boolean") {
+      return true
+    }
+    if (typeof u === "number") {
+      return globalThis.Number.isFinite(u)
+    }
+    if (typeof u !== "object" || u === undefined) {
+      return false
+    }
+    if (seen.has(u)) {
+      return false
+    }
+    seen.add(u)
+    if (Array.isArray(u)) {
+      return u.every(recur)
+    }
+    return Object.keys(u).every((key) => recur((u as Record<string, unknown>)[key]))
+  }
+}
+
+/** @internal */
+export const Json = new Declaration(
+  [],
+  () => (input, ast) =>
+    isJson(input) ?
+      Effect.succeed(input) :
+      Effect.fail(new Issue.InvalidType(ast, Option.some(input))),
+  {
+    typeConstructor: {
+      _tag: "effect/Json"
+    },
+    generation: {
+      runtime: `Schema.Json`,
+      Type: `Schema.Json`
+    },
+    expected: "JSON value",
+    toCodecJson: () => new Link(unknown, Transformation.passthrough())
+  }
+)
+
+/** @internal */
+export const MutableJson = annotate(Json, {
+  typeConstructor: {
+    _tag: "effect/MutableJson"
+  },
+  generation: {
+    runtime: `Schema.MutableJson`,
+    Type: `Schema.MutableJson`
+  }
+})
+
+/** @internal */
+export const unknownToNull = new Link(
+  null_,
+  new Transformation.Transformation(
+    Getter.passthrough(),
+    Getter.transform(() => null)
+  )
+)
+
+/** @internal */
+export const unknownToJson = new Link(
+  Json,
+  Transformation.passthrough()
+)
+
+/**
+ * Returns true if the value is a StringTree value.
+ *
+ * When a cyclic reference is detected, returns false.
+ *
+ * @internal
+ */
+export function isStringTree(u: unknown): u is Schema.StringTree {
+  const seen = new Set<unknown>()
+  return recur(u)
+
+  function recur(u: unknown): boolean {
+    if (u === undefined || typeof u === "string") {
+      return true
+    }
+    if (typeof u !== "object" || u === null) {
+      return false
+    }
+    if (seen.has(u)) {
+      return false
+    }
+    seen.add(u)
+    if (Array.isArray(u)) {
+      return u.every(recur)
+    }
+    return Object.keys(u).every((key) => recur((u as Record<string, unknown>)[key]))
+  }
+}
+
+const StringTree = new Declaration(
+  [],
+  () => (input, ast) =>
+    isStringTree(input) ?
+      Effect.succeed(input) :
+      Effect.fail(new Issue.InvalidType(ast, Option.some(input))),
+  {
+    expected: "StringTree",
+    toCodecStringTree: () => new Link(unknown, Transformation.passthrough())
+  }
+)
+
+/** @internal */
+export const unknownToStringTree = new Link(
+  StringTree,
+  Transformation.passthrough()
+)

package/src/SchemaGetter.ts

@@ -1517,7 +1517,7 @@ export function dateTimeUtcFromInput<E extends DateTime.DateTime.Input>(): Gette
  * @category FormData
  * @since 4.0.0
  */
-export function decodeFormData(): Getter<Schema.TreeObject<string | Blob>, FormData> {
+export function decodeFormData(): Getter<Schema.TreeRecord<string | Blob>, FormData> {
   return transform((input) => makeTreeRecord(Array.from(input.entries())))
 }
 
@@ -1594,7 +1594,7 @@ export function encodeFormData(): Getter<FormData, unknown> {
  * @category URLSearchParams
  * @since 4.0.0
  */
-export function decodeURLSearchParams(): Getter<Schema.TreeObject<string>, URLSearchParams> {
+export function decodeURLSearchParams(): Getter<Schema.TreeRecord<string>, URLSearchParams> {
   return transform((input) => makeTreeRecord(Array.from(input.entries())))
 }
 
@@ -1699,7 +1699,7 @@ function bracketPathToTokens(bracketPath: string): Array<string | number> {
  */
 export function makeTreeRecord<A>(
   bracketPathEntries: ReadonlyArray<readonly [bracketPath: string, value: A]>
-): Schema.TreeObject<A> {
+): Schema.TreeRecord<A> {
   const out: any = {}
   bracketPathEntries.forEach(([key, value]) => {
     const tokens = bracketPathToTokens(key)

package/src/SchemaRepresentation.ts

@@ -1741,6 +1741,12 @@ export const toSchemaDefaultReviver: Reviver<Schema.Top> = (s, recur) => {
       case "URLSearchParams":
         return Schema.URLSearchParams
       // effect types
+      case "effect/Option":
+        return Schema.Option(typeParameters[0])
+      case "effect/Result":
+        return Schema.Result(typeParameters[0], typeParameters[1])
+      case "effect/Redacted":
+        return Schema.Redacted(typeParameters[0])
       case "effect/DateTime.TimeZone":
         return Schema.TimeZone
       case "effect/DateTime.TimeZone.Named":
@@ -1753,6 +1759,8 @@ export const toSchemaDefaultReviver: Reviver<Schema.Top> = (s, recur) => {
         return Schema.DateTimeZoned
       case "effect/BigDecimal":
         return Schema.BigDecimal
+      case "effect/Chunk":
+        return Schema.Chunk(typeParameters[0])
       case "effect/Cause":
         return Schema.Cause(typeParameters[0], typeParameters[1])
       case "effect/Cause/Failure":
@@ -1761,18 +1769,14 @@ export const toSchemaDefaultReviver: Reviver<Schema.Top> = (s, recur) => {
         return Schema.Duration
       case "effect/Exit":
         return Schema.Exit(typeParameters[0], typeParameters[1], typeParameters[2])
+      case "effect/Json":
+        return Schema.Json
+      case "effect/MutableJson":
+        return Schema.MutableJson
       case "effect/HashMap":
         return Schema.HashMap(typeParameters[0], typeParameters[1])
-      case "effect/Option":
-        return Schema.Option(typeParameters[0])
-      case "effect/Redacted":
-        return Schema.Redacted(typeParameters[0])
-      case "effect/Result":
-        return Schema.Result(typeParameters[0], typeParameters[1])
       case "effect/HashSet":
         return Schema.HashSet(typeParameters[0])
-      case "effect/Chunk":
-        return Schema.Chunk(typeParameters[0])
     }
   }
 }

package/src/Stdio.ts

@@ -1,10 +1,12 @@
 /**
  * @since 4.0.0
  */
+import * as Effect from "./Effect.ts"
+import * as Layer from "./Layer.ts"
 import type { PlatformError } from "./PlatformError.ts"
 import * as ServiceMap from "./ServiceMap.ts"
-import type * as Sink from "./Sink.ts"
-import type * as Stream from "./Stream.ts"
+import * as Sink from "./Sink.ts"
+import * as Stream from "./Stream.ts"
 
 /**
  * @since 4.0.0
@@ -24,6 +26,7 @@ export const TypeId: TypeId = "~effect/Stdio"
  */
 export interface Stdio {
   readonly [TypeId]: TypeId
+  readonly args: Effect.Effect<ReadonlyArray<string>>
   readonly stdout: Sink.Sink<void, string | Uint8Array, never, PlatformError>
   readonly stderr: Sink.Sink<void, string | Uint8Array, never, PlatformError>
   readonly stdin: Stream.Stream<Uint8Array, PlatformError>
@@ -42,3 +45,19 @@ export const make = (options: Omit<Stdio, TypeId>): Stdio => ({
   [TypeId]: TypeId,
   ...options
 })
+
+/**
+ * @since 4.0.0
+ * @category Layers
+ */
+export const layerTest = (impl: Partial<Stdio>): Layer.Layer<Stdio> =>
+  Layer.succeed(
+    Stdio,
+    make({
+      args: Effect.succeed([]),
+      stdout: Sink.drain,
+      stderr: Sink.drain,
+      stdin: Stream.empty,
+      ...impl
+    })
+  )

package/src/index.ts

@@ -1160,7 +1160,7 @@ export * as Equivalence from "./Equivalence.ts"
  *
  * // Opt in to error reporting with Effect.withErrorReporting
  * const program = Effect.gen(function*() {
- *   yield* new RateLimitError({ retryAfter: 60 })
+ *   return yield* new RateLimitError({ retryAfter: 60 })
  * }).pipe(
  *   Effect.withErrorReporting,
  *   Effect.provide(ErrorReporter.layer([consoleReporter]))

package/src/internal/schema/representation.ts

@@ -341,11 +341,11 @@ export function toJsonSchemaMultiDocument(
   function on(schema: SchemaRepresentation.Representation): JsonSchema.JsonSchema {
     switch (schema._tag) {
       case "Any":
-        return {}
       case "Unknown":
+      case "ObjectKeyword":
+        return {}
       case "Void":
       case "Undefined":
-      case "ObjectKeyword":
         return { type: "null" }
       case "BigInt":
         return {
@@ -494,10 +494,14 @@ export function toJsonSchemaMultiDocument(
         }
 
         out.additionalProperties = additionalProperties
-        const patternProperties: Record<string, JsonSchema.JsonSchema> = {}
+        const patternProperties: Record<string, JsonSchema.JsonSchema | false> = {}
         // Handle index signatures
         for (const is of schema.indexSignatures) {
-          const type = recur(is.type)
+          let type: JsonSchema.JsonSchema | false = recur(is.type)
+          // Collapse unannotated Never ({ not: {} }) to false, but keep annotated schemas as objects.
+          if (Object.keys(type).length === 1 && "not" in type) {
+            type = false
+          }
           const patterns = getParameterPatterns(is.parameter)
           if (patterns.length > 0) {
             for (const pattern of patterns) {

package/src/internal/schema/to-codec.ts

@@ -1,8 +1,6 @@
 import { memoize } from "../../Function.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as AST from "../../SchemaAST.ts"
-import * as Getter from "../../SchemaGetter.ts"
-import * as Transformation from "../../SchemaTransformation.ts"
 import * as InternalSchema from "./schema.ts"
 
 /** @internal */
@@ -16,8 +14,6 @@ export const toCodecJson = AST.toCodec((ast) => {
 
 function toCodecJsonBase(ast: AST.AST): AST.AST {
   switch (ast._tag) {
-    case "Unknown":
-    case "ObjectKeyword":
     case "Declaration": {
       const getLink = ast.annotations?.toCodecJson ?? ast.annotations?.toCodec
       if (Predicate.isFunction(getLink)) {
@@ -28,18 +24,20 @@ function toCodecJsonBase(ast: AST.AST): AST.AST {
         const to = toCodecJson(link.to)
         return AST.replaceEncoding(ast, to === link.to ? [link] : [new AST.Link(to, link.transformation)])
       }
-      return AST.replaceEncoding(ast, [unknownToNull])
+      return AST.replaceEncoding(ast, [AST.unknownToNull])
     }
+    case "Unknown":
+    case "ObjectKeyword":
+      return AST.replaceEncoding(ast, [AST.unknownToJson])
     case "Undefined":
     case "Void":
-      return ast.encodeToNull()
+    case "Literal":
+    case "Number":
+      return ast.toCodecJson()
     case "UniqueSymbol":
     case "Symbol":
     case "BigInt":
       return ast.toCodecStringTree()
-    case "Literal":
-    case "Number":
-      return ast.toCodecJson()
     case "Objects": {
       if (ast.propertySignatures.some((ps) => typeof ps.name !== "string")) {
         throw new globalThis.Error("Objects property names must be strings", { cause: ast })
@@ -110,14 +108,6 @@ export function makeReorder(getPriority: (ast: AST.AST) => number) {
   }
 }
 
-const unknownToNull = new AST.Link(
-  AST.null,
-  new Transformation.Transformation(
-    Getter.passthrough(),
-    Getter.transform(() => null)
-  )
-)
-
 /** @internal */
 export const toCodecIso = memoize((ast: AST.AST): AST.AST => {
   const out = toCodecIsoBase(ast)

package/src/unstable/ai/AiError.ts

@@ -756,7 +756,8 @@ export class InvalidOutputError extends Schema.ErrorClass<InvalidOutputError>(
  * import { AiError } from "effect/unstable/ai"
  *
  * const error = new AiError.StructuredOutputError({
- *   description: "Expected a valid JSON object"
+ *   description: "Expected a valid JSON object",
+ *   responseText: "{\"foo\":}"
  * })
  *
  * console.log(error.isRetryable) // true
@@ -772,6 +773,7 @@ export class StructuredOutputError extends Schema.ErrorClass<StructuredOutputErr
 )({
   _tag: Schema.tag("StructuredOutputError"),
   description: Schema.String,
+  responseText: Schema.String,
   metadata: providerMetadataWithDefaults<StructuredOutputErrorMetadata>(),
   usage: Schema.optional(UsageInfo)
 }) {
@@ -798,16 +800,18 @@ export class StructuredOutputError extends Schema.ErrorClass<StructuredOutputErr
    * import { AiError } from "effect/unstable/ai"
    *
    * declare const schemaError: Schema.SchemaError
+   * declare const rawText: string
    *
-   * const parseError = AiError.StructuredOutputError.fromSchemaError(schemaError)
+   * const parseError = AiError.StructuredOutputError.fromSchemaError(schemaError, rawText)
    * ```
    *
    * @since 1.0.0
    * @category constructors
    */
-  static fromSchemaError(error: Schema.SchemaError): StructuredOutputError {
+  static fromSchemaError(error: Schema.SchemaError, responseText: string): StructuredOutputError {
     return new StructuredOutputError({
-      description: error.message
+      description: error.message,
+      responseText
     })
   }
 

package/src/unstable/ai/LanguageModel.ts

@@ -1864,29 +1864,32 @@ export const getObjectName = <StructuredOutputSchema extends Schema.Top>(
 const resolveStructuredOutput = Effect.fnUntraced(function*<
   StructuredOutputSchema extends Schema.Top
 >(response: ReadonlyArray<Response.AllParts<any>>, schema: StructuredOutputSchema) {
-  const text: Array<string> = []
+  const texts: Array<string> = []
   for (const part of response) {
     if (part.type === "text") {
-      text.push(part.text)
+      texts.push(part.text)
     }
   }
 
+  const text = texts.join("")
+
   if (text.length === 0) {
     return yield* AiError.make({
       module: "LanguageModel",
       method: "generateObject",
       reason: new AiError.StructuredOutputError({
-        description: "No text content in response"
+        description: "No text content in response",
+        responseText: text
       })
     })
   }
 
   const decode = Schema.decodeEffect(Schema.fromJsonString(schema))
-  return yield* Effect.mapError(decode(text.join("")), (error) =>
+  return yield* Effect.mapError(decode(text), (error) =>
     AiError.make({
       module: "LanguageModel",
       method: "generateObject",
-      reason: AiError.StructuredOutputError.fromSchemaError(error)
+      reason: AiError.StructuredOutputError.fromSchemaError(error, text)
     }))
 })
 

package/src/unstable/cli/CliError.ts

@@ -2,6 +2,7 @@
  * @since 4.0.0
  */
 import * as Predicate from "../../Predicate.ts"
+import * as Runtime from "../../Runtime.ts"
 import * as Schema from "../../Schema.ts"
 
 /**
@@ -107,7 +108,7 @@ export type CliError =
  * // In CLI parsing context
  * const parseCommand = Effect.gen(function*() {
  *   // If parsing encounters unknown flag
- *   return yield* Effect.fail(unrecognizedError)
+ *   return yield* unrecognizedError
  * })
  * ```
  *
@@ -200,7 +201,7 @@ export class DuplicateOption extends Schema.ErrorClass(`${TypeId}/DuplicateOptio
  *   Effect.gen(function*() {
  *     const apiKey = options["api-key"]
  *     if (!apiKey) {
- *       return yield* Effect.fail(missingOptionError)
+ *       return yield* missingOptionError
  *     }
  *     return apiKey
  *   })
@@ -245,7 +246,7 @@ export class MissingOption extends Schema.ErrorClass(`${TypeId}/MissingOption`)(
  * const parseArguments = (args: Array<string>) =>
  *   Effect.gen(function*() {
  *     if (args.length === 0) {
- *       return yield* Effect.fail(missingArgError)
+ *       return yield* missingArgError
  *     }
  *     return args[0]
  *   })
@@ -353,7 +354,7 @@ export class InvalidValue extends Schema.ErrorClass(`${TypeId}/InvalidValue`)({
  *   Effect.gen(function*() {
  *     const validCommands = ["deploy", "destroy", "status"]
  *     if (!validCommands.includes(subcommand)) {
- *       return yield* Effect.fail(unknownSubcommandError)
+ *       return yield* unknownSubcommandError
  *     }
  *     return subcommand
  *   })
@@ -386,61 +387,6 @@ export class UnknownSubcommand extends Schema.ErrorClass(`${TypeId}/UnknownSubco
   }
 }
 
-/**
- * Control flow indicator when help is requested via --help flag.
- * This is not an error but uses the error channel for control flow.
- *
- * @example
- * ```ts
- * import { Effect } from "effect"
- * import { CliError } from "effect/unstable/cli"
- *
- * const showHelpIndicator = new CliError.ShowHelp({
- *   commandPath: ["myapp", "deploy", "production"]
- * })
- *
- * console.log(showHelpIndicator.message)
- * // "Help requested"
- *
- * // In help flag handling
- * const handleHelpFlag = (hasHelpFlag: boolean) =>
- *   Effect.gen(function*() {
- *     if (hasHelpFlag) {
- *       return yield* Effect.fail(showHelpIndicator)
- *     }
- *     return "continuing with command"
- *   })
- *
- * // In error handling
- * const handleCliErrors = (error: CliError.CliError): void => {
- *   if (error._tag === "ShowHelp") {
- *     // Display help for the command path
- *     console.log(`Displaying help for: ${error.commandPath.join(" ")}`)
- *   }
- *   // Handle other errors...
- * }
- * ```
- *
- * @since 4.0.0
- * @category models
- */
-export class ShowHelp extends Schema.ErrorClass(`${TypeId}/ShowHelp`)({
-  _tag: Schema.tag("ShowHelp"),
-  commandPath: Schema.Array(Schema.String)
-}) {
-  /**
-   * @since 4.0.0
-   */
-  readonly [TypeId] = TypeId
-
-  /**
-   * @since 4.0.0
-   */
-  override get message() {
-    return "Help requested"
-  }
-}
-
 /**
  * Wrapper for user (handler) errors to unify under CLI error channel when desired.
  *
@@ -485,3 +431,45 @@ export class UserError extends Schema.ErrorClass(`${TypeId}/UserError`)({
    */
   readonly [TypeId] = TypeId
 }
+
+const NonShowHelpErrors: Schema.Union<
+  readonly [
+    typeof UnrecognizedOption,
+    typeof DuplicateOption,
+    typeof MissingOption,
+    typeof MissingArgument,
+    typeof InvalidValue,
+    typeof UnknownSubcommand,
+    typeof UserError
+  ]
+> = Schema.Union([
+  UnrecognizedOption,
+  DuplicateOption,
+  MissingOption,
+  MissingArgument,
+  InvalidValue,
+  UnknownSubcommand,
+  UserError
+])
+
+/**
+ * Control flow indicator when help is requested via --help flag.
+ * This is not an error but uses the error channel for control flow.
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export class ShowHelp extends Schema.ErrorClass(`${TypeId}/ShowHelp`)({
+  _tag: Schema.tag("ShowHelp"),
+  commandPath: Schema.Array(Schema.String),
+  errors: Schema.Array(NonShowHelpErrors)
+}) {
+  readonly [TypeId] = TypeId
+
+  override readonly [Runtime.errorExitCode] = this.errors.length ? 1 : 0
+  override readonly [Runtime.errorReported] = false
+
+  override get message() {
+    return "Help requested"
+  }
+}