|
| 1 | +--- |
| 2 | +type: docs |
| 3 | +title: "JavaScript SDK for Actors" |
| 4 | +linkTitle: "Actors" |
| 5 | +weight: 1000 |
| 6 | +description: How to get up and running with Actors using the Dapr JavaScript SDK |
| 7 | +--- |
| 8 | + |
| 9 | +The Dapr actors package allows you to interact with Dapr virtual actors from a JavaScript application. The examples below demonstrate how to use the JavaScript SDK for interacting with virtual actors. |
| 10 | + |
| 11 | +For a more in-depth overview of Dapr actors, visit the [actors overview page]({{< ref actors-overview >}}). |
| 12 | + |
| 13 | +## Pre-requisites |
| 14 | +- [Dapr CLI]({{< ref install-dapr-cli.md >}}) installed |
| 15 | +- Initialized [Dapr environment]({{< ref install-dapr-selfhost.md >}}) |
| 16 | +- [Latest LTS version of Node or greater](https://nodejs.org/en/) |
| 17 | +- [JavaScript NPM package installed](https://www.npmjs.com/package/@dapr/dapr) |
| 18 | + |
| 19 | +## Scenario |
| 20 | +The below code examples loosely describe the scenario of a Parking Garage Spot Monitoring System, which can be seen in this [video](https://www.youtube.com/watch?v=eJCu6a-x9uo&t=3785) by Mark Russinovich. |
| 21 | + |
| 22 | +A parking garage consists of hundreds of parking spaces, where each parking space includes a sensor that provides updates to a centralized monitoring system. The parking space sensors (our actors) detect if a parking space is occupied or available. |
| 23 | + |
| 24 | +To jump in and run this example yourself, clone the source code, which can be found in the [JavaScript SDK examples directory](https://github.com/dapr/js-sdk/tree/master/examples/http/actor-parking-sensor). |
| 25 | + |
| 26 | +## Actor Interface |
| 27 | +The actor interface defines the contract that is shared between the actor implementation and the clients calling the actor. In the example below, we have created an interace for a parking garage sensor. Each sensor has 2 methods: `carEnter` and `carLeave`, which defines the state of the parking space: |
| 28 | + |
| 29 | +```ts |
| 30 | +export default interface ParkingSensorInterface { |
| 31 | + carEnter(): Promise<void>; |
| 32 | + carLeave(): Promise<void>; |
| 33 | +} |
| 34 | +``` |
| 35 | + |
| 36 | +## Actor Implementation |
| 37 | +An actor implementation defines a class by extending the base type `AbstractActor` and implementing the actor interface (`ParkingSensorInterface` in this case). |
| 38 | + |
| 39 | +The following code describes an actor implementation along with a few helper methods. |
| 40 | + |
| 41 | +```ts |
| 42 | +import { AbstractActor } from "@dapr/dapr"; |
| 43 | +import ParkingSensorInterface from "./ParkingSensorInterface"; |
| 44 | + |
| 45 | +export default class ParkingSensorImpl extends AbstractActor implements ParkingSensorInterface { |
| 46 | + async carEnter(): Promise<void> { |
| 47 | + // Implementation that updates state that this parking spaces is occupied. |
| 48 | + } |
| 49 | + |
| 50 | + async carLeave(): Promise<void> { |
| 51 | + // Implementation that updates state that this parking spaces is available. |
| 52 | + } |
| 53 | + |
| 54 | + private async getInfo(): Promise<object> { |
| 55 | + // Implementation of requesting an update from the parking space sensor. |
| 56 | + } |
| 57 | + |
| 58 | + /** |
| 59 | + * @override |
| 60 | + */ |
| 61 | + async onActivate(): Promise<void> { |
| 62 | + // Initialization logic called by AbstractActor. |
| 63 | + } |
| 64 | +} |
| 65 | +``` |
| 66 | + |
| 67 | +## Registering Actors |
| 68 | +Initialize and register your actors by using the `DaprServer` package: |
| 69 | + |
| 70 | +```javascript |
| 71 | +import { DaprServer } from "@dapr/dapr"; |
| 72 | +import ParkingSensorImpl from "./ParkingSensorImpl"; |
| 73 | + |
| 74 | +const daprHost = "127.0.0.1"; |
| 75 | +const daprPort = "50000"; |
| 76 | +const serverHost = "127.0.0.1"; |
| 77 | +const serverPort = "50001"; |
| 78 | + |
| 79 | +const server = new DaprServer(serverHost, serverPort, daprHost, daprPort); |
| 80 | + |
| 81 | +await server.actor.init(); // Let the server know we need actors |
| 82 | +server.actor.registerActor(ParkingSensorImpl); // Register the actor |
| 83 | +await server.start(); // Start the server |
| 84 | + |
| 85 | +// To get the registered actors, you can invoke `getRegisteredActors`: |
| 86 | +const resRegisteredActors = await server.actor.getRegisteredActors(); |
| 87 | +console.log(`Registered Actors: ${JSON.stringify(resRegisteredActors)}`); |
| 88 | +``` |
| 89 | + |
| 90 | +## Invoking Actor Methods |
| 91 | +After Actors are registered, create a Proxy object that implements `ParkingSensorInterface` using the `ActorProxyBuilder`. You can invoke the actor methods by directly calling methods on the Proxy object. Internally, it translates to making a network call to the Actor API and fetches the result back. |
| 92 | + |
| 93 | +```javascript |
| 94 | +import { DaprClient, ActorId } from "@dapr/dapr"; |
| 95 | +import ParkingSensorImpl from "./ParkingSensorImpl"; |
| 96 | +import ParkingSensorInterface from "./ParkingSensorInterface"; |
| 97 | + |
| 98 | +const daprHost = "127.0.0.1"; |
| 99 | +const daprPort = "50000"; |
| 100 | + |
| 101 | +const client = new DaprClient(daprHost, daprPort); |
| 102 | + |
| 103 | +// Create a new actor builder. It can be used to create multiple actors of a type. |
| 104 | +const builder = new ActorProxyBuilder<ParkingSensorInterface>(ParkingSensorImpl, client); |
| 105 | + |
| 106 | +// Create a new actor instance. |
| 107 | +const actor = builder.build(new ActorId("my-actor")); |
| 108 | +// Or alternatively, use a random ID |
| 109 | +// const actor = builder.build(ActorId.createRandomId()); |
| 110 | + |
| 111 | +// Invoke the method. |
| 112 | +await actor.carEnter(); |
| 113 | +``` |
| 114 | + |
| 115 | +## Using states with Actor |
| 116 | + |
| 117 | +```ts |
| 118 | +// ... |
| 119 | + |
| 120 | +const PARKING_SENSOR_PARKED_STATE_NAME = "parking-sensor-parked" |
| 121 | + |
| 122 | +const actor = builder.build(new ActorId("my-actor")) |
| 123 | + |
| 124 | +// SET state |
| 125 | +await actor.getStateManager().setState(PARKING_SENSOR_PARKED_STATE_NAME, true); |
| 126 | + |
| 127 | +// GET state |
| 128 | +const value = await actor.getStateManager().getState(PARKING_SENSOR_PARKED_STATE_NAME); |
| 129 | +if (!value) { |
| 130 | + console.log(`Received: ${value}!`); |
| 131 | +} |
| 132 | + |
| 133 | +// DELETE state |
| 134 | +await actor.removeState(PARKING_SENSOR_PARKED_STATE_NAME); |
| 135 | +... |
| 136 | +``` |
| 137 | + |
| 138 | +## Actor Timers and Reminders |
| 139 | +The JS SDK supports actors that can schedule periodic work on themselves by registering either timers or reminders. The main difference between timers and reminders is that the Dapr actor runtime does not retain any information about timers after deactivation, but persists reminders information using the Dapr actor state provider. |
| 140 | + |
| 141 | +This distinction allows users to trade off between light-weight but stateless timers versus more resource-demanding but stateful reminders. |
| 142 | + |
| 143 | +The scheduling interface of timers and reminders is identical. For an more in-depth look at the scheduling configurations see the [actors timers and reminders docs]({{< ref "howto-actors.md#actor-timers-and-reminders" >}}). |
| 144 | + |
| 145 | +### Actor Timers |
| 146 | +```javascript |
| 147 | +// ... |
| 148 | + |
| 149 | +const actor = builder.build(new ActorId("my-actor")); |
| 150 | + |
| 151 | +// Register a timer |
| 152 | +await actor.registerActorTimer( |
| 153 | + "timer-id", // Unique name of the timer. |
| 154 | + "cb-method", // Callback method to execute when timer is fired. |
| 155 | + Temporal.Duration.from({ seconds: 2 }), // DueTime |
| 156 | + Temporal.Duration.from({ seconds: 1 }), // Period |
| 157 | + Temporal.Duration.from({ seconds: 1 }), // TTL |
| 158 | + 50 // State to be sent to timer callback. |
| 159 | +); |
| 160 | + |
| 161 | +// Delete the timer |
| 162 | +await actor.unregisterActorTimer("timer-id"); |
| 163 | +``` |
| 164 | + |
| 165 | +### Actor Reminders |
| 166 | +```javascript |
| 167 | +// ... |
| 168 | + |
| 169 | +const actor = builder.build(new ActorId("my-actor")); |
| 170 | + |
| 171 | +// Register a reminder, it has a default callback: `receiveReminder` |
| 172 | +await actor.registerActorReminder( |
| 173 | + "reminder-id", // Unique name of the reminder. |
| 174 | + Temporal.Duration.from({ seconds: 2 }), // DueTime |
| 175 | + Temporal.Duration.from({ seconds: 1 }), // Period |
| 176 | + Temporal.Duration.from({ seconds: 1 }), // TTL |
| 177 | + 100 // State to be sent to reminder callback. |
| 178 | +); |
| 179 | + |
| 180 | +// Delete the reminder |
| 181 | +await actor.unregisterActorReminder("reminder-id"); |
| 182 | +``` |
| 183 | + |
| 184 | +To handle the callback, you need to override the default `receiveReminder` implementation in your actor. For example, from our original actor implementation: |
| 185 | +```ts |
| 186 | +export default class ParkingSensorImpl extends AbstractActor implements ParkingSensorInterface { |
| 187 | + // ... |
| 188 | + |
| 189 | + /** |
| 190 | + * @override |
| 191 | + */ |
| 192 | + async receiveReminder(state: any): Promise<void> { |
| 193 | + // handle stuff here |
| 194 | + } |
| 195 | + |
| 196 | + // ... |
| 197 | +} |
| 198 | +``` |
| 199 | + |
| 200 | +For a full guide on actors, visit [How-To: Use virtual actors in Dapr]({{< ref howto-actors.md >}}). |
0 commit comments