@theritual/hayson-ts-client 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ritual
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# @theritual/hayson-ts-client
+
+Klient TypeScript do `hayson-server`. Wyłącznie tryb zdalny (gRPC przez `@grpc/grpc-js`) — bazę
+osadzoną w procesie obsługuje `@theritual/hayson`.
+
+```ts
+import { HaysonClient } from '@theritual/hayson-ts-client'
+
+const client = await HaysonClient.open('127.0.0.1:50051', '/var/lib/moja-baza')
+
+await client.createTable('users', usersSchema)
+await client.put('users', { id: 'u1', name: 'Ada', role: 'admin' })
+
+const admins = await client.query('users', { where: { field: 'role', op: 'eq', value: 'admin' } })
+for await (const user of client.queryStream('users', { chunkSize: 500 })) report(user)
+
+const unit = await client.beginTransaction()
+await unit.put('users', { id: 'u2', name: 'Bo' })
+await unit.commit()
+
+await client.close()
+```
+
+`HaysonClient.open(address, databaseDir, options?)` łączy się, wysyła `API_VERSION` (ADR-96fd —
+jako metadane `x-hayson-api-version` przy każdym wywołaniu, nie jako pole `Open`) i trzyma
+`clientId` sesji. Serwer mówiący inną wersją odmawia wywołania i podaje swoją wersję w tym samym
+nagłówku — klient zgłasza to jako `HaysonApiVersionError`, czytając nagłówek, nie treść komunikatu. `address` przyjmuje obie formy — `host:port` (to, co wypisuje serwer przy
+starcie) i `http://host:port` — tak samo jak `hayson-rust-client`; `https://` jest odrzucane od razu,
+bo transport nie ma dziś TLS-a. `databaseDir` rozwiązuje **serwer**, nie proces klienta.
+
+**Uwierzytelnienie.** `hayson-server` domyślnie generuje token przy starcie (albo bierze stały
+z `HAYSON_SERVER_TOKEN`) i wymaga go jako `authorization: Bearer <token>` na każdym RPC. Podaj go
+klientowi przez `options.token` — trafia automatycznie do każdego wywołania w tej sesji, nie tylko
+do `open`:
+
+```ts
+const client = await HaysonClient.open('127.0.0.1:50051', '/var/lib/moja-baza', { token })
+```
+
+Brak albo zły token kończy się `HaysonRpcError` z kodem gRPC `UNAUTHENTICATED`, nie cichym zawieszeniem.
+
+Metody odwzorowują `Database`/`Table` silnika: `put`, `patch`, `delete`, `get`, `query`,
+`queryStream`, `aggregate`, `aggregateGrouped`, `beginTransaction`, `createTable`, `dropField`,
+`declareIndex`, `declareTrigger`, `tables`, `describeTable`, `relations`, `checkIntegrity`,
+`compact`, `compactAll`, `checkpoint`, `close`. Każda przyjmuje na końcu `RequestOptions` (`signal`, `deadlineMs`), a metody
+piszące dodatkowo `force`.
+
+Dokumenty i specyfikacje (schema, index, trigger) przechodzą jako zwykłe obiekty JSON w tych samych
+kształtach, które przyjmuje silnik; predykat i agregat są otypowane (`Predicate`, `AggregateQuery`).
+Wszystko, czego nie da się przenieść jako JSON (instancja klasy, `NaN`, `Infinity`), jest odrzucane
+na granicy klienta, zanim ruszy przez drut.
+
+Błędy: `HaysonClientError` i jego podklasy — `HaysonConnectionError`, `HaysonApiVersionError`,
+`HaysonRpcError` (kod gRPC plus komunikat serwera), `HaysonPayloadError`, `HaysonDecodeError`,
+`HaysonClosedError`. Uwaga: `hayson-server` mapuje dziś większość odmów na `INTERNAL`, więc
+rozgałęziaj się po kodzie, nigdy po treści komunikatu.
+
+Kontrakt sieciowy: `proto/hayson.proto` to kopia `crates/hayson-protocol/proto/hayson.proto`,
+ładowana w runtime i pilnowana testem (`test/package.test.ts`) — obie muszą być bajt w bajt
+identyczne.
+
+Testy jadą przeciw prawdziwej binarce serwera: `cargo build -p hayson-server` z katalogu `crates/`,
+potem `pnpm --filter @theritual/hayson-ts-client test:run`.
+
+Plan pracy i otwarte pytania: cerebro `PLAN-6j76`. Decyzja o konwencji wersjonowania: `ADR-26tj`.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@theritual/hayson-ts-client",
+  "version": "2.0.0",
+  "description": "TypeScript client for hayson-server — a remote hayson database over gRPC",
+  "keywords": [
+    "database",
+    "grpc",
+    "client",
+    "hayson"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gl.theritual.eu/ritual/hayson.git",
+    "directory": "packages/hayson-ts-client"
+  },
+  "homepage": "https://gl.theritual.eu/ritual/hayson",
+  "bugs": {
+    "url": "https://gl.theritual.eu/ritual/hayson/-/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "proto",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@types/node": "^24",
+    "typescript": "7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.14.4",
+    "@grpc/proto-loader": "^0.8.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run"
+  }
+}

