iii-browser-sdk 0.11.5 → 0.11.6-next.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +33 -49
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,7 +1,3 @@
|
|
|
1
|
-
[](https://iii.dev)
|
|
2
|
-
|
|
3
|
-
This is an SDK for [iii](https://iii.dev) — unreasonably simple backend development.
|
|
4
|
-
|
|
5
1
|
# iii-browser-sdk
|
|
6
2
|
|
|
7
3
|
Browser SDK for the [iii engine](https://github.com/iii-hq/iii) — WebSocket-based, no Node.js dependencies, no OpenTelemetry.
|
|
@@ -11,10 +7,10 @@ Browser SDK for the [iii engine](https://github.com/iii-hq/iii) — WebSocket-ba
|
|
|
11
7
|
|
|
12
8
|
## Why the browser SDK
|
|
13
9
|
|
|
14
|
-
The browser SDK turns your frontend into
|
|
10
|
+
The browser SDK turns your frontend into an iii Worker enabling:
|
|
15
11
|
|
|
16
12
|
- **Persistent connection** — one WebSocket replaces many HTTP round-trips.
|
|
17
|
-
- **Bi-directional** — the engine can invoke functions registered in the browser. Backend workers push data to the frontend with `trigger()`, enabling real-time patterns without polling.
|
|
13
|
+
- **Bi-directional communication** — the engine can invoke functions registered in the browser. Backend workers push data to the frontend with `trigger()`, enabling real-time patterns without polling.
|
|
18
14
|
- **Same API** — `registerFunction`, `trigger`, `registerTrigger` — all the primitives you use server-side work identically in the browser.
|
|
19
15
|
- **Zero Node.js dependencies** — runs in any browser environment with native `WebSocket`.
|
|
20
16
|
|
|
@@ -24,20 +20,23 @@ The browser SDK turns your frontend into a **first-class iii worker**:
|
|
|
24
20
|
npm install iii-browser-sdk
|
|
25
21
|
```
|
|
26
22
|
|
|
23
|
+
## Add iii-worker-manager
|
|
24
|
+
|
|
25
|
+
For the iii instance run: `iii worker add iii-worker-manager` to connect workers that run on untrusted clients like a user's browser.
|
|
26
|
+
|
|
27
|
+
Refer to the [iii-worker-manager](https://workers.iii.dev/workers/iii-worker-manager) documentation for more information.
|
|
28
|
+
|
|
27
29
|
## Hello World
|
|
28
30
|
|
|
29
31
|
```typescript
|
|
30
32
|
import { registerWorker } from 'iii-browser-sdk'
|
|
31
33
|
|
|
32
|
-
const iii = registerWorker('ws://
|
|
34
|
+
const iii = registerWorker('ws://remotehost:3111')
|
|
33
35
|
|
|
34
|
-
iii.registerFunction(
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
return { displayed: true }
|
|
39
|
-
},
|
|
40
|
-
)
|
|
36
|
+
iii.registerFunction('ui::show-notification', async (data: { title: string; body: string }) => {
|
|
37
|
+
showToast(data.title, data.body)
|
|
38
|
+
return { displayed: true }
|
|
39
|
+
})
|
|
41
40
|
|
|
42
41
|
const users = await iii.trigger({
|
|
43
42
|
function_id: 'api::get::users',
|
|
@@ -47,30 +46,26 @@ const users = await iii.trigger({
|
|
|
47
46
|
|
|
48
47
|
## API
|
|
49
48
|
|
|
50
|
-
| Operation | Signature
|
|
51
|
-
| ------------------------ |
|
|
52
|
-
| Initialize | `registerWorker(url, options?)`
|
|
53
|
-
| Register function | `iii.registerFunction(id, handler, options?)`
|
|
54
|
-
| Register trigger | `iii.registerTrigger({ type, function_id, config })`
|
|
55
|
-
| Invoke (await) | `await iii.trigger({ function_id, payload })`
|
|
56
|
-
| Invoke (fire-and-forget) | `iii.trigger({ function_id, payload, action: TriggerAction.Void() })`
|
|
57
|
-
|
|
|
58
|
-
|
|
|
59
|
-
|
|
60
|
-
For listing workers, functions, triggers, or subscribing to function availability events, see the [discovery concepts](https://iii.dev/docs/primitives-and-concepts/discovery).
|
|
49
|
+
| Operation | Signature | Description |
|
|
50
|
+
| ------------------------ | --------------------------------------------------------------------------------- | ----------------------------------------------------------- |
|
|
51
|
+
| Initialize | `registerWorker(url, options?)` | Connect to the engine via browser WebSocket. Returns `ISdk` |
|
|
52
|
+
| Register function | `iii.registerFunction(id, handler, options?)` | Register a function the engine (or backend) can invoke |
|
|
53
|
+
| Register trigger | `iii.registerTrigger({ type, function_id, config })` | Bind a trigger to a function |
|
|
54
|
+
| Invoke (await) | `await iii.trigger({ function_id, payload })` | Invoke a function and wait for the result |
|
|
55
|
+
| Invoke (fire-and-forget) | `iii.trigger({ function_id, payload, action: TriggerAction.Void() })` | Invoke without waiting |
|
|
56
|
+
| Invoke (enqueue) | `iii.trigger({ function_id, payload, action: TriggerAction.Enqueue({ queue }) })` | Route invocation through a named queue |
|
|
57
|
+
| Create channel | `iii.createChannel()` | Create a streaming channel pair (writer + reader) |
|
|
58
|
+
| Shutdown | `iii.shutdown()` | Gracefully disconnect from the engine |
|
|
61
59
|
|
|
62
60
|
### Registering Functions
|
|
63
61
|
|
|
64
62
|
Register a function in the browser that backend workers can call:
|
|
65
63
|
|
|
66
64
|
```typescript
|
|
67
|
-
iii.registerFunction(
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
return { displayed: true }
|
|
72
|
-
},
|
|
73
|
-
)
|
|
65
|
+
iii.registerFunction('ui::show-notification', async (data: { title: string; body: string }) => {
|
|
66
|
+
showToast(data.title, data.body)
|
|
67
|
+
return { displayed: true }
|
|
68
|
+
})
|
|
74
69
|
```
|
|
75
70
|
|
|
76
71
|
### Calling Backend Functions
|
|
@@ -89,25 +84,14 @@ const users = await iii.trigger({
|
|
|
89
84
|
Backend workers can push data to the browser in real time. No polling required:
|
|
90
85
|
|
|
91
86
|
```typescript
|
|
92
|
-
iii.registerFunction(
|
|
93
|
-
'
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
return null
|
|
99
|
-
},
|
|
100
|
-
)
|
|
87
|
+
iii.registerFunction('ui::update-dashboard', async (metrics: { cpu: number; memory: number; requests: number }) => {
|
|
88
|
+
document.getElementById('cpu')!.textContent = `${metrics.cpu}%`
|
|
89
|
+
document.getElementById('memory')!.textContent = `${metrics.memory}MB`
|
|
90
|
+
document.getElementById('requests')!.textContent = `${metrics.requests}/s`
|
|
91
|
+
return null
|
|
92
|
+
})
|
|
101
93
|
```
|
|
102
94
|
|
|
103
|
-
## Exports
|
|
104
|
-
|
|
105
|
-
| Import | What it provides |
|
|
106
|
-
| ------------------------ | ------------------------------------- |
|
|
107
|
-
| `iii-browser-sdk` | Core SDK (`registerWorker`, types) |
|
|
108
|
-
| `iii-browser-sdk/stream` | Stream types for real-time state |
|
|
109
|
-
| `iii-browser-sdk/state` | State types for key-value operations |
|
|
110
|
-
|
|
111
95
|
## Resources
|
|
112
96
|
|
|
113
97
|
- [Documentation](https://iii.dev/docs)
|