effect 3.8.4 → 3.9.0

package/src/StreamHaltStrategy.ts

@@ -108,16 +108,33 @@ export const isEither: (self: HaltStrategy) => self is Either = internal.isEithe
  * @category folding
  */
 export const match: {
-  <Z>(options: {
-    readonly onLeft: () => Z
-    readonly onRight: () => Z
-    readonly onBoth: () => Z
-    readonly onEither: () => Z
-  }): (self: HaltStrategy) => Z
-  <Z>(self: HaltStrategy, options: {
-    readonly onLeft: () => Z
-    readonly onRight: () => Z
-    readonly onBoth: () => Z
-    readonly onEither: () => Z
-  }): Z
+  /**
+   * Folds over the specified `HaltStrategy` using the provided case functions.
+   *
+   * @since 2.0.0
+   * @category folding
+   */
+  <Z>(
+    options: {
+      readonly onLeft: () => Z
+      readonly onRight: () => Z
+      readonly onBoth: () => Z
+      readonly onEither: () => Z
+    }
+  ): (self: HaltStrategy) => Z
+  /**
+   * Folds over the specified `HaltStrategy` using the provided case functions.
+   *
+   * @since 2.0.0
+   * @category folding
+   */
+  <Z>(
+    self: HaltStrategy,
+    options: {
+      readonly onLeft: () => Z
+      readonly onRight: () => Z
+      readonly onBoth: () => Z
+      readonly onEither: () => Z
+    }
+  ): Z
 } = internal.match

package/src/String.ts

@@ -65,7 +65,17 @@ export type Concat<A extends string, B extends string> = `${A}${B}`
  * @since 2.0.0
  */
 export const concat: {
+  /**
+   * Concatenates two strings at runtime.
+   *
+   * @since 2.0.0
+   */
   <B extends string>(that: B): <A extends string>(self: A) => Concat<A, B>
+  /**
+   * Concatenates two strings at runtime.
+   *
+   * @since 2.0.0
+   */
   <A extends string, B extends string>(self: A, that: B): Concat<A, B>
 } = dual(2, (self: string, that: string): string => self + that)
 
