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

package/src/String.ts

@@ -206,7 +206,7 @@ export type Concat<A extends string, B extends string> = `${A}${B}`
  * console.log(result2) // "helloworld"
  * ```
  *
- * @category concatenating
+ * @category combining
  * @since 2.0.0
  */
 export const concat: {
@@ -225,7 +225,7 @@ export const concat: {
    * console.log(result2) // "helloworld"
    * ```
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <B extends string>(that: B): <A extends string>(self: A) => Concat<A, B>
@@ -244,7 +244,7 @@ export const concat: {
    * console.log(result2) // "helloworld"
    * ```
    *
-   * @category concatenating
+   * @category combining
    * @since 2.0.0
    */
   <A extends string, B extends string>(self: A, that: B): Concat<A, B>
@@ -525,7 +525,7 @@ export const isNonEmpty = (self: string): boolean => self.length > 0
  * assert.deepStrictEqual(String.length("abc"), 3)
  * ```
  *
- * @category utils
+ * @category getters
  * @since 2.0.0
  */
 export const length = (self: string): number => self.length
@@ -1645,9 +1645,8 @@ const linesSeparated = (self: string, stripped: boolean): LinesIterator => new L
  *
  * **When to use**
  *
- * Use to normalize mixed-case, snake_case, kebab-case, or spaced input into
- * custom word-case output when you need a delimiter or part transform that the
- * fixed case helpers do not provide.
+ * Use when you need custom word-case output with a delimiter or part transform
+ * that the fixed case helpers do not provide.
  *
  * @see {@link pascalCase} for fixed PascalCase output
  * @see {@link camelCase} for fixed lower-initial camelCase output
@@ -1665,9 +1664,8 @@ export const noCase: {
    *
    * **When to use**
    *
-   * Use to normalize mixed-case, snake_case, kebab-case, or spaced input into
-   * custom word-case output when you need a delimiter or part transform that the
-   * fixed case helpers do not provide.
+   * Use when you need custom word-case output with a delimiter or part transform
+   * that the fixed case helpers do not provide.
    *
    * @see {@link pascalCase} for fixed PascalCase output
    * @see {@link camelCase} for fixed lower-initial camelCase output
@@ -1692,9 +1690,8 @@ export const noCase: {
    *
    * **When to use**
    *
-   * Use to normalize mixed-case, snake_case, kebab-case, or spaced input into
-   * custom word-case output when you need a delimiter or part transform that the
-   * fixed case helpers do not provide.
+   * Use when you need custom word-case output with a delimiter or part transform
+   * that the fixed case helpers do not provide.
    *
    * @see {@link pascalCase} for fixed PascalCase output
    * @see {@link camelCase} for fixed lower-initial camelCase output
@@ -1877,7 +1874,7 @@ export const snakeCase: (self: string) => string = noCase({
  *
  * @see {@link concat} for concatenating two strings directly
  *
- * @category concatenating
+ * @category combining
  * @since 4.0.0
  */
 export const ReducerConcat: Reducer.Reducer<string> = Reducer.make((a, b) => a + b, "")

package/src/Struct.ts

@@ -106,7 +106,7 @@ import * as Reducer from "./Reducer.ts"
  *
  * @see {@link Mutable} – also flattens but removes `readonly`
  * @see {@link Assign} – merges two types with right-side precedence
- * @category Type-Level Programming
+ * @category utility types
  * @since 4.0.0
  */
 export type Simplify<T> = { [K in keyof T]: T[K] } & {}
@@ -134,7 +134,7 @@ export type Simplify<T> = { [K in keyof T]: T[K] } & {}
  * ```
  *
  * @see {@link Simplify} – flattens intersections without removing `readonly`
- * @category Type-Level Programming
+ * @category utility types
  * @since 4.0.0
  */
 export type Mutable<T> = { -readonly [K in keyof T]: T[K] } & {}
@@ -165,7 +165,7 @@ export type Mutable<T> = { -readonly [K in keyof T]: T[K] } & {}
  *
  * @see {@link assign} – the runtime equivalent
  * @see {@link Simplify} – flatten the resulting intersection
- * @category Type-Level Programming
+ * @category utility types
  * @since 4.0.0
  */
 export type Assign<T, U> = Simplify<keyof T & keyof U extends never ? T & U : Omit<T, keyof T & keyof U> & U>
@@ -175,7 +175,7 @@ export type Assign<T, U> = Simplify<keyof T & keyof U extends never ? T & U : Om
  *
  * **When to use**
  *
- * Use to extract a single property in a pipeline.
+ * Use to extract a single property from a struct in a pipeline.
  *
  * **Details**
  *
@@ -201,7 +201,7 @@ export const get: {
    *
    * **When to use**
    *
-   * Use to extract a single property in a pipeline.
+   * Use to extract a single property from a struct in a pipeline.
    *
    * **Details**
    *
@@ -227,7 +227,7 @@ export const get: {
    *
    * **When to use**
    *
-   * Use to extract a single property in a pipeline.
+   * Use to extract a single property from a struct in a pipeline.
    *
    * **Details**
    *
@@ -255,8 +255,8 @@ export const get: {
  *
  * **When to use**
  *
- * Use when you use instead of `Object.keys` when you want the return type narrowed to the
- * known keys of the struct.
+ * Use when you want a typed replacement for `Object.keys` that narrows the result
+ * to the known string keys of the struct.
  *
  * **Gotchas**
  *
@@ -823,7 +823,7 @@ type EntryEvolved<S, E> = {
  *
  * @see {@link evolve} – transform values only
  * @see {@link evolveKeys} – transform keys only
- * @category utils
+ * @category transforming
  * @since 4.0.0
  */
 export const evolveEntries: {
@@ -857,7 +857,7 @@ export const evolveEntries: {
    *
    * @see {@link evolve} – transform values only
    * @see {@link evolveKeys} – transform keys only
-   * @category utils
+   * @category transforming
    * @since 4.0.0
    */
   <S extends object, E extends EntryEvolver<S>>(e: E): (self: S) => EntryEvolved<S, E>
@@ -891,7 +891,7 @@ export const evolveEntries: {
    *
    * @see {@link evolve} – transform values only
    * @see {@link evolveKeys} – transform keys only
-   * @category utils
+   * @category transforming
    * @since 4.0.0
    */
   <S extends object, E extends EntryEvolver<S>>(self: S, e: E): EntryEvolved<S, E>
@@ -1003,7 +1003,8 @@ export const renameKeys: {
  *
  * **When to use**
  *
- * Use when you need to compare structs property-by-property.
+ * Use when you need equality for a record-like object to be decided field by
+ * field, with a custom equality rule for each property.
  *
  * **Details**
  *
@@ -1028,7 +1029,7 @@ export const renameKeys: {
  * ```
  *
  * @see {@link makeOrder} – create an `Order` for structs
- * @category Equivalence
+ * @category instances
  * @since 4.0.0
  */
 export const makeEquivalence = Equivalence.Struct
@@ -1040,8 +1041,8 @@ export const makeEquivalence = Equivalence.Struct
  *
  * **When to use**
  *
- * Use to sort or compare structs by multiple fields with lexicographic
- * priority.
+ * Use when you need to sort record-like objects lexicographically by several
+ * fields, with each field using its own ordering rule.
  *
  * **Details**
  *
@@ -1063,7 +1064,7 @@ export const makeEquivalence = Equivalence.Struct
  * ```
  *
  * @see {@link makeEquivalence} – create an `Equivalence` for structs
- * @category Ordering
+ * @category ordering
  * @since 4.0.0
  */
 export const makeOrder = order.Struct
@@ -1074,8 +1075,8 @@ export const makeOrder = order.Struct
  *
  * **When to use**
  *
- * Use when you use this interface when defining a typed function for {@link map},
- * {@link mapPick}, or {@link mapOmit}.
+ * Use when defining a typed function for {@link map}, {@link mapPick}, or
+ * {@link mapOmit}.
  *
  * **Details**
  *
@@ -1538,8 +1539,8 @@ function buildStruct<
  *
  * **When to use**
  *
- * Use when you need to merge two structs of the same shape, such as summing
- * counters or concatenating strings.
+ * Use when you need to merge two same-shape records by combining each property
+ * independently, such as summing counters or concatenating strings.
  *
  * **Details**
  *
@@ -1591,7 +1592,8 @@ export function makeCombiner<A>(
  *
  * **When to use**
  *
- * Use to fold a collection of structs into a single summary struct.
+ * Use when you need to fold same-shape records by accumulating each property
+ * independently into one summary record.
  *
  * **Details**
  *

package/src/SubscriptionRef.ts

@@ -141,7 +141,7 @@ const Proto = {
  *
  * **When to use**
  *
- * Use to create shared mutable state when consumers need to read the latest
+ * Use to create a `SubscriptionRef` when consumers need to read the latest
  * value and subscribe to every update.
  *
  * **Details**
@@ -209,6 +209,11 @@ export const changes = <A>(self: SubscriptionRef<A>): Stream.Stream<A> => Stream
 /**
  * Retrieves the current value of the `SubscriptionRef` unsafely.
  *
+ * **When to use**
+ *
+ * Use when you are in synchronous internals or test setup where concurrent
+ * updates are controlled.
+ *
  * **Gotchas**
  *
  * This function directly accesses the underlying reference without any
@@ -516,8 +521,8 @@ export const getAndUpdateEffect: {
  *
  * **When to use**
  *
- * Use to read the old value while applying a synchronous update only when a
- * new value is available.
+ * Use to read the old `SubscriptionRef` value while applying a synchronous
+ * update only when a new value is available.
  *
  * **Details**
  *
@@ -553,8 +558,8 @@ export const getAndUpdateSome: {
    *
    * **When to use**
    *
-   * Use to read the old value while applying a synchronous update only when a
-   * new value is available.
+   * Use to read the old `SubscriptionRef` value while applying a synchronous
+   * update only when a new value is available.
    *
    * **Details**
    *
@@ -590,8 +595,8 @@ export const getAndUpdateSome: {
    *
    * **When to use**
    *
-   * Use to read the old value while applying a synchronous update only when a
-   * new value is available.
+   * Use to read the old `SubscriptionRef` value while applying a synchronous
+   * update only when a new value is available.
    *
    * **Details**
    *
@@ -641,8 +646,8 @@ export const getAndUpdateSome: {
  *
  * **When to use**
  *
- * Use to read the old value while applying an effectful update only when a new
- * value is available.
+ * Use to read the old `SubscriptionRef` value while applying an effectful
+ * update only when a new value is available.
  *
  * **Details**
  *
@@ -678,8 +683,8 @@ export const getAndUpdateSomeEffect: {
    *
    * **When to use**
    *
-   * Use to read the old value while applying an effectful update only when a new
-   * value is available.
+   * Use to read the old `SubscriptionRef` value while applying an effectful
+   * update only when a new value is available.
    *
    * **Details**
    *
@@ -715,8 +720,8 @@ export const getAndUpdateSomeEffect: {
    *
    * **When to use**
    *
-   * Use to read the old value while applying an effectful update only when a new
-   * value is available.
+   * Use to read the old `SubscriptionRef` value while applying an effectful
+   * update only when a new value is available.
    *
    * **Details**
    *
@@ -958,7 +963,7 @@ export const modifyEffect: {
  * **When to use**
  *
  * Use to return a separate result while synchronously deciding whether to
- * publish a new value.
+ * publish a new `SubscriptionRef` value.
  *
  * **Details**
  *
@@ -996,7 +1001,7 @@ export const modifySome: {
    * **When to use**
    *
    * Use to return a separate result while synchronously deciding whether to
-   * publish a new value.
+   * publish a new `SubscriptionRef` value.
    *
    * **Details**
    *
@@ -1034,7 +1039,7 @@ export const modifySome: {
    * **When to use**
    *
    * Use to return a separate result while synchronously deciding whether to
-   * publish a new value.
+   * publish a new `SubscriptionRef` value.
    *
    * **Details**
    *
@@ -1083,7 +1088,7 @@ export const modifySome: {
  * **When to use**
  *
  * Use to return a separate result while effectfully deciding whether to publish
- * a new value.
+ * a new `SubscriptionRef` value.
  *
  * **Details**
  *
@@ -1125,7 +1130,7 @@ export const modifySomeEffect: {
    * **When to use**
    *
    * Use to return a separate result while effectfully deciding whether to publish
-   * a new value.
+   * a new `SubscriptionRef` value.
    *
    * **Details**
    *
@@ -1167,7 +1172,7 @@ export const modifySomeEffect: {
    * **When to use**
    *
    * Use to return a separate result while effectfully deciding whether to publish
-   * a new value.
+   * a new `SubscriptionRef` value.
    *
    * **Details**
    *