/**
 * Composable transformation primitives for the Effect Schema system.
 *
 * A `Getter<T, E, R>` represents a single-direction transformation from an
 * encoded type `E` to a decoded type `T`. Getters are the building blocks
 * that `Schema.decodeTo` and `Schema.decode` use to define how values are
 * transformed during encoding and decoding. They handle optionality
 * (`Option<E>` in, `Option<T>` out), can fail with `Issue`, and can require
 * Effect services via `R`.
 *
 * ## Mental model
 *
 * - **Getter**: A function `Option<E> -> Effect<Option<T>, Issue, R>`. It
 *   transforms an optional encoded value into an optional decoded value,
 *   possibly failing or requiring services.
 * - **Passthrough**: The identity getter — returns the input unchanged. Used
 *   when no transformation is needed. Optimized away during composition.
 * - **Option-awareness**: Getters receive and return `Option` to handle
 *   missing keys in structs. `Option.None` means the key is absent.
 * - **Composition**: Getters compose left-to-right via `.compose()`. A
 *   passthrough on either side is a no-op (identity optimization).
 * - **Issue**: The error type for all getter failures (see `SchemaIssue`).
 *
 * ## Common tasks
 *
 * - Pass a value through unchanged → {@link passthrough}
 * - Transform a value purely → {@link transform}
 * - Transform a value with possible failure → {@link transformOrFail}
 * - Transform with full Option control → {@link transformOptional}
 * - Handle missing keys → {@link onNone}, {@link required}, {@link withDefault}
 * - Handle present values → {@link onSome}
 * - Validate a value with an effectful check → {@link checkEffect}
 * - Produce a constant value → {@link succeed}
 * - Always fail → {@link fail}, {@link forbidden}
 * - Omit a value from output → {@link omit}
 * - Coerce to a primitive type → {@link String}, {@link Number}, {@link Boolean}, {@link BigInt}, {@link Date}
 * - Transform strings → {@link trim}, {@link capitalize}, {@link toLowerCase}, {@link toUpperCase}, {@link split}, {@link splitKeyValue}, {@link joinKeyValue}
 * - Parse/stringify JSON → {@link parseJson}, {@link stringifyJson}
 * - Encode/decode Base64 → {@link encodeBase64}, {@link decodeBase64}, {@link decodeBase64String}
 * - Encode/decode Hex → {@link encodeHex}, {@link decodeHex}, {@link decodeHexString}
 * - Encode/decode URI components → {@link encodeUriComponent}, {@link decodeUriComponent}
 * - Parse DateTime → {@link dateTimeUtcFromInput}
 * - Decode/encode FormData → {@link decodeFormData}, {@link encodeFormData}
 * - Decode/encode URLSearchParams → {@link decodeURLSearchParams}, {@link encodeURLSearchParams}
 * - Build nested tree from bracket paths → {@link makeTreeRecord}
 * - Flatten nested tree to bracket paths → {@link collectBracketPathEntries}
 *
 * ## Gotchas
 *
 * - Getters are not bidirectional. To define a full encode/decode pair, supply
 *   both a `decode` and an `encode` getter to `Schema.decodeTo`.
 * - `passthrough` requires `T === E` by default. Use `{ strict: false }` to
 *   bypass the type constraint, or use {@link passthroughSupertype} / {@link passthroughSubtype}.
 * - `transform` skips `None` inputs (missing keys) — the function is only
 *   called when a value is present. Use `transformOptional` if you need to
 *   handle missing values.
 * - `parseJson` without a `reviver` returns `Schema.MutableJson`. With a
 *   reviver, the return type widens to `unknown`.
 * - `split` treats an empty string as an empty array, not `[""]`.
 *
 * ## Quickstart
 *
 * **Example** (Using SchemaGetter with Schema.decodeTo)
 *
 * ```ts
 * import { Schema, SchemaGetter } from "effect"
 *
 * const NumberFromString = Schema.String.pipe(
 *   Schema.decodeTo(Schema.Number, {
 *     decode: SchemaGetter.transform((s) => Number(s)),
 *     encode: SchemaGetter.transform((n) => String(n))
 *   })
 * )
 *
 * const result = Schema.decodeUnknownSync(NumberFromString)("42")
 * // result: 42
 * ```
 *
 * ## See also
 *
 * - {@link Getter} — the core class
 * - {@link transform} — most common constructor
 * - {@link passthrough} — identity getter
 * - {@link transformOrFail} — fallible transformation
 *
 * @since 4.0.0
 */
import * as DateTime from "./DateTime.ts"
import * as Effect from "./Effect.ts"
import * as Encoding from "./Encoding.ts"
import * as Option from "./Option.ts"
import * as Pipeable from "./Pipeable.ts"
import * as Predicate from "./Predicate.ts"
import * as Result from "./Result.ts"
import type * as Schema from "./Schema.ts"
import type * as AST from "./SchemaAST.ts"
import * as Issue from "./SchemaIssue.ts"
import * as Str from "./String.ts"

/**
 * A composable transformation from an encoded type `E` to a decoded type `T`.
 *
 * A Getter wraps a function `Option<E> -> Effect<Option<T>, Issue, R>`:
 * - Receives `Option.None` when the encoded key is absent (e.g. missing struct field).
 * - Returns `Option.None` to omit the value from the decoded output.
 * - Fails with `Issue` on invalid input.
 * - May require Effect services via `R`.
 *
 * Use this when:
 * - Building custom schema transformations with `Schema.decodeTo` or `Schema.decode`.
 * - Composing multiple transformation steps into a single getter.
 *
 * Behavior:
 * - Immutable — constructing or composing getters does not mutate existing instances.
 * - `.map(f)` applies `f` to the decoded value (inside the `Some`), leaving `None` unchanged.
 * - `.compose(other)` chains two getters: the output of `this` feeds into `other`.
 *   Passthrough getters on either side are optimized away.
 *
 * **Example** (Creating and composing getters)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const parseNumber = SchemaGetter.transform<number, string>((s) => Number(s))
 * const double = SchemaGetter.transform<number, number>((n) => n * 2)
 * const composed = parseNumber.compose(double)
 * // composed: Getter<number, string> — parses then doubles
 * ```
 *
 * See also:
 * - {@link transform} — create a getter from a pure function
 * - {@link passthrough} — identity getter
 * - {@link transformOrFail} — fallible transformation
 *
 * @category model
 * @since 4.0.0
 */
export class Getter<out T, in E, R = never> extends Pipeable.Class {
  readonly run: (
    input: Option.Option<E>,
    options: AST.ParseOptions
  ) => Effect.Effect<Option.Option<T>, Issue.Issue, R>

  constructor(
    run: (
      input: Option.Option<E>,
      options: AST.ParseOptions
    ) => Effect.Effect<Option.Option<T>, Issue.Issue, R>
  ) {
    super()
    this.run = run
  }
  map<T2>(f: (t: T) => T2): Getter<T2, E, R> {
    return new Getter((oe, options) => this.run(oe, options).pipe(Effect.mapEager(Option.map(f))))
  }
  compose<T2, R2>(other: Getter<T2, T, R2>): Getter<T2, E, R | R2> {
    if (isPassthrough(this)) {
      return other as any
    }
    if (isPassthrough(other)) {
      return this as any
    }
    return new Getter((oe, options) => this.run(oe, options).pipe(Effect.flatMapEager((ot) => other.run(ot, options))))
  }
}

