@effect/atom-react 4.0.0-beta.66 → 4.0.0-beta.68

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. package/dist/Hooks.d.ts +53 -13
  2. package/dist/Hooks.d.ts.map +1 -1
  3. package/dist/Hooks.js +64 -12
  4. package/dist/Hooks.js.map +1 -1
  5. package/dist/ReactHydration.d.ts +12 -2
  6. package/dist/ReactHydration.d.ts.map +1 -1
  7. package/dist/ReactHydration.js +30 -2
  8. package/dist/ReactHydration.js.map +1 -1
  9. package/dist/RegistryContext.d.ts +13 -3
  10. package/dist/RegistryContext.d.ts.map +1 -1
  11. package/dist/RegistryContext.js +36 -4
  12. package/dist/RegistryContext.js.map +1 -1
  13. package/dist/ScopedAtom.d.ts +24 -24
  14. package/dist/ScopedAtom.d.ts.map +1 -1
  15. package/dist/ScopedAtom.js +30 -13
  16. package/dist/ScopedAtom.js.map +1 -1
  17. package/dist/index.d.ts +5 -5
  18. package/dist/index.js +5 -5
  19. package/package.json +6 -6
  20. package/src/Hooks.ts +72 -14
  21. package/src/ReactHydration.ts +34 -3
  22. package/src/RegistryContext.ts +36 -4
  23. package/src/ScopedAtom.ts +42 -25
  24. package/src/index.ts +5 -5
package/dist/Hooks.d.ts CHANGED
@@ -3,78 +3,118 @@ import type * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
3
3
  import * as Atom from "effect/unstable/reactivity/Atom";
4
4
  import type * as AtomRef from "effect/unstable/reactivity/AtomRef";
5
5
  /**
6
- * @since 1.0.0
6
+ * Seeds initial atom values in the current React atom registry.
7
+ *
8
+ * **Details**
9
+ *
10
+ * Each atom is initialized at most once for a given registry, so subsequent
11
+ * renders do not overwrite values that have already been established.
12
+ *
7
13
  * @category hooks
14
+ * @since 4.0.0
8
15
  */
9
16
  export declare const useAtomInitialValues: (initialValues: Iterable<readonly [Atom.Atom<any>, any]>) => void;
10
17
  /**
11
- * @since 1.0.0
18
+ * Subscribes to an atom in the current React registry and returns its current
19
+ * value, optionally mapped through a selector.
20
+ *
12
21
  * @category hooks
22
+ * @since 4.0.0
13
23
  */
14
24
  export declare const useAtomValue: {
15
25
  /**
16
- * @since 1.0.0
26
+ * Subscribes to an atom in the current React registry and returns its current
27
+ * value, optionally mapped through a selector.
28
+ *
17
29
  * @category hooks
30
+ * @since 4.0.0
18
31
  */
19
32
  <A>(atom: Atom.Atom<A>): A;
20
33
  /**
21
- * @since 1.0.0
34
+ * Subscribes to an atom in the current React registry and returns its current
35
+ * value, optionally mapped through a selector.
36
+ *
22
37
  * @category hooks
38
+ * @since 4.0.0
23
39
  */
24
40
  <A, B>(atom: Atom.Atom<A>, f: (_: A) => B): B;
25
41
  };
26
42
  /**
27
- * @since 1.0.0
43
+ * Mounts an atom in the current React registry for the lifetime of the
44
+ * component.
45
+ *
28
46
  * @category hooks
47
+ * @since 4.0.0
29
48
  */
30
49
  export declare const useAtomMount: <A>(atom: Atom.Atom<A>) => void;
31
50
  /**
32
- * @since 1.0.0
51
+ * Mounts a writable atom and returns a setter without subscribing to its value.
52
+ *
33
53
  * @category hooks
54
+ * @since 4.0.0
34
55
  */
35
56
  export declare const useAtomSet: <R, W, Mode extends "value" | "promise" | "promiseExit" = never>(atom: Atom.Writable<R, W>, options?: {
36
57
  readonly mode?: ([R] extends [AsyncResult.AsyncResult<any, any>] ? Mode : "value") | undefined;
37
58
  }) => "promise" extends Mode ? ((value: W) => Promise<AsyncResult.AsyncResult.Success<R>>) : "promiseExit" extends Mode ? ((value: W) => Promise<Exit.Exit<AsyncResult.AsyncResult.Success<R>, AsyncResult.AsyncResult.Failure<R>>>) : ((value: W | ((value: R) => W)) => void);
38
59
  /**
39
- * @since 1.0.0
60
+ * Mounts an atom and returns a callback that refreshes it in the current React
61
+ * registry.
62
+ *
40
63
  * @category hooks
64
+ * @since 4.0.0
41
65
  */
42
66
  export declare const useAtomRefresh: <A>(atom: Atom.Atom<A>) => () => void;
43
67
  /**
44
- * @since 1.0.0
68
+ * Subscribes to a writable atom and returns its current value together with a
69
+ * setter for updating it.
70
+ *
45
71
  * @category hooks
72
+ * @since 4.0.0
46
73
  */
47
74
  export declare const useAtom: <R, W, const Mode extends "value" | "promise" | "promiseExit" = never>(atom: Atom.Writable<R, W>, options?: {
48
75
  readonly mode?: ([R] extends [AsyncResult.AsyncResult<any, any>] ? Mode : "value") | undefined;
49
76
  }) => readonly [value: R, write: "promise" extends Mode ? ((value: W) => Promise<AsyncResult.AsyncResult.Success<R>>) : "promiseExit" extends Mode ? ((value: W) => Promise<Exit.Exit<AsyncResult.AsyncResult.Success<R>, AsyncResult.AsyncResult.Failure<R>>>) : ((value: W | ((value: R) => W)) => void)];
50
77
  /**
51
- * @since 1.0.0
78
+ * Reads an `AsyncResult` atom through React Suspense, suspending while the
79
+ * result is initial or configured as waiting.
80
+ *
52
81
  * @category hooks
82
+ * @since 4.0.0
53
83
  */
54
84
  export declare const useAtomSuspense: <A, E, const IncludeFailure extends boolean = false>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>, options?: {
55
85
  readonly suspendOnWaiting?: boolean | undefined;
56
86
  readonly includeFailure?: IncludeFailure | undefined;
57
87
  }) => AsyncResult.Success<A, E> | (IncludeFailure extends true ? AsyncResult.Failure<A, E> : never);
58
88
  /**
59
- * @since 1.0.0
89
+ * Subscribes a callback to an atom in the current React registry for the
90
+ * component lifetime.
91
+ *
60
92
  * @category hooks
93
+ * @since 4.0.0
61
94
  */
62
95
  export declare const useAtomSubscribe: <A>(atom: Atom.Atom<A>, f: (_: A) => void, options?: {
63
96
  readonly immediate?: boolean;
64
97
  }) => void;
65
98
  /**
66
- * @since 1.0.0
99
+ * Subscribes to an atom ref and returns its latest value.
100
+ *
67
101
  * @category hooks
102
+ * @since 4.0.0
68
103
  */
69
104
  export declare const useAtomRef: <A>(ref: AtomRef.ReadonlyRef<A>) => A;
70
105
  /**
71
- * @since 1.0.0
106
+ * Returns a memoized atom ref for a property of another atom ref.
107
+ *
72
108
  * @category hooks
109
+ * @since 4.0.0
73
110
  */
74
111
  export declare const useAtomRefProp: <A, K extends keyof A>(ref: AtomRef.AtomRef<A>, prop: K) => AtomRef.AtomRef<A[K]>;
75
112
  /**
76
- * @since 1.0.0
113
+ * Subscribes to a property ref derived from an atom ref and returns its current
114
+ * value.
115
+ *
77
116
  * @category hooks
117
+ * @since 4.0.0
78
118
  */
79
119
  export declare const useAtomRefPropValue: <A, K extends keyof A>(ref: AtomRef.AtomRef<A>, prop: K) => A[K];
80
120
  //# sourceMappingURL=Hooks.d.ts.map
