effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/unstable/reactivity/Atom.ts

@@ -1644,10 +1644,11 @@ export const keepAlive = <A extends Atom<any>>(self: A): A =>
   })
 
 /**
- * Reverts the `keepAlive` behavior of a reactive value, allowing it to be
- * disposed of when not in use.
+ * Reverts the `keepAlive` behavior of a reactive value, allowing it to be disposed of when not in use.
  *
- * Note that Atom's have this behavior by default.
+ * **Details**
+ *
+ * Atoms have this behavior by default, so use this to undo `keepAlive` on a copied atom.
  *
  * @category combinators
  * @since 4.0.0
@@ -1661,6 +1662,8 @@ export const autoDispose = <A extends Atom<any>>(self: A): A =>
 /**
  * Sets whether an atom should be lazy.
  *
+ * **Details**
+ *
  * Lazy atoms defer recomputation while they have no active listeners or active
  * non-lazy dependents, rebuilding the next time their value is observed.
  *
@@ -1671,6 +1674,8 @@ export const setLazy: {
   /**
    * Sets whether an atom should be lazy.
    *
+   * **Details**
+   *
    * Lazy atoms defer recomputation while they have no active listeners or active
    * non-lazy dependents, rebuilding the next time their value is observed.
    *
@@ -1681,6 +1686,8 @@ export const setLazy: {
   /**
    * Sets whether an atom should be lazy.
    *
+   * **Details**
+   *
    * Lazy atoms defer recomputation while they have no active listeners or active
    * non-lazy dependents, rebuilding the next time their value is observed.
    *
@@ -1697,6 +1704,8 @@ export const setLazy: {
 /**
  * Attaches a diagnostic label to an atom.
  *
+ * **Details**
+ *
  * The label is used for inspection and debugging metadata and does not change the
  * atom's read or write behavior.
  *
@@ -1707,6 +1716,8 @@ export const withLabel: {
   /**
    * Attaches a diagnostic label to an atom.
    *
+   * **Details**
+   *
    * The label is used for inspection and debugging metadata and does not change the
    * atom's read or write behavior.
    *
@@ -1717,6 +1728,8 @@ export const withLabel: {
   /**
    * Attaches a diagnostic label to an atom.
    *
+   * **Details**
+   *
    * The label is used for inspection and debugging metadata and does not change the
    * atom's read or write behavior.
    *
@@ -1728,6 +1741,8 @@ export const withLabel: {
   /**
    * Attaches a diagnostic label to an atom.
    *
+   * **Details**
+   *
    * The label is used for inspection and debugging metadata and does not change the
    * atom's read or write behavior.
    *
@@ -1738,6 +1753,8 @@ export const withLabel: {
   /**
    * Attaches a diagnostic label to an atom.
    *
+   * **Details**
+   *
    * The label is used for inspection and debugging metadata and does not change the
    * atom's read or write behavior.
    *
@@ -1754,6 +1771,8 @@ export const withLabel: {
 /**
  * Pairs an atom with an initial value for registry initialization.
  *
+ * **Details**
+ *
  * The returned tuple can be supplied to `AtomRegistry` initial values so the atom
  * starts with the provided value before it is first rebuilt.
  *
@@ -1764,6 +1783,8 @@ export const initialValue: {
   /**
    * Pairs an atom with an initial value for registry initialization.
    *
+   * **Details**
+   *
    * The returned tuple can be supplied to `AtomRegistry` initial values so the atom
    * starts with the provided value before it is first rebuilt.
    *
@@ -1774,6 +1795,8 @@ export const initialValue: {
   /**
    * Pairs an atom with an initial value for registry initialization.
    *
+   * **Details**
+   *
    * The returned tuple can be supplied to `AtomRegistry` initial values so the atom
    * starts with the provided value before it is first rebuilt.
    *
@@ -1785,6 +1808,8 @@ export const initialValue: {
   /**
    * Pairs an atom with an initial value for registry initialization.
    *
+   * **Details**
+   *
    * The returned tuple can be supplied to `AtomRegistry` initial values so the atom
    * starts with the provided value before it is first rebuilt.
    *
@@ -1795,6 +1820,8 @@ export const initialValue: {
   /**
    * Pairs an atom with an initial value for registry initialization.
    *
+   * **Details**
+   *
    * The returned tuple can be supplied to `AtomRegistry` initial values so the atom
    * starts with the provided value before it is first rebuilt.
    *
@@ -1808,6 +1835,8 @@ export const initialValue: {
  * Creates a derived atom by reading another atom with a custom `AtomContext`
  * function.
  *
+ * **Details**
+ *
  * If the source is writable, the derived atom keeps the source write input and
  * forwards writes to the source. `initialValueTarget` controls which atom receives
  * preloaded initial values for the derived atom.
@@ -1820,6 +1849,8 @@ export const transform: {
    * Creates a derived atom by reading another atom with a custom `AtomContext`
    * function.
    *
+   * **Details**
+   *
    * If the source is writable, the derived atom keeps the source write input and
    * forwards writes to the source. `initialValueTarget` controls which atom receives
    * preloaded initial values for the derived atom.
@@ -1837,6 +1868,8 @@ export const transform: {
    * Creates a derived atom by reading another atom with a custom `AtomContext`
    * function.
    *
+   * **Details**
+   *
    * If the source is writable, the derived atom keeps the source write input and
    * forwards writes to the source. `initialValueTarget` controls which atom receives
    * preloaded initial values for the derived atom.
@@ -1898,6 +1931,8 @@ const getInitialValueTarget = <A>(atom: Atom<A>): Atom<A> => {
 /**
  * Maps the current value of an atom with a pure function.
  *
+ * **Details**
+ *
  * When the source atom is writable, the returned atom remains writable and keeps
  * the source atom's write input type.
  *
@@ -1908,6 +1943,8 @@ export const map: {
   /**
    * Maps the current value of an atom with a pure function.
    *
+   * **Details**
+   *
    * When the source atom is writable, the returned atom remains writable and keeps
    * the source atom's write input type.
    *
@@ -1918,6 +1955,8 @@ export const map: {
   /**
    * Maps the current value of an atom with a pure function.
    *
+   * **Details**
+   *
    * When the source atom is writable, the returned atom remains writable and keeps
    * the source atom's write input type.
    *
@@ -1933,6 +1972,8 @@ export const map: {
 /**
  * Maps the successful value inside an `AsyncResult` atom.
  *
+ * **Details**
+ *
  * Initial and failure states are preserved, and writable source atoms keep their
  * original write input type.
  *
@@ -1943,6 +1984,8 @@ export const mapResult: {
   /**
    * Maps the successful value inside an `AsyncResult` atom.
    *
+   * **Details**
+   *
    * Initial and failure states are preserved, and writable source atoms keep their
    * original write input type.
    *
@@ -1957,6 +2000,8 @@ export const mapResult: {
   /**
    * Maps the successful value inside an `AsyncResult` atom.
    *
+   * **Details**
+   *
    * Initial and failure states are preserved, and writable source atoms keep their
    * original write input type.
    *
@@ -1977,6 +2022,8 @@ export const mapResult: {
  * Creates an atom that publishes source changes only after the source has stopped
  * changing for the specified duration.
  *
+ * **Details**
+ *
  * The current source value is used immediately, and any pending debounce timer is
  * cleared when the derived atom is disposed.
  *
@@ -1988,6 +2035,8 @@ export const debounce: {
    * Creates an atom that publishes source changes only after the source has stopped
    * changing for the specified duration.
    *
+   * **Details**
+   *
    * The current source value is used immediately, and any pending debounce timer is
    * cleared when the derived atom is disposed.
    *
@@ -1999,6 +2048,8 @@ export const debounce: {
    * Creates an atom that publishes source changes only after the source has stopped
    * changing for the specified duration.
    *
+   * **Details**
+   *
    * The current source value is used immediately, and any pending debounce timer is
    * cleared when the derived atom is disposed.
    *
@@ -2034,6 +2085,8 @@ export const debounce: {
  * Creates a derived atom that reads the source and schedules a refresh after the
  * specified duration.
  *
+ * **Details**
+ *
  * The scheduled refresh is canceled when the derived atom's lifetime is disposed.
  *
  * @category combinators
@@ -2044,6 +2097,8 @@ export const withRefresh: {
    * Creates a derived atom that reads the source and schedules a refresh after the
    * specified duration.
    *
+   * **Details**
+   *
    * The scheduled refresh is canceled when the derived atom's lifetime is disposed.
    *
    * @category combinators
@@ -2054,6 +2109,8 @@ export const withRefresh: {
    * Creates a derived atom that reads the source and schedules a refresh after the
    * specified duration.
    *
+   * **Details**
+   *
    * The scheduled refresh is canceled when the derived atom's lifetime is disposed.
    *
    * @category combinators
@@ -2075,11 +2132,11 @@ export const withRefresh: {
 /**
  * Adds stale-while-revalidate refresh behavior to an async result atom.
  *
+ * **Details**
+ *
  * Automatic revalidation during reads is skipped while the current value is
  * fresh within `staleTime`. Manual `refresh` calls remain forceful and always
- * forward to the wrapped atom.
- *
- * Use `revalidateOnMount` to control whether stale data should trigger a
+ * forward to the wrapped atom. Use `revalidateOnMount` to control whether stale data should trigger a
  * background refresh on first mount. Use `revalidateOnFocus` to control
  * focus behavior. `true` respects `staleTime` and `"always"` forces refetch.
  *
@@ -2090,11 +2147,11 @@ export const swr: {
   /**
    * Adds stale-while-revalidate refresh behavior to an async result atom.
    *
+   * **Details**
+   *
    * Automatic revalidation during reads is skipped while the current value is
    * fresh within `staleTime`. Manual `refresh` calls remain forceful and always
-   * forward to the wrapped atom.
-   *
-   * Use `revalidateOnMount` to control whether stale data should trigger a
+   * forward to the wrapped atom. Use `revalidateOnMount` to control whether stale data should trigger a
    * background refresh on first mount. Use `revalidateOnFocus` to control
    * focus behavior. `true` respects `staleTime` and `"always"` forces refetch.
    *
@@ -2112,11 +2169,11 @@ export const swr: {
   /**
    * Adds stale-while-revalidate refresh behavior to an async result atom.
    *
+   * **Details**
+   *
    * Automatic revalidation during reads is skipped while the current value is
    * fresh within `staleTime`. Manual `refresh` calls remain forceful and always
-   * forward to the wrapped atom.
-   *
-   * Use `revalidateOnMount` to control whether stale data should trigger a
+   * forward to the wrapped atom. Use `revalidateOnMount` to control whether stale data should trigger a
    * background refresh on first mount. Use `revalidateOnFocus` to control
    * focus behavior. `true` respects `staleTime` and `"always"` forces refetch.
    *
@@ -2199,6 +2256,8 @@ const shouldRevalidateSWR = <A, E>(result: AsyncResult.AsyncResult<A, E>, staleT
 /**
  * Wraps an atom in a writable optimistic atom.
  *
+ * **Details**
+ *
  * Writes accept transition atoms containing `AsyncResult` values. Waiting
  * successes are shown optimistically while transitions run; when successful
  * transitions finish, the source atom is refreshed, and failures roll the value
@@ -2301,6 +2360,8 @@ export const optimistic = <A>(self: Atom<A>): Writable<A, Atom<AsyncResult.Async
  * Creates an `AtomResultFn` that applies an optimistic update before running the
  * underlying mutation.
  *
+ * **Details**
+ *
  * The reducer computes the provisional value from the current value and mutation
  * input. The wrapped function result then completes the transition or updates the
  * optimistic value through the provided setter callback.
@@ -2313,6 +2374,8 @@ export const optimisticFn: {
    * Creates an `AtomResultFn` that applies an optimistic update before running the
    * underlying mutation.
    *
+   * **Details**
+   *
    * The reducer computes the provisional value from the current value and mutation
    * input. The wrapped function result then completes the transition or updates the
    * optimistic value through the provided setter callback.
@@ -2334,6 +2397,8 @@ export const optimisticFn: {
    * Creates an `AtomResultFn` that applies an optimistic update before running the
    * underlying mutation.
    *
+   * **Details**
+   *
    * The reducer computes the provisional value from the current value and mutation
    * input. The wrapped function result then completes the transition or updates the
    * optimistic value through the provided setter callback.
@@ -2363,6 +2428,8 @@ export const optimisticFn: {
    * Creates an `AtomResultFn` that applies an optimistic update before running the
    * underlying mutation.
    *
+   * **Details**
+   *
    * The reducer computes the provisional value from the current value and mutation
    * input. The wrapped function result then completes the transition or updates the
    * optimistic value through the provided setter callback.
@@ -2391,6 +2458,8 @@ export const optimisticFn: {
      * Creates an `AtomResultFn` that applies an optimistic update before running the
      * underlying mutation.
      *
+     * **Details**
+     *
      * The reducer computes the provisional value from the current value and mutation
      * input. The wrapped function result then completes the transition or updates the
      * optimistic value through the provided setter callback.
@@ -2402,6 +2471,8 @@ export const optimisticFn: {
      * Creates an `AtomResultFn` that applies an optimistic update before running the
      * underlying mutation.
      *
+     * **Details**
+     *
      * The reducer computes the provisional value from the current value and mutation
      * input. The wrapped function result then completes the transition or updates the
      * optimistic value through the provided setter callback.
@@ -2422,6 +2493,8 @@ export const optimisticFn: {
 /**
  * Runs synchronous atom updates as a batch.
  *
+ * **Details**
+ *
  * Stale nodes are rebuilt and listeners are notified after the callback completes,
  * so dependent updates observe the final batched state.
  *
@@ -2437,6 +2510,8 @@ export const batch: (f: () => void) => void = Registry.batch
 /**
  * A browser-only signal atom that increments when the document becomes visible.
  *
+ * **Details**
+ *
  * It listens for `visibilitychange` events on `window` and removes the listener
  * when the atom is disposed.
  *
@@ -2461,6 +2536,8 @@ export const windowFocusSignal: Atom<number> = readable((get) => {
  * Creates a combinator that refreshes an atom whenever the supplied signal atom
  * changes.
  *
+ * **Details**
+ *
  * The derived atom also subscribes to the source atom so normal source updates are
  * forwarded to its own value.
  *
@@ -2478,6 +2555,8 @@ export const makeRefreshOnSignal = <_>(signal: Atom<_>) => <A extends Atom<any>>
 /**
  * Refreshes an atom whenever `windowFocusSignal` changes.
  *
+ * **Details**
+ *
  * This helper is browser-only because `windowFocusSignal` depends on `window` and
  * `document.visibilityState`.
  *
@@ -2495,6 +2574,8 @@ export const refreshOnWindowFocus: <A extends Atom<any>>(self: A) => WithoutSeri
 /**
  * Creates a writable atom backed by a `KeyValueStore` entry.
  *
+ * **Details**
+ *
  * Values are encoded and decoded with the supplied schema. In sync mode the atom
  * exposes the decoded value and writes the default value when the key is missing;
  * in async mode it exposes an `AsyncResult` of the decoded value.
@@ -2558,9 +2639,11 @@ export const kvs = <S extends Schema.Codec<any, any>, const Mode extends "sync"
 // -----------------------------------------------------------------------------
 
 /**
- * Create an Atom that reads and writes a URL search parameter.
+ * Creates an atom that reads and writes a URL search parameter.
  *
- * Note: If you pass a schema, it has to be synchronous and have no context.
+ * **Gotchas**
+ *
+ * If you pass a schema, it has to be synchronous and have no context.
  *
  * @category URL search params
  * @since 4.0.0
@@ -2646,6 +2729,8 @@ function updateSearchParams() {
 /**
  * Converts an atom into a stream using the `AtomRegistry` service.
  *
+ * **Details**
+ *
  * The stream emits the atom's current value immediately and then emits subsequent
  * changes until the stream scope is closed.
  *
@@ -2658,6 +2743,8 @@ export const toStream = <A>(self: Atom<A>): Stream.Stream<A, never, AtomRegistry
 /**
  * Converts an `AsyncResult` atom into a stream using the `AtomRegistry` service.
  *
+ * **Details**
+ *
  * Initial results are skipped, successes are emitted as stream values, and
  * failures fail the stream with the result cause.
  *
@@ -2766,6 +2853,8 @@ export const update: {
 /**
  * Reads an `AsyncResult` atom as an effect through the `AtomRegistry` service.
  *
+ * **Details**
+ *
  * The effect waits while the result is `Initial`, and also while it is waiting
  * when `suspendOnWaiting` is enabled. Successes succeed with the value and
  * failures fail with the result cause.
@@ -2790,6 +2879,8 @@ export const refresh = <A>(self: Atom<A>): Effect.Effect<void, never, AtomRegist
 /**
  * Mounts an atom in the `AtomRegistry` for the lifetime of the current scope.
  *
+ * **Details**
+ *
  * Mounting keeps the atom subscribed with a no-op listener until the scope
  * finalizer releases it.
  *
@@ -2822,6 +2913,8 @@ export type SerializableTypeId = "~effect-atom/atom/Atom/Serializable"
 /**
  * Serialization metadata attached to an atom.
  *
+ * **Details**
+ *
  * The key identifies the atom in dehydrated state, and the encode/decode
  * functions convert between the atom value and the schema encoded value.
  *
@@ -2847,6 +2940,8 @@ export const isSerializable = (self: Atom<any>): self is Atom<any> & Serializabl
 /**
  * Attaches serialization metadata to an atom using a schema and stable key.
  *
+ * **Details**
+ *
  * The schema is converted to a JSON codec for synchronous encode/decode, and the
  * key is also used as the atom label when the atom does not already have one.
  *
@@ -2857,6 +2952,8 @@ export const serializable: {
   /**
    * Attaches serialization metadata to an atom using a schema and stable key.
    *
+   * **Details**
+   *
    * The schema is converted to a JSON codec for synchronous encode/decode, and the
    * key is also used as the atom label when the atom does not already have one.
    *
@@ -2872,6 +2969,8 @@ export const serializable: {
   /**
    * Attaches serialization metadata to an atom using a schema and stable key.
    *
+   * **Details**
+   *
    * The schema is converted to a JSON codec for synchronous encode/decode, and the
    * key is also used as the atom label when the atom does not already have one.
    *
@@ -2953,6 +3052,8 @@ export const withServerValueInitial = <A extends Atom<AsyncResult.AsyncResult<an
  * Reads an atom from a registry, using its server-side read override when one is
  * present.
  *
+ * **Details**
+ *
  * Nested reads performed by the override are resolved against the same registry.
  *
  * @category ServerValue
@@ -2963,6 +3064,8 @@ export const getServerValue: {
    * Reads an atom from a registry, using its server-side read override when one is
    * present.
    *
+   * **Details**
+   *
    * Nested reads performed by the override are resolved against the same registry.
    *
    * @category ServerValue
@@ -2973,6 +3076,8 @@ export const getServerValue: {
    * Reads an atom from a registry, using its server-side read override when one is
    * present.
    *
+   * **Details**
+   *
    * Nested reads performed by the override are resolved against the same registry.
    *
    * @category ServerValue

package/src/unstable/reactivity/AtomHttpApi.ts

@@ -51,6 +51,8 @@ import * as Reactivity from "./Reactivity.ts"
 /**
  * A `Context.Service` for an HTTP API client integrated with atom reactivity.
  *
+ * **Details**
+ *
  * It exposes the generated HTTP API client, an atom runtime, mutation helpers that
  * return `AtomResultFn`s, and query helpers that return atoms of endpoint results.
  *
@@ -174,6 +176,8 @@ declare global {
  * Creates a `Context.Service` class for an HTTP API client backed by an atom
  * runtime.
  *
+ * **Details**
+ *
  * The options provide the API definition, HTTP client layer, optional client and
  * response transforms, base URL, and runtime factory used by the query and
  * mutation helpers.

package/src/unstable/reactivity/AtomRef.ts

@@ -40,6 +40,8 @@ export const TypeId: TypeId = "~effect/reactivity/AtomRef"
 /**
  * A read-only reactive reference.
  *
+ * **Details**
+ *
  * It exposes a stable key, the current value, subscriptions to value changes, and
  * `map` for creating derived read-only references. Equality and hashing are based
  * on the current value.
@@ -58,6 +60,8 @@ export interface ReadonlyRef<A> extends Equal.Equal {
 /**
  * A mutable reactive reference.
  *
+ * **Details**
+ *
  * It supports replacing the whole value, updating it from the current value, and
  * creating mutable references to nested properties.
  *
@@ -73,6 +77,8 @@ export interface AtomRef<A> extends ReadonlyRef<A> {
 /**
  * A reactive collection of mutable item references.
  *
+ * **Details**
+ *
  * The collection can push, insert, and remove item refs, and `toArray` returns the
  * current raw item values.
  *
@@ -97,6 +103,8 @@ export const make = <A>(value: A): AtomRef<A> => new AtomRefImpl(value)
 /**
  * Creates a reactive collection from an iterable of initial item values.
  *
+ * **Details**
+ *
  * Each item is wrapped in an `AtomRef`, and changes to item refs notify the
  * collection subscribers.
  *