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

package/src/TxReentrantLock.ts

@@ -594,7 +594,8 @@ export const withWriteLock: {
  *
  * **When to use**
  *
- * Use as the short alias for {@link withWriteLock}.
+ * Use when you need to run an effect with exclusive write access through a
+ * `TxReentrantLock` and prefer the concise lock helper.
  *
  * **Example** (Running an effect with exclusive access)
  *
@@ -620,7 +621,8 @@ export const withLock: {
    *
    * **When to use**
    *
-   * Use as the short alias for {@link withWriteLock}.
+   * Use when you need to run an effect with exclusive write access through a
+   * `TxReentrantLock` and prefer the concise lock helper.
    *
    * **Example** (Running an effect with exclusive access)
    *
@@ -646,7 +648,8 @@ export const withLock: {
    *
    * **When to use**
    *
-   * Use as the short alias for {@link withWriteLock}.
+   * Use when you need to run an effect with exclusive write access through a
+   * `TxReentrantLock` and prefer the concise lock helper.
    *
    * **Example** (Running an effect with exclusive access)
    *

package/src/TxRef.ts

@@ -120,7 +120,7 @@ export interface TxRef<in out A> extends Pipeable {
  *
  * **When to use**
  *
- * Use to create a transactional reference inside an `Effect` workflow.
+ * Use to create a `TxRef` inside an `Effect` workflow.
  *
  * **Example** (Creating transactional references)
  *
@@ -153,8 +153,8 @@ export const make = <A>(initial: A) => Effect.sync(() => makeUnsafe(initial))
  *
  * **When to use**
  *
- * Use to construct a transactional reference synchronously when it must be
- * created outside an `Effect` workflow.
+ * Use to construct a `TxRef` synchronously when it must be created outside an
+ * `Effect` workflow.
  *
  * **Example** (Creating transactional references unsafely)
  *
@@ -188,8 +188,8 @@ export const makeUnsafe = <A>(initial: A): TxRef<A> => ({
  *
  * **When to use**
  *
- * Use to update a transactional reference and return a computed result from the
- * same transaction step.
+ * Use to update a `TxRef` and return a computed result from the same
+ * transaction step.
  *
  * **Example** (Modifying transactional references)
  *
@@ -216,8 +216,8 @@ export const modify: {
    *
    * **When to use**
    *
-   * Use to update a transactional reference and return a computed result from the
-   * same transaction step.
+   * Use to update a `TxRef` and return a computed result from the same
+   * transaction step.
    *
    * **Example** (Modifying transactional references)
    *
@@ -244,8 +244,8 @@ export const modify: {
    *
    * **When to use**
    *
-   * Use to update a transactional reference and return a computed result from the
-   * same transaction step.
+   * Use to update a `TxRef` and return a computed result from the same
+   * transaction step.
    *
    * **Example** (Modifying transactional references)
    *
@@ -291,7 +291,7 @@ export const modify: {
  *
  * **When to use**
  *
- * Use to transform a transactional reference when no result value is needed.
+ * Use to transform a `TxRef` when no result value is needed.
  *
  * **Example** (Updating transactional references)
  *
@@ -319,7 +319,7 @@ export const update: {
    *
    * **When to use**
    *
-   * Use to transform a transactional reference when no result value is needed.
+   * Use to transform a `TxRef` when no result value is needed.
    *
    * **Example** (Updating transactional references)
    *
@@ -347,7 +347,7 @@ export const update: {
    *
    * **When to use**
    *
-   * Use to transform a transactional reference when no result value is needed.
+   * Use to transform a `TxRef` when no result value is needed.
    *
    * **Example** (Updating transactional references)
    *
@@ -380,7 +380,7 @@ export const update: {
  *
  * **When to use**
  *
- * Use to read the current value of a transactional reference.
+ * Use to read the current value of a `TxRef`.
  *
  * **Example** (Reading transactional references)
  *
@@ -409,7 +409,7 @@ export const get = <A>(self: TxRef<A>): Effect.Effect<A> => modify(self, (curren
  *
  * **When to use**
  *
- * Use to replace the value of a transactional reference.
+ * Use to replace the value of a `TxRef`.
  *
  * **Example** (Setting transactional references)
  *
@@ -437,7 +437,7 @@ export const set: {
    *
    * **When to use**
    *
-   * Use to replace the value of a transactional reference.
+   * Use to replace the value of a `TxRef`.
    *
    * **Example** (Setting transactional references)
    *
@@ -465,7 +465,7 @@ export const set: {
    *
    * **When to use**
    *
-   * Use to replace the value of a transactional reference.
+   * Use to replace the value of a `TxRef`.
    *
    * **Example** (Setting transactional references)
    *

package/src/TxSubscriptionRef.ts

@@ -123,8 +123,8 @@ const TxSubscriptionRefProto: Omit<TxSubscriptionRef<any>, typeof TypeId | "ref"
  *
  * **When to use**
  *
- * Use to create transactional state that also publishes every committed update
- * to subscribers.
+ * Use to create a `TxSubscriptionRef` that publishes every committed update to
+ * subscribers.
  *
  * **Example** (Creating a transactional subscription reference)
  *
@@ -163,8 +163,8 @@ export const make = <A>(value: A): Effect.Effect<TxSubscriptionRef<A>> =>
  *
  * **When to use**
  *
- * Use to read the current transactional value without subscribing to future
- * changes.
+ * Use to read the current `TxSubscriptionRef` value without subscribing to
+ * future changes.
  *
  * **Example** (Reading the current value)
  *
@@ -195,8 +195,8 @@ export const get = <A>(self: TxSubscriptionRef<A>): Effect.Effect<A> => TxRef.ge
  *
  * **When to use**
  *
- * Use to compute a separate return value and next state in one transactional
- * update.
+ * Use to compute a separate return value and next `TxSubscriptionRef` state in
+ * one transactional update.
  *
  * **Example** (Modifying and returning a value)
  *
@@ -228,8 +228,8 @@ export const modify: {
    *
    * **When to use**
    *
-   * Use to compute a separate return value and next state in one transactional
-   * update.
+   * Use to compute a separate return value and next `TxSubscriptionRef` state in
+   * one transactional update.
    *
    * **Example** (Modifying and returning a value)
    *
@@ -261,8 +261,8 @@ export const modify: {
    *
    * **When to use**
    *
-   * Use to compute a separate return value and next state in one transactional
-   * update.
+   * Use to compute a separate return value and next `TxSubscriptionRef` state in
+   * one transactional update.
    *
    * **Example** (Modifying and returning a value)
    *
@@ -307,7 +307,8 @@ export const modify: {
  *
  * **When to use**
  *
- * Use to replace the current value with a known value and publish it.
+ * Use to replace the current `TxSubscriptionRef` value with a known value and
+ * publish it.
  *
  * **Example** (Setting a new value)
  *
@@ -333,7 +334,8 @@ export const set: {
    *
    * **When to use**
    *
-   * Use to replace the current value with a known value and publish it.
+   * Use to replace the current `TxSubscriptionRef` value with a known value and
+   * publish it.
    *
    * **Example** (Setting a new value)
    *
@@ -359,7 +361,8 @@ export const set: {
    *
    * **When to use**
    *
-   * Use to replace the current value with a known value and publish it.
+   * Use to replace the current `TxSubscriptionRef` value with a known value and
+   * publish it.
    *
    * **Example** (Setting a new value)
    *
@@ -391,7 +394,8 @@ export const set: {
  *
  * **When to use**
  *
- * Use to derive the next value from the current value and publish it.
+ * Use to derive the next `TxSubscriptionRef` value from the current value and
+ * publish it.
  *
  * **Example** (Updating a value)
  *
@@ -418,7 +422,8 @@ export const update: {
    *
    * **When to use**
    *
-   * Use to derive the next value from the current value and publish it.
+   * Use to derive the next `TxSubscriptionRef` value from the current value and
+   * publish it.
    *
    * **Example** (Updating a value)
    *
@@ -445,7 +450,8 @@ export const update: {
    *
    * **When to use**
    *
-   * Use to derive the next value from the current value and publish it.
+   * Use to derive the next `TxSubscriptionRef` value from the current value and
+   * publish it.
    *
    * **Example** (Updating a value)
    *
@@ -478,7 +484,8 @@ export const update: {
  *
  * **When to use**
  *
- * Use to replace the value while returning the previous value.
+ * Use to replace a `TxSubscriptionRef` value while returning the previous value
+ * and publishing the update to subscribers.
  *
  * **Example** (Getting and setting atomically)
  *
@@ -506,7 +513,8 @@ export const getAndSet: {
    *
    * **When to use**
    *
-   * Use to replace the value while returning the previous value.
+   * Use to replace a `TxSubscriptionRef` value while returning the previous value
+   * and publishing the update to subscribers.
    *
    * **Example** (Getting and setting atomically)
    *
@@ -534,7 +542,8 @@ export const getAndSet: {
    *
    * **When to use**
    *
-   * Use to replace the value while returning the previous value.
+   * Use to replace a `TxSubscriptionRef` value while returning the previous value
+   * and publishing the update to subscribers.
    *
    * **Example** (Getting and setting atomically)
    *
@@ -567,7 +576,8 @@ export const getAndSet: {
  *
  * **When to use**
  *
- * Use to derive and publish a new value while returning the previous value.
+ * Use to derive and publish a new `TxSubscriptionRef` value while returning the
+ * previous value.
  *
  * **Example** (Getting and updating atomically)
  *
@@ -595,7 +605,8 @@ export const getAndUpdate: {
    *
    * **When to use**
    *
-   * Use to derive and publish a new value while returning the previous value.
+   * Use to derive and publish a new `TxSubscriptionRef` value while returning the
+   * previous value.
    *
    * **Example** (Getting and updating atomically)
    *
@@ -623,7 +634,8 @@ export const getAndUpdate: {
    *
    * **When to use**
    *
-   * Use to derive and publish a new value while returning the previous value.
+   * Use to derive and publish a new `TxSubscriptionRef` value while returning the
+   * previous value.
    *
    * **Example** (Getting and updating atomically)
    *
@@ -657,7 +669,8 @@ export const getAndUpdate: {
  *
  * **When to use**
  *
- * Use to derive and publish a new value while returning that new value.
+ * Use to derive and publish a new `TxSubscriptionRef` value while returning
+ * that new value.
  *
  * **Example** (Updating and reading atomically)
  *
@@ -684,7 +697,8 @@ export const updateAndGet: {
    *
    * **When to use**
    *
-   * Use to derive and publish a new value while returning that new value.
+   * Use to derive and publish a new `TxSubscriptionRef` value while returning
+   * that new value.
    *
    * **Example** (Updating and reading atomically)
    *
@@ -711,7 +725,8 @@ export const updateAndGet: {
    *
    * **When to use**
    *
-   * Use to derive and publish a new value while returning that new value.
+   * Use to derive and publish a new `TxSubscriptionRef` value while returning
+   * that new value.
    *
    * **Example** (Updating and reading atomically)
    *
@@ -751,7 +766,8 @@ export const updateAndGet: {
  *
  * **When to use**
  *
- * Use to subscribe to committed changes through a scoped transactional queue.
+ * Use to subscribe to `TxSubscriptionRef` committed changes through a scoped
+ * transactional queue.
  *
  * **Example** (Subscribing to changes)
  *
@@ -801,7 +817,7 @@ export const changes = <A>(
  *
  * **When to use**
  *
- * Use to consume committed changes as a `Stream`.
+ * Use to consume `TxSubscriptionRef` committed changes as a `Stream`.
  *
  * **Example** (Streaming changes)
  *

package/src/Types.ts

@@ -43,8 +43,6 @@
  *
  * - {@link TupleOf} with a non-literal `number` (e.g. `TupleOf<number, string>`)
  *   degrades to `Array<string>`.
- * - {@link MergeRecord} is an alias for {@link MergeLeft}; prefer
- *   {@link MergeLeft} or {@link MergeRight} for clarity.
  * - {@link NoInfer} uses the `[A][A extends any ? 0 : never]` trick, not the
  *   built-in `NoInfer` from TypeScript 5.4+.
  * - {@link DeepMutable} recurses into `Map`, `Set`, arrays, and objects but
@@ -168,7 +166,8 @@ export type Tags<E> = E extends { readonly _tag: string } ? E["_tag"] : never
  *
  * **When to use**
  *
- * Use to narrow a union by removing a specific variant.
+ * Use to remove tagged-union members whose `_tag` matches a specific value in
+ * type-level code.
  *
  * **Details**
  *
@@ -201,7 +200,8 @@ export type ExcludeTag<E, K extends string> = Exclude<E, { readonly _tag: K }>
  *
  * **When to use**
  *
- * Use to narrow a union down to a single variant.
+ * Use to select tagged-union members whose `_tag` matches a specific value in
+ * type-level code.
  *
  * **Details**
  *
@@ -358,7 +358,8 @@ export type EqualsWith<A, B, Y, N> = (<T>() => T extends A ? 1 : 2) extends (<T>
  *
  * **When to use**
  *
- * Use to conditionally branch based on the presence of keys in a type.
+ * Use to branch type-level logic when at least one key from a candidate key set
+ * exists on an object type.
  *
  * **Details**
  *
@@ -406,7 +407,6 @@ export type Has<A, Key extends string> = (Key extends infer K ? K extends keyof
  * ```
  *
  * @see {@link MergeRight}
- * @see {@link MergeRecord}
  * @see {@link Simplify}
  *
  * @category models
@@ -451,35 +451,6 @@ export type MergeRight<Target, Source> = Simplify<
   }
 >
 
-/**
- * Alias for {@link MergeLeft}. Merges two object types where keys from
- * `Source` take precedence on conflict.
- *
- * **When to use**
- *
- * Use when prefer {@link MergeLeft} or {@link MergeRight} for clarity about which
- * side wins.
- *
- * **Example** (Merging records)
- *
- * ```ts
- * import type { Types } from "effect"
- *
- * type Result = Types.MergeRecord<
- *   { a: number; b: number },
- *   { a: string; c: boolean }
- * >
- * // { a: number; b: number; c: boolean }
- * ```
- *
- * @see {@link MergeLeft}
- * @see {@link MergeRight}
- *
- * @category models
- * @since 2.0.0
- */
-export type MergeRecord<Source, Target> = MergeLeft<Source, Target>
-
 /**
  * Describes the concurrency level for Effect operations that run multiple
  * effects.
@@ -963,8 +934,8 @@ export type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true
  *
  * **When to use**
  *
- * Use with the nested error pattern where errors wrap sub-errors in a `reason`
- * field.
+ * Use when an error type stores nested sub-errors in a `reason` field and you
+ * need that field's full union type as a standalone type.
  *
  * **Details**
  *
@@ -1033,7 +1004,8 @@ export type ReasonTags<E> = E extends { readonly reason: { readonly _tag: string
  *
  * **When to use**
  *
- * Use to extract only the matching reason variant from a nested error type.
+ * Use when you need the nested reason variant type itself, selected by `_tag`,
+ * rather than the enclosing error type.
  *
  * **Details**
  *
@@ -1147,7 +1119,8 @@ export type OmitReason<E, K extends string> = E extends { readonly reason: infer
  *
  * **When to use**
  *
- * Use to remove a handled reason variant from an error's reason union.
+ * Use when you need the remaining nested reason union type after removing
+ * variants handled by `_tag`, rather than the enclosing error type.
  *
  * **Details**
  *

package/src/UndefinedOr.ts

@@ -179,8 +179,8 @@ export const match: {
  *
  * **When to use**
  *
- * Use when fail-fast unwrapping of an `A | undefined` value is appropriate and
- * callers need to provide the thrown error for the undefined case.
+ * Use when you need fail-fast unwrapping of an `A | undefined` value and want
+ * to provide the thrown error for the undefined case.
  *
  * **Details**
  *
@@ -200,8 +200,8 @@ export const getOrThrowWith: {
    *
    * **When to use**
    *
-   * Use when fail-fast unwrapping of an `A | undefined` value is appropriate and
-   * callers need to provide the thrown error for the undefined case.
+   * Use when you need fail-fast unwrapping of an `A | undefined` value and want
+   * to provide the thrown error for the undefined case.
    *
    * **Details**
    *
@@ -221,8 +221,8 @@ export const getOrThrowWith: {
    *
    * **When to use**
    *
-   * Use when fail-fast unwrapping of an `A | undefined` value is appropriate and
-   * callers need to provide the thrown error for the undefined case.
+   * Use when you need fail-fast unwrapping of an `A | undefined` value and want
+   * to provide the thrown error for the undefined case.
    *
    * **Details**
    *
@@ -249,7 +249,7 @@ export const getOrThrowWith: {
  *
  * **When to use**
  *
- * Use when a value should already be defined at this point and throwing a
+ * Use when you need to unwrap a value that should already be defined and a
  * generic missing-value `Error` is acceptable.
  *
  * **Details**
@@ -301,16 +301,17 @@ export const liftThrowable = <A extends ReadonlyArray<unknown>, B>(
  *
  * **When to use**
  *
- * Use to take the first available value like a fallback chain, combining values
- * only when both operands are present.
+ * Use when you need to reduce values that may be `undefined`, keeping the
+ * first defined value as a fallback and combining only when both operands are
+ * defined.
  *
  * **Details**
  *
- * - `undefined` + `undefined` -> `undefined`
- * - `a` + `undefined` -> `a` (first value wins)
- * - `undefined` + `b` -> `b` (second value wins)
- * - `a` + `b` -> `combiner.combine(a, b)`
- * - Initial value is `undefined`
+ * Combining `undefined` with `undefined` returns `undefined`. Combining a
+ * defined value with `undefined` keeps the defined value, so the first defined
+ * value wins when only one side is present. When both values are defined, they
+ * are combined with `combiner.combine`. The reducer's initial value is
+ * `undefined`.
  *
  * @category constructors
  * @since 4.0.0

package/src/Unify.ts

@@ -79,8 +79,8 @@ export type unifySymbol = typeof unifySymbol
  *
  * **When to use**
  *
- * Use with `unifySymbol` to expose the source type that unification should read
- * from a protocol-enabled data type.
+ * Use when you need a type-level protocol key that exposes the source type
+ * read by `Unify` from a protocol-enabled data type.
  *
  * **Details**
  *

package/src/internal/schema/annotations.ts

@@ -1,15 +1,15 @@
 import { memoize } from "../../Function.ts"
 import type * as Schema from "../../Schema.ts"
-import type * as AST from "../../SchemaAST.ts"
+import type * as SchemaAST from "../../SchemaAST.ts"
 
 /** @internal */
-export function resolve(ast: AST.AST): Schema.Annotations.Annotations | undefined {
+export function resolve(ast: SchemaAST.AST): Schema.Annotations.Annotations | undefined {
   return ast.checks ? ast.checks[ast.checks.length - 1].annotations : ast.annotations
 }
 
 /** @internal */
 export function resolveAt<A>(key: string) {
-  return (ast: AST.AST): A | undefined => resolve(ast)?.[key] as A | undefined
+  return (ast: SchemaAST.AST): A | undefined => resolve(ast)?.[key] as A | undefined
 }
 
 /** @internal */
@@ -25,7 +25,7 @@ export const resolveDescription = resolveAt<string>("description")
 export const resolveBrands = resolveAt<ReadonlyArray<string>>("brands")
 
 /** @internal */
-export const getExpected = memoize((ast: AST.AST): string => {
+export const getExpected = memoize((ast: SchemaAST.AST): string => {
   const identifier = resolveIdentifier(ast)
   if (typeof identifier === "string") return identifier
   return ast.getExpected(getExpected)