effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/unstable/reactivity/Atom.ts

@@ -1,26 +1,40 @@
 /**
- * The `Atom` module defines reactive values and the helpers for constructing,
- * composing, running, and persisting them with an `AtomRegistry`. Atoms are
- * small read functions whose regular `get` reads form a dependency graph, so
- * derived values are cached by the registry and invalidated when their
- * dependencies, writable state, refresh hooks, or subscriptions change.
- *
- * Use atoms for application and UI state, derived data, `Effect` or `Stream`
- * queries exposed as `AsyncResult`, writable function atoms for commands,
- * subscription refs, pull-based streams, optimistic updates, URL search
- * parameters, `KeyValueStore` entries, and serializable or server-specific
- * hydration.
- *
- * The cache belongs to the registry, not the atom object: the same atom can have
- * different values in different registries, and serializable atoms are keyed by
- * their serialization key. Stable atom identity matters for dependency tracking
- * and cache reuse, so use `family` for parameterized atoms. Unobserved atoms are
- * disposed unless kept alive or retained by an idle TTL, which can cause derived
- * state, effects, streams, and finalizers to be rebuilt later. Runtime-backed
- * atoms run effects and streams with the registry scheduler, scope, and
- * `AtomRuntime` layer context; `runtime.withReactivity` only refreshes after
- * explicit `Reactivity` invalidations, while one-shot reads such as `once` do
- * not create dependency edges.
+ * Reactive state primitives for values evaluated by an {@link AtomRegistry}.
+ *
+ * An {@link Atom} describes how to read a value. The registry is the runtime
+ * owner: it evaluates reads, caches results, records dependency edges, runs
+ * effects and streams with the configured runtime services, and disposes nodes
+ * when they are no longer observed.
+ *
+ * **Mental model**
+ *
+ * Regular `get(atom)` calls inside a read function create dependencies. When a
+ * dependency changes or refreshes, dependent atoms are invalidated and re-read
+ * on demand. One-shot reads such as `get.once(atom)` read the current value
+ * without creating an edge. The same atom can hold different cached values in
+ * different registries, so stable atom identity matters; use {@link family} for
+ * atoms parameterized by input values.
+ *
+ * **Common tasks**
+ *
+ * Use {@link readable} or {@link writable} for synchronous state, {@link make}
+ * for effects and streams exposed as `AsyncResult`, {@link fn} for
+ * command-style effects, {@link pull} for pull-based streams, and
+ * {@link subscriptionRef} to expose a `SubscriptionRef`. Use {@link kvs},
+ * {@link searchParam}, and {@link serializable} when atom values need
+ * persistence, URL state, or server-to-client hydration. Read and mutate atoms
+ * from Effect code with {@link get}, {@link set}, {@link update},
+ * {@link refresh}, and {@link mount}; convert observed values to streams with
+ * {@link toStream} or {@link toStreamResult}.
+ *
+ * **Gotchas**
+ *
+ * Cache lifetime belongs to the registry, not the atom object. Unobserved
+ * non-`keepAlive` atoms can be disposed immediately or after their idle TTL,
+ * which also releases finalizers and may rebuild effects, streams, and derived
+ * state on the next read. Runtime-backed atoms refresh only through their
+ * registered refresh hooks or explicit `Reactivity` invalidations; reading an
+ * `Effect` by itself does not keep external data subscribed.
  *
  * @since 4.0.0
  */
