Skip to content

Commit 14d6243

Browse files
XavierGeerinckXavierGeerinck
authored
Merge pull request #108 from greenie-msft/add_actors_docs
Add actors docs
2 parents 1e23f32 + c9a20c0 commit 14d6243

File tree

2 files changed

+178
-26
lines changed

2 files changed

+178
-26
lines changed

‎daprdocs/content/en/js-sdk-docs/_index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,13 +18,13 @@ The Dapr JS SDK will allow you to interface with the Dapr process that abstracts
1818
<a href="{{< ref js-client >}}" class="stretched-link"></a>
1919
</div>
2020
</div>
21-
<!-- <div class="card">
21+
<div class="card">
2222
<div class="card-body">
2323
<h5 class="card-title"><b>Actors</b></h5>
2424
<p class="card-text">Create virtual actors with state, reminders/timers, and methods in JavaScript.</p>
2525
<a href="{{< ref js-actors >}}" class="stretched-link"></a>
2626
</div>
27-
</div> -->
27+
</div>
2828
<div class="card">
2929
<div class="card-body">
3030
<h5 class="card-title"><b>Examples</b></h5>

‎daprdocs/content/en/js-sdk-docs/js-actors/_index.md‎

Lines changed: 176 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,171 @@
1-
<!-- ---
1+
---
22
type: docs
3-
# title: "JavaScript SDK for Actors"
3+
title: "JavaScript SDK for Actors"
44
linkTitle: "Actors"
55
weight: 1000
6-
description: JavaScript SDK package for Actors
6+
description: How to get up and running with Actors using the Dapr JavaScript SDK
77
---
88

