effect 3.10.18 → 3.11.0

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
@@ -101,9 +141,11 @@ export declare namespace Tag {
  * @param key - A key that will be used to compare tags.
  *
  * @example
+ * ```ts
  * import { Context } from "effect"
  *
  * assert.strictEqual(Context.GenericTag("PORT").key === Context.GenericTag("PORT").key, true)
+ * ```
  *
  * @since 2.0.0
  * @category constructors
@@ -148,9 +190,11 @@ export const unsafeMake: <Services>(unsafeMap: Map<string, any>) => Context<Serv
  * @param input - The value to be checked if it is a `Context`.
  *
  * @example
+ * ```ts
  * import { Context } from "effect"
  *
  * assert.strictEqual(Context.isContext(Context.empty()), true)
+ * ```
  *
  * @since 2.0.0
  * @category guards
@@ -163,22 +207,36 @@ export const isContext: (input: unknown) => input is Context<never> = internal.i
  * @param input - The value to be checked if it is a `Tag`.
  *
  * @example
+ * ```ts
  * import { Context } from "effect"
  *
  * assert.strictEqual(Context.isTag(Context.GenericTag("Tag")), true)
+ * ```
  *
  * @since 2.0.0
  * @category guards
  */
 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`.
  *
  * @example
+ * ```ts
  * import { Context } from "effect"
  *
  * assert.strictEqual(Context.isContext(Context.empty()), true)
+ * ```
  *
  * @since 2.0.0
  * @category constructors
@@ -189,6 +247,7 @@ export const empty: () => Context<never> = internal.empty
  * Creates a new `Context` with a single service associated to the tag.
  *
  * @example
+ * ```ts
  * import { Context } from "effect"
  *
  * const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -196,6 +255,7 @@ export const empty: () => Context<never> = internal.empty
  * const Services = Context.make(Port, { PORT: 8080 })
  *
  * assert.deepStrictEqual(Context.get(Services, Port), { PORT: 8080 })
+ * ```
  *
  * @since 2.0.0
  * @category constructors
@@ -207,6 +267,7 @@ export const make: <T extends Tag<any, any>>(tag: T, service: Tag.Service<T>) =>
  * Adds a service to a given `Context`.
  *
  * @example
+ * ```ts
  * import { Context, pipe } from "effect"
  *
  * const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -221,6 +282,7 @@ export const make: <T extends Tag<any, any>>(tag: T, service: Tag.Service<T>) =>
  *
  * assert.deepStrictEqual(Context.get(Services, Port), { PORT: 8080 })
  * assert.deepStrictEqual(Context.get(Services, Timeout), { TIMEOUT: 5000 })
+ * ```
  *
  * @since 2.0.0
  */
@@ -229,6 +291,7 @@ export const add: {
    * Adds a service to a given `Context`.
    *
    * @example
+   * ```ts
    * import { Context, pipe } from "effect"
    *
    * const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -243,6 +306,7 @@ export const add: {
    *
    * assert.deepStrictEqual(Context.get(Services, Port), { PORT: 8080 })
    * assert.deepStrictEqual(Context.get(Services, Timeout), { TIMEOUT: 5000 })
+   * ```
    *
    * @since 2.0.0
    */
@@ -254,6 +318,7 @@ export const add: {
    * Adds a service to a given `Context`.
    *
    * @example
+   * ```ts
    * import { Context, pipe } from "effect"
    *
    * const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -268,6 +333,7 @@ export const add: {
    *
    * assert.deepStrictEqual(Context.get(Services, Port), { PORT: 8080 })
    * assert.deepStrictEqual(Context.get(Services, Timeout), { TIMEOUT: 5000 })
+   * ```
    *
    * @since 2.0.0
    */
@@ -285,6 +351,7 @@ export const add: {
  * @param tag - The `Tag` of the service to retrieve.
  *
  * @example
+ * ```ts
  * import { pipe, Context } from "effect"
  *
  * const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -296,6 +363,7 @@ export const add: {
  * )
  *
  * assert.deepStrictEqual(Context.get(Services, Timeout), { TIMEOUT: 5000 })
+ * ```
  *
  * @since 2.0.0
  * @category getters
@@ -308,6 +376,32 @@ export const get: {
    * @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.
+   *
+   * @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")
@@ -319,6 +413,7 @@ export const get: {
    * )
    *
    * assert.deepStrictEqual(Context.get(Services, Timeout), { TIMEOUT: 5000 })
+   * ```
    *
    * @since 2.0.0
    * @category getters
@@ -331,6 +426,7 @@ export const get: {
    * @param tag - The `Tag` of the service to retrieve.
    *
    * @example
+   * ```ts
    * import { pipe, Context } from "effect"
    *
    * const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -342,6 +438,32 @@ export const get: {
    * )
    *
    * 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.
+   *
+   * @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
@@ -385,6 +507,7 @@ export const getOrElse: {
  * @param tag - The `Tag` of the service to retrieve.
  *
  * @example
+ * ```ts
  * import { Context } from "effect"
  *
  * const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -394,6 +517,7 @@ export const getOrElse: {
  *
  * assert.deepStrictEqual(Context.unsafeGet(Services, Port), { PORT: 8080 })
  * assert.throws(() => Context.unsafeGet(Services, Timeout))
+ * ```
  *
  * @since 2.0.0
  * @category unsafe
@@ -409,6 +533,7 @@ export const unsafeGet: {
    * @param tag - The `Tag` of the service to retrieve.
    *
    * @example
+   * ```ts
    * import { Context } from "effect"
    *
    * const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -418,6 +543,7 @@ export const unsafeGet: {
    *
    * assert.deepStrictEqual(Context.unsafeGet(Services, Port), { PORT: 8080 })
    * assert.throws(() => Context.unsafeGet(Services, Timeout))
+   * ```
    *
    * @since 2.0.0
    * @category unsafe
@@ -433,6 +559,7 @@ export const unsafeGet: {
    * @param tag - The `Tag` of the service to retrieve.
    *
    * @example
+   * ```ts
    * import { Context } from "effect"
    *
    * const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -442,6 +569,7 @@ export const unsafeGet: {
    *
    * assert.deepStrictEqual(Context.unsafeGet(Services, Port), { PORT: 8080 })
    * assert.throws(() => Context.unsafeGet(Services, Timeout))
+   * ```
    *
    * @since 2.0.0
    * @category unsafe
@@ -457,6 +585,7 @@ export const unsafeGet: {
  * @param tag - The `Tag` of the service to retrieve.
  *
  * @example
+ * ```ts
  * import { Context, Option } from "effect"
  *
  * const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -466,6 +595,7 @@ export const unsafeGet: {
  *
  * assert.deepStrictEqual(Context.getOption(Services, Port), Option.some({ PORT: 8080 }))
  * assert.deepStrictEqual(Context.getOption(Services, Timeout), Option.none())
+ * ```
  *
  * @since 2.0.0
  * @category getters
@@ -479,6 +609,7 @@ export const getOption: {
    * @param tag - The `Tag` of the service to retrieve.
    *
    * @example
+   * ```ts
    * import { Context, Option } from "effect"
    *
    * const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -488,6 +619,7 @@ export const getOption: {
    *
    * assert.deepStrictEqual(Context.getOption(Services, Port), Option.some({ PORT: 8080 }))
    * assert.deepStrictEqual(Context.getOption(Services, Timeout), Option.none())
+   * ```
    *
    * @since 2.0.0
    * @category getters
@@ -501,6 +633,7 @@ export const getOption: {
    * @param tag - The `Tag` of the service to retrieve.
    *
    * @example
+   * ```ts
    * import { Context, Option } from "effect"
    *
    * const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -510,6 +643,7 @@ export const getOption: {
    *
    * assert.deepStrictEqual(Context.getOption(Services, Port), Option.some({ PORT: 8080 }))
    * assert.deepStrictEqual(Context.getOption(Services, Timeout), Option.none())
+   * ```
    *
    * @since 2.0.0
    * @category getters
@@ -524,6 +658,7 @@ export const getOption: {
  * @param that - The second `Context` to merge.
  *
  * @example
+ * ```ts
  * import { Context } from "effect"
  *
  * const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -536,6 +671,7 @@ export const getOption: {
  *
  * assert.deepStrictEqual(Context.get(Services, Port), { PORT: 8080 })
  * assert.deepStrictEqual(Context.get(Services, Timeout), { TIMEOUT: 5000 })
+ * ```
  *
  * @since 2.0.0
  */
@@ -547,6 +683,7 @@ export const merge: {
    * @param that - The second `Context` to merge.
    *
    * @example
+   * ```ts
    * import { Context } from "effect"
    *
    * const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -559,6 +696,7 @@ export const merge: {
    *
    * assert.deepStrictEqual(Context.get(Services, Port), { PORT: 8080 })
    * assert.deepStrictEqual(Context.get(Services, Timeout), { TIMEOUT: 5000 })
+   * ```
    *
    * @since 2.0.0
    */
@@ -570,6 +708,7 @@ export const merge: {
    * @param that - The second `Context` to merge.
    *
    * @example
+   * ```ts
    * import { Context } from "effect"
    *
    * const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -582,6 +721,7 @@ export const merge: {
    *
    * assert.deepStrictEqual(Context.get(Services, Port), { PORT: 8080 })
    * assert.deepStrictEqual(Context.get(Services, Timeout), { TIMEOUT: 5000 })
+   * ```
    *
    * @since 2.0.0
    */
@@ -595,6 +735,7 @@ export const merge: {
  * @param tags - The list of `Tag`s to be included in the new `Context`.
  *
  * @example
+ * ```ts
  * import { pipe, Context, Option } from "effect"
  *
  * const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -609,6 +750,7 @@ export const merge: {
  *
  * assert.deepStrictEqual(Context.getOption(Services, Port), Option.some({ PORT: 8080 }))
  * assert.deepStrictEqual(Context.getOption(Services, Timeout), Option.none())
+ * ```
  *
  * @since 2.0.0
  */
@@ -626,6 +768,7 @@ export const omit: <Services, S extends Array<ValidTagsById<Services>>>(
 
 /**
  * @example
+ * ```ts
  * import { Context, Layer } from "effect"
  *
  * class MyTag extends Context.Tag("MyTag")<
@@ -634,8 +777,28 @@ export const omit: <Services, S extends Array<ValidTagsById<Services>>>(
  * >() {
  *  static Live = Layer.succeed(this, { myNum: 108 })
  * }
+ * ```
  *
  * @since 2.0.0
  * @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