/**
 * Creates a getter that always produces the given constant value, ignoring the input.
 *
 * Use this when:
 * - A schema field should always decode to a fixed value.
 * - You need a placeholder getter that produces a known default.
 *
 * Behavior:
 * - Pure, no side effects.
 * - Always returns `Option.some(t)` regardless of whether input is `Some` or `None`.
 *
 * **Example** (Constant getter)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const alwaysZero = SchemaGetter.succeed(0)
 * // alwaysZero: Getter<0, unknown> — always produces 0
 * ```
 *
 * See also:
 * - {@link transform} — when you need to use the input value
 * - {@link passthrough} — when you want to keep the input as-is
 *
 * @category Constructors
 * @since 4.0.0
 */
export function succeed<const T, E>(t: T): Getter<T, E> {
  return new Getter(() => Effect.succeedSome(t))
}

/**
 * Creates a getter that always fails with the given issue.
 *
 * Use this when:
 * - A transformation should unconditionally reject input.
 * - Building custom validation getters that produce specific error types.
 *
 * Behavior:
 * - Always fails with the `Issue` returned by `f`.
 * - The failure function receives the original `Option<E>` input for error context.
 *
 * **Example** (Always-failing getter)
 *
 * ```ts
 * import { SchemaGetter, SchemaIssue, Option } from "effect"
 *
 * const rejectAll = SchemaGetter.fail<string, string>(
 *   (oe) => new SchemaIssue.InvalidValue(oe, { message: "not allowed" })
 * )
 * ```
 *
 * See also:
 * - {@link forbidden} — convenience for `Forbidden` issues
 * - {@link checkEffect} — fail conditionally based on input value
 *
 * @category Constructors
 * @since 4.0.0
 */
export function fail<T, E>(f: (oe: Option.Option<E>) => Issue.Issue): Getter<T, E> {
  return new Getter((oe) => Effect.fail(f(oe)))
}

/**
 * Creates a getter that always fails with a `Forbidden` issue.
 *
 * Use this when:
 * - A field or direction (encode/decode) should be disallowed entirely.
 * - You want a clear "forbidden" error message in schema validation output.
 *
 * Behavior:
 * - Always fails with `Issue.Forbidden`.
 * - The message function receives the `Option<E>` input for context.
 *
 * **Example** (Forbidding a decode direction)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const noEncode = SchemaGetter.forbidden<string, number>(
 *   () => "encoding is not supported"
 * )
 * ```
 *
 * See also:
 * - {@link fail} — fail with a custom issue type
 *
 * @category Constructors
 * @since 4.0.0
 */
export function forbidden<T, E>(message: (oe: Option.Option<E>) => string): Getter<T, E> {
  return fail<T, E>((oe) => new Issue.Forbidden(oe, { message: message(oe) }))
}

const passthrough_ = new Getter<any, any>(Effect.succeed)

function isPassthrough<T, E, R>(getter: Getter<T, E, R>): getter is typeof passthrough_ {
  return getter.run === passthrough_.run
}

/**
 * Returns the identity getter — passes the value through unchanged.
 *
 * Use this when:
 * - No transformation is needed between encoded and decoded types.
 * - One side of a `decodeTo` pair (encode or decode) should be a no-op.
 *
 * Behavior:
 * - Pure, no allocation (singleton instance).
 * - Optimized away during `.compose()` — composing with a passthrough is free.
 * - The default overload requires `T === E`. Pass `{ strict: false }` to opt
 *   out of the type constraint.
 *
 * **Example** (Identity transformation)
 *
 * ```ts
 * import { Schema, SchemaGetter } from "effect"
 *
 * // No transformation needed — types already match
 * const StringToString = Schema.String.pipe(
 *   Schema.decodeTo(Schema.String, {
 *     decode: SchemaGetter.passthrough(),
 *     encode: SchemaGetter.passthrough()
 *   })
 * )
 * ```
 *
 * See also:
 * - {@link passthroughSupertype} — when `T extends E`
 * - {@link passthroughSubtype} — when `E extends T`
 * - {@link transform} — when you need to change the value
 *
 * @category Constructors
 * @since 4.0.0
 */
export function passthrough<T, E>(options: { readonly strict: false }): Getter<T, E>
export function passthrough<T>(): Getter<T, T>
export function passthrough<T>(): Getter<T, T> {
  return passthrough_
}

/**
 * Returns the identity getter, typed for when the decoded type `T` is a supertype of `E`.
 *
 * Use this when:
 * - The decoded type is wider than the encoded type (e.g. `string` from a string literal).
 * - You need type-safe passthrough without `{ strict: false }`.
 *
 * Behavior:
 * - Same singleton as {@link passthrough} — no allocation, optimized in composition.
 *
 * **Example** (Supertype passthrough)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * // string extends string, so this is valid
 * const g = SchemaGetter.passthroughSupertype<string, string>()
 * ```
 *
 * See also:
 * - {@link passthrough} — when types are identical
 * - {@link passthroughSubtype} — when `E extends T`
 *
 * @category Constructors
 * @since 4.0.0
 */
export function passthroughSupertype<T extends E, E>(): Getter<T, E>
export function passthroughSupertype<T>(): Getter<T, T> {
  return passthrough_
}

/**
 * Returns the identity getter, typed for when the encoded type `E` is a subtype of `T`.
 *
 * Use this when:
 * - The encoded type is narrower than the decoded type.
 * - You need type-safe passthrough without `{ strict: false }`.
 *
 * Behavior:
 * - Same singleton as {@link passthrough} — no allocation, optimized in composition.
 *
 * **Example** (Subtype passthrough)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * // "hello" extends string, so E extends T
 * const g = SchemaGetter.passthroughSubtype<string, "hello">()
 * ```
 *
 * See also:
 * - {@link passthrough} — when types are identical
 * - {@link passthroughSupertype} — when `T extends E`
 *
 * @category Constructors
 * @since 4.0.0
 */
export function passthroughSubtype<T, E extends T>(): Getter<T, E>
export function passthroughSubtype<T>(): Getter<T, T> {
  return passthrough_
}

/**
 * Creates a getter that handles the case when the input is absent (`Option.None`).
 *
 * Use this when:
 * - You need to provide a fallback or computed value for missing struct keys.
 * - Building custom "default value" logic more complex than {@link withDefault}.
 *
 * Behavior:
 * - When input is `None`, calls `f` to produce the result.
 * - When input is `Some`, passes it through unchanged.
 * - `f` receives the parse options and may return `None` to keep the value absent.
 *
 * **Example** (Default timestamp for missing field)
 *
 * ```ts
 * import { SchemaGetter, Effect, Option } from "effect"
 *
 * const withTimestamp = SchemaGetter.onNone<number>(() =>
 *   Effect.succeed(Option.some(Date.now()))
 * )
 * ```
 *
 * See also:
 * - {@link required} — fails if input is absent
 * - {@link withDefault} — simpler default value for undefined inputs
 * - {@link onSome} — handle only present values
 *
 * @category Constructors
 * @since 4.0.0
 */
