effect 4.0.0-beta.6 → 4.0.0-beta.60

package/src/SchemaTransformation.ts

@@ -35,10 +35,13 @@
  * - Trim/case strings → {@link trim}, {@link toLowerCase}, {@link toUpperCase}, {@link capitalize}, {@link uncapitalize}, {@link snakeToCamel}
  * - Parse key-value strings → {@link splitKeyValue}
  * - Coerce string ↔ number/bigint → {@link numberFromString}, {@link bigintFromString}
+ * - Coerce string ↔ Date/Duration → {@link dateFromString}, {@link durationFromString}
  * - Decode durations → {@link durationFromNanos}, {@link durationFromMillis}
  * - Wrap nullable/optional as Option → {@link optionFromNullOr}, {@link optionFromOptionalKey}, {@link optionFromOptional}
  * - Parse URLs → {@link urlFromString}
  * - Base64 ↔ Uint8Array → {@link uint8ArrayFromBase64String}
+ * - Base64 ↔ string → {@link stringFromBase64String}
+ * - URI component ↔ string → {@link stringFromUriComponent}
  * - JSON string ↔ unknown → {@link fromJsonString}
  * - FormData/URLSearchParams ↔ unknown → {@link fromFormData}, {@link fromURLSearchParams}
  * - Check if a value is a Transformation → {@link isTransformation}
@@ -86,6 +89,7 @@ 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 { formatDate } from "./Formatter.ts"
 import * as Option from "./Option.ts"
 import * as Predicate from "./Predicate.ts"
 import type * as AST from "./SchemaAST.ts"
@@ -878,6 +882,80 @@ export const bigintFromString = new Transformation(
   Getter.String()
 )
 
+/**
+ * Decodes a `string` into a `Date` and encodes a `Date` back to a `string`.
+ *
+ * When to use this:
+ * - Parsing ISO 8601 date strings from APIs or user input.
+ *
+ * Behavior:
+ * - Decode: creates a `Date` from the string (like `new Date(s)`).
+ * - Encode: converts the `Date` to an ISO string (like `date.toISOString()`),
+ *   returning `"Invalid Date"` for invalid dates.
+ *
+ * **Example** (Date from string)
+ *
+ * ```ts
+ * import { Schema, SchemaTransformation } from "effect"
+ *
+ * const schema = Schema.String.pipe(
+ *   Schema.decodeTo(Schema.Date, SchemaTransformation.dateFromString)
+ * )
+ * ```
+ *
+ * See also:
+ * - {@link numberFromString}
+ * - {@link dateTimeUtcFromString}
+ *
+ * @category Coercions
+ * @since 4.0.0
+ */
+export const dateFromString: Transformation<globalThis.Date, string> = new Transformation(
+  Getter.Date(),
+  Getter.transform(formatDate)
+)
+
+/**
+ * Decodes a `string` into a `Duration` and encodes a `Duration` back to a
+ * parseable `string`.
+ *
+ * When to use this:
+ * - Parsing human-readable duration strings from APIs, config, or user input.
+ *
+ * Behavior:
+ * - Decode: accepts any string that `Duration.fromInput` can parse, including
+ *   `"Infinity"` and `"-Infinity"`.
+ * - Encode: returns `String(duration)`, producing strings like `"2000 millis"`
+ *   or `"10 nanos"` that round-trip through the parser.
+ *
+ * **Example** (Duration from string)
+ *
+ * ```ts
+ * import { Schema, SchemaTransformation } from "effect"
+ *
+ * const schema = Schema.String.pipe(
+ *   Schema.decodeTo(Schema.Duration, SchemaTransformation.durationFromString)
+ * )
+ * ```
+ *
+ * See also:
+ * - {@link durationFromNanos}
+ * - {@link durationFromMillis}
+ *
+ * @since 4.0.0
+ */
+export const durationFromString: Transformation<Duration.Duration, string> = transformOrFail<
+  Duration.Duration,
+  string
+>({
+  decode: (s) =>
+    Option.match(Duration.fromInput(s as Duration.Input), {
+      onNone: () => Effect.fail(new Issue.InvalidValue(Option.some(s), { message: `Invalid Duration string: ${s}` })),
+      onSome: Effect.succeed
+    }),
+  encode: (duration) => Effect.succeed(globalThis.String(duration))
+})
+
 /**
  * Decodes a `bigint` (nanoseconds) into a `Duration` and encodes a
  * `Duration` back to `bigint` nanoseconds.
@@ -907,15 +985,14 @@ export const bigintFromString = new Transformation(
  */
 export const durationFromNanos: Transformation<Duration.Duration, bigint> = transformOrFail({
   decode: (i) => Effect.succeed(Duration.nanos(i)),
-  encode: (a) => {
-    const nanos = Duration.toNanos(a)
-    if (Predicate.isUndefined(nanos)) {
-      return Effect.fail(
-        new Issue.InvalidValue(Option.some(a), { message: `Unable to encode ${a} into a bigint` })
-      )
-    }
-    return Effect.succeed(nanos)
-  }
+  encode: (a) =>
+    Option.match(Duration.toNanos(a), {
+      onNone: () =>
+        Effect.fail(
+          new Issue.InvalidValue(Option.some(a), { message: `Unable to encode ${a} into a bigint` })
+        ),
+      onSome: (nanos) => Effect.succeed(nanos)
+    })
 })
 
 /**
@@ -1006,8 +1083,7 @@ export const errorFromErrorJsonEncoded = (options?: {
  * ```
  *
  * See also:
- * - {@link optionFromOptionalKey}
- * - {@link optionFromOptional}
+ * - {@link optionFromNullishOr}
  *
  * @since 4.0.0
  */
