effect 4.0.0-beta.2 → 4.0.0-beta.21

package/src/Semaphore.ts

@@ -0,0 +1,356 @@
+/**
+ * @since 2.0.0
+ */
+import * as Effect from "./Effect.ts"
+import * as internal from "./internal/effect.ts"
+import * as MutableHashMap from "./MutableHashMap.ts"
+import * as Option from "./Option.ts"
+
+/**
+ * @category models
+ * @since 2.0.0
+ * @example
+ * ```ts
+ * import { Effect, Semaphore } from "effect"
+ *
+ * // Create and use a semaphore for controlling concurrent access
+ * const program = Effect.gen(function*() {
+ *   const semaphore = yield* Semaphore.make(2)
+ *
+ *   return yield* semaphore.withPermits(1)(
+ *     Effect.succeed("Resource accessed")
+ *   )
+ * })
+ * ```
+ */
+export interface Semaphore {
+  /**
+   * Adjusts the number of permits available in the semaphore.
+   */
+  resize(permits: number): Effect.Effect<void>
+
+  /**
+   * Runs an effect with the given number of permits and releases the permits
+   * when the effect completes.
+   *
+   * **Details**
+   *
+   * This function acquires the specified number of permits before executing
+   * the provided effect. Once the effect finishes, the permits are released.
+   * If insufficient permits are available, the function will wait until they
+   * are released by other tasks.
+   */
+  withPermits(permits: number): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+
+  /**
+   * Runs an effect with the given number of permits and releases the permits
+   * when the effect completes.
+   *
+   * **Details**
+   *
+   * This function acquires the specified number of permits before executing
+   * the provided effect. Once the effect finishes, the permits are released.
+   * If insufficient permits are available, the function will wait until they
+   * are released by other tasks.
+   */
+  withPermit<A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>
+
+  /**
+   * Runs an effect only if the specified number of permits are immediately
+   * available.
+   *
+   * **Details**
+   *
+   * This function attempts to acquire the specified number of permits. If they
+   * are available, it runs the effect and releases the permits after the effect
+   * completes. If permits are not available, the effect does not execute, and
+   * the result is `Option.none`.
+   */
+  withPermitsIfAvailable(
+    permits: number
+  ): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<Option.Option<A>, E, R>
+
+  /**
+   * Acquires the specified number of permits and returns the resulting
+   * available permits, suspending the task if they are not yet available.
+   * Concurrent pending `take` calls are processed in a first-in, first-out manner.
+   */
+  take(permits: number): Effect.Effect<number>
+
+  /**
+   * Releases the specified number of permits and returns the resulting
+   * available permits.
+   */
+  release(permits: number): Effect.Effect<number>
+
+  /**
+   * Releases all permits held by this semaphore and returns the resulting available permits.
+   */
+  releaseAll: Effect.Effect<number>
+}
+
+/**
+ * Unsafely creates a new Semaphore.
+ *
+ * **Previously Known As**
+ *
+ * This API replaces the following from Effect 3.x:
+ *
+ * - `Effect.makeSemaphoreUnsafe`
+ *
+ * @example
+ * ```ts
+ * import { Effect, Semaphore } from "effect"
+ *
+ * const semaphore = Semaphore.makeUnsafe(3)
+ *
+ * const task = (id: number) =>
+ *   semaphore.withPermits(1)(
+ *     Effect.gen(function*() {
+ *       yield* Effect.log(`Task ${id} started`)
+ *       yield* Effect.sleep("1 second")
+ *       yield* Effect.log(`Task ${id} completed`)
+ *     })
+ *   )
+ *
+ * // Only 3 tasks can run concurrently
+ * const program = Effect.all([
+ *   task(1),
+ *   task(2),
+ *   task(3),
+ *   task(4),
+ *   task(5)
+ * ], { concurrency: "unbounded" })
+ * ```
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const makeUnsafe: (permits: number) => Semaphore = internal.makeSemaphoreUnsafe
+
+/**
+ * Creates a new Semaphore.
+ *
+ * **Previously Known As**
+ *
+ * This API replaces the following from Effect 3.x:
+ *
+ * - `Effect.makeSemaphore`
+ *
+ * @example
+ * ```ts
+ * import { Effect, Semaphore } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const semaphore = yield* Semaphore.make(2)
+ *
+ *   const task = (id: number) =>
+ *     semaphore.withPermits(1)(
+ *       Effect.gen(function*() {
+ *         yield* Effect.log(`Task ${id} acquired permit`)
+ *         yield* Effect.sleep("1 second")
+ *         yield* Effect.log(`Task ${id} releasing permit`)
+ *       })
+ *     )
+ *
+ *   // Run 4 tasks, but only 2 can run concurrently
+ *   yield* Effect.all([task(1), task(2), task(3), task(4)])
+ * })
+ * ```
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const make: (permits: number) => Effect.Effect<Semaphore> = internal.makeSemaphore
+
+// -----------------------------------------------------------------------------
+// Partitioned
+// -----------------------------------------------------------------------------
+
+/**
+ * @since 3.19.4
+ * @category models
+ */
+export const PartitionedTypeId: PartitionedTypeId = "~effect/PartitionedSemaphore"
+
+/**
+ * @since 3.19.4
+ * @category models
+ */
+export type PartitionedTypeId = "~effect/PartitionedSemaphore"
+
+/**
+ * A `Partitioned` semaphore controls access to a shared permit pool while
+ * tracking waiters by partition key.
+ *
+ * Waiting permits are distributed across partitions in round-robin order.
+ *
+ * **Previously Known As**
+ *
+ * This API replaces the following from Effect 3.x:
+ *
+ * - `PartitionedSemaphore.PartitionedSemaphore`
+ *
+ * @since 3.19.4
+ * @category models
+ */
+export interface Partitioned<in K> {
+  readonly [PartitionedTypeId]: PartitionedTypeId
+  readonly withPermits: (
+    key: K,
+    permits: number
+  ) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+}
+
+/**
+ * Creates a `Partitioned` semaphore unsafely.
+ *
+ * **Previously Known As**
+ *
+ * This API replaces the following from Effect 3.x:
+ *
+ * - `PartitionedSemaphore.makeUnsafe`
+ *
+ * @since 3.19.4
+ * @category constructors
+ */
+export const makePartitionedUnsafe = <K = unknown>(options: {
+  readonly permits: number
+}): Partitioned<K> => {
+  const maxPermits = Math.max(0, options.permits)
+
+  if (!Number.isFinite(maxPermits)) {
+    return {
+      [PartitionedTypeId]: PartitionedTypeId,
+      withPermits: () => (effect) => effect
+    }
+  }
+
+  let totalPermits = maxPermits
+  let waitingPermits = 0
+
+  type Waiter = {
+    permits: number
+    readonly resume: () => void
+  }
+  const partitions = MutableHashMap.empty<K, Set<Waiter>>()
+
+  const take = (key: K, permits: number) =>
+    Effect.callback<void>((resume) => {
+      if (maxPermits < permits) {
+        resume(Effect.never)
+        return
+      }
+
+      if (totalPermits >= permits) {
+        totalPermits -= permits
+        resume(Effect.void)
+        return
+      }
+
+      const needed = permits - totalPermits
+      const taken = permits - needed
+      if (totalPermits > 0) {
+        totalPermits = 0
+      }
+      waitingPermits += needed
+
+      const waiters = Option.getOrElse(
+        MutableHashMap.get(partitions, key),
+        () => {
+          const set = new Set<Waiter>()
+          MutableHashMap.set(partitions, key, set)
+          return set
+        }
+      )
+
+      const entry: Waiter = {
+        permits: needed,
+        resume: () => {
+          cleanup()
+          resume(Effect.void)
+        }
+      }
+
+      const cleanup = () => {
+        waiters.delete(entry)
+        if (waiters.size === 0) {
+          MutableHashMap.remove(partitions, key)
+        }
+      }
+
+      waiters.add(entry)
+
+      return Effect.sync(() => {
+        cleanup()
+        waitingPermits -= entry.permits
+        if (taken > 0) {
+          releaseUnsafe(taken)
+        }
+      })
+    })
+
+  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
+      }
+
+      waiter.permits -= 1
+      waitingPermits -= 1
+
+      if (waiter.permits === 0) {
+        waiter.resume()
+      }
+
+      permits -= 1
+    }
+  }
+
+  return {
+    [PartitionedTypeId]: PartitionedTypeId,
+    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)))
+          )
+        )
+    }
+  }
+}
+
+/**
+ * Creates a `Partitioned` semaphore.
+ *
+ * **Previously Known As**
+ *
+ * This API replaces the following from Effect 3.x:
+ *
+ * - `PartitionedSemaphore.make`
+ *
+ * @since 3.19.4
+ * @category constructors
+ */
+export const makePartitioned = <K = unknown>(options: {
+  readonly permits: number
+}): Effect.Effect<Partitioned<K>> => Effect.sync(() => makePartitionedUnsafe<K>(options))