export function onNone<T, E extends T = T, R = never>(
  f: (options: AST.ParseOptions) => Effect.Effect<Option.Option<T>, Issue.Issue, R>
): Getter<T, E, R> {
  return new Getter((ot, options) => Option.isNone(ot) ? f(options) : Effect.succeed(ot))
}

/**
 * Creates a getter that fails with `MissingKey` if the input is absent (`Option.None`).
 *
 * Use this when:
 * - A struct field must be present in the encoded input.
 * - You want schema validation to report a missing key error.
 *
 * Behavior:
 * - When input is `None`, fails with `Issue.MissingKey`.
 * - When input is `Some`, passes it through unchanged.
 * - Optional `annotations` customize the error message for the missing key.
 *
 * **Example** (Required struct field)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const mustExist = SchemaGetter.required<string>()
 * ```
 *
 * See also:
 * - {@link onNone} — provide a fallback instead of failing
 * - {@link withDefault} — substitute a default for undefined values
 *
 * @category Constructors
 * @since 4.0.0
 */
export function required<T, E extends T = T>(annotations?: Schema.Annotations.Key<T>): Getter<T, E> {
  return onNone(() => Effect.fail(new Issue.MissingKey(annotations)))
}

/**
 * Creates a getter that handles present values (`Option.Some`), passing `None` through.
 *
 * Use this when:
 * - You need to transform or validate only when a value is present.
 * - Missing keys should remain absent in the output.
 *
 * Behavior:
 * - When input is `None`, returns `None` (no-op).
 * - When input is `Some(e)`, calls `f(e, options)` to produce the result.
 * - `f` may return `None` to omit the value, or fail with an `Issue`.
 *
 * **Example** (Transform only present values)
 *
 * ```ts
 * import { SchemaGetter, Effect, Option } from "effect"
 *
 * const parseIfPresent = SchemaGetter.onSome<number, string>(
 *   (s) => Effect.succeed(Option.some(Number(s)))
 * )
 * ```
 *
 * See also:
 * - {@link onNone} — handle only absent values
 * - {@link transform} — simpler pure transformation of present values
 * - {@link transformOrFail} — fallible transformation of present values
 *
 * @category Constructors
 * @since 4.0.0
 */
export function onSome<T, E, R = never>(
  f: (e: E, options: AST.ParseOptions) => Effect.Effect<Option.Option<T>, Issue.Issue, R>
): Getter<T, E, R> {
  return new Getter((oe, options) => Option.isNone(oe) ? Effect.succeedNone : f(oe.value, options))
}

/**
 * Creates a getter that validates a value using an effectful check function.
 *
 * Use this when:
 * - You need to validate a decoded value (e.g. check a constraint or call an external service).
 * - The validation may be asynchronous or require Effect services.
 *
 * Behavior:
 * - Only runs when input is `Some` — `None` passes through.
 * - The check function returns a validation result:
 *   - `undefined` or `true` — value is valid, passes through.
 *   - `false` or a `string` — value is invalid, fails with an `Issue`.
 *   - An `Issue` object — fails with that issue directly.
 *   - `{ path, issue }` — fails with a nested path issue (`issue` may be a
 *     message string or a full {@link Issue.Issue}).
 * - Does not transform the value — input and output types are the same.
 *
 * **Example** (Effectful validation)
 *
 * ```ts
 * import { SchemaGetter, Effect } from "effect"
 *
 * const nonNegative = SchemaGetter.checkEffect<number>((n) =>
 *   Effect.succeed(n >= 0 ? undefined : "must be non-negative")
 * )
 * ```
 *
 * See also:
 * - {@link transform} — when you need to change the value, not just validate
 * - {@link fail} — unconditional failure
 *
 * @category Constructors
 * @since 4.0.0
 */
export function checkEffect<T, R = never>(
  f: (input: T, options: AST.ParseOptions) => Effect.Effect<
    undefined | boolean | Schema.FilterIssue,
    never,
    R
  >
): Getter<T, T, R> {
  return onSome((t, options) => {
    return f(t, options).pipe(Effect.flatMapEager((out) => {
      const issue = Issue.makeSingle(t, out)
      return issue ?
        Effect.fail(issue) :
        Effect.succeed(Option.some(t))
    }))
  })
}

/**
 * Creates a getter that applies a pure function to present values.
 *
 * This is the most commonly used constructor. It transforms `Some(e)` to
 * `Some(f(e))` and leaves `None` unchanged.
 *
 * Use this when:
 * - You have a pure, infallible transformation between types.
 * - Building encode/decode pairs for `Schema.decodeTo`.
 *
 * Behavior:
 * - Pure, does not mutate input.
 * - Skips `None` inputs — only called when a value is present.
 * - Never fails.
 *
 * **Example** (String to number transformation pair)
 *
 * ```ts
 * import { Schema, SchemaGetter } from "effect"
 *
 * const NumberFromString = Schema.String.pipe(
 *   Schema.decodeTo(Schema.Number, {
 *     decode: SchemaGetter.transform((s) => Number(s)),
 *     encode: SchemaGetter.transform((n) => String(n))
 *   })
 * )
 * ```
 *
 * See also:
 * - {@link transformOrFail} — when the transformation can fail
 * - {@link transformOptional} — when you need to handle `None` inputs
 * - {@link passthrough} — when no transformation is needed
 *
 * @category Constructors
 * @since 4.0.0
 */
export function transform<T, E>(f: (e: E) => T): Getter<T, E> {
  return transformOptional(Option.map(f))
}

/**
 * Creates a getter that applies a fallible, effectful transformation to present values.
 *
 * Use this when:
 * - The transformation may fail (e.g. parsing, validation).
 * - The transformation needs Effect services or is async.
 *
 * Behavior:
 * - Skips `None` inputs — only called when a value is present.
 * - On success, wraps the result in `Some`.
 * - On failure, propagates the `Issue`.
 *
 * **Example** (Parsing with failure)
 *
 * ```ts
 * import { SchemaGetter, SchemaIssue, Effect, Option } from "effect"
 *
 * const safeParseInt = SchemaGetter.transformOrFail<number, string>(
 *   (s) => {
 *     const n = parseInt(s, 10)
 *     return isNaN(n)
 *       ? Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), { message: "not an integer" }))
 *       : Effect.succeed(n)
 *   }
 * )
 * ```
 *
 * See also:
 * - {@link transform} — when transformation cannot fail
 * - {@link onSome} — when you need full `Option` control over the output
 *
 * @category Constructors
 * @since 4.0.0
 */
export function transformOrFail<T, E, R = never>(
  f: (e: E, options: AST.ParseOptions) => Effect.Effect<T, Issue.Issue, R>
): Getter<T, E, R> {
  return onSome((e, options) => f(e, options).pipe(Effect.mapEager(Option.some)))
}

