effect 4.0.0-beta.106 → 4.0.0-beta.107

package/src/SchemaRepresentation.ts

@@ -606,17 +606,37 @@ export const makeFilterGroupReviver: <P>(
  *
  * **When to use**
  *
- * Use when each JSON Schema node must be transformed before it is translated.
+ * Use when you need to configure pattern handling or transform each JSON Schema node before translation.
+ *
+ * **Details**
+ *
+ * `patterns` controls pattern constraints reached during best-effort translation, including `pattern`, the keys of
+ * `patternProperties`, and patterns nested in `propertyNames`:
+ *
+ * - `"error"` rejects the document and is the default.
+ * - `"ignore"` skips the constraint.
+ * - `"apply"` compiles and enforces the constraint with the runtime's native regular expression engine.
  *
  * **Gotchas**
  *
- * `onEnter` must return a JSON Schema object. Its result is used directly, and exceptions raised by the callback pass through unchanged.
+ * Use `patterns: "apply"` only for trusted documents because regular expression evaluation may block for an unbounded
+ * amount of time. `patterns: "ignore"` weakens validation by accepting values that the source document may reject.
+ * Ignoring `patternProperties` also skips its value constraints and `additionalProperties`, because matching keys cannot
+ * be determined without evaluating the patterns.
+ * `onEnter` must return a JSON Schema object. Its result is used directly, and exceptions raised by the callback pass
+ * through unchanged.
  *
  * @category models
  * @since 4.0.0
  */
 export interface FromJsonSchemaOptions {
   readonly onEnter?: ((schema: JsonSchema.JsonSchema) => JsonSchema.JsonSchema) | undefined
+  /**
+   * Controls how reached JSON Schema regular expression patterns are imported.
+   *
+   * @default "error"
+   */
+  readonly patterns?: "error" | "ignore" | "apply" | undefined
 }
 
 /**
@@ -1160,7 +1180,10 @@ export function fromRepresentations(
  *
  * **Gotchas**
  *
- * Import is best-effort. Built-in declarations and checks are reconstructed with importer-owned revivers. Callback results are used directly, and exceptions raised by a callback pass through unchanged.
+ * Import is best-effort. Built-in declarations and checks are reconstructed with importer-owned revivers. Pattern
+ * constraints reached during translation cause an error by default. Use `patterns: "apply"` only for trusted documents,
+ * or `patterns: "ignore"` to weaken validation explicitly. Callback results are used directly, and exceptions raised by a
+ * callback pass through unchanged.
  *
  * @see {@link fromJsonSchemaMultiDocument} for multiple roots sharing definitions
  * @see {@link toRepresentation} for converting the result to a representation document
@@ -1184,7 +1207,9 @@ export function fromJsonSchemaDocument(
  *
  * **Gotchas**
  *
- * Only definitions reachable from a root are translated. Callback results are used directly, and exceptions raised by a callback pass through unchanged.
+ * Only definitions reachable from a root are translated. Pattern constraints reached during translation cause an error
+ * by default. Use `patterns: "apply"` only for trusted documents, or `patterns: "ignore"` to weaken validation explicitly.
+ * Callback results are used directly, and exceptions raised by a callback pass through unchanged.
  *
  * @see {@link fromJsonSchemaDocument} for a single root
  * @see {@link toRepresentations} for converting the returned schema ASTs to a representation document

package/src/Stream.ts

@@ -19270,39 +19270,16 @@ export const mkString = <E, R>(self: Stream<string, E, R>): Effect.Effect<string
  * await Effect.runPromise(program) // => [1, 2, 3, 4]
  * ```
  *
+ * **Gotchas**
+ *
+ * This materializes the full content in memory. The source stream must not
+ * reuse or mutate emitted buffers, which are retained until collection completes.
+ *
  * @category destructors
  * @since 4.0.0
  */
 export const mkArrayBuffer = <E, R>(self: Stream<Uint8Array, E, R>): Effect.Effect<ArrayBuffer, E, R> =>
-  Effect.map(
-    Channel.runFold(
-      self.channel,
-      (): {
-        bytes: number
-        readonly arrays: Array<Uint8Array>
-      } => ({
-        bytes: 0,
-        arrays: []
-      }),
-      (acc, chunk) => {
-        for (let i = 0; i < chunk.length; i++) {
-          acc.bytes += chunk[i].length
-          acc.arrays.push(chunk[i])
-        }
-        return acc
-      }
-    ),
-    ({ arrays, bytes }) => {
-      const result = new Uint8Array(bytes)
-      let offset = 0
-      for (let i = 0; i < arrays.length; i++) {
-        const array = arrays[i]
-        result.set(array, offset)
-        offset += array.length
-      }
-      return result.buffer
-    }
-  )
+  Effect.map(Channel.mkUint8Array(self.channel), (bytes) => bytes.buffer)
 
 /**
  * Concatenates the stream's `Uint8Array` chunks into a single `Uint8Array`.
@@ -19321,11 +19298,16 @@ export const mkArrayBuffer = <E, R>(self: Stream<Uint8Array, E, R>): Effect.Effe
  * await Effect.runPromise(program)
  * ```
  *
+ * **Gotchas**
+ *
+ * This materializes the full content in memory. The source stream must not
+ * reuse or mutate emitted buffers, which are retained until collection completes.
+ *
  * @category destructors
  * @since 4.0.0
  */
 export const mkUint8Array = <E, R>(self: Stream<Uint8Array, E, R>): Effect.Effect<Uint8Array, E, R> =>
-  Effect.map(mkArrayBuffer(self), (buffer) => new Uint8Array(buffer))
+  Channel.mkUint8Array(self.channel)
 
 /**
  * Converts the stream to a `ReadableStream` using the provided services.

package/src/internal/schema/fromJsonSchemaDocument.ts

@@ -743,7 +743,7 @@ function translateJsonSchemaMultiDocument(
       case "string":
         return {
           _tag: "String",
-          checks: collectStringChecks(schema)
+          checks: collectStringChecks(schema, path)
         }
       case "number":
       case "integer":
@@ -791,12 +791,23 @@ function translateJsonSchemaMultiDocument(
     }
   }
 
-  function collectStringChecks(schema: JsonSchema.JsonSchema): Array<Check> {
+  function importPatternChecks(pattern: string, path: Path): Array<Check> {
+    switch (options?.patterns ?? "error") {
+      case "error":
+        throw errorWithPath(`Pattern encountered while patterns is set to "error"`, path)
+      case "ignore":
+        return []
+      case "apply":
+        return [jsonSchemaFilter("effect/schema/isPattern", { source: pattern, flags: "" })]
+    }
+  }
+
+  function collectStringChecks(schema: JsonSchema.JsonSchema, path: Path): Array<Check> {
     const checks: Array<Check> = []
     addNumberCheck(checks, schema.minLength, "effect/schema/isMinLength", "minLength")
     addNumberCheck(checks, schema.maxLength, "effect/schema/isMaxLength", "maxLength")
     if (typeof schema.pattern === "string") {
-      checks.push(jsonSchemaFilter("effect/schema/isPattern", { source: schema.pattern, flags: "" }))
+      checks.push(...importPatternChecks(schema.pattern, [...path, "pattern"]))
     }
     return checks
   }
@@ -856,10 +867,12 @@ function translateJsonSchemaMultiDocument(
       !Array.isArray(schema.patternProperties)
     ) {
       for (const [pattern, value] of Object.entries(schema.patternProperties)) {
+        const checks = importPatternChecks(pattern, [...path, "patternProperties", pattern])
+        if (checks.length === 0) return [{ parameter: string, type: unknown }]
         signatures.push({
           parameter: {
             _tag: "String",
-            checks: [jsonSchemaFilter("effect/schema/isPattern", { source: pattern, flags: "" })]
+            checks
           },
           type: recur(value, [...path, "patternProperties", pattern])
         })

package/src/unstable/cli/Argument.ts

@@ -719,7 +719,8 @@ export const map: {
  *       ? Effect.succeed(file)
  *       : Effect.fail(
  *         new CliError.UserError({
- *           cause: new Error("Only .txt files allowed")
+ *           cause: new Error(`Unsupported file extension: ${file}`),
+ *           userMessage: "Only .txt files allowed"
  *         })
  *       )
  *   )
@@ -768,7 +769,8 @@ export const mapEffect: {
    *       ? Effect.succeed(file)
    *       : Effect.fail(
    *         new CliError.UserError({
-   *           cause: new Error("Only .txt files allowed")
+   *           cause: new Error(`Unsupported file extension: ${file}`),
+   *           userMessage: "Only .txt files allowed"
    *         })
    *       )
    *   )
@@ -817,7 +819,8 @@ export const mapEffect: {
    *       ? Effect.succeed(file)
    *       : Effect.fail(
    *         new CliError.UserError({
-   *           cause: new Error("Only .txt files allowed")
+   *           cause: new Error(`Unsupported file extension: ${file}`),
+   *           userMessage: "Only .txt files allowed"
    *         })
    *       )
    *   )

package/src/unstable/cli/CliError.ts

@@ -478,6 +478,10 @@ export class UnknownSubcommand extends Schema.TaggedError<UnknownSubcommand>(
 /**
  * Error wrapper for user handler failures in the CLI error channel.
  *
+ * `userMessage` can provide safe, user-facing text independently of the
+ * underlying cause. When omitted or empty, `message` uses a non-empty string
+ * cause or `Error.message`, then falls back to `"An error occurred"`.
+ *
  * **Example** (Wrapping user errors)
  *
  * ```ts import.meta.vitest
@@ -486,7 +490,8 @@ export class UnknownSubcommand extends Schema.TaggedError<UnknownSubcommand>(
  *
  * // Wrapping user errors
  * const userError = new CliError.UserError({
- *   cause: new Error("Database connection failed")
+ *   cause: new Error("Database connection failed for postgres://localhost"),
+ *   userMessage: "Could not connect to the database"
  * })
  *
  * // In command handler
@@ -516,7 +521,8 @@ export class UnknownSubcommand extends Schema.TaggedError<UnknownSubcommand>(
 export class UserError extends Schema.TaggedError<UserError>(
   `${TypeId}/UserError`
 )("UserError", {
-  cause: Schema.Defect()
+  cause: Schema.Defect(),
+  userMessage: Schema.optionalKey(Schema.String)
 }) {
   /**
    * Marks this value as a user handler error for runtime guards.
@@ -524,6 +530,26 @@ export class UserError extends Schema.TaggedError<UserError>(
    * @since 4.0.0
    */
   readonly [TypeId] = TypeId
+
+  /**
+   * Controls whether the runtime logger should report this error. The CLI
+   * runner sets this to `false` after rendering the error itself.
+   *
+   * @since 4.0.0
+   */
+  override [Runtime.errorReported] = true
+
+  /**
+   * Returns the explicit user-facing message or a safe fallback from `cause`.
+   *
+   * @since 4.0.0
+   */
+  override get message() {
+    if (this.userMessage) return this.userMessage
+    if (typeof this.cause === "string" && this.cause) return this.cause
+    if (this.cause instanceof Error && this.cause.message) return this.cause.message
+    return "An error occurred"
+  }
 }
 
 /**

package/src/unstable/cli/Command.ts

@@ -22,6 +22,7 @@ import type * as Path from "../../Path.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as References from "../../References.ts"
 import * as Result from "../../Result.ts"
+import * as Runtime from "../../Runtime.ts"
 import * as Stdio from "../../Stdio.ts"
 import * as Terminal from "../../Terminal.ts"
 import type { Contravariant, Covariant, NoInfer, Simplify } from "../../Types.ts"
@@ -2669,18 +2670,26 @@ const getOutOfScopeGlobalFlagErrors = (
 
 const showHelp = <Name extends string, Input, E, R, ContextInput>(
   command: Command<Name, Input, ContextInput, E, R>,
-  error: CliError.ShowHelp
+  error: CliError.ShowHelp,
+  renderErrors: boolean
 ): Effect.Effect<void, CliError.CliError, Environment> =>
   Effect.gen(function*() {
     const { builtIns } = yield* CliConfig.CliConfig
     const formatter = yield* CliOutput.Formatter
     const helpDoc = yield* getHelpForCommandPath(command, error.commandPath, builtIns)
     yield* Console.log(formatter.formatHelpDoc(helpDoc))
-    if (error.errors.length > 0) {
+    if (renderErrors && error.errors.length > 0) {
       yield* Console.error(formatter.formatErrors(error.errors as any))
     }
   })
 
+const showUserError = (error: CliError.UserError): Effect.Effect<void> =>
+  Effect.gen(function*() {
+    const formatter = yield* CliOutput.Formatter
+    yield* Console.error(formatter.formatError(error))
+    error[Runtime.errorReported] = false
+  })
+
 /**
  * Runs a command using the arguments supplied by the `Stdio` service.
  *
@@ -2689,6 +2698,11 @@ const showHelp = <Name extends string, Input, E, R, ContextInput>(
  * Use when command-line arguments should come from `Stdio` at the application
  * entry point.
  *
+ * Help documents are always rendered. By default, parse error details and
+ * `CliError.UserError` failures are also rendered with the installed
+ * `CliOutput.Formatter` before the error is rethrown. Set `renderErrors` to
+ * `false` when the host application owns error rendering.
+ *
  * **Example** (Running commands with standard input)
  *
  * ```ts import.meta.vitest
@@ -2746,6 +2760,11 @@ export const run: {
    * Use when command-line arguments should come from `Stdio` at the application
    * entry point.
    *
+   * Help documents are always rendered. By default, parse error details and
+   * `CliError.UserError` failures are also rendered with the installed
+   * `CliOutput.Formatter` before the error is rethrown. Set `renderErrors` to
+   * `false` when the host application owns error rendering.
+   *
    * **Example** (Running commands with standard input)
    *
    * ```ts import.meta.vitest
@@ -2797,6 +2816,7 @@ export const run: {
   (
     config: {
       readonly version: string
+      readonly renderErrors?: boolean | undefined
     }
   ): <Name extends string, Input, E, R, ContextInput>(
     command: Command<Name, Input, ContextInput, E, R>
@@ -2809,6 +2829,11 @@ export const run: {
    * Use when command-line arguments should come from `Stdio` at the application
    * entry point.
    *
+   * Help documents are always rendered. By default, parse error details and
+   * `CliError.UserError` failures are also rendered with the installed
+   * `CliOutput.Formatter` before the error is rethrown. Set `renderErrors` to
+   * `false` when the host application owns error rendering.
+   *
    * **Example** (Running commands with standard input)
    *
    * ```ts import.meta.vitest
@@ -2861,12 +2886,14 @@ export const run: {
     command: Command<Name, Input, ContextInput, E, R>,
     config: {
       readonly version: string
+      readonly renderErrors?: boolean | undefined
     }
   ): Effect.Effect<void, E | CliError.CliError, R | Environment>
 } = dual(2, <Name extends string, Input, E, R, ContextInput>(
   command: Command<Name, Input, ContextInput, E, R>,
   config: {
     readonly version: string
+    readonly renderErrors?: boolean | undefined
   }
 ) =>
   Stdio.Stdio.use(({ args }) =>
@@ -2884,6 +2911,11 @@ export const run: {
  * Use when you need to test CLI applications or programmatically execute
  * commands with specific arguments.
  *
+ * Help documents are always rendered. By default, parse error details and
+ * `CliError.UserError` failures are also rendered with the installed
+ * `CliOutput.Formatter` before the error is rethrown. Set `renderErrors` to
+ * `false` when the host application owns error rendering.
+ *
  * **Example** (Running commands with explicit arguments)
  *
  * ```ts import.meta.vitest
@@ -2937,6 +2969,7 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
   command: Command<Name, Input, ContextInput, E, R>,
   config: {
     readonly version: string
+    readonly renderErrors?: boolean | undefined
   }
 ): (
   input: ReadonlyArray<string>
@@ -3003,7 +3036,7 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
             }))
             if (shouldRun) {
               yield* Console.log()
-              yield* runWith(command, config)(wizardArgs.slice(1))
+              yield* runWith(command, { ...config, renderErrors: false })(wizardArgs.slice(1))
             }
           }).pipe(
             Effect.catchTag("QuitError", () => Console.log(Wizard.renderQuit()))
@@ -3051,7 +3084,14 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
         CliError.isCliError(error) && error._tag === "ShowHelp"
           ? Result.succeed(error)
           : Result.fail(error),
-      (error) => Effect.andThen(showHelp(command, error), Effect.fail(error))
+      (error) => Effect.andThen(showHelp(command, error, config.renderErrors !== false), Effect.fail(error))
+    ),
+    Effect.catchFilter(
+      (error) =>
+        config.renderErrors !== false && CliError.isCliError(error) && error._tag === "UserError"
+          ? Result.succeed(error)
+          : Result.fail(error),
+      (error) => Effect.andThen(showUserError(error), Effect.fail(error))
     ),
     Effect.catchFilter(
       (e) =>

package/src/unstable/http/Multipart.ts

@@ -602,7 +602,7 @@ class FileImpl extends PartBase implements File {
     this.contentType = info.contentType
     this.content = Stream.fromChannel(channel)
     this.contentEffect = channel.pipe(
-      collectUint8Array,
+      Channel.mkUint8Array,
       Effect.mapError((cause) => MultipartError.fromReason("InternalError", cause))
     )
   }
@@ -635,24 +635,15 @@ const defaultWriteFile = (path: string, file: File) =>
  * **Gotchas**
  *
  * This materializes the full content in memory.
+ * The source channel must not reuse or mutate emitted buffers, which are retained
+ * until collection completes.
  *
  * @category converting
  * @since 4.0.0
  */
 export const collectUint8Array = <OE, OD, R>(
   self: Channel.Channel<Arr.NonEmptyReadonlyArray<Uint8Array>, OE, OD, unknown, unknown, unknown, R>
-): Effect.Effect<Uint8Array<ArrayBuffer>, OE, R> =>
-  Channel.runFold(self, constant(new Uint8Array(0)), (accumulator, chunk) => {
-    const totalLength = chunk.reduce((sum, element) => sum + element.length, accumulator.length)
-    const newAccumulator = new Uint8Array(totalLength)
-    newAccumulator.set(accumulator, 0)
-    let offset = accumulator.length
-    for (const element of chunk) {
-      newAccumulator.set(element, offset)
-      offset += element.length
-    }
-    return newAccumulator
-  })
+): Effect.Effect<Uint8Array<ArrayBuffer>, OE, R> => Channel.mkUint8Array(self)
 
 /**
  * Persists a stream of multipart parts into a record.