effect 4.0.0-beta.4 → 4.0.0-beta.40

package/src/Option.ts

@@ -31,7 +31,7 @@
  * **Gotchas**
  *
  * - `Option.some(null)` is a valid `Some`; use {@link fromNullishOr} to treat `null`/`undefined` as `None`
- * - {@link filterMap} is an alias for {@link flatMap}
+ * - {@link filterMap} uses a `Filter` callback that returns `Result`
  * - {@link getOrThrow} throws a generic `Error`; prefer {@link getOrThrowWith} for custom errors
  * - `None` is a singleton; compare with {@link isNone}, not `===`
  * - When yielded in `Effect.gen`, a `None` becomes a `NoSuchElementError` defect
@@ -77,6 +77,7 @@ import * as Combiner from "./Combiner.ts"
 import type { EffectIterator, Yieldable } from "./Effect.ts"
 import * as Equal from "./Equal.ts"
 import * as Equivalence from "./Equivalence.ts"
+import type * as Filter from "./Filter.ts"
 import type { LazyArg } from "./Function.ts"
 import { constNull, constUndefined, dual, identity } from "./Function.ts"
 import type { TypeLambda } from "./HKT.ts"
@@ -93,7 +94,7 @@ import * as Reducer from "./Reducer.ts"
 import type { Result } from "./Result.ts"
 import type { Covariant, NoInfer, NotFunction } from "./Types.ts"
 import type * as Unify from "./Unify.ts"
-import * as Gen from "./Utils.ts"
+import type * as Gen from "./Utils.ts"
 
 const TypeId = "~effect/data/Option"
 
@@ -155,6 +156,7 @@ export type Option<A> = None<A> | Some<A>
 export interface None<out A> extends Pipeable, Inspectable, Yieldable<Option<A>, A, NoSuchElementError> {
   readonly _tag: "None"
   readonly _op: "None"
+  readonly valueOrUndefined: undefined
   readonly [TypeId]: {
     readonly _A: Covariant<A>
   }
@@ -188,6 +190,7 @@ export interface Some<out A> extends Pipeable, Inspectable, Yieldable<Option<A>,
   readonly _tag: "Some"
   readonly _op: "Some"
   readonly value: A
+  readonly valueOrUndefined: A
   readonly [TypeId]: {
     readonly _A: Covariant<A>
   }
@@ -3441,79 +3444,88 @@ export const partitionMap: {
   return result.isFailure(e) ? [some(e.failure), none()] : [none(), some(e.success)]
 })
 
