effect 3.10.19 → 3.11.0

package/dist/esm/internal/version.js

@@ -1,4 +1,4 @@
-let moduleVersion = "3.10.19";
+let moduleVersion = "3.11.0";
 export const getCurrentVersion = () => moduleVersion;
 export const setCurrentVersion = version => {
   moduleVersion = version;

package/dist/esm/internal/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","names":["moduleVersion","getCurrentVersion","setCurrentVersion","version"],"sources":["../../../src/internal/version.ts"],"sourcesContent":[null],"mappings":"AAAA,IAAIA,aAAa,GAAG,SAAS;AAE7B,OAAO,MAAMC,iBAAiB,GAAGA,CAAA,KAAMD,aAAa;AAEpD,OAAO,MAAME,iBAAiB,GAAIC,OAAe,IAAI;EACnDH,aAAa,GAAGG,OAAO;AACzB,CAAC","ignoreList":[]}
+{"version":3,"file":"version.js","names":["moduleVersion","getCurrentVersion","setCurrentVersion","version"],"sources":["../../../src/internal/version.ts"],"sourcesContent":[null],"mappings":"AAAA,IAAIA,aAAa,GAAG,QAAQ;AAE5B,OAAO,MAAMC,iBAAiB,GAAGA,CAAA,KAAMD,aAAa;AAEpD,OAAO,MAAME,iBAAiB,GAAIC,OAAe,IAAI;EACnDH,aAAa,GAAGG,OAAO;AACzB,CAAC","ignoreList":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect",
-  "version": "3.10.19",
+  "version": "3.11.0",
   "description": "The missing standard library for TypeScript, for writing production-grade software.",
   "license": "MIT",
   "repository": {

package/src/BigDecimal.ts

@@ -26,6 +26,7 @@ import { type Pipeable, pipeArguments } from "./Pipeable.js"
 import { hasProperty } from "./Predicate.js"
 
 const DEFAULT_PRECISION = 100
+const FINITE_INT_REGEX = /^[+-]?\d+$/
 
 /**
  * @since 2.0.0
@@ -1473,6 +1474,8 @@ export const fromBigInt = (n: bigint): BigDecimal => make(n, 0)
  * It is not recommended to convert a floating point number to a decimal directly,
  * as the floating point representation may be unexpected.
  *
+ * Throws a `RangeError` if the number is not finite (`NaN`, `+Infinity` or `-Infinity`).
+ *
  * @param value - The `number` value to create a `BigDecimal` from.
  *
  * @example
@@ -1483,12 +1486,61 @@ export const fromBigInt = (n: bigint): BigDecimal => make(n, 0)
  * assert.deepStrictEqual(fromNumber(123.456), make(123456n, 3))
  * ```
  *
+ * @since 3.11.0
+ * @category constructors
+ */
+export const unsafeFromNumber = (n: number): BigDecimal =>
+  Option.getOrThrowWith(safeFromNumber(n), () => new RangeError(`Number must be finite, got ${n}`))
+
+/**
+ * Creates a `BigDecimal` from a `number` value.
+ *
+ * It is not recommended to convert a floating point number to a decimal directly,
+ * as the floating point representation may be unexpected.
+ *
+ * Throws a `RangeError` if the number is not finite (`NaN`, `+Infinity` or `-Infinity`).
+ *
+ * @param value - The `number` value to create a `BigDecimal` from.
+ *
  * @since 2.0.0
  * @category constructors
+ * @deprecated Use {@link unsafeFromNumber} instead.
  */
-export const fromNumber = (n: number): BigDecimal => {
-  const [lead, trail = ""] = `${n}`.split(".")
-  return make(BigInt(`${lead}${trail}`), trail.length)
+export const fromNumber: (n: number) => BigDecimal = unsafeFromNumber
+
+/**
+ * Creates a `BigDecimal` from a `number` value.
+ *
+ * It is not recommended to convert a floating point number to a decimal directly,
+ * as the floating point representation may be unexpected.
+ *
+ * Returns `None` if the number is not finite (`NaN`, `+Infinity` or `-Infinity`).
+ *
+ * @param n - The `number` value to create a `BigDecimal` from.
+ *
+ * @example
+ * import { BigDecimal, Option } from "effect"
+ *
+ * assert.deepStrictEqual(BigDecimal.safeFromNumber(123), Option.some(BigDecimal.make(123n, 0)))
+ * assert.deepStrictEqual(BigDecimal.safeFromNumber(123.456), Option.some(BigDecimal.make(123456n, 3)))
+ * assert.deepStrictEqual(BigDecimal.safeFromNumber(Infinity), Option.none())
+ *
+ * @since 3.11.0
+ * @category constructors
+ */
+export const safeFromNumber = (n: number): Option.Option<BigDecimal> => {
+  // TODO: Rename this to `fromNumber` after removing the current, unsafe implementation of `fromNumber`.
+  if (!Number.isFinite(n)) {
+    return Option.none()
+  }
+
+  const string = `${n}`
+  if (string.includes("e")) {
+    return fromString(string)
+  }
+
+  const [lead, trail = ""] = string.split(".")
+  return Option.some(make(BigInt(`${lead}${trail}`), trail.length))
 }
 
 /**
@@ -1509,26 +1561,44 @@ export const fromNumber = (n: number): BigDecimal => {
  * @category constructors
  */
 export const fromString = (s: string): Option.Option<BigDecimal> => {
-  let digits: string
-  let scale: number
+  if (s === "") {
+    return Option.some(zero)
+  }
 
-  const dot = s.search(/\./)
+  let base: string
+  let exp: number
+  const seperator = s.search(/[eE]/)
+  if (seperator !== -1) {
+    const trail = s.slice(seperator + 1)
+    base = s.slice(0, seperator)
+    exp = Number(trail)
+    if (base === "" || !Number.isSafeInteger(exp) || !FINITE_INT_REGEX.test(trail)) {
+      return Option.none()
+    }
+  } else {
+    base = s
+    exp = 0
+  }
+
+  let digits: string
+  let offset: number
+  const dot = base.search(/\./)
   if (dot !== -1) {
-    const lead = s.slice(0, dot)
-    const trail = s.slice(dot + 1)
+    const lead = base.slice(0, dot)
+    const trail = base.slice(dot + 1)
     digits = `${lead}${trail}`
-    scale = trail.length
+    offset = trail.length
   } else {
-    digits = s
-    scale = 0
+    digits = base
+    offset = 0
   }
 
-  if (digits === "") {
-    // TODO: This mimics the BigInt constructor behavior. Should this be `Option.none()`?
-    return Option.some(zero)
+  if (!FINITE_INT_REGEX.test(digits)) {
+    return Option.none()
   }
 
-  if (!/^(?:\+|-)?\d+$/.test(digits)) {
+  const scale = offset - exp
+  if (!Number.isSafeInteger(scale)) {
     return Option.none()
   }
 
@@ -1558,7 +1628,10 @@ export const unsafeFromString = (s: string): BigDecimal =>
 /**
  * Formats a given `BigDecimal` as a `string`.
  *
- * @param normalized - The `BigDecimal` to format.
+ * If the scale of the `BigDecimal` is greater than or equal to 16, the `BigDecimal` will
+ * be formatted in scientific notation.
+ *
+ * @param n - The `BigDecimal` to format.
  *
  * @example
  * ```ts
@@ -1573,17 +1646,22 @@ export const unsafeFromString = (s: string): BigDecimal =>
  * @category conversions
  */
 export const format = (n: BigDecimal): string => {
-  const negative = n.value < bigint0
-  const absolute = negative ? `${n.value}`.substring(1) : `${n.value}`
+  const normalized = normalize(n)
+  if (Math.abs(normalized.scale) >= 16) {
+    return toExponential(normalized)
+  }
+
+  const negative = normalized.value < bigint0
+  const absolute = negative ? `${normalized.value}`.substring(1) : `${normalized.value}`
 
   let before: string
   let after: string
 
-  if (n.scale >= absolute.length) {
+  if (normalized.scale >= absolute.length) {
     before = "0"
-    after = "0".repeat(n.scale - absolute.length) + absolute
+    after = "0".repeat(normalized.scale - absolute.length) + absolute
   } else {
-    const location = absolute.length - n.scale
+    const location = absolute.length - normalized.scale
     if (location > absolute.length) {
       const zeros = location - absolute.length
       before = `${absolute}${"0".repeat(zeros)}`
@@ -1598,6 +1676,38 @@ export const format = (n: BigDecimal): string => {
   return negative ? `-${complete}` : complete
 }
 
+/**
+ * Formats a given `BigDecimal` as a `string` in scientific notation.
+ *
+ * @param n - The `BigDecimal` to format.
+ *
+ * @example
+ * import { toExponential, make } from "effect/BigDecimal"
+ *
+ * assert.deepStrictEqual(toExponential(make(123456n, -5)), "1.23456e+10")
+ *
+ * @since 3.11.0
+ * @category conversions
+ */
+export const toExponential = (n: BigDecimal): string => {
+  if (isZero(n)) {
+    return "0e+0"
+  }
+
+  const normalized = normalize(n)
+  const digits = `${abs(normalized).value}`
+  const head = digits.slice(0, 1)
+  const tail = digits.slice(1)
+
+  let output = `${isNegative(normalized) ? "-" : ""}${head}`
+  if (tail !== "") {
+    output += `.${tail}`
+  }
+
+  const exp = tail.length - normalized.scale
+  return `${output}e${exp >= 0 ? "+" : ""}${exp}`
+}
+
 /**
  * Converts a `BigDecimal` to a `number`.
  *

package/src/Channel.ts

@@ -2578,7 +2578,7 @@ export const repeated: <OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>(
  */
 export const run: <OutErr, InErr, OutDone, InDone, Env>(
   self: Channel<never, unknown, OutErr, InErr, OutDone, InDone, Env>
-) => Effect.Effect<OutDone, OutErr, Exclude<Env, Scope.Scope>> = channel.run
+) => Effect.Effect<OutDone, OutErr, Env> = channel.run
 
 /**
  * Run the channel until it finishes with a done value or fails with an error
@@ -2591,7 +2591,7 @@ export const run: <OutErr, InErr, OutDone, InDone, Env>(
  */
 export const runCollect: <OutElem, OutErr, InErr, OutDone, InDone, Env>(
   self: Channel<OutElem, unknown, OutErr, InErr, OutDone, InDone, Env>
-) => Effect.Effect<[Chunk.Chunk<OutElem>, OutDone], OutErr, Exclude<Env, Scope.Scope>> = channel.runCollect
+) => Effect.Effect<[Chunk.Chunk<OutElem>, OutDone], OutErr, Env> = channel.runCollect
 
 /**
  * Runs a channel until the end is received.
@@ -2601,7 +2601,21 @@ export const runCollect: <OutElem, OutErr, InErr, OutDone, InDone, Env>(
  */
 export const runDrain: <OutElem, OutErr, InErr, OutDone, InDone, Env>(
   self: Channel<OutElem, unknown, OutErr, InErr, OutDone, InDone, Env>
-) => Effect.Effect<OutDone, OutErr, Exclude<Env, Scope.Scope>> = channel.runDrain
+) => Effect.Effect<OutDone, OutErr, Env> = channel.runDrain
+
+/**
+ * Run the channel until it finishes with a done value or fails with an error.
+ * The channel must not read any input or write any output.
+ *
+ * Closing the channel, which includes execution of all the finalizers
+ * attached to the channel will be added to the current scope as a finalizer.
+ *
+ * @since 3.11.0
+ * @category destructors
+ */
+export const runScoped: <OutErr, InErr, OutDone, InDone, Env>(
+  self: Channel<never, unknown, OutErr, InErr, OutDone, InDone, Env>
+) => Effect.Effect<OutDone, OutErr, Env | Scope.Scope> = channel.runScoped
 
 /**
  * Use a scoped effect to emit an output element.
@@ -2613,6 +2627,18 @@ export const scoped: <A, E, R>(
   effect: Effect.Effect<A, E, R>
 ) => Channel<A, unknown, E, unknown, unknown, unknown, Exclude<R, Scope.Scope>> = channel.scoped
 
+/**
+ * Use a function that receives a scope and returns an effect to emit an output
+ * element. The output element will be the result of the returned effect, if
+ * successful.
+ *
+ * @since 3.11.0
+ * @category constructors
+ */
+export const scopedWith: <A, E, R>(
+  f: (scope: Scope.Scope) => Effect.Effect<A, E, R>
+) => Channel<A, unknown, E, unknown, unknown, unknown, R> = channel.scopedWith
+
 /**
  * Splits strings on newlines. Handles both Windows newlines (`\r\n`) and UNIX
  * newlines (`\n`).
@@ -2682,6 +2708,43 @@ export const toPull: <OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>(
 ) => Effect.Effect<Effect.Effect<Either.Either<OutElem, OutDone>, OutErr, Env>, never, Scope.Scope | Env> =
   channel.toPull
 
+/**
+ * Returns an `Effect` that can be used to repeatedly pull elements from the
+ * constructed `Channel` within the provided `Scope`. The pull effect fails
+ * with the channel's failure in case the channel fails, or returns either the
+ * channel's done value or an emitted element.
+ *
+ * @since 3.11.0
+ * @category destructors
+ */
+export const toPullIn: {
+  /**
+   * Returns an `Effect` that can be used to repeatedly pull elements from the
+   * constructed `Channel` within the provided `Scope`. The pull effect fails
+   * with the channel's failure in case the channel fails, or returns either the
+   * channel's done value or an emitted element.
+   *
+   * @since 3.11.0
+   * @category destructors
+   */
+  (scope: Scope.Scope): <OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>(
+    self: Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>
+  ) => Effect.Effect<Effect.Effect<Either.Either<OutElem, OutDone>, OutErr, Env>, never, Env>
+  /**
+   * Returns an `Effect` that can be used to repeatedly pull elements from the
+   * constructed `Channel` within the provided `Scope`. The pull effect fails
+   * with the channel's failure in case the channel fails, or returns either the
+   * channel's done value or an emitted element.
+   *
+   * @since 3.11.0
+   * @category destructors
+   */
+  <OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>(
+    self: Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>,
+    scope: Scope.Scope
+  ): Effect.Effect<Effect.Effect<Either.Either<OutElem, OutDone>, OutErr, Env>, never, Env>
+} = channel.toPullIn
+
 /**
  * Converts a `Channel` to a `Queue`.
  *
@@ -2721,7 +2784,8 @@ export {
 }
 
 /**
- * Makes a channel from an effect that returns a channel in case of success.
+ * Constructs a `Channel` from an effect that will result in a `Channel` if
+ * successful.
  *
  * @since 2.0.0
  * @category constructors
@@ -2731,7 +2795,8 @@ export const unwrap: <OutElem, InElem, OutErr, InErr, OutDone, InDone, R2, E, R>
 ) => Channel<OutElem, InElem, E | OutErr, InErr, OutDone, InDone, R | R2> = channel.unwrap
 
 /**
- * Makes a channel from a managed that returns a channel in case of success.
+ * Constructs a `Channel` from a scoped effect that will result in a
+ * `Channel` if successful.
  *
  * @since 2.0.0
  * @category constructors
@@ -2740,6 +2805,17 @@ export const unwrapScoped: <OutElem, InElem, OutErr, InErr, OutDone, InDone, Env
   self: Effect.Effect<Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>, E, R>
 ) => Channel<OutElem, InElem, E | OutErr, InErr, OutDone, InDone, Env | Exclude<R, Scope.Scope>> = channel.unwrapScoped
 
+/**
+ * Constructs a `Channel` from a function which receives a `Scope` and returns
+ * an effect that will result in a `Channel` if successful.
+ *
+ * @since 3.11.0
+ * @category constructors
+ */
+export const unwrapScopedWith: <OutElem, InElem, OutErr, InErr, OutDone, InDone, Env, E, R>(
+  f: (scope: Scope.Scope) => Effect.Effect<Channel<OutElem, InElem, OutErr, InErr, OutDone, InDone, Env>, E, R>
+) => Channel<OutElem, InElem, E | OutErr, InErr, OutDone, InDone, R | Env> = channel.unwrapScopedWith
+
 /**
  * Updates a service in the context of this channel.
  *

package/src/Config.ts

@@ -128,6 +128,14 @@ export const array: <A>(config: Config<A>, name?: string) => Config<Array<A>> =
  */
 export const boolean: (name?: string) => Config<boolean> = internal.boolean
 
+/**
+ * Constructs a config for a URL value.
+ *
+ * @since 3.11.0
+ * @category constructors
+ */
+export const url: (name?: string) => Config<URL> = internal.url
+
 /**
  * Constructs a config for a sequence of values.
  *
@@ -443,7 +451,22 @@ export const secret: (name?: string) => Config<Secret.Secret> = internal.secret
  * @since 2.0.0
  * @category constructors
  */
-export const redacted: (name?: string) => Config<Redacted.Redacted> = internal.redacted
+export const redacted: {
+  /**
+   * Constructs a config for a redacted value.
+   *
+   * @since 2.0.0
+   * @category constructors
+   */
+  (name?: string): Config<Redacted.Redacted>
+  /**
+   * Constructs a config for a redacted value.
+   *
+   * @since 2.0.0
+   * @category constructors
+   */
+  <A>(config: Config<A>): Config<Redacted.Redacted<A>>
+} = internal.redacted
 
 /**
  * Constructs a config for a sequence of values.

package/src/Context.ts

@@ -45,6 +45,38 @@ export interface Tag<in out Id, in out Value> extends Pipeable, Inspectable {
   [Unify.ignoreSymbol]?: TagUnifyIgnore
 }
 
+const ReferenceTypeId: unique symbol = internal.ReferenceTypeId
+
+/**
+ * @since 3.11.0
+ * @category symbol
+ */
+export type ReferenceTypeId = typeof ReferenceTypeId
+
+/**
+ * @since 3.11.0
+ * @category models
+ */
+export interface Reference<in out Id, in out Value> extends Pipeable, Inspectable {
+  readonly [ReferenceTypeId]: ReferenceTypeId
+  readonly defaultValue: () => Value
+
+  readonly _op: "Tag"
+  readonly Service: Value
+  readonly Identifier: Id
+  readonly [TagTypeId]: {
+    readonly _Service: Types.Invariant<Value>
+    readonly _Identifier: Types.Invariant<Id>
+  }
+  of(self: Value): Value
+  context(self: Value): Context<Id>
+  readonly stack?: string | undefined
+  readonly key: string
+  [Unify.typeSymbol]?: unknown
+  [Unify.unifySymbol]?: TagUnify<this>
+  [Unify.ignoreSymbol]?: TagUnifyIgnore
+}
+
 /**
  * @since 2.0.0
  * @category models
@@ -63,6 +95,14 @@ export interface TagClass<Self, Id, Type> extends Tag<Self, Type> {
   new(_: never): TagClassShape<Id, Type>
 }
 
+/**
+ * @since 3.11.0
+ * @category models
+ */
+export interface ReferenceClass<Self, Id, Type> extends Reference<Self, Type> {
+  new(_: never): TagClassShape<Id, Type>
+}
+
 /**
  * @category models
  * @since 2.0.0
@@ -178,6 +218,16 @@ export const isContext: (input: unknown) => input is Context<never> = internal.i
  */
 export const isTag: (input: unknown) => input is Tag<any, any> = internal.isTag
 
+/**
+ * Checks if the provided argument is a `Reference`.
+ *
+ * @param input - The value to be checked if it is a `Reference`.
+ * @since 3.11.0
+ * @category guards
+ * @experimental
+ */
+export const isReference: (u: unknown) => u is Reference<any, any> = internal.isReference
+
 /**
  * Returns an empty `Context`.
  *
@@ -319,6 +369,31 @@ export const add: {
  * @category getters
  */
 export const get: {
+  /**
+   * Get a service from the context that corresponds to the given tag.
+   *
+   * @param self - The `Context` to search for the service.
+   * @param tag - The `Tag` of the service to retrieve.
+   *
+   * @example
+   * ```ts
+   * import { pipe, Context } from "effect"
+   *
+   * const Port = Context.GenericTag<{ PORT: number }>("Port")
+   * const Timeout = Context.GenericTag<{ TIMEOUT: number }>("Timeout")
+   *
+   * const Services = pipe(
+   *   Context.make(Port, { PORT: 8080 }),
+   *   Context.add(Timeout, { TIMEOUT: 5000 })
+   * )
+   *
+   * assert.deepStrictEqual(Context.get(Services, Timeout), { TIMEOUT: 5000 })
+   * ```
+   *
+   * @since 2.0.0
+   * @category getters
+   */
+  <I, S>(tag: Reference<I, S>): <Services>(self: Context<Services>) => S
   /**
    * Get a service from the context that corresponds to the given tag.
    *
@@ -344,6 +419,31 @@ export const get: {
    * @category getters
    */
   <Services, T extends ValidTagsById<Services>>(tag: T): (self: Context<Services>) => Tag.Service<T>
+  /**
+   * Get a service from the context that corresponds to the given tag.
+   *
+   * @param self - The `Context` to search for the service.
+   * @param tag - The `Tag` of the service to retrieve.
+   *
+   * @example
+   * ```ts
+   * import { pipe, Context } from "effect"
+   *
+   * const Port = Context.GenericTag<{ PORT: number }>("Port")
+   * const Timeout = Context.GenericTag<{ TIMEOUT: number }>("Timeout")
+   *
+   * const Services = pipe(
+   *   Context.make(Port, { PORT: 8080 }),
+   *   Context.add(Timeout, { TIMEOUT: 5000 })
+   * )
+   *
+   * assert.deepStrictEqual(Context.get(Services, Timeout), { TIMEOUT: 5000 })
+   * ```
+   *
+   * @since 2.0.0
+   * @category getters
+   */
+  <Services, I, S>(self: Context<Services>, tag: Reference<I, S>): S
   /**
    * Get a service from the context that corresponds to the given tag.
    *
@@ -683,3 +783,22 @@ export const omit: <Services, S extends Array<ValidTagsById<Services>>>(
  * @category constructors
  */
 export const Tag: <const Id extends string>(id: Id) => <Self, Shape>() => TagClass<Self, Id, Shape> = internal.Tag
+
+/**
+ * @example
+ * import { Context, Layer } from "effect"
+ *
+ * class MyTag extends Context.Reference<MyTag>()("MyTag", {
+ *   defaultValue: () => ({ myNum: 108 })
+ * }) {
+ *  static Live = Layer.succeed(this, { myNum: 108 })
+ * }
+ *
+ * @since 3.11.0
+ * @category constructors
+ * @experimental
+ */
+export const Reference: <Self>() => <const Id extends string, Service>(
+  id: Id,
+  options: { readonly defaultValue: () => Service }
+) => ReferenceClass<Self, Id, Service> = internal.Reference