useRecoilCallback() (#2075)RecoilEnv.RECOIL_GKS_ENABLED (#2078)Expose flag to disable "duplicate atom key" checking / logging, as it was too noisy in environments such as NextJS or some dev environments using Fast Refresh. (#733, #2020, #2046)
RecoilEnv from the recoil package, and set RecoilEnv.RECOIL_DUPLICATE_ATOM_KEY_CHECKING_ENABLED = false in code to disable the checking and logging.process.env.RECOIL_DUPLICATE_ATOM_KEY_CHECKING_ENABLED=false in NodeJS environments such as NextJsWorkaround for React 18 environments with nested renderers that don't support useSyncExternalStore(). (#2001, #2010)
updateItems() for the listen prop callback in <RecoilSync> in addition to updateItem() and updateAllKnownItems(). (#2017, #2035)queryParams with a param. This is a slight breaking change when an atom might sync with multiple URL params. (#1900, #1976)handlers prop is detected for <RecoilURLSyncTransit>. (#2044)boolean() export to bool() since boolean is a reserved word (#1922, #1962, #1971)native directory in package.json to cleanup errors for react-native. (#1931)Path class for custom checkers. (#1950, #1956)union() and or() with each type. (#1961)useRecoilSnapshot() with React's Fast Refresh during development (#1891)useRecoilSnapshot() and recoil-sync with changed browser behavior starting with Chrome v104 (#1943, #1936)Initial open source release for the recoil-sync NPM package! Recoil Sync provides an add-on library to help synchronize Recoil state with external systems. Simple asynchronous data queries can be implemented via selectors or useEffect(), or atom effects can be used for bi-directional syncing of individual atoms. The recoil-sync add-on package provides some additional functionality:
recoil-sync and refine help provide this functionality.The recoil-sync library also provides built-in implementations for external stores, such as syncing with the browser URL.
The basic idea is that a syncEffect() can be added to each atom that you wish to sync, and then a <RecoilSync> is added inside your <RecoilRoot> to specify how to sync those atoms. You can use built-in stores such as <RecoilURLSyncJSON>, make your own, or even sync different groups of atoms with different stores.
Here is a simple example syncing an atom with the browser URL:
const currentUserState = atom<number>({\n key: 'CurrentUser',\n default: 0,\n effects: [\n syncEffect({ refine: number() }),\n ],\n});\nThen, at the root of your application, simply include <RecoilURLSyncJSON> to sync all of those tagged atoms with the URL
function MyApp() {\n return (\n <RecoilRoot>\n <RecoilURLSyncJSON location={{part: 'queryParams'}}>\n ...\n </RecoilURLSyncJSON>\n </RecoilRoot>\n )\n}\nThat's it! Now this atom will initialize its state based on the URL during initial load, any state mutations will update the URL, and changes in the URL (such as the back button) will update the atom. See more examples in the Sync Effect, Store Implementation, and URL Persistence guides.
", "url": "https://recoiljs.org/blog/2022/06/21/recoil-sync-0.1.0-release", "title": "Recoil Sync 0.1", "summary": "Initial open source release for the recoil-sync NPM package! Recoil Sync provides an add-on library to help synchronize Recoil state with external systems. Simple asynchronous data queries can be implemented via selectors or useEffect(), or atom effects can be used for bi-directional syncing of individual atoms. The recoil-sync add-on package provides some additional functionality:", "date_modified": "2022-06-21T00:00:00.000Z" }, { "id": "/2022/06/21/refine-0.1.0-release", "content_html": "Initial open source release for the @recoiljs/refine library for type refinement and input validation for Flow and TypeScript! To get started learning about Refine, check out the documentation on the core concepts of Utilities and Checkers.
The Recoil Sync library leverages Refine for type refinement, input validation, and upgrading types for backward compatibility. See the recoil-sync docs for more details.
unknown TypeScript type or mixed Flow type values and you need to assert those values have a specific static type.Coerce unknown types to a strongly typed variable. assertion() will throw if the input doesn't match the expected type while coercion() will return null.
const myObjectChecker = object({\n numberProperty: number(),\n stringProperty: optional(string()),\n arrayProperty: array(number()),\n});\n\nconst myObjectAssertion = assertion(myObjectChecker);\nconst myObject: CheckerReturnType<myObjectChecker> = myObjectAssertion({\n numberProperty: 123,\n stringProperty: 'hello',\n arrayProperty: [1, 2, 3],\n});\nUsing match() and asType() you can upgrade from previous types to the latest version.
const myChecker: Checker<{str: string}> = match(\n object({str: string()}),\n asType(string(), str => ({str: str})),\n asType(number(), num => ({str: String(num)})),\n);\n\nconst obj1: {str: string} = coercion(myChecker({str: 'hello'}));\nconst obj2: {str: string} = coercion(myChecker('hello'));\nconst obj3: {str: string} = coercion(myChecker(123));\nRefine wraps JSON to provide a built-in strongly typed parser.
const myParser = jsonParser(\n array(object({num: number()}))\n);\n\nconst result = myParser('[{"num": 1}, {"num": 2}]');\n\nif (result != null) {\n // we can now access values in num typesafe way\n assert(result[0].num === 1);\n} else {\n // value failed to match parser spec\n}\nInitial open source release for the recoil-relay library for using GraphQL!
This library helps Recoil perform type safe and efficient queries using GraphQL with the Relay library. It provides selectors which can easily query with GraphQL. The queries are synced with the Recoil data-flow graph so downstream selectors can derive state from them, they can depend on upstream Recoil state, and they are automatically subscribed to any changes in the graph from Relay. Everything stays in sync automatically.
A GraphQL query is as simple as defining a GraphQL selector:
const userNameQuery = graphQLSelector({\n key: 'UserName',\n environment: myEnvironment,\n query: graphql`\n query UserQuery($id: ID!) {\n user(id: $id) {\n name\n }\n }\n `,\n variables: ({get}) => ({id: get(currentIDAtom)}),\n mapResponse: data => data.user?.name,\n});\nThen use it like any other Recoil selector:
function MyComponent() {\n const userName = useRecoilValue(userNameQuery);\n return <span>{userName}</span>;\n}\nparentStoreID_UNSTABLE to atom effects for the parent Recoil store the atom instance was cloned from. This enables the pre-fetch pattern for GraphQL. (#1744)Selector optimizations and fixes
Typing and various improvements
children prop to <RecoilRoot> and useRecoilBridgeAcrossReactRoots_UNSTABLE() for TypeScript to support the removal of implicit children with `@types/react@^18.0.0 for React 18. (#1718, #1717, #1726, #1731)toJSON(). (#1709, #1703)<RecoilRoot>'s. (#1712)Recoil 0.7 offers some minor API improvements, selector optimizations, and other fixes.
It is now optional to provide a default value for an atom. If no default is provided the atom will be kept in a "pending" state (e.g. triggering React Suspense) until it is set. (#1639)
This can help avoid awkward typing (such as unecessarily making the type nullable) or awkward placeholder values for the default. An example minimal string atom might be:
atom<string>({key: 'MyString'});\nThis is also useful when atoms are initialized with atom effects and a default may not be necessary:
atom({\n key: 'MyQuery',\n effects: [\n dbSyncEffect({query, variables}),\n ],\n});\n.getStoreID() method to Snapshot (#1612)RecoilLoadable.loading() factory for making an async Loadable which never resolves. (#1641)You now no longer need to manually retain snapshots for async callbacks from useRecoilCallback(). (#1632)
const myCallback = useRecoilCallback(({snapshot}) => async () => {\n // No longer necessary to retain() here\n await something;\n ... use snapshot ...\n });\nIf you want to save a Snapshot or reference it from closure state from some other scheduled handler, then you still need to manually retain it.
Now the selector get() evaluation callback or atom default property can use a Loadable object. (#1640) This can allow them to more cleanly accept synchronous error states:
atom({\n key: 'Key',\n default: RecoilLoadable.error(new Error('ERROR')),\n});\nor mapped Loadables or placeholders:
selector({\n key: 'Key',\n get: ({get}) => {\n const queryLoadable = get(noWait(myQuerySelector));\n if (queryLoadable.state === 'loading') {\n return PLACEHOLDER;\n }\n return queryLoadable; // Pass on the query results or error state.\n }\n})\nIf you wish to explicitly evaluate a selector value to a Promise, Loadable, or RecoilState type object then you can now wrap them with selector.value() or atom.value().
selector({\n key: 'Key',\n get: ({get}) => {\n // Returns an immediate synchronous value\n return selector.value(Promise.resolve('Promise as a value'));\n },\n});\nThis is only a minor change. It helps make the API more consisent for handling wrappers such as Promise and Loadable, though is not yet available across the entire API. But, it helps set the stage for future potential ability to explicitly set atoms and selectors to asynchronous values or error states.
useRecoilCallback() now provides a snapshot for the latest state instead of the latest rendered state, which had bugs (#1610, #1604)Window interface. (#1571)setSelf() from onSet() handlers. (#1589, #1582)Recoil 0.6 introduces improved support for React 18, including concurrent rendering and transitions, along with new APIs, fixes, and optimizations.
Recoil 0.6 uses the latest APIs from React 18 for improved safety and performance. This release is compatible with concurrent rendering and <React.StrictMode>, which is useful for testing and identifying potential issues for concurrent rendering. Making Recoil and React state changes in the same batch now stay in sync to provided a consistent view of state. Some of these improvements are also available while using previous versions of React. When experimenting with React 18 please use the latest RC build, as the original React 18.0.0-rc.0 package has a bug that has since been fixed.
React 18 offers a new hook useTransition() for transitioning to a new state while having control over what to render before the new state is ready. Recoil should be compatible with this approach and provides a consistent view with React state. However, React 18 may fallback from concurrent updates and does not yet officially support initiating transitions based on state changes to external stores. This is something the React team is looking into supporting, but until then we have added experimental support for this through the following hooks. This API is considered experimental because there may be use cases we haven’t found which are not handled.
useRecoilState_TRANSITION_SUPPORT_UNSTABLE()useRecoilValue_TRANSITION_SUPPORT_UNSTABLE()useRecoilValueLoadable_TRANSITION_SUPPORT_UNSTABLE()Here's an example that displays the current results while a new result is loading:
function QueryResults() {\n const queryParams = useRecoilValue_TRANSITION_SUPPORT_UNSTABLE(queryParamsAtom);\n const results = useRecoilValue_TRANSITION_SUPPORT_UNSTABLE(myQuerySelector(queryParams));\n return results;\n}\n\nfunction MyApp() {\n const [queryParams, setQueryParams] = useRecoilState_TRANSITION_SUPPORT_UNSTABLE(queryParamsAtom);\n const [inTransition, startTransition] = useTransition();\n return (\n <div>\n {inTransition ? <div>[Loading new results...]</div> : ''}\n Results: <React.Suspense><QueryResults /></React.Suspense>\n <button\n onClick={() => {\n startTransition(() => {\n setQueryParams(...new params...);\n });\n }\n >\n Start New Query\n </button>\n </div>\n );\n}\nuseRecoilCallback() can now also refresh selector caches, similar to useRecoilRefresher_UNSTABLE(). (#1413)getCallback() can now mutate, refresh, and transact state in addition to reading it, similar to useRecoilCallback(). (#1498)StoreID can now be obtained using useRecoilStoreID() (#1417) or the storeID parameter in atom effects (#1414).RecoilLoadable.of() and RecoilLoadable.all() factories now accept either literal values, async Promises, or Loadables. This is comparable to Promise.resolve() and Promise.all() (#1455, #1442)..isRetained() method for Snapshots and check if snapshot is already released when using .retain() in development (#1546)effects_UNSTABLE to just effects, as the interface is mostly stabilizing. (#1520)<RecoilRoot initializeState={...}>. (#1509)useGetRecoilValueInfo_UNSTABLE() and Snapshot#getInfo_UNSTABLE() always report the node type. (#1547)set() during a transaction from useRecoilTransaction_UNSTABLE() (#1466, #1569)onSet() handlers in atom effects when atoms are cleaned up. (#1509)onSet() when atoms are initialized with <RecoilRoot initializeState={...} > (#1519, #1511)<RecoilRoot> will only call initializeState() once during the initial render. (#1372)useGetRecoilValueInfo() or Snapshot#getInfo_UNSTABLE(). (#1548, #1549)Welcome to Recoil 0.5 with a few new APIs and improvements.
The useRecoilRefresher_UNSTABLE() hook has been added for refreshing selectors that execute data queries. This is useful if you just want to refresh for newer data or retry due to an error. (#972, #1294, #1302)
isReset parameter to onSet() callback to know if the atom was reset. (#1358, #1345)getLoadable(), getPromise(), and getInfo_UNSTABLE() for reading other atoms. (#1205, #1210)The RecoilLoadable interface is now available for making your own Loadable objects. (#1263, #1264, #1312)
Loadable improvements:Also lots of restructuring in preparation for the upcoming recoil-sync library release...
Recoil 0.4.1 has been released with some performance optimizations and fixes focused on optimizing when React will re-render components based on Recoil state changes.
We are pleased to announce the release of Recoil 0.4 with configurable selector caches, improved API for transactions with multiple atoms, and other optimizations and fixes.
The new cachePolicy_UNSTABLE property in selectors and selector families allows you to configure the caching behavior of a selector's internal cache. This property can be useful for reducing memory in applications that have a large number of selectors or selectors that have a large number of changing dependencies.
Below is an example of how you might use this new property:
const clockState = selector({\n key: 'clockState',\n get: ({get}) => {\n const hour = get(hourState);\n const minute = get(minuteState);\n const second = get(secondState); // will re-run every second\n\n return `${hour}:${minute}:${second}`;\n },\n cachePolicy_UNSTABLE: {\n // Only store the most recent set of dependencies and their values\n eviction: 'most-recent',\n },\n});\nIn the example above, clockState recalculates every second, adding a new set of dependency values to the internal cache, which may lead to a memory issue over time as the internal cache grows indefinitely. Using the most-recent eviction policy, the internal selector cache will only retain the most recent set of dependencies and their values, along with the actual selector value based on those dependencies, thus solving the memory issue.
Current eviction options are:
lru - evicts the least-recently-used value from the cache when the size exceeds maxSize.most-recent - retains only the most recent value.keep-all (default) - keeps all entries in the cache and does not evict.NOTE: The default eviction policy (currently
keep-all) may change in the future.
Introducing an improved API for updating multiple atoms together as a single transaction. The new useRecoilTransaction_UNSTABLE() hook is easier, more efficient, and safer than before. This new hook should eventually replace most uses of useRecoilCallback(), however this release is only an initial implementation with certain limitations that will be addressed in future releases.
Suppose we have two atoms, positionState and headingState, and we'd like to update them together as part of a single action, where the new value of positionState is a function of both the current value of positionState and headingState. You can accomplish this with a transaction, which must be a pure function without side-effects:
const goForward = useRecoilTransaction_UNSTABLE(({get, set}) => (distance) => {\n const heading = get(headingState);\n const position = get(positionState);\n set(positionAtom, {\n x: position.x + cos(heading) * distance,\n y: position.y + sin(heading) * distance,\n });\n});\nThen you can execute the transaction by just calling goForward(distance) in an event handler. This will update state based on the current values, not the state when the components rendered. You can also read the values of previous writes during a transaction. Because no other updates will be committed while the updater is executing, you will see a consistent store of state.
the previous approach using useRecoilCallback() might have looked like the following:
const goForward = useRecoilCallback(({snapshot, gotoSnapshot}) => (distance) => {\n const mutatedSnapshot = snapshot.map(({get, set}) => {\n const heading = get(headingState);\n const position = get(positionState);\n set(positionState, {\n x: position.x + cos(heading) * distance,\n y: position.y + sin(heading) * distance,\n });\n });\n gotoSnapshot(mutatedSnapshot);\n});\nThis has the following drawbacks:
You can also use this hook to create a reducer pattern of executing actions over multiple atoms:
const reducer = useRecoilTransaction_UNSTABLE(({get, set}) => action => {\n switch(action.type) {\n case 'goForward':\n const heading = get(headingState);\n set(positionState, position => {\n x: position.x + cos(heading) * action.distance,\n y: position.y + sin(heading) * action.distance,\n });\n break;\n\n case 'turn':\n set(headingState, action.heading);\n break;\n }\n});\nselectorFamily(), getCallback(), useGetRecoilValueInfo(), and Snapshot#getNodes() (#1060, #1116, #1123)dangerouslyAllowMutability selector option) to be used with waitFor*() helpers such as waitForAll() (#1074, #1096)onSet() handler to get the proper new value when an atom is reset or has an async default Promise that resolves (#1059, #1050, #738) (This is a slightly breaking change because the actual new value will be provided to the handler instead of a DefaultValue placeholder)Snapshot (#1135, #1107)We are pleased to announce the release of Recoil 0.3 with more flexible RecoilRoot nesting, callback generation, preparation for memory management, optimizations, and bug fixes.
The next release of Recoil will have a breaking API change. Today's release issues a console warning in development builds if you have any code that will need to be updated. Most apps will not need any code changes.
When we ship memory management, Snapshots (such as the one you get as an argument to useRecoilCallback()) will only be valid for the tick in which they are created. If you want to keep a Snapshot around for longer, you need to manually retain and then release it:
const release = snapshot.retain();\ntry {\n await someAsyncWork(snapshot);\n} finally {\n release();\n}\nIn 0.3.0, if you use a Snapshot that hasn't been retained, you will get a console warning in development. There is no change in behavior in production. In the next release, it will throw an exception, in both development and production.
Retaining Snapshots should be avoided whenever possible, because it will prevent reclaiming of memory for all atoms for as long as that Snapshot is retained. Instead, pull out just the values you need before going to async.
atomFamily. One app with thousands of atoms saw 200MB less memory usage.onSet() is no longer called when triggered from setSelf() initializing with a Promise or from the same onSet() handler. (#974, #979, #953, #986)Loadables.We are pleased to announce the release of Recoil 0.2.0. This release has a new, more reliable implementation of async selectors, greatly improved performance, and many bug fixes and improvements.
We've reimplemented selectors to fix a number of corner cases that we didn't handle before. For instance:
These are just a few of the unit tests that pass only with the new implementation. You are now less likely to hit incorrect behavior when using async selectors in Recoil.
Many of the fixed bugs manifested as unnecessary execution of selectors. In one app that heavily uses async selectors, we observed an overall 15% decrease in the number of selector executions.
Christian Santos (@csantos42) has been working on this with great diligence and we're extremely happy to release it today.
Recoil now uses special data structures to maintain efficiency with large numbers of atoms. It is now hundreds of times faster when using 10,000 atoms.
Recoil now has a logo. Thanks to Gray Pegg (@graypegg) for designing it and for sprucing up our website!
waitForAny() has changed: It now lets you access the individual Loadables corresponding to its arguments, even if one of them is in an error state. This makes it more consistent with waitForNone().waitForAllSettled() helper analogous to Promise.allSettled.useRecoilCallback(). (#870)useGetRecoilValueInfo_UNSTABLE() hook for use by dev tools. (#713, #714)Promise that is thrown as an error, rather than only instances of Error.<RecoilRoot> could sometimes have its state updated after being unmounted. (#917)<RecoilRoot> wasn't displayed on React experimental releases. (#712)As mentioned above, the behavior of waitForAny() has changed. If you rely on the behavior that waitForAny() resulted in an error state if any of its arguments is in an error state, your code will break. Now it returns individual Loadables for each argument, just as with the non-error state, and you can check for an error in each argument.
If you throw something that is not a Promise and not an Error from within a selector, it will now put the selector into an error state instead of treating the thrown object as a value.
We are very close to releasing Memory Management, which will allow Recoil to automatically delete atoms and selectors that are no longer being used, configurable on a per-atom basis. This will also include configurable LRU caching for selectors.\nThese new features are in use internally at Facebook, but require a slight breaking change to the API. So our next release will start warning in cases where your code will break. The required changes are not difficult, and should be rare: Out of thousands of modules that import Recoil, we found less than half a dozen that required changes.
", "url": "https://recoiljs.org/blog/2021/03/22/0.2.0-released", "title": "Recoil 0.2", "summary": "We are pleased to announce the release of Recoil 0.2.0. This release has a new, more reliable implementation of async selectors, greatly improved performance, and many bug fixes and improvements.", "date_modified": "2021-03-22T00:00:00.000Z" }, { "id": "/2020/10/30/0.1.1-released", "content_html": "Welcome to Recoil version 0.1.1! This release has performance improvements and introduces several experimental features such as support for React Native, working with Snapshots outside of React, and atom effects for managing side-effects of atoms such as logging, synchronization with external stores, persistence, etc.
Also, nightly builds are now available via the nightly branch.
Several changes to improve Recoil's performance:
useRecoilCallback() are now batched, which avoids copying data structures or performing updates for intermediate states. This allowed setting 5,000 atoms in a loop to go from 10s -> 25ms with some of our stress tests. (@davidmccabe)Recoil should now work with the React Native environment. However, similar to server side rendering, it is not officially supported. (#114 - @jacques-blom, @mondaychen)
Effects for atoms simplifies managing side-effect policies for atoms on a per-atom basis as part of the atom() or atomFamily() definition. Effects can be used for interesting applications such as logging and state synchronization or persistence with external storage such as remote databases, local storage, browser URL history, etc. For example, you could use an atom as a local copy of some user state and provide an effect to subscribe to changes on a server to update the local copy and for local changes to write-through and update the server. (#680, #380, #381, #384, #385, #448, #449, #412, #591, #634, #682 — @drarmstr, @csantos4242)
Snapshots can now be constructed outside of a React context. This can be useful for testing or evaluating selectors outside of a React context. (#649 — @drarmstr, @habond)
Snapshot. (#687 — @kevinfrei, @drarmstr, @habond)waitForAll() concurrency. (#681 — @drarmstr)In a future release, Recoil will automatically free the memory used by atoms and selectors that are no longer used, and will perform better with larger numbers of atoms. (@davidmccabe)
Releasing our prototype Chrome developer tools. (@maxijb)
Libraries of effects for common state persistence, such as browser local storage or URL history. (@bezi)
Thanks for your continued interest in Recoil!
", "url": "https://recoiljs.org/blog/2020/10/30/0.1.1-released", "title": "Recoil 0.1.1", "summary": "Welcome to Recoil version 0.1.1! This release has performance improvements and introduces several experimental features such as support for React Native, working with Snapshots outside of React, and atom effects for managing side-effects of atoms such as logging, synchronization with external stores, persistence, etc.", "date_modified": "2020-10-30T00:00:00.000Z" }, { "id": "/2020/09/15/0.0.11-released", "url": "https://recoiljs.org/blog/2020/09/15/0.0.11-released", "title": "Recoil 0.0.11", "summary": "Today we are releasing Recoil 0.0.11. It contains bug fixes, new features, better performance, and experimental compatibility with Concurrent Mode. Thank you so much to everyone who contributed to this release!", "date_modified": "2020-09-15T00:00:00.000Z" }, { "id": "/2020/06/18/0.0.10-released", "content_html": "Recoil 0.0.9 and 0.0.10 is being released with some bug fixes, TypeScript support, and a new API for Recoil Snapshots to observe, inspect, and manage global Recoil atom state. Thanks again to everyone who helped make this possible and stay tuned for more exciting developments coming soon!
useRecoilCallback() getting current state (#260) - Thanks @drarmstrTypeScript support is being rolled into the Recoil GitHub repository instead of DefinitelyTyped to help better keep it in sync with the API. (#292 & #339) - Thanks @csantos42
#312, #311, #310, #309, #260, #259, #258, #257, #256 - Thanks @drarmstr and the rest of the team
We are introducing the concept of a Snapshot to Recoil. A Snapshot is an immutable snapshot of the state of Recoil atoms. This is intended to standardize the API for observing, inspecting, and managing global Recoil state and derived state. It’s useful for dev tools, global state synchronization, history, and navigation.
The Snapshot class exposes the following methods for getting the values of individual Recoil atoms and selectors:
class Snapshot {\n getLoadable: <T>(RecoilValue<T>) => Loadable<T>;\n getPromise: <T>(RecoilValue<T>) => Promise<T>;\n ...\n}\nSnapshots are read-only with respect to atom state. They can be used to read atom state and evaluate selector derived state. For asynchronous selectors, the getPromise() method can be used to wait for the evaluated value so you can see what the selector value would be based on the static atom state.
There are cases where you may wish to mutate a snapshot. While snapshots are immutable, they have methods to map themselves with a set of transformations to a new immutable snapshot. The map methods take a callback that is passed a MutableSnapshot, which is mutated throughout the callback and will ultimately become the new snapshot returned by the mapping operation.
class Snapshot {\n ...\n map: (MutableSnapshot => void) => Snapshot;\n asyncMap: (MutableSnapshot => Promise<void>) => Promise<Snapshot>;\n}\n\nclass MutableSnapshot {\n set: <T>(RecoilState<T>, T | DefaultValue | (T => T | DefaultValue)) => void;\n reset: <T>(RecoilState<T>) => void;\n}\nNotice that set() and reset() have the same signature as the callbacks provided to a writeable selector’s set() function.
Example
const newSnapshot = snapshot.map(({set}) => set(myAtom, 42));\nRecoil has the following hooks for working with snapshots:
useRecoilSnapshot() - Synchronous access to snapshotuseRecoilCallback() - Asynchronous access to snapshotuseRecoilTransactionObserver() - Subscribe to snapshots of all state updatesuseGotoRecoilSnapshot() - Update current state to match snapshotfunction useRecoilSnapshot(): Snapshot\nYou can use this hook to synchronously obtain a snapshot to the current state while rendering a component. While conceptually simple, this hook will subscribe any component that uses it to any Recoil state change so it always renders with a snapshot of the current state. Therefore, be careful using this hook. One example when you may want to use it is for supporting server-side rendering where you need to synchronously have the state with the first render. In the future, we may provide the ability to debounce for performance.
Example
Define a <LinkToNewState> component that renders an <a> anchor with an href based on the current state with a mutation applied. In this example uriFromSnapshot() is some user-defined function which encodes the current state in the URI which can be restored when loading the page.
function LinkToNewState() {\n const snapshot = useRecoilSnapshot();\n const newSnapshot = snapshot.map(({set}) => set(myAtom, 42));\n return <a href={uriFromSnapshot(newSnapshot)}>Click Me!</a>;\n}\nThis is a simplified example. We have a helper like this for generating links in our browser history persistence library coming soon which is more extensible and optimized. For example, it will hijack the click handler to update local state without needing to go through the browser history.
type CallbackInterface = {\n snapshot: Snapshot,\n gotoSnapshot: Snapshot => void,\n set: <T>(RecoilState<T>, (T => T) | T) => void,\n reset: <T>(RecoilState<T>) => void,\n};\n\nfunction useRecoilCallback<Args, Return>(\n callback: CallbackInterface => (...Args) => ReturnValue,\n deps?: $ReadOnlyArray<mixed>,\n): (...Args) => ReturnValue\nThe useRecoilCallback() hook is similar to the React useCallback() hook for producing a callback function. But, instead of just providing an input callback function you wrap it with a function providing a callback interface parameter that gives you access to a Snapshot and set()/reset() callbacks to update the current global state. The provided Snapshot represents the state when the callback is called, not when the callback function was originally created.
NOTE: This is a slight breaking change in the API, but we are still on version 0.0.x of Recoil and haven’t fully started semantic versioning yet.
useRecoilCallback() also takes an optional deps array parameter for controlling memoization. You can extend the react-hooks/exhaustive-deps lint rule for ensuring this is properly used.
Some motivations for using useRecoilCallback():
Asynchronously use Recoil state without subscribing a React component to re-render if the atom or selector is updated.
Deferring expensive lookups to an async action that you don't want to do at render-time.
Performing side-effects where you would like to also read or write to Recoil state.
Dynamically updating an atom or selector where we may not know at render-time which atom or selector we will want to update, so we can't use useSetRecoilState().
Pre-fetching before rendering
Example
Button component which will evaluate an expensive selector when clicked on.
function ShowDetailsButton() {\n const onClick = useRecoilCallback(({snapshot}) => async () => {\n const data = await snapshot.getPromise(expensiveQuery);\n showPopup(data);\n });\n\n return <button onClick={onClick}>Show Details</button>;\n}\nfunction useRecoilTransactionObserver_UNSTABLE(({\n snapshot: Snapshot,\n previousSnapshot: Snapshot,\n}) => void)\nThis hook subscribes a callback to be executed every time there is a change to Recoil atom state. Multiple updates may be batched together in a single transaction. This hook is great for persisting state changes, dev tools, building history, &c. In the future, we may allow the ability to subscribe to specific conditions or provide debouncing for performance.
Debug Observer Example
function DebugObserver() {\n useRecoilTransactionObserver_UNSTABLE(({snapshot}) => {\n window.myDebugState = {\n a: snapshot.getLoadable(atomA).contents,\n b: snapshot.getLoadable(atomB).contents,\n };\n });\n return null;\n}\nfunction useGotoRecoilSnapshot(): Snapshot => void\nThis hook returns a callback which takes a Snapshot as a parameter and will update the current <RecoilRoot> state to match this atom state.
Time Travel Example
Example list of history of state changes with the ability to go back and restore previous state.
function TimeTravelObserver() {\n const [snapshots, setSnapshots] = useState([]);\n\n useRecoilTransactionObserver_UNSTABLE(({snapshot}) => {\n setSnapshots([...snapshots, snapshot]);\n });\n\n const gotoSnapshot = useGotoRecoilSnapshot();\n\n return (\n <ol>\n {snapshots.map((snapshot, i) => (\n <li key={i}>\n Snapshot {i}\n <button onClick={() => gotoSnapshot(snapshot)}>\n Restore\n </button>\n </li>\n )}\n </ol>\n );\n}\nThe <RecoilRoot> component also has an initializeState prop which can be used to initialize the atom state. This prop takes a function with a MutableSnapshot parameter that can be used to setup the initial atom state. This can be helpful for loading persisted state when you know all atoms in advance. It can be useful for server-side rendering where the state should be setup synchronously for the first render.
Example
function MyApp() {\n return (\n <RecoilRoot\n initializeState={({set}) => {\n for (const [atom, value] of atoms) {\n set(atom, value);\n }\n }}\n >\n <AppContents />\n </RecoilRoot>\n );\n}\nSnapshots allow us to observe and synchronize the global state. But, what if we want a more granular and composable system to work with individual atoms? We’re working on the concept of Atom Effects for observing and dealing with side-effects at the atom level. This will make it easier to persist state or bi-directionally sync with mutable storage. Think of synchronizing state with the browser URI history, browser local storage, RESTful APIs, &c. Coming soon!
The Snapshot API introduced here allows us to inspect the current state for individual atoms and selectors. We’ll be expanding the API to be able to inspect the set of available nodes and explore the data-flow graph structure. This will be powerful for building dev tools. Stay tuned!
And, of course, we still have exiciting support for React Concurrent Mode and improved speed, scalability, and memory management in the works.
", "url": "https://recoiljs.org/blog/2020/06/18/0.0.10-released", "title": "Recoil 0.0.10", "summary": "Recoil 0.0.9 and 0.0.10 is being released with some bug fixes, TypeScript support, and a new API for Recoil Snapshots to observe, inspect, and manage global Recoil atom state. Thanks again to everyone who helped make this possible and stay tuned for more exciting developments coming soon!", "date_modified": "2020-06-18T00:00:00.000Z" }, { "id": "/2020/05/30/0.0.8-released", "content_html": "Today we are releasing Recoil 0.0.8. It contains bug fixes and new features. Thanks so much to everyone who contributed to this release! It's been amazing to see so many people contribute.
TypeScript definitions are now available via the DefinitelyTyped repository.
atomFamily and selectorFamilyThese utilities help you create collections of related atoms or selectors, one for each value of some parameter. Instaed of manually creating a memoized function that returns an atom or selector, you can use atomFamily and selectorFamily. In the future, these utilities will also help with memory management.
The atomFamily function returns a function from some parameter to an atom, creating a new atom for each value of the parameter that is passed in. For example, suppose you wanted to store a set of coordinates {x: number, y: number} for every member of a collection identified by some ID. Then you could write:
const coordinatesForID = atomFamily<{x: number, y: number}, ID>({\n key: 'coordinatesForID',\n default: {x: 0, y: 0},\n});\nand then access that state as follows:
function MyComponent({id}) {\n const [coordinates, setCoordinates] = useRecoilState(\n coordinatesForID(id)\n );\n ...\n}\nEach ID passed to coordinatesForID will get its own independent atom containing the coordinates. Each of these atoms has its own subscriptions, so a component that uses the state for a single ID will only be subscribed to changes to that one ID.
Similarly, selectorFamily lets you create a different selector for each value of some parameter. For example, suppose you wanted to take each of those coordinates and rotate them by 180 degrees:
const rotatedCoordinatesForID = selectorFamily<{x: number, y: number}, ID>({\n key: 'rotatedCoordinatesForID',\n get: id => ({get}) => {\n const coordinates = get(coordinatesForID(id));\n return {\n x: -coordinates.x,\n y: -coordinates.y,\n };\n }\n});\nNote that the get property of a selector family is a function that takes the parameter (in this case ID) and returns a function with a signature identical to the get property of a single selector. In general, this is how all of the options for atom families and selector families work.
We've introduced selector families for controlling concurrency in async selectors:
waitForAll: requests all dependencies in parallel and waits for all of them to become available.waitForAny: requests all dependencies in parallel and waits for any one of them to become available.waitForNone: requests all dependencies in parallel but doesn't wait for any of them.noWait requests a single dependency but doesn't wait for it to become available.These can be used to retireve multiple dependencies in parallel and to write logic conditional on the status of an upstream dependency. For example, you can write a selector that conditionally provides a default value while an async process is in flight instead of propagating that loading state down to components.
constSelector and errorSelectorThese selector families simply return a constant value or always throw a given error, respectively.
This simply wraps a read-write RecoilState in a read-only interface.
We're working on improvements to the observation and persistence APIs, improved speed and memory management, and support for Concurrent Mode. Thanks so much for trying Recoil, we hope you'll stick around and see what it becomes!
", "url": "https://recoiljs.org/blog/2020/05/30/0.0.8-released", "title": "Recoil 0.0.8", "summary": "Today we are releasing Recoil 0.0.8. It contains bug fixes and new features. Thanks so much to everyone who contributed to this release! It's been amazing to see so many people contribute.", "date_modified": "2020-05-30T00:00:00.000Z" } ] }