@@ -903,10 +917,15 @@ export const defaultMemoMap: Layer.MemoMap = Layer.makeMemoMapUnsafe()
 export const runtime: RuntimeFactory = context({ memoMap: defaultMemoMap })
 
 /**
- * An alias to `Rx.runtime.withReactivity`, for refreshing an atom whenever the
+ * Returns `Rx.runtime.withReactivity` for refreshing an atom whenever the
  * keys change in the `Reactivity` service.
  *
- * @category Reactivity
+ * **When to use**
+ *
+ * Use to refresh an atom whenever one or more invalidation keys change in the
+ * default reactivity runtime.
+ *
+ * @category reactivity
  * @since 4.0.0
  */
 export const withReactivity: (
@@ -1223,7 +1242,12 @@ export interface AtomResultFn<Arg, A, E = never>
 {}
 
 /**
- * Control symbol that can be written to an `AtomResultFn` to reset it to its initial state.
+ * Defines the control symbol that can be written to an `AtomResultFn` to reset it to its initial state.
+ *
+ * **When to use**
+ *
+ * Use to write to an `AtomResultFn` when you need to clear the current async
+ * result and return it to the initial state.
  *
  * @category symbols
  * @since 4.0.0
@@ -1239,7 +1263,12 @@ export const Reset = Symbol.for("effect/reactivity/atom/Atom/Reset")
 export type Reset = typeof Reset
 
 /**
- * Control symbol that can be written to an `AtomResultFn` to interrupt the current asynchronous computation.
+ * Defines the control symbol that can be written to an `AtomResultFn` to interrupt the current asynchronous computation.
+ *
+ * **When to use**
+ *
+ * Use to write to an `AtomResultFn` when you need to interrupt the currently
+ * running async computation.
  *
  * @category symbols
  * @since 4.0.0
@@ -1644,7 +1673,7 @@ 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.
+ * Allows a reactive value to be disposed of when it is not in use.
  *
  * **Details**
  *
@@ -1771,6 +1800,10 @@ export const withLabel: {
 /**
  * Pairs an atom with an initial value for registry initialization.
  *
+ * **When to use**
+ *
+ * Use to preload an atom value when constructing or seeding a registry.
+ *
  * **Details**
  *
  * The returned tuple can be supplied to `AtomRegistry` initial values so the atom
@@ -1783,6 +1816,10 @@ export const initialValue: {
   /**
    * Pairs an atom with an initial value for registry initialization.
    *
+   * **When to use**
+   *
+   * Use to preload an atom value when constructing or seeding a registry.
+   *
    * **Details**
    *
    * The returned tuple can be supplied to `AtomRegistry` initial values so the atom
@@ -1795,6 +1832,10 @@ export const initialValue: {
   /**
    * Pairs an atom with an initial value for registry initialization.
    *
+   * **When to use**
+   *
+   * Use to preload an atom value when constructing or seeding a registry.
+   *
    * **Details**
    *
    * The returned tuple can be supplied to `AtomRegistry` initial values so the atom
@@ -1808,6 +1849,10 @@ export const initialValue: {
   /**
    * Pairs an atom with an initial value for registry initialization.
    *
+   * **When to use**
+   *
+   * Use to preload an atom value when constructing or seeding a registry.
+   *
    * **Details**
    *
    * The returned tuple can be supplied to `AtomRegistry` initial values so the atom
@@ -1820,6 +1865,10 @@ export const initialValue: {
   /**
    * Pairs an atom with an initial value for registry initialization.
    *
+   * **When to use**
+   *
+   * Use to preload an atom value when constructing or seeding a registry.
+   *
    * **Details**
    *
    * The returned tuple can be supplied to `AtomRegistry` initial values so the atom
@@ -2508,7 +2557,7 @@ export const batch: (f: () => void) => void = Registry.batch
 // -----------------------------------------------------------------------------
 
 /**
- * A browser-only signal atom that increments when the document becomes visible.
+ * Creates a browser-only signal atom that increments when the document becomes visible.
  *
  * **Details**
  *
@@ -2868,7 +2917,12 @@ export const getResult = <A, E>(
 ): Effect.Effect<A, E, AtomRegistry> => AtomRegistry.use(Registry.getResult(self, options))
 
 /**
- * Requests a refresh of an atom through the `AtomRegistry` service.
+ * Runs a refresh request for an atom through the `AtomRegistry` service.
+ *
+ * **When to use**
+ *
+ * Use to invalidate and recompute an atom from an Effect that has access to the
+ * active registry.
  *
  * @category converting
  * @since 4.0.0
@@ -2897,7 +2951,7 @@ export const mount = <A>(self: Atom<A>): Effect.Effect<void, never, AtomRegistry
 /**
  * The type id used to mark atoms that carry serialization metadata.
  *
- * @category Serializable
+ * @category type IDs
  * @since 4.0.0
  */
 export const SerializableTypeId: SerializableTypeId = "~effect-atom/atom/Atom/Serializable"
@@ -2905,7 +2959,7 @@ export const SerializableTypeId: SerializableTypeId = "~effect-atom/atom/Atom/Se
 /**
  * The literal type of the serializable atom marker.
  *
- * @category Serializable
+ * @category type IDs
  * @since 4.0.0
  */
 export type SerializableTypeId = "~effect-atom/atom/Atom/Serializable"
@@ -3003,27 +3057,27 @@ export const serializable: {
 /**
  * The type id used to mark atoms with a server-side read override.
  *
- * @category ServerValue
+ * @category type IDs
  * @since 4.0.0
  */
 export const ServerValueTypeId = "~effect-atom/atom/Atom/ServerValue" as const
 
 /**
- * Overrides the value of an Atom when read on the server.
+ * Sets the value of an Atom when read on the server.
  *
  * @category ServerValue
  * @since 4.0.0
  */
 export const withServerValue: {
   /**
-   * Overrides the value of an Atom when read on the server.
+   * Sets the value of an Atom when read on the server.
    *
    * @category ServerValue
    * @since 4.0.0
    */
   <A extends Atom<any>>(read: (get: <A>(atom: Atom<A>) => A) => Type<A>): (self: A) => A
   /**
-   * Overrides the value of an Atom when read on the server.
+   * Sets the value of an Atom when read on the server.
    *
    * @category ServerValue
    * @since 4.0.0

package/src/unstable/reactivity/AtomRef.ts

@@ -1,20 +1,36 @@
 /**
- * Mutable reactive references for local, in-memory state that should be read,
- * updated, and observed without going through an `AtomRegistry`.
+ * Mutable reactive references for local, in-memory state.
  *
- * `AtomRef` is useful for small state models, form-like state, and collections
- * of item references where callers need direct mutation methods together with
- * subscriptions. A ref exposes its current `value`, notifies subscribers after
- * `set` or `update`, can derive read-only views with `map`, and can focus on
- * nested object or array properties with `prop`.
+ * `AtomRef` provides small observable state cells that can be read, updated,
+ * focused, and subscribed to without going through an `AtomRegistry`. It is
+ * suited to form state, local view models, and collections of item references
+ * where callers need direct mutation methods together with change notifications.
  *
- * Notifications are equality-aware: setting a value that is `Equal.equals` to
- * the current value is ignored, and mapped or property subscriptions only emit
- * when their derived value changes. Mutate state through `set`, `update`, or a
- * property ref so subscribers are notified; direct mutation of the stored value
- * does not notify listeners. Collection subscribers are notified when items are
- * inserted, removed, or when an item ref changes, while `toArray` returns the
- * current raw item values.
+ * **Mental model**
+ *
+ * An `AtomRef` is a value cell with a stable key and a subscriber list.
+ * {@link make} creates a mutable cell, `map` derives read-only views, and `prop`
+ * focuses on nested object or array properties while preserving mutation
+ * helpers. {@link collection} stores ordered item refs and emits collection
+ * updates when items are inserted, removed, or changed through their refs.
+ *
+ * **Common tasks**
+ *
+ * - Use {@link make} for standalone local state.
+ * - Use `ref.set` or `ref.update` to replace the current value.
+ * - Use `ref.map` for derived read-only values.
+ * - Use `ref.prop` to update nested object fields or array entries.
+ * - Use {@link collection} for ordered lists whose items should remain
+ *   individually mutable.
+ *
+ * **Gotchas**
+ *
+ * Notifications are equality-aware: values that are `Equal.equals` to the
+ * current value do not notify subscribers, and mapped or property subscriptions
+ * only emit when their derived value changes. Directly mutating an object or
+ * array stored in a ref does not notify listeners; use `set`, `update`, or a
+ * property ref instead. `toArray` returns the current raw item values, not the
+ * item refs.
  *
  * @since 4.0.0
  */
@@ -137,25 +153,36 @@ class ReadonlyRefImpl<A> implements ReadonlyRef<A> {
     return Hash.hash(this.value)
   }
 
-  listeners: Array<(a: A) => void> = []
-  listenerCount = 0
+  listeners: Listener<A> | null = null
 
   notify(a: A) {
-    for (let i = 0; i < this.listenerCount; i++) {
-      this.listeners[i](a)
+    let listener = this.listeners
+    while (listener !== null) {
+      listener.f(a)
+      listener = listener.next
     }
   }
 
   subscribe(f: (a: A) => void): () => void {
-    this.listeners.push(f)
-    this.listenerCount++
+    const listener: Listener<A> = {
+      f,
+      prev: null,
+      next: this.listeners
+    }
+    if (this.listeners) {
+      this.listeners.prev = listener
+    }
+    this.listeners = listener
 
     return () => {
-      const index = this.listeners.indexOf(f)
-      if (index !== -1) {
-        this.listeners[index] = this.listeners[this.listenerCount - 1]
-        this.listeners.pop()
-        this.listenerCount--
+      if (this.listeners === listener) {
+        this.listeners = listener.next
+      }
+      if (listener.prev) {
+        listener.prev.next = listener.next
+      }
+      if (listener.next) {
+        listener.next.prev = listener.prev
       }
     }
   }
@@ -165,6 +192,12 @@ class ReadonlyRefImpl<A> implements ReadonlyRef<A> {
   }
 }
 
+type Listener<A> = {
+  readonly f: (a: A) => void
+  prev: Listener<A> | null
+  next: Listener<A> | null
+}
+
 class AtomRefImpl<A> extends ReadonlyRefImpl<A> implements AtomRef<A> {
   prop<K extends keyof A>(prop: K): AtomRef<A[K]> {
     return new PropRefImpl(this, prop)

package/src/unstable/reactivity/AtomRegistry.ts

@@ -1,22 +1,78 @@
 /**
- * The `AtomRegistry` module provides the runtime cache used by reactivity
- * atoms. A registry owns the node graph for a group of atoms, stores their
- * current values, records parent/child dependencies while atoms are read, and
- * coordinates writes, refreshes, stream conversions, and node disposal.
+ * The `AtomRegistry` module provides the runtime cache for unstable reactivity
+ * atoms. A registry owns the node graph for a group of atoms, stores current
+ * values, records parent and child dependencies while atoms are read, and
+ * coordinates writes, refreshes, subscriptions, stream conversions, and node
+ * disposal.
  *
- * Create a registry directly with {@link make} or provide it with {@link layer}
- * or {@link layerOptions} when a UI root, request, test, or other Effect scope
- * needs its own atom state. The same atom can have different cached values in
- * different registries, while serializable atoms are keyed by their
- * serialization key so preloaded values can hydrate a node before its first
- * read.
+ * Use a separate registry for each UI root, request, test, route boundary, or
+ * other lifetime that needs isolated atom state. The same atom object can have
+ * different cached values in different registries, while serializable atoms use
+ * their stable serialization key so preloaded values can hydrate a node before
+ * the first read.
  *
- * Subscriptions and {@link mount} keep nodes alive and must be released when
- * the consumer is done; scoped helpers install finalizers for this. Unobserved
- * non-`keepAlive` atoms may be removed immediately or after their `idleTTL` (or
- * the registry `defaultIdleTTL`), which means later reads can rebuild derived
- * state. Disposing a registry clears its cache and makes future atom access an
- * error.
+ * **Mental model**
+ *
+ * - Reading an atom creates or reuses a registry node, evaluates the atom when
+ *   its value is missing or stale, and records any nested atom reads as
+ *   dependencies.
+ * - Writing a writable atom updates its node through the atom's write function,
+ *   invalidates dependent nodes, and notifies listeners after batching settles.
+ * - Subscriptions and scoped {@link mount} calls keep nodes alive. When the last
+ *   listener and dependent child disappear, non-`keepAlive` atoms can be
+ *   removed immediately or after their idle TTL.
+ * - Effects and streams started by atoms run with the registry scheduler and
+ *   are finalized when the node is rebuilt, removed, reset, or disposed.
+ * - Disposing a registry clears its nodes and makes later atom access an error.
+ *
+ * **Common tasks**
+ *
+ * - Create a registry directly with {@link make}, or provide one to Effect
+ *   programs with {@link layer} or {@link layerOptions}.
+ * - Read and write atom state with the registry instance methods `get`, `set`,
+ *   `modify`, `update`, and `refresh`.
+ * - Keep an atom alive for an Effect scope with {@link mount}; subscribe with
+ *   `subscribe` when integrating with callback-based UI code.
+ * - Convert observed atom values with {@link toStream} and
+ *   {@link toStreamResult}, or wait for an `AsyncResult` atom with
+ *   {@link getResult}.
+ * - Preload encoded serializable state with `setSerializable` before the
+ *   matching atom is read.
+ *
+ * **Quickstart**
+ *
+ * **Example** (Isolated atom state)
+ *
+ * ```ts
+ * import { Atom, AtomRegistry } from "effect/unstable/reactivity"
+ *
+ * const count = Atom.make(0)
+ * const doubled = Atom.make((get) => get(count) * 2)
+ *
+ * const registry = AtomRegistry.make()
+ *
+ * registry.set(count, 21)
+ * registry.get(doubled)
+ * // 42
+ * ```
+ *
+ * **Gotchas**
+ *
+ * - Atom identity matters. Creating a new atom object creates a different node
+ *   unless the atom is serializable and uses the same serialization key.
+ * - Unobserved atoms without `keepAlive` can be removed, so later reads may
+ *   rebuild derived values, restart effects or streams, and rerun finalizers.
+ * - `subscribe` and the instance `mount` method return release callbacks; call
+ *   them when the external consumer is done. The exported {@link mount} helper
+ *   ties that release to an Effect scope.
+ * - `reset` and `dispose` remove every node in the registry. Use a new registry
+ *   when a whole lifetime should start from empty state.
+ *
+ * **See also**
+ *
+ * - {@link Atom.Atom} for defining reactive values read by a registry.
+ * - {@link Result.AsyncResult} for asynchronous atom results.
+ * - {@link Stream.Stream} for streams produced from observed atom values.
  *
  * @since 4.0.0
  */
@@ -141,9 +197,14 @@ export const make = (
   )
 
 /**
- * The `Context` service tag for the current `AtomRegistry`.
+ * Service tag for the active atom runtime cache.
+ *
+ * **When to use**
+ *
+ * Use to access or provide the registry that stores atom values,
+ * dependencies, subscriptions, and disposal state for a reactive lifetime.
  *
- * @category Tags
+ * @category tags
  * @since 4.0.0
  */
 export const AtomRegistry = Context.Service<AtomRegistry>(TypeId)

package/src/unstable/reactivity/Hydration.ts

@@ -1,20 +1,35 @@
 /**
- * Utilities for moving serializable reactivity state between atom registries.
- *
- * `dehydrate` snapshots atoms marked with `Atom.serializable` from an
- * `AtomRegistry`, preserving their serialization keys, encoded values, and
- * dehydration time so another registry can preload the same state with `hydrate`.
- * This is useful for server rendering, browser bootstrapping, route transitions,
- * and other handoffs where a registry should start from values that were already
- * computed elsewhere.
- *
- * Only serializable atoms are included, and the receiving registry needs atoms
- * with matching stable keys and compatible schemas. Values crossing a
- * client/server boundary should be the encoded JSON-safe values produced by the
- * atom codecs. The optional `resultPromise` used for `AsyncResult.Initial`
- * handoffs is a live JavaScript promise, so it cannot be sent through JSON and
- * should be omitted or replaced by an application-level streaming protocol when
- * dehydrated state leaves the current runtime.
+ * Moves serializable reactivity state between `AtomRegistry` instances.
+ *
+ * The `Hydration` module snapshots atoms marked with `Atom.serializable` and
+ * loads those encoded values into another registry before the atoms are read. It
+ * is useful for server rendering, browser bootstrapping, route transitions, and
+ * other handoffs where a new registry should start from values computed by a
+ * previous one.
+ *
+ * **Mental model**
+ *
+ * `dehydrate` walks the source registry and produces `DehydratedAtomValue`
+ * records keyed by each atom's serialization key. `hydrate` stores those encoded
+ * values in the target registry so the matching atom can decode them with its own
+ * serializable codec. Atom identity is not transferred; only the stable key,
+ * encoded value, dehydration timestamp, and optional async handoff are.
+ *
+ * **Common tasks**
+ *
+ * Use `dehydrate` before rendering or crossing a route boundary, then call
+ * `hydrate` on the registry that will serve the next read. Use `toValues` when
+ * code accepts generic `DehydratedAtom` entries but needs the concrete record
+ * shape, and use `encodeInitialAs` to choose how `AsyncResult.Initial` values
+ * should appear in the snapshot.
+ *
+ * **Gotchas**
+ *
+ * Only serializable atoms are included, and the target registry must contain
+ * atoms with matching stable keys and compatible codecs. The optional
+ * `resultPromise` used for `AsyncResult.Initial` is a live JavaScript promise; it
+ * can be handed to another registry in the same runtime, but it cannot be sent
+ * through JSON or across process boundaries.
  *
  * @since 4.0.0
  */
@@ -117,7 +132,12 @@ export const dehydrate = (
 export const toValues = (state: ReadonlyArray<DehydratedAtom>): Array<DehydratedAtomValue> => state as any
 
 /**
- * Loads dehydrated atom state into a registry.
+ * Applies dehydrated atom state to a registry.
+ *
+ * **When to use**
+ *
+ * Use to preload serialized atom values into a target registry before those
+ * atoms are read.
  *
  * **Details**
  *

package/src/unstable/reactivity/Reactivity.ts

@@ -1,24 +1,42 @@
 /**
- * The `Reactivity` module provides an in-memory service for connecting writes to
- * dependent reads through explicit invalidation keys. It is useful for keeping
- * query results, UI subscriptions, read models, or other derived views fresh
- * after mutations without coupling the writer to every consumer that should
- * rerun.
+ * The `Reactivity` module provides process-local invalidation for connecting
+ * writes to dependent reads. It does not cache values itself; it tracks keys,
+ * registers query handlers, and reruns effects when matching keys are
+ * invalidated so queues, streams, UI subscriptions, and read models can stay
+ * fresh after successful writes.
  *
- * Reads are modeled with {@link query} and {@link stream}: the effect runs once
- * immediately and then runs again whenever one of its keys is invalidated.
- * Writes can use {@link mutation} to invalidate keys only after the wrapped
- * effect succeeds, or call {@link invalidate} directly. Keys may be supplied as
- * a flat collection or as a record of namespaces with ids, which lets callers
- * invalidate both broad groups and individual records.
+ * **Mental model**
  *
- * The service tracks handlers by hashed keys and does not cache values by
- * itself; consumers receive fresh queue or stream emissions and decide how to
- * store them. Registrations are tied to the surrounding scope, failures from a
- * query fail the queue or stream, and invalidations that arrive while a query is
- * already running schedule a single follow-up run. Use stable key values, be
- * aware that the default layer is process-local, and use the {@link Reactivity}
- * service when many invalidations should be coalesced until the batch exits.
+ * A query registers one or more keys, runs once immediately, and publishes each
+ * result to a queue or stream. Invalidating any registered key schedules the
+ * query to rerun. Mutations wrap an effect and invalidate keys only after it
+ * succeeds. Keys can be a flat array, or a record whose property names act as
+ * broad namespaces and whose ids address individual records.
+ *
+ * **Common tasks**
+ *
+ * - Provide the default in-memory service with {@link layer}.
+ * - Use {@link query} when callers need a queue of rerun results.
+ * - Use {@link stream} when downstream code should consume reruns as a stream.
+ * - Wrap writes with {@link mutation}, or call {@link invalidate} directly when
+ *   invalidation is already part of the workflow.
+ * - Use the {@link Reactivity} service directly when many invalidations should
+ *   be coalesced until a batch exits.
+ *
+ * **Gotchas**
+ *
+ * - The default layer is process-local; it does not coordinate invalidations
+ *   across processes or cluster runners.
+ * - Non-primitive keys are matched by their `Hash.hash` value, so prefer stable
+ *   key values over mutable objects.
+ * - If a query fails, its queue or stream fails with the same cause.
+ * - Invalidations that arrive while a query is already running coalesce into one
+ *   follow-up run.
+ *
+ * **See also**
+ *
+ * - {@link query}, {@link stream}, {@link mutation}, and {@link invalidate}
+ * - {@link layer} and {@link Reactivity}
  *
  * @since 4.0.0
  */
@@ -35,7 +53,12 @@ import * as Scope from "../../Scope.ts"
 import * as Stream from "../../Stream.ts"
 
 /**
- * A service for key-based reactive invalidation.
+ * Service for key-based reactive invalidation.
+ *
+ * **When to use**
+ *
+ * Use to provide the invalidation service that refreshes queries, streams, and
+ * atoms when application keys change.
  *
  * **Details**
  *