/**
 * Creates a getter that transforms the full `Option` — both present and absent values.
 *
 * Use this when:
 * - You need to handle both `Some` and `None` cases.
 * - You want to turn a present value into absent, or vice versa.
 *
 * Behavior:
 * - Pure, never fails.
 * - Receives the full `Option<E>` and must return `Option<T>`.
 *
 * **Example** (Filter out empty strings)
 *
 * ```ts
 * import { SchemaGetter, Option } from "effect"
 *
 * const skipEmpty = SchemaGetter.transformOptional<string, string>((o) =>
 *   Option.filter(o, (s) => s.length > 0)
 * )
 * ```
 *
 * See also:
 * - {@link transform} — simpler, only handles present values
 * - {@link omit} — always returns `None`
 *
 * @category Constructors
 * @since 4.0.0
 */
export function transformOptional<T, E>(f: (oe: Option.Option<E>) => Option.Option<T>): Getter<T, E> {
  return new Getter((oe) => Effect.succeed(f(oe)))
}

/**
 * Creates a getter that always returns `None`, effectively omitting the value from output.
 *
 * Use this when:
 * - A field should be excluded during decoding or encoding.
 *
 * Behavior:
 * - Always returns `Option.None` regardless of input.
 * - Never fails.
 *
 * **Example** (Omit a field during encoding)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const omitField = SchemaGetter.omit<string>()
 * ```
 *
 * See also:
 * - {@link transformOptional} — when you want conditional omission
 * - {@link forbidden} — when you want to fail instead of silently omit
 *
 * @category Constructors
 * @since 4.0.0
 */
export function omit<T>(): Getter<never, T> {
  return new Getter(() => Effect.succeedNone)
}

/**
 * Creates a getter that replaces `undefined` values with a default.
 *
 * Use this when:
 * - A field may be `undefined` in the encoded input and should have a fallback.
 *
 * Behavior:
 * - If the input is `Some(undefined)` or `None`, produces `Some(T)`.
 * - If the input is `Some(value)` where value is not `undefined`, passes it through.
 * - `defaultValue` is an `Effect` that will be executed each time a default is needed.
 *
 * **Example** (Default value for optional field)
 *
 * ```ts
 * import { Effect, SchemaGetter } from "effect"
 *
 * const withZero = SchemaGetter.withDefault(Effect.succeed(0))
 * // Getter<number, number | undefined>
 * ```
 *
 * See also:
 * - {@link onNone} — handle only absent keys (not `undefined` values)
 * - {@link required} — fail instead of providing a default
 *
 * @category Constructors
 * @since 4.0.0
 */
export function withDefault<T>(defaultValue: Effect.Effect<T>): Getter<T, T | undefined> {
  return new Getter((o) => {
    const filtered = Option.filter(o, Predicate.isNotUndefined)
    return Option.isSome(filtered) ? Effect.succeed(filtered) : Effect.map(defaultValue, Option.some)
  })
}

/**
 * Coerces any value to a `string` using the global `String()` constructor.
 *
 * Use this when:
 * - You need a string representation of an arbitrary encoded value.
 *
 * Behavior:
 * - Pure, never fails.
 * - Delegates to `globalThis.String`.
 *
 * **Example** (Coerce to string)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const toString = SchemaGetter.String<number>()
 * // Getter<string, number>
 * ```
 *
 * See also:
 * - {@link transform} — for custom string conversions
 *
 * @category Coercions
 * @since 4.0.0
 */
export function String<E>(): Getter<string, E> {
  return transform(globalThis.String)
}

/**
 * Coerces any value to a `number` using the global `Number()` constructor.
 *
 * Use this when:
 * - You need numeric coercion of an encoded value.
 *
 * Behavior:
 * - Pure, never fails (may produce `NaN` for non-numeric inputs).
 * - Delegates to `globalThis.Number`.
 *
 * **Example** (Coerce to number)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const toNumber = SchemaGetter.Number<string>()
 * // Getter<number, string>
 * ```
 *
 * See also:
 * - {@link transformOrFail} — for validated number parsing
 *
 * @category Coercions
 * @since 4.0.0
 */
export function Number<E>(): Getter<number, E> {
  return transform(globalThis.Number)
}

/**
 * Coerces any value to a `boolean` using the global `Boolean()` constructor.
 *
 * Use this when:
 * - You need boolean coercion (truthiness check) of an encoded value.
 *
 * Behavior:
 * - Pure, never fails.
 * - Delegates to `globalThis.Boolean`.
 *
 * **Example** (Coerce to boolean)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const toBool = SchemaGetter.Boolean<string>()
 * // Getter<boolean, string>
 * ```
 *
 * @category Coercions
 * @since 4.0.0
 */
export function Boolean<E>(): Getter<boolean, E> {
  return transform(globalThis.Boolean)
}

/**
 * Coerces a value to `bigint` using the global `BigInt()` constructor.
 *
 * Use this when:
 * - You need to convert strings, numbers, or booleans to `bigint`.
 *
 * Behavior:
 * - Delegates to `globalThis.BigInt`.
 * - Throws at runtime if the input cannot be converted (e.g. non-numeric string).
 *
 * **Example** (Coerce to bigint)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const toBigInt = SchemaGetter.BigInt<string>()
 * // Getter<bigint, string>
 * ```
 *
 * @category Coercions
 * @since 4.0.0
 */
export function BigInt<E extends string | number | bigint | boolean>(): Getter<bigint, E> {
  return transform(globalThis.BigInt)
}

/**
 * Coerces a value to a `Date` using `new Date(input)`.
 *
 * Use this when:
 * - You need to parse a string, number, or Date into a `Date` object.
 *
 * Behavior:
 * - Delegates to `new globalThis.Date(input)`.
 * - Does not validate the result — may produce an invalid Date.
 *
 * **Example** (Coerce to Date)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const toDate = SchemaGetter.Date<string>()
 * // Getter<Date, string>
 * ```
 *
 * See also:
 * - {@link dateTimeUtcFromInput} — validated DateTime parsing
 *
 * @category Coercions
 * @since 4.0.0
 */
export function Date<E extends string | number | Date>(): Getter<Date, E> {
  return transform((u) => new globalThis.Date(u))
}

/**
 * Trims whitespace from both ends of a string.
 *
 * Behavior:
 * - Pure, delegates to `String.trim`.
 *
 * **Example** (Trim whitespace)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const trimmed = SchemaGetter.trim<string>()
 * ```
 *
 * @category string
 * @since 4.0.0
 */
export function trim<E extends string>(): Getter<string, E> {
  return transform(Str.trim)
}

/**
 * Capitalizes the first character of a string.
 *
 * Behavior:
 * - Pure, delegates to `String.capitalize`.
 *
 * **Example** (Capitalize string)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const cap = SchemaGetter.capitalize<string>()
 * ```
 *
 * @category string
 * @since 4.0.0
 */
export function capitalize<E extends string>(): Getter<string, E> {
  return transform(Str.capitalize)
}

/**
 * Lowercases the first character of a string.
 *
 * Behavior:
 * - Pure, delegates to `String.uncapitalize`.
 *
 * **Example** (Uncapitalize string)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const uncap = SchemaGetter.uncapitalize<string>()
 * ```
 *
 * @category string
 * @since 4.0.0
 */
