effect 3.13.9 → 3.13.11

package/src/Option.ts

@@ -97,9 +97,9 @@ export declare namespace Option {
   /**
    * Extracts the type of the value contained in an `Option`.
    *
-   * @example
+   * **Example** (Getting the Value Type of an Option)
+   *
    * ```ts
-   * // Title: Getting the Value Type of an Option
    * import { Option } from "effect"
    *
    * // Declare an Option holding a string
@@ -139,11 +139,9 @@ export interface OptionTypeLambda extends TypeLambda {
  * This means you can use it in place of any `Option<A>` regardless of the type
  * `A`.
  *
- * @see {@link some} for the opposite operation.
+ * **Example** (Creating an Option with No Value)
  *
- * @example
  * ```ts
- * // Title: Creating an Option with No Value
  * import { Option } from "effect"
  *
  * // An Option holding no value
@@ -156,6 +154,8 @@ export interface OptionTypeLambda extends TypeLambda {
  * // Output: { _id: 'Option', _tag: 'None' }
  * ```
  *
+ * @see {@link some} for the opposite operation.
+ *
  * @category Constructors
  * @since 2.0.0
  */
@@ -164,11 +164,9 @@ export const none = <A = never>(): Option<A> => option.none
 /**
  * Wraps the given value into an `Option` to represent its presence.
  *
- * @see {@link none} for the opposite operation.
+ * **Example** (Creating an Option with a Value)
  *
- * @example
  * ```ts
- * // Title: Creating an Option with a Value
  * import { Option } from "effect"
  *
  * // An Option holding the number 1
@@ -181,6 +179,8 @@ export const none = <A = never>(): Option<A> => option.none
  * // Output: { _id: 'Option', _tag: 'Some', value: 1 }
  * ```
  *
+ * @see {@link none} for the opposite operation.
+ *
  * @category Constructors
  * @since 2.0.0
  */
@@ -218,8 +218,6 @@ export const isOption: (input: unknown) => input is Option<unknown> = option.isO
 /**
  * Checks whether an `Option` represents the absence of a value (`None`).
  *
- * @see {@link isSome} for the opposite check.
- *
  * @example
  * ```ts
  * import { Option } from "effect"
@@ -231,6 +229,8 @@ export const isOption: (input: unknown) => input is Option<unknown> = option.isO
  * // Output: true
  * ```
  *
+ * @see {@link isSome} for the opposite check.
+ *
  * @category Guards
  * @since 2.0.0
  */
@@ -239,8 +239,6 @@ export const isNone: <A>(self: Option<A>) => self is None<A> = option.isNone
 /**
  * Checks whether an `Option` contains a value (`Some`).
  *
- * @see {@link isNone} for the opposite check.
- *
  * @example
  * ```ts
  * import { Option } from "effect"
@@ -252,6 +250,8 @@ export const isNone: <A>(self: Option<A>) => self is None<A> = option.isNone
  * // Output: false
  * ```
  *
+ * @see {@link isNone} for the opposite check.
+ *
  * @category Guards
  * @since 2.0.0
  */
@@ -277,9 +277,9 @@ export const isSome: <A>(self: Option<A>) => self is Some<A> = option.isSome
  * without resorting to `if` or manual checks, making your code more declarative
  * and readable.
  *
- * @example
+ * **Example** (Pattern Matching with Option)
+ *
  * ```ts
- * // Title: Pattern Matching with Option
  * import { Option } from "effect"
  *
  * const foo = Option.some(1)
@@ -317,9 +317,9 @@ export const match: {
    * without resorting to `if` or manual checks, making your code more declarative
    * and readable.
    *
-   * @example
+   * **Example** (Pattern Matching with Option)
+   *
    * ```ts
-   * // Title: Pattern Matching with Option
    * import { Option } from "effect"
    *
    * const foo = Option.some(1)
@@ -362,9 +362,9 @@ export const match: {
    * without resorting to `if` or manual checks, making your code more declarative
    * and readable.
    *
-   * @example
+   * **Example** (Pattern Matching with Option)
+   *
    * ```ts
-   * // Title: Pattern Matching with Option
    * import { Option } from "effect"
    *
    * const foo = Option.some(1)
@@ -495,8 +495,6 @@ export const fromIterable = <A>(collection: Iterable<A>): Option<A> => {
  * using this function, you can convert `Either` into a simpler structure for
  * cases where error handling is not required.
  *
- * @see {@link getLeft} for the opposite operation.
- *
  * @example
  * ```ts
  * import { Either, Option } from "effect"
@@ -508,6 +506,8 @@ export const fromIterable = <A>(collection: Iterable<A>): Option<A> => {
  * // Output: { _id: 'Option', _tag: 'None' }
  * ```
  *
+ * @see {@link getLeft} for the opposite operation.
+ *
  * @category Conversions
  * @since 2.0.0
  */
@@ -529,8 +529,6 @@ export const getRight: <R, L>(self: Either<R, L>) => Option<R> = either.getRight
  * `Either` and want to handle it as an `Option`. By discarding the right value,
  * it simplifies error-focused workflows.
  *
- * @see {@link getRight} for the opposite operation.
- *
  * @example
  * ```ts
  * import { Either, Option } from "effect"
@@ -542,6 +540,8 @@ export const getRight: <R, L>(self: Either<R, L>) => Option<R> = either.getRight
  * // Output: { _id: 'Option', _tag: 'Some', value: 'err' }
  * ```
  *
+ * @see {@link getRight} for the opposite operation.
+ *
  * @category Conversions
  * @since 2.0.0
  */
@@ -563,9 +563,6 @@ export const getLeft: <R, L>(self: Either<R, L>) => Option<L> = either.getLeft
  * value. It is particularly useful for providing default values or alternative
  * logic when working with optional values.
  *
- * @see {@link getOrNull} for a version that returns `null` instead of executing a function.
- * @see {@link getOrUndefined} for a version that returns `undefined` instead of executing a function.
- *
  * @example
  * ```ts
  * import { Option } from "effect"
@@ -577,6 +574,9 @@ export const getLeft: <R, L>(self: Either<R, L>) => Option<L> = either.getLeft
  * // Output: 0
  * ```
  *
+ * @see {@link getOrNull} for a version that returns `null` instead of executing a function.
+ * @see {@link getOrUndefined} for a version that returns `undefined` instead of executing a function.
+ *
  * @category Getters
  * @since 2.0.0
  */
@@ -597,9 +597,6 @@ export const getOrElse: {
    * value. It is particularly useful for providing default values or alternative
    * logic when working with optional values.
    *
-   * @see {@link getOrNull} for a version that returns `null` instead of executing a function.
-   * @see {@link getOrUndefined} for a version that returns `undefined` instead of executing a function.
-   *
    * @example
    * ```ts
    * import { Option } from "effect"
@@ -611,6 +608,9 @@ export const getOrElse: {
    * // Output: 0
    * ```
    *
+   * @see {@link getOrNull} for a version that returns `null` instead of executing a function.
+   * @see {@link getOrUndefined} for a version that returns `undefined` instead of executing a function.
+   *
    * @category Getters
    * @since 2.0.0
    */
@@ -631,9 +631,6 @@ export const getOrElse: {
    * value. It is particularly useful for providing default values or alternative
    * logic when working with optional values.
    *
-   * @see {@link getOrNull} for a version that returns `null` instead of executing a function.
-   * @see {@link getOrUndefined} for a version that returns `undefined` instead of executing a function.
-   *
    * @example
    * ```ts
    * import { Option } from "effect"
@@ -645,6 +642,9 @@ export const getOrElse: {
    * // Output: 0
    * ```
    *
+   * @see {@link getOrNull} for a version that returns `null` instead of executing a function.
+   * @see {@link getOrUndefined} for a version that returns `undefined` instead of executing a function.
+   *
    * @category Getters
    * @since 2.0.0
    */
@@ -1157,8 +1157,6 @@ export const liftThrowable = <A extends ReadonlyArray<unknown>, B>(
  * a fail-fast behavior for empty `Option` values and want to provide a custom
  * error message or object.
  *
- * @see {@link getOrThrow} for a version that throws a default error.
- *
  * @example
  * ```ts
  * import * as assert from "node:assert"
@@ -1171,6 +1169,8 @@ export const liftThrowable = <A extends ReadonlyArray<unknown>, B>(
  * assert.throws(() => Option.getOrThrowWith(Option.none(), () => new Error('Unexpected None')))
  * ```
  *
+ * @see {@link getOrThrow} for a version that throws a default error.
+ *
  * @category Conversions
  * @since 2.0.0
  */
@@ -1187,8 +1187,6 @@ export const getOrThrowWith: {
    * a fail-fast behavior for empty `Option` values and want to provide a custom
    * error message or object.
    *
-   * @see {@link getOrThrow} for a version that throws a default error.
-   *
    * @example
    * ```ts
    * import * as assert from "node:assert"
@@ -1201,6 +1199,8 @@ export const getOrThrowWith: {
    * assert.throws(() => Option.getOrThrowWith(Option.none(), () => new Error('Unexpected None')))
    * ```
    *
+   * @see {@link getOrThrow} for a version that throws a default error.
+   *
    * @category Conversions
    * @since 2.0.0
    */
@@ -1217,8 +1217,6 @@ export const getOrThrowWith: {
    * a fail-fast behavior for empty `Option` values and want to provide a custom
    * error message or object.
    *
-   * @see {@link getOrThrow} for a version that throws a default error.
-   *
    * @example
    * ```ts
    * import * as assert from "node:assert"
@@ -1231,6 +1229,8 @@ export const getOrThrowWith: {
    * assert.throws(() => Option.getOrThrowWith(Option.none(), () => new Error('Unexpected None')))
    * ```
    *
+   * @see {@link getOrThrow} for a version that throws a default error.
+   *
    * @category Conversions
    * @since 2.0.0
    */
@@ -1253,8 +1253,6 @@ export const getOrThrowWith: {
  * scenarios where the absence of a value is treated as an exceptional case and
  * a default error is sufficient.
  *
- * @see {@link getOrThrowWith} for a version that allows you to provide a custom error.
- *
  * @example
  * ```ts
  * import * as assert from "node:assert"
@@ -1264,6 +1262,8 @@ export const getOrThrowWith: {
  * assert.throws(() => Option.getOrThrow(Option.none()))
  * ```
  *
+ * @see {@link getOrThrowWith} for a version that allows you to provide a custom error.
+ *
  * @category Conversions
  * @since 2.0.0
  */
@@ -3102,9 +3102,9 @@ export const filter: {
  * - Two `Some` values are equivalent if their inner values are equivalent
  *   according to the provided `Equivalence`.
  *
- * @example
+ * **Example** (Comparing Optional Numbers for Equivalence)
+ *
  * ```ts
- * // Title: Comparing Optional Numbers for Equivalence
  * import { Number, Option } from "effect"
  *
  * const isEquivalent = Option.getEquivalence(Number.Equivalence)
@@ -3361,8 +3361,6 @@ export const liftPredicate: { // Note: I intentionally avoid using the NoInfer p
  * equivalence function returns `true`, the result is `true`. If the `Option` is
  * `None` or the values are not equivalent, the result is `false`.
  *
- * @see {@link contains} for a version that uses the default `Equivalence`.
- *
  * @example
  * ```ts
  * import { Number, Option } from "effect"
@@ -3379,6 +3377,8 @@ export const liftPredicate: { // Note: I intentionally avoid using the NoInfer p
  * // Output: false
  * ```
  *
+ * @see {@link contains} for a version that uses the default `Equivalence`.
+ *
  * @category Elements
  * @since 2.0.0
  */
@@ -3401,8 +3401,6 @@ const _equivalence = Equal.equivalence()
  * result is `true`. If the `Option` is `None` or the values are not equivalent,
  * the result is `false`.
  *
- * @see {@link containsWith} for a version that allows you to specify a custom equivalence function.
- *
  * @example
  * ```ts
  * import { Option } from "effect"
@@ -3417,6 +3415,8 @@ const _equivalence = Equal.equivalence()
  * // Output: false
  * ```
  *
+ * @see {@link containsWith} for a version that allows you to specify a custom equivalence function.
+ *
  * @category Elements
  * @since 2.0.0
  */
@@ -3433,8 +3433,6 @@ export const contains: {
    * result is `true`. If the `Option` is `None` or the values are not equivalent,
    * the result is `false`.
    *
-   * @see {@link containsWith} for a version that allows you to specify a custom equivalence function.
-   *
    * @example
    * ```ts
    * import { Option } from "effect"
@@ -3449,6 +3447,8 @@ export const contains: {
    * // Output: false
    * ```
    *
+   * @see {@link containsWith} for a version that allows you to specify a custom equivalence function.
+   *
    * @category Elements
    * @since 2.0.0
    */
@@ -3465,8 +3465,6 @@ export const contains: {
    * result is `true`. If the `Option` is `None` or the values are not equivalent,
    * the result is `false`.
    *
-   * @see {@link containsWith} for a version that allows you to specify a custom equivalence function.
-   *
    * @example
    * ```ts
    * import { Option } from "effect"
@@ -3481,6 +3479,8 @@ export const contains: {
    * // Output: false
    * ```
    *
+   * @see {@link containsWith} for a version that allows you to specify a custom equivalence function.
+   *
    * @category Elements
    * @since 2.0.0
    */
@@ -3673,10 +3673,6 @@ export const exists: {
  * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
  * 5. Regular `Option` functions like `map` and `filter` can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope
  *
- * @see {@link Do}
- * @see {@link bind}
- * @see {@link let_ let}
- *
  * @example
  * ```ts
  * import * as assert from "node:assert"
@@ -3692,6 +3688,10 @@ export const exists: {
  * assert.deepStrictEqual(result, Option.some({ x: 2, y: 3, sum: 5 }))
  * ```
  *
+ * @see {@link Do}
+ * @see {@link bind}
+ * @see {@link let_ let}
+ *
  * @category Do notation
  * @since 2.0.0
  */
@@ -3711,10 +3711,6 @@ export const bindTo: {
    * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
    * 5. Regular `Option` functions like `map` and `filter` can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope
    *
-   * @see {@link Do}
-   * @see {@link bind}
-   * @see {@link let_ let}
-   *
    * @example
    * ```ts
    * import * as assert from "node:assert"
@@ -3730,6 +3726,10 @@ export const bindTo: {
    * assert.deepStrictEqual(result, Option.some({ x: 2, y: 3, sum: 5 }))
    * ```
    *
+   * @see {@link Do}
+   * @see {@link bind}
+   * @see {@link let_ let}
+   *
    * @category Do notation
    * @since 2.0.0
    */
@@ -3749,10 +3749,6 @@ export const bindTo: {
    * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
    * 5. Regular `Option` functions like `map` and `filter` can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope
    *
-   * @see {@link Do}
-   * @see {@link bind}
-   * @see {@link let_ let}
-   *
    * @example
    * ```ts
    * import * as assert from "node:assert"
@@ -3768,6 +3764,10 @@ export const bindTo: {
    * assert.deepStrictEqual(result, Option.some({ x: 2, y: 3, sum: 5 }))
    * ```
    *
+   * @see {@link Do}
+   * @see {@link bind}
+   * @see {@link let_ let}
+   *
    * @category Do notation
    * @since 2.0.0
    */
@@ -3798,10 +3798,6 @@ export {
    * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
    * 5. Regular `Option` functions like `map` and `filter` can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope
    *
-   * @see {@link Do}
-   * @see {@link bind}
-   * @see {@link bindTo}
-   *
    * @example
    * ```ts
    * import * as assert from "node:assert"
@@ -3815,8 +3811,12 @@ export {
    *   Option.filter(({ x, y }) => x * y > 5)
    * )
    * assert.deepStrictEqual(result, Option.some({ x: 2, y: 3, sum: 5 }))
-   *
    * ```
+   *
+   * @see {@link Do}
+   * @see {@link bind}
+   * @see {@link bindTo}
+   *
    * @category Do notation
    * @since 2.0.0
    */
@@ -3834,10 +3834,6 @@ export {
  * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
  * 5. Regular `Option` functions like `map` and `filter` can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope
  *
- * @see {@link Do}
- * @see {@link bindTo}
- * @see {@link let_ let}
- *
  * @example
  * ```ts
  * import * as assert from "node:assert"
@@ -3853,6 +3849,10 @@ export {
  * assert.deepStrictEqual(result, Option.some({ x: 2, y: 3, sum: 5 }))
  * ```
  *
+ * @see {@link Do}
+ * @see {@link bindTo}
+ * @see {@link let_ let}
+ *
  * @category Do notation
  * @since 2.0.0
  */
@@ -3868,10 +3868,6 @@ export const bind: {
    * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
    * 5. Regular `Option` functions like `map` and `filter` can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope
    *
-   * @see {@link Do}
-   * @see {@link bindTo}
-   * @see {@link let_ let}
-   *
    * @example
    * ```ts
    * import * as assert from "node:assert"
@@ -3887,6 +3883,10 @@ export const bind: {
    * assert.deepStrictEqual(result, Option.some({ x: 2, y: 3, sum: 5 }))
    * ```
    *
+   * @see {@link Do}
+   * @see {@link bindTo}
+   * @see {@link let_ let}
+   *
    * @category Do notation
    * @since 2.0.0
    */
@@ -3902,10 +3902,6 @@ export const bind: {
    * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
    * 5. Regular `Option` functions like `map` and `filter` can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope
    *
-   * @see {@link Do}
-   * @see {@link bindTo}
-   * @see {@link let_ let}
-   *
    * @example
    * ```ts
    * import * as assert from "node:assert"
@@ -3921,6 +3917,10 @@ export const bind: {
    * assert.deepStrictEqual(result, Option.some({ x: 2, y: 3, sum: 5 }))
    * ```
    *
+   * @see {@link Do}
+   * @see {@link bindTo}
+   * @see {@link let_ let}
+   *
    * @category Do notation
    * @since 2.0.0
    */
@@ -3942,10 +3942,6 @@ export const bind: {
  * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
  * 5. Regular `Option` functions like `map` and `filter` can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope
  *
- * @see {@link bindTo}
- * @see {@link bind}
- * @see {@link let_ let}
- *
  * @example
  * ```ts
  * import * as assert from "node:assert"
@@ -3961,6 +3957,10 @@ export const bind: {
  * assert.deepStrictEqual(result, Option.some({ x: 2, y: 3, sum: 5 }))
  * ```
  *
+ * @see {@link bindTo}
+ * @see {@link bind}
+ * @see {@link let_ let}
+ *
  * @category Do notation
  * @since 2.0.0
  */
@@ -3974,9 +3974,9 @@ const adapter = Gen.adapter<OptionTypeLambda>()
  * involves `Option` easier to write and understand. This approach is similar to
  * using `async/await` but tailored for `Option`.
  *
- * @example
+ * **Example** (Using `Option.gen` to Create a Combined Value)
+ *
  * ```ts
- * // Title: Using Option.gen to Create a Combined Value
  * import { Option } from "effect"
  *
  * const maybeName: Option.Option<string> = Option.some("John")

package/src/Predicate.ts

@@ -431,6 +431,10 @@ export const isBigInt = (input: unknown): input is bigint => typeof input === "b
  */
 export const isSymbol = (input: unknown): input is symbol => typeof input === "symbol"
 
+// TODO: make public
+/** @internal */
+export const isPropertyKey = (u: unknown): u is PropertyKey => isString(u) || isNumber(u) || isSymbol(u)
+
 /**
  * Tests if a value is a `function`.
  *