Skip to content

Commit e4f8245

Browse files
XavierGeerinckXavierGeerinck
authored
Merge pull request #256 from XavierGeerinck/issue_223
Rename dapr-client to @dapr/dapr
2 parents b827da6 + 2da4bd8 commit e4f8245

File tree

40 files changed

+11439
-11296
lines changed

40 files changed

+11439
-11296
lines changed

‎.github/workflows/build.yml‎

Lines changed: 25 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,7 @@
1010
# See the License for the specific language governing permissions and
1111
# limitations under the License.
1212
#
13-
14-
name: Node.js CI
13+
name: Build
1514

1615
on:
1716
push:
@@ -20,30 +19,27 @@ on:
2019
- release-*
2120
tags:
2221
- v*
23-
pull_request:
24-
branches:
25-
- master
26-
- release-*
2722

2823
jobs:
2924
build:
3025
runs-on: ubuntu-latest
26+
environment: production
3127
env:
3228
NODE_VER: 16.14.0
3329
steps:
34-
- uses: actions/checkout@v2
30+
- uses: actions/checkout@v3
3531

3632
# Setup .npmrc file to publish to npm
37-
# https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
38-
- name: Use Node.js
39-
uses: actions/setup-node@v2
33+
- name: Configure .npmrc for NPM publish to @dapr
34+
uses: actions/setup-node@v3
4035
with:
4136
node-version: ${{ env.NODE_VER }}
4237
registry-url: 'https://registry.npmjs.org'
4338

4439
- name: Build Package
4540
run: ./scripts/build.sh
4641