-// TODO(4.0): remove?
 /**
- * Alias of {@link flatMap}. Applies a function returning `Option` to the value
- * inside a `Some`, flattening the result.
+ * Transforms and filters an `Option` using a `Filter` callback.
+ *
+ * The callback returns a `Result`: `Result.succeed` keeps and transforms the
+ * value, while `Result.fail` discards it.
  *
  * **Example** (Filtering and transforming)
  *
  * ```ts
  * import { Option } from "effect"
+ * import * as Result from "effect/Result"
  *
  * console.log(Option.filterMap(
  *   Option.some(2),
- *   (n) => (n % 2 === 0 ? Option.some(`Even: ${n}`) : Option.none())
+ *   (n) => (n % 2 === 0 ? Result.succeed(`Even: ${n}`) : Result.failVoid)
  * ))
  * // Output: { _id: 'Option', _tag: 'Some', value: 'Even: 2' }
  * ```
  *
- * @see {@link flatMap} (canonical)
  * @see {@link filter} for predicate-based filtering
  *
  * @category Filtering
  * @since 2.0.0
  */
 export const filterMap: {
-  // TODO(4.0): remove?
   /**
-   * Alias of {@link flatMap}. Applies a function returning `Option` to the value
-   * inside a `Some`, flattening the result.
+   * Transforms and filters an `Option` using a `Filter` callback.
+   *
+   * The callback returns a `Result`: `Result.succeed` keeps and transforms the
+   * value, while `Result.fail` discards it.
    *
    * **Example** (Filtering and transforming)
    *
    * ```ts
    * import { Option } from "effect"
+   * import * as Result from "effect/Result"
    *
    * console.log(Option.filterMap(
    *   Option.some(2),
-   *   (n) => (n % 2 === 0 ? Option.some(`Even: ${n}`) : Option.none())
+   *   (n) => (n % 2 === 0 ? Result.succeed(`Even: ${n}`) : Result.failVoid)
    * ))
    * // Output: { _id: 'Option', _tag: 'Some', value: 'Even: 2' }
    * ```
    *
-   * @see {@link flatMap} (canonical)
    * @see {@link filter} for predicate-based filtering
    *
    * @category Filtering
    * @since 2.0.0
    */
-  <A, B>(f: (a: A) => Option<B>): (self: Option<A>) => Option<B>
-  // TODO(4.0): remove?
+  <A, B, X>(f: Filter.Filter<A, B, X>): (self: Option<A>) => Option<B>
   /**
-   * Alias of {@link flatMap}. Applies a function returning `Option` to the value
-   * inside a `Some`, flattening the result.
+   * Transforms and filters an `Option` using a `Filter` callback.
+   *
+   * The callback returns a `Result`: `Result.succeed` keeps and transforms the
+   * value, while `Result.fail` discards it.
    *
    * **Example** (Filtering and transforming)
    *
    * ```ts
    * import { Option } from "effect"
+   * import * as Result from "effect/Result"
    *
    * console.log(Option.filterMap(
    *   Option.some(2),
-   *   (n) => (n % 2 === 0 ? Option.some(`Even: ${n}`) : Option.none())
+   *   (n) => (n % 2 === 0 ? Result.succeed(`Even: ${n}`) : Result.failVoid)
    * ))
    * // Output: { _id: 'Option', _tag: 'Some', value: 'Even: 2' }
    * ```
    *
-   * @see {@link flatMap} (canonical)
    * @see {@link filter} for predicate-based filtering
    *
    * @category Filtering
    * @since 2.0.0
    */
-  <A, B>(self: Option<A>, f: (a: A) => Option<B>): Option<B>
-} = flatMap
+  <A, B, X>(self: Option<A>, f: Filter.Filter<A, B, X>): Option<B>
+} = dual(2, <A, B, X>(self: Option<A>, f: Filter.Filter<A, B, X>): Option<B> => {
+  if (isNone(self)) {
+    return none()
+  }
+  const next = f(self.value)
+  return result.isSuccess(next) ? some(next.success) : none()
+})
 
 /**
  * Filters an `Option` using a predicate. Returns `None` if the predicate is
@@ -3723,7 +3735,7 @@ export const filter: {
 } = dual(
   2,
   <A>(self: Option<A>, predicate: Predicate<A>): Option<A> =>
-    filterMap(self, (b) => (predicate(b) ? option.some(b) : option.none))
+    isNone(self) ? none() : predicate(self.value) ? some(self.value) : none()
 )
 
 /**
@@ -4659,9 +4671,7 @@ export const gen: Gen.Gen<OptionTypeLambda> = (...args) => {
   const iterator = f()
   let state: IteratorResult<any> = iterator.next()
   while (!state.done) {
-    const current = Gen.isGenKind(state.value)
-      ? state.value.value
-      : state.value
+    const current = state.value
     if (isNone(current)) {
       return current
     }

package/src/Order.ts

@@ -764,40 +764,9 @@ export function Tuple<const Elements extends ReadonlyArray<Order<any>>>(
 }
 
 /**
- * Creates an `Order` for arrays by applying the given `Order` to each element, then comparing by length if all elements are equal.
- *
- * When to use this:
- * - When comparing arrays of the same element type
- * - When you want shorter arrays to be considered less than longer arrays
- * - When sorting collections of arrays
- *
- * Behavior:
- * - Pure function: does not mutate inputs
- * - Compares arrays element-by-element using the provided order
- * - Stops at the first non-zero comparison result
- * - If all elements are equal, shorter arrays are less than longer arrays
- * - Returns `0` only if arrays have the same length and all elements are equal
- *
- * **Example** (Array Element Ordering)
- *
- * ```ts
- * import { Order } from "effect"
- *
- * const arrayOrder = Order.Array(Order.Number)
- *
- * console.log(arrayOrder([1, 2], [1, 3])) // -1
- * console.log(arrayOrder([1, 2], [1, 2, 3])) // -1 (shorter array is less)
- * console.log(arrayOrder([1, 2, 3], [1, 2])) // 1 (longer array is greater)
- * console.log(arrayOrder([1, 2], [1, 2])) // 0
- * ```
- *
- * See also:
- * - {@link Tuple} - Type-safe tuple ordering
- *
- * @category combinators
  * @since 4.0.0
  */
