effect 4.0.1 → 4.0.3

package/src/SchemaGetter.ts

@@ -9,6 +9,7 @@
  * and ready-made conversions for common string, number, binary, date, form, and
  * URL-related values.
  *
+ * @stability stable
  * @since 4.0.0
  */
 import * as Arr from "./Array.ts"
@@ -31,6 +32,7 @@ import * as Str from "./String.ts"
 /**
  * A transformation that returns its input unchanged.
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -41,6 +43,7 @@ export interface Passthrough extends Pipeable.Pipeable {
 /**
  * A synchronous transformation of present values.
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -52,6 +55,7 @@ export interface Transform<out T, in E> extends Pipeable.Pipeable {
 /**
  * A synchronous transformation of optional values.
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -63,6 +67,7 @@ export interface TransformOptional<out T, in E> extends Pipeable.Pipeable {
 /**
  * An effectful transformation of present values.
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -77,6 +82,7 @@ export interface TransformEffect<out T, in E, R> extends Pipeable.Pipeable {
 /**
  * An effectful transformation of optional values.
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -122,6 +128,7 @@ export interface TransformOptionalEffect<out T, in E, R> extends Pipeable.Pipeab
  * @see {@link transform} to create a getter from a pure function
  * @see {@link transformEffect} for effectful transformation
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -175,6 +182,7 @@ const runGetter = <T, E, R>(
  * result // => Option.some(42)
  * ```
  *
+ * @stability stable
  * @category converting
  * @since 4.0.0
  */
