@exodus/atoms 9.0.0 → 9.0.2

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [9.0.2](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/atoms@9.0.1...@exodus/atoms@9.0.2) (2025-03-19)
+
+**Note:** Version bump only for package @exodus/atoms
+
+## [9.0.1](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/atoms@9.0.0...@exodus/atoms@9.0.1) (2025-01-31)
+
+### Bug Fixes
+
+- fix: reset call state after atom reset (#11306)
+
+### Performance
+
+- perf(atoms): memoize compute enhancer selectors (#10771)
+
 ## [9.0.0](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/atoms@8.1.1...@exodus/atoms@9.0.0) (2024-09-26)
 
 ### ⚠ BREAKING CHANGES

package/README.md

@@ -11,30 +11,47 @@
 An atom is a data source wrapper that exposes a single piece of data through 3 different methods:
 
 - **get()**: read data
-- **set(newValue)**: write data
+- **set(newValue)**: sets the atoms value, blocking until all observers have resolved.
 - **observe(async (data) => {})**: observes data changes. Will be called initially with current data value. Observers are awaited in series.
 - **reset()**: clear the stored value. The next `get()` call will return the default value\* and observers will be called with the default value.
 
 ## Data sources
 
-This library provides helpers for creating atoms from multiple data sources we use in our apps
+This library provides helpers for creating atoms from multiple data sources we use in our apps.
 
-|               | get   | set     | observe |
-| ------------- | ----- | ------- | ------- |
-| Memory        | ✅ \* | ✅      | ✅      |
-| Storage       | ✅    | 🟡 \*\* | ✅      |
-| Remote config | ✅    | ❌      | ✅      |
-| Local config  | ✅    | ✅      | ✅      |
-| Event emitter | ✅    | ❌      | ✅      |
+|               | get | set   | observe |
+| ------------- | --- | ----- | ------- |
+| Memory        | ✅  | ✅    | ✅      |
+| Storage       | ✅  | ✅    | ✅      |
+| Keystore      | ✅  | 🟡 \* | ✅      |
+| Event emitter | ✅  | ❌    | ✅      |
 
-\* If no `defaultValue` is provided, a memory atom's `get()` method will hang and observers will NOT be called until the first `set()` call.
+\* A keystore atom needs a special `isSoleWriter` param to allow write access.
 
-\*\* A storage atom needs a special `isSoleWriter` param to allow write access. This is because storage instances can overlap, e.g. a parent namespace can mutate a child namespace, and our [storage-spec](https://github.com/ExodusMovement/exodus-hydra/tree/master/modules/storage-spec) doesn't currently provide for detecting changes across those instances.
+See also:
+
+- [@exodus/remote-config-atoms](../remote-config-atoms)
+- [@exodus/fusion-atoms](../fusion-atoms)
+
+Note: this library originally hosted a bunch of media-specific factories, which have since been moved out, like the two above. The above will likely follow suit, and this library will only implement the common media-agnostic atom behaviors.
+
+## Troubleshooting
+
+Theoretically all atoms should behave similarly. In practice, there are a few currently inconsistent behaviors, which we aim to fix in the future, particularly around memory atoms and atoms created from an event emitter:
+
+- Memory atoms hang on `get()` if no `defaultValue` is provided.
+- Memory and Event Emitter atom observers are non-blocking, i.e. `memoryAtom.set()` is fire-and-forget
 
 ## Usage
 
 ```js
-import { createInMemoryAtom, createStorageAtomFactory, fromEventEmitter } from '@exodus/atoms'
+import { EventEmitter } from 'events'
+import {
+  createInMemoryAtom,
+  createStorageAtomFactory,
+  fromEventEmitter,
+  createKeystoreAtom,
+} from '@exodus/atoms'
 
 // In memory atoms
 const availableAssetNamesAtom = createInMemoryAtom({
@@ -51,19 +68,145 @@ const acceptedTermsAtom = storageAtomFactory({
 })
 
 // Event emitter
+const geolocation = new EventEmitter()
 const geolocationAtom = fromEventEmitter({
   emitter: geolocation,
   event: 'geolocation',
-  get: geolocation.get,
+  get: async () =>
+    new Promise((resolve, reject) => navigator.geolocation.getCurrentPosition(resolve, reject)),
+})
+
+navigator.geolocation.watchPosition((position) => {
+  geolocation.emit('geolocation', position)
+})
+
+// keystore
+const keystoreAtom = createKeystoreAtom({
+  keystore, // see @exodus/keystore-mobile
+  config: {
+    key: 'my-secret',
+    defaultValue, // optional
+    isSoleWriter, // if you plan to call set() on this atom instance
+  },
+})
+```
+
+## Enhancers
+
+To compute derived values, combine multiple atoms into, and perform other useful derivations, there are a bunch of enhancers available. Below is a non-exhaustive list, so check out [./src/enhancers](https://github.com/ExodusOSS/hydra/tree/master/libraries/atoms/src/enhancers) for more.
+
+### compute({ atom, selector }): ReadonlyAtom
+
+Computes an atom from another by applying a selector function to the observed data source.
+
+Example:
+
+```js
+import { createInMemoryAtom, compute } from '@exodus/atoms'
+
+const yearAtom = createInMemoryAtom({ defaultValue: 2025 })
+
+const isDoorsOfStoneOutYetAtom = compute({
+  atom: yearAtom,
+  selector: (year) => year > 2040,
+})
+
+isDoorsOfStoneOutYetAtom.observe(console.log) // false
+```
+
+### combine({ [key]: Atom }): ReadonlyAtom
+
+Combines multiple atoms into one:
+
+- `combinedAtom.observe`: fires for the first time when all atoms have emitted a value.
+- `combinedAtom.get`: resolves to an object with the values of all atoms as keyed in the input.
+
+Example:
+
+```js
+import { createInMemoryAtom, combine } from '@exodus/atoms'
+
+const nameAtom = createInMemoryAtom()
+const ageAtom = createInMemoryAtom()
+const userAtom = combine({
+  name: nameAtom,
+  age: ageAtom,
 })
+
+userAtom.observe(console.log) // hangs until both name and age are set
+nameAtom.set('Voldemort')
+ageAtom.set(25)
+// userAtom atom fires with { name: 'Voldemort', age: 25 }
 ```
 
-## Helper functions
+### dedupe(atom)
 
-### compute({ atom, selector })
+By default, atoms perform a shallow equality check to determine if a newly written value differs from the current one, and avoid notifying observers if it doesn't. If you want a deep equality check, use `dedupe`. (Even better, don't write deeply equal objects to that atom in the first place, and don't use `dedupe`!)
+
+Example:
+
+```js
+import { createInMemoryAtom, dedupe } from '@exodus/atoms'
 
-Computes an atom from another by applying a selector function to the observed data source. Returned atom is read-only, i.e. **set** will fail.
+const userAtom = createInMemoryAtom({ defaultValue: { name: 'Voldemort', age: 25 } })
+const dedupedUserAtom = dedupe(userAtom)
+userAtom.set({ name: 'Voldemort', age: 25 }) // `userAtom` observers are notified
+dedupedUserAtom.set({ name: 'Voldemort', age: 25 }) // `dedupedUserAtom` observers are NOT notified
+```
 
 ### withSerialization({ atom, serialize, deserialize })
 
-Computes an atom from another by serializing it's data after reading it and deserializing it before writing it.
+If you're storing data in an atom that needs to (de)serialize it, e.g. a storage atom, and the data doesn't survive a roundtrip through JSON.stringify / JSON.parse, use `withSerialization` to provide custom serialization.
+
+Example:
+
+```js
+import BJSON from 'buffer-json'
+import { createInMemoryAtom, withSerialization } from '@exodus/atoms'
+
+const rawPublicKeysAtom = createInMemoryAtom()
+const publicKeysAtom = withSerialization({
+  atom: rawPublicKeysAtom,
+  serialize: BJSON.stringify,
+  deserialize: BJSON.parse,
+})
+
+publicKeysAtom.set({
+  bitcoin: Buffer.from([...]),
+  ethereum: Buffer.from([...]),
+})
+```
+
+### difference(atom)
+
+If you want to get both the current and previous value emitted by an atom, use `difference`.
+
+Example:
+
+```js
+import { createInMemoryAtom, difference } from '@exodus/atoms'
+
+const nameAtom = createInMemoryAtom({ defaultValue: 'Tom' })
+const nameChangeAtom = difference(nameAtom)
+nameChangeAtom.observe(console.log)
+nameAtom.set('Voldemort')
+// nameChangeAtom emits
+// { previous: 'Tom', current: 'Voldemort' }
+```
+
+### filter(atom, predicate)
+
+If you're only interested in a subset of values an atom emits, use `filter`:
+
+Example:
+
+```js
+import { createInMemoryAtom, filter } from '@exodus/atoms'
+
+const nameAtom = createInMemoryAtom({ defaultValue: 'Tom' })
+const unusualNameAtom = filter(nameAtom, (name) => !['Tom', 'Dick', 'Harry'].includes(name))
+unusualNameAtom.observe(console.log)
+nameAtom.set('Dick') // unusualNameAtom doesn't emit
+nameAtom.set('Harry') // unusualNameAtom doesn't emit
+nameAtom.set('Voldemort') // unusualNameAtom emits 'Voldemort'
+```

package/lib/effects/wait-until.js

@@ -16,7 +16,7 @@ const waitUntil = ({ atom, predicate, rejectAfter }) => {
             }, rejectAfter);
         }
     });
