@xcitedbs/client 0.2.12 → 0.2.13

package/dist/client.d.ts

@@ -436,12 +436,18 @@ export declare class XCiteDBClient {
     queryLog(query: XCiteQuery, fromDate: string, toDate: string): Promise<LogEntry[]>;
     addMeta(identifier: string, value: unknown, path?: string, opts?: {
         mode?: 'set' | 'append';
+        overwrite?: boolean;
     }): Promise<boolean>;
     addMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean, opts?: {
         mode?: 'set' | 'append';
+        overwrite?: boolean;
+    }): Promise<boolean>;
+    appendMeta(identifier: string, value: unknown, path?: string, opts?: {
+        overwrite?: boolean;
+    }): Promise<boolean>;
+    appendMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean, opts?: {
+        overwrite?: boolean;
     }): Promise<boolean>;
-    appendMeta(identifier: string, value: unknown, path?: string): Promise<boolean>;
-    appendMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean): Promise<boolean>;
     queryMeta<T = MetaValue>(identifier: string, path?: string): Promise<T>;
     queryMetaByQuery<T = MetaValue>(query: XCiteQuery, path?: string): Promise<T>;
     clearMeta(query: XCiteQuery): Promise<boolean>;
@@ -517,12 +523,16 @@ export declare class XCiteDBClient {
      * The final event has `done: true` and may include `sources`.
      */
     ragQueryStream(options: Omit<RagQueryOptions, 'stream'>, onEvent: (ev: RagStreamEvent) => void): Promise<void>;
-    writeJsonDocument(identifier: string, data: unknown): Promise<void>;
+    writeJsonDocument(identifier: string, data: unknown, opts?: {
+        overwrite?: boolean;
+    }): Promise<void>;
     readJsonDocument<T = unknown>(identifier: string): Promise<T>;
     deleteJsonDocument(identifier: string): Promise<void>;
     listJsonDocuments(match?: string, limit?: number, offset?: number): Promise<ListIdentifiersResult>;
     /** JSON document shorthand — same as {@link writeJsonDocument}. */
-    put(identifier: string, data: unknown): Promise<void>;
+    put(identifier: string, data: unknown, opts?: {
+        overwrite?: boolean;
+    }): Promise<void>;
     /** JSON document read — same as {@link readJsonDocument}. */
     get<T = unknown>(identifier: string): Promise<T>;
     /** JSON document delete — same as {@link deleteJsonDocument}. */

package/dist/client.js

@@ -1352,6 +1352,8 @@ class XCiteDBClient {
         const body = { identifier: this.isoPrefixId(identifier), value, path };
         if (opts?.mode === 'append')
             body.mode = 'append';
+        if (opts?.overwrite)
+            body.overwrite = true;
         const r = await this.request('POST', '/api/v1/meta', body);
         return r?.ok !== false;
     }
@@ -1364,14 +1366,16 @@ class XCiteDBClient {
         };
         if (opts?.mode === 'append')
             body.mode = 'append';
+        if (opts?.overwrite)
+            body.overwrite = true;
         const r = await this.request('POST', '/api/v1/meta', body);
         return r?.ok !== false;
     }
