@xstate/react - npm Package Compare versions

Comparing version 1.0.0 to 1.0.1

CHANGELOG.md

 # Changelog
 
+## 1.0.1
+
+### Patch Changes
+
+- [`c0bd0407`](https://github.com/davidkpiano/xstate/commit/c0bd040767dcac20ed690e49a8725b4f1011dd5d) [#1493](https://github.com/davidkpiano/xstate/pull/1493) Thanks [@davidkpiano](https://github.com/davidkpiano)! - There will now be a descriptive error when trying to use an actor-like object in the `useService()` hook, where `useActor()` should be preferred:
+
+  > Attempted to use an actor-like object instead of a service in the useService() hook. Please use the useActor() hook instead.
+
 All notable changes to this project will be documented in this file.
@@ -4,0 +12,0 @@

es/useService.js

 import { useMemo } from 'react';
 import { useActor } from './useActor';
 export function fromService(service) {
+    if (process.env.NODE_ENV !== 'production' && !('machine' in service)) {
+        throw new Error("Attempted to use an actor-like object instead of a service in the useService() hook. Please use the useActor() hook instead.");
+    }
     var machine = service.machine;
@@ -5,0 +8,0 @@ return {

lib/useService.js

@@ -7,2 +7,5 @@ "use strict";
 function fromService(service) {
+    if (process.env.NODE_ENV !== 'production' && !('machine' in service)) {
+        throw new Error("Attempted to use an actor-like object instead of a service in the useService() hook. Please use the useActor() hook instead.");
+    }
     var machine = service.machine;
@@ -9,0 +12,0 @@ return {

package.json

 {
   "name": "@xstate/react",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "XState tools for React",
@@ -5,0 +5,0 @@ "keywords": [

README.md

 # @xstate/react
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Quick Start](#quick-start)
+- [Examples](#examples)
+- [API](#api)
+  - [`useMachine(machine, options?)`](#usemachinemachine-options)
+  - [`useService(service)`](#useserviceservice)
+  - [`useActor(actor, getSnapshot)`](#useactoractor-getsnapshot)
+  - [`asEffect(action)`](#aseffectaction)
+  - [`asLayoutEffect(action)`](#aslayouteffectaction)
+  - [`useMachine(machine)` with `@xstate/fsm`](#usemachinemachine-with-xstatefsm)
+- [Configuring Machines](#configuring-machines)
+- [Matching States](#matching-states)
+- [Persisted and Rehydrated State](#persisted-and-rehydrated-state)
+- [Services](#services)
+- [Migration from 0.x](#migration-from-0x)
+- [Resources](#resources)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Quick Start
@@ -43,2 +64,6 @@
 
+## Examples
+
+- [XState + React TodoMVC (CodeSandbox)](https://codesandbox.io/s/xstate-todomvc-33wr94qv1)
+
 ## API
@@ -52,3 +77,16 @@
 
-- `machine` - An [XState machine](https://xstate.js.org/docs/guides/machines.html).
+- `machine` - An [XState machine](https://xstate.js.org/docs/guides/machines.html) or a function that lazily returns a machine:
+
+  ```js
+  // existing machine
+  const [state, send] = useMachine(machine);
+
+  // lazily-created machine
+  const [state, send] = useMachine(() =>
+    createMachine({
+      /* ... */
+    })
+  );
+  ```
+
 - `options` (optional) - [Interpreter options](https://xstate.js.org/docs/guides/interpretation.html#options) OR one of the following Machine Config options: `guards`, `actions`, `activities`, `services`, `delays`, `immediate`, `context`, or `state`.
@@ -64,7 +102,7 @@
 
-A [React hook](https://reactjs.org/hooks) that subscribes to state changes from an existing [service](TODO).
+A [React hook](https://reactjs.org/hooks) that subscribes to state changes from an existing [service](https://xstate.js.org/docs/guides/interpretation.html).
 
 **Arguments**
 
-- `service` - An [XState service](https://xstate.js.org/docs/guides/communication.html).
+- `service` - An [XState service](https://xstate.js.org/docs/guides/interpretation.html).
 
@@ -76,2 +114,22 @@ **Returns** a tuple of `[state, send]`:
 
+### `useActor(actor, getSnapshot)`
+
+A [React hook](https://reactjs.org/hooks) that subscribes to emitted changes from an existing [actor](https://xstate.js.org/docs/guides/actors.html).
+
+**Arguments**
+
+- `actor` - an actor-like object that contains `.send(...)` and `.subscribe(...)` methods.
+- `getSnapshot` - a function that should return the latest emitted value from the `actor`.
+  - Defaults to attempting to get the `actor.state`, or returning `undefined` if that does not exist.
+
+```js
+const [state, send] = useActor(someSpawnedActor);
+
+// with custom actors
+const [state, send] = useActor(customActor, (actor) => {
+  // implementation-specific pseudocode example:
+  return actor.getLastEmittedValue();
+});
+```
+
 ### `asEffect(action)`
@@ -201,3 +259,3 @@
 
-## Configuring Machines <Badge text="0.7+"/>
+## Configuring Machines
 
@@ -346,3 +404,3 @@ Existing machines can be configured by passing the machine options as the 2nd argument of `useMachine(machine, options)`.
 // Get the persisted state config object from somewhere, e.g. localStorage
-const persistedState = JSON.parse(localStorage.getItem('some-persisted-state-key'));
+const persistedState = JSON.parse(localStorage.getItem('some-persisted-state-key')) || someMachine.initialState;
 
@@ -384,4 +442,16 @@ const App = () => {
 
+## Migration from 0.x
+
+- For spawned actors created using `invoke` or `spawn(...)`, use the `useActor()` hook instead of `useService()`:
+
+  ```diff
+  -import { useService } from '@xstate/react';
+  +import { useService } from '@xstate/react';
+
+  -const [state, send] = useService(someActor);
+  +const [state, send] = useActor(someActor);
+  ```
+
 ## Resources
 
 [State Machines in React](https://gedd.ski/post/state-machines-in-react/)

No alert changes

Improved metrics

Total package byte prevSize

60237

increased by5.92%

Lines of code

1006

increased by0.6%

Number of lines in readme file

451

increased by18.37%

Worsened metrics

Number of low supply chain risk alerts

6

increased by50%

No dependency changes