atom.io 0.34.2 → 0.35.0

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 (51) hide show
  1. package/dist/internal/index.d.ts +32 -41
  2. package/dist/internal/index.d.ts.map +1 -1
  3. package/dist/internal/index.js +106 -128
  4. package/dist/internal/index.js.map +1 -1
  5. package/dist/json/index.d.ts +7 -7
  6. package/dist/json/index.js +2 -2
  7. package/dist/json/index.js.map +1 -1
  8. package/dist/main/index.d.ts +779 -886
  9. package/dist/main/index.d.ts.map +1 -1
  10. package/dist/main/index.js +46 -14
  11. package/dist/main/index.js.map +1 -1
  12. package/dist/react-devtools/index.js +10 -10
  13. package/dist/react-devtools/index.js.map +1 -1
  14. package/dist/realtime/index.d.ts.map +1 -1
  15. package/dist/realtime/index.js +3 -5
  16. package/dist/realtime/index.js.map +1 -1
  17. package/dist/realtime-client/index.js +10 -10
  18. package/dist/realtime-client/index.js.map +1 -1
  19. package/dist/realtime-server/index.d.ts.map +1 -1
  20. package/dist/realtime-server/index.js +8 -10
  21. package/dist/realtime-server/index.js.map +1 -1
  22. package/package.json +4 -4
  23. package/src/internal/atom/create-regular-atom.ts +1 -0
  24. package/src/internal/atom/index.ts +0 -1
  25. package/src/internal/families/index.ts +0 -1
  26. package/src/internal/index.ts +111 -89
  27. package/src/internal/join/join-internal.ts +3 -4
  28. package/src/internal/mutable/create-mutable-atom-family.ts +0 -1
  29. package/src/internal/mutable/create-mutable-atom.ts +1 -1
  30. package/src/internal/selector/register-selector.ts +2 -2
  31. package/src/json/entries.ts +7 -7
  32. package/src/main/atom.ts +67 -114
  33. package/src/main/dispose-state.ts +0 -2
  34. package/src/main/find-state.ts +3 -9
  35. package/src/main/get-state.ts +0 -2
  36. package/src/main/index.ts +1 -176
  37. package/src/main/join.ts +0 -7
  38. package/src/main/reset-state.ts +0 -2
  39. package/src/main/selector.ts +5 -72
  40. package/src/main/set-state.ts +1 -4
  41. package/src/main/silo.ts +14 -5
  42. package/src/main/subscribe.ts +0 -7
  43. package/src/main/timeline.ts +1 -18
  44. package/src/main/tokens.ts +247 -0
  45. package/src/main/transaction.ts +17 -55
  46. package/src/main/validators.ts +1 -1
  47. package/src/react-devtools/store.ts +61 -45
  48. package/src/realtime/shared-room-store.ts +3 -5
  49. package/src/realtime-server/realtime-server-stores/server-user-store.ts +3 -5
  50. package/src/internal/atom/create-standalone-atom.ts +0 -39
  51. package/src/internal/families/create-atom-family.ts +0 -38
@@ -1,85 +1,132 @@
1
1
  import { Each, EnvironmentData, Flat, Func, Junction, JunctionEntriesBase, JunctionSchemaBase, Refinement, Store, Timeline, TimelineAtomUpdate, TimelineMoleculeCreation, TimelineMoleculeDisposal, TimelineSelectorUpdate, TimelineStateCreation, TimelineStateDisposal, TimelineTransactionUpdate, Transceiver } from "atom.io/internal";
2
2
  import { Canonical, Json, JsonInterface, stringified } from "atom.io/json";
3
- import { MutableAtomFamilyToken as MutableAtomFamilyToken$1, MutableAtomToken as MutableAtomToken$1, ReadableFamilyToken as ReadableFamilyToken$1, ReadableToken as ReadableToken$1, ReadonlyPureSelectorFamilyToken as ReadonlyPureSelectorFamilyToken$1, ReadonlyPureSelectorToken as ReadonlyPureSelectorToken$1, ReadonlySelectorFamilyToken as ReadonlySelectorFamilyToken$1, ReadonlySelectorToken as ReadonlySelectorToken$1, RegularAtomFamilyToken as RegularAtomFamilyToken$1, RegularAtomToken as RegularAtomToken$1, WritableFamilyToken as WritableFamilyToken$1, WritablePureSelectorFamilyToken as WritablePureSelectorFamilyToken$1, WritablePureSelectorToken as WritablePureSelectorToken$1, WritableSelectorFamilyToken as WritableSelectorFamilyToken$1, WritableSelectorToken as WritableSelectorToken$1, WritableToken as WritableToken$1, findState as findState$1, getState as getState$1, setState as setState$1 } from "atom.io";
3
+ import { MutableAtomFamilyToken as MutableAtomFamilyToken$1, MutableAtomToken as MutableAtomToken$1, ReadableFamilyToken as ReadableFamilyToken$1, ReadableToken as ReadableToken$1, ReadonlyPureSelectorToken as ReadonlyPureSelectorToken$1, ReadonlySelectorFamilyToken as ReadonlySelectorFamilyToken$1, ReadonlySelectorToken as ReadonlySelectorToken$1, RegularAtomToken as RegularAtomToken$1, WritableFamilyToken as WritableFamilyToken$1, WritableSelectorFamilyToken as WritableSelectorFamilyToken$1, WritableSelectorToken as WritableSelectorToken$1, WritableToken as WritableToken$1, findState as findState$1 } from "atom.io";
4
4
  import { SetRTX, SetRTXJson } from "atom.io/transceivers/set-rtx";
5
5
 
6
- //#region src/main/atom.d.ts
6
+ //#region src/main/tokens.d.ts
7
7
 
8
8
  /**
9
- * @public
10
- * Create a mutable atom, a global reactive variable in the implicit store
9
+ * A token is an object that uniquely identifies a particular state, family, timeline, or transaction.
11
10
  *
12
- * The value of a mutable atom must be some kind of {@link Transceiver}.
11
+ * While they represent one of these resources, they are not the resource itself. Think of them like paper currency representing money in the bank.
13
12
  *
14
- * @param options - {@link MutableAtomOptions}.
15
- * @returns
16
- * A reference to the atom created: a {@link MutableAtomToken}
17
- * @overload Mutable
13
+ * Tokens are returned from resource creation functions, such as {@link atom} and {@link transaction}.
14
+ *
15
+ * Tokens can be used as parameters to functions that take a token, such as {@link getState}, {@link setState}, or {@link runTransaction}.
16
+ *
17
+ * Tokens are fully serializable, so they can be passed between processes.
18
18
  */
19
- declare function atom<T extends Transceiver<any>, J extends Json.Serializable>(options: MutableAtomOptions<T, J>): MutableAtomToken<T, J>;
19
+ type AtomIOToken = ReadableFamilyToken<any, any> | ReadableToken<any> | TimelineToken<any> | TransactionToken<any>;
20
20
  /**
21
- * @public
22
- * Create a regular atom, a global reactive variable in the implicit store
23
- * @param options - {@link RegularAtomOptions}.
24
- * @returns
25
- * A reference to the atom created: a {@link RegularAtomToken}
26
- * @overload Regular
21
+ * These states cannot be set.
27
22
  */
28
- declare function atom<T>(options: RegularAtomOptions<T>): RegularAtomToken<T>;
29
- /** @public */
30
- type Effectors<T> = {
31
- /**
32
- * Reset the value of the atom to its default
33
- */
34
- resetSelf: () => void;
35
- /**
36
- * Set the value of the atom
37
- * @param next - The new value of the atom, or a setter function
38
- */
39
- setSelf: <New extends T>(next: New | Setter<T, New>) => void;
40
- /** Subscribe to changes to the atom */
41
- onSet: (callback: (options: {
42
- newValue: T;
43
- oldValue: T;
44
- }) => void) => void;
45
- };
23
+ type ReadableToken<T, K extends Canonical = any> = AtomToken<T, K> | SelectorToken<T, K>;
46
24
  /**
47
- * @public
48
- * A function that runs side effects when the atom is set
49
- * @param tools - {@link Effectors} that can be used to run side effects
50
- * @returns
51
- * Optionally, a cleanup function that will be called when the atom is disposed
25
+ * These states can be set.
52
26
  */