9-
### Actors
9+
The Dapr actors package allows you to interact with Dapr virtual actors from a JavaScript application. The below examples demonstarte how to use the JavaScript SDK for interacting with virtual actors.
10+
11+
For a more in-depth overview of Dapr actors and supported scenarios, 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/) d
17+
- [JavaScript NPM package installed](https://www.npmjs.com/package/dapr-client)
18+
19+
## Actor Interface
20+
The actor interface defines the contract that is shared between the actor implementation and the clients calling the actor.
21+
22+
```javascript
23+
export default interface ActorSayInterface {
24+
say(msg: string): string;
25+
}
26+
```
27+
28+
## Actor Implementation
29+
An actor implementation defines a class by extending the base type `AbstractActor` and implements the interfaces defined in the actor interface.
30+
31+
```javascript
32+
import { AbstractActor } from "dapr-client";
33+
import ActorSayInterface from "./ActorSayInterface";
34+
35+
export default class ActorSayImp extends AbstractActor implements ActorSayInterface {
36+
say(msg: string): string {
37+
return `Actor said: "${msg}"`;
38+
}
39+
}
40+
```
41+
42+
## Invoking Actors
43+
Use the DaprServer package to create your actors bindings, which will initalize and register your actors. After Actors are registered, use the DaprClient to invoke methods on an actor. The will client call the actor methods defined in the actor interface.
44+
45+
```javascript
46+
import { DaprServer, DaprClient } from "dapr-client";
47+
import ActorSayImp from "./actor/ActorSayImp";
48+
49+
const daprHost = "127.0.0.1";
50+
const daprPort = "50000"; // Dapr Sidecar Port of this Example Server
51+
const serverHost = "127.0.0.1"; // App Host of this Example Server
52+
const serverPort = "50001"; // App Port of this Example Server
53+
54+
async function start() {
55+
const server = new DaprServer(serverHost, serverPort, daprHost, daprPort);
56+
const client = new DaprClient(daprHost, daprPort);
57+
58+
// Creating actor bindings
59+
await server.actor.init();
60+
server.actor.registerActor(ActorSayImp);
61+
62+
const actorId = "actor-id";
63+
const timerId = "actor-timer-id";
64+
65+
await server.startServer();
66+
67+
// Invoke method 'say' with msg 'Hello World'");
68+
const resActorInvokeSay = await client.actor.invoke("PUT", ActorSayImp.name, actorId, "method-to-invoke", "Hello World");
69+
}
70+
```
71+
72+
## Saving and Getting State
73+
74+
```javascript
75+
import { DaprServer, DaprClient } from "dapr-client";
76+
import StateActor from "./actor/StateActor";
77+
78+
const daprHost = "127.0.0.1";
79+
const daprPort = "50000"; // Dapr Sidecar Port of this Example Server
80+
const serverHost = "127.0.0.1"; // App Host of this Example Server
81+
const serverPort = "50001"; // App Port of this Example Server
82+
83+
async function start() {
84+
const server = new DaprServer(serverHost, serverPort, daprHost, daprPort);
85+
const client = new DaprClient(daprHost, daprPort);
86+
87+
// Creating actor bindings
88+
await server.actor.init();
89+
server.actor.registerActor(StateActor);
90+
await server.startServer();
91+
92+
const actorId = "actor-id";
93+
94+
await client.actor.stateTransaction("StateActor", actorId, [
95+
{
96+
operation: "upsert",
97+
request: {
98+
key: "first-key",
99+
value: "hello"
100+
}
101+
},
102+
{
103+
operation: "upsert",
104+
request: {
105+
key: "second-key",
106+
value: "world"
107+
}
108+
},
109+
{
110+
operation: "delete",
111+
request: {
112+
key: "second-key"
113+
}
114+
}
115+
]);
116+
117+
const ActorStateGet = await client.actor.stateGet("StateActor", actorId, "first-key");
118+
}
119+
```
120+
121+
## Actor Timers and Reminders
122+
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 is not retaining any information about timers after deactivation, while persisting the information about reminders using the Dapr actor state provider.
123+
124+
This distintcion allows users to trade off between light-weight but stateless timers vs. more resource-demanding but stateful reminders.
125+
126+
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" >}}).
127+
128+
### Actor Timers
129+
```javascript
130+
import { DaprServer, DaprClient } from "dapr-client";
131+
import ActorTimerImpl from "./actor/ActorTimerImpl";
132+
133+
const daprHost = "127.0.0.1";
134+
const daprPort = "50000"; // Dapr Sidecar Port of this Example Server
135+
const serverHost = "127.0.0.1"; // App Host of this Example Server
136+
const serverPort = "50001"; // App Port of this Example Server
137+
138+
async function start() {
139+
const server = new DaprServer(serverHost, serverPort, daprHost, daprPort);
140+
const client = new DaprClient(daprHost, daprPort);
10141

142+
// Creating actor bindings
143+
await server.actor.init();
144+
server.actor.registerActor(ActorTimerImpl);
145+
await server.startServer();
146+
147+
const actorId = "actor-id";
148+
const timerId = "actor-timer-id";
149+
150+
// Activate actor
151+
await client.actor.invoke("PUT", ActorTimerImpl.name, actorId, "init");
152+
153+
// Register a timer
154+
await client.actor.timerCreate(ActorTimerImpl.name, actorId, timerId, {
155+
callback: "method-to-excute-on-actor",
156+
dueTime: Temporal.Duration.from({ seconds: 2 }),
157+
period: Temporal.Duration.from({ seconds: 1 })
158+
});
159+
160+
// Delete the timer
161+
await client.actor.timerDelete(ActorTimerImpl.name, actorId, timerId);
162+
}
163+
```
164+
165+
### Actor Reminders
11166
```javascript
12-
import { DaprServer, DaprClient, HttpMethod } from "dapr-client";
13-
import DemoActorCounterImpl from "./actor/DemoActorCounterImpl";
14-
import DemoActorReminderImpl from "./actor/DemoActorReminderImpl";
15-
import DemoActorSayImpl from "./actor/DemoActorSayImpl";
16-
import DemoActorTimerImpl from "./actor/DemoActorTimerImpl";
167+
import { DaprServer, DaprClient } from "dapr-client";
168+
import ActorReminderImpl from "./actor/ActorReminderImpl";
17169

18170
const daprHost = "127.0.0.1";
19171
const daprPort = "50000"; // Dapr Sidecar Port of this Example Server
@@ -26,24 +178,24 @@ async function start() {
26178

27179
// Creating actor bindings
28180
await server.actor.init();
29-
server.actor.registerActor(DemoActorCounterImpl);
30-
server.actor.registerActor(DemoActorSayImpl);
31-
server.actor.registerActor(DemoActorTimerImpl);
32-
server.actor.registerActor(DemoActorReminderImpl);
33-
34-
// We initialize after registering our listeners since these should be defined upfront
35-
// this is how Dapr works, it waits until we are listening on the port. Once that is detected
36-
// it will scan the binding list and pubsub subscriptions list to process
181+
server.actor.registerActor(ActorReminderImpl);
37182
await server.startServer();
38183

39-
console.log("===============================================================");
40-
console.log("EXECUTING CLIENT - ACTORS");
41-
console.log("Note: we create new client for now since Actors are not supported internally!")
42-
console.log("===============================================================");
184+
const actorId = "actor-id";
185+
const reminderId = "actor-timer-id";
186+
187+
// Activate our actor
188+
await client.actor.invoke("PUT", ActorReminderImpl.name, actorId, "init");
43189

190+
// Register a reminder, it has a default callback
191+
await client.actor.reminderCreate(ActorReminderImpl.name, actorId, reminderId, {
192+
dueTime: Temporal.Duration.from({ seconds: 2 }),
193+
period: Temporal.Duration.from({ seconds: 1 }),
194+
data: 100
195+
});
44196

45-
const resRegisteredActors = await server.actor.getRegisteredActors();
46-
console.log(`Registered Actor Types: ${JSON.stringify(resRegisteredActors)}`);
197+
// Delete the reminder
198+
await client.actor.reminderDelete(ActorReminderImpl.name, actorId, reminderId);
47199
```
48200
49-
- For a full guide on actors visit [How-To: Use virtual actors in Dapr]({{< ref howto-actors.md >}}). -->
201+
- For a full guide on actors visit [How-To: Use virtual actors in Dapr]({{< ref howto-actors.md >}}).

0 commit comments

Comments
 (0)