-export function Array<A>(O: Order<A>): Order<ReadonlyArray<A>> {
+function Array_<A>(O: Order<A>): Order<ReadonlyArray<A>> {
   return make((self, that) => {
     const aLen = self.length
     const bLen = that.length
@@ -812,6 +781,44 @@ export function Array<A>(O: Order<A>): Order<ReadonlyArray<A>> {
   })
 }
 
+export {
+  /**
+   * Creates an `Order` for arrays by applying the given `Order` to each element, then comparing by length if all elements are equal.
+   *
+   * When to use this:
+   * - When comparing arrays of the same element type
+   * - When you want shorter arrays to be considered less than longer arrays
+   * - When sorting collections of arrays
+   *
+   * Behavior:
+   * - Pure function: does not mutate inputs
+   * - Compares arrays element-by-element using the provided order
+   * - Stops at the first non-zero comparison result
+   * - If all elements are equal, shorter arrays are less than longer arrays
+   * - Returns `0` only if arrays have the same length and all elements are equal
+   *
+   * **Example** (Array Element Ordering)
+   *
+   * ```ts
+   * import { Order } from "effect"
+   *
+   * const arrayOrder = Order.Array(Order.Number)
+   *
+   * console.log(arrayOrder([1, 2], [1, 3])) // -1
+   * console.log(arrayOrder([1, 2], [1, 2, 3])) // -1 (shorter array is less)
+   * console.log(arrayOrder([1, 2, 3], [1, 2])) // 1 (longer array is greater)
+   * console.log(arrayOrder([1, 2], [1, 2])) // 0
+   * ```
+   *
+   * See also:
+   * - {@link Tuple} - Type-safe tuple ordering
+   *
+   * @category combinators
+   * @since 4.0.0
+   */
+  Array_ as Array
+}
+
 /**
  * Creates an `Order` for structs by applying the given `Order`s to each property in sequence.
  *

package/src/PartitionedSemaphore.ts

@@ -1,24 +1,22 @@
 /**
- * @since 3.19.4
- * @experimental
+ * @since 4.0.0
  */
 import * as Effect from "./Effect.ts"
+import { dual } from "./Function.ts"
 import * as MutableHashMap from "./MutableHashMap.ts"
 import * as Option from "./Option.ts"
 
 /**
- * @since 3.19.4
+ * @since 4.0.0
  * @category models
- * @experimental
  */
-export const TypeId: TypeId = "~effect/PartitionedSemaphore"
+export const PartitionedTypeId: PartitionedTypeId = "~effect/PartitionedSemaphore"
 
 /**
- * @since 3.19.4
+ * @since 4.0.0
  * @category models
- * @experimental
  */
-export type TypeId = "~effect/PartitionedSemaphore"
+export type PartitionedTypeId = "~effect/PartitionedSemaphore"
 
 /**
  * A `PartitionedSemaphore` controls access to a shared permit pool while
@@ -26,24 +24,36 @@ export type TypeId = "~effect/PartitionedSemaphore"
  *
  * Waiting permits are distributed across partitions in round-robin order.
  *
- * @since 3.19.4
+ * @since 4.0.0
  * @category models
- * @experimental
  */
 export interface PartitionedSemaphore<in K> {
-  readonly [TypeId]: TypeId
+  readonly [PartitionedTypeId]: PartitionedTypeId
+  readonly capacity: number
+  readonly available: Effect.Effect<number>
+  readonly take: (key: K, permits: number) => Effect.Effect<void>
+  readonly release: (permits: number) => Effect.Effect<number>
   readonly withPermits: (
     key: K,
     permits: number
   ) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  readonly withPermit: (key: K) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  readonly withPermitsIfAvailable: (
+    permits: number
+  ) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<Option.Option<A>, E, R>
 }
 
+/**
+ * @since 4.0.0
+ * @category models
+ */
+export interface Partitioned<in K> extends PartitionedSemaphore<K> {}
+
 /**
  * Creates a `PartitionedSemaphore` unsafely.
  *
- * @since 3.19.4
+ * @since 4.0.0
  * @category constructors
- * @experimental
  */
 export const makeUnsafe = <K = unknown>(options: {
   readonly permits: number
@@ -52,8 +62,14 @@ export const makeUnsafe = <K = unknown>(options: {
 
   if (!Number.isFinite(maxPermits)) {
     return {
-      [TypeId]: TypeId,
-      withPermits: () => (effect) => effect
+      [PartitionedTypeId]: PartitionedTypeId,
+      capacity: maxPermits,
+      available: Effect.succeed(maxPermits),
+      take: () => Effect.void,
+      release: () => Effect.succeed(maxPermits),
+      withPermits: () => (effect) => effect,
+      withPermit: () => (effect) => effect,
+      withPermitsIfAvailable: () => (effect) => Effect.asSome(effect)
     }
   }
 
@@ -64,10 +80,50 @@ export const makeUnsafe = <K = unknown>(options: {
     permits: number
     readonly resume: () => void
   }
+
   const partitions = MutableHashMap.empty<K, Set<Waiter>>()
+  let iterator = partitions[Symbol.iterator]()
+
+  const releaseUnsafe = (permits: number): number => {
+    while (permits > 0) {
+      if (waitingPermits === 0) {
+        totalPermits = Math.min(maxPermits, totalPermits + permits)
+        return totalPermits
+      }
+
+      let state = iterator.next()
+      if (state.done) {
+        iterator = partitions[Symbol.iterator]()
+        state = iterator.next()
+        if (state.done) {
+          return totalPermits
+        }
+      }
+
+      const waiter = state.value[1].values().next().value
+      if (waiter === undefined) {
+        continue
+      }
+
+      waiter.permits -= 1
+      waitingPermits -= 1
 
-  const take = (key: K, permits: number) =>
-    Effect.callback<void>((resume) => {
+      if (waiter.permits === 0) {
+        waiter.resume()
+      }
+
+      permits -= 1
+    }
+
+    return totalPermits
+  }
+
+  const take = (key: K, permits: number): Effect.Effect<void> => {
+    if (permits <= 0) {
+      return Effect.void
+    }
+
+    return Effect.callback<void>((resume) => {
       if (maxPermits < permits) {
         resume(Effect.never)
         return
@@ -120,63 +176,239 @@ export const makeUnsafe = <K = unknown>(options: {
         }
       })
     })
+  }
 
-  let iterator = partitions[Symbol.iterator]()
-
-  const releaseUnsafe = (permits: number): void => {
-    while (permits > 0) {
-      if (waitingPermits === 0) {
-        totalPermits += permits
-        return
-      }
-
-      let state = iterator.next()
-      if (state.done) {
-        iterator = partitions[Symbol.iterator]()
-        state = iterator.next()
-        if (state.done) {
-          return
-        }
-      }
-
-      const waiter = state.value[1].values().next().value
-      if (waiter === undefined) {
-        continue
+  const withPermits =
+    (key: K, permits: number) => <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> => {
+      if (permits <= 0) {
+        return effect
       }
 
-      waiter.permits -= 1
-      waitingPermits -= 1
+      const takePermits = take(key, permits)
+      return Effect.uninterruptibleMask((restore) =>
+        Effect.flatMap(
+          restore(takePermits),
+          () =>
+            Effect.ensuring(
+              restore(effect),
+              Effect.sync(() => {
+                releaseUnsafe(permits)
+              })
+            )
+        )
+      )
+    }
 
-      if (waiter.permits === 0) {
-        waiter.resume()
-      }
+  const tryTake = (permits: number): boolean => {
+    if (permits <= 0) {
+      return true
+    }
 
-      permits -= 1
+    if (maxPermits < permits || totalPermits < permits) {
+      return false
     }
+
+    totalPermits -= permits
+    return true
   }
 
   return {
-    [TypeId]: TypeId,
-    withPermits: (key, permits) => {
-      const takePermits = take(key, permits)
-      return (effect) =>
-        Effect.uninterruptibleMask((restore) =>
-          Effect.flatMap(
-            restore(takePermits),
-            () => Effect.ensuring(restore(effect), Effect.sync(() => releaseUnsafe(permits)))
+    [PartitionedTypeId]: PartitionedTypeId,
+    capacity: maxPermits,
+    available: Effect.sync(() => totalPermits),
+    take,
+    release: (permits) => Effect.sync(() => releaseUnsafe(permits)),
+    withPermits,
+    withPermit: (key) => withPermits(key, 1),
+    withPermitsIfAvailable:
+      (permits) => <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<Option.Option<A>, E, R> => {
+        if (permits <= 0) {
+          return Effect.asSome(effect)
+        }
+
+        return Effect.suspend(() => {
+          if (!tryTake(permits)) {
+            return Effect.succeed(Option.none())
+          }
+
+          return Effect.ensuring(
+            Effect.asSome(effect),
+            Effect.sync(() => {
+              releaseUnsafe(permits)
+            })
           )
-        )
-    }
+        })
+      }
   }
 }
 
 /**
  * Creates a `PartitionedSemaphore`.
  *
- * @since 3.19.4
+ * @since 4.0.0
  * @category constructors
- * @experimental
  */
 export const make = <K = unknown>(options: {
   readonly permits: number
 }): Effect.Effect<PartitionedSemaphore<K>> => Effect.sync(() => makeUnsafe<K>(options))
+
+/**
+ * Gets the current number of available permits.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const available = <K>(self: PartitionedSemaphore<K>): Effect.Effect<number> => self.available
+
+/**
+ * Gets the total capacity.
+ *
+ * @since 4.0.0
+ * @category getters
+ */
+export const capacity = <K>(self: PartitionedSemaphore<K>): number => self.capacity
+
+/**
+ * Acquires permits for a partition.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const take: {
+  /**
+   * Acquires permits for a partition.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <K>(key: K, permits: number): (self: PartitionedSemaphore<K>) => Effect.Effect<void>
+  /**
+   * Acquires permits for a partition.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <K>(self: PartitionedSemaphore<K>, key: K, permits: number): Effect.Effect<void>
+} = dual(3, <K>(self: PartitionedSemaphore<K>, key: K, permits: number): Effect.Effect<void> => self.take(key, permits))
+
+/**
+ * Releases permits back to the shared pool.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const release: {
+  /**
+   * Releases permits back to the shared pool.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  (permits: number): <K>(self: PartitionedSemaphore<K>) => Effect.Effect<number>
+  /**
+   * Releases permits back to the shared pool.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <K>(self: PartitionedSemaphore<K>, permits: number): Effect.Effect<number>
+} = dual(2, <K>(self: PartitionedSemaphore<K>, permits: number): Effect.Effect<number> => self.release(permits))
+
+/**
+ * Runs an effect with permits for a partition.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const withPermits: {
+  /**
+   * Runs an effect with permits for a partition.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <K>(self: PartitionedSemaphore<K>, key: K, permits: number): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  /**
+   * Runs an effect with permits for a partition.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <K, A, E, R>(
+    self: PartitionedSemaphore<K>,
+    key: K,
+    permits: number,
+    effect: Effect.Effect<A, E, R>
+  ): Effect.Effect<A, E, R>
+} = ((...args: Array<any>) => {
+  if (args.length === 3) {
+    const [self, key, permits] = args
+    return (effect: Effect.Effect<any, any, any>) => self.withPermits(key, permits)(effect)
+  }
+  const [self, key, permits, effect] = args
+  return self.withPermits(key, permits)(effect)
+}) as any
+
+/**
+ * Runs an effect with a single permit for a partition.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const withPermit: {
+  /**
+   * Runs an effect with a single permit for a partition.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <K>(self: PartitionedSemaphore<K>, key: K): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  /**
+   * Runs an effect with a single permit for a partition.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <K, A, E, R>(self: PartitionedSemaphore<K>, key: K, effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>
+} = ((...args: Array<any>) => {
+  if (args.length === 2) {
+    const [self, key] = args
+    return (effect: Effect.Effect<any, any, any>) => self.withPermit(key)(effect)
+  }
+  const [self, key, effect] = args
+  return self.withPermit(key)(effect)
+}) as any
+
+/**
+ * Runs an effect only if the permits are immediately available.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const withPermitsIfAvailable: {
+  /**
+   * Runs an effect only if the permits are immediately available.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <K>(self: PartitionedSemaphore<K>, permits: number): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<Option.Option<A>, E, R>
+  /**
+   * Runs an effect only if the permits are immediately available.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <K, A, E, R>(
+    self: PartitionedSemaphore<K>,
+    permits: number,
+    effect: Effect.Effect<A, E, R>
+  ): Effect.Effect<Option.Option<A>, E, R>
+} = ((...args: Array<any>) => {
+  if (args.length === 2) {
+    const [self, permits] = args
+    return (effect: Effect.Effect<any, any, any>) => self.withPermitsIfAvailable(permits)(effect)
+  }
+  const [self, permits, effect] = args
+  return self.withPermitsIfAvailable(permits)(effect)
+}) as any