42+
# @TODO: add a depend on the test-e2e pipeline?
4743
- name: Run unit tests
4844
id: tests
4945
run: npm run test:unit:all
@@ -54,9 +50,25 @@ jobs:
5450
- name: Is Release?
5551
if: startswith(github.ref, 'refs/tags/v')
5652
run: echo "DEPLOY_PACKAGE=true" >> $GITHUB_ENV
57-
58-
- name: Publish to npm
53+
54+
# note: package.json gets updated here for the new package name
55+
- name: Publish to npm (@dapr/dapr)
5956
if: env.DEPLOY_PACKAGE == 'true'
60-
run: npm run build && npm pack && npm publish build/ --access public
57+
run: npm publish --access public
6158
env:
6259
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
60+
61+
- name: "[dapr-client] Configure to publish to dapr-client for deprecation notice reasons"
62+
if: env.DEPLOY_PACKAGE == 'true'
63+
run: sed -i s#"@dapr/dapr"#"dapr-client"# package.json
64+
65+
- name: "[dapr-client] Build Package"
66+
if: env.DEPLOY_PACKAGE == 'true'
67+
run: ./scripts/build.sh
68+
69+
# note: package.json gets updated here for the new package name
70+
- name: "[dapr-client] Publish to npm (dapr-client)"
71+
if: env.DEPLOY_PACKAGE == 'true'
72+
run: npm publish --access public
73+
env:
74+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ spec:
4545
**example.ts**
4646
4747
```javascript
48-
import { DaprClient, DaprServer } from "dapr-client";
48+
import { DaprClient, DaprServer } from "@dapr/dapr";
4949

5050
const daprHost = "127.0.0.1"; // Dapr Sidecar Host
5151
const daprPort = "50000"; // Dapr Sidecar Port

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

Lines changed: 188 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -3,68 +3,198 @@ type: docs
33
title: "JavaScript SDK"
44
linkTitle: "JavaScript"
55
weight: 1000
6-
description: JavaScript SDK packages for developing Dapr applications
7-
no_list: true
6+
description: How to get up and running with Actors using the Dapr JavaScript SDK
87
---
98

10-
The Dapr JS SDK will allow you to interface with the Dapr process that abstracts several commonly used functionalities such as Service-to-Service invocation, State Management, PubSub, and more.
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.
1110

12-
## Installation
11+
For a more in-depth overview of Dapr actors, visit the [actors overview page]({{< ref actors-overview >}}).
1312

14-
To get started with the Javascript SDK, you can download the Dapr Javascript SDK package from [NPM](https://npmjs.org/package/dapr-client) by running the following:
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)
1518

16-
```bash
17-
npm install --save dapr-client
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+
}
18198
```
19199

20-
## Structure
21-
22-
The Dapr Javascript SDK contains two major components:
23-
24-
* **DaprServer:** The Dapr Server manages all communication from the Dapr Sidecar to your application
25-
* **DaprClient:** The Dapr Client manages all communication from your application to the Dapr Sidecar
26-
27-
The above communication can be configured to use either of the gRPC or HTTP protocols.
28-
29-
![Dapr Server](./js-server/dapr-server.jpg)
30-
![Dapr Client](./js-client/dapr-client.jpg)
31-
32-
## Get Started
33-
34-
To help you get started, check out the resources below:
35-
36-
<div class="card-deck">
37-
<div class="card">
38-
<div class="card-body">
39-
<h5 class="card-title"><b>Client</b></h5>
40-
<p class="card-text">Create a JavaScript client and interact with a Dapr sidecar and other Dapr applications. (e.g., publishing events, output binding support, etc.)</p>
41-
<a href="{{< ref js-client >}}" class="stretched-link"></a>
42-
</div>
43-
</div>
44-
<div class="card">
45-
<div class="card-body">
46-
<h5 class="card-title"><b>Server</b></h5>
47-
<p class="card-text">Create a JavaScript server and let the Dapr sidecar interact with your application. (e.g., subscribing to events, input binding support, etc.)</p>
48-
<a href="{{< ref js-server >}}" class="stretched-link"></a>
49-
</div>
50-
</div>
51-
<div class="card">
52-
<div class="card-body">
53-
<h5 class="card-title"><b>Actors</b></h5>
54-
<p class="card-text">Create virtual actors with state, reminders/timers, and methods in JavaScript.</p>
55-
<a href="{{< ref js-actors >}}" class="stretched-link"></a>
56-
</div>
57-
</div>
58-
<div class="card">
59-
<div class="card-body">
60-
<h5 class="card-title"><b>Examples</b></h5>
61-
<p class="card-text">Clone the JavaScript SDK repo and try out some of the examples and get started quickly.</p>
62-
<a href="https://github.com/dapr/js-sdk/blob/master/documentation/examples.md" class="stretched-link"></a>
63-
</div>
64-
</div>
65-
</div>
66-
67-
### Available packages
68-
- [DaprClient]({{< ref "js-client#installing-and-importing-daprs-js-sdk" >}}) is a package that for how your application interacts with the Dapr sidecar, or other Dapr powered applications.
69-
70-
- [DaprServer]({{< ref "js-client#installing-and-importing-daprs-js-sdk" >}}) is a package for how the Dapr sidecar interacts with your application, forwarding event subscriptions, invokes and more.
200+
For a full guide on actors, visit [How-To: Use virtual actors in Dapr]({{< ref howto-actors.md >}}).

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ For a more in-depth overview of Dapr actors, visit the [actors overview page]({{
1414
- [Dapr CLI]({{< ref install-dapr-cli.md >}}) installed
1515
- Initialized [Dapr environment]({{< ref install-dapr-selfhost.md >}})
1616
- [Latest LTS version of Node or greater](https://nodejs.org/en/)
17-
- [JavaScript NPM package installed](https://www.npmjs.com/package/dapr-client)
17+
- [JavaScript NPM package installed](https://www.npmjs.com/package/@dapr/dapr)
1818

1919
## Scenario
2020
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.
@@ -39,7 +39,7 @@ An actor implementation defines a class by extending the base type `AbstractActo
3939
The following code describes an actor implementation along with a few helper methods.
4040

4141
```ts
42-
import { AbstractActor } from "dapr-client";
42+
import { AbstractActor } from "@dapr/dapr";
4343
import ParkingSensorInterface from "./ParkingSensorInterface";
4444

4545
export default class ParkingSensorImpl extends AbstractActor implements ParkingSensorInterface {
@@ -68,7 +68,7 @@ export default class ParkingSensorImpl extends AbstractActor implements ParkingS
6868
Initialize and register your actors by using the `DaprServer` package:
6969

7070
```javascript
71-
import { DaprServer } from "dapr-client";
71+
import { DaprServer } from "@dapr/dapr";
7272
import ParkingSensorImpl from "./ParkingSensorImpl";
7373

7474
const daprHost = "127.0.0.1";
@@ -91,7 +91,7 @@ console.log(`Registered Actors: ${JSON.stringify(resRegisteredActors)}`);
9191
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.
9292

9393
```javascript
94-
import { DaprClient, ActorId } from "dapr-client";
94+
import { DaprClient, ActorId } from "@dapr/dapr";
9595
import ParkingSensorImpl from "./ParkingSensorImpl";
9696
import ParkingSensorInterface from "./ParkingSensorInterface";
9797

0 commit comments

Comments
 (0)