@@ -225,7 +235,25 @@ export const length = (self: string): number => self.length
  * @since 2.0.0
  */
 export const split: {
+  /**
+   * @example
+   * import { pipe, String } from "effect"
+   *
+   * assert.deepStrictEqual(pipe('abc', String.split('')), ['a', 'b', 'c'])
+   * assert.deepStrictEqual(pipe('', String.split('')), [''])
+   *
+   * @since 2.0.0
+   */
   (separator: string | RegExp): (self: string) => NonEmptyArray<string>
+  /**
+   * @example
+   * import { pipe, String } from "effect"
+   *
+   * assert.deepStrictEqual(pipe('abc', String.split('')), ['a', 'b', 'c'])
+   * assert.deepStrictEqual(pipe('', String.split('')), [''])
+   *
+   * @since 2.0.0
+   */
   (self: string, separator: string | RegExp): NonEmptyArray<string>
 } = dual(2, (self: string, separator: string | RegExp): NonEmptyArray<string> => {
   const out = self.split(separator)
@@ -263,7 +291,25 @@ export const endsWith = (searchString: string, position?: number) => (self: stri
  * @since 2.0.0
  */
 export const charCodeAt: {
+  /**
+   * @example
+   * import { pipe, String, Option } from "effect"
+   *
+   * assert.deepStrictEqual(pipe("abc", String.charCodeAt(1)), Option.some(98))
+   * assert.deepStrictEqual(pipe("abc", String.charCodeAt(4)), Option.none())
+   *
+   * @since 2.0.0
+   */
   (index: number): (self: string) => Option.Option<number>
+  /**
+   * @example
+   * import { pipe, String, Option } from "effect"
+   *
+   * assert.deepStrictEqual(pipe("abc", String.charCodeAt(1)), Option.some(98))
+   * assert.deepStrictEqual(pipe("abc", String.charCodeAt(4)), Option.none())
+   *
+   * @since 2.0.0
+   */
   (self: string, index: number): Option.Option<number>
 } = dual(
   2,
@@ -292,7 +338,25 @@ export const substring = (start: number, end?: number) => (self: string): string
  * @since 2.0.0
  */
 export const at: {
+  /**
+   * @example
+   * import { pipe, String, Option } from "effect"
+   *
+   * assert.deepStrictEqual(pipe("abc", String.at(1)), Option.some("b"))
+   * assert.deepStrictEqual(pipe("abc", String.at(4)), Option.none())
+   *
+   * @since 2.0.0
+   */
   (index: number): (self: string) => Option.Option<string>
+  /**
+   * @example
+   * import { pipe, String, Option } from "effect"
+   *
+   * assert.deepStrictEqual(pipe("abc", String.at(1)), Option.some("b"))
+   * assert.deepStrictEqual(pipe("abc", String.at(4)), Option.none())
+   *
+   * @since 2.0.0
+   */
   (self: string, index: number): Option.Option<string>
 } = dual(2, (self: string, index: number): Option.Option<string> => Option.fromNullable(self.at(index)))
 
@@ -306,7 +370,25 @@ export const at: {
  * @since 2.0.0
  */
 export const charAt: {
+  /**
+   * @example
+   * import { pipe, String, Option } from "effect"
+   *
+   * assert.deepStrictEqual(pipe("abc", String.charAt(1)), Option.some("b"))
+   * assert.deepStrictEqual(pipe("abc", String.charAt(4)), Option.none())
+   *
+   * @since 2.0.0
+   */
   (index: number): (self: string) => Option.Option<string>
+  /**
+   * @example
+   * import { pipe, String, Option } from "effect"
+   *
+   * assert.deepStrictEqual(pipe("abc", String.charAt(1)), Option.some("b"))
+   * assert.deepStrictEqual(pipe("abc", String.charAt(4)), Option.none())
+   *
+   * @since 2.0.0
+   */
   (self: string, index: number): Option.Option<string>
 } = dual(
   2,
@@ -322,7 +404,23 @@ export const charAt: {
  * @since 2.0.0
  */
 export const codePointAt: {
+  /**
+   * @example
+   * import { pipe, String, Option } from "effect"
+   *
+   * assert.deepStrictEqual(pipe("abc", String.codePointAt(1)), Option.some(98))
+   *
+   * @since 2.0.0
+   */
   (index: number): (self: string) => Option.Option<number>
+  /**
+   * @example
+   * import { pipe, String, Option } from "effect"
+   *
+   * assert.deepStrictEqual(pipe("abc", String.codePointAt(1)), Option.some(98))
+   *
+   * @since 2.0.0
+   */
   (self: string, index: number): Option.Option<number>
 } = dual(2, (self: string, index: number): Option.Option<number> => Option.fromNullable(self.codePointAt(index)))
 
@@ -450,7 +548,27 @@ export const replaceAll = (searchValue: string | RegExp, replaceValue: string) =
  * @since 2.0.0
  */
 export const search: {
+  /**
+   * @example
+   * import { pipe, String, Option } from "effect"
+   *
+   * assert.deepStrictEqual(pipe("ababb", String.search("b")), Option.some(1))
+   * assert.deepStrictEqual(pipe("ababb", String.search(/abb/)), Option.some(2))
+   * assert.deepStrictEqual(pipe("ababb", String.search("d")), Option.none())
+   *
+   * @since 2.0.0
+   */
   (regexp: RegExp | string): (self: string) => Option.Option<number>
+  /**
+   * @example
+   * import { pipe, String, Option } from "effect"
+   *
+   * assert.deepStrictEqual(pipe("ababb", String.search("b")), Option.some(1))
+   * assert.deepStrictEqual(pipe("ababb", String.search(/abb/)), Option.some(2))
+   * assert.deepStrictEqual(pipe("ababb", String.search("d")), Option.none())
+   *
+   * @since 2.0.0
+   */
   (self: string, regexp: RegExp | string): Option.Option<number>
 } = dual(
   2,
@@ -500,7 +618,41 @@ export const toLocaleUpperCase = (locale?: string | Array<string>) => (self: str
  * @since 2.0.0
  */
 export const takeLeft: {
+  /**
+   * Keep the specified number of characters from the start of a string.
+   *
+   * If `n` is larger than the available number of characters, the string will
+   * be returned whole.
+   *
+   * If `n` is not a positive number, an empty string will be returned.
+   *
+   * If `n` is a float, it will be rounded down to the nearest integer.
+   *
+   * @example
+   * import { String } from "effect"
+   *
+   * assert.deepStrictEqual(String.takeLeft("Hello World", 5), "Hello")
+   *
+   * @since 2.0.0
+   */
   (n: number): (self: string) => string
+  /**
+   * Keep the specified number of characters from the start of a string.
+   *
+   * If `n` is larger than the available number of characters, the string will
+   * be returned whole.
+   *
+   * If `n` is not a positive number, an empty string will be returned.
+   *
+   * If `n` is a float, it will be rounded down to the nearest integer.
+   *
+   * @example
+   * import { String } from "effect"
+   *
+   * assert.deepStrictEqual(String.takeLeft("Hello World", 5), "Hello")
+   *
+   * @since 2.0.0
+   */
   (self: string, n: number): string
 } = dual(2, (self: string, n: number): string => self.slice(0, Math.max(n, 0)))
 
@@ -522,7 +674,41 @@ export const takeLeft: {
  * @since 2.0.0
  */
 export const takeRight: {
+  /**
+   * Keep the specified number of characters from the end of a string.
+   *
+   * If `n` is larger than the available number of characters, the string will
+   * be returned whole.
+   *
+   * If `n` is not a positive number, an empty string will be returned.
+   *
+   * If `n` is a float, it will be rounded down to the nearest integer.
+   *
+   * @example
+   * import { String } from "effect"
+   *
+   * assert.deepStrictEqual(String.takeRight("Hello World", 5), "World")
+   *
+   * @since 2.0.0
+   */
   (n: number): (self: string) => string
+  /**
+   * Keep the specified number of characters from the end of a string.
+   *
+   * If `n` is larger than the available number of characters, the string will
+   * be returned whole.
+   *
+   * If `n` is not a positive number, an empty string will be returned.
+   *
+   * If `n` is a float, it will be rounded down to the nearest integer.
+   *
+   * @example
+   * import { String } from "effect"
+   *
+   * assert.deepStrictEqual(String.takeRight("Hello World", 5), "World")
+   *
+   * @since 2.0.0
+   */
   (self: string, n: number): string
 } = dual(
   2,
@@ -556,7 +742,21 @@ export const linesWithSeparators = (s: string): LinesIterator => linesSeparated(
  * @since 2.0.0
  */
 export const stripMarginWith: {
+  /**
+   * For every line in this string, strip a leading prefix consisting of blanks
+   * or control characters followed by the character specified by `marginChar`
+   * from the line.
+   *
+   * @since 2.0.0
+   */
   (marginChar: string): (self: string) => string
+  /**
+   * For every line in this string, strip a leading prefix consisting of blanks
+   * or control characters followed by the character specified by `marginChar`
+   * from the line.
+   *
+   * @since 2.0.0
+   */
   (self: string, marginChar: string): string
 } = dual(2, (self: string, marginChar: string): string => {
   let out = ""

package/src/Struct.ts

@@ -22,11 +22,31 @@ import type { MatchRecord, Simplify } from "./Types.js"
  * @since 2.0.0
  */
 export const pick: {
-  <Keys extends Array<PropertyKey>>(
-    ...keys: Keys
-  ): <S extends { [K in Keys[number]]?: any }>(
+  /**
+   * Create a new object by picking properties of an existing object.
+   *
+   * @example
+   * import { pipe, Struct } from "effect"
+   *
+   * assert.deepStrictEqual(pipe({ a: "a", b: 1, c: true }, Struct.pick("a", "b")), { a: "a", b: 1 })
+   * assert.deepStrictEqual(Struct.pick({ a: "a", b: 1, c: true }, "a", "b"), { a: "a", b: 1 })
+   *
+   * @since 2.0.0
+   */
+  <Keys extends Array<PropertyKey>>(...keys: Keys): <S extends { [K in Keys[number]]?: any }>(
     s: S
   ) => MatchRecord<S, { [K in Keys[number]]?: S[K] }, Simplify<Pick<S, Keys[number]>>>
+  /**
+   * Create a new object by picking properties of an existing object.
+   *
+   * @example
+   * import { pipe, Struct } from "effect"
+   *
+   * assert.deepStrictEqual(pipe({ a: "a", b: 1, c: true }, Struct.pick("a", "b")), { a: "a", b: 1 })
+   * assert.deepStrictEqual(Struct.pick({ a: "a", b: 1, c: true }, "a", "b"), { a: "a", b: 1 })
+   *
+   * @since 2.0.0
+   */
   <S extends object, Keys extends Array<keyof S>>(
     s: S,
     ...keys: Keys
@@ -56,13 +76,32 @@ export const pick: {
  * @since 2.0.0
  */
 export const omit: {
+  /**
+   * Create a new object by omitting properties of an existing object.
+   *
+   * @example
+   * import { pipe, Struct } from "effect"
+   *
+   * assert.deepStrictEqual(pipe({ a: "a", b: 1, c: true }, Struct.omit("c")), { a: "a", b: 1 })
+   * assert.deepStrictEqual(Struct.omit({ a: "a", b: 1, c: true }, "c"), { a: "a", b: 1 })
+   *
+   * @since 2.0.0
+   */
   <Keys extends Array<PropertyKey>>(
     ...keys: Keys
   ): <S extends { [K in Keys[number]]?: any }>(s: S) => Simplify<Omit<S, Keys[number]>>
-  <S extends object, Keys extends Array<keyof S>>(
-    s: S,
-    ...keys: Keys
-  ): Simplify<Omit<S, Keys[number]>>
+  /**
+   * Create a new object by omitting properties of an existing object.
+   *
+   * @example
+   * import { pipe, Struct } from "effect"
+   *
+   * assert.deepStrictEqual(pipe({ a: "a", b: 1, c: true }, Struct.omit("c")), { a: "a", b: 1 })
+   * assert.deepStrictEqual(Struct.omit({ a: "a", b: 1, c: true }, "c"), { a: "a", b: 1 })
+   *
+   * @since 2.0.0
+   */
+  <S extends object, Keys extends Array<keyof S>>(s: S, ...keys: Keys): Simplify<Omit<S, Keys[number]>>
 } = dual(
   (args) => Predicate.isObject(args[0]),
   <S extends object, Keys extends Array<keyof S>>(s: S, ...keys: Keys) => {
@@ -148,7 +187,47 @@ type PartialTransform<O, T> = {
  * @since 2.0.0
  */
 export const evolve: {
+  /**
+   * Transforms the values of a Struct provided a transformation function for each key.
+   * If no transformation function is provided for a key, it will return the origional value for that key.
+   *
+   * @example
+   * import { pipe, Struct } from "effect"
+   *
+   * assert.deepStrictEqual(
+   *   pipe(
+   *     { a: 'a', b: 1, c: 3 },
+   *     Struct.evolve({
+   *       a: (a) => a.length,
+   *       b: (b) => b * 2
+   *     })
+   *   ),
+   *   { a: 1, b: 2, c: 3 }
+   * )
+   *
+   * @since 2.0.0
+   */
   <O, T>(t: PartialTransform<O, T>): (obj: O) => Transformed<O, T>
+  /**
+   * Transforms the values of a Struct provided a transformation function for each key.
+   * If no transformation function is provided for a key, it will return the origional value for that key.
+   *
+   * @example
+   * import { pipe, Struct } from "effect"
+   *
+   * assert.deepStrictEqual(
+   *   pipe(
+   *     { a: 'a', b: 1, c: 3 },
+   *     Struct.evolve({
+   *       a: (a) => a.length,
+   *       b: (b) => b * 2
+   *     })
+   *   ),
+   *   { a: 1, b: 2, c: 3 }
+   * )
+   *
+   * @since 2.0.0
+   */
   <O, T>(obj: O, t: PartialTransform<O, T>): Transformed<O, T>
 } = dual(
   2,

package/src/Subscribable.ts

@@ -58,7 +58,15 @@ export const make = <A, E, R>(options: {
  * @category combinators
  */
 export const map: {
+  /**
+   * @since 2.0.0
+   * @category combinators
+   */
   <A, B>(f: (a: NoInfer<A>) => B): <E, R>(fa: Subscribable<A, E, R>) => Subscribable<B, E, R>
+  /**
+   * @since 2.0.0
+   * @category combinators
+   */
   <A, E, R, B>(self: Subscribable<A, E, R>, f: (a: NoInfer<A>) => B): Subscribable<B, E, R>
 } = dual(2, <A, E, R, B>(self: Subscribable<A, E, R>, f: (a: NoInfer<A>) => B): Subscribable<B, E, R> =>
   make({
@@ -71,9 +79,17 @@ export const map: {
  * @category combinators
  */
 export const mapEffect: {
+  /**
+   * @since 2.0.0
+   * @category combinators
+   */
   <A, B, E2, R2>(
     f: (a: NoInfer<A>) => Effect.Effect<B, E2, R2>
   ): <E, R>(fa: Subscribable<A, E, R>) => Subscribable<B, E | E2, R | R2>
+  /**
+   * @since 2.0.0
+   * @category combinators
+   */
   <A, E, R, B, E2, R2>(
     self: Subscribable<A, E, R>,
     f: (a: NoInfer<A>) => Effect.Effect<B, E2, R2>