export function uncapitalize<E extends string>(): Getter<string, E> {
  return transform(Str.uncapitalize)
}

/**
 * Converts a `snake_case` string to `camelCase`.
 *
 * Behavior:
 * - Pure, delegates to `String.snakeToCamel`.
 *
 * **Example** (Snake to camel)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const toCamel = SchemaGetter.snakeToCamel<string>()
 * ```
 *
 * See also:
 * - {@link camelToSnake} — inverse operation
 *
 * @category string
 * @since 4.0.0
 */
export function snakeToCamel<E extends string>(): Getter<string, E> {
  return transform(Str.snakeToCamel)
}

/**
 * Converts a `camelCase` string to `snake_case`.
 *
 * Behavior:
 * - Pure, delegates to `String.camelToSnake`.
 *
 * **Example** (Camel to snake)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const toSnake = SchemaGetter.camelToSnake<string>()
 * ```
 *
 * See also:
 * - {@link snakeToCamel} — inverse operation
 *
 * @category string
 * @since 4.0.0
 */
export function camelToSnake<E extends string>(): Getter<string, E> {
  return transform(Str.camelToSnake)
}

/**
 * Converts a string to lowercase.
 *
 * Behavior:
 * - Pure, delegates to `String.toLowerCase`.
 *
 * **Example** (To lowercase)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const lower = SchemaGetter.toLowerCase<string>()
 * ```
 *
 * See also:
 * - {@link toUpperCase} — inverse operation
 *
 * @category string
 * @since 4.0.0
 */
export function toLowerCase<E extends string>(): Getter<string, E> {
  return transform(Str.toLowerCase)
}

/**
 * Converts a string to uppercase.
 *
 * Behavior:
 * - Pure, delegates to `String.toUpperCase`.
 *
 * **Example** (To uppercase)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const upper = SchemaGetter.toUpperCase<string>()
 * ```
 *
 * See also:
 * - {@link toLowerCase} — inverse operation
 *
 * @category string
 * @since 4.0.0
 */
export function toUpperCase<E extends string>(): Getter<string, E> {
  return transform(Str.toUpperCase)
}

type ParseJsonOptions = {
  readonly reviver?: Parameters<typeof JSON.parse>[1]
}

/**
 * Parses a JSON string into a value.
 *
 * Use this when:
 * - An encoded value is a JSON string that needs to be parsed during decoding.
 *
 * Behavior:
 * - Skips `None` inputs.
 * - Without `reviver`: returns `Schema.MutableJson` (typed JSON).
 * - With `reviver`: returns `unknown` (reviver may produce arbitrary values).
 * - On parse failure, fails with `Issue.InvalidValue` containing the error message.
 *
 * **Example** (Parse JSON)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const parse = SchemaGetter.parseJson<string>()
 * // Getter<MutableJson, string>
 * ```
 *
 * See also:
 * - {@link stringifyJson} — inverse operation
 *
 * @category Json
 * @since 4.0.0
 */
export function parseJson<E extends string>(): Getter<Schema.MutableJson, E>
export function parseJson<E extends string>(options: ParseJsonOptions): Getter<unknown, E>
export function parseJson<E extends string>(options?: ParseJsonOptions | undefined): Getter<unknown, E> {
  return onSome((input) =>
    Effect.try({
      try: () => Option.some(JSON.parse(input, options?.reviver)),
      catch: (e) => new Issue.InvalidValue(Option.some(input), { message: globalThis.String(e) })
    })
  )
}

type StringifyJsonOptions = {
  readonly replacer?: Parameters<typeof JSON.stringify>[1]
  readonly space?: Parameters<typeof JSON.stringify>[2]
}

/**
 * Stringifies a value to JSON.
 *
 * Use this when:
 * - A decoded value needs to be serialized to a JSON string during encoding.
 *
 * Behavior:
 * - Skips `None` inputs.
 * - On stringify failure (e.g. circular references), fails with `Issue.InvalidValue`.
 * - Supports optional `replacer` and `space` options (same as `JSON.stringify`).
 *
 * **Example** (Stringify JSON)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const stringify = SchemaGetter.stringifyJson()
 * // Getter<string, unknown>
 * ```
 *
 * See also:
 * - {@link parseJson} — inverse operation
 *
 * @category Json
 * @since 4.0.0
 */
export function stringifyJson(options?: StringifyJsonOptions): Getter<string, unknown> {
  return onSome((input) =>
    Effect.try({
      try: () => Option.some(JSON.stringify(input, options?.replacer, options?.space)),
      catch: (e) => new Issue.InvalidValue(Option.some(input), { message: globalThis.String(e) })
    })
  )
}

/**
 * Parses a string into a record of key-value pairs.
 *
 * Use this when:
 * - An encoded string contains delimited key-value pairs (e.g. `"a=1,b=2"`).
 *
 * Behavior:
 * - Splits the string by `separator` (default `,`), then each pair by `keyValueSeparator` (default `=`).
 * - Pairs missing a key or value are silently skipped.
 * - Pure, never fails.
 *
 * **Example** (Parse key-value string)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const parse = SchemaGetter.splitKeyValue<string>()
 * // "a=1,b=2" -> { a: "1", b: "2" }
 * ```
 *
 * See also:
 * - {@link joinKeyValue} — inverse operation
 * - {@link split} — split into an array of strings
 *
 * @category string
 * @since 4.0.0
 */
export function splitKeyValue<E extends string>(options?: {
  readonly separator?: string | undefined
  readonly keyValueSeparator?: string | undefined
}): Getter<Record<string, string>, E> {
  const separator = options?.separator ?? ","
  const keyValueSeparator = options?.keyValueSeparator ?? "="
  return transform((input) =>
    input.split(separator).reduce((acc, pair) => {
      const [key, value] = pair.split(keyValueSeparator)
      if (key && value) {
        acc[key] = value
      }
      return acc
    }, {} as Record<string, string>)
  )
}

/**
 * Joins a record of key-value pairs into a delimited string.
 *
 * Use this when:
 * - A decoded record needs to be serialized as a delimited key-value string.
 *
 * Behavior:
 * - Joins entries with `separator` (default `,`) and key/value with `keyValueSeparator` (default `=`).
 * - Pure, never fails.
 *
 * **Example** (Join key-value record)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const join = SchemaGetter.joinKeyValue()
 * // { a: "1", b: "2" } -> "a=1,b=2"
 * ```
 *
 * See also:
 * - {@link splitKeyValue} — inverse operation
 *
 * @category string
 * @since 4.0.0
 */
export function joinKeyValue<E extends Record<PropertyKey, string>>(options?: {
  readonly separator?: string | undefined
  readonly keyValueSeparator?: string | undefined
}): Getter<string, E> {
  const separator = options?.separator ?? ","
  const keyValueSeparator = options?.keyValueSeparator ?? "="
  return transform((input) =>
    Object.entries(input).map(([key, value]) => `${key}${keyValueSeparator}${value}`).join(separator)
  )
}