-    Object.defineProperty(promise, 'unobserve', {
+    void Object.defineProperty(promise, 'unobserve', {
         value: () => {
             unobserve();
             clearTimeout(timeout);

package/lib/enforce-rules.js

@@ -30,7 +30,7 @@ const enforceObservableRules = ({ defaultValue, makeGetNonConcurrent = false, ge
             called = true;
             return enqueue(() => listener(value));
         };
-        nonConcurrentGet().then((value) => {
+        void nonConcurrentGet().then((value) => {
             if (!subscribed)
                 return;
             if (!called) {
@@ -38,7 +38,7 @@ const enforceObservableRules = ({ defaultValue, makeGetNonConcurrent = false, ge
                 publishSerially(postProcessValue(value));
             }
         });
-        const unsubscribe = atom.observe((value) => {
+        const subscriber = (value) => {
             if (valueEmittedFromGet !== undefined) {
                 const isAlreadyEmitted = value === valueEmittedFromGet;
                 valueEmittedFromGet = undefined;
@@ -47,7 +47,11 @@ const enforceObservableRules = ({ defaultValue, makeGetNonConcurrent = false, ge
                 }
             }
             return publishSerially(postProcessValue(value));
+        };
+        Object.defineProperty(subscriber, 'resetCallState', {
+            value: () => (called = false),
         });
+        const unsubscribe = atom.observe(subscriber);
         return () => {
             unsubscribe();
             subscribed = false;

package/lib/enhancers/block-until.js

@@ -6,7 +6,7 @@ export default function blockUntil({ atom, unblock }) {
         observe: (listener) => {
             let isSubscribed = true;
             let unsubscribe = () => { };
-            unblock().then(() => {
+            void unblock().then(() => {
                 if (isSubscribed) {
                     unsubscribe = atom.observe(listener);
                 }

package/lib/enhancers/compute.js

@@ -1,7 +1,9 @@
+import { safeMemoize } from '../utils/memoize.js';
 const compute = ({ atom, selector }) => {
+    const memoizedSelector = safeMemoize((value) => selector(value));
     const get = async () => {
         const values = await atom.get();
-        return selector(values);
+        return memoizedSelector(values);
     };
     const set = async () => {
         throw new Error('selected atom does not support set');
@@ -10,7 +12,7 @@ const compute = ({ atom, selector }) => {
         let prev;
         let called;
         return atom.observe(async (values) => {
-            const selected = await selector(values);
+            const selected = await memoizedSelector(values);
             if (called && prev === selected)
                 return;
             called = true;

package/lib/factories/storage.js

@@ -3,7 +3,7 @@ import enforceObservableRules from '../enforce-rules.js';
 const createStorageAtomFactory = ({ storage }) => {
     function createStorageAtom({ key, defaultValue }) {
         let version = 0;
-        const { notify, observe } = createSimpleObserver({ enable: true });
+        const { notify, observe, listeners } = createSimpleObserver({ enable: true });
         let canUseCached = false;
         let cached;
         let pendingWrite;
@@ -23,6 +23,9 @@ const createStorageAtomFactory = ({ storage }) => {
             })();
             await pendingWrite;
             await notify(value);
+            if (!canUseCached && listeners.length > 0) {
+                listeners.forEach((listener) => listener.resetCallState());
+            }
         };
         const get = async () => {
             if (pendingWrite) {

package/lib/index.d.ts

@@ -22,4 +22,4 @@ export { default as withStorageCache } from './enhancers/with-storage-cache.js';
 export { default as waitUntil } from './effects/wait-until.js';
 export { default as enforceObservableRules } from './enforce-rules.js';
 export { default as fromEventEmitter } from './event-emitter.js';
-export type { Atom, ReadonlyAtom, Listener, Unsubscribe } from './utils/types.js';
+export type * from './utils/types.js';

package/lib/simple-observer.d.ts

@@ -2,6 +2,7 @@ import type { Listener } from './utils/types.js';
 declare const createSimpleObserver: <T>({ enable }?: {
     enable?: boolean | undefined;
 }) => {
+    listeners: Listener<T>[];
     observe: (listener: Listener<T>) => () => void;
     notify: (value: T) => Promise<void[]>;
 };

package/lib/simple-observer.js

@@ -11,6 +11,7 @@ const createSimpleObserver = ({ enable = true } = {}) => {
         };
     };
     return {
+        listeners,
         observe,
         notify,
     };

package/lib/utils/memoize.d.ts

@@ -0,0 +1,4 @@
+export type ModelLike = Record<string, any> & {
+    toJSON: () => object;
+};
+export declare function safeMemoize<T extends (...args: any[]) => any>(fn: T): T;

package/lib/utils/memoize.js

@@ -0,0 +1,57 @@
+import { memoize } from '@exodus/basic-utils';
+function processValue(value, seen) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (typeof value !== 'object') {
+        const isSpecialType = ['symbol', 'function', 'bigint'].includes(typeof value);
+        return isSpecialType ? value.toString() : value;
+    }
+    if (seen.has(value)) {
+        return '[Circular]';
+    }
+    seen.add(value);
+    if (isModelWithToJSON(value)) {
+        return value.toJSON();
+    }
+    if (value instanceof RegExp) {
+        return value.toString();
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (value instanceof Map) {
+        return [...value.entries()].map(([k, v]) => [k, processValue(v, seen)]);
+    }
+    if (value instanceof Set) {
+        return [...value].map((v) => processValue(v, seen));
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => processValue(v, seen));
+    }
+    const result = {};
+    for (const [key, val] of Object.entries(value)) {
+        if (val !== undefined) {
+            result[key] = processValue(val, seen);
+        }
+    }
+    return result;
+}
+function safeSerialize(value) {
+    try {
+        return JSON.stringify(processValue(value, new WeakSet()));
+    }
+    catch {
+        console.error('Could not serialize value:', value);
+        throw new Error('Value could not be serialized for memoization');
+    }
+}
+function isModelWithToJSON(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'toJSON' in value &&
+        typeof value.toJSON === 'function');
+}
+export function safeMemoize(fn) {
+    return memoize(fn, safeSerialize);
+}

package/lib/utils/types.d.ts

@@ -1,5 +1,8 @@
 export type Unsubscribe = () => void;
 export type Listener<T> = (value: T) => Promise<void> | void;
+export type ResettableListener<T> = Listener<T> & {
+    resetCallState: () => void;
+};
 export interface EventEmitter {
     on<T>(event: string, listener: Listener<T>): void;
     removeListener<T>(event: string, listener: Listener<T>): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/atoms",
-  "version": "9.0.0",
+  "version": "9.0.2",
   "description": "Abstraction for encapsulating a piece of data behind a simple unified interface: get, set, observe",
   "type": "module",
   "main": "lib/index.js",
@@ -28,6 +28,7 @@
     "url": "https://github.com/ExodusMovement/exodus-hydra/issues?q=is%3Aissue+is%3Aopen+label%3Aatoms"
   },
   "dependencies": {
+    "@exodus/basic-utils": "^3.2.0",
     "@exodus/storage-interface": "^1.0.0",
     "delay": "^5.0.0",
     "eventemitter3": "^4.0.7",
@@ -40,13 +41,14 @@
   },
   "devDependencies": {
     "@exodus/atom-tests": "^1.0.0",
-    "@exodus/storage-encrypted": "^1.4.1",
-    "@exodus/storage-memory": "^2.2.1",
+    "@exodus/deferring-storage": "^1.0.2",
+    "@exodus/storage-encrypted": "^1.4.2",
+    "@exodus/storage-memory": "^2.2.2",
     "@types/jest": "^29.5.11",
     "@types/json-stringify-safe": "^5.0.3",
     "@types/lodash": "^4.14.200",
     "@types/minimalistic-assert": "^1.0.2",
     "events": "^3.3.0"
   },
-  "gitHead": "bbcb4c47a53d1770a36213ba77fa1f46bccc8d64"
+  "gitHead": "86e9ba86050f754e564bcba758ccee8f9797c32d"
 }