iii-browser-sdk 0.11.5-next.1 → 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.
Files changed (2) hide show
  1. package/README.md +33 -49
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,7 +1,3 @@
1
- [![iii](https://iii.dev/og-image.png)](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 a **first-class iii worker**:
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://localhost:49135')
34
+ const iii = registerWorker('ws://remotehost:3111')
33
35
 
34
- iii.registerFunction(
35
- 'ui::show-notification',
36
- async (data: { title: string; body: string }) => {
37
- showToast(data.title, data.body)
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 | Description |
51
- | ------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------ |
52
- | Initialize | `registerWorker(url, options?)` | Connect to the engine via browser WebSocket. Returns `ISdk` |
53
- | Register function | `iii.registerFunction(id, handler, options?)` | Register a function the engine (or backend) can invoke |
54
- | Register trigger | `iii.registerTrigger({ type, function_id, config })` | Bind a trigger to a function |
55
- | Invoke (await) | `await iii.trigger({ function_id, payload })` | Invoke a function and wait for the result |
56
- | Invoke (fire-and-forget) | `iii.trigger({ function_id, payload, action: TriggerAction.Void() })` | Invoke without waiting |
57
- | Create channel | `iii.createChannel()` | Create a streaming channel pair (writer + reader) |
58
- | Shutdown | `iii.shutdown()` | Gracefully disconnect from the engine |
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
- 'ui::show-notification',
69
- async (data: { title: string; body: string }) => {
70
- showToast(data.title, data.body)
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
- 'ui::update-dashboard',
94
- async (metrics: { cpu: number; memory: number; requests: number }) => {
95
- document.getElementById('cpu')!.textContent = `${metrics.cpu}%`
96
- document.getElementById('memory')!.textContent = `${metrics.memory}MB`
97
- document.getElementById('requests')!.textContent = `${metrics.requests}/s`
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)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "iii-browser-sdk",
3
- "version": "0.11.5-next.1",
3
+ "version": "0.11.6-next.1",
4
4
  "private": false,
5
5
  "publishConfig": {
6
6
  "access": "public"