/**
 * Splits a string into an array of strings by a separator.
 *
 * Use this when:
 * - An encoded string is a delimited list (e.g. CSV values).
 *
 * Behavior:
 * - Splits by `separator` (default `,`).
 * - An empty string produces an empty array (not `[""]`).
 * - Pure, never fails.
 *
 * **Example** (Split comma-separated string)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const splitComma = SchemaGetter.split<string>()
 * // "a,b,c" -> ["a", "b", "c"]
 * // "" -> []
 * ```
 *
 * See also:
 * - {@link splitKeyValue} — when values are key-value pairs
 *
 * @category string
 * @since 4.0.0
 */
export function split<E extends string>(options?: {
  readonly separator?: string | undefined
}): Getter<ReadonlyArray<string>, E> {
  const separator = options?.separator ?? ","
  return transform((input) => input === "" ? [] : input.split(separator))
}

/**
 * Encodes a `Uint8Array` or string to a Base64 string.
 *
 * Behavior:
 * - Pure, never fails.
 *
 * **Example** (Encode to Base64)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const encode = SchemaGetter.encodeBase64<Uint8Array>()
 * ```
 *
 * See also:
 * - {@link decodeBase64} — inverse (to `Uint8Array`)
 * - {@link decodeBase64String} — inverse (to `string`)
 * - {@link encodeBase64Url} — URL-safe variant
 *
 * @category Base64
 * @since 4.0.0
 */
export function encodeBase64<E extends Uint8Array | string>(): Getter<string, E> {
  return transform(Encoding.encodeBase64)
}

/**
 * Encodes a `Uint8Array` or string to a URL-safe Base64 string.
 *
 * Behavior:
 * - Pure, never fails.
 *
 * **Example** (Encode to Base64Url)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const encode = SchemaGetter.encodeBase64Url<Uint8Array>()
 * ```
 *
 * See also:
 * - {@link decodeBase64Url} — inverse (to `Uint8Array`)
 * - {@link decodeBase64UrlString} — inverse (to `string`)
 * - {@link encodeBase64} — standard Base64 variant
 *
 * @category Base64
 * @since 4.0.0
 */
export function encodeBase64Url<E extends Uint8Array | string>(): Getter<string, E> {
  return transform(Encoding.encodeBase64Url)
}

/**
 * Encodes a `Uint8Array` or string to a hexadecimal string.
 *
 * Behavior:
 * - Pure, never fails.
 *
 * **Example** (Encode to hex)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const encode = SchemaGetter.encodeHex<Uint8Array>()
 * ```
 *
 * See also:
 * - {@link decodeHex} — inverse (to `Uint8Array`)
 * - {@link decodeHexString} — inverse (to `string`)
 *
 * @category Hex
 * @since 4.0.0
 */
export function encodeHex<E extends Uint8Array | string>(): Getter<string, E> {
  return transform(Encoding.encodeHex)
}

/**
 * Decodes a Base64 string to a `Uint8Array`.
 *
 * Behavior:
 * - Fails with `Issue.InvalidValue` if the input is not valid Base64.
 *
 * **Example** (Decode Base64 to bytes)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const decode = SchemaGetter.decodeBase64<string>()
 * // Getter<Uint8Array, string>
 * ```
 *
 * See also:
 * - {@link decodeBase64String} — decode to `string` instead
 * - {@link encodeBase64} — inverse operation
 *
 * @category Base64
 * @since 4.0.0
 */
export function decodeBase64<E extends string>(): Getter<Uint8Array, E> {
  return transformOrFail((input) =>
    Effect.mapErrorEager(
      Effect.fromResult(Encoding.decodeBase64(input)),
      (e) => new Issue.InvalidValue(Option.some(input), { message: e.message })
    )
  )
}

/**
 * Decodes a Base64 string to a UTF-8 `string`.
 *
 * Behavior:
 * - Fails with `Issue.InvalidValue` if the input is not valid Base64.
 *
 * **Example** (Decode Base64 to string)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const decode = SchemaGetter.decodeBase64String<string>()
 * // Getter<string, string>
 * ```
 *
 * See also:
 * - {@link decodeBase64} — decode to `Uint8Array` instead
 * - {@link encodeBase64} — inverse operation
 *
 * @category Base64
 * @since 4.0.0
 */
export function decodeBase64String<E extends string>(): Getter<string, E> {
  return transformOrFail((input) =>
    Result.match(Encoding.decodeBase64String(input), {
      onFailure: (e) => Effect.fail(new Issue.InvalidValue(Option.some(input), { message: e.message })),
      onSuccess: Effect.succeed
    })
  )
}

/**
 * Decodes a URL-safe Base64 string to a `Uint8Array`.
 *
 * Behavior:
 * - Fails with `Issue.InvalidValue` if the input is not valid Base64Url.
 *
 * **Example** (Decode Base64Url to bytes)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const decode = SchemaGetter.decodeBase64Url<string>()
 * // Getter<Uint8Array, string>
 * ```
 *
 * See also:
 * - {@link decodeBase64UrlString} — decode to `string` instead
 * - {@link encodeBase64Url} — inverse operation
 *
 * @category Base64
 * @since 4.0.0
 */
export function decodeBase64Url<E extends string>(): Getter<Uint8Array, E> {
  return transformOrFail((input) =>
    Result.match(Encoding.decodeBase64Url(input), {
      onFailure: (e) => Effect.fail(new Issue.InvalidValue(Option.some(input), { message: e.message })),
      onSuccess: Effect.succeed
    })
  )
}

/**
 * Decodes a URL-safe Base64 string to a UTF-8 `string`.
 *
 * Behavior:
 * - Fails with `Issue.InvalidValue` if the input is not valid Base64Url.
 *
 * **Example** (Decode Base64Url to string)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const decode = SchemaGetter.decodeBase64UrlString<string>()
 * // Getter<string, string>
 * ```
 *
 * See also:
 * - {@link decodeBase64Url} — decode to `Uint8Array` instead
 * - {@link encodeBase64Url} — inverse operation
 *
 * @category Base64
 * @since 4.0.0
 */
export function decodeBase64UrlString<E extends string>(): Getter<string, E> {
  return transformOrFail((input) =>
    Result.match(Encoding.decodeBase64UrlString(input), {
      onFailure: (e) => Effect.fail(new Issue.InvalidValue(Option.some(input), { message: e.message })),
      onSuccess: Effect.succeed
    })
  )
}

/**
 * Decodes a hexadecimal string to a `Uint8Array`.
 *
 * Behavior:
 * - Fails with `Issue.InvalidValue` if the input is not valid hex.
 *
 * **Example** (Decode hex to bytes)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const decode = SchemaGetter.decodeHex<string>()
 * // Getter<Uint8Array, string>
 * ```
 *
 * See also:
 * - {@link decodeHexString} — decode to `string` instead
 * - {@link encodeHex} — inverse operation
 *
 * @category Hex
 * @since 4.0.0
 */
export function decodeHex<E extends string>(): Getter<Uint8Array, E> {
  return transformOrFail((input) =>
    Result.match(Encoding.decodeHex(input), {
      onFailure: (e) => Effect.fail(new Issue.InvalidValue(Option.some(input), { message: e.message })),
      onSuccess: Effect.succeed
    })
  )
}

