@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 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
- # Temporary Holding Version
1
+ # @niwa-labs/client
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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
+ }