effect 3.8.3 → 3.8.5

package/src/Context.ts

@@ -226,10 +226,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 +302,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 +358,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 +400,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 +472,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 +541,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

@@ -370,7 +370,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({}, {