@@ -1018,6 +1094,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.
@@ -1047,8 +1205,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
@@ -1088,8 +1246,8 @@ export function optionFromOptionalKey<T>(): Transformation<Option.Option<T>, T>
  * ```
  *
  * See also:
- * - {@link optionFromNullOr}
  * - {@link optionFromOptionalKey}
+ * - {@link optionFromUndefinedOr}
  * - {@link transformOptional}
  *
  * @since 4.0.0
@@ -1133,7 +1291,7 @@ export const urlFromString: Transformation<URL, string> = transformOrFail<URL, s
   decode: (s) =>
     Effect.try({
       try: () => new URL(s),
-      catch: (e) => new Issue.InvalidValue(Option.some(s), { message: globalThis.String(e) })
+      catch: () => new Issue.InvalidValue(Option.some(s), { message: `Invalid URL string: ${s}` })
     }),
   encode: (url) => Effect.succeed(url.href)
 })
@@ -1158,9 +1316,9 @@ export const bigDecimalFromString: Transformation<BigDecimal.BigDecimal, string>
 >({
   decode: (s) => {
     const result = BigDecimal.fromString(s)
-    return result === undefined
+    return Option.isNone(result)
       ? Effect.fail(new Issue.InvalidValue(Option.some(s), { message: `Invalid BigDecimal string: ${s}` }))
-      : Effect.succeed(result)
+      : Effect.succeed(result.value)
   },
   encode: (bd) => Effect.succeed(BigDecimal.format(bd))
 })
@@ -1189,6 +1347,7 @@ export const bigDecimalFromString: Transformation<BigDecimal.BigDecimal, string>
  *
  * See also:
  * - {@link fromJsonString}
+ * - `Schema.Uint8ArrayFromBase64` - a ready-made schema wrapping this transformation.
  *
  * @since 4.0.0
  */
@@ -1197,6 +1356,134 @@ export const uint8ArrayFromBase64String: Transformation<Uint8Array<ArrayBufferLi
   Getter.encodeBase64()
 )
 
+/**
+ * Decodes a Base64-encoded `string` into a UTF-8 `string` and encodes a
+ * UTF-8 `string` back to a Base64 string.
+ *
+ * When to use this:
+ * - Handling text data transmitted as Base64 strings.
+ *
+ * Behavior:
+ * - Decode: parses the Base64 string into a UTF-8 string.
+ * - Encode: encodes the string as a Base64 string.
+ *
+ * **Example** (String from Base64)
+ *
+ * ```ts
+ * import { Schema, SchemaTransformation } from "effect"
+ *
+ * const schema = Schema.String.pipe(
+ *   Schema.decodeTo(Schema.String, SchemaTransformation.stringFromBase64String)
+ * )
+ * ```
+ *
+ * See also:
+ * - {@link uint8ArrayFromBase64String}
+ * - `Schema.StringFromBase64` - a ready-made schema wrapping this transformation.
+ *
+ * @since 4.0.0
+ */
+export const stringFromBase64String: Transformation<string, string> = new Transformation(
+  Getter.decodeBase64String(),
+  Getter.encodeBase64()
+)
+
+/**
+ * Decodes a base64 (URL) encoded `string` into a UTF-8 `string` and encodes it back.
+ *
+ * When to use this:
+ * - Handling text data transmitted as Base64 URL-safe strings.
+ *
+ * Behavior:
+ * - Decode: parses the Base64 URL string into a UTF-8 string.
+ * - Encode: encodes the string as a Base64 URL string.
+ *
+ * **Example** (String from Base64Url)
+ *
+ * ```ts
+ * import { Schema, SchemaTransformation } from "effect"
+ *
+ * const schema = Schema.String.pipe(
+ *   Schema.decodeTo(Schema.String, SchemaTransformation.stringFromBase64UrlString)
+ * )
+ * ```
+ *
+ * See also:
+ * - {@link stringFromBase64String}
+ * - `Schema.StringFromBase64Url` - a ready-made schema wrapping this transformation.
+ *
+ * @since 4.0.0
+ */
+export const stringFromBase64UrlString: Transformation<string, string> = new Transformation(
+  Getter.decodeBase64UrlString(),
+  Getter.encodeBase64Url()
+)
+
+/**
+ * Decodes a hex encoded `string` into a UTF-8 `string` and encodes it back.
+ *
+ * When to use this:
+ * - Handling text data transmitted as hexadecimal strings.
+ *
+ * Behavior:
+ * - Decode: parses the hex string into a UTF-8 string.
+ * - Encode: encodes the string as a hex string.
+ *
+ * **Example** (String from Hex)
+ *
+ * ```ts
+ * import { Schema, SchemaTransformation } from "effect"
+ *
+ * const schema = Schema.String.pipe(
+ *   Schema.decodeTo(Schema.String, SchemaTransformation.stringFromHexString)
+ * )
+ * ```
+ *
+ * See also:
+ * - {@link stringFromBase64String}
+ * - `Schema.StringFromHex` - a ready-made schema wrapping this transformation.
+ *
+ * @since 4.0.0
+ */
+export const stringFromHexString: Transformation<string, string> = new Transformation(
+  Getter.decodeHexString(),
+  Getter.encodeHex()
+)
+
+/**
+ * Decodes a URI component encoded string into a UTF-8 string and encodes a
+ * UTF-8 string into a URI component encoded string.
+ *
+ * When to use this:
+ * - Storing structured data in URL query parameters or fragments.
+ * - Composing with `Schema.parseJson` to round-trip JSON through a URL.
+ *
+ * Behavior:
+ * - Decode: calls `decodeURIComponent`. Fails if the input contains malformed
+ *   percent-encoding sequences.
+ * - Encode: calls `encodeURIComponent`.
+ *
+ * **Example** (URI component schema)
+ *
+ * ```ts
+ * import { Schema, SchemaTransformation } from "effect"
+ *
+ * const schema = Schema.String.pipe(
+ *   Schema.decodeTo(Schema.String, SchemaTransformation.stringFromUriComponent)
+ * )
+ * ```
+ *
+ * See also:
+ * - {@link stringFromBase64String}
+ * - `Schema.StringFromUriComponent` - a ready-made schema wrapping this transformation.
+ *
+ * @since 4.0.0
+ */
+export const stringFromUriComponent: Transformation<string, string> = new Transformation(
+  Getter.decodeUriComponent(),
+  Getter.encodeUriComponent()
+)
+
 /**
  * Decodes a JSON `string` into an `unknown` value and encodes an `unknown`
  * value back to a JSON string.
@@ -1313,10 +1600,10 @@ export const timeZoneNamedFromString: Transformation<DateTime.TimeZone.Named, st
   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)
+    return Option.match(DateTime.zoneMakeNamed(s), {
+      onNone: () => Effect.fail(new Issue.InvalidValue(Option.some(s), { message: `Invalid IANA time zone: ${s}` })),
+      onSome: Effect.succeed
+    })
   },
   encode: (tz) => Effect.succeed(tz.id)
 })
@@ -1329,10 +1616,10 @@ export const timeZoneFromString: Transformation<DateTime.TimeZone, string> = tra
   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)
+    return Option.match(DateTime.zoneFromString(s), {
+      onNone: () => Effect.fail(new Issue.InvalidValue(Option.some(s), { message: `Invalid time zone: ${s}` })),
+      onSome: Effect.succeed
+    })
   },
   encode: (tz) => Effect.succeed(DateTime.zoneToString(tz))
 })
@@ -1345,10 +1632,11 @@ export const dateTimeUtcFromString: Transformation<DateTime.Utc, string> = trans
   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))
+    return Option.match(DateTime.make(s), {
+      onNone: () =>
+        Effect.fail(new Issue.InvalidValue(Option.some(s), { message: `Invalid UTC DateTime string: ${s}` })),
+      onSome: (result) => Effect.succeed(DateTime.toUtc(result))
+    })
   },
   encode: (utc) => Effect.succeed(DateTime.formatIso(utc))
 })
@@ -1361,10 +1649,11 @@ export const dateTimeZonedFromString: Transformation<DateTime.Zoned, string> = t
   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)
+    return Option.match(DateTime.makeZonedFromString(s), {
+      onNone: () =>
+        Effect.fail(new Issue.InvalidValue(Option.some(s), { message: `Invalid Zoned DateTime string: ${s}` })),
+      onSome: Effect.succeed
+    })
   },
   encode: (zoned) => Effect.succeed(DateTime.formatIsoZoned(zoned))
 })

package/src/Scope.ts

@@ -14,10 +14,10 @@
  * @since 2.0.0
  */
 
+import type * as Context from "./Context.ts"
 import type { Effect } from "./Effect.ts"
 import type { Exit } from "./Exit.ts"
 import * as effect from "./internal/effect.ts"
-import type * as ServiceMap from "./ServiceMap.ts"
 
 const TypeId = effect.ScopeTypeId
 const CloseableTypeId = effect.ScopeCloseableTypeId
@@ -208,7 +208,7 @@ export namespace State {
  * @since 2.0.0
  * @category tags
  */
-export const Scope: ServiceMap.Service<Scope, Scope> = effect.scopeTag
+export const Scope: Context.Service<Scope, Scope> = effect.scopeTag
 
 /**
  * Creates a new `Scope` with the specified finalizer strategy.

package/src/ScopedCache.ts

@@ -2,6 +2,7 @@
  * @since 4.0.0
  */
 import * as Arr from "./Array.ts"
+import * as Context from "./Context.ts"
 import * as Deferred from "./Deferred.ts"
 import * as Duration from "./Duration.ts"
 import type * as Effect from "./Effect.ts"
@@ -16,7 +17,6 @@ import * as Option from "./Option.ts"
 import type { Pipeable } from "./Pipeable.ts"
 import * as Predicate from "./Predicate.ts"
 import * as Scope from "./Scope.ts"
-import * as ServiceMap from "./ServiceMap.ts"
 
 const TypeId = "~effect/ScopedCache"
 
@@ -69,26 +69,26 @@ 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>,
   never,
   ("lookup" extends ServiceMode ? never : R) | Scope.Scope
 > =>
-  effect.servicesWith((services: ServiceMap.ServiceMap<any>) => {
-    const scope = ServiceMap.get(services, Scope.Scope)
+  effect.contextWith((context: Context.Context<any>) => {
+    const scope = Context.get(context, Scope.Scope)
     const self = Object.create(Proto)
     self.lookup = (key: Key): Effect.Effect<A, E> =>
-      effect.updateServices(
+      effect.updateContext(
         options.lookup(key),
-        (input) => ServiceMap.merge(services, input)
+        (input) => Context.merge(context, input)
       )
     const map = MutableHashMap.empty<Key, Entry<A, E>>()
     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<