/**
 * Decodes a hexadecimal string to a UTF-8 `string`.
 *
 * Behavior:
 * - Fails with `Issue.InvalidValue` if the input is not valid hex.
 *
 * **Example** (Decode hex to string)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const decode = SchemaGetter.decodeHexString<string>()
 * // Getter<string, string>
 * ```
 *
 * See also:
 * - {@link decodeHex} — decode to `Uint8Array` instead
 * - {@link encodeHex} — inverse operation
 *
 * @category Hex
 * @since 4.0.0
 */
export function decodeHexString<E extends string>(): Getter<string, E> {
  return transformOrFail((input) =>
    Result.match(Encoding.decodeHexString(input), {
      onFailure: (e) => Effect.fail(new Issue.InvalidValue(Option.some(input), { message: e.message })),
      onSuccess: Effect.succeed
    })
  )
}

/**
 * Encodes a string using `encodeURIComponent`.
 *
 * Behavior:
 * - Pure, never fails.
 *
 * **Example** (Encode a URI component)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const encode = SchemaGetter.encodeUriComponent<string>()
 * ```
 *
 * See also:
 * - {@link decodeUriComponent} - inverse operation
 *
 * @category URI
 * @since 4.0.0
 */
export function encodeUriComponent<E extends string>(): Getter<string, E> {
  return transform(encodeURIComponent)
}

/**
 * Decodes a URI component encoded string using `decodeURIComponent`.
 *
 * Behavior:
 * - Fails with `Issue.InvalidValue` if the input contains malformed percent-encoding sequences.
 *
 * **Example** (Decode a URI component)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const decode = SchemaGetter.decodeUriComponent<string>()
 * // Getter<string, string>
 * ```
 *
 * See also:
 * - {@link encodeUriComponent} - inverse operation
 *
 * @category URI
 * @since 4.0.0
 */
export function decodeUriComponent<E extends string>(): Getter<string, E> {
  return transformOrFail((input) => {
    try {
      return Effect.succeed(globalThis.decodeURIComponent(input))
    } catch (e) {
      return Effect.fail(
        new Issue.InvalidValue(Option.some(input), {
          message: e instanceof URIError ? e.message : "Invalid URI component"
        })
      )
    }
  })
}

/**
 * Parses a `DateTime.Input` value (string, number, or Date) into a `DateTime.Utc`.
 *
 * Use this when:
 * - An encoded value represents a date/time and should be decoded to a `DateTime.Utc`.
 *
 * Behavior:
 * - Fails with `Issue.InvalidValue` if the input cannot be parsed as a valid DateTime.
 *
 * **Example** (Parse DateTime)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const parseDate = SchemaGetter.dateTimeUtcFromInput<string>()
 * // Getter<DateTime.Utc, string>
 * ```
 *
 * See also:
 * - {@link Date} — simpler coercion to `Date` (no validation)
 *
 * @category DateTime
 * @since 4.0.0
 */
export function dateTimeUtcFromInput<E extends DateTime.DateTime.Input>(): Getter<DateTime.Utc, E> {
  return transformOrFail((input) => {
    return Option.match(DateTime.make(input), {
      onNone: () => Effect.fail(new Issue.InvalidValue(Option.some(input), { message: "Invalid DateTime input" })),
      onSome: (dt) => Effect.succeed(DateTime.toUtc(dt))
    })
  })
}

/**
 * Decodes a `FormData` object into a nested tree structure using bracket-path notation.
 *
 * Use this when:
 * - Parsing `FormData` from HTTP requests into structured objects.
 *
 * Behavior:
 * - Pure, never fails.
 * - Interprets bracket-path keys (e.g. `user[name]`, `items[0]`) to build nested objects/arrays.
 * - Leaf values are `string` or `Blob`.
 *
 * **Example** (Decode FormData)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const decode = SchemaGetter.decodeFormData()
 * // Getter<TreeObject<string | Blob>, FormData>
 * ```
 *
 * See also:
 * - {@link encodeFormData} — inverse operation
 * - {@link makeTreeRecord} — the underlying bracket-path parser
 * - {@link decodeURLSearchParams} — similar for URLSearchParams
 *
 * @category FormData
 * @since 4.0.0
 */
export function decodeFormData(): Getter<Schema.TreeRecord<string | Blob>, FormData> {
  return transform((input) => makeTreeRecord(Array.from(input.entries())))
}

const collectFormDataEntries = collectBracketPathEntries((value): value is string | Blob =>
  typeof value === "string" || (typeof Blob !== "undefined" && value instanceof Blob)
)

/**
 * Encodes a nested object into a `FormData` instance using bracket-path notation.
 *
 * Use this when:
 * - Serializing structured data to `FormData` for HTTP requests.
 *
 * Behavior:
 * - Pure, never fails.
 * - Flattens nested objects/arrays into bracket-path keys (e.g. `user[name]`, `items[0]`).
 * - Non-object inputs produce an empty `FormData`.
 *
 * **Example** (Encode to FormData)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const encode = SchemaGetter.encodeFormData()
 * // Getter<FormData, unknown>
 * ```
 *
 * See also:
 * - {@link decodeFormData} — inverse operation
 * - {@link collectBracketPathEntries} — the underlying flattener
 * - {@link encodeURLSearchParams} — similar for URLSearchParams
 *
 * @category FormData
 * @since 4.0.0
 */
export function encodeFormData(): Getter<FormData, unknown> {
  return transform((input) => {
    const out = new FormData()
    if (typeof input === "object" && input !== null) {
      const entries = collectFormDataEntries(input)
      entries.forEach(([key, value]) => {
        out.append(key, value)
      })
    }
    return out
  })
}

/**
 * Decodes a `URLSearchParams` object into a nested tree structure using bracket-path notation.
 *
 * Use this when:
 * - Parsing query parameters from URLs into structured objects.
 *
 * Behavior:
 * - Pure, never fails.
 * - Interprets bracket-path keys (e.g. `user[name]`, `items[0]`) to build nested objects/arrays.
 * - Leaf values are `string`.
 *
 * **Example** (Decode URLSearchParams)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const decode = SchemaGetter.decodeURLSearchParams()
 * // Getter<TreeObject<string>, URLSearchParams>
 * ```
 *
 * See also:
 * - {@link encodeURLSearchParams} — inverse operation
 * - {@link makeTreeRecord} — the underlying bracket-path parser
 * - {@link decodeFormData} — similar for FormData
 *
 * @category URLSearchParams
 * @since 4.0.0
 */
export function decodeURLSearchParams(): Getter<Schema.TreeRecord<string>, URLSearchParams> {
  return transform((input) => makeTreeRecord(Array.from(input.entries())))
}

const collectURLSearchParamsEntries = collectBracketPathEntries(Predicate.isString)