@@ -201,6 +209,7 @@ export const run: {
    * result // => Option.some(42)
    * ```
    *
+   * @stability stable
    * @category converting
    * @since 4.0.0
    */
@@ -227,6 +236,7 @@ export const run: {
    * result // => Option.some(42)
    * ```
    *
+   * @stability stable
    * @category converting
    * @since 4.0.0
    */
@@ -275,6 +285,7 @@ const composeOptionalEffect = <T, E, R, T2, R2>(
  * Effect.runSync(SchemaGetter.run(getter, Option.some("-1"), {})) // => Option.some(0)
  * ```
  *
+ * @stability stable
  * @category combining
  * @since 4.0.0
  */
@@ -306,6 +317,7 @@ export const compose: {
    * Effect.runSync(SchemaGetter.run(getter, Option.some("-1"), {})) // => Option.some(0)
    * ```
    *
+   * @stability stable
    * @category combining
    * @since 4.0.0
    */
@@ -337,6 +349,7 @@ export const compose: {
    * Effect.runSync(SchemaGetter.run(getter, Option.some("-1"), {})) // => Option.some(0)
    * ```
    *
+   * @stability stable
    * @category combining
    * @since 4.0.0
    */
@@ -415,6 +428,7 @@ export const compose: {
  * Effect.runSync(SchemaGetter.run(getter, Option.some("21"), {})) // => Option.some(42)
  * ```
  *
+ * @stability stable
  * @category mapping
  * @since 4.0.0
  */
@@ -443,6 +457,7 @@ export const map: {
    * Effect.runSync(SchemaGetter.run(getter, Option.some("21"), {})) // => Option.some(42)
    * ```
    *
+   * @stability stable
    * @category mapping
    * @since 4.0.0
    */
@@ -471,6 +486,7 @@ export const map: {
    * Effect.runSync(SchemaGetter.run(getter, Option.some("21"), {})) // => Option.some(42)
    * ```
    *
+   * @stability stable
    * @category mapping
    * @since 4.0.0
    */
@@ -502,6 +518,7 @@ export const map: {
  * @see {@link transform} when you need to use the input value
  * @see {@link passthrough} when you want to keep the input as-is
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -540,6 +557,7 @@ export function succeed<const T, E>(t: T): Getter<T, E> {
  * @see {@link forbidden} for a convenience helper for `Forbidden` issues
  * @see {@link checkEffect} to fail conditionally based on input value
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -579,6 +597,7 @@ export function fail<T, E>(
  *
  * @see {@link fail} to fail with a custom issue type
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -616,6 +635,7 @@ export function forbidden<T, E>(message: (oe: Option.Option<E>) => string): Gett
  *
  * @see {@link forbidden} for a forbidden getter with a custom message
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -657,6 +677,7 @@ const passthrough_: Passthrough = makeGetter({ _tag: "Passthrough" })
  * @see {@link passthroughSubtype} when `E extends T`
  * @see {@link transform} when you need to change the value
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -691,6 +712,7 @@ export function passthrough<T>(): Getter<T, T> {
  * @see {@link passthrough} when types are identical
  * @see {@link passthroughSubtype} when `E extends T`
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -724,6 +746,7 @@ export function passthroughSupertype<T>(): Getter<T, T> {
  * @see {@link passthrough} when types are identical
  * @see {@link passthroughSupertype} when `T extends E`
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -760,6 +783,7 @@ export function passthroughSubtype<T>(): Getter<T, T> {
  *
  * @see {@link withDefault} to substitute a default for undefined values
  *
+ * @stability stable
  * @category validation
  * @since 4.0.0
  */
@@ -803,6 +827,7 @@ export function required<T, E extends T = T>(annotations?: Schema.Annotations.Ke
  * @see {@link transform} when you need to change the value, not just validate
  * @see {@link fail} for unconditional failure
  *
+ * @stability stable
  * @category validation
  * @since 4.0.0
  */
@@ -857,6 +882,7 @@ export function checkEffect<T, R = never>(
  * @see {@link transformOptional} when you need to handle `None` inputs
  * @see {@link passthrough} when no transformation is needed
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -897,6 +923,7 @@ export function transform<T, E>(f: (e: E) => T): Getter<T, E> {
  * @see {@link transform} when transformation cannot fail
  * @see {@link transformOptionalEffect} when you need full `Option` control over the output
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -933,6 +960,7 @@ export function transformEffect<T, E, R = never>(
  * @see {@link transform} when you only need to transform present values
  * @see {@link omit} when you always want `None`
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -943,6 +971,7 @@ export function transformOptional<T, E>(f: (oe: Option.Option<E>) => Option.Opti
 /**
  * Creates a getter that effectfully transforms the full `Option`.
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -980,6 +1009,7 @@ export function transformOptionalEffect<T, E, R = never>(
  * @see {@link transformOptional} when you want conditional omission
  * @see {@link forbidden} when you want to fail instead of silently omit
  *
+ * @stability stable
  * @category filtering
  * @since 4.0.0
  */
@@ -1013,6 +1043,7 @@ export function omit<T>(): Getter<never, T> {
  * @see {@link transformOptionalEffect} for custom effectful missing-key handling
  * @see {@link required} when absent input should fail instead of using a default
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -1048,6 +1079,7 @@ export function withDefault<T, R = never>(
  *
  * @see {@link transform} for custom string conversions
  *
+ * @stability stable
  * @category converting
  * @since 4.0.0
  */
@@ -1079,6 +1111,7 @@ export function String<E>(): Getter<string, E> {
  *
  * @see {@link transformEffect} for effectful or validated number parsing
  *
+ * @stability stable
  * @category converting
  * @since 4.0.0
  */
@@ -1107,6 +1140,7 @@ export function Number<E>(): Getter<number, E> {
  * Effect.runSync(SchemaGetter.run(toBool, Option.some("true"), {})) // => Option.some(true)
  * ```
  *
+ * @stability stable
  * @category converting
  * @since 4.0.0
  */
@@ -1136,6 +1170,7 @@ export function Boolean<E>(): Getter<boolean, E> {
  * Effect.runSync(SchemaGetter.run(toBigInt, Option.some("42"), {})) // => Option.some(42n)
  * ```
  *
+ * @stability stable
  * @category converting
  * @since 4.0.0
  */
@@ -1168,6 +1203,7 @@ export function BigInt<E extends string | number | bigint | boolean>(): Getter<b
  *
  * @see {@link dateTimeUtcFromInput} for validated DateTime parsing
  *
+ * @stability stable
  * @category converting
  * @since 4.0.0
  */
@@ -1191,6 +1227,7 @@ export function Date<E extends string | number | Date>(): Getter<Date, E> {
  * Effect.runSync(SchemaGetter.run(trimmed, Option.some("  hello  "), {})) // => Option.some("hello")
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -1214,6 +1251,7 @@ export function trim<E extends string>(): Getter<string, E> {
  * Effect.runSync(SchemaGetter.run(cap, Option.some("hello"), {})) // => Option.some("Hello")
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -1237,6 +1275,7 @@ export function capitalize<E extends string>(): Getter<string, E> {
  * Effect.runSync(SchemaGetter.run(uncap, Option.some("Hello"), {})) // => Option.some("hello")
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -1262,6 +1301,7 @@ export function uncapitalize<E extends string>(): Getter<string, E> {
  *
  * @see {@link camelToSnake} for the inverse operation
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -1287,6 +1327,7 @@ export function snakeToCamel<E extends string>(): Getter<string, E> {
  *
  * @see {@link snakeToCamel} for the inverse operation
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -1312,6 +1353,7 @@ export function camelToSnake<E extends string>(): Getter<string, E> {
  *
  * @see {@link toUpperCase} for the inverse operation
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -1337,6 +1379,7 @@ export function toLowerCase<E extends string>(): Getter<string, E> {
  *
  * @see {@link toLowerCase} for the inverse operation
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -1377,6 +1420,7 @@ type ParseJsonOptions = {
  *
  * @see {@link stringifyJson} for the inverse operation
  *
+ * @stability stable
  * @category decoding
  * @since 4.0.0
  */
@@ -1399,6 +1443,7 @@ export function parseJson<E extends string>(options?: ParseJsonOptions | undefin
 /**
  * Replacer function or property allowlist accepted by `JSON.stringify`.
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -1440,6 +1485,7 @@ type StringifyJsonOptions = {
  *
  * @see {@link parseJson} for the inverse operation
  *
+ * @stability stable
  * @category encoding
  * @since 4.0.0
  */
@@ -1474,8 +1520,9 @@ export function stringifyJson(options?: StringifyJsonOptions): Getter<string, un
  * **Details**
  *
  * The getter is pure and never fails. It splits the string by `separator`
- * (default `,`) and then each pair by `keyValueSeparator` (default `=`). Pairs
- * missing a key or value are silently skipped.
+ * (default `,`) and then each pair at the first `keyValueSeparator` (default `=`),
+ * preserving the rest of the value. An empty `keyValueSeparator` uses the first
+ * two characters as the key and value. Pairs missing a key or value are skipped.
  *
  * **Example** (Parsing a key-value string)
  *
@@ -1490,6 +1537,7 @@ export function stringifyJson(options?: StringifyJsonOptions): Getter<string, un
  * @see {@link joinKeyValue} for the inverse operation
  * @see {@link split} to split into an array of strings
  *
+ * @stability stable
  * @category splitting
  * @since 4.0.0
  */
@@ -1501,8 +1549,16 @@ export function splitKeyValue<E extends string>(options?: {
   const keyValueSeparator = options?.keyValueSeparator ?? "="
   return transform((input) =>
     input.split(separator).reduce((acc, pair) => {
-      const [key, value] = pair.split(keyValueSeparator)
-      if (key && value) {
+      if (keyValueSeparator === "") {
+        const [key, value] = pair.split("")
+        if (key && value) InternalRecord.assignProperty(acc, key, value)
+        return acc
+      }
+      const index = pair.indexOf(keyValueSeparator)
+      if (index <= 0) return acc
+      const key = pair.slice(0, index)
+      const value = pair.slice(index + keyValueSeparator.length)
+      if (value) {
         InternalRecord.assignProperty(acc, key, value)
       }
       return acc
@@ -1536,6 +1592,7 @@ export function splitKeyValue<E extends string>(options?: {
  *
  * @see {@link splitKeyValue} for the inverse operation
  *
+ * @stability stable
  * @category combining
  * @since 4.0.0
  */
@@ -1575,6 +1632,7 @@ export function joinKeyValue<E extends Record<PropertyKey, string>>(options?: {
  *
  * @see {@link splitKeyValue} when values are key-value pairs
  *
+ * @stability stable
  * @category splitting
  * @since 4.0.0
  */
@@ -1606,6 +1664,7 @@ export function split<E extends string>(options?: {
  * @see {@link decodeBase64String} for the inverse operation to `string`
  * @see {@link encodeBase64Url} for the URL-safe variant
  *
+ * @stability stable
  * @category encoding
  * @since 4.0.0
  */
@@ -1634,6 +1693,7 @@ export function encodeBase64<E extends Uint8Array | string>(): Getter<string, E>
  * @see {@link decodeBase64UrlString} for the inverse operation to `string`
  * @see {@link encodeBase64} for the standard Base64 variant
  *
+ * @stability stable
  * @category encoding
  * @since 4.0.0
  */
@@ -1661,6 +1721,7 @@ export function encodeBase64Url<E extends Uint8Array | string>(): Getter<string,
  * @see {@link decodeHex} for the inverse operation to `Uint8Array`
  * @see {@link decodeHexString} for the inverse operation to `string`
  *
+ * @stability stable
  * @category encoding
  * @since 4.0.0
  */
@@ -1688,6 +1749,7 @@ export function encodeHex<E extends Uint8Array | string>(): Getter<string, E> {
  * @see {@link decodeBase64String} to decode to `string` instead
  * @see {@link encodeBase64} for the inverse operation
  *
+ * @stability stable
  * @category decoding
  * @since 4.0.0
  */
@@ -1725,6 +1787,7 @@ export function decodeBase64<E extends string>(): Getter<Uint8Array, E> {
  * @see {@link decodeBase64} to decode to `Uint8Array` instead
  * @see {@link encodeBase64} for the inverse operation
  *
+ * @stability stable
  * @category decoding
  * @since 4.0.0
  */
@@ -1764,6 +1827,7 @@ export function decodeBase64String<E extends string>(): Getter<string, E> {
  * @see {@link decodeBase64UrlString} to decode to `string` instead
  * @see {@link encodeBase64Url} for the inverse operation
  *
+ * @stability stable
  * @category decoding
  * @since 4.0.0
  */
@@ -1803,6 +1867,7 @@ export function decodeBase64Url<E extends string>(): Getter<Uint8Array, E> {
  * @see {@link decodeBase64Url} to decode to `Uint8Array` instead
  * @see {@link encodeBase64Url} for the inverse operation
  *
+ * @stability stable
  * @category decoding
  * @since 4.0.0
  */
@@ -1842,6 +1907,7 @@ export function decodeBase64UrlString<E extends string>(): Getter<string, E> {
  * @see {@link decodeHexString} to decode to `string` instead
  * @see {@link encodeHex} for the inverse operation
  *
+ * @stability stable
  * @category decoding
  * @since 4.0.0
  */
@@ -1881,6 +1947,7 @@ export function decodeHex<E extends string>(): Getter<Uint8Array, E> {
  * @see {@link decodeHex} to decode to `Uint8Array` instead
  * @see {@link encodeHex} for the inverse operation
  *
+ * @stability stable
  * @category decoding
  * @since 4.0.0
  */
@@ -1921,6 +1988,7 @@ export function decodeHexString<E extends string>(): Getter<string, E> {
  *
  * @see {@link decodeUriComponent} for the inverse operation
  *
+ * @stability stable
  * @category encoding
  * @since 4.0.0
  */
@@ -1947,6 +2015,7 @@ export function encodeUriComponent<E extends string>(): Getter<string, E> {
  *
  * @see {@link encodeUriComponent} for the inverse operation
  *
+ * @stability stable
  * @category decoding
  * @since 4.0.0
  */
@@ -1997,6 +2066,7 @@ export function decodeUriComponent<E extends string>(): Getter<string, E> {
  *
  * @see {@link Date} for a simpler coercion to `Date` (no validation)
  *
+ * @stability stable
  * @category converting
  * @since 4.0.0
  */
@@ -2042,6 +2112,7 @@ export function dateTimeUtcFromInput<E extends DateTime.DateTime.Input>(): Gette
  * @see {@link makeTreeRecord} for the underlying bracket-path parser
  * @see {@link decodeURLSearchParams} for the URLSearchParams variant
  *
+ * @stability stable
  * @category decoding
  * @since 4.0.0
  */
@@ -2081,6 +2152,7 @@ const collectFormDataEntries = collectBracketPathEntries((value): value is strin
  * @see {@link collectBracketPathEntries} for the underlying flattener
  * @see {@link encodeURLSearchParams} for the URLSearchParams variant
  *
+ * @stability stable
  * @category encoding
  * @since 4.0.0
  */
@@ -2126,6 +2198,7 @@ export function encodeFormData(): Getter<FormData, unknown> {
  * @see {@link makeTreeRecord} for the underlying bracket-path parser
  * @see {@link decodeFormData} for the FormData variant
  *
+ * @stability stable
  * @category decoding
  * @since 4.0.0
  */
@@ -2162,6 +2235,7 @@ const collectURLSearchParamsEntries = collectBracketPathEntries(Predicate.isStri
  * @see {@link collectBracketPathEntries} for the underlying flattener
  * @see {@link encodeFormData} for the FormData variant
  *
+ * @stability stable
  * @category encoding
  * @since 4.0.0
  */
@@ -2235,6 +2309,7 @@ function bracketPathToTokens(bracketPath: string): Array<string | number> {
  * @see {@link decodeFormData} for a higher-level FormData decoder
  * @see {@link decodeURLSearchParams} for a higher-level URLSearchParams decoder
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -2333,6 +2408,7 @@ export function makeTreeRecord<A>(
  * @see {@link encodeFormData} for a higher-level FormData encoder
  * @see {@link encodeURLSearchParams} for a higher-level URLSearchParams encoder
  *
+ * @stability stable
  * @category converting
  * @since 4.0.0
  */