effect 4.0.0-beta.101 → 4.0.0-beta.103

package/src/unstable/reactivity/Atom.ts

@@ -68,6 +68,7 @@ export interface Atom<A> extends Pipeable, Inspectable.Inspectable {
   readonly keepAlive: boolean
   readonly lazy: boolean
   readonly read: (get: AtomContext) => A
+  equals(value: A, next: A): boolean
   readonly refresh?: (f: <A>(atom: Atom<A>) => void) => void
   readonly label?: readonly [name: string, stack: string]
   readonly idleTTL?: number
@@ -253,6 +254,7 @@ const removeTtl = setIdleTTL(0)
 
 const AtomProto = {
   [TypeId]: TypeId,
+  equals: Object.is,
   ...PipeInspectableProto,
   toJSON(this: Atom<any>) {
     return {
@@ -377,7 +379,7 @@ const WritableProto = {
 /**
  * Returns `true` when an atom is writable.
  *
- * @category refinements
+ * @category guards
  * @since 4.0.0
  */
 export const isWritable = <R, W>(atom: Atom<R>): atom is Writable<R, W> => WritableTypeId in atom
@@ -1702,6 +1704,99 @@ export const setLazy: {
     lazy
   }))
 
+/**
+ * Returns a copy of an atom that uses a custom equality function to detect
+ * value changes.
+ *
+ * **Details**
+ *
+ * When an atom's value is rebuilt or written, the registry compares the new
+ * value against the current one to decide whether dependents and listeners
+ * should be notified. By default the comparison uses `Object.is`, so a
+ * structurally equal but referentially distinct value still triggers
+ * notifications. Providing an equality function lets the atom skip updates
+ * when the new value is equal to the current one.
+ *
+ * **Example** (Comparing values structurally)
+ *
+ * ```ts import.meta.vitest
+ * import { Atom } from "effect/unstable/reactivity"
+ *
+ * const point = Atom.make({ x: 0, y: 0 }).pipe(
+ *   Atom.withEquality<{ x: number; y: number }>((a, b) => a.x === b.x && a.y === b.y)
+ * )
+ * point.equals({ x: 1, y: 2 }, { x: 1, y: 2 }) // => true
+ * ```
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export const withEquality: {
+  /**
+   * Returns a copy of an atom that uses a custom equality function to detect
+   * value changes.
+   *
+   * **Details**
+   *
+   * When an atom's value is rebuilt or written, the registry compares the new
+   * value against the current one to decide whether dependents and listeners
+   * should be notified. By default the comparison uses `Object.is`, so a
+   * structurally equal but referentially distinct value still triggers
+   * notifications. Providing an equality function lets the atom skip updates
+   * when the new value is equal to the current one.
+   *
+   * **Example** (Comparing values structurally)
+   *
+   * ```ts import.meta.vitest
+   * import { Atom } from "effect/unstable/reactivity"
+   *
+   * const point = Atom.make({ x: 0, y: 0 }).pipe(
+   *   Atom.withEquality<{ x: number; y: number }>((a, b) => a.x === b.x && a.y === b.y)
+   * )
+   * point.equals({ x: 1, y: 2 }, { x: 1, y: 2 }) // => true
+   * ```
+   *
+   * @category combinators
+   * @since 4.0.0
+   */
+  <A>(equals: (value: A, next: A) => boolean): <T extends Atom<A>>(self: T) => T
+  /**
+   * Returns a copy of an atom that uses a custom equality function to detect
+   * value changes.
+   *
+   * **Details**
+   *
+   * When an atom's value is rebuilt or written, the registry compares the new
+   * value against the current one to decide whether dependents and listeners
+   * should be notified. By default the comparison uses `Object.is`, so a
+   * structurally equal but referentially distinct value still triggers
+   * notifications. Providing an equality function lets the atom skip updates
+   * when the new value is equal to the current one.
+   *
+   * **Example** (Comparing values structurally)
+   *
+   * ```ts import.meta.vitest
+   * import { Atom } from "effect/unstable/reactivity"
+   *
+   * const point = Atom.make({ x: 0, y: 0 }).pipe(
+   *   Atom.withEquality<{ x: number; y: number }>((a, b) => a.x === b.x && a.y === b.y)
+   * )
+   * point.equals({ x: 1, y: 2 }, { x: 1, y: 2 }) // => true
+   * ```
+   *
+   * @category combinators
+   * @since 4.0.0
+   */
+  <T extends Atom<any>>(self: T, equals: (value: Type<T>, next: Type<T>) => boolean): T
+} = dual(
+  2,
+  <T extends Atom<any>>(self: T, equals: (value: Type<T>, next: Type<T>) => boolean): T =>
+    Object.assign(Object.create(Object.getPrototypeOf(self)), {
+      ...self,
+      equals
+    })
+)
+
 /**
  * Attaches a diagnostic label to an atom.
  *
@@ -2284,7 +2379,7 @@ const shouldRevalidateSWR = <A, E>(result: AsyncResult.AsyncResult<A, E>, staleT
  * transitions finish, the source atom is refreshed, and failures roll the value
  * back to the latest source value.
  *
- * @category Optimistic
+ * @category constructors
  * @since 4.0.0
  */
 export const optimistic = <A>(self: Atom<A>): Writable<A, Atom<AsyncResult.AsyncResult<A, unknown>>> => {
@@ -2387,7 +2482,7 @@ export const optimistic = <A>(self: Atom<A>): Writable<A, Atom<AsyncResult.Async
  * input. The wrapped function result then completes the transition or updates the
  * optimistic value through the provided setter callback.
  *
- * @category Optimistic
+ * @category combinators
  * @since 4.0.0
  */
 export const optimisticFn: {
@@ -2401,7 +2496,7 @@ export const optimisticFn: {
    * input. The wrapped function result then completes the transition or updates the
    * optimistic value through the provided setter callback.
    *
-   * @category Optimistic
+   * @category combinators
    * @since 4.0.0
    */
   <A, W, XA, XE, OW = void>(
@@ -2424,7 +2519,7 @@ export const optimisticFn: {
    * input. The wrapped function result then completes the transition or updates the
    * optimistic value through the provided setter callback.
    *
-   * @category Optimistic
+   * @category combinators
    * @since 4.0.0
    */
   <A, W, XA, XE, OW = void>(
@@ -2455,7 +2550,7 @@ export const optimisticFn: {
    * input. The wrapped function result then completes the transition or updates the
    * optimistic value through the provided setter callback.
    *
-   * @category Optimistic
+   * @category combinators
    * @since 4.0.0
    */
   AsyncResult.AsyncResult<W, unknown>>(AsyncResult.initial()))
@@ -2485,7 +2580,7 @@ export const optimisticFn: {
      * input. The wrapped function result then completes the transition or updates the
      * optimistic value through the provided setter callback.
      *
-     * @category Optimistic
+     * @category combinators
      * @since 4.0.0
      */
     XA, /**
@@ -2498,7 +2593,7 @@ export const optimisticFn: {
      * input. The wrapped function result then completes the transition or updates the
      * optimistic value through the provided setter callback.
      *
-     * @category Optimistic
+     * @category combinators
      * @since 4.0.0
      */
     XE>((resume) => {
@@ -2536,7 +2631,7 @@ export const batch: (f: () => void) => void = Registry.batch
  * It listens for `visibilitychange` events on `window` and removes the listener
  * when the atom is disposed.
  *
- * @category Focus
+ * @category constants
  * @since 4.0.0
  */
 export const windowFocusSignal: Atom<number> = readable((get) => {
@@ -2562,7 +2657,7 @@ export const windowFocusSignal: Atom<number> = readable((get) => {
  * The derived atom also subscribes to the source atom so normal source updates are
  * forwarded to its own value.
  *
- * @category Focus
+ * @category constructors
  * @since 4.0.0
  */
 export const makeRefreshOnSignal = <_>(signal: Atom<_>) => <A extends Atom<any>>(self: A): WithoutSerializable<A> =>
@@ -2581,7 +2676,7 @@ export const makeRefreshOnSignal = <_>(signal: Atom<_>) => <A extends Atom<any>>
  * This helper is browser-only because `windowFocusSignal` depends on `window` and
  * `document.visibilityState`.
  *
- * @category Focus
+ * @category combinators
  * @since 4.0.0
  */
 export const refreshOnWindowFocus: <A extends Atom<any>>(self: A) => WithoutSerializable<A> = makeRefreshOnSignal(
@@ -2601,7 +2696,7 @@ export const refreshOnWindowFocus: <A extends Atom<any>>(self: A) => WithoutSeri
  * 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.
  *
- * @category KeyValueStore
+ * @category constructors
  * @since 4.0.0
  */
 export const kvs = <S extends Schema.ConstraintCodec<any, any>, const Mode extends "sync" | "async" = never>(options: {
@@ -2666,7 +2761,7 @@ export const kvs = <S extends Schema.ConstraintCodec<any, any>, const Mode exten
  *
  * If you pass a schema, it has to be synchronous and have no context.
  *
- * @category search params
+ * @category constructors
  * @since 4.0.0
  */
 export const searchParam = <S extends Schema.ConstraintCodec<any, string> = never>(
@@ -2947,7 +3042,7 @@ export type SerializableTypeId = "~effect-atom/atom/Atom/Serializable"
  * The key identifies the atom in dehydrated state, and the encode/decode
  * functions convert between the atom value and the schema encoded value.
  *
- * @category Serializable
+ * @category models
  * @since 4.0.0
  */
 export interface Serializable<S extends Schema.Constraint> {
@@ -2961,7 +3056,7 @@ export interface Serializable<S extends Schema.Constraint> {
 /**
  * Returns `true` when an atom carries `Serializable` metadata.
  *
- * @category Serializable
+ * @category guards
  * @since 4.0.0
  */
 export const isSerializable = (self: Atom<any>): self is Atom<any> & Serializable<any> => SerializableTypeId in self
@@ -3040,21 +3135,21 @@ export const ServerValueTypeId = "~effect-atom/atom/Atom/ServerValue" as const
 /**
  * Sets the value of an Atom when read on the server.
  *
- * @category ServerValue
+ * @category transforming
  * @since 4.0.0
  */
 export const withServerValue: {
   /**
    * Sets the value of an Atom when read on the server.
    *
-   * @category ServerValue
+   * @category transforming
    * @since 4.0.0
    */
   <A extends Atom<any>>(read: (get: <A>(atom: Atom<A>) => A) => Type<A>): (self: A) => A
   /**
    * Sets the value of an Atom when read on the server.
    *
-   * @category ServerValue
+   * @category transforming
    * @since 4.0.0
    */
   <A extends Atom<any>>(self: A, read: (get: <A>(atom: Atom<A>) => A) => Type<A>): A
@@ -3071,7 +3166,7 @@ export const withServerValue: {
  * Sets an `AsyncResult` atom's server-side value to
  * `AsyncResult.initial(true)`.
  *
- * @category ServerValue
+ * @category transforming
  * @since 4.0.0
  */
 export const withServerValueInitial = <A extends Atom<AsyncResult.AsyncResult<any, any>>>(self: A): A =>
@@ -3085,7 +3180,7 @@ export const withServerValueInitial = <A extends Atom<AsyncResult.AsyncResult<an
  *
  * Nested reads performed by the override are resolved against the same registry.
  *
- * @category ServerValue
+ * @category getters
  * @since 4.0.0
  */
 export const getServerValue: {
@@ -3097,7 +3192,7 @@ export const getServerValue: {
    *
    * Nested reads performed by the override are resolved against the same registry.
    *
-   * @category ServerValue
+   * @category getters
    * @since 4.0.0
    */
   (registry: Registry.AtomRegistry): <A>(self: Atom<A>) => A
@@ -3109,7 +3204,7 @@ export const getServerValue: {
    *
    * Nested reads performed by the override are resolved against the same registry.
    *
-   * @category ServerValue
+   * @category getters
    * @since 4.0.0
    */
   <A>(self: Atom<A>, registry: Registry.AtomRegistry): A

package/src/unstable/reactivity/AtomHttpApi.ts

@@ -37,7 +37,7 @@ import * as Reactivity from "./Reactivity.ts"
  * 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.
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export interface AtomHttpApiClient<Self, Id extends string, Groups extends HttpApiGroup.Constraint>
@@ -266,6 +266,9 @@ export const Service =
           HttpClientError.HttpClientError | SchemaError
         >)
       }))
+      if (opts.reactivityKeys) {
+        atom = self.runtime.factory.withReactivity(opts.reactivityKeys)(atom)
+      }
       if (opts.responseMode === "decoded-only" && opts.serializationKey) {
         const endpoint = groups[opts.group].endpoints[opts.endpoint]
         atom = Atom.serializable(atom, {
@@ -281,9 +284,7 @@ export const Service =
           ? Atom.setIdleTTL(atom, opts.timeToLive)
           : Atom.keepAlive(atom)
       }
-      return opts.reactivityKeys
-        ? self.runtime.factory.withReactivity(opts.reactivityKeys)(atom)
-        : atom
+      return atom
     })
 
     self.query = ((

package/src/unstable/reactivity/AtomRegistry.ts

@@ -555,7 +555,15 @@ class RegistryImpl implements AtomRegistry {
       const encoded = this.preloadedSerializable.get(key)
       this.preloadedSerializable.delete(key)
       const decoded = (atom as any as Atom.Serializable<any>)[SerializableTypeId].decode(encoded)
-      node.setValue(decoded)
+      let target = atom
+      while (target.initialValueTarget) {
+        target = target.initialValueTarget
+      }
+      if (target === atom) {
+        node.setValue(decoded)
+      } else {
+        this.ensureNode(target).setInitialValue(decoded)
+      }
     }
     return node
   }
@@ -718,6 +726,8 @@ class NodeImpl<A> {
   children = new Set<NodeImpl<any>>()
   listeners = new Set<() => void>()
   skipInvalidation = false
+  building = false
+  invalidatedDuringBuild = false
 
   currentState() {
     switch (this.state) {
@@ -740,7 +750,9 @@ class NodeImpl<A> {
   value(): A {
     if ((this.state & NodeFlags.waitingForValue) !== 0) {
       this.lifetime = makeLifetime(this)
+      this.building = true
       const value = this.atom.read(this.lifetime)
+      this.building = false
       if ((this.state & NodeFlags.waitingForValue) !== 0) {
         if (this.preserveInitialValueOnBuild) {
           this.preserveInitialValueOnBuild = false
@@ -805,7 +817,7 @@ class NodeImpl<A> {
     }
 
     this.state = NodeState.valid
-    if (Object.is(this._value, value)) {
+    if (this.atom.equals(this._value, value)) {
       return
     }
 
@@ -847,6 +859,9 @@ class NodeImpl<A> {
   }
 
   invalidate(): void {
+    if (this.building && batchState.phase === BatchPhase.collect) {
+      this.invalidatedDuringBuild = true
+    }
     if (this.state === NodeState.valid) {
       this.state = NodeState.stale
       this.disposeLifetime()
@@ -972,8 +987,9 @@ const LifetimeProto: Omit<Lifetime<any>, "node" | "finalizers" | "disposed" | "i
       return this.node.registry.get(atom)
     }
     const parent = this.node.registry.ensureNode(atom)
+    const value = parent.value()
     this.node.addParent(parent)
-    return parent.value()
+    return value
   },
 
   result<A, E>(this: Lifetime<any>, atom: Atom.Atom<Result.AsyncResult<A, E>>, options?: {
@@ -1222,7 +1238,12 @@ export function batch(f: () => void): void {
 
 function batchRebuildNode(node: NodeImpl<any>) {
   if (node.state === NodeState.valid) {
-    return
+    if (!node.invalidatedDuringBuild) {
+      return
+    }
+    node.invalidatedDuringBuild = false
+    node.state = NodeState.stale
+    node.disposeLifetime()
   }
 
   for (const parent of node.parents) {

package/src/unstable/reactivity/AtomRpc.ts

@@ -37,7 +37,7 @@ import * as Reactivity from "./Reactivity.ts"
  * It exposes the RPC client, an atom runtime, mutation helpers that return `AtomResultFn`s, and query helpers that
  * return atoms or pull atoms for RPC results.
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export interface AtomRpcClient<Self, Id extends string, Rpcs extends Rpc.Any> extends
@@ -234,6 +234,9 @@ export const Service = <Self>() =>
         : self.runtime.atom(
           self.use((client) => client(tag, payload, { headers } as any)) as any
         )
+      if (reactivityKeys) {
+        atom = self.runtime.factory.withReactivity(reactivityKeys)(atom)
+      }
       if (!isStream && key.serializationKey) {
         atom = Atom.serializable(atom, {
           key: `AtomRpc:${key.tag}:${key.serializationKey}`,
@@ -248,9 +251,7 @@ export const Service = <Self>() =>
           ? Atom.setIdleTTL(atom, timeToLive)
           : Atom.keepAlive(atom)
       }
-      return reactivityKeys
-        ? self.runtime.factory.withReactivity(reactivityKeys)(atom)
-        : atom
+      return atom
     }
   )
 

package/src/unstable/reactivity/Hydration.ts

@@ -103,7 +103,7 @@ export const dehydrate = (
 /**
  * Returns dehydrated state entries as `DehydratedAtomValue` records.
  *
- * @category dehydration
+ * @category converting
  * @since 4.0.0
  */
 export const toValues = (state: ReadonlyArray<DehydratedAtom>): Array<DehydratedAtomValue> => state as any