/**
 * Encodes a nested object into a `URLSearchParams` instance using bracket-path notation.
 *
 * Use this when:
 * - Serializing structured data to query parameters for URLs.
 *
 * Behavior:
 * - Pure, never fails.
 * - Flattens nested objects/arrays into bracket-path keys.
 * - Non-object inputs produce an empty `URLSearchParams`.
 *
 * **Example** (Encode to URLSearchParams)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const encode = SchemaGetter.encodeURLSearchParams()
 * // Getter<URLSearchParams, unknown>
 * ```
 *
 * See also:
 * - {@link decodeURLSearchParams} — inverse operation
 * - {@link collectBracketPathEntries} — the underlying flattener
 * - {@link encodeFormData} — similar for FormData
 *
 * @category URLSearchParams
 * @since 4.0.0
 */
export function encodeURLSearchParams(): Getter<URLSearchParams, unknown> {
  return transform((input) => {
    if (typeof input === "object" && input !== null) {
      return new URLSearchParams(collectURLSearchParamsEntries(input))
    }
    return new URLSearchParams()
  })
}

const INDEX_REGEXP = /^\d+$/

function bracketPathToTokens(bracketPath: string): Array<string | number> {
  // real empty path (from append("", value))
  if (bracketPath === "") {
    return [""]
  }

  const replaced = bracketPath.replace(/\[(.*?)\]/g, ".$1")
  const parts = replaced.split(".")
  // if bracket path started with "[...]" we get ".foo" => ["", "foo"]; drop the synthetic first ""
  const start = replaced.startsWith(".") ? 1 : 0

  return parts
    .slice(start)
    .map((part) => (INDEX_REGEXP.test(part) ? globalThis.Number(part) : part))
}

/**
 * Builds a nested tree object from a list of bracket-path entries.
 *
 * A bracket path is a string like `"user[address][city]"` that describes nested
 * object/array structure. This function interprets those paths and constructs the
 * corresponding nested object.
 *
 * Use this when:
 * - Parsing FormData or URLSearchParams entries into structured objects.
 * - You have flat key-value pairs with bracket-path keys that need nesting.
 *
 * Behavior:
 * - Mutates and returns a new object (does not mutate the input array).
 * - Supported syntax:
 *   - `"foo"` → object key `"foo"`
 *   - `"foo[bar]"` → nested `{ foo: { bar: ... } }`
 *   - `"foo[0]"` → array index `{ foo: [value] }`
 *   - `"foo[]"` → append to array `foo`
 *   - `""` → real empty key
 * - Duplicate keys for the same path are merged into arrays.
 *
 * **Example** (Build tree from bracket paths)
 *
 * ```ts
 * import { SchemaGetter } from "effect"
 *
 * const tree = SchemaGetter.makeTreeRecord([
 *   ["user[name]", "Alice"],
 *   ["user[tags][]", "admin"],
 *   ["user[tags][]", "editor"]
 * ])
 * // { user: { name: "Alice", tags: ["admin", "editor"] } }
 * ```
 *
 * See also:
 * - {@link collectBracketPathEntries} — inverse operation (tree to flat entries)
 * - {@link decodeFormData} — uses this internally
 * - {@link decodeURLSearchParams} — uses this internally
 *
 * @category Tree
 * @since 4.0.0
 */
export function makeTreeRecord<A>(
  bracketPathEntries: ReadonlyArray<readonly [bracketPath: string, value: A]>
): Schema.TreeRecord<A> {
  const out: any = {}
  bracketPathEntries.forEach(([key, value]) => {
    const tokens = bracketPathToTokens(key)
    let cur: any = out
    tokens.forEach((token, i) => {
      const isLast = i === tokens.length - 1

      // We are inside an array and see "[]" (empty token) => append
      if (Array.isArray(cur) && token === "") {
        if (isLast) {
          cur.push(value)
        } else {
          // bracket path: "foo[][bar]" => push a new element and descend into it
          const next = tokens[i + 1]
          const shouldBeArray = typeof next === "number" || next === ""
          const index = cur.length

          if (cur[index] === undefined) {
            cur[index] = shouldBeArray ? [] : {}
          }

          cur = cur[index]
        }
      } else if (isLast) {
        // 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
        if (Array.isArray(cur[token])) {
          cur[token].push(value)
        } else if (Object.prototype.hasOwnProperty.call(cur, token)) {
          cur[token] = [cur[token], value]
        } else {
          cur[token] = value
        }
      } else {
        const next = tokens[i + 1]
        // if next is a number OR "" (from []), we are building an array
        const shouldBeArray = typeof next === "number" || next === ""

        if (cur[token] === undefined) {
          cur[token] = shouldBeArray ? [] : {}
        }

        cur = cur[token]
      }
    })
  })
  return out
}

/**
 * Flattens a nested object into bracket-path entries, filtering leaf values by a type guard.
 *
 * This is the inverse of {@link makeTreeRecord}. It takes a nested object and produces
 * flat `[bracketPath, value]` pairs suitable for `FormData` or `URLSearchParams`.
 *
 * Use this when:
 * - Serializing structured objects to flat key-value entries.
 * - Building custom `FormData` or `URLSearchParams` encoders.
 *
 * Behavior:
 * - Returns a curried function: first call provides the leaf type guard, second call provides the object.
 * - Recursively traverses objects and arrays.
 * - If all elements of an array are leaves, encodes them as multiple entries with the same key
 *   (e.g. `tags=a&tags=b`). Otherwise uses indexed bracket paths (e.g. `items[0]`, `items[1]`).
 * - Non-leaf values that aren't objects or arrays are silently skipped.
 *
 * **Example** (Flatten object to bracket paths)
 *
 * ```ts
 * import { SchemaGetter, Predicate } from "effect"
 *
 * const collectStrings = SchemaGetter.collectBracketPathEntries(Predicate.isString)
 * const entries = collectStrings({ user: { name: "Alice", tags: ["admin", "editor"] } })
 * // [["user[name]", "Alice"], ["user[tags]", "admin"], ["user[tags]", "editor"]]
 * ```
 *
 * See also:
 * - {@link makeTreeRecord} — inverse operation (flat entries to tree)
 * - {@link encodeFormData} — uses this internally
 * - {@link encodeURLSearchParams} — uses this internally
 *
 * @category Tree
 * @since 4.0.0
 */
export function collectBracketPathEntries<A>(isLeaf: (value: unknown) => value is A) {
  return (input: object): Array<[bracketPath: string, value: A]> => {
    const bracketPathEntries: Array<[string, A]> = []

    function append(key: string, value: unknown): void {
      if (isLeaf(value)) {
        bracketPathEntries.push([key, value])
      } else if (Array.isArray(value)) {
        // If all values are leaves, encode as multiple entries with the same key
        const allLeaves = value.every(isLeaf)
        if (allLeaves) {
          value.forEach((v) => {
            bracketPathEntries.push([key, v])
          })
        } else {
          value.forEach((v, i) => {
            append(`${key}[${i}]`, v)
          })
        }
      } else if (typeof value === "object" && value !== null) {
        for (const [k, v] of Object.entries(value)) {
          append(`${key}[${k}]`, v)
        }
      }
    }

    for (const [key, value] of Object.entries(input)) {
      append(key, value)
    }

    return bracketPathEntries
  }
}