effect 4.0.0-beta.3 → 4.0.0-beta.31

package/src/SchemaTransformation.ts

@@ -82,6 +82,8 @@
  * @since 4.0.0
  */
 
+import * as BigDecimal from "./BigDecimal.ts"
+import * as DateTime from "./DateTime.ts"
 import * as Duration from "./Duration.ts"
 import * as Effect from "./Effect.ts"
 import * as Option from "./Option.ts"
@@ -1004,8 +1006,7 @@ export const errorFromErrorJsonEncoded = (options?: {
  * ```
  *
  * See also:
- * - {@link optionFromOptionalKey}
- * - {@link optionFromOptional}
+ * - {@link optionFromNullishOr}
  *
  * @since 4.0.0
  */
@@ -1016,6 +1017,88 @@ export function optionFromNullOr<T>(): Transformation<Option.Option<T>, T | null
   })
 }
 
+/**
+ * Decodes `T | undefined` into `Option<T>` and encodes `Option<T>` back
+ * to `T | undefined`.
+ *
+ * When to use this:
+ * - Converting undefined-or API fields to `Option`.
+ *
+ * Behavior:
+ * - Decode: `undefined` → `Option.none()`, non-undefined → `Option.some(value)`.
+ * - Encode: `Option.none()` → `undefined`, `Option.some(value)` → `value`.
+ * - Pure and synchronous.
+ *
+ * **Example** (Option from undefined-or)
+ *
+ * ```ts
+ * import { Schema, SchemaTransformation } from "effect"
+ *
+ * const schema = Schema.UndefinedOr(Schema.String).pipe(
+ *   Schema.decodeTo(
+ *     Schema.Option(Schema.String),
+ *     SchemaTransformation.optionFromUndefinedOr()
+ *   )
+ * )
+ * ```
+ *
+ * See also:
+ * - {@link optionFromOptionalKey}
+ * - {@link optionFromOptional}
+ *
+ * @since 4.0.0
+ */
+export function optionFromUndefinedOr<T>(): Transformation<Option.Option<T>, T | undefined> {
+  return transform({
+    decode: Option.fromUndefinedOr,
+    encode: Option.getOrUndefined
+  })
+}
+
+/**
+ * Decodes `T | null | undefined` into `Option<T>` and encodes `Option<T>`
+ * back to `T | null` or `T | undefined` depending on the provided `options.onNoneEncoding` (defaults to `undefined`).
+ *
+ * When to use this:
+ * - Converting nullish API fields to `Option` when both `null` and
+ *   `undefined` represent absence.
+ *
+ * Behavior:
+ * - Decode: `null` or `undefined` → `Option.none()`, otherwise → `Option.some(value)`.
+ * - Encode: `Option.none()` → `null` or `undefined` (per `options.onNoneEncoding`),
+ *   `Option.some(value)` → `value`.
+ * - Pure and synchronous.
+ *
+ * **Example** (Option from nullish, encoding None as null)
+ *
+ * ```ts
+ * import { Schema, SchemaTransformation } from "effect"
+ *
+ * const schema = Schema.NullishOr(Schema.String).pipe(
+ *   Schema.decodeTo(
+ *     Schema.Option(Schema.String),
+ *     SchemaTransformation.optionFromNullishOr({ onNoneEncoding: null })
+ *   )
+ * )
+ * ```
+ *
+ * See also:
+ * - {@link optionFromNullOr}
+ * - {@link optionFromUndefinedOr}
+ *
+ * @since 4.0.0
+ */
+export function optionFromNullishOr<T>(
+  options?: {
+    onNoneEncoding: null | undefined
+  }
+): Transformation<Option.Option<T>, T | null | undefined> {
+  return transform({
+    decode: Option.fromNullishOr,
+    encode: options?.onNoneEncoding === null ? Option.getOrNull : Option.getOrUndefined
+  })
+}
+
 /**
  * Decodes an optional struct key into `Option<T>` and encodes `Option<T>`
  * back to an optional key.
@@ -1045,8 +1128,8 @@ export function optionFromNullOr<T>(): Transformation<Option.Option<T>, T | null
  * ```
  *
  * See also:
- * - {@link optionFromNullOr}
  * - {@link optionFromOptional}
+ * - {@link optionFromUndefinedOr}
  * - {@link transformOptional}
  *
  * @since 4.0.0
@@ -1086,8 +1169,8 @@ export function optionFromOptionalKey<T>(): Transformation<Option.Option<T>, T>
  * ```
  *
  * See also:
- * - {@link optionFromNullOr}
  * - {@link optionFromOptionalKey}
+ * - {@link optionFromUndefinedOr}
  * - {@link transformOptional}
  *
  * @since 4.0.0
@@ -1136,6 +1219,33 @@ export const urlFromString: Transformation<URL, string> = transformOrFail<URL, s
   encode: (url) => Effect.succeed(url.href)
 })
 
+/**
+ * Decodes a `string` into a `BigDecimal` and encodes a `BigDecimal` back to
+ * its string representation.
+ *
+ * When to use this:
+ * - Parsing decimal number strings from APIs or user input.
+ *
+ * Behavior:
+ * - Decode: calls `BigDecimal.fromString(s)`. Fails with `InvalidValue` if the
+ *   string is not a valid BigDecimal representation.
+ * - Encode: returns `BigDecimal.format(bd)`.
+ *
+ * @since 4.0.0
+ */
+export const bigDecimalFromString: Transformation<BigDecimal.BigDecimal, string> = transformOrFail<
+  BigDecimal.BigDecimal,
+  string
+>({
+  decode: (s) => {
+    const result = BigDecimal.fromString(s)
+    return result === undefined
+      ? Effect.fail(new Issue.InvalidValue(Option.some(s), { message: `Invalid BigDecimal string: ${s}` }))
+      : Effect.succeed(result)
+  },
+  encode: (bd) => Effect.succeed(BigDecimal.format(bd))
+})
+
 /**
  * Decodes a Base64-encoded `string` into a `Uint8Array` and encodes a
  * `Uint8Array` back to a Base64 string.
@@ -1264,3 +1374,78 @@ export const fromURLSearchParams = new Transformation<unknown, URLSearchParams>(
   Getter.decodeURLSearchParams(),
   Getter.encodeURLSearchParams()
 )
+
+/**
+ * @since 4.0.0
+ */
+export const timeZoneOffsetFromNumber: Transformation<DateTime.TimeZone.Offset, number> = transform<
+  DateTime.TimeZone.Offset,
+  number
+>({
+  decode: (n) => DateTime.zoneMakeOffset(n),
+  encode: (tz) => tz.offset
+})
+
+/**
+ * @since 4.0.0
+ */
+export const timeZoneNamedFromString: Transformation<DateTime.TimeZone.Named, string> = transformOrFail<
+  DateTime.TimeZone.Named,
+  string
+>({
+  decode: (s) => {
+    const result = DateTime.zoneMakeNamed(s)
+    return result === undefined
+      ? Effect.fail(new Issue.InvalidValue(Option.some(s), { message: `Invalid IANA time zone: ${s}` }))
+      : Effect.succeed(result)
+  },
+  encode: (tz) => Effect.succeed(tz.id)
+})
+
+/**
+ * @since 4.0.0
+ */
+export const timeZoneFromString: Transformation<DateTime.TimeZone, string> = transformOrFail<
+  DateTime.TimeZone,
+  string
+>({
+  decode: (s) => {
+    const result = DateTime.zoneFromString(s)
+    return result === undefined
+      ? Effect.fail(new Issue.InvalidValue(Option.some(s), { message: `Invalid time zone: ${s}` }))
+      : Effect.succeed(result)
+  },
+  encode: (tz) => Effect.succeed(DateTime.zoneToString(tz))
+})
+
+/**
+ * @since 4.0.0
+ */
+export const dateTimeUtcFromString: Transformation<DateTime.Utc, string> = transformOrFail<
+  DateTime.Utc,
+  string
+>({
+  decode: (s) => {
+    const result = DateTime.make(s)
+    return result === undefined
+      ? Effect.fail(new Issue.InvalidValue(Option.some(s), { message: "Invalid DateTime input" }))
+      : Effect.succeed(DateTime.toUtc(result))
+  },
+  encode: (utc) => Effect.succeed(DateTime.formatIso(utc))
+})
+
+/**
+ * @since 4.0.0
+ */
+export const dateTimeZonedFromString: Transformation<DateTime.Zoned, string> = transformOrFail<
+  DateTime.Zoned,
+  string
+>({
+  decode: (s) => {
+    const result = DateTime.makeZonedFromString(s)
+    return result === undefined
+      ? Effect.fail(new Issue.InvalidValue(Option.some(s), { message: `Invalid zoned DateTime string: ${s}` }))
+      : Effect.succeed(result)
+  },
+  encode: (zoned) => Effect.succeed(DateTime.formatIsoZoned(zoned))
+})

package/src/ScopedCache.ts

@@ -69,7 +69,7 @@ export const makeWith = <
 >(options: {
   readonly lookup: (key: Key) => Effect.Effect<A, E, R | Scope.Scope>
   readonly capacity: number
-  readonly timeToLive?: ((exit: Exit.Exit<A, E>, key: Key) => Duration.DurationInput) | undefined
+  readonly timeToLive?: ((exit: Exit.Exit<A, E>, key: Key) => Duration.Input) | undefined
   readonly requireServicesAt?: ServiceMode | undefined
 }): Effect.Effect<
   ScopedCache<Key, A, E, "lookup" extends ServiceMode ? Exclude<R, Scope.Scope> : never>,
@@ -88,7 +88,7 @@ export const makeWith = <
     self.state = { _tag: "Open", map }
     self.capacity = options.capacity
     self.timeToLive = options.timeToLive
-      ? (exit: Exit.Exit<A, E>, key: Key) => Duration.fromDurationInputUnsafe(options.timeToLive!(exit, key))
+      ? (exit: Exit.Exit<A, E>, key: Key) => Duration.fromInputUnsafe(options.timeToLive!(exit, key))
       : defaultTimeToLive
     return effect.as(
       Scope.addFinalizer(
@@ -116,7 +116,7 @@ export const make = <
   options: {
     readonly lookup: (key: Key) => Effect.Effect<A, E, R | Scope.Scope>
     readonly capacity: number
-    readonly timeToLive?: Duration.DurationInput | undefined
+    readonly timeToLive?: Duration.Input | undefined
     readonly requireServicesAt?: ServiceMode | undefined
   }
 ): Effect.Effect<

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))