@typed/fx 2.0.0-beta.1 → 2.0.0-beta.11

package/dist/RefSubject/RefCause.js

@@ -10,10 +10,21 @@ import * as RefSubject from "./RefSubject.js";
 /**
  * Creates a new `RefCause` from a Cause, `Effect`, or `Fx`.
  *
+ * @remarks
+ * ## Why
+ *
+ * Creates cause state with equality suited to that Effect data type, so unchanged values do not
+ * produce redundant pushed updates.
+ *
+ * ## Ownership and lifetime
+ *
+ * The creation Effect requires Scope. It owns initializer acquisition, live source subscriptions,
+ * and cleanup; source failures and services stay on reads and pushes.
+ *
  * @example
  * ```ts
  * import { Effect, Cause } from "effect"
- * import * as RefCause from "effect/typed/fx/RefSubject/RefCause"
+ * import * as RefCause from "@typed/fx/RefCause"
  *
  * const program = Effect.gen(function* () {
  *   const value = yield* RefCause.make(Cause.fail("error"))
@@ -23,31 +34,64 @@ import * as RefSubject from "./RefSubject.js";
  * ```
  *
  * @since 1.18.0
- * @category constructors
+ * @category Constructors
  */
 export function make(initial, eq = equals) {
     return RefSubject.make(initial, { eq: Equivalence_.make(eq) });
 }
 /**
  * Set the current state of a RefCause to a Fail cause.
+ * @remarks
+ * ## Why
+ *
+ * Keeps set fail atomic with respect to competing RefSubject writes instead of splitting the read
+ * and replacement into separate effects.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running set fail performs one serialized cause transition and resolves with its committed value.
+ * It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const setFail = dual(2, function setFail(ref, error) {
     return RefSubject.set(ref, Cause.fail(error));
 });
 /**
  * Set the current state of a RefCause to a Die cause.
+ * @remarks
+ * ## Why
+ *
+ * Keeps set die atomic with respect to competing RefSubject writes instead of splitting the read
+ * and replacement into separate effects.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running set die performs one serialized cause transition and resolves with its committed value.
+ * It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const setDie = dual(2, function setDie(ref, defect) {
     return RefSubject.set(ref, Cause.die(defect));
 });
 /**
  * Set the current state of a RefCause to an Interrupt cause.
+ * @remarks
+ * ## Why
+ *
+ * Keeps set interrupt atomic with respect to competing RefSubject writes instead of splitting the
+ * read and replacement into separate effects.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running set interrupt performs one serialized cause transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const setInterrupt = dual(2, function setInterrupt(ref, fiberId) {
     return RefSubject.set(ref, Cause.interrupt(fiberId));
@@ -57,37 +101,103 @@ export const setInterrupt = dual(2, function setInterrupt(ref, fiberId) {
 // ========================================
 /**
  * Check if the current state of a RefCause has a Fail.
+ * @remarks
+ * ## Why
+ *
+ * Makes has fails a live projection of the cause; consumers can sample it now or observe it
+ * without copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The has fails view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category State predicates
  */
 export const hasFails = (ref) => RefSubject.map(ref, Cause.hasFails);
 /**
  * Check if the current state of a RefCause has a Die.
+ * @remarks
+ * ## Why
+ *
+ * Makes has dies a live projection of the cause; consumers can sample it now or observe it without
+ * copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The has dies view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category State predicates
  */
 export const hasDies = (ref) => RefSubject.map(ref, Cause.hasDies);
 /**
  * Check if the current state of a RefCause has an Interrupt.
+ * @remarks
+ * ## Why
+ *
+ * Makes has interrupts a live projection of the cause; consumers can sample it now or observe it
+ * without copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The has interrupts view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category State predicates
  */
 export const hasInterrupts = (ref) => RefSubject.map(ref, Cause.hasInterrupts);
 /**
  * Check if the current state of a RefCause is empty.
+ * @remarks
+ * ## Why
+ *
+ * Makes is empty a live projection of the cause; consumers can sample it now or observe it without
+ * copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The is empty view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category State predicates
  */
 export const isEmpty = (ref) => RefSubject.map(ref, (self) => self.reasons.length === 0);
 /**
  * Get the size (number of failures) of the current state of a RefCause.
+ * @remarks
+ * ## Why
+ *
+ * Makes size a live projection of the cause; consumers can sample it now or observe it without
+ * copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The size view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category Derived queries
  */
 export const size = (ref) => RefSubject.map(ref, (self) => self.reasons.length);
 /**
  * Get the reasons array of the current state of a RefCause.
+ * @remarks
+ * ## Why
+ *
+ * Get the reasons array of the current state of a RefCause. The operation remains attached to the
+ * RefSubject's versioned state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * The reasons view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category Derived queries
  */
 export const reasons = (ref) => RefSubject.map(ref, (self) => self.reasons);