53
- type AtomEffect<T> = (tools: Effectors<T>) => (() => void) | void;
54
- /** @public */
55
- type RegularAtomOptions<T> = {
56
- /** The unique identifier of the atom */
27
+ type WritableToken<T, K extends Canonical = any> = AtomToken<T, K> | WritableSelectorToken<T, K>;
28
+ /**
29
+ * States belonging to this family can be gotten from the store.
30
+ */
31
+ type ReadableFamilyToken<T, K extends Canonical> = AtomFamilyToken<T, K> | SelectorFamilyToken<T, K>;
32
+ /**
33
+ * States belonging to this family can be set.
34
+ */
35
+ type WritableFamilyToken<T, K extends Canonical> = AtomFamilyToken<T, K> | WritableSelectorFamilyToken<T, K>;
36
+ type TimelineToken<M> = {
37
+ /** The unique identifier of the timeline */
57
38
  key: string;
58
- /** The starting value of the atom */
59
- default: T | (() => T);
60
- /** Hooks used to run side effects when the atom is set */
61
- effects?: AtomEffect<T>[];
39
+ /** Discriminator */
40
+ type: `timeline`;
41
+ /** Never present. This is a marker that preserves the type of the managed atoms */
42
+ __M?: M;
62
43
  };
63
- /** @public */
64
- type MutableAtomOptions<T extends Transceiver<any>, J extends Json.Serializable> = JsonInterface<T, J> & {
65
- /** Used to signal that the atom is mutable */
66
- mutable: true;
67
- /** The unique identifier of the atom */
44
+ type TransactionToken<F extends Func> = {
45
+ /** The unique identifier of the transaction */
68
46
  key: string;
69
- /** A function to create an initial value for the atom */
70
- default: () => T;
71
- /** Hooks used to run side effects when the atom is set */
72
- effects?: AtomEffect<T>[];
47
+ /** Discriminator */
48
+ type: `transaction`;
49
+ /** Never present. This is a marker that preserves the type of the transaction function */
50
+ __F?: F;
73
51
  };
74
- /** @public */
75
- type RegularAtomFamilyOptions<T, K extends Canonical> = {
76
- /** The unique identifier of the atom family */
52
+ type AtomToken<T, K extends Canonical = any> = MutableAtomToken<T extends Transceiver<any> ? T : never, any, K> | RegularAtomToken<T, K>;
53
+ type RegularAtomToken<T, K extends Canonical = any> = {
54
+ /** The unique identifier of the atom. */
77
55
  key: string;
78
- /** The starting value of the atom family */
79
- default: T | ((key: K) => T);
80
- /** Hooks used to run side effects when an atom in the family is set */
81
- effects?: (key: K) => AtomEffect<T>[];
56
+ /** Discriminator. */
57
+ type: `atom`;
58
+ /** Present if the atom belongs to a family. */
59
+ family?: FamilyMetadata<K>;
60
+ /** Never present. This is a marker that preserves the type of the atom's value. */
61
+ __T?: T;
62
+ };
63
+ type MutableAtomToken<T extends Transceiver<any>, J extends Json.Serializable, K extends Canonical = any> = {
64
+ /** The unique identifier of the atom. */
65
+ key: string;
66
+ /** Discriminator. */
67
+ type: `mutable_atom`;
68
+ /** Present if the atom belongs to a family. */
69
+ family?: FamilyMetadata<K>;
70
+ /** Never present. This is a marker that preserves the JSON form of the atom's transceiver value. */
71
+ __J?: J;
72
+ /** Never present. This is a marker that preserves the type of the atom's transceiver value. */
73
+ __U?: T extends Transceiver<infer Update> ? Update : never;
74
+ };
75
+ type SelectorToken<T, K extends Canonical = any> = ReadonlySelectorToken<T, K> | WritableSelectorToken<T, K>;
76
+ type ReadonlySelectorToken<T, K extends Canonical = any> = ReadonlyHeldSelectorToken<T, K> | ReadonlyPureSelectorToken<T, K>;
77
+ type WritableSelectorToken<T, K extends Canonical = any> = WritableHeldSelectorToken<T, K> | WritablePureSelectorToken<T, K>;
78
+ type PureSelectorToken<T, K extends Canonical = any> = ReadonlyPureSelectorToken<T, K> | WritablePureSelectorToken<T, K>;
79
+ type HeldSelectorToken<T, K extends Canonical = any> = ReadonlyHeldSelectorToken<T, K> | WritableHeldSelectorToken<T, K>;
80
+ type WritablePureSelectorToken<T, K extends Canonical = any> = {
81
+ /** The unique identifier of the selector. */
82
+ key: string;
83
+ /** Discriminator. */
84
+ type: `writable_pure_selector`;
85
+ /** Present if the selector belongs to a family. */
86
+ family?: FamilyMetadata<K>;
87
+ /** Never present. This is a marker that preserves the type of the selector's value. */
88
+ __T?: T;
89
+ };
90
+ type WritableHeldSelectorToken<T, K extends Canonical = any> = {
91
+ /** The unique identifier of the selector. */
92
+ key: string;
93
+ /** Discriminator. */
94
+ type: `writable_held_selector`;
95
+ /** Present if the selector belongs to a family. */
96
+ family?: FamilyMetadata<K>;
97
+ /** Never present. This is a marker that preserves the type of the selector's value. */
98
+ __T?: T;
99
+ };
100
+ type ReadonlyPureSelectorToken<T, K extends Canonical = any> = {
101
+ /** The unique identifier of the selector. */
102
+ key: string;
103
+ /** Discriminator. */
104
+ type: `readonly_pure_selector`;
105
+ /** Present if the selector belongs to a family. */
106
+ family?: FamilyMetadata<K>;
107
+ /** Never present. This is a marker that preserves the type of the selector's value. */
108
+ __T?: T;
109
+ };
110
+ type ReadonlyHeldSelectorToken<T, K extends Canonical = any> = {
111
+ /** The unique identifier of the selector. */
112
+ key: string;
113
+ /** Discriminator. */
114
+ type: `readonly_held_selector`;
115
+ /** Present if the selector belongs to a family. */
116
+ family?: FamilyMetadata<K>;
117
+ /** Never present. This is a marker that preserves the type of the selector's value. */
118
+ __T?: T;
119
+ };
120
+ /**
121
+ * Identifies a state's connection to its family.
122
+ */
123
+ type FamilyMetadata<K extends Canonical = any> = {
124
+ /** The family's unique key. */
125
+ key: string;
126
+ /** The family member's unique identifier, in the form of a string. */
127
+ subKey: stringified<K>;
82
128
  };
129
+ type AtomFamilyToken<T, K extends Canonical = Canonical> = MutableAtomFamilyToken<T extends Transceiver<any> ? T : never, any, K> | RegularAtomFamilyToken<T, K>;
83
130
  type RegularAtomFamilyToken<T, K extends Canonical> = {
84
131
  /** The unique identifier of the atom family */
85
132
  key: string;
@@ -90,17 +137,6 @@ type RegularAtomFamilyToken<T, K extends Canonical> = {
90
137
  /** Never present. This is a marker that preserves the type of keys used for atoms in this family */
91
138
  __K?: K;
92
139
  };
93
- /** @public */
94
- type MutableAtomFamilyOptions<T extends Transceiver<any>, J extends Json.Serializable, K extends Canonical> = JsonInterface<T, J> & {
95
- /** Used to signal that the atoms created from this family are mutable */
96
- mutable: true;
97
- /** The unique identifier of the atom family */
98
- key: string;
99
- /** A function to create an initial value for each atom in the family */
100
- default: (key: K) => T;
101
- /** Hooks used to run side effects when an atom in the family is set */
102
- effects?: (key: K) => AtomEffect<T>[];
103
- };
104
140
  type MutableAtomFamilyToken<T extends Transceiver<any>, J extends Json.Serializable, K extends Canonical> = {
105
141
  /** The unique identifier of the atom family */
106
142
  key: string;
@@ -113,685 +149,372 @@ type MutableAtomFamilyToken<T extends Transceiver<any>, J extends Json.Serializa
113
149
  /** Never present. This is a marker that preserves the type of keys used for atoms in this family */
114
150
  __K?: K;
115
151
  };
116
- type AtomFamilyToken<T, K extends Canonical = Canonical> = MutableAtomFamilyToken<T extends Transceiver<any> ? T : never, any, K> | RegularAtomFamilyToken<T, K>;
117
- /**
118
- * @public
119
- * Create a family of mutable atoms, allowing for the dynamic creation and disposal of atoms.
120
- *
121
- * The value of a mutable atom must be some kind of {@link Transceiver}.
122
- *
123
- * @param options - {@link MutableAtomFamilyOptions}
124
- * @returns
125
- * A reference to the atom family created: a {@link MutableAtomFamilyToken}
126
- * @overload Mutable
127
- */
128
- declare function atomFamily<T extends Transceiver<any>, J extends Json.Serializable, K extends Canonical>(options: MutableAtomFamilyOptions<T, J, K>): MutableAtomFamilyToken<T, J, K>;
152
+ type SelectorFamilyToken<T, K extends Canonical> = ReadonlySelectorFamilyToken<T, K> | WritableSelectorFamilyToken<T, K>;
153
+ type ReadonlySelectorFamilyToken<T, K extends Canonical> = ReadonlyHeldSelectorFamilyToken<T, K> | ReadonlyPureSelectorFamilyToken<T, K>;
154
+ type WritableSelectorFamilyToken<T, K extends Canonical> = WritableHeldSelectorFamilyToken<T, K> | WritablePureSelectorFamilyToken<T, K>;
155
+ type PureSelectorFamilyToken<T, K extends Canonical> = ReadonlyPureSelectorFamilyToken<T, K> | WritablePureSelectorFamilyToken<T, K>;
156
+ type HeldSelectorFamilyToken<T, K extends Canonical> = ReadonlyHeldSelectorFamilyToken<T, K> | WritableHeldSelectorFamilyToken<T, K>;
157
+ type WritablePureSelectorFamilyToken<T, K extends Canonical> = {
158
+ /** The unique identifier of the family */
159
+ key: string;
160
+ /** Discriminator */
161
+ type: `writable_pure_selector_family`;
162
+ /** Never present. This is a marker that preserves the type of the value of each family member */
163
+ __T?: T;
164
+ /** Never present. This is a marker that preserves the type of keys used for each family member */
165
+ __K?: K;
166
+ };
167
+ type ReadonlyPureSelectorFamilyToken<T, K extends Canonical> = {
168
+ /** The unique identifier of the family */
169
+ key: string;
170
+ /** Discriminator */
171
+ type: `readonly_pure_selector_family`;
172
+ /** Never present. This is a marker that preserves the type of the value of each family member */
173
+ __T?: T;
174
+ /** Never present. This is a marker that preserves the type of keys used for each family member */
175
+ __K?: K;
176
+ };
177
+ type WritableHeldSelectorFamilyToken<T, K extends Canonical> = {
178
+ /** The unique identifier of the family */
179
+ key: string;
180
+ /** Discriminator */
181
+ type: `writable_held_selector_family`;
182
+ /** Never present. This is a marker that preserves the type of the value of each family member */
183
+ __T?: T;
184
+ /** Never present. This is a marker that preserves the type of keys used for each family member */
185
+ __K?: K;
186
+ };
187
+ type ReadonlyHeldSelectorFamilyToken<T, K extends Canonical> = {
188
+ /** The unique identifier of the family */
189
+ key: string;
190
+ /** Discriminator */
191
+ type: `readonly_held_selector_family`;
192
+ /** Never present. This is a marker that preserves the type of the value of each family member */
193
+ __T?: T;
194
+ /** Never present. This is a marker that preserves the type of keys used for each family member */
195
+ __K?: K;
196
+ };
197
+ //#endregion
198
+ //#region src/main/set-state.d.ts
129
199
  /**
130
- * @public
131
- * Create a family of regular atoms, allowing for the dynamic creation and disposal of atoms.
132
- * @param options - {@link RegularAtomFamilyOptions}
200
+ * A function that sets the value of a state.
201
+ * @param oldValue - The current value of the state.
133
202
  * @returns
134
- * A reference to the atom family created: a {@link RegularAtomFamilyToken}
135
- * @overload Regular
203
+ * The new value of the state.
136
204
  */
137
- declare function atomFamily<T, K extends Canonical>(options: RegularAtomFamilyOptions<T, K>): RegularAtomFamilyToken<T, K>;
138
- //#endregion
139
- //#region src/main/reset-state.d.ts
205
+ type Setter<T, New extends T> = (oldValue: T) => New;
140
206
  /**
141
- * @public
142
- * Set the value of a state into the implicit store back to its default value.
207
+ * Set the value of a state into the implicit store.
143
208
  * @param token - An atom or writable selector token.
209
+ * @param value - The new value of the state.
144
210
  * @overload Default
145
211
  * @default
146
212
  */
147
- declare function resetState(token: WritableToken<any>): void;
213
+ declare function setState<T, New extends T>(token: WritableToken<T>, value: New | Setter<T, New>): void;
148
214
  /**
149
- * @public
150
- * Set the value of a state into the implicit store back to its default value.
215
+ * Set the value of a state into the implicit store.
151
216
  * @param token - An atom family or writable selector family token.
152
217
  * @param key - The unique key of the state to set.
218
+ * @param value - The new value of the state.
153
219
  * @overload Streamlined
154
220
  */
155
- declare function resetState<K extends Canonical>(token: WritableFamilyToken<any, K>, key: K): void;
221
+ declare function setState<T, K extends Canonical, New extends T, Key extends K>(token: WritableFamilyToken<T, K>, key: Key, value: New | Setter<T, New>): void;
156
222
  //#endregion
157
- //#region src/main/transaction.d.ts
158
- /** @public */
159
- type TransactionToken<F extends Func> = {
160
- /** The unique identifier of the transaction */
223
+ //#region src/main/atom.d.ts
224
+ type RegularAtomOptions<T> = {
225
+ /** The unique identifier of the atom */
161
226
  key: string;
162
- /** Discriminator */
163
- type: `transaction`;
164
- /** Never present. This is a marker that preserves the type of the transaction function */
165
- __F?: F;
227
+ /** The starting value of the atom */
228
+ default: T | (() => T);
229
+ /** Hooks used to run side effects when the atom is set */
230
+ effects?: AtomEffect<T>[];
166
231
  };
167
- /** @public */
168
- type StateCreation<Token extends ReadableToken<any>> = {
169
- type: `state_creation`;
170
- token: Token;
171
- };
172
- /** @public */
173
- type AtomDisposal<Token extends ReadableToken<any>> = {
174
- type: `state_disposal`;
175
- subType: `atom`;
176
- token: Token;
177
- value: TokenType<Token>;
178
- };
179
- /** @public */
180
- type SelectorDisposal<Token extends ReadableToken<any>> = {
181
- type: `state_disposal`;
182
- subType: `selector`;
183
- token: Token;
184
- };
185
- /** @public */
186
- type StateDisposal<Token extends ReadableToken<any>> = AtomDisposal<Token> | SelectorDisposal<Token>;
187
- /** @public */
188
- type MoleculeCreation = {
189
- type: `molecule_creation`;
190
- key: Canonical;
191
- provenance: Canonical;
192
- };
193
- /** @public */
194
- type MoleculeDisposal = {
195
- type: `molecule_disposal`;
196
- key: Canonical;
197
- provenance: stringified<Canonical>[];
198
- values: [key: string, value: any][];
199
- };
200
- /** @public */
201
- type MoleculeTransfer = {
202
- type: `molecule_transfer`;
203
- key: Canonical;
204
- from: Canonical[];
205
- to: Canonical[];
206
- };
207
- /** @public */
208
- type TransactionUpdateContent = KeyedStateUpdate<unknown> | MoleculeCreation | MoleculeDisposal | MoleculeTransfer | StateCreation<ReadableToken<unknown>> | StateDisposal<ReadableToken<unknown>> | TransactionUpdate<Func>;
209
- /** @public */
210
- type TransactionUpdate<F extends Func> = {
211
- type: `transaction_update`;
212
- key: string;
213
- id: string;
214
- epoch: number;
215
- updates: TransactionUpdateContent[];
216
- params: Parameters<F>;
217
- output: ReturnType<F>;
218
- };
219
- /** @public */
220
- type GetterToolkit = Pick<SetterToolkit, `find` | `get` | `json`>;
221
- /** @public */
222
- type SetterToolkit = Readonly<{
223
- get: typeof getState$1;
224
- set: typeof setState$1;
225
- find: typeof findState$1;
226
- json: <T extends Transceiver<any>, J extends Json.Serializable>(state: MutableAtomToken<T, J>) => WritablePureSelectorToken<J>;
227
- }>;
228
- /** @public */
229
- type ActorToolkit = Readonly<{
230
- get: typeof getState$1;
231
- set: typeof setState$1;
232
- reset: typeof resetState;
233
- find: typeof findState$1;
234
- json: <T extends Transceiver<any>, J extends Json.Serializable>(state: MutableAtomToken<T, J>) => WritablePureSelectorToken<J>;
235
- dispose: typeof disposeState;
236
- run: typeof runTransaction;
237
- env: () => EnvironmentData;
238
- }>;
239
- /** @public */
240
- type Read<F extends Func> = (toolkit: GetterToolkit, ...parameters: Parameters<F>) => ReturnType<F>;
241
- /** @public */
242
- type Write<F extends Func> = (toolkit: SetterToolkit, ...parameters: Parameters<F>) => ReturnType<F>;
243
- /** @public */
244
- type Transact<F extends Func> = (toolkit: ActorToolkit, ...parameters: Parameters<F>) => ReturnType<F>;
245
- /** @public */
246
- type TransactionIO<Token extends TransactionToken<any>> = Token extends TransactionToken<infer F> ? F : never;
247
- /** @public */
248
- type TransactionOptions<F extends Func> = {
249
- /** The unique identifier of the transaction */
232
+ /**
233
+ * Create a regular atom, a global reactive variable in the implicit store
234
+ * @param options - {@link RegularAtomOptions}.
235
+ * @returns
236
+ * A reference to the atom created: a {@link RegularAtomToken}
237
+ */
238
+ declare function atom<T>(options: RegularAtomOptions<T>): RegularAtomToken<T>;
239
+ type MutableAtomOptions<T extends Transceiver<any>, J extends Json.Serializable> = JsonInterface<T, J> & {
240
+ /** The unique identifier of the atom */
250
241
  key: string;
251
- /** The operation to perform */
252
- do: Transact<F>;
242
+ /** A function to create an initial value for the atom */
243
+ default: () => T;
244
+ /** Hooks used to run side effects when the atom is set */
245
+ effects?: AtomEffect<T>[];
253
246
  };
254
247
  /**
255
- * @public
256
- * Create a transaction, a mechanism for batching updates multiple states in a single, all-or-nothing operation
257
- * @param options - {@link TransactionOptions}
258
- * @returns A reference to the transaction created: a {@link TransactionToken}
248
+ * Create a mutable atom, a global reactive variable in the implicit store
249
+ *
250
+ * The value of a mutable atom must be some kind of {@link Transceiver}.
251
+ *
252
+ * @param options - {@link MutableAtomOptions}.
253
+ * @returns
254
+ * A reference to the atom created: a {@link MutableAtomToken}
259
255
  */
260
- declare function transaction<F extends Func>(options: TransactionOptions<F>): TransactionToken<F>;
256
+ declare function mutableAtom<T extends Transceiver<any>, J extends Json.Serializable>(options: MutableAtomOptions<T, J>): MutableAtomToken<T, J>;
261
257
  /**
262
- * @public
263
- * Execute a {@link transaction}
264
- * @param token - A {@link TransactionToken}
265
- * @param id - A unique identifier for the transaction. If not provided, a random identifier will be generated
266
- * @returns A function that can be called to run the transaction with its {@link TransactionIO} parameters
258
+ * A function that runs side effects when the atom is set
259
+ * @param tools - {@link Effectors} that can be used to run side effects
260
+ * @returns
261
+ * Optionally, a cleanup function that will be called when the atom is disposed
267
262
  */
268
- declare function runTransaction<F extends Func>(token: TransactionToken<F>, id?: string): (...parameters: Parameters<F>) => ReturnType<F>;
269
- //#endregion
270
- //#region src/main/selector.d.ts
271
- type WritablePureSelectorOptions<T> = {
272
- /** The unique identifier of the selector */
273
- key: string;
274
- /** For each instantiated selector, a function that computes its value */
275
- get: Read<() => T>;
276
- /** For each instantiated selector, a function that sets its value */
277
- set: Write<(newValue: T) => void>;
278
- };
279
- type ReadonlyPureSelectorOptions<T> = {
280
- /** The unique identifier of the selector */
281
- key: string;
282
- /** For each instantiated selector, a function that computes its value */
283
- get: Read<() => T>;
263
+ type AtomEffect<T> = (tools: Effectors<T>) => (() => void) | void;
264
+ type Effectors<T> = {
265
+ /**
266
+ * Reset the value of the atom to its default
267
+ */
268
+ resetSelf: () => void;
269
+ /**
270
+ * Set the value of the atom
271
+ * @param next - The new value of the atom, or a setter function
272
+ */
273
+ setSelf: <New extends T>(next: New | Setter<T, New>) => void;
274
+ /** Subscribe to changes to the atom */
275
+ onSet: (callback: (options: {
276
+ newValue: T;
277
+ oldValue: T;
278
+ }) => void) => void;
284
279
  };
285
- type ReadonlyHeldSelectorOptions<T extends object> = {
286
- /** The unique identifier of the selector */
280
+ type RegularAtomFamilyOptions<T, K extends Canonical> = {
281
+ /** The unique identifier of the atom family */
287
282
  key: string;
288
- /** For each instantiated selector, a constant reference to a value that will not be replaced */
289
- const: T;
290
- /** For each instantiated selector, a function that computes its value */
291
- get: Read<(permanent: T) => void>;
283
+ /** The starting value of the atom family */
284
+ default: T | ((key: K) => T);
285
+ /** Hooks used to run side effects when an atom in the family is set */
286
+ effects?: (key: K) => AtomEffect<T>[];
292
287
  };
293
- type WritableHeldSelectorOptions<T extends object> = {
294
- /** The unique identifier of the selector */
288
+ /**
289
+ * Create a family of regular atoms, allowing for the dynamic creation and disposal of atoms.
290
+ * @param options - {@link RegularAtomFamilyOptions}
291
+ * @returns
292
+ * A reference to the atom family created: a {@link RegularAtomFamilyToken}
293
+ */
294
+ declare function atomFamily<T, K extends Canonical>(options: RegularAtomFamilyOptions<T, K>): RegularAtomFamilyToken<T, K>;
295
+ type MutableAtomFamilyOptions<T extends Transceiver<any>, J extends Json.Serializable, K extends Canonical> = JsonInterface<T, J> & {
296
+ /** The unique identifier of the atom family */
295
297
  key: string;
296
- /** For each instantiated selector, a constant reference to a value that will not be replaced */
297
- const: T;
298
- /** For each instantiated selector, a function that computes its value */
299
- get: Read<(permanent: T) => void>;
300
- /** For each instantiated selector, a function that sets its value */
301
- set: Write<(newValue: T) => void>;
298
+ /** A function to create an initial value for each atom in the family */
299
+ default: (key: K) => T;
300
+ /** Hooks used to run side effects when an atom in the family is set */
301
+ effects?: (key: K) => AtomEffect<T>[];
302
302
  };
303
303
  /**
304
- * @public
305
- * Declare a selector. The value of a selector should depend
306
- * on the value of atoms or other selectors in the store, and
307
- * should be recycled when a root atom of the selector is set.
304
+ * Create a family of mutable atoms, allowing for the dynamic creation and disposal of atoms.
308
305
  *
309
- * A held selector's value must be some object.
310
- * The reference to that object is permanent and will not be replaced.
306
+ * The value of a mutable atom must be some kind of {@link Transceiver}.
311
307
  *
312
- * A writable selector can be "set" to a new value.
313
- * It is strongly advised to set its dependencies to values
314
- * that would produce the new value of the selector.
308
+ * @param options - {@link MutableAtomFamilyOptions}
309
+ * @returns
310
+ * A reference to the atom family created: a {@link MutableAtomFamilyToken}
311
+ */
312
+ declare function mutableAtomFamily<T extends Transceiver<any>, J extends Json.Serializable, K extends Canonical>(options: MutableAtomFamilyOptions<T, J, K>): MutableAtomFamilyToken<T, J, K>;
313
+ //#endregion
314
+ //#region src/main/dispose-state.d.ts
315
+ /**
316
+ * Disposes of a state in the implicit store.
315
317
  *
316
- * @param options - {@link WritableHeldSelectorOptions}.
318
+ * Only family members can be disposed of.
319
+ *
320
+ * @param token - The token of the state to dispose
321
+ * @overload Default
322
+ */
323
+ declare function disposeState(token: ReadableToken<any>): void;
324
+ /**
325
+ * Disposes of a state in the implicit store.
326
+ *
327
+ * Only family members can be disposed of.
328
+ *
329
+ * @param token - The token of the state family to dispose
330
+ * @param key - The unique key of the state to dispose
331
+ */
332
+ declare function disposeState<K extends Canonical>(token: ReadableFamilyToken<any, K>, key: K): void;
333
+ //#endregion
334
+ //#region src/main/find-state.d.ts
335
+ /**
336
+ * Finds a {@link MutableAtomToken} in the store, without accessing its value.
337
+ *
338
+ * In an ephemeral store, this will create a new atom if one does not exist with the given key.
339
+ *
340
+ * In an immortal store, a "counterfeit" atom token will be returned in this case and a warning will be logged.
341
+ *
342
+ * @param token - A {@link MutableAtomFamilyToken}
343
+ * @param key - The key of the state
317
344
  * @returns
318
- * The token for your selector.
319
- * @overload WritableHeld
345
+ * The current value of the state
346
+ * @overload Mutable Atom
320
347
  */
321
- declare function selector<T extends object>(options: WritableHeldSelectorOptions<T>): WritableHeldSelectorToken<T>;
348
+ declare function findState<T extends Transceiver<any>, J extends Json.Serializable, K extends Canonical, Key extends K>(token: MutableAtomFamilyToken<T, J, K>, key: Key): MutableAtomToken$1<T, J, K>;
322
349
  /**
323
- * @public
324
- * Declare a selector. The value of a selector should depend
325
- * on the value of atoms or other selectors in the store,
326
- * and should be recycled when a root atom of the selector is set.
350
+ * Finds a {@link RegularAtomToken} in the store, without accessing its value.
327
351
  *
328
- * A held selector's value must be some object.
329
- * The reference to that object is permanent and will not be replaced.
352
+ * In an ephemeral store, this will create a new atom if one does not exist with the given key.
330
353
  *
331
- * A readonly selector can be "gotten" but not "set".
354
+ * In an immortal store, a "counterfeit" atom token will be returned in this case and a warning will be logged.
332
355
  *
333
- * @param options - {@link ReadonlyHeldSelectorOptions}.
356
+ * @param token - The token of the state family
357
+ * @param key - The key of the state
334
358
  * @returns
335
- * The token for your selector.
336
- * @overload ReadonlyHeld
359
+ * The current value of the state
360
+ * @overload Regular Atom
337
361
  */
338
- declare function selector<T extends object>(options: ReadonlyHeldSelectorOptions<T>): ReadonlyHeldSelectorToken<T>;
362
+ declare function findState<T, K extends Canonical, Key extends K>(token: RegularAtomFamilyToken<T, K>, key: Key): RegularAtomToken$1<T, K>;
339
363
  /**
340
- * @public
341
- * Declare a selector. The value of a selector should depend
342
- * on the value of atoms or other selectors in the store.
364
+ * Finds a {@link WritableSelectorToken} in the store, without accessing its value.
343
365
  *
344
- * A pure selector's current value is evicted from the store
345
- * in order to be garbage collected when a root atom of the selector is set.
366
+ * In an ephemeral store, this will create a new selector if one does not exist with the given key.
346
367
  *
347
- * A writable selector can be "set" to a new value.
348
- * It is strongly advised to set its dependencies to values
349
- * that would produce the new value of the selector.
368
+ * In an immortal store, a "counterfeit" selector token will be returned in this case and a warning will be logged.
350
369
  *
351
- * @param options - {@link TransientWritableSelectorOptions}.
370
+ * @param token - The token of the state family
371
+ * @param key - The key of the state
352
372
  * @returns
353
- * The token for your selector.
354
- * @overload WritablePure
373
+ * The current value of the state
374
+ * @overload Writable Selector
355
375
  */
356
- declare function selector<T>(options: WritablePureSelectorOptions<T>): WritablePureSelectorToken<T>;
376
+ declare function findState<T, K extends Canonical, Key extends K>(token: WritableSelectorFamilyToken$1<T, K>, key: Key): WritableSelectorToken$1<T, K>;
357
377
  /**
358
- * @public
359
- * Declare a selector. The value of a selector should depend
360
- * on the value of atoms or other selectors in the store.
378
+ * Finds a {@link ReadonlySelectorToken} in the store, without accessing its value.
361
379
  *
362
- * A pure selector's current value is evicted from the store
363
- * in order to be garbage collected when a root atom of the selector is set.
380
+ * In an ephemeral store, this will create a new selector if one does not exist with the given key.
364
381
  *
365
- * A readonly selector can be "gotten" but not "set".
382
+ * In an immortal store, a "counterfeit" selector token will be returned in this case and a warning will be logged.
366
383
  *
367
- * @param options - {@link ReadonlyPureSelectorOptions}.
384
+ * @param token - The token of the state family
385
+ * @param key - The key of the state
368
386
  * @returns
369
- * The token for your selector.
370
- * @overload ReadonlyPure
387
+ * The current value of the state
388
+ * @overload Readonly Selector
371
389
  */
372
- declare function selector<T>(options: ReadonlyPureSelectorOptions<T>): ReadonlyPureSelectorToken<T>;
373
- /** @public */
374
- type WritablePureSelectorFamilyOptions<T, K extends Canonical> = {
375
- /** The unique identifier of the family */
376
- key: string;
377
- /** For each instantiated family member, a function that computes its value */
378
- get: (key: K) => Read<() => T>;
379
- /** For each instantiated family member, a function that sets its value */
380
- set: (key: K) => Write<(newValue: T) => void>;
381
- };
382
- /** @public */
383
- type ReadonlyPureSelectorFamilyOptions<T, K extends Canonical> = {
384
- /** The unique identifier of the family */
385
- key: string;
386
- /** For each instantiated family member, a function that computes its value */
387
- get: (key: K) => Read<() => T>;
388
- };
389
- /** @public */
390
- type WritableHeldSelectorFamilyOptions<T extends object, K extends Canonical> = {
391
- /** The unique identifier of the family */
392
- key: string;
393
- /** For each instantiated family member, a constant reference to a value that will not be replaced */
394
- const: (key: K) => T;
395
- /** For each instantiated family member, a function that computes its value */
396
- get: (key: K) => Read<(permanent: T) => void>;
397
- /** For each instantiated family member, a function that sets its value */
398
- set: (key: K) => Write<(newValue: T) => void>;
399
- };
400
- /** @public */
401
- type ReadonlyHeldSelectorFamilyOptions<T extends object, K extends Canonical> = {
402
- /** The unique identifier of the family */
403
- key: string;
404
- /** For each instantiated family member, a constant reference to a value that will not be replaced */
405
- const: (key: K) => T;
406
- /** For each instantiated family member, a function that computes its value */
407
- get: (key: K) => Read<(permanent: T) => void>;
408
- };
409
- type WritablePureSelectorFamilyToken<T, K extends Canonical> = {
410
- /** The unique identifier of the family */
411
- key: string;
412
- /** Discriminator */
413
- type: `writable_pure_selector_family`;
414
- /** Never present. This is a marker that preserves the type of the value of each family member */
415
- __T?: T;
416
- /** Never present. This is a marker that preserves the type of keys used for each family member */
417
- __K?: K;
418
- };
419
- type ReadonlyPureSelectorFamilyToken<T, K extends Canonical> = {
420
- /** The unique identifier of the family */
421
- key: string;
422
- /** Discriminator */
423
- type: `readonly_pure_selector_family`;
424
- /** Never present. This is a marker that preserves the type of the value of each family member */
425
- __T?: T;
426
- /** Never present. This is a marker that preserves the type of keys used for each family member */
427
- __K?: K;
428
- };
429
- type WritableHeldSelectorFamilyToken<T, K extends Canonical> = {
430
- /** The unique identifier of the family */
431
- key: string;
432
- /** Discriminator */
433
- type: `writable_held_selector_family`;
434
- /** Never present. This is a marker that preserves the type of the value of each family member */
435
- __T?: T;
436
- /** Never present. This is a marker that preserves the type of keys used for each family member */
437
- __K?: K;
438
- };
439
- type ReadonlyHeldSelectorFamilyToken<T, K extends Canonical> = {
440
- /** The unique identifier of the family */
441
- key: string;
442
- /** Discriminator */
443
- type: `readonly_held_selector_family`;
444
- /** Never present. This is a marker that preserves the type of the value of each family member */
445
- __T?: T;
446
- /** Never present. This is a marker that preserves the type of keys used for each family member */
447
- __K?: K;
448
- };
449
- type PureSelectorFamilyToken<T, K extends Canonical> = ReadonlyPureSelectorFamilyToken<T, K> | WritablePureSelectorFamilyToken<T, K>;
450
- type HeldSelectorFamilyToken<T, K extends Canonical> = ReadonlyHeldSelectorFamilyToken<T, K> | WritableHeldSelectorFamilyToken<T, K>;
451
- type ReadonlySelectorFamilyToken<T, K extends Canonical> = ReadonlyHeldSelectorFamilyToken<T, K> | ReadonlyPureSelectorFamilyToken<T, K>;
452
- type WritableSelectorFamilyToken<T, K extends Canonical> = WritableHeldSelectorFamilyToken<T, K> | WritablePureSelectorFamilyToken<T, K>;
453
- type SelectorFamilyToken<T, K extends Canonical> = HeldSelectorFamilyToken<T, K> | PureSelectorFamilyToken<T, K>;
390
+ declare function findState<T, K extends Canonical, Key extends K>(token: ReadonlySelectorFamilyToken$1<T, K>, key: Key): ReadonlySelectorToken$1<T, K>;
454
391
  /**
455
- * @public
456
- * Create a family of selectors, allowing for the dynamic creation and disposal of selectors.
457
- *
458
- * The value of a held selector should depend on the value of atoms or other selectors in the store,
459
- * and should be recycled when a root atom of the selector is set.
392
+ * Finds a {@link WritableToken} in the store, without accessing its value.
460
393
  *
461
- * A held selector's value must be some object.
462
- * The reference to that object is permanent and will not be replaced.
394
+ * In an ephemeral store, this will create a new atom or selector if one does not exist with the given key.
463
395
  *
464
- * A writable selector can be "set" to a new value.
465
- * It is advised to set its dependencies to values
466
- * that would produce the new value of the selector.
396
+ * In an immortal store, a "counterfeit" token will be returned in this case and a warning will be logged.
467
397
  *
468
- * @param options - {@link WritableHeldSelectorFamilyOptions}.
398
+ * @param token - The token of the state family
399
+ * @param key - The key of the state
469
400
  * @returns
470
- * A reference to the selector family created: a {@link WritableHeldSelectorFamilyToken}
471
- * @overload WritableHeld
401
+ * The current value of the state
402
+ * @overload Writable State
472
403
  */
473
- declare function selectorFamily<T extends object, K extends Canonical>(options: WritableHeldSelectorFamilyOptions<T, K>): WritableHeldSelectorFamilyToken<T, K>;
404
+ declare function findState<T, K extends Canonical, Key extends K>(token: WritableFamilyToken$1<T, K>, key: Key): WritableToken$1<T, K>;
474
405
  /**
475
- * @public
476
- * Create a family of selectors, allowing for the dynamic creation and disposal of selectors.
477
- *
478
- * The value of a held selector should depend on the value of atoms or other selectors in the store,
479
- * and should be recycled when a root atom of the selector is set.
406
+ * Finds a {@link MutableAtomToken} in the store, without accessing its value.
480
407
  *
481
- * A held selector's value must be some object.
482
- * The reference to that object is permanent and will not be replaced.
408
+ * In an ephemeral store, this will create a new atom or selector if one does not exist with the given key.
483
409
  *
484
- * A readonly selector can be "gotten" but not "set".
410
+ * In an immortal store, a "counterfeit" token will be returned in this case and a warning will be logged.
485
411
  *
486
- * @param options - {@link ReadonlyHeldSelectorFamilyOptions}.
412
+ * @param token - A {@link ReadableFamilyToken}
413
+ * @param key - The key of the state
487
414
  * @returns
488
- * A reference to the selector family created: a {@link ReadonlyHeldSelectorFamilyToken}
489
- * @overload ReadonlyHeld
415
+ * The current value of the state
416
+ * @overload Unknown
417
+ * @default
490
418
  */
491
- declare function selectorFamily<T extends object, K extends Canonical>(options: ReadonlyHeldSelectorFamilyOptions<T, K>): ReadonlyHeldSelectorFamilyToken<T, K>;
419
+ declare function findState<T, K extends Canonical, Key extends K>(token: ReadableFamilyToken$1<T, K>, key: Key): ReadableToken$1<T, K>;
420
+ //#endregion
421
+ //#region src/main/get-state.d.ts
492
422
  /**
493
- * @public
494
- * Create a family of selectors, allowing for the dynamic creation and disposal of selectors.
495
- *
496
- * The value of a selector should depend on the value of atoms or other selectors in the store.
423
+ * Read or compute the current value of a state
424
+ * @param token - The token of the state to get
425
+ * @return The current value of the state
426
+ * @overload Default
427
+ * @default
428
+ */
429
+ declare function getState<T>(token: ReadableToken<T>): T;
430
+ /**
431
+ * Read or compute the current value of a state
432
+ * @param token - The token of a state family
433
+ * @param key - The unique key of the state to get
434
+ * @return The current value of the state
435
+ * @overload Streamlined
436
+ */
437
+ declare function getState<T, K extends Canonical, Key extends K>(token: ReadableFamilyToken<T, K>, key: Key): T;
438
+ //#endregion
439
+ //#region src/main/join.d.ts
440
+ type JoinOptions<ASide extends string, AType extends string, BSide extends string, BType extends string, Cardinality extends `1:1` | `1:n` | `n:n`, Content extends Json.Object | null> = Flat<JunctionSchemaBase<ASide, BSide> & {
441
+ /** Unique identifier of the join */
442
+ readonly key: string;
443
+ /** How many relations are allowed in each direction? */
444
+ readonly cardinality: Cardinality;
445
+ /** Type guard for the type of the left side */
446
+ readonly isAType: Refinement<string, AType>;
447
+ /** Type guard for the type of the right side */
448
+ readonly isBType: Refinement<string, BType>;
449
+ }> & Partial<JunctionEntriesBase<AType, BType, Content>>;
450
+ type JoinToken<ASide extends string, AType extends string, BSide extends string, BType extends string, Cardinality extends `1:1` | `1:n` | `n:n`, Content extends Json.Object | null = null> = {
451
+ /** Unique identifier of the join */
452
+ key: string;
453
+ /** Discriminator */
454
+ type: `join`;
455
+ /** How many relations are allowed in each direction? */
456
+ cardinality: Cardinality;
457
+ /** Name of the join's left side */
458
+ a: ASide;
459
+ /** Name of the join's right side */
460
+ b: BSide;
461
+ /** Never present. This is a marker that preserves the type of the left side's keys */
462
+ __aType?: AType;
463
+ /** Never present. This is a marker that preserves the type of the right side's keys */
464
+ __bType?: BType;
465
+ /** Never present. This is a marker that preserves the type of the data present for each relation */
466
+ __content?: Content;
467
+ };
468
+ /**
469
+ * Create a join, an interface for managing relations between two sets of keys.
497
470
  *
498
- * A pure selector's current value is evicted from the store
499
- * in order to be garbage collected when a root atom of the selector is set.
471
+ * Use joins when it is important to view relationships from either side.
500
472
  *
501
- * A writable selector can be "set" to a new value.
502
- * It is advised to set its dependencies to values
503
- * that would produce the new value of the selector.
473
+ * Under the hood, joins coordinate changes of multiple atoms to support that the desired relationships stay consistent.
504
474
  *
505
- * @param options - {@link TransientWritableSelectorFamilyOptions}.
475
+ * @param options - {@link JoinOptions}
476
+ * @param defaultContent - (undefined)
506
477
  * @returns
507
- * A reference to the selector family created: a {@link TransientWritableSelectorFamilyToken}
508
- * @overload WritablePure
478
+ * A reference to the join created: a {@link JoinToken}
479
+ * @overload No Content
509
480
  */
510
- declare function selectorFamily<T, K extends Canonical>(options: WritablePureSelectorFamilyOptions<T, K>): WritablePureSelectorFamilyToken<T, K>;
481
+ declare function join<const ASide extends string, const AType extends string, const BSide extends string, const BType extends string, const Cardinality extends `1:1` | `1:n` | `n:n`>(options: JoinOptions<ASide, AType, BSide, BType, Cardinality, null>, defaultContent?: undefined): JoinToken<ASide, AType, BSide, BType, Cardinality, null>;
511
482
  /**
512
- * @public
513
- * Create a family of selectors, allowing for the dynamic creation and disposal of selectors.
514
- *
515
- * The value of a selector should depend on the value of atoms or other selectors in the store.
483
+ * Create a join, an interface for managing relations between two sets of keys.
516
484
  *
517
- * A pure selector's current value is evicted from the store
518
- * in order to be garbage collected when a root atom of the selector is set.
485
+ * Use joins when it is important to view relationships from either side.
519
486
  *
520
- * A readonly selector can be "gotten" but not "set".
487
+ * Under the hood, joins coordinate changes of multiple atoms to support that the desired relationships stay consistent.
521
488
  *
522
- * @param options - {@link ReadonlyPureSelectorFamilyOptions}.
489
+ * @param options - {@link JoinOptions}
490
+ * @param defaultContent - The default value for the content of each relation
523
491
  * @returns
524
- * A reference to the selector family created: a {@link ReadonlyPureSelectorFamilyToken}
525
- * @overload ReadonlyPure
492
+ * A reference to the join created: a {@link JoinToken}
493
+ * @overload With Content
526
494
  */
527
- declare function selectorFamily<T, K extends Canonical>(options: ReadonlyPureSelectorFamilyOptions<T, K>): ReadonlyPureSelectorFamilyToken<T, K>;
528
- //#endregion
529
- //#region src/main/timeline.d.ts
530
- /** @public */
531
- type TimelineManageable = AtomFamilyToken<any, any> | AtomToken<any>;
532
- /** @public */
533
- type AtomOnly<M extends TimelineManageable> = M extends AtomFamilyToken<any, any> ? AtomToken<any> : M extends AtomToken<any> ? M : never;
534
- /** @public */
535
- type TimelineToken<M> = {
536
- /** The unique identifier of the timeline */
537
- key: string;
538
- /** Discriminator */
539
- type: `timeline`;
540
- /** Never present. This is a marker that preserves the type of the managed atoms */
541
- __M?: M;
542
- };
495
+ declare function join<const ASide extends string, const AType extends string, const BSide extends string, const BType extends string, const Cardinality extends `1:1` | `1:n` | `n:n`, const Content extends Json.Object>(options: JoinOptions<ASide, AType, BSide, BType, Cardinality, Content>, defaultContent: Content): JoinToken<ASide, AType, BSide, BType, Cardinality, Content>;
496
+ type JoinStates<ASide extends string, AType extends string, BSide extends string, BType extends string, Cardinality extends `1:1` | `1:n` | `n:n`, Content extends Json.Object | null> = Cardinality extends `1:1` ? (Content extends Json.Object ? { readonly [A in ASide as `${A}EntryOf${Capitalize<BSide>}`]: ReadonlyPureSelectorToken$1<[AType, Content] | null, BType> } & { readonly [B in BSide as `${B}EntryOf${Capitalize<ASide>}`]: ReadonlyPureSelectorToken$1<[BType, Content] | null, AType> } : {}) & { readonly [A in ASide as `${A}KeyOf${Capitalize<BSide>}`]: ReadonlyPureSelectorToken$1<AType | null, BType> } & { readonly [B in BSide as `${B}KeyOf${Capitalize<ASide>}`]: ReadonlyPureSelectorToken$1<BType | null, AType> } : Cardinality extends `1:n` ? (Content extends Json.Object ? { readonly [A in ASide as `${A}EntryOf${Capitalize<BSide>}`]: ReadonlyPureSelectorToken$1<[AType, Content] | null, BType> } & { readonly [B in BSide as `${B}EntriesOf${Capitalize<ASide>}`]: ReadonlyPureSelectorToken$1<[BType, Content][], AType> } : {}) & { readonly [A in ASide as `${A}KeyOf${Capitalize<BSide>}`]: ReadonlyPureSelectorToken$1<AType | null, BType> } & { readonly [B in BSide as `${B}KeysOf${Capitalize<ASide>}`]: ReadonlyPureSelectorToken$1<BType[], AType> } : Cardinality extends `n:n` ? (Content extends Json.Object ? { readonly [A in ASide as `${A}EntriesOf${Capitalize<BSide>}`]: ReadonlyPureSelectorToken$1<[AType, Content][], BType> } & { readonly [B in BSide as `${B}EntriesOf${Capitalize<ASide>}`]: ReadonlyPureSelectorToken$1<[BType, Content][], AType> } : {}) & { readonly [A in ASide as `${A}KeysOf${Capitalize<BSide>}`]: ReadonlyPureSelectorToken$1<AType[], BType> } & { readonly [B in BSide as `${B}KeysOf${Capitalize<ASide>}`]: ReadonlyPureSelectorToken$1<BType[], AType> } : never;
543
497
  /**
544
- * @public
545
- * If there is an update ahead of the cursor (in the future of this {@link timeline}), apply it and move the cursor to the next update
546
- * @param timeline - A {@link TimelineToken}
498
+ * Find the current value of a relation owned by a {@link join}
499
+ * @param token - The token of the join
500
+ * @param key - The key of the relation to find
501
+ * @returns
502
+ * A {@link JoinStates} interface to access the relation
503
+ * @overload Default
547
504
  */
548
- declare const redo: (timeline: TimelineToken<any>) => void;
505
+ declare function findRelations<ASide extends string, AType extends string, BSide extends string, BType extends string, Cardinality extends `1:1` | `1:n` | `n:n`, Content extends Json.Object | null>(token: JoinToken<ASide, AType, BSide, BType, Cardinality, Content>, key: AType | BType): JoinStates<ASide, AType, BSide, BType, Cardinality, Content>;
549
506
  /**
550
- * @public
551
- * Reverse the last update on the {@link timeline} and move the cursor to the previous update
552
- * @param timeline - A {@link TimelineToken}
507
+ * Change one or multiple relations owned by a {@link join}
508
+ * @param token - The token of the join
509
+ * @param change - A function that takes a {@link Junction} interface to edit the relations
553
510
  */
554
- declare const undo: (timeline: TimelineToken<any>) => void;
555
- /** @public */
556
- type TimelineUpdate<ManagedAtom extends TimelineManageable> = TimelineAtomUpdate<ManagedAtom> | TimelineMoleculeCreation | TimelineMoleculeDisposal | TimelineSelectorUpdate<ManagedAtom> | TimelineStateCreation<AtomOnly<ManagedAtom>> | TimelineStateDisposal<AtomOnly<ManagedAtom>> | TimelineTransactionUpdate;
557
- /** @public */
558
- type TimelineOptions<ManagedAtom extends TimelineManageable> = {
559
- /** The unique identifier of the timeline */
560
- key: string;
561
- /** The managed atoms (and families of atoms) to record */
562
- scope: ManagedAtom[];
563
- /** A function that determines whether a given update should be recorded */
564
- shouldCapture?: (update: TimelineUpdate<ManagedAtom>, timeline: Timeline<TimelineManageable>) => boolean;
565
- };
511
+ declare function editRelations<ASide extends string, AType extends string, BSide extends string, BType extends string, Cardinality extends `1:1` | `1:n` | `n:n`, Content extends Json.Object | null>(token: JoinToken<ASide, AType, BSide, BType, Cardinality, Content>, change: (relations: Junction<ASide, AType, BSide, BType, Content>) => void): void;
566
512
  /**
567
- * @public
568
- * Create a timeline, a mechanism for recording, undoing, and replaying changes to groups of atoms
569
- * @param options - {@link TimelineOptions}
570
- * @returns A reference to the timeline created: a {@link TimelineToken}
513
+ * @param token - The token of the join
514
+ * @returns
515
+ * A {@link MutableAtomFamilyToken} to access the internal relations
571
516
  */
572
- declare const timeline: <ManagedAtom extends TimelineManageable>(options: TimelineOptions<ManagedAtom>) => TimelineToken<ManagedAtom>;
573
- //#endregion
574
- //#region src/main/dispose-state.d.ts
575
- /**
576
- * @public
577
- * Disposes of a state in the implicit store.
578
- *
579
- * Only family members can be disposed of.
580
- *
581
- * @param token - The token of the state to dispose
582
- * @overload Default
583
- */
584
- declare function disposeState(token: ReadableToken<any>): void;
585
- /**
586
- * @public
587
- * Disposes of a state in the implicit store.
588
- *
589
- * Only family members can be disposed of.
590
- *
591
- * @param token - The token of the state family to dispose
592
- * @param key - The unique key of the state to dispose
593
- */
594
- declare function disposeState<K extends Canonical>(token: ReadableFamilyToken<any, K>, key: K): void;
595
- //#endregion
596
- //#region src/main/find-state.d.ts
597
- /**
598
- * @public
599
- * Finds a {@link MutableAtomToken} in the store, without accessing its value.
600
- *
601
- * In an ephemeral store, this will create a new atom if one does not exist with the given key.
602
- *
603
- * In an immortal store, a "counterfeit" atom token will be returned in this case and a warning will be logged.
604
- *
605
- * @param token - A {@link MutableAtomFamilyToken}
606
- * @param key - The key of the state
607
- * @returns
608
- * The current value of the state
609
- * @overload Mutable Atom
610
- */
611
- declare function findState<T extends Transceiver<any>, J extends Json.Serializable, K extends Canonical, Key extends K>(token: MutableAtomFamilyToken$1<T, J, K>, key: Key): MutableAtomToken$1<T, J, K>;
612
- /**
613
- * @public
614
- * Finds a {@link RegularAtomToken} in the store, without accessing its value.
615
- *
616
- * In an ephemeral store, this will create a new atom if one does not exist with the given key.
617
- *
618
- * In an immortal store, a "counterfeit" atom token will be returned in this case and a warning will be logged.
619
- *
620
- * @param token - The token of the state family
621
- * @param key - The key of the state
622
- * @returns
623
- * The current value of the state
624
- * @overload Regular Atom
625
- */
626
- declare function findState<T, K extends Canonical, Key extends K>(token: RegularAtomFamilyToken$1<T, K>, key: Key): RegularAtomToken$1<T, K>;
627
- /**
628
- * @public
629
- * Finds a {@link WritableSelectorToken} in the store, without accessing its value.
630
- *
631
- * In an ephemeral store, this will create a new selector if one does not exist with the given key.
632
- *
633
- * In an immortal store, a "counterfeit" selector token will be returned in this case and a warning will be logged.
634
- *
635
- * @param token - The token of the state family
636
- * @param key - The key of the state
637
- * @returns
638
- * The current value of the state
639
- * @overload Writable Selector
640
- */
641
- declare function findState<T, K extends Canonical, Key extends K>(token: WritableSelectorFamilyToken$1<T, K>, key: Key): WritableSelectorToken$1<T, K>;
642
- /**
643
- * @public
644
- * Finds a {@link ReadonlySelectorToken} in the store, without accessing its value.
645
- *
646
- * In an ephemeral store, this will create a new selector if one does not exist with the given key.
647
- *
648
- * In an immortal store, a "counterfeit" selector token will be returned in this case and a warning will be logged.
649
- *
650
- * @param token - The token of the state family
651
- * @param key - The key of the state
652
- * @returns
653
- * The current value of the state
654
- * @overload Readonly Selector
655
- */
656
- declare function findState<T, K extends Canonical, Key extends K>(token: ReadonlySelectorFamilyToken$1<T, K>, key: Key): ReadonlySelectorToken$1<T, K>;
657
- /**
658
- * @public
659
- * Finds a {@link WritableToken} in the store, without accessing its value.
660
- *
661
- * In an ephemeral store, this will create a new atom or selector if one does not exist with the given key.
662
- *
663
- * In an immortal store, a "counterfeit" token will be returned in this case and a warning will be logged.
664
- *
665
- * @param token - The token of the state family
666
- * @param key - The key of the state
667
- * @returns
668
- * The current value of the state
669
- * @overload Writable State
670
- */
671
- declare function findState<T, K extends Canonical, Key extends K>(token: WritableFamilyToken$1<T, K>, key: Key): WritableToken$1<T, K>;
672
- /**
673
- * @public
674
- * Finds a {@link MutableAtomToken} in the store, without accessing its value.
675
- *
676
- * In an ephemeral store, this will create a new atom or selector if one does not exist with the given key.
677
- *
678
- * In an immortal store, a "counterfeit" token will be returned in this case and a warning will be logged.
679
- *
680
- * @param token - A {@link ReadableFamilyToken}
681
- * @param key - The key of the state
682
- * @returns
683
- * The current value of the state
684
- * @overload Unknown
685
- * @default
686
- */
687
- declare function findState<T, K extends Canonical, Key extends K>(token: ReadableFamilyToken$1<T, K>, key: Key): ReadableToken$1<T, K>;
688
- //#endregion
689
- //#region src/main/get-state.d.ts
690
- /**
691
- * @public
692
- * Read or compute the current value of a state
693
- * @param token - The token of the state to get
694
- * @return The current value of the state
695
- * @overload Default
696
- * @default
697
- */
698
- declare function getState<T>(token: ReadableToken<T>): T;
699
- /**
700
- * @public
701
- * Read or compute the current value of a state
702
- * @param token - The token of a state family
703
- * @param key - The unique key of the state to get
704
- * @return The current value of the state
705
- * @overload Streamlined
706
- */
707
- declare function getState<T, K extends Canonical, Key extends K>(token: ReadableFamilyToken<T, K>, key: Key): T;
708
- //#endregion
709
- //#region src/main/join.d.ts
710
- /** @public */
711
- type JoinOptions<ASide extends string, AType extends string, BSide extends string, BType extends string, Cardinality extends `1:1` | `1:n` | `n:n`, Content extends Json.Object | null> = Flat<JunctionSchemaBase<ASide, BSide> & {
712
- /** Unique identifier of the join */
713
- readonly key: string;
714
- /** How many relations are allowed in each direction? */
715
- readonly cardinality: Cardinality;
716
- /** Type guard for the type of the left side */
717
- readonly isAType: Refinement<string, AType>;
718
- /** Type guard for the type of the right side */
719
- readonly isBType: Refinement<string, BType>;
720
- }> & Partial<JunctionEntriesBase<AType, BType, Content>>;
721
- /** @public */
722
- type JoinToken<ASide extends string, AType extends string, BSide extends string, BType extends string, Cardinality extends `1:1` | `1:n` | `n:n`, Content extends Json.Object | null = null> = {
723
- /** Unique identifier of the join */
724
- key: string;
725
- /** Discriminator */
726
- type: `join`;
727
- /** How many relations are allowed in each direction? */
728
- cardinality: Cardinality;
729
- /** Name of the join's left side */
730
- a: ASide;
731
- /** Name of the join's right side */
732
- b: BSide;
733
- /** Never present. This is a marker that preserves the type of the left side's keys */
734
- __aType?: AType;
735
- /** Never present. This is a marker that preserves the type of the right side's keys */
736
- __bType?: BType;
737
- /** Never present. This is a marker that preserves the type of the data present for each relation */
738
- __content?: Content;
739
- };
740
- /**
741
- * @public
742
- * Create a join, an interface for managing relations between two sets of keys.
743
- *
744
- * Use joins when it is important to view relationships from either side.
745
- *
746
- * Under the hood, joins coordinate changes of multiple atoms to support that the desired relationships stay consistent.
747
- *
748
- * @param options - {@link JoinOptions}
749
- * @param defaultContent - (undefined)
750
- * @returns
751
- * A reference to the join created: a {@link JoinToken}
752
- * @overload No Content
753
- */
754
- declare function join<const ASide extends string, const AType extends string, const BSide extends string, const BType extends string, const Cardinality extends `1:1` | `1:n` | `n:n`>(options: JoinOptions<ASide, AType, BSide, BType, Cardinality, null>, defaultContent?: undefined): JoinToken<ASide, AType, BSide, BType, Cardinality, null>;
755
- /**
756
- * @public
757
- * Create a join, an interface for managing relations between two sets of keys.
758
- *
759
- * Use joins when it is important to view relationships from either side.
760
- *
761
- * Under the hood, joins coordinate changes of multiple atoms to support that the desired relationships stay consistent.
762
- *
763
- * @param options - {@link JoinOptions}
764
- * @param defaultContent - The default value for the content of each relation
765
- * @returns
766
- * A reference to the join created: a {@link JoinToken}
767
- * @overload With Content
768
- */
769
- declare function join<const ASide extends string, const AType extends string, const BSide extends string, const BType extends string, const Cardinality extends `1:1` | `1:n` | `n:n`, const Content extends Json.Object>(options: JoinOptions<ASide, AType, BSide, BType, Cardinality, Content>, defaultContent: Content): JoinToken<ASide, AType, BSide, BType, Cardinality, Content>;
770
- type JoinStates<ASide extends string, AType extends string, BSide extends string, BType extends string, Cardinality extends `1:1` | `1:n` | `n:n`, Content extends Json.Object | null> = Cardinality extends `1:1` ? (Content extends Json.Object ? { readonly [A in ASide as `${A}EntryOf${Capitalize<BSide>}`]: ReadonlyPureSelectorToken$1<[AType, Content] | null, BType> } & { readonly [B in BSide as `${B}EntryOf${Capitalize<ASide>}`]: ReadonlyPureSelectorToken$1<[BType, Content] | null, AType> } : {}) & { readonly [A in ASide as `${A}KeyOf${Capitalize<BSide>}`]: ReadonlyPureSelectorToken$1<AType | null, BType> } & { readonly [B in BSide as `${B}KeyOf${Capitalize<ASide>}`]: ReadonlyPureSelectorToken$1<BType | null, AType> } : Cardinality extends `1:n` ? (Content extends Json.Object ? { readonly [A in ASide as `${A}EntryOf${Capitalize<BSide>}`]: ReadonlyPureSelectorToken$1<[AType, Content] | null, BType> } & { readonly [B in BSide as `${B}EntriesOf${Capitalize<ASide>}`]: ReadonlyPureSelectorToken$1<[BType, Content][], AType> } : {}) & { readonly [A in ASide as `${A}KeyOf${Capitalize<BSide>}`]: ReadonlyPureSelectorToken$1<AType | null, BType> } & { readonly [B in BSide as `${B}KeysOf${Capitalize<ASide>}`]: ReadonlyPureSelectorToken$1<BType[], AType> } : Cardinality extends `n:n` ? (Content extends Json.Object ? { readonly [A in ASide as `${A}EntriesOf${Capitalize<BSide>}`]: ReadonlyPureSelectorToken$1<[AType, Content][], BType> } & { readonly [B in BSide as `${B}EntriesOf${Capitalize<ASide>}`]: ReadonlyPureSelectorToken$1<[BType, Content][], AType> } : {}) & { readonly [A in ASide as `${A}KeysOf${Capitalize<BSide>}`]: ReadonlyPureSelectorToken$1<AType[], BType> } & { readonly [B in BSide as `${B}KeysOf${Capitalize<ASide>}`]: ReadonlyPureSelectorToken$1<BType[], AType> } : never;
771
- /**
772
- * @public
773
- * Find the current value of a relation owned by a {@link join}
774
- * @param token - The token of the join
775
- * @param key - The key of the relation to find
776
- * @returns
777
- * A {@link JoinStates} interface to access the relation
778
- * @overload Default
779
- */
780
- declare function findRelations<ASide extends string, AType extends string, BSide extends string, BType extends string, Cardinality extends `1:1` | `1:n` | `n:n`, Content extends Json.Object | null>(token: JoinToken<ASide, AType, BSide, BType, Cardinality, Content>, key: AType | BType): JoinStates<ASide, AType, BSide, BType, Cardinality, Content>;
781
- /**
782
- * @public
783
- * Change one or multiple relations owned by a {@link join}
784
- * @param token - The token of the join
785
- * @param change - A function that takes a {@link Junction} interface to edit the relations
786
- */
787
- declare function editRelations<ASide extends string, AType extends string, BSide extends string, BType extends string, Cardinality extends `1:1` | `1:n` | `n:n`, Content extends Json.Object | null>(token: JoinToken<ASide, AType, BSide, BType, Cardinality, Content>, change: (relations: Junction<ASide, AType, BSide, BType, Content>) => void): void;
788
- /**
789
- * @public
790
- * @param token - The token of the join
791
- * @returns
792
- * A {@link MutableAtomFamilyToken} to access the internal relations
793
- */
794
- declare function getInternalRelations<ASide extends string, AType extends string, BSide extends string, BType extends string, Cardinality extends `1:1` | `1:n` | `n:n`, Content extends Json.Object | null>(token: JoinToken<ASide, AType, BSide, BType, Cardinality, Content>): MutableAtomFamilyToken$1<SetRTX<string>, SetRTXJson<string>, string>;
517
+ declare function getInternalRelations<ASide extends string, AType extends string, BSide extends string, BType extends string, Cardinality extends `1:1` | `1:n` | `n:n`, Content extends Json.Object | null>(token: JoinToken<ASide, AType, BSide, BType, Cardinality, Content>): MutableAtomFamilyToken$1<SetRTX<string>, SetRTXJson<string>, string>;
795
518
  //#endregion
796
519
  //#region src/main/logger.d.ts
797
520
  declare const LOGGER_ICON_DICTIONARY: {
@@ -950,53 +673,380 @@ type ExclusiveFealty = {
950
673
  above: TypedKey | `root`;
951
674
  below: Scope;
952
675
  };
953
- type Fealty = ExclusiveFealty | MutualFealty;
954
- type Hierarchy<F extends Fealty[] = Fealty[]> = Each<F>;
955
- type Vassal<H extends Hierarchy> = { [K in keyof H]: H[K] extends MutualFealty ? H[K][`below`] : H[K] extends {
956
- below: Array<infer V>;
957
- } ? V extends TypedKey ? V : never : never }[keyof H];
958
- type Above<TK extends TypedKey, H extends Hierarchy> = { [K in keyof H]: H[K] extends MutualFealty ? TK extends H[K][`below`] ? H[K][`above`] : never : H[K] extends {
959
- below: Array<infer V>;
960
- } ? TK extends V ? H[K] extends ExclusiveFealty ? H[K][`above`] : never : never : never }[keyof H];
961
- type Below<TK extends TypedKey | TypedKey[], H extends Hierarchy> = { [K in keyof H]: H[K] extends MutualFealty ? TK extends H[K][`above`] ? H[K][`below`] : TK extends H[K][`above`][number] ? H[K][`below`] : never : H[K] extends {
962
- above: infer V;
963
- } ? TK extends V ? H[K] extends ExclusiveFealty ? H[K][`below`][number] : never : never : never }[keyof H];
964
- type Mutuals<TK extends TypedKey | TypedKey[], H extends Hierarchy> = { [K in keyof H]: H[K] extends MutualFealty ? TK extends H[K][`above`][number] ? [mutual: Exclude<H[K][`above`][number], TK>, below: H[K][`below`]] : never : never }[keyof H];
965
- type CompoundFrom<H extends Hierarchy> = { [K in keyof H]: H[K] extends MutualFealty ? H[K][`below`] : never }[keyof H];
966
- //#endregion
967
- //#region src/main/set-state.d.ts
676
+ type Fealty = ExclusiveFealty | MutualFealty;
677
+ type Hierarchy<F extends Fealty[] = Fealty[]> = Each<F>;
678
+ type Vassal<H extends Hierarchy> = { [K in keyof H]: H[K] extends MutualFealty ? H[K][`below`] : H[K] extends {
679
+ below: Array<infer V>;
680
+ } ? V extends TypedKey ? V : never : never }[keyof H];
681
+ type Above<TK extends TypedKey, H extends Hierarchy> = { [K in keyof H]: H[K] extends MutualFealty ? TK extends H[K][`below`] ? H[K][`above`] : never : H[K] extends {
682
+ below: Array<infer V>;
683
+ } ? TK extends V ? H[K] extends ExclusiveFealty ? H[K][`above`] : never : never : never }[keyof H];
684
+ type Below<TK extends TypedKey | TypedKey[], H extends Hierarchy> = { [K in keyof H]: H[K] extends MutualFealty ? TK extends H[K][`above`] ? H[K][`below`] : TK extends H[K][`above`][number] ? H[K][`below`] : never : H[K] extends {
685
+ above: infer V;
686
+ } ? TK extends V ? H[K] extends ExclusiveFealty ? H[K][`below`][number] : never : never : never }[keyof H];
687
+ type Mutuals<TK extends TypedKey | TypedKey[], H extends Hierarchy> = { [K in keyof H]: H[K] extends MutualFealty ? TK extends H[K][`above`][number] ? [mutual: Exclude<H[K][`above`][number], TK>, below: H[K][`below`]] : never : never }[keyof H];
688
+ type CompoundFrom<H extends Hierarchy> = { [K in keyof H]: H[K] extends MutualFealty ? H[K][`below`] : never }[keyof H];
689
+ //#endregion
690
+ //#region src/main/reset-state.d.ts
691
+ /**
692
+ * Set the value of a state into the implicit store back to its default value.
693
+ * @param token - An atom or writable selector token.
694
+ * @overload Default
695
+ * @default
696
+ */
697
+ declare function resetState(token: WritableToken<any>): void;
698
+ /**
699
+ * Set the value of a state into the implicit store back to its default value.
700
+ * @param token - An atom family or writable selector family token.
701
+ * @param key - The unique key of the state to set.
702
+ * @overload Streamlined
703
+ */
704
+ declare function resetState<K extends Canonical>(token: WritableFamilyToken<any, K>, key: K): void;
705
+ //#endregion
706
+ //#region src/main/subscribe.d.ts
707
+ type StateUpdate<T> = {
708
+ newValue: T;
709
+ oldValue: T;
710
+ };
711
+ type KeyedStateUpdate<T> = Flat<StateUpdate<T> & {
712
+ key: string;
713
+ type: `atom_update` | `selector_update`;
714
+ family?: FamilyMetadata;
715
+ }>;
716
+ type UpdateHandler<T> = (update: StateUpdate<T>) => void;
717
+ type TransactionUpdateHandler<F extends Func> = (data: TransactionUpdate<F>) => void;
718
+ /**
719
+ * Subscribe to a state in the implicit store
720
+ * @param token - The token of the state to subscribe to
721
+ * @param handleUpdate - A function that will be called when the state is updated
722
+ * @param key - A unique key for the subscription. If not provided, a random key will be generated.
723
+ * @returns A function that can be called to unsubscribe from the state
724
+ * @overload State
725
+ */
726
+ declare function subscribe<T>(token: ReadableToken<T>, handleUpdate: UpdateHandler<T>, key?: string): () => void;
727
+ /**
728
+ * Subscribe to a transaction in the implicit store
729
+ * @param token - The token of the transaction to subscribe to
730
+ * @param handleUpdate - A function that will be called when the transaction succeeds
731
+ * @param key - A unique key for the subscription. If not provided, a random key will be generated.
732
+ * @returns A function that can be called to unsubscribe from the transaction
733
+ * @overload Transaction
734
+ */
735
+ declare function subscribe<F extends Func>(token: TransactionToken<F>, handleUpdate: TransactionUpdateHandler<F>, key?: string): () => void;
736
+ /**
737
+ * Subscribe to a timeline in the implicit store
738
+ * @param token - The token of the timeline to subscribe to
739
+ * @param handleUpdate - A function that will be called when a new update is available
740
+ * @param key - A unique key for the subscription. If not provided, a random key will be generated.
741
+ * @returns A function that can be called to unsubscribe from the timeline
742
+ * @overload Timeline
743
+ */
744
+ declare function subscribe<M extends TimelineManageable>(token: TimelineToken<M>, handleUpdate: (update: TimelineUpdate<M> | `redo` | `undo`) => void, key?: string): () => void;
745
+ //#endregion
746
+ //#region src/main/validators.d.ts
747
+ type TokenType<Comparison extends ReadableFamilyToken<any, any> | ReadableToken<any>> = Comparison extends ReadableToken<infer RepresentedValue> ? RepresentedValue : Comparison extends ReadableFamilyToken<infer RepresentedValue, any> ? RepresentedValue : never;
748
+ declare function isToken<KnownToken extends RegularAtomToken<any>>(knownToken: KnownToken, unknownToken: ReadableToken<any>): unknownToken is RegularAtomToken<TokenType<KnownToken>>;
749
+ declare function isToken<KnownToken extends MutableAtomToken<any, any>>(knownToken: KnownToken, unknownToken: ReadableToken<any>): unknownToken is MutableAtomToken<TokenType<KnownToken>, any>;
750
+ declare function isToken<KnownToken extends WritablePureSelectorToken<any>>(knownToken: KnownToken, unknownToken: ReadableToken<any>): unknownToken is WritablePureSelectorToken<TokenType<KnownToken>>;
751
+ declare function isToken<KnownToken extends ReadonlyPureSelectorToken<any>>(knownToken: KnownToken, unknownToken: ReadableToken<any>): unknownToken is ReadonlyPureSelectorToken<TokenType<KnownToken>>;
752
+ declare function isToken<KnownToken extends WritableToken<any>>(knownToken: KnownToken, unknownToken: ReadableToken<any>): unknownToken is WritableToken<TokenType<KnownToken>>;
753
+ declare function isToken<KnownToken extends ReadableToken<any>>(knownToken: KnownToken, unknownToken: ReadableToken<any>): unknownToken is ReadableToken<TokenType<KnownToken>>;
754
+ declare function belongsTo<Family extends RegularAtomFamilyToken<any, any>>(family: Family, unknownToken: ReadableToken<any>): unknownToken is RegularAtomToken<TokenType<Family>>;
755
+ declare function belongsTo<Family extends MutableAtomFamilyToken<any, any, any>>(family: Family, unknownToken: ReadableToken<any>): unknownToken is MutableAtomToken<TokenType<Family>, any>;
756
+ declare function belongsTo<Family extends WritablePureSelectorFamilyToken<any, any>>(family: Family, unknownToken: ReadableToken<any>): unknownToken is WritablePureSelectorToken<TokenType<Family>>;
757
+ declare function belongsTo<Family extends ReadonlyPureSelectorFamilyToken<any, any>>(family: Family, unknownToken: ReadableToken<any>): unknownToken is ReadonlyPureSelectorToken<TokenType<Family>>;
758
+ declare function belongsTo<Family extends WritableFamilyToken<any, any>>(family: Family, unknownToken: ReadableToken<any>): unknownToken is WritableToken<TokenType<Family>>;
759
+ declare function belongsTo<Family extends ReadableFamilyToken<any, any>>(family: Family, unknownToken: ReadableToken<any>): unknownToken is ReadableToken<TokenType<Family>>;
760
+ //#endregion
761
+ //#region src/main/transaction.d.ts
762
+ type StateCreation<Token extends ReadableToken<any>> = {
763
+ type: `state_creation`;
764
+ token: Token;
765
+ };
766
+ type StateDisposal<Token extends ReadableToken<any>> = AtomDisposal<Token> | SelectorDisposal<Token>;
767
+ type AtomDisposal<Token extends ReadableToken<any>> = {
768
+ type: `state_disposal`;
769
+ subType: `atom`;
770
+ token: Token;
771
+ value: TokenType<Token>;
772
+ };
773
+ type SelectorDisposal<Token extends ReadableToken<any>> = {
774
+ type: `state_disposal`;
775
+ subType: `selector`;
776
+ token: Token;
777
+ };
778
+ type MoleculeCreation = {
779
+ type: `molecule_creation`;
780
+ key: Canonical;
781
+ provenance: Canonical;
782
+ };
783
+ type MoleculeDisposal = {
784
+ type: `molecule_disposal`;
785
+ key: Canonical;
786
+ provenance: stringified<Canonical>[];
787
+ values: [key: string, value: any][];
788
+ };
789
+ type MoleculeTransfer = {
790
+ type: `molecule_transfer`;
791
+ key: Canonical;
792
+ from: Canonical[];
793
+ to: Canonical[];
794
+ };
795
+ type TransactionUpdateContent = KeyedStateUpdate<unknown> | MoleculeCreation | MoleculeDisposal | MoleculeTransfer | StateCreation<ReadableToken<unknown>> | StateDisposal<ReadableToken<unknown>> | TransactionUpdate<Func>;
796
+ type TransactionUpdate<F extends Func> = {
797
+ type: `transaction_update`;
798
+ key: string;
799
+ id: string;
800
+ epoch: number;
801
+ updates: TransactionUpdateContent[];
802
+ params: Parameters<F>;
803
+ output: ReturnType<F>;
804
+ };
805
+ type ReaderToolkit = Pick<ActorToolkit, `find` | `get` | `json`>;
806
+ type WriterToolkit = Pick<ActorToolkit, `find` | `get` | `json` | `set`>;
807
+ type ActorToolkit = Readonly<{
808
+ get: typeof getState;
809
+ set: typeof setState;
810
+ reset: typeof resetState;
811
+ find: typeof findState;
812
+ json: <T extends Transceiver<any>, J extends Json.Serializable>(state: MutableAtomToken<T, J>) => WritablePureSelectorToken<J>;
813
+ dispose: typeof disposeState;
814
+ run: typeof runTransaction;
815
+ env: () => EnvironmentData;
816
+ }>;
817
+ type Read<F extends Func> = (toolkit: ReaderToolkit, ...parameters: Parameters<F>) => ReturnType<F>;
818
+ type Write<F extends Func> = (toolkit: WriterToolkit, ...parameters: Parameters<F>) => ReturnType<F>;
819
+ type Transact<F extends Func> = (toolkit: ActorToolkit, ...parameters: Parameters<F>) => ReturnType<F>;
820
+ type TransactionIO<Token extends TransactionToken<any>> = Token extends TransactionToken<infer F> ? F : never;
821
+ type TransactionOptions<F extends Func> = {
822
+ /** The unique identifier of the transaction */
823
+ key: string;
824
+ /** The operation to perform */
825
+ do: Transact<F>;
826
+ };
827
+ /**
828
+ * Create a transaction, a mechanism for batching updates multiple states in a single, all-or-nothing operation
829
+ * @param options - {@link TransactionOptions}
830
+ * @returns A reference to the transaction created: a {@link TransactionToken}
831
+ */
832
+ declare function transaction<F extends Func>(options: TransactionOptions<F>): TransactionToken<F>;
833
+ /**
834
+ * Execute a {@link transaction}
835
+ * @param token - A {@link TransactionToken}
836
+ * @param id - A unique identifier for the transaction. If not provided, a random identifier will be generated
837
+ * @returns A function that can be called to run the transaction with its {@link TransactionIO} parameters
838
+ */
839
+ declare function runTransaction<F extends Func>(token: TransactionToken<F>, id?: string): (...parameters: Parameters<F>) => ReturnType<F>;
840
+ //#endregion
841
+ //#region src/main/selector.d.ts
842
+ type WritablePureSelectorOptions<T> = {
843
+ /** The unique identifier of the selector */
844
+ key: string;
845
+ /** For each instantiated selector, a function that computes its value */
846
+ get: Read<() => T>;
847
+ /** For each instantiated selector, a function that sets its value */
848
+ set: Write<(newValue: T) => void>;
849
+ };
850
+ type ReadonlyPureSelectorOptions<T> = {
851
+ /** The unique identifier of the selector */
852
+ key: string;
853
+ /** For each instantiated selector, a function that computes its value */
854
+ get: Read<() => T>;
855
+ };
856
+ type ReadonlyHeldSelectorOptions<T extends object> = {
857
+ /** The unique identifier of the selector */
858
+ key: string;
859
+ /** For each instantiated selector, a constant reference to a value that will not be replaced */
860
+ const: T;
861
+ /** For each instantiated selector, a function that computes its value */
862
+ get: Read<(permanent: T) => void>;
863
+ };
864
+ type WritableHeldSelectorOptions<T extends object> = {
865
+ /** The unique identifier of the selector */
866
+ key: string;
867
+ /** For each instantiated selector, a constant reference to a value that will not be replaced */
868
+ const: T;
869
+ /** For each instantiated selector, a function that computes its value */
870
+ get: Read<(permanent: T) => void>;
871
+ /** For each instantiated selector, a function that sets its value */
872
+ set: Write<(newValue: T) => void>;
873
+ };
874
+ /**
875
+ * Declare a selector. The value of a selector should depend
876
+ * on the value of atoms or other selectors in the store, and
877
+ * should be recycled when a root atom of the selector is set.
878
+ *
879
+ * A held selector's value must be some object.
880
+ * The reference to that object is permanent and will not be replaced.
881
+ *
882
+ * A writable selector can be "set" to a new value.
883
+ * It is strongly advised to set its dependencies to values
884
+ * that would produce the new value of the selector.
885
+ *
886
+ * @param options - {@link WritableHeldSelectorOptions}.
887
+ * @returns
888
+ * The token for your selector.
889
+ * @overload WritableHeld
890
+ */
891
+ declare function selector<T extends object>(options: WritableHeldSelectorOptions<T>): WritableHeldSelectorToken<T>;
892
+ /**
893
+ * Declare a selector. The value of a selector should depend
894
+ * on the value of atoms or other selectors in the store,
895
+ * and should be recycled when a root atom of the selector is set.
896
+ *
897
+ * A held selector's value must be some object.
898
+ * The reference to that object is permanent and will not be replaced.
899
+ *
900
+ * A readonly selector can be "gotten" but not "set".
901
+ *
902
+ * @param options - {@link ReadonlyHeldSelectorOptions}.
903
+ * @returns
904
+ * The token for your selector.
905
+ * @overload ReadonlyHeld
906
+ */
907
+ declare function selector<T extends object>(options: ReadonlyHeldSelectorOptions<T>): ReadonlyHeldSelectorToken<T>;
908
+ /**
909
+ * Declare a selector. The value of a selector should depend
910
+ * on the value of atoms or other selectors in the store.
911
+ *
912
+ * A pure selector's current value is evicted from the store
913
+ * in order to be garbage collected when a root atom of the selector is set.
914
+ *
915
+ * A writable selector can be "set" to a new value.
916
+ * It is strongly advised to set its dependencies to values
917
+ * that would produce the new value of the selector.
918
+ *
919
+ * @param options - {@link TransientWritableSelectorOptions}.
920
+ * @returns
921
+ * The token for your selector.
922
+ * @overload WritablePure
923
+ */
924
+ declare function selector<T>(options: WritablePureSelectorOptions<T>): WritablePureSelectorToken<T>;
925
+ /**
926
+ * Declare a selector. The value of a selector should depend
927
+ * on the value of atoms or other selectors in the store.
928
+ *
929
+ * A pure selector's current value is evicted from the store
930
+ * in order to be garbage collected when a root atom of the selector is set.
931
+ *
932
+ * A readonly selector can be "gotten" but not "set".
933
+ *
934
+ * @param options - {@link ReadonlyPureSelectorOptions}.
935
+ * @returns
936
+ * The token for your selector.
937
+ * @overload ReadonlyPure
938
+ */
939
+ declare function selector<T>(options: ReadonlyPureSelectorOptions<T>): ReadonlyPureSelectorToken<T>;
940
+ type WritablePureSelectorFamilyOptions<T, K extends Canonical> = {
941
+ /** The unique identifier of the family */
942
+ key: string;
943
+ /** For each instantiated family member, a function that computes its value */
944
+ get: (key: K) => Read<() => T>;
945
+ /** For each instantiated family member, a function that sets its value */
946
+ set: (key: K) => Write<(newValue: T) => void>;
947
+ };
948
+ type ReadonlyPureSelectorFamilyOptions<T, K extends Canonical> = {
949
+ /** The unique identifier of the family */
950
+ key: string;
951
+ /** For each instantiated family member, a function that computes its value */
952
+ get: (key: K) => Read<() => T>;
953
+ };
954
+ type WritableHeldSelectorFamilyOptions<T extends object, K extends Canonical> = {
955
+ /** The unique identifier of the family */
956
+ key: string;
957
+ /** For each instantiated family member, a constant reference to a value that will not be replaced */
958
+ const: (key: K) => T;
959
+ /** For each instantiated family member, a function that computes its value */
960
+ get: (key: K) => Read<(permanent: T) => void>;
961
+ /** For each instantiated family member, a function that sets its value */
962
+ set: (key: K) => Write<(newValue: T) => void>;
963
+ };
964
+ type ReadonlyHeldSelectorFamilyOptions<T extends object, K extends Canonical> = {
965
+ /** The unique identifier of the family */
966
+ key: string;
967
+ /** For each instantiated family member, a constant reference to a value that will not be replaced */
968
+ const: (key: K) => T;
969
+ /** For each instantiated family member, a function that computes its value */
970
+ get: (key: K) => Read<(permanent: T) => void>;
971
+ };
968
972
  /**
969
- * @public
970
- * A function that sets the value of a state.
971
- * @param oldValue - The current value of the state.
973
+ * Create a family of selectors, allowing for the dynamic creation and disposal of selectors.
974
+ *
975
+ * The value of a held selector should depend on the value of atoms or other selectors in the store,
976
+ * and should be recycled when a root atom of the selector is set.
977
+ *
978
+ * A held selector's value must be some object.
979
+ * The reference to that object is permanent and will not be replaced.
980
+ *
981
+ * A writable selector can be "set" to a new value.
982
+ * It is advised to set its dependencies to values
983
+ * that would produce the new value of the selector.
984
+ *
985
+ * @param options - {@link WritableHeldSelectorFamilyOptions}.
972
986
  * @returns
973
- * The new value of the state.
987
+ * A reference to the selector family created: a {@link WritableHeldSelectorFamilyToken}
988
+ * @overload WritableHeld
974
989
  */
975
- type Setter<T, New extends T> = (oldValue: T) => New;
990
+ declare function selectorFamily<T extends object, K extends Canonical>(options: WritableHeldSelectorFamilyOptions<T, K>): WritableHeldSelectorFamilyToken<T, K>;
976
991
  /**
977
- * @public
978
- * Set the value of a state into the implicit store.
979
- * @param token - An atom or writable selector token.
980
- * @param value - The new value of the state.
981
- * @overload Default
982
- * @default
992
+ * Create a family of selectors, allowing for the dynamic creation and disposal of selectors.
993
+ *
994
+ * The value of a held selector should depend on the value of atoms or other selectors in the store,
995
+ * and should be recycled when a root atom of the selector is set.
996
+ *
997
+ * A held selector's value must be some object.
998
+ * The reference to that object is permanent and will not be replaced.
999
+ *
1000
+ * A readonly selector can be "gotten" but not "set".
1001
+ *
1002
+ * @param options - {@link ReadonlyHeldSelectorFamilyOptions}.
1003
+ * @returns
1004
+ * A reference to the selector family created: a {@link ReadonlyHeldSelectorFamilyToken}
1005
+ * @overload ReadonlyHeld
983
1006
  */
984
- declare function setState<T, New extends T>(token: WritableToken<T>, value: New | Setter<T, New>): void;
1007
+ declare function selectorFamily<T extends object, K extends Canonical>(options: ReadonlyHeldSelectorFamilyOptions<T, K>): ReadonlyHeldSelectorFamilyToken<T, K>;
985
1008
  /**
986
- * @public
987
- * Set the value of a state into the implicit store.
988
- * @param token - An atom family or writable selector family token.
989
- * @param key - The unique key of the state to set.
990
- * @param value - The new value of the state.
991
- * @overload Streamlined
1009
+ * Create a family of selectors, allowing for the dynamic creation and disposal of selectors.
1010
+ *
1011
+ * The value of a selector should depend on the value of atoms or other selectors in the store.
1012
+ *
1013
+ * A pure selector's current value is evicted from the store
1014
+ * in order to be garbage collected when a root atom of the selector is set.
1015
+ *
1016
+ * A writable selector can be "set" to a new value.
1017
+ * It is advised to set its dependencies to values
1018
+ * that would produce the new value of the selector.
1019
+ *
1020
+ * @param options - {@link TransientWritableSelectorFamilyOptions}.
1021
+ * @returns
1022
+ * A reference to the selector family created: a {@link TransientWritableSelectorFamilyToken}
1023
+ * @overload WritablePure
992
1024
  */
993
- declare function setState<T, K extends Canonical, New extends T, Key extends K>(token: WritableFamilyToken<T, K>, key: Key, value: New | Setter<T, New>): void;
1025
+ declare function selectorFamily<T, K extends Canonical>(options: WritablePureSelectorFamilyOptions<T, K>): WritablePureSelectorFamilyToken<T, K>;
1026
+ /**
1027
+ * Create a family of selectors, allowing for the dynamic creation and disposal of selectors.
1028
+ *
1029
+ * The value of a selector should depend on the value of atoms or other selectors in the store.
1030
+ *
1031
+ * A pure selector's current value is evicted from the store
1032
+ * in order to be garbage collected when a root atom of the selector is set.
1033
+ *
1034
+ * A readonly selector can be "gotten" but not "set".
1035
+ *
1036
+ * @param options - {@link ReadonlyPureSelectorFamilyOptions}.
1037
+ * @returns
1038
+ * A reference to the selector family created: a {@link ReadonlyPureSelectorFamilyToken}
1039
+ * @overload ReadonlyPure
1040
+ */
1041
+ declare function selectorFamily<T, K extends Canonical>(options: ReadonlyPureSelectorFamilyOptions<T, K>): ReadonlyPureSelectorFamilyToken<T, K>;
994
1042
  //#endregion
995
1043
  //#region src/main/silo.d.ts
996
1044
  declare class Silo {
997
1045
  store: Store;
998
1046
  atom: typeof atom;
1047
+ mutableAtom: typeof mutableAtom;
999
1048
  atomFamily: typeof atomFamily;
1049
+ mutableAtomFamily: typeof mutableAtomFamily;
1000
1050
  selector: typeof selector;
1001
1051
  selectorFamily: typeof selectorFamily;
1002
1052
  transaction: typeof transaction;
@@ -1014,194 +1064,37 @@ declare class Silo {
1014
1064
  constructor(config: Store[`config`], fromStore?: Store | null);
1015
1065
  }
1016
1066
  //#endregion
1017
- //#region src/main/subscribe.d.ts
1018
- /** @public */
1019
- type StateUpdate<T> = {
1020
- newValue: T;
1021
- oldValue: T;
1022
- };
1023
- /** @public */
1024
- type KeyedStateUpdate<T> = Flat<StateUpdate<T> & {
1025
- key: string;
1026
- type: `atom_update` | `selector_update`;
1027
- family?: FamilyMetadata;
1028
- }>;
1029
- /** @public */
1030
- type UpdateHandler<T> = (update: StateUpdate<T>) => void;
1031
- /** @public */
1032
- type TransactionUpdateHandler<F extends Func> = (data: TransactionUpdate<F>) => void;
1033
- /**
1034
- * @public
1035
- * Subscribe to a state in the implicit store
1036
- * @param token - The token of the state to subscribe to
1037
- * @param handleUpdate - A function that will be called when the state is updated
1038
- * @param key - A unique key for the subscription. If not provided, a random key will be generated.
1039
- * @returns A function that can be called to unsubscribe from the state
1040
- * @overload State
1041
- */
1042
- declare function subscribe<T>(token: ReadableToken<T>, handleUpdate: UpdateHandler<T>, key?: string): () => void;
1043
- /**
1044
- * @public
1045
- * Subscribe to a transaction in the implicit store
1046
- * @param token - The token of the transaction to subscribe to
1047
- * @param handleUpdate - A function that will be called when the transaction succeeds
1048
- * @param key - A unique key for the subscription. If not provided, a random key will be generated.
1049
- * @returns A function that can be called to unsubscribe from the transaction
1050
- * @overload Transaction
1051
- */
1052
- declare function subscribe<F extends Func>(token: TransactionToken<F>, handleUpdate: TransactionUpdateHandler<F>, key?: string): () => void;
1067
+ //#region src/main/timeline.d.ts
1068
+ type TimelineManageable = AtomFamilyToken<any, any> | AtomToken<any>;
1069
+ type AtomOnly<M extends TimelineManageable> = M extends AtomFamilyToken<any, any> ? AtomToken<any> : M extends AtomToken<any> ? M : never;
1053
1070
  /**
1054
- * @public
1055
- * Subscribe to a timeline in the implicit store
1056
- * @param token - The token of the timeline to subscribe to
1057
- * @param handleUpdate - A function that will be called when a new update is available
1058
- * @param key - A unique key for the subscription. If not provided, a random key will be generated.
1059
- * @returns A function that can be called to unsubscribe from the timeline
1060
- * @overload Timeline
1071
+ * If there is an update ahead of the cursor (in the future of this {@link timeline}), apply it and move the cursor to the next update
1072
+ * @param timeline - A {@link TimelineToken}
1061
1073
  */
1062
- declare function subscribe<M extends TimelineManageable>(token: TimelineToken<M>, handleUpdate: (update: TimelineUpdate<M> | `redo` | `undo`) => void, key?: string): () => void;
1063
- //#endregion
1064
- //#region src/main/validators.d.ts
1065
- type TokenType<Comparison extends ReadableFamilyToken$1<any, any> | ReadableToken$1<any>> = Comparison extends ReadableToken$1<infer RepresentedValue> ? RepresentedValue : Comparison extends ReadableFamilyToken$1<infer RepresentedValue, any> ? RepresentedValue : never;
1066
- declare function isToken<KnownToken extends RegularAtomToken$1<any>>(knownToken: KnownToken, unknownToken: ReadableToken$1<any>): unknownToken is RegularAtomToken$1<TokenType<KnownToken>>;
1067
- declare function isToken<KnownToken extends MutableAtomToken$1<any, any>>(knownToken: KnownToken, unknownToken: ReadableToken$1<any>): unknownToken is MutableAtomToken$1<TokenType<KnownToken>, any>;
1068
- declare function isToken<KnownToken extends WritablePureSelectorToken$1<any>>(knownToken: KnownToken, unknownToken: ReadableToken$1<any>): unknownToken is WritablePureSelectorToken$1<TokenType<KnownToken>>;
1069
- declare function isToken<KnownToken extends ReadonlyPureSelectorToken$1<any>>(knownToken: KnownToken, unknownToken: ReadableToken$1<any>): unknownToken is ReadonlyPureSelectorToken$1<TokenType<KnownToken>>;
1070
- declare function isToken<KnownToken extends WritableToken$1<any>>(knownToken: KnownToken, unknownToken: ReadableToken$1<any>): unknownToken is WritableToken$1<TokenType<KnownToken>>;
1071
- declare function isToken<KnownToken extends ReadableToken$1<any>>(knownToken: KnownToken, unknownToken: ReadableToken$1<any>): unknownToken is ReadableToken$1<TokenType<KnownToken>>;
1072
- declare function belongsTo<Family extends RegularAtomFamilyToken$1<any, any>>(family: Family, unknownToken: ReadableToken$1<any>): unknownToken is RegularAtomToken$1<TokenType<Family>>;
1073
- declare function belongsTo<Family extends MutableAtomFamilyToken$1<any, any, any>>(family: Family, unknownToken: ReadableToken$1<any>): unknownToken is MutableAtomToken$1<TokenType<Family>, any>;
1074
- declare function belongsTo<Family extends WritablePureSelectorFamilyToken$1<any, any>>(family: Family, unknownToken: ReadableToken$1<any>): unknownToken is WritablePureSelectorToken$1<TokenType<Family>>;
1075
- declare function belongsTo<Family extends ReadonlyPureSelectorFamilyToken$1<any, any>>(family: Family, unknownToken: ReadableToken$1<any>): unknownToken is ReadonlyPureSelectorToken$1<TokenType<Family>>;
1076
- declare function belongsTo<Family extends WritableFamilyToken$1<any, any>>(family: Family, unknownToken: ReadableToken$1<any>): unknownToken is WritableToken$1<TokenType<Family>>;
1077
- declare function belongsTo<Family extends ReadableFamilyToken$1<any, any>>(family: Family, unknownToken: ReadableToken$1<any>): unknownToken is ReadableToken$1<TokenType<Family>>;
1078
- //#endregion
1079
- //#region src/main/index.d.ts
1074
+ declare const redo: (timeline: TimelineToken<any>) => void;
1080
1075
  /**
1081
- * @public
1082
- * A token is an object that uniquely identifies a particular state, family, timeline, or transaction.
1083
- *
1084
- * While they represent one of these resources, they are not the resource itself. Think of them like paper currency representing money in the bank.
1085
- *
1086
- * Tokens are returned from resource creation functions, such as {@link atom} and {@link transaction}.
1087
- *
1088
- * Tokens can be used as parameters to functions that take a token, such as {@link getState}, {@link setState}, or {@link runTransaction}.
1089
- *
1090
- * Tokens are fully serializable, so they can be passed between processes.
1076
+ * Reverse the last update on the {@link timeline} and move the cursor to the previous update
1077
+ * @param timeline - A {@link TimelineToken}
1091
1078
  */
1092
- type AtomIOToken = ReadableFamilyToken<any, any> | ReadableToken<any> | TimelineToken<any> | TransactionToken<any>;
1093
- /** @public */
1094
- type RegularAtomToken<T, K extends Canonical = any> = {
1095
- /** The unique identifier of the atom. */
1096
- key: string;
1097
- /** Discriminator. */
1098
- type: `atom`;
1099
- /** Present if the atom belongs to a family. */
1100
- family?: FamilyMetadata<K>;
1101
- /** Never present. This is a marker that preserves the type of the atom's value. */
1102
- __T?: T;
1103
- };
1104
- /** @public */
1105
- type MutableAtomToken<T extends Transceiver<any>, J extends Json.Serializable, K extends Canonical = any> = {
1106
- /** The unique identifier of the atom. */
1107
- key: string;
1108
- /** Discriminator. */
1109
- type: `mutable_atom`;
1110
- /** Present if the atom belongs to a family. */
1111
- family?: FamilyMetadata<K>;
1112
- /** Never present. This is a marker that preserves the JSON form of the atom's transceiver value. */
1113
- __J?: J;
1114
- /** Never present. This is a marker that preserves the type of the atom's transceiver value. */
1115
- __U?: T extends Transceiver<infer Update> ? Update : never;
1116
- };
1117
- /** @public */
1118
- type AtomToken<T, K extends Canonical = any> = MutableAtomToken<T extends Transceiver<any> ? T : never, any, K> | RegularAtomToken<T, K>;
1119
- /** @public */
1120
- type WritablePureSelectorToken<T, K extends Canonical = any> = {
1121
- /** The unique identifier of the selector. */
1122
- key: string;
1123
- /** Discriminator. */
1124
- type: `writable_pure_selector`;
1125
- /** Present if the selector belongs to a family. */
1126
- family?: FamilyMetadata<K>;
1127
- /** Never present. This is a marker that preserves the type of the selector's value. */
1128
- __T?: T;
1129
- };
1130
- /** @public */
1131
- type WritableHeldSelectorToken<T, K extends Canonical = any> = {
1132
- /** The unique identifier of the selector. */
1133
- key: string;
1134
- /** Discriminator. */
1135
- type: `writable_held_selector`;
1136
- /** Present if the selector belongs to a family. */
1137
- family?: FamilyMetadata<K>;
1138
- /** Never present. This is a marker that preserves the type of the selector's value. */
1139
- __T?: T;
1140
- };
1141
- /** @public */
1142
- type ReadonlyPureSelectorToken<T, K extends Canonical = any> = {
1143
- /** The unique identifier of the selector. */
1144
- key: string;
1145
- /** Discriminator. */
1146
- type: `readonly_pure_selector`;
1147
- /** Present if the selector belongs to a family. */
1148
- family?: FamilyMetadata<K>;
1149
- /** Never present. This is a marker that preserves the type of the selector's value. */
1150
- __T?: T;
1151
- };
1152
- /** @public */
1153
- type ReadonlyHeldSelectorToken<T, K extends Canonical = any> = {
1154
- /** The unique identifier of the selector. */
1079
+ declare const undo: (timeline: TimelineToken<any>) => void;
1080
+ type TimelineUpdate<ManagedAtom extends TimelineManageable> = TimelineAtomUpdate<ManagedAtom> | TimelineMoleculeCreation | TimelineMoleculeDisposal | TimelineSelectorUpdate<ManagedAtom> | TimelineStateCreation<AtomOnly<ManagedAtom>> | TimelineStateDisposal<AtomOnly<ManagedAtom>> | TimelineTransactionUpdate;
1081
+ type TimelineOptions<ManagedAtom extends TimelineManageable> = {
1082
+ /** The unique identifier of the timeline */
1155
1083
  key: string;
1156
- /** Discriminator. */
1157
- type: `readonly_held_selector`;
1158
- /** Present if the selector belongs to a family. */
1159
- family?: FamilyMetadata<K>;
1160
- /** Never present. This is a marker that preserves the type of the selector's value. */
1161
- __T?: T;
1084
+ /** The managed atoms (and families of atoms) to record */
1085
+ scope: ManagedAtom[];
1086
+ /** A function that determines whether a given update should be recorded */
1087
+ shouldCapture?: (update: TimelineUpdate<ManagedAtom>, timeline: Timeline<TimelineManageable>) => boolean;
1162
1088
  };
1163
- /** @public */
1164
- type PureSelectorToken<T, K extends Canonical = any> = ReadonlyPureSelectorToken<T, K> | WritablePureSelectorToken<T, K>;
1165
- /** @public */
1166
- type HeldSelectorToken<T, K extends Canonical = any> = ReadonlyHeldSelectorToken<T, K> | WritableHeldSelectorToken<T, K>;
1167
- /** @public */
1168
- type ReadonlySelectorToken<T, K extends Canonical = any> = ReadonlyHeldSelectorToken<T, K> | ReadonlyPureSelectorToken<T, K>;
1169
- /** @public */
1170
- type WritableSelectorToken<T, K extends Canonical = any> = WritableHeldSelectorToken<T, K> | WritablePureSelectorToken<T, K>;
1171
- /** @public */
1172
- type SelectorToken<T, K extends Canonical = any> = ReadonlyHeldSelectorToken<T, K> | ReadonlyPureSelectorToken<T, K> | WritableHeldSelectorToken<T, K> | WritablePureSelectorToken<T, K>;
1173
- /**
1174
- * @public
1175
- * These states can be set.
1176
- */
1177
- type WritableToken<T, K extends Canonical = any> = AtomToken<T, K> | WritableSelectorToken<T, K>;
1178
- /**
1179
- * @public
1180
- * These states cannot be set.
1181
- */
1182
- type ReadableToken<T, K extends Canonical = any> = AtomToken<T, K> | SelectorToken<T, K>;
1183
- /**
1184
- * @public
1185
- * States belonging to this family can be set.
1186
- */
1187
- type WritableFamilyToken<T, K extends Canonical> = AtomFamilyToken<T, K> | WritableSelectorFamilyToken<T, K>;
1188
1089
  /**
1189
- * @public
1190
- * States belonging to this family cannot be set.
1191
- */
1192
- type ReadableFamilyToken<T, K extends Canonical> = AtomFamilyToken<T, K> | SelectorFamilyToken<T, K>;
1193
- /**
1194
- * @public
1195
- * Identifies a state's connection to its family.
1090
+ * Create a timeline, a mechanism for recording, undoing, and replaying changes to groups of atoms
1091
+ * @param options - {@link TimelineOptions}
1092
+ * @returns A reference to the timeline created: a {@link TimelineToken}
1196
1093
  */
1197
- type FamilyMetadata<K extends Canonical = any> = {
1198
- /** The family's unique key. */
1199
- key: string;
1200
- /** The family member's unique identifier, in the form of a string. */
1201
- subKey: stringified<K>;
1202
- };
1094
+ declare const timeline: <ManagedAtom extends TimelineManageable>(options: TimelineOptions<ManagedAtom>) => TimelineToken<ManagedAtom>;
1095
+ //#endregion
1096
+ //#region src/main/index.d.ts
1203
1097
  /**
1204
- * @public
1205
1098
  * Loadable is used to type atoms or selectors that may at some point be initialized to or set to a {@link Promise}.
1206
1099
  *
1207
1100
  * When a Promise is cached as the value of a state in atom.io, that state will be automatically set to the resolved value of the Promise when it is resolved.
@@ -1210,5 +1103,5 @@ type FamilyMetadata<K extends Canonical = any> = {
1210
1103
  */
1211
1104
  type Loadable<T> = Promise<T> | T;
1212
1105
  //#endregion
1213
- export { $claim, Above, ActorToolkit, Anarchy, AtomDisposal, AtomEffect, AtomFamilyToken, AtomIOLogger, AtomIOToken, AtomOnly, AtomToken, Below, Claim, CompoundFrom, CompoundTypedKey, Effectors, FamilyMetadata, GetterToolkit, HeldSelectorFamilyToken, HeldSelectorToken, Hierarchy, JoinOptions, JoinStates, JoinToken, KeyedStateUpdate, LOG_LEVELS, Loadable, LogFilter, LogFn, LogLevel, Logger, LoggerIcon, MoleculeCreation, MoleculeDisposal, MoleculeTransfer, MutableAtomFamilyOptions, MutableAtomFamilyToken, MutableAtomOptions, MutableAtomToken, Mutuals, PureSelectorFamilyToken, PureSelectorToken, Read, ReadableFamilyToken, ReadableToken, ReadonlyHeldSelectorFamilyOptions, ReadonlyHeldSelectorFamilyToken, ReadonlyHeldSelectorOptions, ReadonlyHeldSelectorToken, ReadonlyPureSelectorFamilyOptions, ReadonlyPureSelectorFamilyToken, ReadonlyPureSelectorOptions, ReadonlyPureSelectorToken, ReadonlySelectorFamilyToken, ReadonlySelectorToken, Realm, RegularAtomFamilyOptions, RegularAtomFamilyToken, RegularAtomOptions, RegularAtomToken, SelectorDisposal, SelectorFamilyToken, SelectorToken, Setter, SetterToolkit, Silo, SingularTypedKey, StateCreation, StateDisposal, StateUpdate, T$, TimelineManageable, TimelineOptions, TimelineToken, TimelineUpdate, TokenDenomination, TokenType, Transact, TransactionIO, TransactionOptions, TransactionToken, TransactionUpdate, TransactionUpdateContent, TransactionUpdateHandler, TypeTag, TypedKey, UpdateHandler, Vassal, WritableFamilyToken, WritableHeldSelectorFamilyOptions, WritableHeldSelectorFamilyToken, WritableHeldSelectorOptions, WritableHeldSelectorToken, WritablePureSelectorFamilyOptions, WritablePureSelectorFamilyToken, WritablePureSelectorOptions, WritablePureSelectorToken, WritableSelectorFamilyToken, WritableSelectorToken, WritableToken, Write, atom, atomFamily, belongsTo, disposeState, editRelations, findRelations, findState, getInternalRelations, getState, isToken, join, redo, resetState, runTransaction, selector, selectorFamily, setState, simpleLog, simpleLogger, subscribe, timeline, transaction, undo };
1106
+ export { $claim, Above, ActorToolkit, Anarchy, AtomDisposal, AtomEffect, AtomFamilyToken, AtomIOLogger, AtomIOToken, AtomOnly, AtomToken, Below, Claim, CompoundFrom, CompoundTypedKey, Effectors, FamilyMetadata, HeldSelectorFamilyToken, HeldSelectorToken, Hierarchy, JoinOptions, JoinStates, JoinToken, KeyedStateUpdate, LOG_LEVELS, Loadable, LogFilter, LogFn, LogLevel, Logger, LoggerIcon, MoleculeCreation, MoleculeDisposal, MoleculeTransfer, MutableAtomFamilyOptions, MutableAtomFamilyToken, MutableAtomOptions, MutableAtomToken, Mutuals, PureSelectorFamilyToken, PureSelectorToken, Read, ReadableFamilyToken, ReadableToken, ReaderToolkit, ReadonlyHeldSelectorFamilyOptions, ReadonlyHeldSelectorFamilyToken, ReadonlyHeldSelectorOptions, ReadonlyHeldSelectorToken, ReadonlyPureSelectorFamilyOptions, ReadonlyPureSelectorFamilyToken, ReadonlyPureSelectorOptions, ReadonlyPureSelectorToken, ReadonlySelectorFamilyToken, ReadonlySelectorToken, Realm, RegularAtomFamilyOptions, RegularAtomFamilyToken, RegularAtomOptions, RegularAtomToken, SelectorDisposal, SelectorFamilyToken, SelectorToken, Setter, Silo, SingularTypedKey, StateCreation, StateDisposal, StateUpdate, T$, TimelineManageable, TimelineOptions, TimelineToken, TimelineUpdate, TokenDenomination, TokenType, Transact, TransactionIO, TransactionOptions, TransactionToken, TransactionUpdate, TransactionUpdateContent, TransactionUpdateHandler, TypeTag, TypedKey, UpdateHandler, Vassal, WritableFamilyToken, WritableHeldSelectorFamilyOptions, WritableHeldSelectorFamilyToken, WritableHeldSelectorOptions, WritableHeldSelectorToken, WritablePureSelectorFamilyOptions, WritablePureSelectorFamilyToken, WritablePureSelectorOptions, WritablePureSelectorToken, WritableSelectorFamilyToken, WritableSelectorToken, WritableToken, Write, WriterToolkit, atom, atomFamily, belongsTo, disposeState, editRelations, findRelations, findState, getInternalRelations, getState, isToken, join, mutableAtom, mutableAtomFamily, redo, resetState, runTransaction, selector, selectorFamily, setState, simpleLog, simpleLogger, subscribe, timeline, transaction, undo };
1214
1107
  //# sourceMappingURL=index.d.ts.map