package/src/ServiceMap.ts

@@ -24,6 +24,24 @@ import type * as Types from "./Types.ts"
 
 const ServiceTypeId = "~effect/ServiceMap/Service" as const
 
+/**
+ * The base type used for all ServiceMap keys.
+ *
+ * @since 4.0.0
+ * @category Models
+ */
+export interface Key<in out Identifier, in out Shape> extends Pipeable, Inspectable {
+  readonly [ServiceTypeId]: {
+    readonly _Service: Types.Invariant<Shape>
+    readonly _Identifier: Types.Invariant<Identifier>
+  }
+  readonly Service: Shape
+  readonly Identifier: Identifier
+  readonly key: string
+  readonly stack?: string | undefined
+  asEffect(): Effect<Shape, never, Identifier>
+}
+
 /**
  * @example
  * ```ts
@@ -42,21 +60,12 @@ const ServiceTypeId = "~effect/ServiceMap/Service" as const
  * @category Models
  */
 export interface Service<in out Identifier, in out Shape>
-  extends Pipeable, Inspectable, Yieldable<Service<Identifier, Shape>, Shape, never, Identifier>
+  extends Key<Identifier, Shape>, Yieldable<Service<Identifier, Shape>, Shape, never, Identifier>
 {
-  readonly [ServiceTypeId]: {
-    readonly _Service: Types.Invariant<Shape>
-    readonly _Identifier: Types.Invariant<Identifier>
-  }
-  readonly Service: Shape
-  readonly Identifier: Identifier
   of(self: Shape): Shape
   serviceMap(self: Shape): ServiceMap<Identifier>
   use<A, E, R>(f: (service: Shape) => Effect<A, E, R>): Effect<A, E, R | Identifier>
   useSync<A>(f: (service: Shape) => A): Effect<A, never, Identifier>
-
-  readonly stack?: string | undefined
-  readonly key: string
 }
 
 /**
@@ -368,7 +377,7 @@ export declare namespace Service {
    * @since 4.0.0
    * @category Models
    */
