effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/Context.ts

@@ -193,8 +193,8 @@ export declare namespace ServiceClass {
  *
  * **When to use**
  *
- * Use when a dependency must be provided by the surrounding context. Use
- * `Reference` when a dependency should have a default value.
+ * Use when you need to define a context service key for a dependency that must
+ * be provided by the surrounding context.
  *
  * **Details**
  *
@@ -242,8 +242,8 @@ export const Service: {
    *
    * **When to use**
    *
-   * Use when a dependency must be provided by the surrounding context. Use
-   * `Reference` when a dependency should have a default value.
+   * Use when you need to define a context service key for a dependency that must
+   * be provided by the surrounding context.
    *
    * **Details**
    *
@@ -291,8 +291,8 @@ export const Service: {
    *
    * **When to use**
    *
-   * Use when a dependency must be provided by the surrounding context. Use
-   * `Reference` when a dependency should have a default value.
+   * Use when you need to define a context service key for a dependency that must
+   * be provided by the surrounding context.
    *
    * **Details**
    *
@@ -353,8 +353,8 @@ export const Service: {
    *
    * **When to use**
    *
-   * Use when a dependency must be provided by the surrounding context. Use
-   * `Reference` when a dependency should have a default value.
+   * Use when you need to define a context service key for a dependency that must
+   * be provided by the surrounding context.
    *
    * **Details**
    *
@@ -646,8 +646,12 @@ export interface Context<in Services> extends Equal.Equal, Pipeable, Inspectable
 }
 
 /**
- * Creates a `Context` from an existing service map without validating or
- * copying it.
+ * Creates a `Context` from an existing service map.
+ *
+ * **When to use**
+ *
+ * Use when constructing a low-level `Context` from a trusted map whose lifecycle
+ * you control.
  *
  * **Gotchas**
  *
@@ -830,8 +834,7 @@ export const make = <I, S>(
  *
  * **When to use**
  *
- * Use when you always have a service value to store. Use `addOrOmit`
- * when the value is optional and a missing value should remove the service.
+ * Use when you need to store a known service value in a `Context`.
  *
  * **Details**
  *
@@ -869,8 +872,7 @@ export const add: {
    *
    * **When to use**
    *
-   * Use when you always have a service value to store. Use `addOrOmit`
-   * when the value is optional and a missing value should remove the service.
+   * Use when you need to store a known service value in a `Context`.
    *
    * **Details**
    *
@@ -908,8 +910,7 @@ export const add: {
    *
    * **When to use**
    *
-   * Use when you always have a service value to store. Use `addOrOmit`
-   * when the value is optional and a missing value should remove the service.
+   * Use when you need to store a known service value in a `Context`.
    *
    * **Details**
    *
@@ -956,8 +957,7 @@ export const add: {
  *
  * **When to use**
  *
- * Use when service presence is already represented as an `Option`.
- * Use `add` when you always want to store a service value.
+ * Use when you need to add or omit a `Context` service based on an `Option`.
  *
  * **Details**
  *
@@ -991,8 +991,7 @@ export const addOrOmit: {
    *
    * **When to use**
    *
-   * Use when service presence is already represented as an `Option`.
-   * Use `add` when you always want to store a service value.
+   * Use when you need to add or omit a `Context` service based on an `Option`.
    *
    * **Details**
    *
@@ -1026,8 +1025,7 @@ export const addOrOmit: {
    *
    * **When to use**
    *
-   * Use when service presence is already represented as an `Option`.
-   * Use `add` when you always want to store a service value.
+   * Use when you need to add or omit a `Context` service based on an `Option`.
    *
    * **Details**
    *
@@ -1079,8 +1077,8 @@ export const addOrOmit: {
  *
  * **When to use**
  *
- * Use when you want a fallback value for a missing regular
- * service. Use `getOption` when you need to distinguish presence from absence.
+ * Use when you need a fallback for a missing `Context.Service` key while still
+ * resolving `Context.Reference` defaults.
  *
  * **Details**
  *
@@ -1129,8 +1127,8 @@ export const getOrElse: {
    *
    * **When to use**
    *
-   * Use when you want a fallback value for a missing regular
-   * service. Use `getOption` when you need to distinguish presence from absence.
+   * Use when you need a fallback for a missing `Context.Service` key while still
+   * resolving `Context.Reference` defaults.
    *
    * **Details**
    *
@@ -1179,8 +1177,8 @@ export const getOrElse: {
    *
    * **When to use**
    *
-   * Use when you want a fallback value for a missing regular
-   * service. Use `getOption` when you need to distinguish presence from absence.
+   * Use when you need a fallback for a missing `Context.Service` key while still
+   * resolving `Context.Reference` defaults.
    *
    * **Details**
    *
@@ -1236,8 +1234,8 @@ export const getOrElse: {
  *
  * **When to use**
  *
- * Use when you need raw map-style lookup. Use `getOption` when you want the
- * usual `Context.Reference` default-value behavior.
+ * Use when you need to read the service stored for a key without resolving
+ * `Context.Reference` defaults.
  *
  * **Gotchas**
  *
@@ -1256,8 +1254,8 @@ export const getOrUndefined: {
    *
    * **When to use**
    *
-   * Use when you need raw map-style lookup. Use `getOption` when you want the
-   * usual `Context.Reference` default-value behavior.
+   * Use when you need to read the service stored for a key without resolving
+   * `Context.Reference` defaults.
    *
    * **Gotchas**
    *
@@ -1276,8 +1274,8 @@ export const getOrUndefined: {
    *
    * **When to use**
    *
-   * Use when you need raw map-style lookup. Use `getOption` when you want the
-   * usual `Context.Reference` default-value behavior.
+   * Use when you need to read the service stored for a key without resolving
+   * `Context.Reference` defaults.
    *
    * **Gotchas**
    *
@@ -1301,9 +1299,8 @@ export const getOrUndefined: {
  *
  * **When to use**
  *
- * Use when the context type cannot prove that the service is present. Use
- * `get` when the service requirement is tracked in the context type, or
- * `getOption` when absence is expected.
+ * Use when you need to read a service from a context whose type does not prove
+ * the service is present.
  *
  * **Details**
  *
@@ -1339,9 +1336,8 @@ export const getUnsafe: {
    *
    * **When to use**
    *
-   * Use when the context type cannot prove that the service is present. Use
-   * `get` when the service requirement is tracked in the context type, or
-   * `getOption` when absence is expected.
+   * Use when you need to read a service from a context whose type does not prove
+   * the service is present.
    *
    * **Details**
    *
@@ -1377,9 +1373,8 @@ export const getUnsafe: {
    *
    * **When to use**
    *
-   * Use when the context type cannot prove that the service is present. Use
-   * `get` when the service requirement is tracked in the context type, or
-   * `getOption` when absence is expected.
+   * Use when you need to read a service from a context whose type does not prove
+   * the service is present.
    *
    * **Details**
    *
@@ -1425,8 +1420,8 @@ export const getUnsafe: {
  *
  * **When to use**
  *
- * Use when the context type proves that the service is present. Use
- * `getOption` or `getOrElse` when a service may be absent.
+ * Use when you need type-checked access to a service already included in the
+ * context type.
  *
  * **Example** (Getting a service from a context)
  *
@@ -1457,8 +1452,8 @@ export const get: {
    *
    * **When to use**
    *
-   * Use when the context type proves that the service is present. Use
-   * `getOption` or `getOrElse` when a service may be absent.
+   * Use when you need type-checked access to a service already included in the
+   * context type.
    *
    * **Example** (Getting a service from a context)
    *
@@ -1489,8 +1484,8 @@ export const get: {
    *
    * **When to use**
    *
-   * Use when the context type proves that the service is present. Use
-   * `getOption` or `getOrElse` when a service may be absent.
+   * Use when you need type-checked access to a service already included in the
+   * context type.
    *
    * **Example** (Getting a service from a context)
    *
@@ -1524,8 +1519,8 @@ export const get: {
  *
  * **When to use**
  *
- * Use to resolve a `Context.Reference` against a context when you want either
- * the stored override or the reference's default value.
+ * Use when you need a `Context.Reference` value resolved from either a stored
+ * override or the reference's default value.
  *
  * **Details**
  *
@@ -1601,8 +1596,8 @@ const serviceNotFoundError = (service: Key<any, any>) => {
  *
  * **When to use**
  *
- * Use when service absence is expected and should be represented
- * as data. Use `getOrElse` when you want to provide a fallback value directly.
+ * Use when you need to read a `Context` service as an `Option` so absence is
+ * represented as data.
  *
  * **Details**
  *
@@ -1639,8 +1634,8 @@ export const getOption: {
    *
    * **When to use**
    *
-   * Use when service absence is expected and should be represented
-   * as data. Use `getOrElse` when you want to provide a fallback value directly.
+   * Use when you need to read a `Context` service as an `Option` so absence is
+   * represented as data.
    *
    * **Details**
    *
@@ -1677,8 +1672,8 @@ export const getOption: {
    *
    * **When to use**
    *
-   * Use when service absence is expected and should be represented
-   * as data. Use `getOrElse` when you want to provide a fallback value directly.
+   * Use when you need to read a `Context` service as an `Option` so absence is
+   * represented as data.
    *
    * **Details**
    *
@@ -1722,8 +1717,7 @@ export const getOption: {
  *
  * **When to use**
  *
- * Use when combining two contexts. Use `mergeAll` when combining a
- * variadic list of contexts.
+ * Use when you need to combine two contexts.
  *
  * **Details**
  *
@@ -1759,8 +1753,7 @@ export const merge: {
    *
    * **When to use**
    *
-   * Use when combining two contexts. Use `mergeAll` when combining a
-   * variadic list of contexts.
+   * Use when you need to combine two contexts.
    *
    * **Details**
    *
@@ -1796,8 +1789,7 @@ export const merge: {
    *
    * **When to use**
    *
-   * Use when combining two contexts. Use `mergeAll` when combining a
-   * variadic list of contexts.
+   * Use when you need to combine two contexts.
    *
    * **Details**
    *
@@ -1841,8 +1833,7 @@ export const merge: {
  *
  * **When to use**
  *
- * Use when the number of contexts is variadic. Use `merge` when
- * combining exactly two contexts.
+ * Use when you need to combine a variadic list of contexts.
  *
  * **Details**
  *
@@ -1896,8 +1887,7 @@ export const mergeAll = <T extends Array<unknown>>(
  *
  * **When to use**
  *
- * Use when you want to keep a small allowlist of services. Use `omit`
- * when it is easier to name the services to remove.
+ * Use when you want to keep an allowlist of services in a `Context`.
  *
  * **Example** (Picking services from a context)
  *
@@ -1944,8 +1934,7 @@ export const pick = <S extends ReadonlyArray<Key<any, any>>>(
  *
  * **When to use**
  *
- * Use when you want to remove a small denylist of services. Use `pick`
- * when it is easier to name the services to keep.
+ * Use when you want to remove a denylist of services from a `Context`.
  *
  * **Example** (Omitting services from a context)
  *
@@ -2000,7 +1989,7 @@ export const omit = <S extends ReadonlyArray<Key<any, any>>>(
  * @see {@link pick} for keeping selected services
  * @see {@link omit} for removing selected services
  *
- * @category utils
+ * @category mutations
  * @since 4.0.0
  */
 export const mutate: {
@@ -2019,7 +2008,7 @@ export const mutate: {
    * @see {@link pick} for keeping selected services
    * @see {@link omit} for removing selected services
    *
-   * @category utils
+   * @category mutations
    * @since 4.0.0
    */
   <Services, B>(f: (context: Context<Services>) => Context<B>): <Services>(self: Context<Services>) => Context<B>
@@ -2038,7 +2027,7 @@ export const mutate: {
    * @see {@link pick} for keeping selected services
    * @see {@link omit} for removing selected services
    *
-   * @category utils
+   * @category mutations
    * @since 4.0.0
    */
   <Services, B>(self: Context<Services>, f: (context: Context<Services>) => Context<B>): Context<B>
@@ -2060,7 +2049,7 @@ export const mutate: {
      * @see {@link pick} for keeping selected services
      * @see {@link omit} for removing selected services
      *
-     * @category utils
+     * @category mutations
      * @since 4.0.0
      */
     Services>(new Map(self.mapUnsafe))
@@ -2086,9 +2075,8 @@ const withMapUnsafe = <Services, B>(self: Context<Services>, f: (map: Map<string
  *
  * **When to use**
  *
- * Use when a service should be available even if it is not
- * explicitly stored in the `Context`. Use `Service` when the service must be
- * provided by the surrounding context.
+ * Use when you need to define a context key with a lazily computed default
+ * value.
  *
  * **Details**
  *

package/src/Cron.ts

@@ -632,8 +632,8 @@ export const parse = (cron: string, tz?: DateTime.TimeZone | string): Result.Res
  *
  * **When to use**
  *
- * Use when the input is expected to be valid and you want to avoid
- * handling the `Result` type.
+ * Use when you expect the input to be valid and want to avoid handling the
+ * `Result` type.
  *
  * **Example** (Parsing cron expressions unsafely)
  *
@@ -690,7 +690,7 @@ export const parseUnsafe = (cron: string, tz?: DateTime.TimeZone | string): Cron
  * @see {@link next} for finding the next matching date/time
  * @see {@link prev} for finding the previous matching date/time
  *
- * @category utils
+ * @category predicates
  * @since 2.0.0
  */
 export const match = (cron: Cron, date: DateTime.DateTime.Input): boolean => {
@@ -766,7 +766,7 @@ const daysInMonth = (date: Date): number =>
  * @see {@link prev} for finding the previous scheduled occurrence
  * @see {@link sequence} for iterating future scheduled occurrences
  *
- * @category utils
+ * @category getters
  * @since 2.0.0
  */
 export const next = (cron: Cron, now?: DateTime.DateTime.Input): Date => {
@@ -792,7 +792,7 @@ export const next = (cron: Cron, now?: DateTime.DateTime.Input): Date => {
  *
  * @see {@link next} for finding the next scheduled occurrence
  *
- * @category utils
+ * @category getters
  * @since 3.20.0
  */
 export const prev = (cron: Cron, now?: DateTime.DateTime.Input): Date => {
@@ -983,7 +983,7 @@ const stepCron = (cron: Cron, now: DateTime.DateTime.Input | undefined, directio
  *
  * @see {@link next} for computing one next occurrence
  *
- * @category utils
+ * @category sequencing
  * @since 2.0.0
  */
 export const sequence = function*(cron: Cron, now?: DateTime.DateTime.Input): IterableIterator<Date> {

package/src/Crypto.ts

@@ -202,13 +202,13 @@ export interface Crypto {
  *
  * **When to use**
  *
- * Use when you need to provide or retrieve the full platform Crypto service
- * from an effect's context.
+ * Use when you need to provide or retrieve the full platform cryptography
+ * service from an effect's context.
  *
  * **Details**
  *
- * Providing this service supplies the cryptographic operations described by the
- * `Crypto` interface.
+ * Providing this service supplies platform-agnostic cryptographic operations
+ * such as hashing, UUID generation, and secure random values.
  *
  * @see {@link make} for constructing a Crypto service from primitive operations
  *

package/src/Data.ts

@@ -87,7 +87,7 @@ import type { Unify } from "./Unify.ts"
  *
  * **When to use**
  *
- * Use when you need a lightweight immutable value type with `.pipe()` support. If you also need a `_tag` discriminator, use {@link TaggedClass}; if you need a yieldable error, use {@link Error} or {@link TaggedError}.
+ * Use when you need a lightweight immutable value type with `.pipe()` support.
  *
  * **Details**
  *
@@ -131,7 +131,7 @@ export const Class: new<A extends Record<string, any> = {}>(
  *
  * **When to use**
  *
- * Use when you need a single-variant tagged type or an ad-hoc discriminator. For multi-variant unions, prefer {@link TaggedEnum} with {@link taggedEnum}; for yieldable errors, use {@link TaggedError}.
+ * Use when you need a single-variant tagged type or an ad-hoc discriminator.
  *
  * **Details**
  *
@@ -174,7 +174,7 @@ export const TaggedClass = <Tag extends string>(
  *
  * **When to use**
  *
- * Use when you have two or more variants that share a common `_tag` discriminator. For generic tagged enums, see {@link TaggedEnum.WithGenerics}.
+ * Use when you have two or more variants that share a common `_tag` discriminator.
  *
  * **Details**
  *
@@ -254,7 +254,7 @@ export declare namespace TaggedEnum {
    *
    * **When to use**
    *
-   * Use when variant payloads need to be parameterized, such as `Result<E, A>`. Pass the interface, not the type alias, to {@link taggedEnum} to get generic-aware constructors and matchers.
+   * Use when variant payloads need to be parameterized, such as `Result<E, A>`.
    *
    * **Details**
    *
@@ -420,7 +420,8 @@ export declare namespace TaggedEnum {
    *
    * **When to use**
    *
-   * Use to type the constructors-and-matchers object returned by `taggedEnum`.
+   * Use when you want to annotate an exported constructor bundle so downstream
+   * code keeps exact variant constructors and exhaustive matching.
    *
    * **Details**
    *
@@ -586,7 +587,8 @@ export declare namespace TaggedEnum {
  *
  * **When to use**
  *
- * Use when you have a `TaggedEnum` type and need constructors and matchers for its values. For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+ * Use when you model a closed union with plain data objects and want
+ * construction, tag checks, and exhaustive matching from the same definition.
  *
  * **Details**
  *
@@ -658,7 +660,8 @@ export const taggedEnum: {
    *
    * **When to use**
    *
-   * Use when you have a `TaggedEnum` type and need constructors and matchers for its values. For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   * Use when you model a closed union with plain data objects and want
+   * construction, tag checks, and exhaustive matching from the same definition.
    *
    * **Details**
    *
@@ -741,7 +744,8 @@ export const taggedEnum: {
    *
    * **When to use**
    *
-   * Use when you have a `TaggedEnum` type and need constructors and matchers for its values. For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   * Use when you model a closed union with plain data objects and want
+   * construction, tag checks, and exhaustive matching from the same definition.
    *
    * **Details**
    *
@@ -824,7 +828,8 @@ export const taggedEnum: {
    *
    * **When to use**
    *
-   * Use when you have a `TaggedEnum` type and need constructors and matchers for its values. For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   * Use when you model a closed union with plain data objects and want
+   * construction, tag checks, and exhaustive matching from the same definition.
    *
    * **Details**
    *
@@ -907,7 +912,8 @@ export const taggedEnum: {
    *
    * **When to use**
    *
-   * Use when you have a `TaggedEnum` type and need constructors and matchers for its values. For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   * Use when you model a closed union with plain data objects and want
+   * construction, tag checks, and exhaustive matching from the same definition.
    *
    * **Details**
    *
@@ -990,7 +996,8 @@ export const taggedEnum: {
    *
    * **When to use**
    *
-   * Use when you have a `TaggedEnum` type and need constructors and matchers for its values. For generic enums, pass a {@link TaggedEnum.WithGenerics} interface.
+   * Use when you model a closed union with plain data objects and want
+   * construction, tag checks, and exhaustive matching from the same definition.
    *
    * **Details**
    *
@@ -1106,8 +1113,8 @@ function taggedMatch<
  *
  * **When to use**
  *
- * Use when defining yieldable errors that do **not** need tag-based
- * discrimination. If you need tag-based recovery, use {@link TaggedError}.
+ * Use when you need yieldable errors that do **not** need tag-based
+ * discrimination.
  *
  * **Details**
  *
@@ -1149,8 +1156,7 @@ export const Error: new<A extends Record<string, any> = {}>(
  *
  * **When to use**
  *
- * Use when modeling domain errors in Effect applications where you want
- * discriminated-union error handling.
+ * Use when you need domain errors with discriminated-union handling.
  *
  * **Details**
  *