Skip to content

Commit 1e23f32

Browse files
XavierGeerinckXavierGeerinck
authored
Merge pull request #103 from greenie-msft/add_dapr_docs
Add dapr docs
2 parents 29ad3fe + a785327 commit 1e23f32

File tree

5 files changed

+377
-0
lines changed

5 files changed

+377
-0
lines changed

‎daprdocs/README.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Dapr JavaScript SDK documentation
2+
3+
This page covers how the documentation is structured for the Dapr JavaScript SDK
4+
5+
## Dapr Docs
6+
7+
All Dapr documentation is hosted at [docs.dapr.io](https://docs.dapr.io), including the docs for the [JavaScript SDK](https://docs.dapr.io/developing-applications/sdks/javascript/). Head over there if you want to read the docs.
8+
9+
### JavaScript SDK docs source
10+
11+
Although the docs site code and content is in the [docs repo](https://github.com/dapr/docs), the JavaScript SDK content and images are within the `content` and `static` directories, respectively.
12+
13+
This allows separation of roles and expertise between maintainers, and makes it easy to find the docs files you are looking for.
14+
15+
## Writing JavaScript SDK docs
16+
17+
To get up and running to write JavaScript SDK docs, visit the [docs repo](https://github.com/dapr/docs) to initialize your environment. It will clone both the docs repo and this repo, so you can make changes and see it rendered within the site instantly, as well as commit and PR into this repo.
18+
19+
Make sure to read the [docs contributing guide](https://docs.dapr.io/contributing/contributing-docs/) for information on style/semantics/etc.
20+
21+
## Docs architecture
22+
23+
The docs site is built on [Hugo](https://gohugo.io), which lives in the docs repo. This repo is setup as a git submodule so that when the repo is cloned and initialized, the javascript-sdk repo, along with the docs, are cloned as well.
24+
25+
Then, in the Hugo configuration file, the `daprdocs/content` and `daprdocs/static` directories are redirected to the `daprdocs/developing-applications/sdks/javascript` and `static/javascript` directories, respectively. Thus, all the content within this repo is folded into the main docs site.

‎daprdocs/content/en/js-sdk-contributing/js-contributing.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
type: docs
3+
title: "Contributing to the JavaScript SDK"
4+
linkTitle: "JavaScript SDK"
5+
weight: 3000
6+
description: Guidelines for contributing to the Dapr JavaScript SDK
7+
---
8+
9+
When contributing to the [JavaScript SDK](https://github.com/dapr/js-sdk) the following rules and best-practices should be followed.
10+
11+
## Examples
12+
13+
The `examples` directory contains code samples for users to run to try out specific functionality of the various JavaScript SDK packages and extensions. When writing new and updated samples keep in mind:
14+
15+
- All examples should be runnable on Windows, Linux, and MacOS. While JavaScript code is consistent among operating systems, any pre/post example commands should provide options through [codetabs]({{< ref "contributing-docs.md#tabbed-content" >}})
16+
- Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine.
17+
18+
## Docs
19+
20+
The `daprdocs` directory contains the markdown files that are rendered into the [Dapr Docs](https://docs.dapr.io) website. When the documentation website is built, this repo is cloned and configured so that its contents are rendered with the docs content. When writing docs, keep in mind:
21+
22+
- All rules in the [docs guide]({{< ref contributing-docs.md >}}) should be followed in addition to these.
23+
- All files and directories should be prefixed with `js-` to ensure all file/directory names are globally unique across all Dapr documentation.

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

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
type: docs
3+
title: "JavaScript SDK"
4+
linkTitle: "JavaScript"
5+
weight: 1000
6+
description: JavaScript SDK packages for developing Dapr applications
7+
no_list: true
8+
---
9+
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.
11+
12+
13+
<div class="card-deck">
14+
<div class="card">
15+
<div class="card-body">
16+
<h5 class="card-title"><b>Client</b></h5>
17+
<p class="card-text">Create a JavaScript client and interact with a Dapr sidecar and other Dapr applications.</p>
18+
<a href="{{< ref js-client >}}" class="stretched-link"></a>
19+
</div>
20+
</div>
21+
<!-- <div class="card">
22+
<div class="card-body">
23+
<h5 class="card-title"><b>Actors</b></h5>
24+
<p class="card-text">Create virtual actors with state, reminders/timers, and methods in JavaScript.</p>
25+
<a href="{{< ref js-actors >}}" class="stretched-link"></a>
26+
</div>
27+
</div> -->
28+
<div class="card">
29+
<div class="card-body">
30+
<h5 class="card-title"><b>Examples</b></h5>
31+
<p class="card-text">Clone the JavaScript SDK repo and try out some of the examples and get started quickly.</p>
32+
<a href="https://github.com/dapr/js-sdk/blob/master/documentation/examples.md" class="stretched-link"></a>
33+
</div>
34+
</div>
35+
</div>
36+
37+
### Available packages
38+
- [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.
39+
40+
- [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.

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

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
<!-- ---
2+
type: docs
3+
# title: "JavaScript SDK for Actors"
4+
linkTitle: "Actors"
5+
weight: 1000
6+
description: JavaScript SDK package for Actors
7+
---
8+
9+
### Actors
10+
11+
```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";
17+
18+
const daprHost = "127.0.0.1";
19+
const daprPort = "50000"; // Dapr Sidecar Port of this Example Server
20+
const serverHost = "127.0.0.1"; // App Host of this Example Server
21+
const serverPort = "50001"; // App Port of this Example Server
22+
23+
async function start() {
24+
const server = new DaprServer(serverHost, serverPort, daprHost, daprPort);
25+
const client = new DaprClient(daprHost, daprPort);
26+
27+
// Creating actor bindings
28+
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
37+
await server.startServer();
38+
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("===============================================================");
43+
44+
45+
const resRegisteredActors = await server.actor.getRegisteredActors();
46+
console.log(`Registered Actor Types: ${JSON.stringify(resRegisteredActors)}`);
47+
```
48+
49+
- 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-client/_index.md‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
---
2+
type: docs
3+
title: "JavaScript Client SDK"
4+
linkTitle: "Client"
5+
weight: 500
6+
description: JavaScript Client SDK for developing Dapr applications
7+
---
8+
9+
## Pre-requisites
10+
11+
- [Dapr CLI]({{< ref install-dapr-cli.md >}}) installed
12+
- Initialized [Dapr environment]({{< ref install-dapr-selfhost.md >}})
13+
- [Latest LTS version of Node or greater](https://nodejs.org/en/)
14+
15+
## Installing and importing Dapr's JS SDK
16+
17+
Install the SDK with npm:
18+
```
19+
npm i dapr-client
20+
```
21+
22+
Import the libraries:
23+
```javascript
24+
import { DaprClient, DaprServer, HttpMethod, CommunicationProtocolEnum } from "dapr-client";
25+
26+
const daprHost = "127.0.0.1"; // Dapr Sidecar Host
27+
const daprPort = "3500"; // Dapr Sidecar Port of this Example Server
28+
const serverHost = "127.0.0.1"; // App Host of this Example Server
29+
const serverPort = "50051"; // App Port of this Example Server
30+
31+
// HTTP
32+
const server = new DaprServer(serverHost, serverPort, daprHost, daprPort);
33+
const client = new DaprClient(daprHost, daprPort);
34+
35+
// GRPC
36+
const server = new DaprServer(serverHost, serverPort, daprHost, daprPort, CommunicationProtocolEnum.GRPC);
37+
const client = new DaprClient(daprHost, daprPort, CommunicationProtocolEnum.GRPC);
38+
```
39+
40+
##### DaprClient Library
41+
A library that provides methods for how an application communicates with the Dapr sidecar.
42+
43+
##### DaprServer Library
44+
A library for how an application registers bindings / routes with Dapr. The `startServer()` method is used to start the server and bind the routes.
45+
46+
## Building blocks
47+
48+
The JavaScript SDK allows you to interface with all of the [Dapr building blocks]({{< ref building-blocks >}}).
49+
50+
### Invoke a service
51+
52+
```javascript
53+
import { DaprClient, HttpMethod, CommunicationProtocolEnum } from "dapr-client";
54+
55+
const daprHost = "127.0.0.1";
56+
const daprPort = "3500";
57+
58+
async function start() {
59+
const client = new DaprClient(daprHost, daprPort, CommunicationProtocolEnum.GRPC);
60+
61+
const serviceAppId = "my-app-id";
62+
const serviceMethod = "say-hello";
63+
64+
// POST Request
65+
const response = await client.invoker.invoke(serviceAppId , serviceMethod , HttpMethod.POST, { hello: "world" });
66+
67+
// GET Request
68+
const response = await client.invoker.invoke(serviceAppId , serviceMethod , HttpMethod.GET);
69+
}
70+
```
71+
- For a full guide on service invocation visit [How-To: Invoke a service]({{< ref howto-invoke-discover-services.md >}}).
72+
73+
### Save, get and delete application state
74+
75+
```javascript
76+
import { DaprClient, CommunicationProtocolEnum } from "dapr-client";
77+
78+
const daprHost = "127.0.0.1";
79+
const daprPort = "3500";
80+
81+
async function start() {
82+
const client = new DaprClient(daprHost, daprPort, CommunicationProtocolEnum.GRPC);
83+
84+
const serviceStoreName = "my-state-store-name";
85+
86+
// Save State
87+
const response = await client.state.save(serviceStoreName, [
88+
{
89+
key: "first-key-name",
90+
value: "hello"
91+
},
92+
{
93+
key: "second-key-name",
94+
value: "world"
95+
}
96+
]);
97+
98+
// Get State
99+
const response = await client.state.get(serviceStoreName, "first-key-name");
100+
101+
// Get Bulk State
102+
const response = await client.state.getBulk(serviceStoreName, ["first-key-name", "second-key-name"]);
103+
104+
// State Transactions
105+
await client.state.transaction(serviceStoreName, [
106+
{
107+
operation: "upsert",
108+
request: {
109+
key: "first-key-name",
110+
value: "new-data"
111+
}
112+
},
113+
{
114+
operation: "delete",
115+
request: {
116+
key: "second-key-name"
117+
}
118+
}
119+
]);
120+
121+
// Delete State
122+
const response = await client.state.delete(serviceStoreName, "first-key-name");
123+
}
124+
```
125+
- For a full list of state operations visit [How-To: Get & save state]({{< ref howto-get-save-state.md >}}).
126+
127+
### Publish & subscribe to messages
128+
129+
##### Publish messages
130+
131+
```javascript
132+
import { DaprClient, CommunicationProtocolEnum } from "dapr-client";
133+
134+
const daprHost = "127.0.0.1";
135+
const daprPort = "3500";
136+
137+
async function start() {
138+
const client = new DaprClient(daprHost, daprPort, CommunicationProtocolEnum.GRPC);
139+
140+
const pubSubName = "my-pubsub-name";
141+
const topic = "topic-a";
142+
const message = { hello: "world" }
143+
144+
// Publish Message to Topic
145+
const response = await client.pubsub.publish(pubSubName, topic, message);
146+
}
147+
```
148+
149+
##### Subscribe to messages
150+
151+
```javascript
152+
import { DaprServer, CommunicationProtocolEnum } from "dapr-client";
153+
154+
const daprHost = "127.0.0.1"; // Dapr Sidecar Host
155+
const daprPort = "3500"; // Dapr Sidecar Port of this Example Server
156+
const serverHost = "127.0.0.1"; // App Host of this Example Server
157+
const serverPort = "50051"; // App Port of this Example Server "
158+
159+
async function start() {
160+
const server = new DaprServer(serverHost, serverPort, daprHost, daprPort, CommunicationProtocolEnum.GRPC);
161+
162+
const pubSubName = "my-pubsub-name";
163+
const topic = "topic-a";
164+
165+
// Configure Subscriber for a Topic
166+
await server.pubsub.subscribe(pubSubName, topic, async (data: any) => console.log(`Got Data: ${JSON.stringify(data)}`));
167+
168+
await server.startServer();
169+
}
170+
```
171+
172+
- For a full list of state operations visit [How-To: Publish & subscribe]({{< ref howto-publish-subscribe.md >}}).
173+
174+
### Interact with bindings
175+
176+
**Output Bindings**
177+
```javascript
178+
import { DaprClient, CommunicationProtocolEnum } from "dapr-client";
179+
180+
const daprHost = "127.0.0.1";
181+
const daprPort = "3500";
182+
183+
async function start() {
184+
const client = new DaprClient(daprHost, daprPort, CommunicationProtocolEnum.GRPC);
185+
186+
const bindingName = "my-binding-name";
187+
const bindingOperation = "create";
188+
const message = { hello: "world" };
189+
190+
const response = await client.binding.send(bindingName, bindingOperation, message);
191+
}
192+
```
193+
194+
**Input Bindings**
195+
```javascript
196+
import { DaprServer, CommunicationProtocolEnum } from "dapr-client";;
197+
198+
const daprHost = "127.0.0.1";
199+
const daprPort = "3500";
200+
const serverHost = "127.0.0.1";
201+
const serverPort = "5051";
202+
203+
async function start() {
204+
const server = new DaprServer(serverHost, serverPort, daprHost, daprPort, CommunicationProtocolEnum.GRPC);;
205+
206+
const bindingName = "my-binding-name";
207+
208+
const response = await server.binding.receive(bindingName, async (data: any) => console.log(`Got Data: ${JSON.stringify(data)}`));
209+
210+
await server.startServer();
211+
}
212+
```
213+
214+
- For a full guide on output bindings visit [How-To: Use bindings]({{< ref howto-bindings.md >}}).
215+
216+
### Retrieve secrets
217+
218+
```javascript
219+
import { DaprClient, CommunicationProtocolEnum } from "dapr-client";
220+
221+
const daprHost = "127.0.0.1";
222+
const daprPort = "3500";
223+
224+
async function start() {
225+
const client = new DaprClient(daprHost, daprPort, CommunicationProtocolEnum.GRPC);
226+
227+
const secretStoreName = "my-secret-store";
228+
const secretKey = "secret-key";
229+
230+
// Retrieve a single secret from secret store
231+
const response = await client.secret.get(secretStoreName, secretKey);
232+
233+
// Retrieve all secrets from secret store
234+
const response = await client.secret.getBulk(secretStoreName);
235+
}
236+
```
237+
- For a full guide on secrets visit [How-To: Retrieve secrets]({{< ref howto-secrets.md >}}).
238+
239+
## Related links
240+
- [JavaScript SDK examples](https://github.com/dapr/js-sdk/tree/master/examples)

0 commit comments

Comments
 (0)