-  export type Any = Service<never, any> | Service<any, any>
+  export type Any = Key<never, any> | Key<any, any>
 
   /**
    * @example
@@ -508,20 +517,20 @@ const Proto: Omit<ServiceMap<never>, "mapUnsafe"> = {
 export const isServiceMap = (u: unknown): u is ServiceMap<never> => hasProperty(u, TypeId)
 
 /**
- * Checks if the provided argument is a `Service`.
+ * Checks if the provided argument is a `Key`.
  *
  * @example
  * ```ts
  * import { ServiceMap } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.strictEqual(ServiceMap.isService(ServiceMap.Service("Service")), true)
+ * assert.strictEqual(ServiceMap.isKey(ServiceMap.Service("Service")), true)
  * ```
  *
  * @since 4.0.0
  * @category Guards
  */
-export const isService = (u: unknown): u is Service<any, any> => hasProperty(u, ServiceTypeId)
+export const isKey = (u: unknown): u is Key<any, any> => hasProperty(u, ServiceTypeId)
 
 /**
  * Checks if the provided argument is a `Reference`.
@@ -580,7 +589,7 @@ const emptyServiceMap = makeUnsafe(new Map())
  * @category Constructors
  */
 export const make = <I, S>(
-  key: Service<I, S>,
+  key: Key<I, S>,
   service: Types.NoInfer<S>
 ): ServiceMap<I> => makeUnsafe(new Map([[key.key, service]]))
 
