effect 3.8.4 → 3.9.0

package/src/Context.ts

@@ -29,7 +29,6 @@ export type TagTypeId = typeof TagTypeId
  * @category models
  */
 export interface Tag<in out Id, in out Value> extends Pipeable, Inspectable {
-  readonly _tag: "Tag"
   readonly _op: "Tag"
   readonly Service: Value
   readonly Identifier: Id
@@ -85,13 +84,13 @@ export declare namespace Tag {
   /**
    * @since 2.0.0
    */
-  export type Service<T extends Tag<any, any> | TagClassShape<any, any>> = T extends Tag<any, infer A> ? A
+  export type Service<T extends Tag<any, any> | TagClassShape<any, any>> = T extends Tag<any, any> ? T["Service"]
     : T extends TagClassShape<any, infer A> ? A
     : never
   /**
    * @since 2.0.0
    */
-  export type Identifier<T extends Tag<any, any> | TagClassShape<any, any>> = T extends Tag<infer A, any> ? A
+  export type Identifier<T extends Tag<any, any> | TagClassShape<any, any>> = T extends Tag<any, any> ? T["Identifier"]
     : T extends TagClassShape<any, any> ? T
     : never
 }
@@ -226,10 +225,52 @@ export const make: <T extends Tag<any, any>>(tag: T, service: Tag.Service<T>) =>
  * @since 2.0.0
  */
 export const add: {
+  /**
+   * Adds a service to a given `Context`.
+   *
+   * @example
+   * import { Context, pipe } from "effect"
+   *
+   * const Port = Context.GenericTag<{ PORT: number }>("Port")
+   * const Timeout = Context.GenericTag<{ TIMEOUT: number }>("Timeout")
+   *
+   * const someContext = Context.make(Port, { PORT: 8080 })
+   *
+   * const Services = pipe(
+   *   someContext,
+   *   Context.add(Timeout, { TIMEOUT: 5000 })
+   * )
+   *
+   * assert.deepStrictEqual(Context.get(Services, Port), { PORT: 8080 })
+   * assert.deepStrictEqual(Context.get(Services, Timeout), { TIMEOUT: 5000 })
+   *
+   * @since 2.0.0
+   */
   <T extends Tag<any, any>>(
     tag: T,
     service: Tag.Service<T>
   ): <Services>(self: Context<Services>) => Context<Services | Tag.Identifier<T>>
+  /**
+   * Adds a service to a given `Context`.
+   *
+   * @example
+   * import { Context, pipe } from "effect"
+   *
+   * const Port = Context.GenericTag<{ PORT: number }>("Port")
+   * const Timeout = Context.GenericTag<{ TIMEOUT: number }>("Timeout")
+   *
+   * const someContext = Context.make(Port, { PORT: 8080 })
+   *
+   * const Services = pipe(
+   *   someContext,
+   *   Context.add(Timeout, { TIMEOUT: 5000 })
+   * )
+   *
+   * assert.deepStrictEqual(Context.get(Services, Port), { PORT: 8080 })
+   * assert.deepStrictEqual(Context.get(Services, Timeout), { TIMEOUT: 5000 })
+   *
+   * @since 2.0.0
+   */
   <Services, T extends Tag<any, any>>(
     self: Context<Services>,
     tag: T,
@@ -260,7 +301,51 @@ 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
+   * 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, 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
+   * 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, T extends ValidTagsById<Services>>(self: Context<Services>, tag: T): Tag.Service<T>
 } = internal.get
 
@@ -272,7 +357,21 @@ export const get: {
  * @category getters
  */
 export const getOrElse: {
+  /**
+   * Get a service from the context that corresponds to the given tag, or
+   * use the fallback value.
+   *
+   * @since 3.7.0
+   * @category getters
+   */
   <S, I, B>(tag: Tag<I, S>, orElse: LazyArg<B>): <Services>(self: Context<Services>) => S | B
+  /**
+   * Get a service from the context that corresponds to the given tag, or
+   * use the fallback value.
+   *
+   * @since 3.7.0
+   * @category getters
+   */
   <Services, S, I, B>(self: Context<Services>, tag: Tag<I, S>, orElse: LazyArg<B>): S | B
 } = internal.getOrElse
 
@@ -300,7 +399,53 @@ export const getOrElse: {
  * @category unsafe
  */
 export const unsafeGet: {
+  /**
+   * Get a service from the context that corresponds to the given tag.
+   * This function is unsafe because if the tag is not present in the context, a runtime error will be thrown.
+   *
+   * For a safer version see {@link getOption}.
+   *
+   * @param self - The `Context` to search for the service.
+   * @param tag - The `Tag` of the service to retrieve.
+   *
+   * @example
+   * import { Context } from "effect"
+   *
+   * const Port = Context.GenericTag<{ PORT: number }>("Port")
+   * const Timeout = Context.GenericTag<{ TIMEOUT: number }>("Timeout")
+   *
+   * const Services = Context.make(Port, { PORT: 8080 })
+   *
+   * assert.deepStrictEqual(Context.unsafeGet(Services, Port), { PORT: 8080 })
+   * assert.throws(() => Context.unsafeGet(Services, Timeout))
+   *
+   * @since 2.0.0
+   * @category unsafe
+   */
   <S, I>(tag: Tag<I, S>): <Services>(self: Context<Services>) => S
+  /**
+   * Get a service from the context that corresponds to the given tag.
+   * This function is unsafe because if the tag is not present in the context, a runtime error will be thrown.
+   *
+   * For a safer version see {@link getOption}.
+   *
+   * @param self - The `Context` to search for the service.
+   * @param tag - The `Tag` of the service to retrieve.
+   *
+   * @example
+   * import { Context } from "effect"
+   *
+   * const Port = Context.GenericTag<{ PORT: number }>("Port")
+   * const Timeout = Context.GenericTag<{ TIMEOUT: number }>("Timeout")
+   *
+   * const Services = Context.make(Port, { PORT: 8080 })
+   *
+   * assert.deepStrictEqual(Context.unsafeGet(Services, Port), { PORT: 8080 })
+   * assert.throws(() => Context.unsafeGet(Services, Timeout))
+   *
+   * @since 2.0.0
+   * @category unsafe
+   */
   <Services, S, I>(self: Context<Services>, tag: Tag<I, S>): S
 } = internal.unsafeGet
 
@@ -326,7 +471,49 @@ export const unsafeGet: {
  * @category getters
  */
 export const getOption: {
+  /**
+   * Get the value associated with the specified tag from the context wrapped in an `Option` object. If the tag is not
+   * found, the `Option` object will be `None`.
+   *
+   * @param self - The `Context` to search for the service.
+   * @param tag - The `Tag` of the service to retrieve.
+   *
+   * @example
+   * import { Context, Option } from "effect"
+   *
+   * const Port = Context.GenericTag<{ PORT: number }>("Port")
+   * const Timeout = Context.GenericTag<{ TIMEOUT: number }>("Timeout")
+   *
+   * const Services = Context.make(Port, { PORT: 8080 })
+   *
+   * assert.deepStrictEqual(Context.getOption(Services, Port), Option.some({ PORT: 8080 }))
+   * assert.deepStrictEqual(Context.getOption(Services, Timeout), Option.none())
+   *
+   * @since 2.0.0
+   * @category getters
+   */
   <S, I>(tag: Tag<I, S>): <Services>(self: Context<Services>) => Option<S>
+  /**
+   * Get the value associated with the specified tag from the context wrapped in an `Option` object. If the tag is not
+   * found, the `Option` object will be `None`.
+   *
+   * @param self - The `Context` to search for the service.
+   * @param tag - The `Tag` of the service to retrieve.
+   *
+   * @example
+   * import { Context, Option } from "effect"
+   *
+   * const Port = Context.GenericTag<{ PORT: number }>("Port")
+   * const Timeout = Context.GenericTag<{ TIMEOUT: number }>("Timeout")
+   *
+   * const Services = Context.make(Port, { PORT: 8080 })
+   *
+   * assert.deepStrictEqual(Context.getOption(Services, Port), Option.some({ PORT: 8080 }))
+   * assert.deepStrictEqual(Context.getOption(Services, Timeout), Option.none())
+   *
+   * @since 2.0.0
+   * @category getters
+   */
   <Services, S, I>(self: Context<Services>, tag: Tag<I, S>): Option<S>
 } = internal.getOption
 
@@ -353,7 +540,51 @@ export const getOption: {
  * @since 2.0.0
  */
 export const merge: {
+  /**
+   * Merges two `Context`s, returning a new `Context` containing the services of both.
+   *
+   * @param self - The first `Context` to merge.
+   * @param that - The second `Context` to merge.
+   *
+   * @example
+   * import { Context } from "effect"
+   *
+   * const Port = Context.GenericTag<{ PORT: number }>("Port")
+   * const Timeout = Context.GenericTag<{ TIMEOUT: number }>("Timeout")
+   *
+   * const firstContext = Context.make(Port, { PORT: 8080 })
+   * const secondContext = Context.make(Timeout, { TIMEOUT: 5000 })
+   *
+   * const Services = Context.merge(firstContext, secondContext)
+   *
+   * assert.deepStrictEqual(Context.get(Services, Port), { PORT: 8080 })
+   * assert.deepStrictEqual(Context.get(Services, Timeout), { TIMEOUT: 5000 })
+   *
+   * @since 2.0.0
+   */
   <R1>(that: Context<R1>): <Services>(self: Context<Services>) => Context<R1 | Services>
+  /**
+   * Merges two `Context`s, returning a new `Context` containing the services of both.
+   *
+   * @param self - The first `Context` to merge.
+   * @param that - The second `Context` to merge.
+   *
+   * @example
+   * import { Context } from "effect"
+   *
+   * const Port = Context.GenericTag<{ PORT: number }>("Port")
+   * const Timeout = Context.GenericTag<{ TIMEOUT: number }>("Timeout")
+   *
+   * const firstContext = Context.make(Port, { PORT: 8080 })
+   * const secondContext = Context.make(Timeout, { TIMEOUT: 5000 })
+   *
+   * const Services = Context.merge(firstContext, secondContext)
+   *
+   * assert.deepStrictEqual(Context.get(Services, Port), { PORT: 8080 })
+   * assert.deepStrictEqual(Context.get(Services, Timeout), { TIMEOUT: 5000 })
+   *
+   * @since 2.0.0
+   */
   <Services, R1>(self: Context<Services>, that: Context<R1>): Context<Services | R1>
 } = internal.merge
 

package/src/Cron.ts

@@ -7,7 +7,7 @@ import * as Equal from "./Equal.js"
 import * as equivalence from "./Equivalence.js"
 import { dual, pipe } from "./Function.js"
 import * as Hash from "./Hash.js"
-import { format, type Inspectable, NodeInspectSymbol } from "./Inspectable.js"
+import { DenoInspectSymbol, format, type Inspectable, NodeInspectSymbol } from "./Inspectable.js"
 import * as N from "./Number.js"
 import { type Pipeable, pipeArguments } from "./Pipeable.js"
 import { hasProperty } from "./Predicate.js"
@@ -67,6 +67,9 @@ const CronProto: Omit<Cron, "minutes" | "hours" | "days" | "months" | "weekdays"
       weekdays: Arr.fromIterable(this.weekdays)
     }
   },
+  [DenoInspectSymbol](this: Cron) {
+    return this.toJSON()
+  },
   [NodeInspectSymbol](this: Cron) {
     return this.toJSON()
   },
@@ -370,7 +373,19 @@ const restrictionsEquals = (self: ReadonlySet<number>, that: ReadonlySet<number>
  * @category predicates
  */
 export const equals: {
+  /**
+   * Checks if two `Cron`s are equal.
+   *
+   * @since 2.0.0
+   * @category predicates
+   */
   (that: Cron): (self: Cron) => boolean
+  /**
+   * Checks if two `Cron`s are equal.
+   *
+   * @since 2.0.0
+   * @category predicates
+   */
   (self: Cron, that: Cron): boolean
 } = dual(2, (self: Cron, that: Cron): boolean => Equivalence(self, that))
 

package/src/Data.ts

@@ -430,6 +430,39 @@ export declare namespace TaggedEnum {
  * @since 2.0.0
  */
 export const taggedEnum: {
+  /**
+   * Create a constructor for a tagged union of `Data` structs.
+   *
+   * You can also pass a `TaggedEnum.WithGenerics` if you want to add generics to
+   * the constructor.
+   *
+   * @example
+   * import { Data } from "effect"
+   *
+   * const { BadRequest, NotFound } = Data.taggedEnum<
+   *   | { readonly _tag: "BadRequest"; readonly status: 400; readonly message: string }
+   *   | { readonly _tag: "NotFound"; readonly status: 404; readonly message: string }
+   * >()
+   *
+   * const notFound = NotFound({ status: 404, message: "Not Found" })
+   *
+   * @example
+   * import { Data } from "effect"
+   *
+   * type MyResult<E, A> = Data.TaggedEnum<{
+   *   Failure: { readonly error: E }
+   *   Success: { readonly value: A }
+   * }>
+   * interface MyResultDefinition extends Data.TaggedEnum.WithGenerics<2> {
+   *   readonly taggedEnum: MyResult<this["A"], this["B"]>
+   * }
+   * const { Failure, Success } = Data.taggedEnum<MyResultDefinition>()
+   *
+   * const success = Success({ value: 1 })
+   *
+   * @category constructors
+   * @since 2.0.0
+   */
   <Z extends TaggedEnum.WithGenerics<1>>(): Types.Simplify<
     {
       readonly [Tag in Z["taggedEnum"]["_tag"]]: <A>(
@@ -442,6 +475,39 @@ export const taggedEnum: {
     } & TaggedEnum.GenericMatchers<Z>
   >
 
+  /**
+   * Create a constructor for a tagged union of `Data` structs.
+   *
+   * You can also pass a `TaggedEnum.WithGenerics` if you want to add generics to
+   * the constructor.
+   *
+   * @example
+   * import { Data } from "effect"
+   *
+   * const { BadRequest, NotFound } = Data.taggedEnum<
+   *   | { readonly _tag: "BadRequest"; readonly status: 400; readonly message: string }
+   *   | { readonly _tag: "NotFound"; readonly status: 404; readonly message: string }
+   * >()
+   *
+   * const notFound = NotFound({ status: 404, message: "Not Found" })
+   *
+   * @example
+   * import { Data } from "effect"
+   *
+   * type MyResult<E, A> = Data.TaggedEnum<{
+   *   Failure: { readonly error: E }
+   *   Success: { readonly value: A }
+   * }>
+   * interface MyResultDefinition extends Data.TaggedEnum.WithGenerics<2> {
+   *   readonly taggedEnum: MyResult<this["A"], this["B"]>
+   * }
+   * const { Failure, Success } = Data.taggedEnum<MyResultDefinition>()
+   *
+   * const success = Success({ value: 1 })
+   *
+   * @category constructors
+   * @since 2.0.0
+   */
   <Z extends TaggedEnum.WithGenerics<2>>(): Types.Simplify<
     {
       readonly [Tag in Z["taggedEnum"]["_tag"]]: <A, B>(
@@ -454,6 +520,39 @@ export const taggedEnum: {
     } & TaggedEnum.GenericMatchers<Z>
   >
 
+  /**
+   * Create a constructor for a tagged union of `Data` structs.
+   *
+   * You can also pass a `TaggedEnum.WithGenerics` if you want to add generics to
+   * the constructor.
+   *
+   * @example
+   * import { Data } from "effect"
+   *
+   * const { BadRequest, NotFound } = Data.taggedEnum<
+   *   | { readonly _tag: "BadRequest"; readonly status: 400; readonly message: string }
+   *   | { readonly _tag: "NotFound"; readonly status: 404; readonly message: string }
+   * >()
+   *
+   * const notFound = NotFound({ status: 404, message: "Not Found" })
+   *
+   * @example
+   * import { Data } from "effect"
+   *
+   * type MyResult<E, A> = Data.TaggedEnum<{
+   *   Failure: { readonly error: E }
+   *   Success: { readonly value: A }
+   * }>
+   * interface MyResultDefinition extends Data.TaggedEnum.WithGenerics<2> {
+   *   readonly taggedEnum: MyResult<this["A"], this["B"]>
+   * }
+   * const { Failure, Success } = Data.taggedEnum<MyResultDefinition>()
+   *
+   * const success = Success({ value: 1 })
+   *
+   * @category constructors
+   * @since 2.0.0
+   */
   <Z extends TaggedEnum.WithGenerics<3>>(): Types.Simplify<
     {
       readonly [Tag in Z["taggedEnum"]["_tag"]]: <A, B, C>(
@@ -466,6 +565,39 @@ export const taggedEnum: {
     } & TaggedEnum.GenericMatchers<Z>
   >
 
+  /**
+   * Create a constructor for a tagged union of `Data` structs.
+   *
+   * You can also pass a `TaggedEnum.WithGenerics` if you want to add generics to
+   * the constructor.
+   *
+   * @example
+   * import { Data } from "effect"
+   *
+   * const { BadRequest, NotFound } = Data.taggedEnum<
+   *   | { readonly _tag: "BadRequest"; readonly status: 400; readonly message: string }
+   *   | { readonly _tag: "NotFound"; readonly status: 404; readonly message: string }
+   * >()
+   *
+   * const notFound = NotFound({ status: 404, message: "Not Found" })
+   *
+   * @example
+   * import { Data } from "effect"
+   *
+   * type MyResult<E, A> = Data.TaggedEnum<{
+   *   Failure: { readonly error: E }
+   *   Success: { readonly value: A }
+   * }>
+   * interface MyResultDefinition extends Data.TaggedEnum.WithGenerics<2> {
+   *   readonly taggedEnum: MyResult<this["A"], this["B"]>
+   * }
+   * const { Failure, Success } = Data.taggedEnum<MyResultDefinition>()
+   *
+   * const success = Success({ value: 1 })
+   *
+   * @category constructors
+   * @since 2.0.0
+   */
   <Z extends TaggedEnum.WithGenerics<4>>(): Types.Simplify<
     {
       readonly [Tag in Z["taggedEnum"]["_tag"]]: <A, B, C, D>(
@@ -478,6 +610,39 @@ export const taggedEnum: {
     } & TaggedEnum.GenericMatchers<Z>
   >
 
+  /**
+   * Create a constructor for a tagged union of `Data` structs.
+   *
+   * You can also pass a `TaggedEnum.WithGenerics` if you want to add generics to
+   * the constructor.
+   *
+   * @example
+   * import { Data } from "effect"
+   *
+   * const { BadRequest, NotFound } = Data.taggedEnum<
+   *   | { readonly _tag: "BadRequest"; readonly status: 400; readonly message: string }
+   *   | { readonly _tag: "NotFound"; readonly status: 404; readonly message: string }
+   * >()
+   *
+   * const notFound = NotFound({ status: 404, message: "Not Found" })
+   *
+   * @example
+   * import { Data } from "effect"
+   *
+   * type MyResult<E, A> = Data.TaggedEnum<{
+   *   Failure: { readonly error: E }
+   *   Success: { readonly value: A }
+   * }>
+   * interface MyResultDefinition extends Data.TaggedEnum.WithGenerics<2> {
+   *   readonly taggedEnum: MyResult<this["A"], this["B"]>
+   * }
+   * const { Failure, Success } = Data.taggedEnum<MyResultDefinition>()
+   *
+   * const success = Success({ value: 1 })
+   *
+   * @category constructors
+   * @since 2.0.0
+   */
   <A extends { readonly _tag: string }>(): TaggedEnum.Constructor<A>
 } = () =>
   new Proxy({}, {