package/dist/Hooks.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"Hooks.d.ts","sourceRoot":"","sources":["../src/Hooks.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"Hooks.d.ts","sourceRoot":"","sources":["../src/Hooks.ts"],"names":[],"mappings":"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"}
package/dist/Hooks.js CHANGED
@@ -1,5 +1,23 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * React hooks for reading, writing, mounting, refreshing, and subscribing to
3
+ * Effect atoms from the registry provided by `RegistryContext`.
4
+ *
5
+ * **Common tasks**
6
+ *
7
+ * - Read atom values in React components with {@link useAtomValue}
8
+ * - Read and write writable atoms with {@link useAtom}
9
+ * - Write without subscribing to the value with {@link useAtomSet}
10
+ * - Seed registry-local initial values with {@link useAtomInitialValues}
11
+ * - Integrate `AsyncResult` atoms with React Suspense through {@link useAtomSuspense}
12
+ * - Subscribe to atom changes or derive stable `AtomRef` properties
13
+ *
14
+ * **Gotchas**
15
+ *
16
+ * - Hooks use the current `RegistryContext`, so each provider has an independent atom registry
17
+ * - Writable atoms are mounted by the write-oriented hooks before updates are sent
18
+ * - Suspense support throws promises for initial or waiting `AsyncResult` values and defects for failures unless `includeFailure` is enabled
19
+ *
20
+ * @since 4.0.0
3
21
  */
4
22
  "use client";
5
23
 
@@ -41,8 +59,15 @@ function useStore(registry, atom) {
41
59
  }
42
60
  const initialValuesSet = /*#__PURE__*/new WeakMap();
43
61
  /**
44
- * @since 1.0.0
62
+ * Seeds initial atom values in the current React atom registry.
63
+ *
64
+ * **Details**
65
+ *
66
+ * Each atom is initialized at most once for a given registry, so subsequent
67
+ * renders do not overwrite values that have already been established.
68
+ *
45
69
  * @category hooks
70
+ * @since 4.0.0
46
71
  */
47
72
  export const useAtomInitialValues = initialValues => {
48
73
  const registry = React.useContext(RegistryContext);
@@ -59,8 +84,11 @@ export const useAtomInitialValues = initialValues => {
59
84
  }
60
85
  };
61
86
  /**
62
- * @since 1.0.0
87
+ * Subscribes to an atom in the current React registry and returns its current
88
+ * value, optionally mapped through a selector.
89
+ *
63
90
  * @category hooks
91
+ * @since 4.0.0
64
92
  */
65
93
  export const useAtomValue = (atom, f) => {
66
94
  const registry = React.useContext(RegistryContext);
@@ -92,16 +120,21 @@ const flattenExit = exit => {
92
120
  throw Cause.squash(exit.cause);
93
121
  };
94
122
  /**
95
- * @since 1.0.0
123
+ * Mounts an atom in the current React registry for the lifetime of the
124
+ * component.
125
+ *
96
126
  * @category hooks
127
+ * @since 4.0.0
97
128
  */
98
129
  export const useAtomMount = atom => {
99
130
  const registry = React.useContext(RegistryContext);
100
131
  mountAtom(registry, atom);
101
132
  };
102
133
  /**
103
- * @since 1.0.0
134
+ * Mounts a writable atom and returns a setter without subscribing to its value.
135
+ *
104
136
  * @category hooks
137
+ * @since 4.0.0
105
138
  */
106
139
  export const useAtomSet = (atom, options) => {
107
140
  const registry = React.useContext(RegistryContext);
@@ -109,8 +142,11 @@ export const useAtomSet = (atom, options) => {
109
142
  return setAtom(registry, atom, options);
110
143
  };
111
144
  /**
112
- * @since 1.0.0
145
+ * Mounts an atom and returns a callback that refreshes it in the current React
146
+ * registry.
147
+ *
113
148
  * @category hooks
149
+ * @since 4.0.0
114
150
  */
115
151
  export const useAtomRefresh = atom => {
116
152
  const registry = React.useContext(RegistryContext);
@@ -120,8 +156,11 @@ export const useAtomRefresh = atom => {
120
156
  }, [registry, atom]);
121
157
  };
122
158
  /**
123
- * @since 1.0.0
159
+ * Subscribes to a writable atom and returns its current value together with a
160
+ * setter for updating it.
161
+ *
124
162
  * @category hooks
163
+ * @since 4.0.0
125
164
  */
126
165
  export const useAtom = (atom, options) => {
127
166
  const registry = React.useContext(RegistryContext);
@@ -158,8 +197,11 @@ function atomResultOrSuspend(registry, atom, suspendOnWaiting) {
158
197
  return value;
159
198
  }
160
199
  /**
161
- * @since 1.0.0
200
+ * Reads an `AsyncResult` atom through React Suspense, suspending while the
201
+ * result is initial or configured as waiting.
202
+ *
162
203
  * @category hooks
204
+ * @since 4.0.0
163
205
  */
164
206
  export const useAtomSuspense = (atom, options) => {
165
207
  const registry = React.useContext(RegistryContext);
@@ -170,16 +212,21 @@ export const useAtomSuspense = (atom, options) => {
170
212
  return result;
171
213
  };
172
214
  /**
173
- * @since 1.0.0
215
+ * Subscribes a callback to an atom in the current React registry for the
216
+ * component lifetime.
217
+ *
174
218
  * @category hooks
219
+ * @since 4.0.0
175
220
  */
176
221
  export const useAtomSubscribe = (atom, f, options) => {
177
222
  const registry = React.useContext(RegistryContext);
178
223
  React.useEffect(() => registry.subscribe(atom, f, options), [registry, atom, f, options?.immediate]);
179
224
  };
180
225
  /**
181
- * @since 1.0.0
226
+ * Subscribes to an atom ref and returns its latest value.
227
+ *
182
228
  * @category hooks
229
+ * @since 4.0.0
183
230
  */
184
231
  export const useAtomRef = ref => {
185
232
  const [, setValue] = React.useState(ref.value);
@@ -187,13 +234,18 @@ export const useAtomRef = ref => {
187
234
  return ref.value;
188
235
  };
189
236
  /**
190
- * @since 1.0.0
237
+ * Returns a memoized atom ref for a property of another atom ref.
238
+ *
191
239
  * @category hooks
240
+ * @since 4.0.0
192
241
  */
193
242
  export const useAtomRefProp = (ref, prop) => React.useMemo(() => ref.prop(prop), [ref, prop]);
194
243
  /**
195
- * @since 1.0.0
244
+ * Subscribes to a property ref derived from an atom ref and returns its current
245
+ * value.
246
+ *
196
247
  * @category hooks
248
+ * @since 4.0.0
197
249
  */
198
250
  export const useAtomRefPropValue = (ref, prop) => useAtomRef(useAtomRefProp(ref, prop));
199
251
  //# sourceMappingURL=Hooks.js.map
package/dist/Hooks.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"Hooks.js","names":["Cause","Effect","Exit","Atom","AtomRegistry","React","RegistryContext","storeRegistry","WeakMap","makeStore","registry","atom","stores","get","undefined","set","store","newStore","subscribe","f","snapshot","getServerSnapshot","getServerValue","useStore","useSyncExternalStore","initialValuesSet","useAtomInitialValues","initialValues","useContext","WeakSet","value","has","add","ensureNode","setValue","useAtomValue","atomB","useMemo","map","mountAtom","useEffect","mount","setAtom","options","mode","useCallback","promise","runPromiseExit","getResult","suspendOnWaiting","then","flattenExit","exit","isSuccess","squash","cause","useAtomMount","useAtomSet","useAtomRefresh","refresh","useAtom","atomPromiseMap","Map","default","atomToPromise","Promise","resolve","dispose","result","_tag","waiting","setTimeout","delete","atomResultOrSuspend","useAtomSuspense","includeFailure","useAtomSubscribe","immediate","useAtomRef","ref","useState","useAtomRefProp","prop","useAtomRefPropValue"],"sources":["../src/Hooks.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
1
+ {"version":3,"file":"Hooks.js","names":["Cause","Effect","Exit","Atom","AtomRegistry","React","RegistryContext","storeRegistry","WeakMap","makeStore","registry","atom","stores","get","undefined","set","store","newStore","subscribe","f","snapshot","getServerSnapshot","getServerValue","useStore","useSyncExternalStore","initialValuesSet","useAtomInitialValues","initialValues","useContext","WeakSet","value","has","add","ensureNode","setValue","useAtomValue","atomB","useMemo","map","mountAtom","useEffect","mount","setAtom","options","mode","useCallback","promise","runPromiseExit","getResult","suspendOnWaiting","then","flattenExit","exit","isSuccess","squash","cause","useAtomMount","useAtomSet","useAtomRefresh","refresh","useAtom","atomPromiseMap","Map","default","atomToPromise","Promise","resolve","dispose","result","_tag","waiting","setTimeout","delete","atomResultOrSuspend","useAtomSuspense","includeFailure","useAtomSubscribe","immediate","useAtomRef","ref","useState","useAtomRefProp","prop","useAtomRefPropValue"],"sources":["../src/Hooks.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
package/dist/ReactHydration.d.ts CHANGED
@@ -1,16 +1,26 @@
1
1
  import * as Hydration from "effect/unstable/reactivity/Hydration";
2
2
  import * as React from "react";
3
3
  /**
4
- * @since 1.0.0
4
+ * Props for a boundary that applies dehydrated Atom values to the nearest
5
+ * {@link RegistryContext} while rendering its children.
6
+ *
5
7
  * @category components
8
+ * @since 4.0.0
6
9
  */
7
10
  export interface HydrationBoundaryProps {
8
11
  state?: Iterable<Hydration.DehydratedAtom>;
9
12
  children?: React.ReactNode;
10
13
  }
11
14
  /**
12
- * @since 1.0.0
15
+ * Hydrates dehydrated Atom values into the current Atom registry for a React
16
+ * subtree.
17
+ *
18
+ * New Atom values are hydrated during render so descendants can read them
19
+ * immediately, while values for existing Atoms are deferred until after commit
20
+ * so transition data does not update the current UI before React accepts it.
21
+ *
13
22
  * @category components
23
+ * @since 4.0.0
14
24
  */
15
25
  export declare const HydrationBoundary: React.FC<HydrationBoundaryProps>;
16
26
  //# sourceMappingURL=ReactHydration.d.ts.map
package/dist/ReactHydration.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"ReactHydration.d.ts","sourceRoot":"","sources":["../src/ReactHydration.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,SAAS,MAAM,sCAAsC,CAAA;AACjE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,cAAc,CAAC,CAAA;IAC1C,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC3B;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC,sBAAsB,CA6D9D,CAAA"}
1
+ {"version":3,"file":"ReactHydration.d.ts","sourceRoot":"","sources":["../src/ReactHydration.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,SAAS,MAAM,sCAAsC,CAAA;AACjE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,cAAc,CAAC,CAAA;IAC1C,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC3B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC,sBAAsB,CA6D9D,CAAA"}
package/dist/ReactHydration.js CHANGED
@@ -1,5 +1,26 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * React helpers for hydrating Atom registry state that was serialized on the
3
+ * server or produced by a previous render. This module exposes
4
+ * {@link HydrationBoundary}, a client component that receives dehydrated Atom
5
+ * values and applies them to the nearest {@link RegistryContext} before
6
+ * rendering children when it is safe to do so.
7
+ *
8
+ * **Common use cases**
9
+ *
10
+ * - Reusing Atom values that were collected during server rendering
11
+ * - Restoring client-side Atom state around a routed subtree
12
+ * - Keeping Atom-backed React trees consistent during hydration and transitions
13
+ *
14
+ * **React gotchas**
15
+ *
16
+ * - New Atom values can be hydrated during render so children see them
17
+ * immediately.
18
+ * - Existing Atom values are queued until after commit to avoid updating the
19
+ * current UI with transition data that might later be discarded.
20
+ * - Hydration is idempotent, so repeated or older dehydrated values are safe to
21
+ * pass through the boundary.
22
+ *
23
+ * @since 4.0.0
3
24
  */
4
25
  "use client";
5
26
 
@@ -7,8 +28,15 @@ import * as Hydration from "effect/unstable/reactivity/Hydration";
7
28
  import * as React from "react";
8
29
  import { RegistryContext } from "./RegistryContext.js";
9
30
  /**
10
- * @since 1.0.0
31
+ * Hydrates dehydrated Atom values into the current Atom registry for a React
32
+ * subtree.
33
+ *
34
+ * New Atom values are hydrated during render so descendants can read them
35
+ * immediately, while values for existing Atoms are deferred until after commit
36
+ * so transition data does not update the current UI before React accepts it.
37
+ *
11
38
  * @category components
39
+ * @since 4.0.0
12
40
  */
13
41
  export const HydrationBoundary = ({
14
42
  children,
package/dist/ReactHydration.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"ReactHydration.js","names":["Hydration","React","RegistryContext","HydrationBoundary","children","state","registry","useContext","hydrationQueue","useMemo","dehydratedAtoms","Array","from","nodes","getNodes","newDehydratedAtoms","existingDehydratedAtoms","dehydratedAtom","existingNode","get","key","push","length","hydrate","undefined","useEffect","createElement","Fragment"],"sources":["../src/ReactHydration.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAGA,YAAY;;AACZ,OAAO,KAAKA,SAAS,MAAM,sCAAsC;AACjE,OAAO,KAAKC,KAAK,MAAM,OAAO;AAC9B,SAASC,eAAe,QAAQ,sBAAsB;AAWtD;;;;AAIA,OAAO,MAAMC,iBAAiB,GAAqCA,CAAC;EAClEC,QAAQ;EACRC;AAAK,CACN,KAAI;EACH,MAAMC,QAAQ,GAAGL,KAAK,CAACM,UAAU,CAACL,eAAe,CAAC;EAElD;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,MAAMM,cAAc,GAAqDP,KAAK,CAACQ,OAAO,CAAC,MAAK;IAC1F,IAAIJ,KAAK,EAAE;MACT,MAAMK,eAAe,GAAGC,KAAK,CAACC,IAAI,CAACP,KAAK,CAAyC;MACjF,MAAMQ,KAAK,GAAGP,QAAQ,CAACQ,QAAQ,EAAE;MAEjC,MAAMC,kBAAkB,GAAyC,EAAE;MACnE,MAAMC,uBAAuB,GAAyC,EAAE;MAExE,KAAK,MAAMC,cAAc,IAAIP,eAAe,EAAE;QAC5C,MAAMQ,YAAY,GAAGL,KAAK,CAACM,GAAG,CAACF,cAAc,CAACG,GAAG,CAAC;QAElD,IAAI,CAACF,YAAY,EAAE;UACjB;UACAH,kBAAkB,CAACM,IAAI,CAACJ,cAAc,CAAC;QACzC,CAAC,MAAM;UACL;UACAD,uBAAuB,CAACK,IAAI,CAACJ,cAAc,CAAC;QAC9C;MACF;MAEA,IAAIF,kBAAkB,CAACO,MAAM,GAAG,CAAC,EAAE;QACjC;QACA;QACAtB,SAAS,CAACuB,OAAO,CAACjB,QAAQ,EAAES,kBAAkB,CAAC;MACjD;MAEA,IAAIC,uBAAuB,CAACM,MAAM,GAAG,CAAC,EAAE;QACtC,OAAON,uBAAuB;MAChC;IACF;IACA,OAAOQ,SAAS;EAClB,CAAC,EAAE,CAAClB,QAAQ,EAAED,KAAK,CAAC,CAAC;EAErBJ,KAAK,CAACwB,SAAS,CAAC,MAAK;IACnB,IAAIjB,cAAc,EAAE;MAClBR,SAAS,CAACuB,OAAO,CAACjB,QAAQ,EAAEE,cAAc,CAAC;IAC7C;EACF,CAAC,EAAE,CAACF,QAAQ,EAAEE,cAAc,CAAC,CAAC;EAE9B,OAAOP,KAAK,CAACyB,aAAa,CAACzB,KAAK,CAAC0B,QAAQ,EAAE,EAAE,EAAEvB,QAAQ,CAAC;AAC1D,CAAC","ignoreList":[]}
1
+ {"version":3,"file":"ReactHydration.js","names":["Hydration","React","RegistryContext","HydrationBoundary","children","state","registry","useContext","hydrationQueue","useMemo","dehydratedAtoms","Array","from","nodes","getNodes","newDehydratedAtoms","existingDehydratedAtoms","dehydratedAtom","existingNode","get","key","push","length","hydrate","undefined","useEffect","createElement","Fragment"],"sources":["../src/ReactHydration.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,YAAY;;AACZ,OAAO,KAAKA,SAAS,MAAM,sCAAsC;AACjE,OAAO,KAAKC,KAAK,MAAM,OAAO;AAC9B,SAASC,eAAe,QAAQ,sBAAsB;AActD;;;;;;;;;;;AAWA,OAAO,MAAMC,iBAAiB,GAAqCA,CAAC;EAClEC,QAAQ;EACRC;AAAK,CACN,KAAI;EACH,MAAMC,QAAQ,GAAGL,KAAK,CAACM,UAAU,CAACL,eAAe,CAAC;EAElD;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,MAAMM,cAAc,GAAqDP,KAAK,CAACQ,OAAO,CAAC,MAAK;IAC1F,IAAIJ,KAAK,EAAE;MACT,MAAMK,eAAe,GAAGC,KAAK,CAACC,IAAI,CAACP,KAAK,CAAyC;MACjF,MAAMQ,KAAK,GAAGP,QAAQ,CAACQ,QAAQ,EAAE;MAEjC,MAAMC,kBAAkB,GAAyC,EAAE;MACnE,MAAMC,uBAAuB,GAAyC,EAAE;MAExE,KAAK,MAAMC,cAAc,IAAIP,eAAe,EAAE;QAC5C,MAAMQ,YAAY,GAAGL,KAAK,CAACM,GAAG,CAACF,cAAc,CAACG,GAAG,CAAC;QAElD,IAAI,CAACF,YAAY,EAAE;UACjB;UACAH,kBAAkB,CAACM,IAAI,CAACJ,cAAc,CAAC;QACzC,CAAC,MAAM;UACL;UACAD,uBAAuB,CAACK,IAAI,CAACJ,cAAc,CAAC;QAC9C;MACF;MAEA,IAAIF,kBAAkB,CAACO,MAAM,GAAG,CAAC,EAAE;QACjC;QACA;QACAtB,SAAS,CAACuB,OAAO,CAACjB,QAAQ,EAAES,kBAAkB,CAAC;MACjD;MAEA,IAAIC,uBAAuB,CAACM,MAAM,GAAG,CAAC,EAAE;QACtC,OAAON,uBAAuB;MAChC;IACF;IACA,OAAOQ,SAAS;EAClB,CAAC,EAAE,CAAClB,QAAQ,EAAED,KAAK,CAAC,CAAC;EAErBJ,KAAK,CAACwB,SAAS,CAAC,MAAK;IACnB,IAAIjB,cAAc,EAAE;MAClBR,SAAS,CAACuB,OAAO,CAACjB,QAAQ,EAAEE,cAAc,CAAC;IAC7C;EACF,CAAC,EAAE,CAACF,QAAQ,EAAEE,cAAc,CAAC,CAAC;EAE9B,OAAOP,KAAK,CAACyB,aAAa,CAACzB,KAAK,CAAC0B,QAAQ,EAAE,EAAE,EAAEvB,QAAQ,CAAC;AAC1D,CAAC","ignoreList":[]}
package/dist/RegistryContext.d.ts CHANGED
@@ -2,18 +2,28 @@ import type * as Atom from "effect/unstable/reactivity/Atom";
2
2
  import * as AtomRegistry from "effect/unstable/reactivity/AtomRegistry";
3
3
  import * as React from "react";
4
4
  /**
5
- * @since 1.0.0
5
+ * Schedules Atom registry work with React's scheduler at low priority and
6
+ * returns a cancellation function for the scheduled task.
7
+ *
6
8
  * @category context
9
+ * @since 4.0.0
7
10
  */
8
11
  export declare function scheduleTask(f: () => void): () => void;
9
12
  /**
10
- * @since 1.0.0
13
+ * React context that supplies the `AtomRegistry` used by Atom hooks and
14
+ * hydration helpers, defaulting to a standalone registry when no provider is
15
+ * present.
16
+ *
11
17
  * @category context
18
+ * @since 4.0.0
12
19
  */
13
20
  export declare const RegistryContext: React.Context<AtomRegistry.AtomRegistry>;
14
21
  /**
15
- * @since 1.0.0
22
+ * Provides a stable `AtomRegistry` to a React subtree, optionally seeding
23
+ * initial atom values and overriding registry scheduling or idle settings.
24
+ *
16
25
  * @category context
26
+ * @since 4.0.0
17
27
  */
18
28
  export declare const RegistryProvider: (options: {
19
29
  readonly children?: React.ReactNode | undefined;
package/dist/RegistryContext.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"RegistryContext.d.ts","sourceRoot":"","sources":["../src/RegistryContext.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,KAAK,IAAI,MAAM,iCAAiC,CAAA;AAC5D,OAAO,KAAK,YAAY,MAAM,yCAAyC,CAAA;AACvE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAGtD;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,0CAGzB,CAAA;AAEH;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,CAAA;IAC/C,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,SAAS,CAAA;IAC7E,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC,GAAG,SAAS,CAAA;IACnE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7C,mFA2BA,CAAA"}
1
+ {"version":3,"file":"RegistryContext.d.ts","sourceRoot":"","sources":["../src/RegistryContext.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,KAAK,IAAI,MAAM,iCAAiC,CAAA;AAC5D,OAAO,KAAK,YAAY,MAAM,yCAAyC,CAAA;AACvE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAGtD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,0CAGzB,CAAA;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,CAAA;IAC/C,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,SAAS,CAAA;IAC7E,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC,GAAG,SAAS,CAAA;IACnE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7C,mFA2BA,CAAA"}
package/dist/RegistryContext.js CHANGED
@@ -1,5 +1,27 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * The `RegistryContext` module provides the React context used by Effect Atom
3
+ * hooks to share an `AtomRegistry` across a component tree. The registry owns
4
+ * atom state, scheduling, and idle cleanup, so components that read or write
5
+ * atoms can coordinate through the same runtime instead of each creating an
6
+ * isolated registry.
7
+ *
8
+ * **Common tasks**
9
+ *
10
+ * - Use {@link RegistryProvider} to scope atom state to a React subtree
11
+ * - Seed atoms for tests, stories, or server-provided data with `initialValues`
12
+ * - Override scheduling or idle timing for custom rendering environments
13
+ * - Read {@link RegistryContext} when integrating lower-level atom APIs
14
+ *
15
+ * **Gotchas**
16
+ *
17
+ * - This is a client module because it depends on React runtime hooks and the
18
+ * scheduler package
19
+ * - A provider keeps the registry stable across renders and disposes it shortly
20
+ * after unmount, allowing React remounts to reuse the same registry
21
+ * - Overriding `scheduleTask` changes when atom work is flushed, so it should
22
+ * return a cancellation function compatible with React unmounts
23
+ *
24
+ * @since 4.0.0
3
25
  */
4
26
  "use client";
5
27
 
@@ -7,24 +29,34 @@ import * as AtomRegistry from "effect/unstable/reactivity/AtomRegistry";
7
29
  import * as React from "react";
8
30
  import * as Scheduler from "scheduler";
9
31
  /**
10
- * @since 1.0.0
32
+ * Schedules Atom registry work with React's scheduler at low priority and
33
+ * returns a cancellation function for the scheduled task.
34
+ *
11
35
  * @category context
36
+ * @since 4.0.0
12
37
  */
13
38
  export function scheduleTask(f) {
14
39
  const node = Scheduler.unstable_scheduleCallback(Scheduler.unstable_LowPriority, f);
15
40
  return () => Scheduler.unstable_cancelCallback(node);
16
41
  }
17
42
  /**
18
- * @since 1.0.0
43
+ * React context that supplies the `AtomRegistry` used by Atom hooks and
44
+ * hydration helpers, defaulting to a standalone registry when no provider is
45
+ * present.
46
+ *
19
47
  * @category context
48
+ * @since 4.0.0
20
49
  */
21
50
  export const RegistryContext = /*#__PURE__*/React.createContext(/*#__PURE__*/AtomRegistry.make({
22
51
  scheduleTask,
23
52
  defaultIdleTTL: 400
24
53
  }));
25
54
  /**
26
- * @since 1.0.0
55
+ * Provides a stable `AtomRegistry` to a React subtree, optionally seeding
56
+ * initial atom values and overriding registry scheduling or idle settings.
57
+ *
27
58
  * @category context
59
+ * @since 4.0.0
28
60
  */
29
61
  export const RegistryProvider = options => {
30
62
  const ref = React.useRef(null);
package/dist/RegistryContext.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"RegistryContext.js","names":["AtomRegistry","React","Scheduler","scheduleTask","f","node","unstable_scheduleCallback","unstable_LowPriority","unstable_cancelCallback","RegistryContext","createContext","make","defaultIdleTTL","RegistryProvider","options","ref","useRef","current","registry","initialValues","timeoutResolution","useEffect","timeout","undefined","clearTimeout","setTimeout","dispose","createElement","Provider","value","children"],"sources":["../src/RegistryContext.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAGA,YAAY;;AAGZ,OAAO,KAAKA,YAAY,MAAM,yCAAyC;AACvE,OAAO,KAAKC,KAAK,MAAM,OAAO;AAC9B,OAAO,KAAKC,SAAS,MAAM,WAAW;AAEtC;;;;AAIA,OAAM,SAAUC,YAAYA,CAACC,CAAa;EACxC,MAAMC,IAAI,GAAGH,SAAS,CAACI,yBAAyB,CAACJ,SAAS,CAACK,oBAAoB,EAAEH,CAAC,CAAC;EACnF,OAAO,MAAMF,SAAS,CAACM,uBAAuB,CAACH,IAAI,CAAC;AACtD;AAEA;;;;AAIA,OAAO,MAAMI,eAAe,gBAAGR,KAAK,CAACS,aAAa,cAA4BV,YAAY,CAACW,IAAI,CAAC;EAC9FR,YAAY;EACZS,cAAc,EAAE;CACjB,CAAC,CAAC;AAEH;;;;AAIA,OAAO,MAAMC,gBAAgB,GAAIC,OAMhC,IAAI;EACH,MAAMC,GAAG,GAAGd,KAAK,CAACe,MAAM,CAGrB,IAAI,CAAC;EACR,IAAID,GAAG,CAACE,OAAO,KAAK,IAAI,EAAE;IACxBF,GAAG,CAACE,OAAO,GAAG;MACZC,QAAQ,EAAElB,YAAY,CAACW,IAAI,CAAC;QAC1BR,YAAY,EAAEW,OAAO,CAACX,YAAY,IAAIA,YAAY;QAClDgB,aAAa,EAAEL,OAAO,CAACK,aAAa;QACpCC,iBAAiB,EAAEN,OAAO,CAACM,iBAAiB;QAC5CR,cAAc,EAAEE,OAAO,CAACF;OACzB;KACF;EACH;EACAX,KAAK,CAACoB,SAAS,CAAC,MAAK;IACnB,IAAIN,GAAG,CAACE,OAAO,EAAEK,OAAO,KAAKC,SAAS,EAAE;MACtCC,YAAY,CAACT,GAAG,CAACE,OAAO,CAACK,OAAO,CAAC;IACnC;IACA,OAAO,MAAK;MACVP,GAAG,CAACE,OAAQ,CAACK,OAAO,GAAGG,UAAU,CAAC,MAAK;QACrCV,GAAG,CAACE,OAAO,EAAEC,QAAQ,CAACQ,OAAO,EAAE;QAC/BX,GAAG,CAACE,OAAO,GAAG,IAAI;MACpB,CAAC,EAAE,GAAG,CAAQ;IAChB,CAAC;EACH,CAAC,EAAE,CAACF,GAAG,CAAC,CAAC;EACT,OAAOd,KAAK,CAAC0B,aAAa,CAAClB,eAAe,CAACmB,QAAQ,EAAE;IAAEC,KAAK,EAAEd,GAAG,CAACE,OAAO,CAACC;EAAQ,CAAE,EAAEJ,OAAO,EAAEgB,QAAQ,CAAC;AAC1G,CAAC","ignoreList":[]}
1
+ {"version":3,"file":"RegistryContext.js","names":["AtomRegistry","React","Scheduler","scheduleTask","f","node","unstable_scheduleCallback","unstable_LowPriority","unstable_cancelCallback","RegistryContext","createContext","make","defaultIdleTTL","RegistryProvider","options","ref","useRef","current","registry","initialValues","timeoutResolution","useEffect","timeout","undefined","clearTimeout","setTimeout","dispose","createElement","Provider","value","children"],"sources":["../src/RegistryContext.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,YAAY;;AAGZ,OAAO,KAAKA,YAAY,MAAM,yCAAyC;AACvE,OAAO,KAAKC,KAAK,MAAM,OAAO;AAC9B,OAAO,KAAKC,SAAS,MAAM,WAAW;AAEtC;;;;;;;AAOA,OAAM,SAAUC,YAAYA,CAACC,CAAa;EACxC,MAAMC,IAAI,GAAGH,SAAS,CAACI,yBAAyB,CAACJ,SAAS,CAACK,oBAAoB,EAAEH,CAAC,CAAC;EACnF,OAAO,MAAMF,SAAS,CAACM,uBAAuB,CAACH,IAAI,CAAC;AACtD;AAEA;;;;;;;;AAQA,OAAO,MAAMI,eAAe,gBAAGR,KAAK,CAACS,aAAa,cAA4BV,YAAY,CAACW,IAAI,CAAC;EAC9FR,YAAY;EACZS,cAAc,EAAE;CACjB,CAAC,CAAC;AAEH;;;;;;;AAOA,OAAO,MAAMC,gBAAgB,GAAIC,OAMhC,IAAI;EACH,MAAMC,GAAG,GAAGd,KAAK,CAACe,MAAM,CAGrB,IAAI,CAAC;EACR,IAAID,GAAG,CAACE,OAAO,KAAK,IAAI,EAAE;IACxBF,GAAG,CAACE,OAAO,GAAG;MACZC,QAAQ,EAAElB,YAAY,CAACW,IAAI,CAAC;QAC1BR,YAAY,EAAEW,OAAO,CAACX,YAAY,IAAIA,YAAY;QAClDgB,aAAa,EAAEL,OAAO,CAACK,aAAa;QACpCC,iBAAiB,EAAEN,OAAO,CAACM,iBAAiB;QAC5CR,cAAc,EAAEE,OAAO,CAACF;OACzB;KACF;EACH;EACAX,KAAK,CAACoB,SAAS,CAAC,MAAK;IACnB,IAAIN,GAAG,CAACE,OAAO,EAAEK,OAAO,KAAKC,SAAS,EAAE;MACtCC,YAAY,CAACT,GAAG,CAACE,OAAO,CAACK,OAAO,CAAC;IACnC;IACA,OAAO,MAAK;MACVP,GAAG,CAACE,OAAQ,CAACK,OAAO,GAAGG,UAAU,CAAC,MAAK;QACrCV,GAAG,CAACE,OAAO,EAAEC,QAAQ,CAACQ,OAAO,EAAE;QAC/BX,GAAG,CAACE,OAAO,GAAG,IAAI;MACpB,CAAC,EAAE,GAAG,CAAQ;IAChB,CAAC;EACH,CAAC,EAAE,CAACF,GAAG,CAAC,CAAC;EACT,OAAOd,KAAK,CAAC0B,aAAa,CAAClB,eAAe,CAACmB,QAAQ,EAAE;IAAEC,KAAK,EAAEd,GAAG,CAACE,OAAO,CAACC;EAAQ,CAAE,EAAEJ,OAAO,EAAEgB,QAAQ,CAAC;AAC1G,CAAC","ignoreList":[]}
package/dist/ScopedAtom.d.ts CHANGED
@@ -1,37 +1,34 @@
1
1
  import type * as Atom from "effect/unstable/reactivity/Atom";
2
2
  import * as React from "react";
3
3
  /**
4
- * @since 1.0.0
5
- * @category Type IDs
6
- *
7
4
  * Type identifier for ScopedAtom.
5
+ *
6
+ * @category type IDs
7
+ * @since 4.0.0
8
8
  */
9
9
  export type TypeId = "~@effect/atom-react/ScopedAtom";
10
10
  /**
11
- * @since 1.0.0
12
- * @category Type IDs
13
- *
14
11
  * Type identifier for ScopedAtom.
12
+ *
13
+ * @category type IDs
14
+ * @since 4.0.0
15
15
  */
16
16
  export declare const TypeId: TypeId;
17
17
  /**
18
- * @since 1.0.0
19
- * @category models
20
- *
21
18
  * Scoped Atom interface with a provider-backed instance.
22
19
  *
23
- * @example
20
+ * **Example** (Providing and reading a scoped atom)
21
+ *
24
22
  * ```ts
25
- * import * as Atom from "effect/unstable/reactivity/Atom"
23
+ * import * as AtomReact from "@effect/atom-react"
24
+ * import { Atom } from "effect/unstable/reactivity"
26
25
  * import * as React from "react"
27
- * import * as ScopedAtom from "@effect/atom-react/ScopedAtom"
28
- * import { useAtomValue } from "@effect/atom-react"
29
26
  *
30
- * const Counter = ScopedAtom.make(() => Atom.make(0))
27
+ * const Counter = AtomReact.make(() => Atom.make(0))
31
28
  *
32
29
  * function View() {
33
30
  * const atom = Counter.use()
34
- * const value = useAtomValue(atom)
31
+ * const value = AtomReact.useAtomValue(atom)
35
32
  * return React.createElement("div", null, value)
36
33
  * }
37
34
  *
@@ -39,6 +36,9 @@ export declare const TypeId: TypeId;
39
36
  * return React.createElement(Counter.Provider, null, React.createElement(View))
40
37
  * }
41
38
  * ```
39
+ *
40
+ * @category models
41
+ * @since 4.0.0
42
42
  */
43
43
  export interface ScopedAtom<A extends Atom.Atom<any>, Input = never> {
44
44
  readonly [TypeId]: TypeId;
@@ -52,23 +52,20 @@ export interface ScopedAtom<A extends Atom.Atom<any>, Input = never> {
52
52
  Context: React.Context<A>;
53
53
  }
54
54
  /**
55
- * @since 1.0.0
56
- * @category constructors
57
- *
58
55
  * Creates a ScopedAtom from a factory function.
59
56
  *
60
- * @example
57
+ * **Example** (Creating a scoped atom with input)
58
+ *
61
59
  * ```ts
62
- * import * as Atom from "effect/unstable/reactivity/Atom"
60
+ * import * as AtomReact from "@effect/atom-react"
61
+ * import { Atom } from "effect/unstable/reactivity"
63
62
  * import * as React from "react"
64
- * import * as ScopedAtom from "@effect/atom-react/ScopedAtom"
65
- * import { useAtomValue } from "@effect/atom-react"
66
63
  *
67
- * const User = ScopedAtom.make((name: string) => Atom.make(name))
64
+ * const User = AtomReact.make((name: string) => Atom.make(name))
68
65
  *
69
66
  * function UserName() {
70
67
  * const atom = User.use()
71
- * const value = useAtomValue(atom)
68
+ * const value = AtomReact.useAtomValue(atom)
72
69
  * return React.createElement("span", null, value)
73
70
  * }
74
71
  *
@@ -80,6 +77,9 @@ export interface ScopedAtom<A extends Atom.Atom<any>, Input = never> {
80
77
  * )
81
78
  * }
82
79
  * ```
80
+ *
81
+ * @category constructors
82
+ * @since 4.0.0
83
83
  */
84
84
  export declare const make: <A extends Atom.Atom<any>, Input = never>(f: (() => A) | ((input: Input) => A)) => ScopedAtom<A, Input>;
85
85
  //# sourceMappingURL=ScopedAtom.d.ts.map
package/dist/ScopedAtom.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"ScopedAtom.d.ts","sourceRoot":"","sources":["../src/ScopedAtom.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,KAAK,IAAI,MAAM,iCAAiC,CAAA;AAC5D,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,gCAAgC,CAAA;AAErD;;;;;GAKG;AACH,eAAO,MAAM,MAAM,EAAE,MAAyC,CAAA;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK;IACjE,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACzB,GAAG,IAAI,CAAC,CAAA;IACR,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,CAAA;KAAE,CAAC,GAC7F,KAAK,CAAC,EAAE,CAAC;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC,CAAA;IACxF,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,EAC1D,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,CAAC,CAAC,KACnC,UAAU,CAAC,CAAC,EAAE,KAAK,CA6BrB,CAAA"}
1
+ {"version":3,"file":"ScopedAtom.d.ts","sourceRoot":"","sources":["../src/ScopedAtom.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,KAAK,IAAI,MAAM,iCAAiC,CAAA;AAC5D,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,gCAAgC,CAAA;AAErD;;;;;GAKG;AACH,eAAO,MAAM,MAAM,EAAE,MAAyC,CAAA;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK;IACjE,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACzB,GAAG,IAAI,CAAC,CAAA;IACR,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,CAAA;KAAE,CAAC,GAC7F,KAAK,CAAC,EAAE,CAAC;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC,CAAA;IACxF,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,EAC1D,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,CAAC,CAAC,KACnC,UAAU,CAAC,CAAC,EAAE,KAAK,CA6BrB,CAAA"}
package/dist/ScopedAtom.js CHANGED
@@ -1,34 +1,48 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * The `ScopedAtom` module provides a small React integration for creating atom
3
+ * instances that are scoped to a component subtree. A scoped atom bundles a
4
+ * React provider, context, and `use` accessor so each mounted provider owns its
5
+ * own atom instance instead of sharing a single module-level atom.
6
+ *
7
+ * Use `ScopedAtom` when an atom needs to be isolated per feature, route,
8
+ * component instance, test harness, or provider input. The provider may receive
9
+ * an initial `value` that is passed to the atom factory, making it useful for
10
+ * state that should be seeded from React props while still being consumed by the
11
+ * atom hooks in descendants.
12
+ *
13
+ * **Gotchas**
14
+ *
15
+ * - `use` must be called under the matching provider or it throws.
16
+ * - The provider creates the atom once for its lifetime; changing the provider
17
+ * `value` prop after mount does not recreate the atom.
18
+ *
19
+ * @since 4.0.0
3
20
  */
4
21
  "use client";
5
22
 
6
23
  import * as React from "react";
7
24
  /**
8
- * @since 1.0.0
9
- * @category Type IDs
10
- *
11
25
  * Type identifier for ScopedAtom.
26
+ *
27
+ * @category type IDs
28
+ * @since 4.0.0
12
29
  */
13
30
  export const TypeId = "~@effect/atom-react/ScopedAtom";
14
31
  /**
15
- * @since 1.0.0
16
- * @category constructors
17
- *
18
32
  * Creates a ScopedAtom from a factory function.
19
33
  *
20
- * @example
34
+ * **Example** (Creating a scoped atom with input)
35
+ *
21
36
  * ```ts
22
- * import * as Atom from "effect/unstable/reactivity/Atom"
37
+ * import * as AtomReact from "@effect/atom-react"
38
+ * import { Atom } from "effect/unstable/reactivity"
23
39
  * import * as React from "react"
24
- * import * as ScopedAtom from "@effect/atom-react/ScopedAtom"
25
- * import { useAtomValue } from "@effect/atom-react"
26
40
  *
27
- * const User = ScopedAtom.make((name: string) => Atom.make(name))
41
+ * const User = AtomReact.make((name: string) => Atom.make(name))
28
42
  *
29
43
  * function UserName() {
30
44
  * const atom = User.use()
31
- * const value = useAtomValue(atom)
45
+ * const value = AtomReact.useAtomValue(atom)
32
46
  * return React.createElement("span", null, value)
33
47
  * }
34
48
  *
@@ -40,6 +54,9 @@ export const TypeId = "~@effect/atom-react/ScopedAtom";
40
54
  * )
41
55
  * }
42
56
  * ```
57
+ *
58
+ * @category constructors
59
+ * @since 4.0.0
43
60
  */
44
61
  export const make = f => {
45
62
  const Context = React.createContext(undefined);
package/dist/ScopedAtom.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"ScopedAtom.js","names":["React","TypeId","make","f","Context","createContext","undefined","use","atom","useContext","Error","Provider","props","useRef","current","value","createElement","children"],"sources":["../src/ScopedAtom.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAGA,YAAY;;AAGZ,OAAO,KAAKA,KAAK,MAAM,OAAO;AAU9B;;;;;;AAMA,OAAO,MAAMC,MAAM,GAAW,gCAAgC;AAoC9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,OAAO,MAAMC,IAAI,GACfC,CAAoC,IACZ;EACxB,MAAMC,OAAO,GAAGJ,KAAK,CAACK,aAAa,CAAIC,SAAyB,CAAC;EAEjE,MAAMC,GAAG,GAAGA,CAAA,KAAQ;IAClB,MAAMC,IAAI,GAAGR,KAAK,CAACS,UAAU,CAACL,OAAO,CAAC;IACtC,IAAII,IAAI,KAAKF,SAAS,EAAE;MACtB,MAAM,IAAII,KAAK,CAAC,yCAAyC,CAAC;IAC5D;IACA,OAAOF,IAAI;EACb,CAAC;EAED,MAAMG,QAAQ,GAA2FC,KAAK,IAAI;IAChH,MAAMJ,IAAI,GAAGR,KAAK,CAACa,MAAM,CAAW,IAAI,CAAC;IACzC,IAAIL,IAAI,CAACM,OAAO,KAAK,IAAI,EAAE;MACzB,IAAI,OAAO,IAAIF,KAAK,EAAE;QACpBJ,IAAI,CAACM,OAAO,GAAIX,CAAyB,CAACS,KAAK,CAACG,KAAc,CAAC;MACjE,CAAC,MAAM;QACLP,IAAI,CAACM,OAAO,GAAIX,CAAa,EAAE;MACjC;IACF;IACA,OAAOH,KAAK,CAACgB,aAAa,CAACZ,OAAO,CAACO,QAAQ,EAAE;MAAEI,KAAK,EAAEP,IAAI,CAACM;IAAO,CAAE,EAAEF,KAAK,CAACK,QAAQ,CAAC;EACvF,CAAC;EAED,OAAO;IACL,CAAChB,MAAM,GAAGA,MAAM;IAChBM,GAAG;IACHI,QAAQ,EAAEA,QAAe;IACzBP;GACD;AACH,CAAC","ignoreList":[]}
1
+ {"version":3,"file":"ScopedAtom.js","names":["React","TypeId","make","f","Context","createContext","undefined","use","atom","useContext","Error","Provider","props","useRef","current","value","createElement","children"],"sources":["../src/ScopedAtom.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;AAoBA,YAAY;;AAGZ,OAAO,KAAKA,KAAK,MAAM,OAAO;AAU9B;;;;;;AAMA,OAAO,MAAMC,MAAM,GAAW,gCAAgC;AAoC9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,OAAO,MAAMC,IAAI,GACfC,CAAoC,IACZ;EACxB,MAAMC,OAAO,GAAGJ,KAAK,CAACK,aAAa,CAAIC,SAAyB,CAAC;EAEjE,MAAMC,GAAG,GAAGA,CAAA,KAAQ;IAClB,MAAMC,IAAI,GAAGR,KAAK,CAACS,UAAU,CAACL,OAAO,CAAC;IACtC,IAAII,IAAI,KAAKF,SAAS,EAAE;MACtB,MAAM,IAAII,KAAK,CAAC,yCAAyC,CAAC;IAC5D;IACA,OAAOF,IAAI;EACb,CAAC;EAED,MAAMG,QAAQ,GAA2FC,KAAK,IAAI;IAChH,MAAMJ,IAAI,GAAGR,KAAK,CAACa,MAAM,CAAW,IAAI,CAAC;IACzC,IAAIL,IAAI,CAACM,OAAO,KAAK,IAAI,EAAE;MACzB,IAAI,OAAO,IAAIF,KAAK,EAAE;QACpBJ,IAAI,CAACM,OAAO,GAAIX,CAAyB,CAACS,KAAK,CAACG,KAAc,CAAC;MACjE,CAAC,MAAM;QACLP,IAAI,CAACM,OAAO,GAAIX,CAAa,EAAE;MACjC;IACF;IACA,OAAOH,KAAK,CAACgB,aAAa,CAACZ,OAAO,CAACO,QAAQ,EAAE;MAAEI,KAAK,EAAEP,IAAI,CAACM;IAAO,CAAE,EAAEF,KAAK,CAACK,QAAQ,CAAC;EACvF,CAAC;EAED,OAAO;IACL,CAAChB,MAAM,GAAGA,MAAM;IAChBM,GAAG;IACHI,QAAQ,EAAEA,QAAe;IACzBP;GACD;AACH,CAAC","ignoreList":[]}
package/dist/index.d.ts CHANGED
@@ -1,20 +1,20 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * @since 4.0.0
3
3
  */
4
4
  /**
5
- * @since 1.0.0
5
+ * @since 4.0.0
6
6
  */
7
7
  export * from "./Hooks.ts";
8
8
  /**
9
- * @since 1.0.0
9
+ * @since 4.0.0
10
10
  */
11
11
  export * from "./RegistryContext.ts";
12
12
  /**
13
- * @since 1.0.0
13
+ * @since 4.0.0
14
14
  */
15
15
  export * from "./ReactHydration.ts";
16
16
  /**
17
- * @since 1.0.0
17
+ * @since 4.0.0
18
18
  */
19
19
  export * from "./ScopedAtom.ts";
20
20
  //# sourceMappingURL=index.d.ts.map
package/dist/index.js CHANGED
@@ -1,20 +1,20 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * @since 4.0.0
3
3
  */
4
4
  /**
5
- * @since 1.0.0
5
+ * @since 4.0.0
6
6
  */
7
7
  export * from "./Hooks.js";
8
8
  /**
9
- * @since 1.0.0
9
+ * @since 4.0.0
10
10
  */
11
11
  export * from "./RegistryContext.js";
12
12
  /**
13
- * @since 1.0.0
13
+ * @since 4.0.0
14
14
  */
15
15
  export * from "./ReactHydration.js";
16
16
  /**
17
- * @since 1.0.0
17
+ * @since 4.0.0
18
18
  */
19
19
  export * from "./ScopedAtom.js";
20
20
  //# sourceMappingURL=index.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@effect/atom-react",
3
- "version": "4.0.0-beta.66",
3
+ "version": "4.0.0-beta.68",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "description": "React bindings for the Effect Atom modules",
@@ -45,7 +45,7 @@
45
45
  "peerDependencies": {
46
46
  "react": "^19.2.4",
47
47
  "scheduler": "*",
48
- "effect": "^4.0.0-beta.66"
48
+ "effect": "^4.0.0-beta.68"
49
49
  },
50
50
  "devDependencies": {
51
51
  "@testing-library/dom": "^10.4.1",
@@ -54,12 +54,12 @@
54
54
  "@types/react": "^19.2.14",
55
55
  "@types/react-dom": "^19.2.2",
56
56
  "@types/scheduler": "^0.26.0",
57
- "jsdom": "^29.0.2",
58
- "react": "19.2.5",
59
- "react-dom": "19.2.5",
57
+ "jsdom": "^29.1.1",
58
+ "react": "19.2.6",
59
+ "react-dom": "19.2.6",
60
60
  "react-error-boundary": "^6.1.1",
61
61
  "scheduler": "^0.27.0",
62
- "effect": "^4.0.0-beta.66"
62
+ "effect": "^4.0.0-beta.68"
63
63
  },
64
64
  "scripts": {
65
65
  "build": "tsc -b tsconfig.json && pnpm babel",
package/src/Hooks.ts CHANGED
@@ -1,5 +1,23 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * React hooks for reading, writing, mounting, refreshing, and subscribing to
3
+ * Effect atoms from the registry provided by `RegistryContext`.
4
+ *
5
+ * **Common tasks**
6
+ *
7
+ * - Read atom values in React components with {@link useAtomValue}
8
+ * - Read and write writable atoms with {@link useAtom}
9
+ * - Write without subscribing to the value with {@link useAtomSet}
10
+ * - Seed registry-local initial values with {@link useAtomInitialValues}
11
+ * - Integrate `AsyncResult` atoms with React Suspense through {@link useAtomSuspense}
12
+ * - Subscribe to atom changes or derive stable `AtomRef` properties
13
+ *
14
+ * **Gotchas**
15
+ *
16
+ * - Hooks use the current `RegistryContext`, so each provider has an independent atom registry
17
+ * - Writable atoms are mounted by the write-oriented hooks before updates are sent
18
+ * - Suspense support throws promises for initial or waiting `AsyncResult` values and defects for failures unless `includeFailure` is enabled
19
+ *
20
+ * @since 4.0.0
3
21
  */
4
22
  "use client"
5
23
 
@@ -55,8 +73,15 @@ function useStore<A>(registry: AtomRegistry.AtomRegistry, atom: Atom.Atom<A>): A
55
73
  const initialValuesSet = new WeakMap<AtomRegistry.AtomRegistry, WeakSet<Atom.Atom<any>>>()
56
74
 
57
75
  /**
58
- * @since 1.0.0
76
+ * Seeds initial atom values in the current React atom registry.
77
+ *
78
+ * **Details**
79
+ *
80
+ * Each atom is initialized at most once for a given registry, so subsequent
81
+ * renders do not overwrite values that have already been established.
82
+ *
59
83
  * @category hooks
84
+ * @since 4.0.0
60
85
  */
61
86
  export const useAtomInitialValues = (initialValues: Iterable<readonly [Atom.Atom<any>, any]>): void => {
62
87
  const registry = React.useContext(RegistryContext)
@@ -74,18 +99,27 @@ export const useAtomInitialValues = (initialValues: Iterable<readonly [Atom.Atom
74
99
  }
75
100
 
76
101
  /**
77
- * @since 1.0.0
102
+ * Subscribes to an atom in the current React registry and returns its current
103
+ * value, optionally mapped through a selector.
104
+ *
78
105
  * @category hooks
106
+ * @since 4.0.0
79
107
  */
80
108
  export const useAtomValue: {
81
109
  /**
82
- * @since 1.0.0
110
+ * Subscribes to an atom in the current React registry and returns its current
111
+ * value, optionally mapped through a selector.
112
+ *
83
113
  * @category hooks
114
+ * @since 4.0.0
84
115
  */
85
116
  <A>(atom: Atom.Atom<A>): A
86
117
  /**
87
- * @since 1.0.0
118
+ * Subscribes to an atom in the current React registry and returns its current
119
+ * value, optionally mapped through a selector.
120
+ *
88
121
  * @category hooks
122
+ * @since 4.0.0
89
123
  */
90
124
  <A, B>(atom: Atom.Atom<A>, f: (_: A) => B): B
91
125
  } = <A>(atom: Atom.Atom<A>, f?: (_: A) => A): A => {
@@ -137,8 +171,11 @@ const flattenExit = <A, E>(exit: Exit.Exit<A, E>): A => {
137
171
  }
138
172
 
139
173
  /**
140
- * @since 1.0.0
174
+ * Mounts an atom in the current React registry for the lifetime of the
175
+ * component.
176
+ *
141
177
  * @category hooks
178
+ * @since 4.0.0
142
179
  */
143
180
  export const useAtomMount = <A>(atom: Atom.Atom<A>): void => {
144
181
  const registry = React.useContext(RegistryContext)
@@ -146,8 +183,10 @@ export const useAtomMount = <A>(atom: Atom.Atom<A>): void => {
146
183
  }
147
184
 
148
185
  /**
149
- * @since 1.0.0
186
+ * Mounts a writable atom and returns a setter without subscribing to its value.
187
+ *
150
188
  * @category hooks
189
+ * @since 4.0.0
151
190
  */
152
191
  export const useAtomSet = <
153
192
  R,
@@ -172,8 +211,11 @@ export const useAtomSet = <
172
211
  }
173
212
 
174
213
  /**
175
- * @since 1.0.0
214
+ * Mounts an atom and returns a callback that refreshes it in the current React
215
+ * registry.
216
+ *
176
217
  * @category hooks
218
+ * @since 4.0.0
177
219
  */
178
220
  export const useAtomRefresh = <A>(atom: Atom.Atom<A>): () => void => {
179
221
  const registry = React.useContext(RegistryContext)
@@ -184,8 +226,11 @@ export const useAtomRefresh = <A>(atom: Atom.Atom<A>): () => void => {
184
226
  }
185
227
 
186
228
  /**
187
- * @since 1.0.0
229
+ * Subscribes to a writable atom and returns its current value together with a
230
+ * setter for updating it.
231
+ *
188
232
  * @category hooks
233
+ * @since 4.0.0
189
234
  */
190
235
  export const useAtom = <R, W, const Mode extends "value" | "promise" | "promiseExit" = never>(
191
236
  atom: Atom.Writable<R, W>,
@@ -251,8 +296,11 @@ function atomResultOrSuspend<A, E>(
251
296
  }
252
297
 
253
298
  /**
254
- * @since 1.0.0
299
+ * Reads an `AsyncResult` atom through React Suspense, suspending while the
300
+ * result is initial or configured as waiting.
301
+ *
255
302
  * @category hooks
303
+ * @since 4.0.0
256
304
  */
257
305
  export const useAtomSuspense = <A, E, const IncludeFailure extends boolean = false>(
258
306
  atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>,
@@ -270,8 +318,11 @@ export const useAtomSuspense = <A, E, const IncludeFailure extends boolean = fal
270
318
  }
271
319
 
272
320
  /**
273
- * @since 1.0.0
321
+ * Subscribes a callback to an atom in the current React registry for the
322
+ * component lifetime.
323
+ *
274
324
  * @category hooks
325
+ * @since 4.0.0
275
326
  */
276
327
  export const useAtomSubscribe = <A>(
277
328
  atom: Atom.Atom<A>,
@@ -286,8 +337,10 @@ export const useAtomSubscribe = <A>(
286
337
  }
287
338
 
288
339
  /**
289
- * @since 1.0.0
340
+ * Subscribes to an atom ref and returns its latest value.
341
+ *
290
342
  * @category hooks
343
+ * @since 4.0.0
291
344
  */
292
345
  export const useAtomRef = <A>(ref: AtomRef.ReadonlyRef<A>): A => {
293
346
  const [, setValue] = React.useState(ref.value)
@@ -296,15 +349,20 @@ export const useAtomRef = <A>(ref: AtomRef.ReadonlyRef<A>): A => {
296
349
  }
297
350
 
298
351
  /**
299
- * @since 1.0.0
352
+ * Returns a memoized atom ref for a property of another atom ref.
353
+ *
300
354
  * @category hooks
355
+ * @since 4.0.0
301
356
  */
302
357
  export const useAtomRefProp = <A, K extends keyof A>(ref: AtomRef.AtomRef<A>, prop: K): AtomRef.AtomRef<A[K]> =>
303
358
  React.useMemo(() => ref.prop(prop), [ref, prop])
304
359
 
305
360
  /**
306
- * @since 1.0.0
361
+ * Subscribes to a property ref derived from an atom ref and returns its current
362
+ * value.
363
+ *
307
364
  * @category hooks
365
+ * @since 4.0.0
308
366
  */
309
367
  export const useAtomRefPropValue = <A, K extends keyof A>(ref: AtomRef.AtomRef<A>, prop: K): A[K] =>
310
368
  useAtomRef(useAtomRefProp(ref, prop))
package/src/ReactHydration.ts CHANGED
@@ -1,5 +1,26 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * React helpers for hydrating Atom registry state that was serialized on the
3
+ * server or produced by a previous render. This module exposes
4
+ * {@link HydrationBoundary}, a client component that receives dehydrated Atom
5
+ * values and applies them to the nearest {@link RegistryContext} before
6
+ * rendering children when it is safe to do so.
7
+ *
8
+ * **Common use cases**
9
+ *
10
+ * - Reusing Atom values that were collected during server rendering
11
+ * - Restoring client-side Atom state around a routed subtree
12
+ * - Keeping Atom-backed React trees consistent during hydration and transitions
13
+ *
14
+ * **React gotchas**
15
+ *
16
+ * - New Atom values can be hydrated during render so children see them
17
+ * immediately.
18
+ * - Existing Atom values are queued until after commit to avoid updating the
19
+ * current UI with transition data that might later be discarded.
20
+ * - Hydration is idempotent, so repeated or older dehydrated values are safe to
21
+ * pass through the boundary.
22
+ *
23
+ * @since 4.0.0
3
24
  */
4
25
  "use client"
5
26
  import * as Hydration from "effect/unstable/reactivity/Hydration"
@@ -7,8 +28,11 @@ import * as React from "react"
7
28
  import { RegistryContext } from "./RegistryContext.ts"
8
29
 
9
30
  /**
10
- * @since 1.0.0
31
+ * Props for a boundary that applies dehydrated Atom values to the nearest
32
+ * {@link RegistryContext} while rendering its children.
33
+ *
11
34
  * @category components
35
+ * @since 4.0.0
12
36
  */
13
37
  export interface HydrationBoundaryProps {
14
38
  state?: Iterable<Hydration.DehydratedAtom>
@@ -16,8 +40,15 @@ export interface HydrationBoundaryProps {
16
40
  }
17
41
 
18
42
  /**
19
- * @since 1.0.0
43
+ * Hydrates dehydrated Atom values into the current Atom registry for a React
44
+ * subtree.
45
+ *
46
+ * New Atom values are hydrated during render so descendants can read them
47
+ * immediately, while values for existing Atoms are deferred until after commit
48
+ * so transition data does not update the current UI before React accepts it.
49
+ *
20
50
  * @category components
51
+ * @since 4.0.0
21
52
  */
22
53
  export const HydrationBoundary: React.FC<HydrationBoundaryProps> = ({
23
54
  children,
package/src/RegistryContext.ts CHANGED
@@ -1,5 +1,27 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * The `RegistryContext` module provides the React context used by Effect Atom
3
+ * hooks to share an `AtomRegistry` across a component tree. The registry owns
4
+ * atom state, scheduling, and idle cleanup, so components that read or write
5
+ * atoms can coordinate through the same runtime instead of each creating an
6
+ * isolated registry.
7
+ *
8
+ * **Common tasks**
9
+ *
10
+ * - Use {@link RegistryProvider} to scope atom state to a React subtree
11
+ * - Seed atoms for tests, stories, or server-provided data with `initialValues`
12
+ * - Override scheduling or idle timing for custom rendering environments
13
+ * - Read {@link RegistryContext} when integrating lower-level atom APIs
14
+ *
15
+ * **Gotchas**
16
+ *
17
+ * - This is a client module because it depends on React runtime hooks and the
18
+ * scheduler package
19
+ * - A provider keeps the registry stable across renders and disposes it shortly
20
+ * after unmount, allowing React remounts to reuse the same registry
21
+ * - Overriding `scheduleTask` changes when atom work is flushed, so it should
22
+ * return a cancellation function compatible with React unmounts
23
+ *
24
+ * @since 4.0.0
3
25
  */
4
26
  "use client"
5
27
 
@@ -9,8 +31,11 @@ import * as React from "react"
9
31
  import * as Scheduler from "scheduler"
10
32
 
11
33
  /**
12
- * @since 1.0.0
34
+ * Schedules Atom registry work with React's scheduler at low priority and
35
+ * returns a cancellation function for the scheduled task.
36
+ *
13
37
  * @category context
38
+ * @since 4.0.0
14
39
  */
15
40
  export function scheduleTask(f: () => void): () => void {
16
41
  const node = Scheduler.unstable_scheduleCallback(Scheduler.unstable_LowPriority, f)
@@ -18,8 +43,12 @@ export function scheduleTask(f: () => void): () => void {
18
43
  }
19
44
 
20
45
  /**
21
- * @since 1.0.0
46
+ * React context that supplies the `AtomRegistry` used by Atom hooks and
47
+ * hydration helpers, defaulting to a standalone registry when no provider is
48
+ * present.
49
+ *
22
50
  * @category context
51
+ * @since 4.0.0
23
52
  */
24
53
  export const RegistryContext = React.createContext<AtomRegistry.AtomRegistry>(AtomRegistry.make({
25
54
  scheduleTask,
@@ -27,8 +56,11 @@ export const RegistryContext = React.createContext<AtomRegistry.AtomRegistry>(At
27
56
  }))
28
57
 
29
58
  /**
30
- * @since 1.0.0
59
+ * Provides a stable `AtomRegistry` to a React subtree, optionally seeding
60
+ * initial atom values and overriding registry scheduling or idle settings.
61
+ *
31
62
  * @category context
63
+ * @since 4.0.0
32
64
  */
33
65
  export const RegistryProvider = (options: {
34
66
  readonly children?: React.ReactNode | undefined
package/src/ScopedAtom.ts CHANGED
@@ -1,5 +1,22 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * The `ScopedAtom` module provides a small React integration for creating atom
3
+ * instances that are scoped to a component subtree. A scoped atom bundles a
4
+ * React provider, context, and `use` accessor so each mounted provider owns its
5
+ * own atom instance instead of sharing a single module-level atom.
6
+ *
7
+ * Use `ScopedAtom` when an atom needs to be isolated per feature, route,
8
+ * component instance, test harness, or provider input. The provider may receive
9
+ * an initial `value` that is passed to the atom factory, making it useful for
10
+ * state that should be seeded from React props while still being consumed by the
11
+ * atom hooks in descendants.
12
+ *
13
+ * **Gotchas**
14
+ *
15
+ * - `use` must be called under the matching provider or it throws.
16
+ * - The provider creates the atom once for its lifetime; changing the provider
17
+ * `value` prop after mount does not recreate the atom.
18
+ *
19
+ * @since 4.0.0
3
20
  */
4
21
  "use client"
5
22
 
@@ -7,39 +24,36 @@ import type * as Atom from "effect/unstable/reactivity/Atom"
7
24
  import * as React from "react"
8
25
 
9
26
  /**
10
- * @since 1.0.0
11
- * @category Type IDs
12
- *
13
27
  * Type identifier for ScopedAtom.
28
+ *
29
+ * @category type IDs
30
+ * @since 4.0.0
14
31
  */
15
32
  export type TypeId = "~@effect/atom-react/ScopedAtom"
16
33
 
17
34
  /**
18
- * @since 1.0.0
19
- * @category Type IDs
20
- *
21
35
  * Type identifier for ScopedAtom.
36
+ *
37
+ * @category type IDs
38
+ * @since 4.0.0
22
39
  */
23
40
  export const TypeId: TypeId = "~@effect/atom-react/ScopedAtom"
24
41
 
25
42
  /**
26
- * @since 1.0.0
27
- * @category models
28
- *
29
43
  * Scoped Atom interface with a provider-backed instance.
30
44
  *
31
- * @example
45
+ * **Example** (Providing and reading a scoped atom)
46
+ *
32
47
  * ```ts
33
- * import * as Atom from "effect/unstable/reactivity/Atom"
48
+ * import * as AtomReact from "@effect/atom-react"
49
+ * import { Atom } from "effect/unstable/reactivity"
34
50
  * import * as React from "react"
35
- * import * as ScopedAtom from "@effect/atom-react/ScopedAtom"
36
- * import { useAtomValue } from "@effect/atom-react"
37
51
  *
38
- * const Counter = ScopedAtom.make(() => Atom.make(0))
52
+ * const Counter = AtomReact.make(() => Atom.make(0))
39
53
  *
40
54
  * function View() {
41
55
  * const atom = Counter.use()
42
- * const value = useAtomValue(atom)
56
+ * const value = AtomReact.useAtomValue(atom)
43
57
  * return React.createElement("div", null, value)
44
58
  * }
45
59
  *
@@ -47,6 +61,9 @@ export const TypeId: TypeId = "~@effect/atom-react/ScopedAtom"
47
61
  * return React.createElement(Counter.Provider, null, React.createElement(View))
48
62
  * }
49
63
  * ```
64
+ *
65
+ * @category models
66
+ * @since 4.0.0
50
67
  */
51
68
  export interface ScopedAtom<A extends Atom.Atom<any>, Input = never> {
52
69
  readonly [TypeId]: TypeId
@@ -57,23 +74,20 @@ export interface ScopedAtom<A extends Atom.Atom<any>, Input = never> {
57
74
  }
58
75
 
59
76
  /**
60
- * @since 1.0.0
61
- * @category constructors
62
- *
63
77
  * Creates a ScopedAtom from a factory function.
64
78
  *
65
- * @example
79
+ * **Example** (Creating a scoped atom with input)
80
+ *
66
81
  * ```ts
67
- * import * as Atom from "effect/unstable/reactivity/Atom"
82
+ * import * as AtomReact from "@effect/atom-react"
83
+ * import { Atom } from "effect/unstable/reactivity"
68
84
  * import * as React from "react"
69
- * import * as ScopedAtom from "@effect/atom-react/ScopedAtom"
70
- * import { useAtomValue } from "@effect/atom-react"
71
85
  *
72
- * const User = ScopedAtom.make((name: string) => Atom.make(name))
86
+ * const User = AtomReact.make((name: string) => Atom.make(name))
73
87
  *
74
88
  * function UserName() {
75
89
  * const atom = User.use()
76
- * const value = useAtomValue(atom)
90
+ * const value = AtomReact.useAtomValue(atom)
77
91
  * return React.createElement("span", null, value)
78
92
  * }
79
93
  *
@@ -85,6 +99,9 @@ export interface ScopedAtom<A extends Atom.Atom<any>, Input = never> {
85
99
  * )
86
100
  * }
87
101
  * ```
102
+ *
103
+ * @category constructors
104
+ * @since 4.0.0
88
105
  */
89
106
  export const make = <A extends Atom.Atom<any>, Input = never>(
90
107
  f: (() => A) | ((input: Input) => A)
package/src/index.ts CHANGED
@@ -1,23 +1,23 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * @since 4.0.0
3
3
  */
4
4
 
5
5
  /**
6
- * @since 1.0.0
6
+ * @since 4.0.0
7
7
  */
8
8
  export * from "./Hooks.ts"
9
9
 
10
10
  /**
11
- * @since 1.0.0
11
+ * @since 4.0.0
12
12
  */
13
13
  export * from "./RegistryContext.ts"
14
14
 
15
15
  /**
16
- * @since 1.0.0
16
+ * @since 4.0.0
17
17
  */
18
18
  export * from "./ReactHydration.ts"
19
19
 
20
20
  /**
21
- * @since 1.0.0
21
+ * @since 4.0.0
22
22
  */
23
23
  export * from "./ScopedAtom.ts"