@@ -635,7 +644,7 @@ export const add: {
    * @since 4.0.0
    * @category Adders
    */
-  <I, S>(key: Service<I, S>, service: Types.NoInfer<S>): <Services>(self: ServiceMap<Services>) => ServiceMap<Services | I>
+  <I, S>(key: Key<I, S>, service: Types.NoInfer<S>): <Services>(self: ServiceMap<Services>) => ServiceMap<Services | I>
   /**
    * Adds a service to a given `ServiceMap`.
    *
@@ -661,10 +670,10 @@ export const add: {
    * @since 4.0.0
    * @category Adders
    */
-  <Services, I, S>(self: ServiceMap<Services>, key: Service<I, S>, service: Types.NoInfer<S>): ServiceMap<Services | I>
+  <Services, I, S>(self: ServiceMap<Services>, key: Key<I, S>, service: Types.NoInfer<S>): ServiceMap<Services | I>
 } = dual(3, <Services, I, S>(
   self: ServiceMap<Services>,
-  key: Service<I, S>,
+  key: Key<I, S>,
   service: Types.NoInfer<S>
 ): ServiceMap<Services | I> => {
   const map = new Map(self.mapUnsafe)
@@ -681,19 +690,19 @@ export const addOrOmit: {
    * @since 4.0.0
    * @category Adders
    */
-  <I, S>(key: Service<I, S>, service: Option.Option<Types.NoInfer<S>>): <Services>(self: ServiceMap<Services>) => ServiceMap<Services | I>
+  <I, S>(key: Key<I, S>, service: Option.Option<Types.NoInfer<S>>): <Services>(self: ServiceMap<Services>) => ServiceMap<Services | I>
   /**
    * @since 4.0.0
    * @category Adders
    */
   <Services, I, S>(
     self: ServiceMap<Services>,
-    key: Service<I, S>,
+    key: Key<I, S>,
     service: Option.Option<Types.NoInfer<S>>
   ): ServiceMap<Services | I>
 } = dual(3, <Services, I, S>(
   self: ServiceMap<Services>,
-  key: Service<I, S>,
+  key: Key<I, S>,
   service: Option.Option<Types.NoInfer<S>>
 ): ServiceMap<Services | I> => {
   const map = new Map(self.mapUnsafe)
@@ -770,7 +779,7 @@ export const getOrElse: {
    * @since 4.0.0
    * @category Getters
    */
-  <S, I, B>(key: Service<I, S>, orElse: LazyArg<B>): <Services>(self: ServiceMap<Services>) => S | B
+  <S, I, B>(key: Key<I, S>, orElse: LazyArg<B>): <Services>(self: ServiceMap<Services>) => S | B
   /**
    * Get a service from the context that corresponds to the given key, or
    * use the fallback value.
@@ -803,8 +812,8 @@ export const getOrElse: {
    * @since 4.0.0
    * @category Getters
    */
-  <Services, S, I, B>(self: ServiceMap<Services>, key: Service<I, S>, orElse: LazyArg<B>): S | B
-} = dual(3, <Services, S, I, B>(self: ServiceMap<Services>, key: Service<I, S>, orElse: LazyArg<B>): S | B => {
+  <Services, S, I, B>(self: ServiceMap<Services>, key: Key<I, S>, orElse: LazyArg<B>): S | B
+} = dual(3, <Services, S, I, B>(self: ServiceMap<Services>, key: Key<I, S>, orElse: LazyArg<B>): S | B => {
   if (self.mapUnsafe.has(key.key)) {
     return self.mapUnsafe.get(key.key)! as any
   }
@@ -820,15 +829,15 @@ export const getOrUndefined: {
    * @since 4.0.0
    * @category Getters
    */
-  <S, I>(key: Service<I, S>): <Services>(self: ServiceMap<Services>) => S | undefined
+  <S, I>(key: Key<I, S>): <Services>(self: ServiceMap<Services>) => S | undefined
   /**
    * @since 4.0.0
    * @category Getters
    */
-  <Services, S, I>(self: ServiceMap<Services>, key: Service<I, S>): S | undefined
+  <Services, S, I>(self: ServiceMap<Services>, key: Key<I, S>): S | undefined
 } = dual(
   2,
-  <Services, S, I>(self: ServiceMap<Services>, key: Service<I, S>): S | undefined => self.mapUnsafe.get(key.key)
+  <Services, S, I>(self: ServiceMap<Services>, key: Key<I, S>): S | undefined => self.mapUnsafe.get(key.key)
 )
 
 /**
@@ -888,7 +897,7 @@ export const getUnsafe: {
    * @since 4.0.0
    * @category unsafe
    */
-  <S, I>(service: Service<I, S>): <Services>(self: ServiceMap<Services>) => S
+  <S, I>(service: Key<I, S>): <Services>(self: ServiceMap<Services>) => S
   /**
    * Get a service from the context that corresponds to the given key.
    *
@@ -917,10 +926,10 @@ export const getUnsafe: {
    * @since 4.0.0
    * @category unsafe
    */
-  <Services, S, I>(self: ServiceMap<Services>, services: Service<I, S>): S
+  <Services, S, I>(self: ServiceMap<Services>, services: Key<I, S>): S
 } = dual(
   2,
-  <Services, I extends Services, S>(self: ServiceMap<Services>, service: Service<I, S>): S => {
+  <Services, I extends Services, S>(self: ServiceMap<Services>, service: Key<I, S>): S => {
     if (!self.mapUnsafe.has(service.key)) {
       if (ReferenceTypeId in service) return getDefaultValue(service as any)
       throw serviceNotFoundError(service)
@@ -980,7 +989,7 @@ export const get: {
    * @since 4.0.0
    * @category Getters
    */
-  <Services, I extends Services, S>(service: Service<I, S>): (self: ServiceMap<Services>) => S
+  <Services, I extends Services, S>(service: Key<I, S>): (self: ServiceMap<Services>) => S
   /**
    * Get a service from the context that corresponds to the given key.
    *
@@ -1006,7 +1015,7 @@ export const get: {
    * @since 4.0.0
    * @category Getters
    */
-  <Services, I extends Services, S>(self: ServiceMap<Services>, service: Service<I, S>): S
+  <Services, I extends Services, S>(self: ServiceMap<Services>, service: Key<I, S>): S
 } = getUnsafe
 
 /**
@@ -1044,7 +1053,7 @@ const getDefaultValue = (ref: Reference<any>) => {
   return (ref as any)[defaultValueCacheKey] = ref.defaultValue()
 }
 
-const serviceNotFoundError = (service: Service<any, any>) => {
+const serviceNotFoundError = (service: Key<any, any>) => {
   const error = new Error(
     `Service not found${service.key ? `: ${String(service.key)}` : ""}`
   )
@@ -1122,7 +1131,7 @@ export const getOption: {
    * @since 4.0.0
    * @category Getters
    */
-  <S, I>(service: Service<I, S>): <Services>(self: ServiceMap<Services>) => Option.Option<S>
+  <S, I>(service: Key<I, S>): <Services>(self: ServiceMap<Services>) => Option.Option<S>
   /**
    * Get the value associated with the specified key from the context wrapped in
    * an `Option` object. If the key is not found, the `Option` object will be
@@ -1151,8 +1160,8 @@ export const getOption: {
    * @since 4.0.0
    * @category Getters
    */
-  <Services, S, I>(self: ServiceMap<Services>, service: Service<I, S>): Option.Option<S>
-} = dual(2, <Services, I extends Services, S>(self: ServiceMap<Services>, service: Service<I, S>): Option.Option<S> => {
+  <Services, S, I>(self: ServiceMap<Services>, service: Key<I, S>): Option.Option<S>
+} = dual(2, <Services, I extends Services, S>(self: ServiceMap<Services>, service: Key<I, S>): Option.Option<S> => {
   if (self.mapUnsafe.has(service.key)) {
     return Option.some(self.mapUnsafe.get(service.key)! as any)
   }
@@ -1320,7 +1329,7 @@ export const mergeAll = <T extends Array<unknown>>(
  * @since 4.0.0
  * @category Utils
  */
-export const pick = <S extends ReadonlyArray<Service<any, any>>>(
+export const pick = <S extends ReadonlyArray<Key<any, any>>>(
   ...services: S
 ) =>
 <Services>(self: ServiceMap<Services>): ServiceMap<Services & Service.Identifier<S[number]>> => {
@@ -1360,7 +1369,7 @@ export const pick = <S extends ReadonlyArray<Service<any, any>>>(
  * @since 4.0.0
  * @category Utils
  */
-export const omit = <S extends ReadonlyArray<Service<any, any>>>(
+export const omit = <S extends ReadonlyArray<Key<any, any>>>(
   ...keys: S
 ) =>
 <Services>(self: ServiceMap<Services>): ServiceMap<Exclude<Services, Service.Identifier<S[number]>>> => {