effect 4.0.0-rc.111 → 4.0.0-rc.113

package/src/Iterable.ts

@@ -12,6 +12,7 @@
 import type { NonEmptyArray } from "./Array.ts"
 import * as Equal from "./Equal.ts"
 import { dual } from "./Function.ts"
+import * as Count from "./internal/count.ts"
 import * as InternalRecord from "./internal/record.ts"
 import type { Option } from "./Option.ts"
 import * as O from "./Option.ts"
@@ -27,9 +28,9 @@ import type { NoInfer } from "./Types.ts"
  *
  * **Details**
  *
- * The function is called with each index starting from `0`. If no length is
- * specified, the iterable is infinite. This is useful for generating
- * sequences, patterns, or any indexed data.
+ * The function is called with each index starting from `0`. If a length is
+ * provided, it is rounded down and normalized to at least `1`, with `NaN`
+ * treated as `1`. If no length is specified, the iterable is infinite.
  *
  * **Example** (Generating values by index)
  *
@@ -56,7 +57,7 @@ import type { NoInfer } from "./Types.ts"
 export const makeBy = <A>(f: (i: number) => A, options?: {
   readonly length?: number
 }): Iterable<A> => {
-  const max = options?.length !== undefined ? Math.max(1, Math.floor(options.length)) : Infinity
+  const max = options?.length !== undefined ? Count.normalizeNonEmpty(options.length) : Infinity
   return {
     [Symbol.iterator]() {
       let i = 0
@@ -106,7 +107,8 @@ export const range = (start: number, end?: number): Iterable<number> => {
  *
  * **Details**
  *
- * `n` is normalized to an integer greater than or equal to `1`.
+ * `n` is rounded down and normalized to an integer greater than or equal to
+ * `1`. `NaN` is treated as `1`.
  *
  * **Example** (Repeating a value)
  *
@@ -125,7 +127,8 @@ export const replicate: {
    *
    * **Details**
    *
-   * `n` is normalized to an integer greater than or equal to `1`.
+   * `n` is rounded down and normalized to an integer greater than or equal to
+   * `1`. `NaN` is treated as `1`.
    *
    * **Example** (Repeating a value)
    *
@@ -144,7 +147,8 @@ export const replicate: {
    *
    * **Details**
    *
-   * `n` is normalized to an integer greater than or equal to `1`.
+   * `n` is rounded down and normalized to an integer greater than or equal to
+   * `1`. `NaN` is treated as `1`.
    *
    * **Example** (Repeating a value)
    *
@@ -170,7 +174,8 @@ export const replicate: {
  *
  * **Details**
  *
- * The result is lazy. Each repetition obtains a new iterator from `self`.
+ * The result is lazy. `n` is rounded down and normalized to at least `1`, with
+ * `NaN` treated as `1`. Each repetition obtains a new iterator from `self`.
  *
  * @see {@link forever} for repeating without an upper bound
  * @see {@link replicate} for repeating a single value
@@ -188,7 +193,8 @@ export const repeat: {
    *
    * **Details**
    *
-   * The result is lazy. Each repetition obtains a new iterator from `self`.
+   * The result is lazy. `n` is rounded down and normalized to at least `1`, with
+   * `NaN` treated as `1`. Each repetition obtains a new iterator from `self`.
    *
    * @see {@link forever} for repeating without an upper bound
    * @see {@link replicate} for repeating a single value
@@ -206,7 +212,8 @@ export const repeat: {
    *
    * **Details**
    *
-   * The result is lazy. Each repetition obtains a new iterator from `self`.
+   * The result is lazy. `n` is rounded down and normalized to at least `1`, with
+   * `NaN` treated as `1`. Each repetition obtains a new iterator from `self`.
    *
    * @see {@link forever} for repeating without an upper bound
    * @see {@link replicate} for repeating a single value
@@ -877,7 +884,8 @@ export const headUnsafe = <A>(self: Iterable<A>): A => {
  *
  * **Details**
  *
- * `n` is normalized to a non-negative integer.
+ * `n` is rounded down and normalized to a non-negative integer. `NaN` is
+ * treated as `0`.
  *
  * **Example** (Taking from the start)
  *
@@ -911,7 +919,8 @@ export const take: {
    *
    * **Details**
    *
-   * `n` is normalized to a non-negative integer.
+   * `n` is rounded down and normalized to a non-negative integer. `NaN` is
+   * treated as `0`.
    *
    * **Example** (Taking from the start)
    *
@@ -945,7 +954,8 @@ export const take: {
    *
    * **Details**
    *
-   * `n` is normalized to a non-negative integer.
+   * `n` is rounded down and normalized to a non-negative integer. `NaN` is
+   * treated as `0`.
    *
    * **Example** (Taking from the start)
    *
@@ -974,21 +984,24 @@ export const take: {
    * @since 2.0.0
    */
   <A>(self: Iterable<A>, n: number): Iterable<A>
-} = dual(2, <A>(self: Iterable<A>, n: number): Iterable<A> => ({
-  [Symbol.iterator]() {
-    let i = 0
-    const iterator = self[Symbol.iterator]()
-    return {
-      next() {
-        if (i < n) {
-          i++
-          return iterator.next()
+} = dual(2, <A>(self: Iterable<A>, n: number): Iterable<A> => {
+  const count = Count.normalize(n)
+  return {
+    [Symbol.iterator]() {
+      let i = 0
+      const iterator = self[Symbol.iterator]()
+      return {
+        next() {
+          if (i < count) {
+            i++
+            return iterator.next()
+          }
+          return { done: true, value: undefined }
         }
-        return { done: true, value: undefined }
       }
     }
   }
-}))
+})
 
 /**
  * Takes the longest initial `Iterable` prefix for which all elements satisfy the
@@ -1191,7 +1204,8 @@ export const takeWhile: {
  *
  * **Details**
  *
- * `n` is normalized to a non-negative integer.
+ * `n` is rounded down and normalized to a non-negative integer. `NaN` is
+ * treated as `0`.
  *
  * **Example** (Dropping from the start)
  *
@@ -1224,7 +1238,8 @@ export const drop: {
    *
    * **Details**
    *
-   * `n` is normalized to a non-negative integer.
+   * `n` is rounded down and normalized to a non-negative integer. `NaN` is
+   * treated as `0`.
    *
    * **Example** (Dropping from the start)
    *
@@ -1257,7 +1272,8 @@ export const drop: {
    *
    * **Details**
    *
-   * `n` is normalized to a non-negative integer.
+   * `n` is rounded down and normalized to a non-negative integer. `NaN` is
+   * treated as `0`.
    *
    * **Example** (Dropping from the start)
    *
@@ -1285,24 +1301,27 @@ export const drop: {
    * @since 2.0.0
    */
   <A>(self: Iterable<A>, n: number): Iterable<A>
-} = dual(2, <A>(self: Iterable<A>, n: number): Iterable<A> => ({
-  [Symbol.iterator]() {
-    const iterator = self[Symbol.iterator]()
-    let i = 0
-    return {
-      next() {
-        while (i < n) {
-          const result = iterator.next()
-          if (result.done) {
-            return { done: true, value: undefined }
+} = dual(2, <A>(self: Iterable<A>, n: number): Iterable<A> => {
+  const count = Count.normalize(n)
+  return {
+    [Symbol.iterator]() {
+      const iterator = self[Symbol.iterator]()
+      let i = 0
+      return {
+        next() {
+          while (i < count) {
+            const result = iterator.next()
+            if (result.done) {
+              return { done: true, value: undefined }
+            }
+            i++
           }
-          i++
+          return iterator.next()
         }
-        return iterator.next()
       }
     }
   }
-}))
+})
 
 /**
  * Returns the first element that satisfies the specified
@@ -2465,6 +2484,8 @@ export const contains: {
 /**
  * Splits an `Iterable` into length-`n` pieces. The last piece will be shorter if `n` does not evenly divide the length of
  * the `Iterable`.
+ * `n` is rounded down and normalized to at least `1`; `NaN` and non-positive
+ * values therefore produce singleton pieces.
  *
  * **Example** (Chunking an iterable)
  *
@@ -2502,6 +2523,8 @@ export const chunksOf: {
   /**
    * Splits an `Iterable` into length-`n` pieces. The last piece will be shorter if `n` does not evenly divide the length of
    * the `Iterable`.
+   * `n` is rounded down and normalized to at least `1`; `NaN` and non-positive
+   * values therefore produce singleton pieces.
    *
    * **Example** (Chunking an iterable)
    *
@@ -2539,6 +2562,8 @@ export const chunksOf: {
   /**
    * Splits an `Iterable` into length-`n` pieces. The last piece will be shorter if `n` does not evenly divide the length of
    * the `Iterable`.
+   * `n` is rounded down and normalized to at least `1`; `NaN` and non-positive
+   * values therefore produce singleton pieces.
    *
    * **Example** (Chunking an iterable)
    *
@@ -2574,7 +2599,7 @@ export const chunksOf: {
    */
   <A>(self: Iterable<A>, n: number): Iterable<Array<A>>
 } = dual(2, <A>(self: Iterable<A>, n: number): Iterable<Array<A>> => {
-  const safeN = Math.max(1, Math.floor(n))
+  const safeN = Count.normalizeNonEmpty(n)
   return ({
     [Symbol.iterator]() {
       let iterator: Iterator<A> | undefined = self[Symbol.iterator]()
@@ -2790,6 +2815,13 @@ export const group: <A>(self: Iterable<A>) => Iterable<NonEmptyArray<A>> = group
  * that produced that key. Unlike `group`, matching elements do not need to be
  * consecutive.
  *
+ * **Gotchas**
+ *
+ * When the key function returns a finite union of string literals or unique
+ * symbols, the result preserves those keys as optional properties because the
+ * input may not produce every key. Open `string` and `symbol` key types retain
+ * their record index signatures.
+ *
  * **Example** (Grouping by a key)
  *
  * ```ts import.meta.vitest
@@ -2834,6 +2866,13 @@ export const groupBy: {
    * that produced that key. Unlike `group`, matching elements do not need to be
    * consecutive.
    *
+   * **Gotchas**
+   *
+   * When the key function returns a finite union of string literals or unique
+   * symbols, the result preserves those keys as optional properties because the
+   * input may not produce every key. Open `string` and `symbol` key types retain
+   * their record index signatures.
+   *
    * **Example** (Grouping by a key)
    *
    * ```ts import.meta.vitest
@@ -2868,7 +2907,7 @@ export const groupBy: {
    * @category grouping
    * @since 2.0.0
    */
-  <A, K extends string | symbol>(f: (a: A) => K): (self: Iterable<A>) => Record<Record.ReadonlyRecord.NonLiteralKey<K>, NonEmptyArray<A>>
+  <A, K extends string | symbol>(f: (a: A) => K): (self: Iterable<A>) => Record.ReadonlyRecord.GroupByResult<K, NonEmptyArray<A>>
   /**
    * Groups all elements by the string or symbol key returned by `f`.
    *
@@ -2878,6 +2917,13 @@ export const groupBy: {
    * that produced that key. Unlike `group`, matching elements do not need to be
    * consecutive.
    *
+   * **Gotchas**
+   *
+   * When the key function returns a finite union of string literals or unique
+   * symbols, the result preserves those keys as optional properties because the
+   * input may not produce every key. Open `string` and `symbol` key types retain
+   * their record index signatures.
+   *
    * **Example** (Grouping by a key)
    *
    * ```ts import.meta.vitest
@@ -2912,11 +2958,11 @@ export const groupBy: {
    * @category grouping
    * @since 2.0.0
    */
-  <A, K extends string | symbol>(self: Iterable<A>, f: (a: A) => K): Record<Record.ReadonlyRecord.NonLiteralKey<K>, NonEmptyArray<A>>
+  <A, K extends string | symbol>(self: Iterable<A>, f: (a: A) => K): Record.ReadonlyRecord.GroupByResult<K, NonEmptyArray<A>>
 } = dual(2, <A, K extends string | symbol>(
   self: Iterable<A>,
   f: (a: A) => K
-): Record<Record.ReadonlyRecord.NonLiteralKey<K>, NonEmptyArray<A>> => {
+): Record.ReadonlyRecord.GroupByResult<K, NonEmptyArray<A>> => {
   const out: Record<string | symbol, NonEmptyArray<A>> = {}
   for (const a of self) {
     const k = f(a)

package/src/JsonPatch.ts

@@ -307,8 +307,8 @@ function tokenize(pointer: string): Array<string> {
   return pointer.split("/").slice(1).map(unescapeToken)
 }
 
-/** Convert a reference token to a non-negative array index (rejects `-` and negatives). */
-function toIndex(token: string): number {
+/** Converts a JSON Pointer reference token to a non-negative array index. */
+function toJsonPointerArrayIndex(token: string): number {
   if (!/^(0|[1-9]\d*)$/.test(token)) {
     throw new Error(`Invalid array index: "${token}"`)
   }
@@ -332,7 +332,7 @@ function applyOperation(doc: Schema.Json, op: JsonPatchOperation): Schema.Json {
     if (lastToken === "-" && op.op !== "add") {
       throw new Error(`"-" is not valid for ${op.op} at "${op.path}".`)
     }
-    const index = lastToken === "-" ? parent.length : toIndex(lastToken)
+    const index = lastToken === "-" ? parent.length : toJsonPointerArrayIndex(lastToken)
     const maxIndex = op.op === "add" ? parent.length : parent.length - 1
     if (index > maxIndex) throw new Error(`Array index out of bounds at "${op.path}".`)
     const updated = parent.slice()
@@ -374,7 +374,7 @@ function resolveParent(
     const token = tokens[i]
 
     if (Array.isArray(cur)) {
-      const idx = toIndex(token)
+      const idx = toJsonPointerArrayIndex(token)
       if (idx >= cur.length) return null
       stack.push({ container: cur, token: idx })
       cur = cur[idx]

package/src/JsonPointer.ts

@@ -1,8 +1,8 @@
 /**
- * Helpers for escaping and unescaping JSON Pointer path segments. JSON Pointer
- * uses `/` to separate path tokens inside a JSON document, so token text must
- * encode literal `~` and `/` characters. This module provides the two RFC 6901
- * token conversions used by JSON Patch and related path handling.
+ * Helpers for escaping JSON Pointer path segments and converting JSON Pointer
+ * URI fragments. JSON Pointer uses `/` to separate path tokens inside a JSON
+ * document, so token text must encode literal `~` and `/` characters. URI
+ * fragments additionally apply percent-encoding after JSON Pointer escaping.
  *
  * @since 4.0.0
  */
@@ -78,3 +78,96 @@ export function escapeToken(token: string): string {
 export function unescapeToken(token: string): string {
   return token.replace(/~1/g, "/").replace(/~0/g, "~");
 }
+
+/** @internal */
+export function formatUriFragmentToken(token: string): string {
+  return encodeURI(escapeToken(token)).replace(/#/g, "%23");
+}
+
+/** @internal */
+export function decodeUriFragment(fragment: string): string | undefined {
+  if (fragment.length === 0 || fragment === "#") return ""
+  if (!fragment.startsWith("#")) return undefined
+  const encoded = fragment.slice(1)
+  try {
+    if (encodeURI(encoded).replace(/%25/g, "%").replace(/#/g, "%23") !== encoded) return undefined
+    const pointer = decodeURIComponent(encoded)
+    return pointer.startsWith("/") && !/~(?:[^01]|$)/.test(pointer) ? pointer : undefined;
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Parses a JSON Pointer URI fragment into decoded path tokens.
+ *
+ * **When to use**
+ *
+ * Use when you need to resolve a URI fragment against a JSON document.
+ *
+ * **Details**
+ *
+ * Percent-encoding is decoded before the pointer is split into tokens, then
+ * each token is decoded with {@link unescapeToken}. The empty string and `#`
+ * both represent the document root.
+ *
+ * **Gotchas**
+ *
+ * Returns `undefined` when the input is not a URI fragment, contains characters
+ * that require percent-encoding, or contains an invalid JSON Pointer escape
+ * sequence.
+ *
+ * **Example** (Parsing URI fragments)
+ *
+ * ```ts import.meta.vitest
+ * import { JsonPointer } from "effect"
+ *
+ * JsonPointer.parseUriFragment("#/users/a~1b") // => ["users", "a/b"]
+ * JsonPointer.parseUriFragment("#/caf%C3%A9") // => ["café"]
+ * JsonPointer.parseUriFragment("#/%") // => undefined
+ * JsonPointer.parseUriFragment("#/a#b") // => undefined
+ * ```
+ *
+ * @see {@link formatUriFragment} for the inverse operation
+ * @category decoding
+ * @since 4.0.0
+ */
+export function parseUriFragment(fragment: string): ReadonlyArray<string> | undefined {
+  const pointer = decodeUriFragment(fragment)
+  return pointer === undefined ? undefined : pointer.length === 0 ? [] : pointer.slice(1).split("/").map(unescapeToken)
+}
+
+/**
+ * Formats path tokens as a JSON Pointer URI fragment.
+ *
+ * **When to use**
+ *
+ * Use when you need a URI fragment that identifies a value in a JSON document.
+ *
+ * **Details**
+ *
+ * Each token is encoded with {@link escapeToken} before URI percent-encoding
+ * is applied. An empty path is formatted as `#`.
+ *
+ * **Gotchas**
+ *
+ * Throws a `URIError` when a token contains an unpaired surrogate.
+ *
+ * **Example** (Formatting a URI fragment)
+ *
+ * ```ts import.meta.vitest
+ * import { JsonPointer } from "effect"
+ *
+ * JsonPointer.formatUriFragment(["users", "a/b", "Rate%"]) // => "#/users/a~1b/Rate%25"
+ * ```
+ *
+ * @see {@link parseUriFragment} for the inverse operation
+ * @category encoding
+ * @since 4.0.0
+ */
+export function formatUriFragment(path: ReadonlyArray<string>): string {
+  return path.reduce(
+    (fragment, token) => `${fragment}/${formatUriFragmentToken(token)}`,
+    "#"
+  )
+}