effect 4.0.0-beta.74 → 4.0.0-beta.75

package/src/ConfigProvider.ts

@@ -173,7 +173,7 @@ export function makeValue(value: string): Node {
  *
  * **When to use**
  *
- * Use when describing a directory or JSON object inside a custom
+ * Use when you need to describe a directory or JSON object inside a custom
  * provider.
  *
  * **Details**
@@ -207,8 +207,8 @@ export function makeRecord(keys: ReadonlySet<string>, value?: string): Node {
  *
  * **When to use**
  *
- * Use when describing a JSON array or a set of numerically-indexed env
- * vars inside a custom provider.
+ * Use when you need to describe a JSON array or numerically indexed env vars
+ * inside a custom provider.
  *
  * **Details**
  *
@@ -239,9 +239,8 @@ export function makeArray(length: number, value?: string): Node {
  *
  * **When to use**
  *
- * Use when you use this from a custom provider's `get` callback when the underlying store
- * is unreachable or produces an I/O error, or match on it in error channels
- * when consuming provider output directly.
+ * Use when you need to report that a custom provider's underlying store is
+ * unreachable or produced an I/O error while reading configuration data.
  *
  * **Gotchas**
  *
@@ -367,10 +366,8 @@ export interface ConfigProvider extends Pipeable {
  *
  * **When to use**
  *
- * Use to override the provider for an entire program via
- * `Effect.provideService(ConfigProvider.ConfigProvider, myProvider)`, or to
- * retrieve the current provider inside an Effect with
- * `yield* ConfigProvider.ConfigProvider`.
+ * Use to override the active raw configuration provider for an entire program,
+ * or retrieve the current provider inside an Effect.
  *
  * **Example** (Providing a custom provider)
  *
@@ -473,8 +470,8 @@ export function make(
  *
  * **When to use**
  *
- * Use to layer multiple config sources, such as env vars plus a defaults
- * file, or to provide partial overrides on top of a base config.
+ * Use to layer multiple config sources, such as env vars plus a defaults file,
+ * or provide partial overrides on top of a base config.
  *
  * **Details**
  *
@@ -510,8 +507,8 @@ export const orElse: {
    *
    * **When to use**
    *
-   * Use to layer multiple config sources, such as env vars plus a defaults
-   * file, or to provide partial overrides on top of a base config.
+   * Use to layer multiple config sources, such as env vars plus a defaults file,
+   * or provide partial overrides on top of a base config.
    *
    * **Details**
    *
@@ -547,8 +544,8 @@ export const orElse: {
    *
    * **When to use**
    *
-   * Use to layer multiple config sources, such as env vars plus a defaults
-   * file, or to provide partial overrides on top of a base config.
+   * Use to layer multiple config sources, such as env vars plus a defaults file,
+   * or provide partial overrides on top of a base config.
    *
    * **Details**
    *
@@ -589,9 +586,8 @@ export const orElse: {
  *
  * **When to use**
  *
- * Use when you use this for renaming or re-casing path segments, or for adding suffixes and
- * other per-segment transformations. See {@link constantCase} for a common
- * specialization.
+ * Use when you need to rename, re-case, or otherwise transform config path
+ * segments before lookup.
  *
  * **Details**
  *
@@ -628,9 +624,8 @@ export const mapInput: {
    *
    * **When to use**
    *
-   * Use when you use this for renaming or re-casing path segments, or for adding suffixes and
-   * other per-segment transformations. See {@link constantCase} for a common
-   * specialization.
+   * Use when you need to rename, re-case, or otherwise transform config path
+   * segments before lookup.
    *
    * **Details**
    *
@@ -667,9 +662,8 @@ export const mapInput: {
    *
    * **When to use**
    *
-   * Use when you use this for renaming or re-casing path segments, or for adding suffixes and
-   * other per-segment transformations. See {@link constantCase} for a common
-   * specialization.
+   * Use when you need to rename, re-case, or otherwise transform config path
+   * segments before lookup.
    *
    * **Details**
    *
@@ -749,7 +743,7 @@ export const constantCase: (self: ConfigProvider) => ConfigProvider = mapInput((
  * **When to use**
  *
  * Use to namespace config under a prefix like `"app"` or `"database"`, or
- * to reuse the same provider shape for multiple sub-configs.
+ * reuse the same provider shape for multiple sub-configs.
  *
  * **Details**
  *
@@ -788,7 +782,7 @@ export const nested: {
    * **When to use**
    *
    * Use to namespace config under a prefix like `"app"` or `"database"`, or
-   * to reuse the same provider shape for multiple sub-configs.
+   * reuse the same provider shape for multiple sub-configs.
    *
    * **Details**
    *
@@ -827,7 +821,7 @@ export const nested: {
    * **When to use**
    *
    * Use to namespace config under a prefix like `"app"` or `"database"`, or
-   * to reuse the same provider shape for multiple sub-configs.
+   * reuse the same provider shape for multiple sub-configs.
    *
    * **Details**
    *
@@ -913,9 +907,9 @@ export const layer = <E = never, R = never>(
  *
  * **When to use**
  *
- * Use to add defaults that should only apply when the primary provider
- * has no value for a path, or to override specific keys while keeping the rest
- * from the existing provider by setting `asPrimary: true`.
+ * Use to add defaults that should only apply when the primary provider has no
+ * value for a path, or override specific keys while keeping the rest from the
+ * existing provider by setting `asPrimary: true`.
  *
  * **Details**
  *
@@ -963,9 +957,8 @@ export const layerAdd = <E = never, R = never>(
  *
  * **When to use**
  *
- * Use when you use this in unit or integration tests where you want deterministic config
- * without touching the environment, or when embedding config directly in code
- * or reading a JSON file.
+ * Use when you need deterministic config from an in-memory JavaScript value,
+ * such as in tests, embedded config, or parsed JSON.
  *
  * **Details**
  *
@@ -1050,8 +1043,8 @@ function describeUnknown(u: unknown): Node | undefined {
  *
  * **When to use**
  *
- * Use to read configuration from `process.env`, which is the default when
- * no provider is explicitly set, or to pass a custom env record for testing or
+ * Use to read configuration from `process.env`, which is the default when no
+ * provider is explicitly set, or pass a custom env record for testing or
  * non-Node runtimes.
  *
  * **Details**
@@ -1170,9 +1163,8 @@ function trieNodeAt(root: EnvTrieNode, path: Path): EnvTrieNode | undefined {
  *
  * **When to use**
  *
- * Use when you already have the `.env` contents as a string, such as
- * contents fetched from a remote store or embedded in a test. Use
- * {@link fromDotEnv} instead if you want to read a `.env` file from disk.
+ * Use when you already have the `.env` contents as a string, such as contents
+ * fetched from a remote store or embedded in a test.
  *
  * **Details**
  *
@@ -1312,9 +1304,7 @@ function searchLast(str: string, rgx: RegExp): number {
  *
  * **When to use**
  *
- * Use to load environment config from a `.env` file at application
- * startup. Use {@link fromDotEnvContents} if you already have the file
- * contents as a string.
+ * Use to load environment config from a `.env` file at application startup.
  *
  * **Details**
  *
@@ -1358,8 +1348,8 @@ export const fromDotEnv: (options?: {
  *
  * **When to use**
  *
- * Use when you use this for Kubernetes ConfigMap or Secret volume mounts, where each key is
- * a file under a mount path, or for any file-per-key configuration layout.
+ * Use when you expose each config key as a file under a directory, such as
+ * Kubernetes ConfigMap or Secret volume mounts.
  *
  * **Details**
  *

package/src/Console.ts

@@ -113,8 +113,8 @@ export interface Console {
  *
  * **When to use**
  *
- * Use when an Effect program needs the current console service as a context
- * reference, such as when providing or overriding a console implementation.
+ * Use when you need an effect to run against a provided console implementation,
+ * such as tests or alternate runtimes, rather than the default console.
  *
  * **Details**
  *

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)
  *
@@ -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)
  *

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
  *