effect 4.0.0-beta.98 → 4.0.0-rc.108

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
@@ -788,7 +790,7 @@ export interface AtomRuntime<R, ER = never> extends Atom<AsyncResult.AsyncResult
 }
 
 /**
- * Factory for `AtomRuntime` values that share a `Layer.MemoMap` and a set of global layers.
+ * Factory for `AtomRuntime` values that share a set of global layers.
  *
  * @category models
  * @since 4.0.0
@@ -799,7 +801,6 @@ export interface RuntimeFactory {
       | Layer.Layer<R, E, AtomRegistry | Reactivity.Reactivity>
       | ((get: AtomContext) => Layer.Layer<R, E, AtomRegistry | Reactivity.Reactivity>)
   ): AtomRuntime<R, E>
-  readonly memoMap: Layer.MemoMap
   readonly addGlobalLayer: <A, E>(layer: Layer.Layer<A, E, AtomRegistry | Reactivity.Reactivity>) => void
 
   /**
@@ -812,14 +813,40 @@ export interface RuntimeFactory {
 }
 
 /**
- * Creates a `RuntimeFactory` backed by the supplied `Layer.MemoMap`.
+ * A `RuntimeFactory` backed by an atom whose memo map is scoped to each registry.
  *
- * @category constructors
+ * @category models
+ * @since 4.0.0
+ */
+export interface RegistryRuntimeFactory extends RuntimeFactory {
+  readonly memoMap: Atom<Layer.MemoMap>
+}
+
+/**
+ * A `RuntimeFactory` backed by a concrete memo map shared across registries.
+ *
+ * @category models
  * @since 4.0.0
  */
-export const context: (options: {
+export interface SharedRuntimeFactory extends RuntimeFactory {
   readonly memoMap: Layer.MemoMap
-}) => RuntimeFactory = (options) => {
+}
+
+/**
+ * Creates a `RuntimeFactory` backed by a registry-scoped memo map by default,
+ * or by the supplied atom or concrete `Layer.MemoMap`.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export function context(): RegistryRuntimeFactory
+export function context(options: { readonly memoMap: Atom<Layer.MemoMap> }): RegistryRuntimeFactory
+export function context(options: { readonly memoMap: Layer.MemoMap }): SharedRuntimeFactory
+export function context(options?: {
+  readonly memoMap: Atom<Layer.MemoMap> | Layer.MemoMap
+}): RegistryRuntimeFactory | SharedRuntimeFactory {
+  const memoMap = options?.memoMap ?? removeTtl(make(() => Layer.makeMemoMapUnsafe()))
+  const resolveMemoMap = (get: AtomContext): Layer.MemoMap => isAtom(memoMap) ? get(memoMap) : memoMap
   let globalLayer: Layer.Layer<any, any, AtomRegistry> = Reactivity.layer
   function factory<E, R>(
     create:
@@ -841,23 +868,25 @@ export const context: (options: {
 
     self.read = function read(get: AtomContext) {
       const layer = get(layerAtom)
-      const build = Effect.flatMap(Effect.scope, (scope) => Layer.buildWithMemoMap(layer, options.memoMap, scope))
+      const build = Effect.flatMap(Effect.scope, (scope) => Layer.buildWithMemoMap(layer, resolveMemoMap(get), scope))
       return effect(get, build, { uninterruptible: true })
     }
 
     return self
   }
-  factory.memoMap = options.memoMap
+  factory.memoMap = memoMap
   factory.addGlobalLayer = (layer: Layer.Layer<any, any, AtomRegistry | Reactivity.Reactivity>) => {
     globalLayer = Layer.provideMerge(globalLayer, Layer.provide(layer, Reactivity.layer))
   }
-  const reactivityAtom = removeTtl(make(
-    Effect.contextWith((services: Context.Context<Scope.Scope>) =>
-      Layer.buildWithMemoMap(Reactivity.layer, options.memoMap, Context.get(services, Scope.Scope))
-    ).pipe(
-      Effect.map(Context.get(Reactivity.Reactivity))
+  const reactivityAtom = removeTtl(
+    make((get) =>
+      Effect.contextWith((services: Context.Context<Scope.Scope>) =>
+        Layer.buildWithMemoMap(Reactivity.layer, resolveMemoMap(get), Context.get(services, Scope.Scope))
+      ).pipe(
+        Effect.map(Context.get(Reactivity.Reactivity))
+      )
     )
-  ))
+  )
   factory.withReactivity =
     (keys: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>>) =>
     <A extends Atom<any>>(atom: A): A =>
@@ -869,24 +898,16 @@ export const context: (options: {
         get.subscribe(atom, (value) => get.setSelf(value))
         return get.once(atom)
       }, { initialValueTarget: atom }) as any as A
-  return factory
+  return factory as any
 }
 
 /**
- * Default `Layer.MemoMap` used by the module-level `runtime` factory.
- *
- * @category context
- * @since 4.0.0
- */
-export const defaultMemoMap: Layer.MemoMap = Layer.makeMemoMapUnsafe()
-
-/**
- * Default `RuntimeFactory` created with `defaultMemoMap`.
+ * Default registry-scoped `RuntimeFactory`.
  *
  * @category context
  * @since 4.0.0
  */
-export const runtime: RuntimeFactory = context({ memoMap: defaultMemoMap })
+export const runtime: RegistryRuntimeFactory = context()
 
 /**
  * Returns `Rx.runtime.withReactivity` for refreshing an atom whenever the
@@ -1702,6 +1723,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 +2398,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 +2501,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 +2515,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 +2538,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 +2569,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 +2599,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 +2612,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 +2650,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 +2676,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 +2695,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 +2715,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 +2780,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 +3061,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 +3075,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 +3154,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 +3185,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 +3199,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 +3211,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 +3223,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