effect 4.0.0-rc.112 → 4.0.0-rc.113

package/src/SchemaGetter.ts

@@ -11,6 +11,7 @@
  *
  * @since 4.0.0
  */
+import * as Arr from "./Array.ts"
 import * as DateTime from "./DateTime.ts"
 import * as Effect from "./Effect.ts"
 import * as Encoding from "./Encoding.ts"
@@ -56,12 +57,32 @@ import * as Str from "./String.ts"
  *
  * @see {@link transform} to create a getter from a pure function
  * @see {@link passthrough} for the identity getter
- * @see {@link transformOrFail} for fallible transformation
+ * @see {@link transformEffect} for effectful transformation
  *
  * @category models
  * @since 4.0.0
  */
-export class Getter<out T, in E, R = never> extends Pipeable.Class {
+export interface Getter<out T, in E, R = never> extends Pipeable.Pipeable {
+  readonly run: (
+    input: Option.Option<E>,
+    options: SchemaAST.ParseOptions
+  ) => Effect.Effect<Option.Option<T>, SchemaIssue.Issue, R>
+  map<T2>(f: (t: T) => T2): Getter<T2, E, R>
+  compose<T2, R2>(other: Getter<T2, T, R2>): Getter<T2, E, R | R2>
+}
+
+/**
+ * Constructs a composable schema getter.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const Getter: new<T, E, R = never>(
+  run: (
+    input: Option.Option<E>,
+    options: SchemaAST.ParseOptions
+  ) => Effect.Effect<Option.Option<T>, SchemaIssue.Issue, R>
+) => Getter<T, E, R> = class<out T, in E, R = never> extends Pipeable.Class {
   readonly run: (
     input: Option.Option<E>,
     options: SchemaAST.ParseOptions
@@ -200,6 +221,36 @@ export function forbidden<T, E>(message: (oe: Option.Option<E>) => string): Gett
   })
 }
 
+/**
+ * Getter that always fails with a `Forbidden` issue indicating that encoding is unsupported.
+ *
+ * **When to use**
+ *
+ * Use as the encode side of a decode-only Schema transformation.
+ *
+ * **Details**
+ *
+ * Its `Getter<never, unknown>` type is assignable to every encoding getter because it accepts any input and never
+ * produces an output value.
+ *
+ * **Example** (Rejecting encoding)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaGetter } from "effect"
+ *
+ * const issue = await Effect.runPromise(
+ *   Effect.flip(SchemaGetter.forbiddenEncoding.run(Option.some("value"), {}))
+ * )
+ * issue._tag // => "Forbidden"
+ * ```
+ *
+ * @see {@link forbidden} for a forbidden getter with a custom message
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const forbiddenEncoding: Getter<never, unknown> = forbidden(() => "Encoding is not supported")
+
 const passthrough_ = new Getter<any, any>(Effect.succeed)
 
 function isPassthrough<T, E, R>(getter: Getter<T, E, R>): getter is typeof passthrough_ {
@@ -416,7 +467,7 @@ export function required<T, E extends T = T>(annotations?: Schema.Annotations.Ke
  *
  * @see {@link onNone} to handle only absent values
  * @see {@link transform} for a simpler pure transformation of present values
- * @see {@link transformOrFail} for fallible transformation of present values
+ * @see {@link transformEffect} for effectful transformation of present values
  *
  * @category transforming
  * @since 4.0.0
@@ -511,7 +562,7 @@ export function checkEffect<T, R = never>(
  * Schema.decodeSync(NumberFromString)("42") // => 42
  * ```
  *
- * @see {@link transformOrFail} when the transformation can fail
+ * @see {@link transformEffect} when the transformation returns an `Effect`
  * @see {@link transformOptional} when you need to handle `None` inputs
  * @see {@link passthrough} when no transformation is needed
  *
@@ -523,7 +574,7 @@ export function transform<T, E>(f: (e: E) => T): Getter<T, E> {
 }
 
 /**
- * Creates a getter that applies a fallible, effectful transformation to present values.
+ * Creates a getter that applies an effectful transformation to present values.
  *
  * **When to use**
  *
@@ -541,7 +592,7 @@ export function transform<T, E>(f: (e: E) => T): Getter<T, E> {
  * ```ts import.meta.vitest
  * import { Effect, Option, SchemaGetter, SchemaIssue } from "effect"
  *
- * const safeParseInt = SchemaGetter.transformOrFail<number, string>(
+ * const safeParseInt = SchemaGetter.transformEffect<number, string>(
  *   (s, options) => {
  *     const n = parseInt(s, 10)
  *     return isNaN(n)
@@ -558,7 +609,7 @@ export function transform<T, E>(f: (e: E) => T): Getter<T, E> {
  * @category transforming
  * @since 4.0.0
  */
-export function transformOrFail<T, E, R = never>(
+export function transformEffect<T, E, R = never>(
   f: (e: E, options: SchemaAST.ParseOptions) => Effect.Effect<T, SchemaIssue.Issue, R>
 ): Getter<T, E, R> {
   return onSome((e, options) => f(e, options).pipe(Effect.mapEager(Option.some)))
@@ -720,7 +771,7 @@ export function String<E>(): Getter<string, E> {
  * await Effect.runPromise(toNumber.run(Option.some("42"), {})) // => Option.some(42)
  * ```
  *
- * @see {@link transformOrFail} for validated number parsing
+ * @see {@link transformEffect} for effectful or validated number parsing
  *
  * @category converting
  * @since 4.0.0
@@ -1327,7 +1378,7 @@ export function encodeHex<E extends Uint8Array | string>(): Getter<string, E> {
  * @since 4.0.0
  */
 export function decodeBase64<E extends string>(): Getter<Uint8Array, E> {
-  return transformOrFail((input, options) =>
+  return transformEffect((input, options) =>
     Effect.mapErrorEager(
       Effect.fromResult(Encoding.decodeBase64(input)),
       () =>
@@ -1363,7 +1414,7 @@ export function decodeBase64<E extends string>(): Getter<Uint8Array, E> {
  * @since 4.0.0
  */
 export function decodeBase64String<E extends string>(): Getter<string, E> {
-  return transformOrFail((input, options) =>
+  return transformEffect((input, options) =>
     Result.match(Encoding.decodeBase64String(input), {
       onFailure: () =>
         Effect.fail(
@@ -1402,7 +1453,7 @@ export function decodeBase64String<E extends string>(): Getter<string, E> {
  * @since 4.0.0
  */
 export function decodeBase64Url<E extends string>(): Getter<Uint8Array, E> {
-  return transformOrFail((input, options) =>
+  return transformEffect((input, options) =>
     Result.match(Encoding.decodeBase64Url(input), {
       onFailure: () =>
         Effect.fail(
@@ -1440,7 +1491,7 @@ export function decodeBase64Url<E extends string>(): Getter<Uint8Array, E> {
  * @since 4.0.0
  */
 export function decodeBase64UrlString<E extends string>(): Getter<string, E> {
-  return transformOrFail((input, options) =>
+  return transformEffect((input, options) =>
     Result.match(Encoding.decodeBase64UrlString(input), {
       onFailure: () =>
         Effect.fail(
@@ -1479,7 +1530,7 @@ export function decodeBase64UrlString<E extends string>(): Getter<string, E> {
  * @since 4.0.0
  */
 export function decodeHex<E extends string>(): Getter<Uint8Array, E> {
-  return transformOrFail((input, options) =>
+  return transformEffect((input, options) =>
     Result.match(Encoding.decodeHex(input), {
       onFailure: () =>
         Effect.fail(
@@ -1517,7 +1568,7 @@ export function decodeHex<E extends string>(): Getter<Uint8Array, E> {
  * @since 4.0.0
  */
 export function decodeHexString<E extends string>(): Getter<string, E> {
-  return transformOrFail((input, options) =>
+  return transformEffect((input, options) =>
     Result.match(Encoding.decodeHexString(input), {
       onFailure: () =>
         Effect.fail(
@@ -1581,7 +1632,7 @@ export function encodeUriComponent<E extends string>(): Getter<string, E> {
  * @since 4.0.0
  */
 export function decodeUriComponent<E extends string>(): Getter<string, E> {
-  return transformOrFail((input, options) => {
+  return transformEffect((input, options) => {
     try {
       return Effect.succeed(globalThis.decodeURIComponent(input))
     } catch {
@@ -1629,7 +1680,7 @@ export function decodeUriComponent<E extends string>(): Getter<string, E> {
  * @since 4.0.0
  */
 export function dateTimeUtcFromInput<E extends DateTime.DateTime.Input>(): Getter<DateTime.Utc, E> {
-  return transformOrFail((input, options) => {
+  return transformEffect((input, options) => {
     return Option.match(DateTime.make(input), {
       onNone: () =>
         Effect.fail(
@@ -1800,8 +1851,6 @@ export function encodeURLSearchParams(): Getter<URLSearchParams, unknown> {
   })
 }
 
-const INDEX_REGEXP = /^\d+$/
-
 function bracketPathToTokens(bracketPath: string): Array<string | number> {
   // real empty path (from append("", value))
   if (bracketPath === "") {
@@ -1815,7 +1864,7 @@ function bracketPathToTokens(bracketPath: string): Array<string | number> {
 
   return parts
     .slice(start)
-    .map((part) => (INDEX_REGEXP.test(part) ? globalThis.Number(part) : part))
+    .map((part) => (Arr.isCanonicalArrayIndex(part) ? globalThis.Number(part) : part))
 }
 
 /**
@@ -1839,6 +1888,8 @@ function bracketPathToTokens(bracketPath: string): Array<string | number> {
  *   - `"foo[0]"` → array index `{ foo: [value] }`
  *   - `"foo[]"` → append to array `foo`
  *   - `""` → real empty key
+ * - Numeric bracket segments become array indices only when they are valid
+ *   JavaScript array-index strings; otherwise they remain object keys.
  * - Duplicate keys for the same path are merged into arrays.
  * - If a structural path conflicts with a previous leaf or a different container
  *   type, the later structural path replaces the conflicting value.
@@ -1869,6 +1920,7 @@ export function makeTreeRecord<A>(
 ): Schema.TreeRecord<A> {
   const out: any = {}
   const containers = new WeakSet<object>()
+  const duplicates = new WeakSet<object>()
 
   function getOrCreateContainer(self: any, key: PropertyKey, shouldBeArray: boolean): any {
     const current = Object.hasOwn(self, key) ? self[key] : undefined
@@ -1902,10 +1954,12 @@ export function makeTreeRecord<A>(
         // If we're setting a value at a path that already exists
         // convert it to an array to support multiple values for the same key
         const hasOwn = Object.hasOwn(cur, token)
-        if (hasOwn && Array.isArray(cur[token])) {
+        if (hasOwn && Array.isArray(cur[token]) && (containers.has(cur[token]) || duplicates.has(cur[token]))) {
           cur[token].push(value)
         } else if (hasOwn) {
-          InternalRecord.assignProperty(cur, token, [cur[token], value])
+          const values = [cur[token], value]
+          duplicates.add(values)
+          InternalRecord.assignProperty(cur, token, values)
         } else {
           InternalRecord.assignProperty(cur, token, value)
         }

package/src/SchemaIssue.ts

@@ -148,7 +148,16 @@ export type Issue =
   | Composite
   | AnyOf
 
-class Base {
+interface IssueNode {
+  readonly [TypeId]: typeof TypeId
+  /**
+   * The input reported by the schema parser, when input reporting is enabled
+   * and the issue is associated with a present value.
+   */
+  readonly input?: unknown
+}
+
+class IssueNodeImpl implements IssueNode {
   readonly [TypeId] = TypeId
   /**
    * The input reported by the schema parser, when input reporting is enabled
@@ -202,7 +211,43 @@ class Base {
  * @category models
  * @since 4.0.0
  */
-export class Filter extends Base {
+export interface Filter extends IssueNode {
+  readonly _tag: "Filter"
+  /**
+   * The filter that failed.
+   */
+  readonly filter: SchemaAST.Filter<unknown>
+  /**
+   * The issue that occurred.
+   */
+  readonly issue: Issue
+}
+
+/**
+ * Constructs a schema issue for a failed refinement check.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const Filter: new(
+  /**
+   * The filter that failed.
+   */
+  filter: SchemaAST.Filter<any>,
+  /**
+   * The issue that occurred.
+   */
+  issue: Issue,
+  /**
+   * The present input associated with the issue. It is retained only when
+   * `options.reportInput` is `true`.
+   */
+  input?: unknown,
+  /**
+   * The effective parse options controlling input retention.
+   */
+  options?: SchemaAST.ParseOptions
+) => Filter = class extends IssueNodeImpl {
   readonly _tag = "Filter"
   /**
    * The filter that failed.
@@ -257,7 +302,30 @@ export class Filter extends Base {
  * @category models
  * @since 4.0.0
  */
-export class Encoding extends Base {
+export interface Encoding extends IssueNode {
+  readonly _tag: "Encoding"
+  /**
+   * The schema that caused the issue.
+   */
+  readonly ast: SchemaAST.AST
+  /**
+   * The issue that occurred.
+   */
+  readonly issue: Issue
+}
+
+/**
+ * Constructs a schema issue for a failed transformation.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const Encoding: new(
+  ast: SchemaAST.AST,
+  issue: Issue,
+  input?: unknown,
+  options?: SchemaAST.ParseOptions
+) => Encoding = class extends IssueNodeImpl {
   readonly _tag = "Encoding"
   /**
    * The schema that caused the issue.
@@ -311,9 +379,27 @@ export class Encoding extends Base {
  * @see {@link Composite} — groups multiple issues under one schema node
  *
  * @category models
- * @since 3.10.0
+ * @since 4.0.0
+ */
+export interface Pointer extends IssueNode {
+  readonly _tag: "Pointer"
+  /**
+   * The path to the location in the input that caused the issue.
+   */
+  readonly path: ReadonlyArray<PropertyKey>
+  /**
+   * The issue that occurred.
+   */
+  readonly issue: Issue
+}
+
+/**
+ * Constructs a schema issue that points to a nested location.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
-export class Pointer extends Base {
+export const Pointer: new(path: ReadonlyArray<PropertyKey>, issue: Issue) => Pointer = class extends IssueNodeImpl {
   readonly _tag = "Pointer"
   /**
    * The path to the location in the input that caused the issue.
@@ -357,7 +443,23 @@ export class Pointer extends Base {
  * @category models
  * @since 4.0.0
  */
-export class MissingKey extends Base {
+export interface MissingKey extends IssueNode {
+  readonly _tag: "MissingKey"
+  /**
+   * The metadata for the issue.
+   */
+  readonly annotations: Schema.Annotations.Key<unknown> | undefined
+}
+
+/**
+ * Constructs a schema issue for a missing key or tuple index.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const MissingKey: new(annotations: Schema.Annotations.Key<unknown> | undefined) => MissingKey = class
+  extends IssueNodeImpl
+{
   readonly _tag = "MissingKey"
   /**
    * The metadata for the issue.
@@ -397,7 +499,25 @@ export class MissingKey extends Base {
  * @category models
  * @since 4.0.0
  */
-export class UnexpectedKey extends Base {
+export interface UnexpectedKey extends IssueNode {
+  readonly _tag: "UnexpectedKey"
+  /**
+   * The schema that caused the issue.
+   */
+  readonly ast: SchemaAST.AST
+}
+
+/**
+ * Constructs a schema issue for an unexpected key or tuple index.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const UnexpectedKey: new(
+  ast: SchemaAST.AST,
+  input?: unknown,
+  options?: SchemaAST.ParseOptions
+) => UnexpectedKey = class extends IssueNodeImpl {
   readonly _tag = "UnexpectedKey"
   /**
    * The schema that caused the issue.
@@ -440,9 +560,32 @@ export class UnexpectedKey extends Base {
  * @see {@link Pointer} — adds path context to individual issues
  *
  * @category models
- * @since 3.10.0
+ * @since 4.0.0
  */
-export class Composite extends Base {
+export interface Composite extends IssueNode {
+  readonly _tag: "Composite"
+  /**
+   * The schema that caused the issue.
+   */
+  readonly ast: SchemaAST.AST
+  /**
+   * The issues that occurred.
+   */
+  readonly issues: readonly [Issue, ...Array<Issue>]
+}
+
+/**
+ * Constructs a schema issue that groups multiple child issues.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const Composite: new(
+  ast: SchemaAST.AST,
+  issues: readonly [Issue, ...Array<Issue>],
+  input?: unknown,
+  options?: SchemaAST.ParseOptions
+) => Composite = class extends IssueNodeImpl {
   readonly _tag = "Composite"
   /**
    * The schema that caused the issue.
@@ -508,7 +651,25 @@ export class Composite extends Base {
  * @category models
  * @since 4.0.0
  */
-export class InvalidType extends Base {
+export interface InvalidType extends IssueNode {
+  readonly _tag: "InvalidType"
+  /**
+   * The schema that caused the issue.
+   */
+  readonly ast: SchemaAST.AST
+}
+
+/**
+ * Constructs a schema issue for an input with an invalid runtime type.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const InvalidType: new(
+  ast: SchemaAST.AST,
+  input?: unknown,
+  options?: SchemaAST.ParseOptions
+) => InvalidType = class extends IssueNodeImpl {
   readonly _tag = "InvalidType"
   /**
    * The schema that caused the issue.
@@ -569,7 +730,25 @@ export class InvalidType extends Base {
  * @category models
  * @since 4.0.0
  */
-export class InvalidValue extends Base {
+export interface InvalidValue extends IssueNode {
+  readonly _tag: "InvalidValue"
+  /**
+   * The metadata for the issue.
+   */
+  readonly annotations: Schema.Annotations.Issue | undefined
+}
+
+/**
+ * Constructs a schema issue for a value that violates a constraint.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const InvalidValue: new(
+  annotations?: Schema.Annotations.Issue | undefined,
+  input?: unknown,
+  options?: SchemaAST.ParseOptions
+) => InvalidValue = class extends IssueNodeImpl {
   readonly _tag = "InvalidValue"
   /**
    * The metadata for the issue.
@@ -641,9 +820,27 @@ export function makeCompositeAtKey(
  * @see {@link InvalidValue} — for value-constraint failures (not operation failures)
  *
  * @category models
- * @since 3.10.0
+ * @since 4.0.0
  */
-export class Forbidden extends Base {
+export interface Forbidden extends IssueNode {
+  readonly _tag: "Forbidden"
+  /**
+   * The metadata for the issue.
+   */
+  readonly annotations: Schema.Annotations.Issue | undefined
+}
+
+/**
+ * Constructs a schema issue for a forbidden parsing operation.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const Forbidden: new(
+  annotations: Schema.Annotations.Issue | undefined,
+  input?: unknown,
+  options?: SchemaAST.ParseOptions
+) => Forbidden = class extends IssueNodeImpl {
   readonly _tag = "Forbidden"
   /**
    * The metadata for the issue.
@@ -695,7 +892,30 @@ export class Forbidden extends Base {
  * @category models
  * @since 4.0.0
  */
-export class AnyOf extends Base {
+export interface AnyOf extends IssueNode {
+  readonly _tag: "AnyOf"
+  /**
+   * The schema that caused the issue.
+   */
+  readonly ast: SchemaAST.Union
+  /**
+   * The issues that occurred.
+   */
+  readonly issues: ReadonlyArray<Issue>
+}
+
+/**
+ * Constructs a schema issue for a value that matches no union member.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const AnyOf: new(
+  ast: SchemaAST.Union,
+  issues: ReadonlyArray<Issue>,
+  input?: unknown,
+  options?: SchemaAST.ParseOptions
+) => AnyOf = class extends IssueNodeImpl {
   readonly _tag = "AnyOf"
   /**
    * The schema that caused the issue.
@@ -754,7 +974,30 @@ export class AnyOf extends Base {
  * @category models
  * @since 4.0.0
  */
-export class OneOf extends Base {
+export interface OneOf extends IssueNode {
+  readonly _tag: "OneOf"
+  /**
+   * The schema that caused the issue.
+   */
+  readonly ast: SchemaAST.Union
+  /**
+   * The schemas that were successful.
+   */
+  readonly successes: ReadonlyArray<SchemaAST.AST>
+}
+
+/**
+ * Constructs a schema issue for a value that matches multiple union members.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const OneOf: new(
+  ast: SchemaAST.Union,
+  successes: ReadonlyArray<SchemaAST.AST>,
+  input?: unknown,
+  options?: SchemaAST.ParseOptions
+) => OneOf = class extends IssueNodeImpl {
   readonly _tag = "OneOf"
   /**
    * The schema that caused the issue.
@@ -950,6 +1193,7 @@ export const defaultLeafHook: LeafHook = (issue): string => {
  *
  * - Returns `string` to override the message, or `undefined` to fall back to
  *   the default formatting.
+ *
  * @see {@link defaultCheckHook} — the built-in implementation
  * @see {@link Filter} — the issue type this hook formats
  *

package/src/SchemaParser.ts

@@ -1093,13 +1093,8 @@ function makeParser(
     ? ast.encoding ? [...ast.encoding, constructorDefault] : [constructorDefault]
     : ast.encoding
   const encodingChecks = (ast as any).encodingChecks
-  const astOptions = (checks ? checks[checks.length - 1].annotations : ast.annotations)
-    ?.["parseOptions"]
   if (!links && !checks && !encodingChecks) {
-    if (!astOptions) {
-      return parser
-    }
-    return (input, options) => parser(input, mergeParseOptions(options, astOptions))
+    return parser
   }
   let encodingParsers: ReadonlyArray<Parser> | undefined
   const parseLocal = (
@@ -1161,17 +1156,12 @@ function makeParser(
     return result
   }
   if (!links) {
-    return astOptions
-      ? (input, options) => parseLocal(input, mergeParseOptions(options, astOptions))
-      : parseLocal
+    return parseLocal
   }
   return (
     input: unknown,
     options: SchemaAST.ParseOptions
   ) => {
-    if (astOptions) {
-      options = mergeParseOptions(options, astOptions)
-    }
     const parsers = encodingParsers ??= links.map((link) => compile(link.to))
     let current = input
     let result = parsers[parsers.length - 1](input, options)