-    async appendMeta(identifier, value, path = '') {
-        return this.addMeta(identifier, value, path, { mode: 'append' });
+    async appendMeta(identifier, value, path = '', opts) {
+        return this.addMeta(identifier, value, path, { mode: 'append', ...opts });
     }
-    async appendMetaByQuery(query, value, path = '', firstMatch = false) {
-        return this.addMetaByQuery(query, value, path, firstMatch, { mode: 'append' });
+    async appendMetaByQuery(query, value, path = '', firstMatch = false, opts) {
+        return this.addMetaByQuery(query, value, path, firstMatch, { mode: 'append', ...opts });
     }
     async queryMeta(identifier, path = '') {
         return this.request('GET', `/api/v1/meta${buildQuery({ identifier: this.isoPrefixId(identifier), path })}`);
@@ -1654,8 +1658,11 @@ class XCiteDBClient {
         }
         throw new types_1.XCiteDBError('RAG stream failed after retry', 401, null);
     }
-    async writeJsonDocument(identifier, data) {
-        await this.request('POST', '/api/v1/json-documents', { identifier: this.isoPrefixId(identifier), data });
+    async writeJsonDocument(identifier, data, opts) {
+        const body = { identifier: this.isoPrefixId(identifier), data };
+        if (opts?.overwrite)
+            body.overwrite = true;
+        await this.request('POST', '/api/v1/json-documents', body);
     }
     async readJsonDocument(identifier) {
         return this.request('GET', `/api/v1/json-documents${buildQuery({ identifier: this.isoPrefixId(identifier) })}`);
@@ -1684,8 +1691,8 @@ class XCiteDBClient {
         return { identifiers: [], total: 0, offset: 0, limit: 0 };
     }
     /** JSON document shorthand — same as {@link writeJsonDocument}. */
-    async put(identifier, data) {
-        return this.writeJsonDocument(identifier, data);
+    async put(identifier, data, opts) {
+        return this.writeJsonDocument(identifier, data, opts);
     }
     /** JSON document read — same as {@link readJsonDocument}. */
     async get(identifier) {

package/llms-full.txt

@@ -452,14 +452,23 @@ Returns `{ parent_path, parent_is_identifier, children: [{ segment, full_path, i
 
 **`POST /api/v1/json-documents`**
 
+JSON body fields:
+
+| Field | Required | Meaning |
+|-------|----------|---------|
+| `identifier` | yes | Document path key |
+| `data` | yes | JSON value to merge or store |
+| `overwrite` | no (default `false`) | When `true`, delete all metadata under the document root first, then write `data` only. When `false`, **`data` is merged** into any existing document (nested objects combine fields; nested arrays follow meta merge rules—see Metadata). |
+
 ```json
 {
   "identifier": "app.settings",
-  "data": { "theme": "dark", "maxUploadMb": 25 }
+  "data": { "theme": "dark", "maxUploadMb": 25 },
+  "overwrite": false
 }
 ```
 
-Note: The SDK method uses `identifier` and `data` fields. Some older documentation shows `key` and `value`.
+Note: SDKs use `identifier` and `data` (optional `overwrite`). Some older documentation shows `key` and `value`.
 
 ## Read JSON document
 
@@ -503,15 +512,26 @@ Attach structured **JSON metadata** to documents or nodes.
 
 **`POST /api/v1/meta`**
 
+| Field | Required | Meaning |
+|-------|----------|---------|
+| `identifier` **or** `query` | one required | Target document id or document query |
+| `value` | yes | JSON to write (omit only for string-specific query batch paths handled by the server) |
+| `path` | no (default `""`) | Meta path (dot-separated keys; `[i]` for array indices) |
+| `mode` | no (default `"set"`) | `"set"` — write/replace at `path`. For **arrays** at `path`, indices `0..n-1` are written and any previous tail beyond the new length is cleared. `"append"` — for **arrays** at `path`, new elements are written after existing indices (extend in place). |
+| `overwrite` | no (default `false`) | When `true`, delete existing metadata under `path` before applying `value`. |
+| `first_match` | no | With `query`, only the first matching identifier is updated when `true`. |
+
 ```json
 {
   "identifier": "/book/ch1",
   "value": { "status": "review", "owner": "alice" },
-  "path": ""
+  "path": "",
+  "mode": "set",
+  "overwrite": false
 }
 ```
 
-Optional `"mode": "append"` to append rather than overwrite.
+Use `"mode": "append"` to extend arrays at `path` instead of replacing them.
 
 Can also use `"query"` instead of `"identifier"` to target multiple documents by query filter.
 
@@ -527,6 +547,12 @@ Can also use `"query"` instead of `"identifier"` to target multiple documents by
 
 **`DELETE /api/v1/meta`** — `{ "query": {...} }`
 
+## JSON metadata storage model (best practices)
+
+- **Field-indexed objects.** Metadata and standalone JSON documents share the same shredded-key storage. **JSON objects** map to named paths so fields can be read or updated without loading a monolithic blob.
+- **Dictionary threshold.** When the **set of distinct field names** on an object reaches the server threshold (default **32**, native setting `meta_dict_field_threshold`), XCiteDB switches that object to **dictionary storage** (`{*}` plus per-field keys) for scalable indexed access.
+- **Modeling guidance.** Prefer stable **`{ "key": value, ... }`** / nested-object shapes for records you look up by key. Arrays are appropriate for ordered lists; use **`mode: "append"`** when appending to a stored array.
+
 ---
 
 # Search
@@ -1374,17 +1400,17 @@ interface DatabaseContext {
 - `queryLog(query, fromDate, toDate)` → `LogEntry[]`
 
 ### JSON Documents
-- `writeJsonDocument(identifier, data)` → `void`
+- `writeJsonDocument(identifier, data, opts?)` → `void` — merge by default; `opts?.overwrite` replaces root
 - `readJsonDocument<T>(identifier)` → `T` (default `unknown`)
 - `deleteJsonDocument(identifier)` → `void`
 - `listJsonDocuments(match?, limit?, offset?)` → `ListIdentifiersResult`
-- `put(identifier, data)` / `get<T>(identifier)` / `remove(identifier)` / `list(match?, limit?, offset?)` — JSON CRUD aliases
+- `put(identifier, data, opts?)` / `get<T>(identifier)` / `remove(identifier)` / `list(match?, limit?, offset?)` — JSON CRUD aliases (`opts` same as `writeJsonDocument`)
 
 ### Metadata
-- `addMeta(identifier, value, path?, opts?)` → `boolean`
+- `addMeta(identifier, value, path?, opts?)` → `boolean` — `opts`: `mode?: 'set'|'append'`, `overwrite?: boolean`
 - `addMetaByQuery(query, value, path?, firstMatch?, opts?)` → `boolean`
-- `appendMeta(identifier, value, path?)` → `boolean`
-- `appendMetaByQuery(query, value, path?, firstMatch?)` → `boolean`
+- `appendMeta(identifier, value, path?, opts?)` → `boolean` — same as `addMeta` with `mode: 'append'`
+- `appendMetaByQuery(query, value, path?, firstMatch?, opts?)` → `boolean`
 - `queryMeta<T>(identifier, path?)` → `T`
 - `queryMetaByQuery<T>(query, path?)` → `T`
 - `clearMeta(query)` → `boolean`

package/llms.txt

@@ -111,6 +111,12 @@ await app.writeJsonDocument('userdata/alice/profile', { ok: true });
 4. **Cleanup:** `DELETE /api/v1/test/sessions/current` with `X-Test-Session` (no other auth), or `DELETE /api/v1/test/sessions/all` / `DELETE /api/v1/test/sessions/{token}` with normal auth for the owning key or JWT.
 5. **SDKs:** **JS/TS:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, … })`, optional `overlay: true`, optional `testRequireAuth`, then `destroyTestSession()`. **Python:** `async with XCiteDBClient.test_session(...)` or provision with **`POST /api/v1/test/sessions`** and JSON **`{"overlay":true}`** when you need overlay, then pass `test_session_token` / `test_require_auth` to the constructor. **C++:** `XCiteDBClient::create_test_session(options)` with optional `test_session_overlay = true`, `destroy_test_session()`, optional `test_require_auth` in options.
 
+## JSON documents and metadata (merge, overwrite, efficiency)
+
+- **JSON documents merge by default.** `POST /api/v1/json-documents` merges the posted `data` into the existing document (object fields combined per XCiteDB meta merge rules). Send **`overwrite: true`** to clear all stored JSON under that document root first, then write only the new payload. SDKs accept the same flag (e.g. `writeJsonDocument(id, data, { overwrite: true })` in JavaScript).
+- **Metadata `mode` and arrays.** **`POST /api/v1/meta`** uses **`mode`**: default **`set`** writes or replaces at `path` (arrays are replaced in range; excess old indices cleared); **`append`** appends array elements after existing ones at `path`. Optional **`overwrite: true`** clears metadata under `path` before writing. JavaScript: **`appendMeta`** or **`addMeta(..., { mode: 'append' })`**; Python/C++: **`append_meta`** or **`add_meta`** with **`mode`** / **`overwrite`** (see SDK sections below).
+- **Prefer dictionary-style objects.** Shredded JSON metadata is keyed by field names. **Object maps** get per-field storage; when an object accumulates enough distinct field names (server default threshold **32**), XCiteDB switches automatically to **dictionary storage** (`{*}` plus per-field keys) for efficient indexed access. For lookup-heavy or wide records, use **`{ "key": value, ... }`** shapes (or one document per logical row) rather than opaque arrays when you need keyed reads.
+
 ## JavaScript/TypeScript SDK (`@xcitedbs/client`)
 
 Install: `npm install @xcitedbs/client`
@@ -232,15 +238,15 @@ interface XCiteDBClientOptions {
 - `listIdentifierChildren(parentPath?)` — Navigate identifier hierarchy
 
 **JSON Documents:**
-- `writeJsonDocument(identifier, data)` — Store a JSON document
+- `writeJsonDocument(identifier, data, opts?)` — Store or merge a JSON document (`opts?.overwrite` replaces entire document root)
 - `readJsonDocument(identifier)` — Read a JSON document (generic `readJsonDocument<T>()` supported)
 - `deleteJsonDocument(identifier)` — Delete a JSON document
 - `listJsonDocuments(match?, limit?, offset?)` — List JSON document keys
 - **Quick JSON aliases:** `put`, `get`, `remove`, `list` — same as the four methods above
 
 **Metadata (JSON on XML):**
-- `addMeta(identifier, value, path?)` — Set metadata on a document
-- `appendMeta(identifier, value, path?)` — Append to metadata
+- `addMeta(identifier, value, path?, opts?)` — Set or append metadata (`opts?.mode`: `set`|`append`; `opts?.overwrite`)
+- `appendMeta(identifier, value, path?, opts?)` — Append at `path` (same as `addMeta` with `mode: 'append'`)
 - `queryMeta(identifier, path?)` — Read metadata
 - `clearMeta(query)` — Remove metadata
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xcitedbs/client",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",