package/proto/hayson.proto

@@ -0,0 +1,266 @@
+syntax = "proto3";
+
+package hayson;
+
+import "google/protobuf/struct.proto";
+
+// Full RPC surface of hayson-server, per ADR-6b6m. All 25 RPCs below are implemented —
+// none return UNIMPLEMENTED.
+service Hayson {
+  rpc Open(OpenRequest) returns (OpenResponse);
+  rpc Close(CloseRequest) returns (CloseResponse);
+
+  rpc Put(PutRequest) returns (WriteResponse);
+  rpc Patch(PatchRequest) returns (WriteResponse);
+  rpc Delete(DeleteRequest) returns (WriteResponse);
+
+  rpc Get(GetRequest) returns (GetResponse);
+  rpc Query(QueryRequest) returns (stream QueryResultChunk);
+  rpc Aggregate(AggregateRequest) returns (AggregateResponse);
+
+  rpc BeginTransaction(BeginTransactionRequest) returns (TransactionHandle);
+  rpc TxPut(TxWriteRequest) returns (TxWriteResponse);
+  rpc TxPatch(TxWriteRequest) returns (TxWriteResponse);
+  rpc TxDelete(TxWriteRequest) returns (TxWriteResponse);
+  rpc TxQuery(TxQueryRequest) returns (stream QueryResultChunk);
+  rpc CommitTransaction(CommitTransactionRequest) returns (UnitOfWorkResult);
+  rpc RollbackTransaction(TransactionHandle) returns (RollbackResponse);
+
+  rpc CreateTable(CreateTableRequest) returns (Empty);
+  rpc DropField(DropFieldRequest) returns (Empty);
+  rpc DeclareIndex(DeclareIndexRequest) returns (Empty);
+  rpc DeclareTrigger(DeclareTriggerRequest) returns (Empty);
+
+  rpc TableNames(SessionRequest) returns (TableNamesResponse);
+  rpc DescribeTable(DescribeTableRequest) returns (DescribeTableResponse);
+  rpc Relations(RelationsRequest) returns (RelationsResponse);
+  rpc CheckIntegrity(SessionRequest) returns (IntegrityReport);
+  rpc Compact(CompactRequest) returns (CompactResponse);
+  rpc Checkpoint(CheckpointRequest) returns (Empty);
+}
+
+message Empty {}
+
+// A request carrying only the session that already opened a database — no other arguments.
+message SessionRequest {
+  string client_id = 1;
+}
+
+message OpenRequest {
+  // Filesystem path to the database directory, resolved on the server.
+  string database_dir = 1;
+  // Field 2 was `api_version`: the handshake now travels as the `x-hayson-api-version` metadata
+  // key on every request, checked by an interceptor, not as a field of this one message.
+  reserved 2;
+}
+
+message OpenResponse {
+  // Handle for every subsequent RPC on this database session.
+  string client_id = 1;
+  // Field 2 was `api_version` — see OpenRequest. A refusal carries the server's version as
+  // `x-hayson-api-version` metadata on the status instead.
+  reserved 2;
+}
+
+message CloseRequest {
+  string client_id = 1;
+}
+
+message CloseResponse {}
+
+message PutRequest {
+  string client_id = 1;
+  string table = 2;
+  google.protobuf.Struct document = 3;
+  bool force = 4;
+}
+
+message PatchRequest {
+  string client_id = 1;
+  string table = 2;
+  string key = 3;
+  google.protobuf.Struct changes = 4;
+  bool force = 5;
+}
+
+message DeleteRequest {
+  string client_id = 1;
+  string table = 2;
+  string key = 3;
+  bool force = 4;
+}
+
+message WriteResponse {
+  google.protobuf.Struct record = 1;
+}
+
+message GetRequest {
+  string client_id = 1;
+  string table = 2;
+  string key = 3;
+}
+
+message GetResponse {
+  optional google.protobuf.Struct record = 1;
+}
+
+message QueryRequest {
+  string client_id = 1;
+  string table = 2;
+  // A QuerySpec/PredicateNode tree serialized as JSON by serde_json, deserialized server-side —
+  // see the ADR/report for why this repo did not mirror the whole predicate tree in proto.
+  string predicate_json = 3;
+  // Records per streamed chunk; 0 lets the server pick its own default batch size.
+  uint32 chunk_size = 4;
+  // Matches to skip before the first returned record; 0 means no offset.
+  uint32 offset = 5;
+  // Maximum matches to return after the offset. Absent means no limit; a present 0 asks for
+  // no records, the meaning hayson-engine's query planner gives a limit of zero.
+  optional uint32 limit = 6;
+}
+
+message QueryResultChunk {
+  repeated google.protobuf.Struct records = 1;
+}
+
+message AggregateRequest {
+  string client_id = 1;
+  string table = 2;
+  string predicate_json = 3;
+  // count/sum/avg/min/max/group_by, serialized the same way as predicate_json.
+  string aggregate_json = 4;
+}
+
+message AggregateResponse {
+  // AggregateResult or GroupedAggregateResult, serialized as JSON.
+  string result_json = 1;
+}
+
+message BeginTransactionRequest {
+  string client_id = 1;
+}
+
+message TransactionHandle {
+  string transaction_id = 1;
+}
+
+// Commit of a unit of work. `idempotency_key` is what makes the commit retryable: the server
+// remembers the outcome of a recent commit under its key and answers a repeat of that key with
+// the very same outcome instead of applying the unit of work twice.
+message CommitTransactionRequest {
+  string transaction_id = 1;
+  // Client-generated, unique per unit of work. Empty opts out of deduplication: the commit is
+  // applied and answered as it was before this field existed.
+  string idempotency_key = 2;
+}
+
+enum TxOp {
+  TX_OP_UNSPECIFIED = 0;
+  TX_OP_PUT = 1;
+  TX_OP_PATCH = 2;
+  TX_OP_DELETE = 3;
+}
+
+message TxWriteRequest {
+  string transaction_id = 1;
+  string table = 2;
+  TxOp op = 3;
+  // Required for TX_OP_PATCH and TX_OP_DELETE, ignored for TX_OP_PUT.
+  optional string key = 4;
+  // Required for TX_OP_PUT and TX_OP_PATCH.
+  google.protobuf.Struct document = 5;
+  bool force = 6;
+}
+
+message TxWriteResponse {
+  optional google.protobuf.Struct record = 1;
+  // Set only for TX_OP_DELETE — whether the key existed before the delete.
+  optional bool existed = 2;
+}
+
+message TxQueryRequest {
+  string transaction_id = 1;
+  string table = 2;
+  string predicate_json = 3;
+  uint32 chunk_size = 4;
+  // Matches to skip before the first returned record; 0 means no offset.
+  uint32 offset = 5;
+  // Maximum matches to return after the offset. Absent means no limit; a present 0 asks for
+  // no records, the meaning hayson-engine's query planner gives a limit of zero.
+  optional uint32 limit = 6;
+}
+
+message UnitOfWorkResult {
+  uint32 operations = 1;
+}
+
+message RollbackResponse {}
+
+message CreateTableRequest {
+  string client_id = 1;
+  string table = 2;
+  // A TableSchema spec, in the same JSON shape `hayson-engine::schema::parse_schema` accepts.
+  string schema_json = 3;
+}
+
+message DropFieldRequest {
+  string client_id = 1;
+  string table = 2;
+  string field = 3;
+  bool force = 4;
+}
+
+message DeclareIndexRequest {
+  string client_id = 1;
+  string table = 2;
+  string index_json = 3;
+}
+
+message DeclareTriggerRequest {
+  string client_id = 1;
+  string trigger_json = 2;
+}
+
+message TableNamesResponse {
+  // Names of the tables the session serves, sorted, as a JSON array of strings.
+  string names_json = 1;
+}
+
+message DescribeTableRequest {
+  string client_id = 1;
+  string table = 2;
+}
+
+message DescribeTableResponse {
+  // The schema of one table as a standalone document, the same JSON shape
+  // CreateTableRequest.schema_json accepts back.
+  string schema_json = 1;
+}
+
+message RelationsRequest {
+  string client_id = 1;
+  optional string table = 2;
+}
+
+message RelationsResponse {
+  // Relation entries, serialized as JSON.
+  string relations_json = 1;
+}
+
+message IntegrityReport {
+  string report_json = 1;
+}
+
+message CompactRequest {
+  string client_id = 1;
+  optional string table = 2;
+}
+
+message CompactResponse {
+  string result_json = 1;
+}
+
+message CheckpointRequest {
+  string client_id = 1;
+  optional string table = 2;
+}