@niwa-labs/client 0.0.0-stage → 0.0.0
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/LICENSE +21 -0
- package/README.md +4 -2
- package/package.json +11 -4
- package/src/client-types.ts +80 -0
- package/src/client.ts +949 -0
- package/src/holder.ts +58 -0
- package/src/home.ts +11 -0
- package/src/index.ts +10 -0
- package/src/live.ts +141 -0
- package/src/observation.ts +181 -0
- package/src/pause.ts +30 -0
- package/src/token.ts +38 -0
- package/src/wire.ts +315 -0
- package/src/working-directory.ts +28 -0
- package/test/connection-leak.test.ts +17 -0
- package/test/fixtures/owner-token-of.ts +5 -0
- package/test/helpers.ts +54 -0
- package/test/line-decoder.test.ts +37 -0
- package/test/live-cancel.test.ts +24 -0
- package/test/live-feed.test.ts +49 -0
- package/test/no-sqlite.test.ts +79 -0
- package/test/owner-token.test.ts +31 -0
- package/test/query-refused.test.ts +20 -0
- package/test/retry-pause.test.ts +19 -0
- package/test/write-failure.test.ts +54 -0
- package/tsconfig.json +6 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Niwa Labs contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @niwa-labs/client
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The wire protocol, the client and the live record stream, plus the owner token and the probe for the
|
|
4
|
+
process that holds a home. It imports only the contracts of core and does not load the database
|
|
5
|
+
driver until the holder probe runs.
|
package/package.json
CHANGED
|
@@ -1,6 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@niwa-labs/client",
|
|
3
|
-
"version": "0.0.0
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"license": "MIT",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"exports": {
|
|
7
|
+
".": "./src/index.ts"
|
|
8
|
+
},
|
|
9
|
+
"dependencies": {
|
|
10
|
+
"@niwa-labs/core": "0.0.0",
|
|
11
|
+
"zod": "^4.6.7"
|
|
12
|
+
}
|
|
13
|
+
}
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
// The API a client holds: the shape the host and a connected client share.
|
|
2
|
+
import type { ActionTarget, CallOptions, Description, EmitBatch, EmitOptions, LiveFrame, RecordReadQuery, RecordId, RecordQuery, RecordType, StoredRecord, TracedRecord } from "@niwa-labs/core";
|
|
3
|
+
|
|
4
|
+
/** The frames of one channel, from the moment the host registered the listener. */
|
|
5
|
+
export interface LiveSubscription extends AsyncIterableIterator<LiveFrame> {
|
|
6
|
+
/**
|
|
7
|
+
* Resolves once the host has registered the listener: a frame sent after this is received. It
|
|
8
|
+
* rejects when the subscription ended before the host answered. Returning from the iterator
|
|
9
|
+
* ends the subscription, even while a read waits on a quiet channel.
|
|
10
|
+
*/
|
|
11
|
+
readonly ready: Promise<void>;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
/** The records that answer a query, history then live. */
|
|
15
|
+
export interface RecordFeed extends AsyncIterable<StoredRecord> {
|
|
16
|
+
/**
|
|
17
|
+
* Resolves once the host has accepted the subscription: it holds the query's reader and its position, and it was not
|
|
18
|
+
* refused. A grant that does not let the connection read the journal rejects it with the host's refusal, before any
|
|
19
|
+
* record. The answer does not wait for a first record, so it comes on an empty journal as well. Asking for it opens the
|
|
20
|
+
* subscription when no record was read yet. Absent in an implementation that has no step between the call and the
|
|
21
|
+
* subscription to wait for.
|
|
22
|
+
*/
|
|
23
|
+
readonly ready?: Promise<void>;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** The API shared by the host and a client. */
|
|
27
|
+
export interface NiwaApi {
|
|
28
|
+
/**
|
|
29
|
+
* Write an external input. It starts its own chain: root = its own id, cause = null.
|
|
30
|
+
*
|
|
31
|
+
* With an explicit id the write is idempotent: the same id with the same content returns the
|
|
32
|
+
* existing record, the same id with different content is an integrity error.
|
|
33
|
+
*/
|
|
34
|
+
emit<T>(type: RecordType<T>, data: T, opts?: EmitOptions): Promise<StoredRecord>;
|
|
35
|
+
emitAll<const T extends readonly RecordType<any>[]>(entries: EmitBatch<T, EmitOptions>): Promise<StoredRecord[]>;
|
|
36
|
+
/**
|
|
37
|
+
* Call an action by typed reference, by value or by name, outside any invocation.
|
|
38
|
+
*
|
|
39
|
+
* With a reference or an action the input is checked against the action's own input type, and the
|
|
40
|
+
* result has its output type: `I` is taken from the reference alone (`NoInfer`), so a wrong field
|
|
41
|
+
* in the input is an error and not a new type. With a bare name nothing is known and both are
|
|
42
|
+
* unknown.
|
|
43
|
+
*
|
|
44
|
+
* The input is what the schema accepts, not what it produces: a branded or transformed field is
|
|
45
|
+
* given as it is written down, and the schema does the rest.
|
|
46
|
+
*/
|
|
47
|
+
call<I, O, In = I>(action: ActionTarget<I, O, In>, input: NoInfer<In>, opts?: CallOptions): Promise<O>;
|
|
48
|
+
/** What niwa is: its actions and its record types, with their schemas. */
|
|
49
|
+
describe(): Promise<Description>;
|
|
50
|
+
/** The live stream: frames that are not recorded. */
|
|
51
|
+
live: {
|
|
52
|
+
/** Send a frame on a channel. A frame that nobody receives is simply lost. */
|
|
53
|
+
send(channel: string, frame: LiveFrame): Promise<void>;
|
|
54
|
+
/** The frames of a channel, from now on. Never ends by itself; `ready` says when it is listening. */
|
|
55
|
+
subscribe(channel: string): LiveSubscription;
|
|
56
|
+
};
|
|
57
|
+
/**
|
|
58
|
+
* Everything that grew from a record: down through causes and links, depth-first, each record
|
|
59
|
+
* once, with the depth it was found at.
|
|
60
|
+
*/
|
|
61
|
+
trace(id: RecordId): Promise<TracedRecord[]>;
|
|
62
|
+
/** What a record depends on: up through its cause and its links. */
|
|
63
|
+
causes(id: RecordId): Promise<StoredRecord[]>;
|
|
64
|
+
records: {
|
|
65
|
+
/**
|
|
66
|
+
* The records that answer a query, history then live, no gap, no duplicate: the same records a
|
|
67
|
+
* read of the query gives, and then the ones committed later. Never ends by itself.
|
|
68
|
+
*/
|
|
69
|
+
since(query?: RecordQuery<any>): RecordFeed;
|
|
70
|
+
/**
|
|
71
|
+
* The history after a position, read once: the records that are committed now, and nothing
|
|
72
|
+
* that comes later.
|
|
73
|
+
*
|
|
74
|
+
* Unlike `since`, this read ends: it answers with the records that exist at the moment it is
|
|
75
|
+
* made, so a reader never waits for a stream that has no end.
|
|
76
|
+
*/
|
|
77
|
+
read(query?: RecordReadQuery<any>): Promise<StoredRecord[]>;
|
|
78
|
+
};
|
|
79
|
+
close(): Promise<void>;
|
|
80
|
+
}
|