@ekodb/ekodb-client 0.15.0 → 0.15.2

package/README.md

@@ -328,9 +328,38 @@ const joinResults = await client.find("users", multiQuery);
 
 ### WebSocket Methods
 
-- `findAll(collection: string): Promise<Record[]>`
+**Full CRUD (14 methods):**
+
+- `findAll(collection): Promise<Record[]>`
+- `insert(collection, record, bypassRipple?): Promise<any>`
+- `query(collection, options?): Promise<any[]>`
+- `findById(collection, id): Promise<any>`
+- `update(collection, id, record, bypassRipple?): Promise<any>`
+- `delete(collection, id, bypassRipple?): Promise<void>`
+- `batchInsert(collection, records, bypassRipple?): Promise<any>`
+- `batchUpdate(collection, updates, bypassRipple?): Promise<any>`
+- `batchDelete(collection, ids, bypassRipple?): Promise<void>`
+- `textSearch(collection, query, fields?, limit?): Promise<any[]>`
+- `distinctValues(collection, field, filter?): Promise<any>`
+- `updateWithAction(collection, id, action, field, value?): Promise<any>`
+- `createCollection(name, schema?): Promise<void>`
+- `listCollections(): Promise<string[]>`
+- `deleteCollection(name): Promise<void>`
 - `close(): void`
 
+**Schema Cache:**
+
+```typescript
+import { SchemaCache, extractRecordId } from "@ekodb/ekodb-client";
+
+const cache = new SchemaCache({ enabled: true, ttlSeconds: 300 });
+ws.setSchemaCache(cache);
+
+// Extract IDs correctly with custom primary_key_alias
+const id = extractRecordId(record); // tries "id", "_id"
+const id2 = ws.extractId("users", record); // uses cache
+```
+
 ## Examples
 
 See the

package/dist/client.d.ts

@@ -1219,11 +1219,40 @@ export declare class EventStream<_T = unknown> {
 /**
  * WebSocket client for real-time queries, subscriptions, and chat streaming.
  */
+/**
+ * In-memory schema cache with TTL for primary_key_alias resolution.
+ */
+export declare class SchemaCache {
+    private entries;
+    private lruOrder;
+    private enabled;
+    private maxEntries;
+    private ttlMs;
+    constructor(options?: {
+        enabled?: boolean;
+        maxEntries?: number;
+        ttlSeconds?: number;
+    });
+    isEnabled(): boolean;
+    setEnabled(enabled: boolean): void;
+    getAlias(collection: string): string | undefined;
+    insert(collection: string, primaryKeyAlias: string, version: number): void;
+    invalidate(collection: string): void;
+    invalidateAll(): void;
+    handleSchemaChanged(collection: string, version: number, primaryKeyAlias: string): void;
+    get size(): number;
+    private touchLRU;
+}
+/**
+ * Extract record ID from a record object, trying custom alias, "id", then "_id".
+ */
+export declare function extractRecordId(record: Record, extraCandidates?: string[]): string | undefined;
 export declare class WebSocketClient {
     private wsURL;
     private token;
     private ws;
     private dispatcherRunning;
+    private schemaCache;
     private pendingRequests;
     private subscriptions;
     private chatStreams;
@@ -1269,6 +1298,44 @@ export declare class WebSocketClient {
      * proxy timeouts.
      */
     rawCompletion(request: RawCompletionRequest): Promise<RawCompletionResponse>;
+    /** Attach a schema cache for automatic invalidation on SchemaChanged events. */
+    setSchemaCache(cache: SchemaCache): void;
+    /** Extract record ID using the schema cache's primary_key_alias. */
+    extractId(collection: string, record: Record): string | undefined;
+    private sendCRUD;
+    /** Insert a single record via WebSocket. */
+    insert(collection: string, record: Record, bypassRipple?: boolean): Promise<any>;
+    /** Query records via WebSocket. */
+    query(collection: string, options?: {
+        filter?: any;
+        sort?: any;
+        limit?: number;
+        skip?: number;
+    }): Promise<any[]>;
+    /** Find a record by ID via WebSocket. */
+    findById(collection: string, id: string): Promise<any>;
+    /** Update a record by ID via WebSocket. */
+    update(collection: string, id: string, record: Record, bypassRipple?: boolean): Promise<any>;
+    /** Delete a record by ID via WebSocket. */
+    delete(collection: string, id: string, bypassRipple?: boolean): Promise<void>;
+    /** Batch insert multiple records via WebSocket. */
+    batchInsert(collection: string, records: Record[], bypassRipple?: boolean): Promise<any>;
+    /** Batch update multiple records via WebSocket. */
+    batchUpdate(collection: string, updates: [string, Record][], bypassRipple?: boolean): Promise<any>;
+    /** Batch delete records by IDs via WebSocket. */
+    batchDelete(collection: string, ids: string[], bypassRipple?: boolean): Promise<void>;
+    /** Full-text search via WebSocket. */
+    textSearch(collection: string, query: string, fields?: string[], limit?: number): Promise<any[]>;
+    /** Get distinct values for a field via WebSocket. */
+    distinctValues(collection: string, field: string, filter?: any): Promise<any>;
+    /** Apply an atomic field action via WebSocket. */
+    updateWithAction(collection: string, id: string, action: string, field: string, value?: any): Promise<any>;
+    /** Create a collection with optional schema via WebSocket. */
+    createCollection(name: string, schema?: any): Promise<void>;
+    /** List all collections via WebSocket. */
+    listCollections(): Promise<string[]>;
+    /** Delete a collection via WebSocket. */
+    deleteCollection(name: string): Promise<void>;
     /**
      * Close the WebSocket connection.
      */

package/dist/client.js

@@ -36,7 +36,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WebSocketClient = exports.EventStream = exports.EkoDBClient = exports.MergeStrategy = exports.RateLimitError = exports.SerializationFormat = void 0;
+exports.WebSocketClient = exports.SchemaCache = exports.EventStream = exports.EkoDBClient = exports.MergeStrategy = exports.RateLimitError = exports.SerializationFormat = void 0;
+exports.extractRecordId = extractRecordId;
 const msgpack_1 = require("@msgpack/msgpack");
 const query_builder_1 = require("./query-builder");
 const schema_1 = require("./schema");
@@ -1719,7 +1720,10 @@ class EkoDBClient {
             limit,
         };
         const response = await this.search(collection, searchQuery);
-        return response.results.map((r) => r.record);
+        return response.results.map((r) => ({
+            ...r.record,
+            _score: r.score,
+        }));
     }
     /**
      * Find all records in a collection with a limit
@@ -1778,10 +1782,107 @@ exports.EventStream = EventStream;
 /**
  * WebSocket client for real-time queries, subscriptions, and chat streaming.
  */
+/**
+ * In-memory schema cache with TTL for primary_key_alias resolution.
+ */
+class SchemaCache {
+    constructor(options = {}) {
+        this.entries = new Map();
+        this.lruOrder = [];
+        this.enabled = options.enabled ?? false;
+        this.maxEntries = options.maxEntries ?? 100;
+        this.ttlMs = (options.ttlSeconds ?? 300) * 1000;
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+    getAlias(collection) {
+        if (!this.enabled)
+            return undefined;
+        const entry = this.entries.get(collection);
+        if (!entry)
+            return undefined;
+        if (Date.now() - entry.cachedAt > this.ttlMs) {
+            this.entries.delete(collection);
+            this.lruOrder = this.lruOrder.filter((c) => c !== collection);
+            return undefined;
+        }
+        this.touchLRU(collection);
+        return entry.primaryKeyAlias;
+    }
+    insert(collection, primaryKeyAlias, version) {
+        if (!this.enabled)
+            return;
+        const isNew = !this.entries.has(collection);
+        this.entries.set(collection, {
+            primaryKeyAlias,
+            version,
+            cachedAt: Date.now(),
+        });
+        if (isNew) {
+            this.lruOrder.push(collection);
+            while (this.lruOrder.length > this.maxEntries) {
+                const oldest = this.lruOrder.shift();
+                this.entries.delete(oldest);
+            }
+        }
+        else {
+            this.touchLRU(collection);
+        }
+    }
+    invalidate(collection) {
+        this.entries.delete(collection);
+        this.lruOrder = this.lruOrder.filter((c) => c !== collection);
+    }
+    invalidateAll() {
+        this.entries.clear();
+        this.lruOrder = [];
+    }
+    handleSchemaChanged(collection, version, primaryKeyAlias) {
+        if (!this.enabled)
+            return;
+        const existing = this.entries.get(collection);
+        if (existing && version <= existing.version)
+            return;
+        this.insert(collection, primaryKeyAlias, version);
+    }
+    get size() {
+        return this.entries.size;
+    }
+    touchLRU(collection) {
+        this.lruOrder = this.lruOrder.filter((c) => c !== collection);
+        this.lruOrder.push(collection);
+    }
+}
+exports.SchemaCache = SchemaCache;
+/**
+ * Extract record ID from a record object, trying custom alias, "id", then "_id".
+ */
+function extractRecordId(record, extraCandidates = []) {
+    for (const key of extraCandidates) {
+        const val = record[key];
+        if (typeof val === "string")
+            return val;
+        if (val && typeof val === "object" && "value" in val)
+            return String(val.value);
+    }
+    for (const key of ["id", "_id"]) {
+        const val = record[key];
+        if (typeof val === "string")
+            return val;
+        if (val && typeof val === "object" && "value" in val)
+            return String(val.value);
+    }
+    return undefined;
+}
 class WebSocketClient {
     constructor(wsURL, token) {
         this.ws = null;
         this.dispatcherRunning = false;
+        this.schemaCache = null;
         // Dispatcher state
         this.pendingRequests = new Map();
         this.subscriptions = new Map();
@@ -1956,6 +2057,12 @@ class WebSocketClient {
                 }
                 break;
             }
+            case "SchemaChanged": {
+                if (this.schemaCache && msg.payload) {
+                    this.schemaCache.handleSchemaChanged(msg.payload.collection, msg.payload.version, msg.payload.primary_key_alias);
+                }
+                break;
+            }
             case "ClientToolCall": {
                 const chatId = msg.payload?.chat_id || msg.payload?.chatId;
                 const stream = this.chatStreams.get(chatId);
@@ -2120,6 +2227,136 @@ class WebSocketClient {
         });
         return { content: payload?.data?.content || "" };
     }
+    /** Attach a schema cache for automatic invalidation on SchemaChanged events. */
+    setSchemaCache(cache) {
+        this.schemaCache = cache;
+    }
+    /** Extract record ID using the schema cache's primary_key_alias. */
+    extractId(collection, record) {
+        const alias = this.schemaCache?.getAlias(collection);
+        return extractRecordId(record, alias ? [alias] : []);
+    }
+    // =========================================================================
+    // WS CRUD Methods — Full Parity with Server
+    // =========================================================================
+    async sendCRUD(msgType, payload) {
+        const messageId = this.genMessageId();
+        const response = await this.sendRequest({
+            type: msgType,
+            messageId,
+            payload,
+        });
+        return response?.data ?? response;
+    }
+    /** Insert a single record via WebSocket. */
+    async insert(collection, record, bypassRipple) {
+        return this.sendCRUD("Insert", {
+            collection,
+            record,
+            ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+        });
+    }
+    /** Query records via WebSocket. */
+    async query(collection, options) {
+        const data = await this.sendCRUD("Query", {
+            collection,
+            ...options,
+        });
+        return Array.isArray(data) ? data : [];
+    }
+    /** Find a record by ID via WebSocket. */
+    async findById(collection, id) {
+        return this.sendCRUD("FindById", { collection, id });
+    }
+    /** Update a record by ID via WebSocket. */
+    async update(collection, id, record, bypassRipple) {
+        return this.sendCRUD("Update", {
+            collection,
+            id,
+            record,
+            ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+        });
+    }
+    /** Delete a record by ID via WebSocket. */
+    async delete(collection, id, bypassRipple) {
+        await this.sendCRUD("Delete", {
+            collection,
+            id,
+            ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+        });
+    }
+    /** Batch insert multiple records via WebSocket. */
+    async batchInsert(collection, records, bypassRipple) {
+        return this.sendCRUD("BatchInsert", {
+            collection,
+            records,
+            ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+        });
+    }
+    /** Batch update multiple records via WebSocket. */
+    async batchUpdate(collection, updates, bypassRipple) {
+        return this.sendCRUD("BatchUpdate", {
+            collection,
+            updates,
+            ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+        });
+    }
+    /** Batch delete records by IDs via WebSocket. */
+    async batchDelete(collection, ids, bypassRipple) {
+        await this.sendCRUD("BatchDelete", {
+            collection,
+            ids,
+            ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+        });
+    }
+    /** Full-text search via WebSocket. */
+    async textSearch(collection, query, fields, limit) {
+        const options = {};
+        if (fields)
+            options.fields = fields;
+        if (limit)
+            options.limit = limit;
+        const data = await this.sendCRUD("TextSearch", {
+            collection,
+            query,
+            ...(Object.keys(options).length > 0 && { options }),
+        });
+        return Array.isArray(data) ? data : [];
+    }
+    /** Get distinct values for a field via WebSocket. */
+    async distinctValues(collection, field, filter) {
+        return this.sendCRUD("DistinctValues", {
+            collection,
+            field,
+            ...(filter && { filter }),
+        });
+    }
+    /** Apply an atomic field action via WebSocket. */
+    async updateWithAction(collection, id, action, field, value) {
+        return this.sendCRUD("UpdateWithAction", {
+            collection,
+            id,
+            action,
+            field,
+            ...(value !== undefined && { value }),
+        });
+    }
+    /** Create a collection with optional schema via WebSocket. */
+    async createCollection(name, schema) {
+        await this.sendCRUD("CreateCollection", {
+            name,
+            schema: schema ?? {},
+        });
+    }
+    /** List all collections via WebSocket. */
+    async listCollections() {
+        const data = await this.sendCRUD("GetCollections", {});
+        return Array.isArray(data) ? data : [];
+    }
+    /** Delete a collection via WebSocket. */
+    async deleteCollection(name) {
+        await this.sendCRUD("DeleteCollection", { name });
+    }
     /**
      * Close the WebSocket connection.
      */

package/dist/client.test.js

@@ -1944,6 +1944,7 @@ function mockErrorResponse(status, message) {
         (0, vitest_1.expect)(result).toHaveLength(1);
         (0, vitest_1.expect)(result[0]).toHaveProperty("id", "doc_1");
         (0, vitest_1.expect)(result[0]).toHaveProperty("title", "ML Guide");
+        (0, vitest_1.expect)(result[0]).toHaveProperty("_score", 0.95);
     });
 });
 // ============================================================================

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { EkoDBClient, WebSocketClient, EventStream, SerializationFormat, MergeStrategy, RateLimitError, } from "./client";
+export { EkoDBClient, WebSocketClient, EventStream, SerializationFormat, MergeStrategy, RateLimitError, SchemaCache, extractRecordId, } from "./client";
 export { QueryBuilder, SortOrder } from "./query-builder";
 export { SearchQueryBuilder } from "./search";
 export { SchemaBuilder, FieldTypeSchemaBuilder, VectorIndexAlgorithm, DistanceMetric, } from "./schema";

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Field = exports.getObjectValue = exports.getVectorValue = exports.getSetValue = exports.getArrayValue = exports.getBinaryValue = exports.getBytesValue = exports.getDurationValue = exports.getDecimalValue = exports.getUUIDValue = exports.getDateTimeValue = exports.extractRecord = exports.getValues = exports.getValue = exports.ChatMessage = exports.Stage = exports.JoinBuilder = exports.DistanceMetric = exports.VectorIndexAlgorithm = exports.FieldTypeSchemaBuilder = exports.SchemaBuilder = exports.SearchQueryBuilder = exports.SortOrder = exports.QueryBuilder = exports.RateLimitError = exports.MergeStrategy = exports.SerializationFormat = exports.EventStream = exports.WebSocketClient = exports.EkoDBClient = void 0;
+exports.Field = exports.getObjectValue = exports.getVectorValue = exports.getSetValue = exports.getArrayValue = exports.getBinaryValue = exports.getBytesValue = exports.getDurationValue = exports.getDecimalValue = exports.getUUIDValue = exports.getDateTimeValue = exports.extractRecord = exports.getValues = exports.getValue = exports.ChatMessage = exports.Stage = exports.JoinBuilder = exports.DistanceMetric = exports.VectorIndexAlgorithm = exports.FieldTypeSchemaBuilder = exports.SchemaBuilder = exports.SearchQueryBuilder = exports.SortOrder = exports.QueryBuilder = exports.extractRecordId = exports.SchemaCache = exports.RateLimitError = exports.MergeStrategy = exports.SerializationFormat = exports.EventStream = exports.WebSocketClient = exports.EkoDBClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "EkoDBClient", { enumerable: true, get: function () { return client_1.EkoDBClient; } });
 Object.defineProperty(exports, "WebSocketClient", { enumerable: true, get: function () { return client_1.WebSocketClient; } });
@@ -8,6 +8,8 @@ Object.defineProperty(exports, "EventStream", { enumerable: true, get: function
 Object.defineProperty(exports, "SerializationFormat", { enumerable: true, get: function () { return client_1.SerializationFormat; } });
 Object.defineProperty(exports, "MergeStrategy", { enumerable: true, get: function () { return client_1.MergeStrategy; } });
 Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return client_1.RateLimitError; } });
+Object.defineProperty(exports, "SchemaCache", { enumerable: true, get: function () { return client_1.SchemaCache; } });
+Object.defineProperty(exports, "extractRecordId", { enumerable: true, get: function () { return client_1.extractRecordId; } });
 var query_builder_1 = require("./query-builder");
 Object.defineProperty(exports, "QueryBuilder", { enumerable: true, get: function () { return query_builder_1.QueryBuilder; } });
 Object.defineProperty(exports, "SortOrder", { enumerable: true, get: function () { return query_builder_1.SortOrder; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekodb/ekodb-client",
-  "version": "0.15.0",
+  "version": "0.15.2",
   "description": "Official TypeScript/JavaScript client for ekoDB",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/client.test.ts

@@ -2584,6 +2584,7 @@ describe("EkoDBClient text and hybrid search", () => {
     expect(result).toHaveLength(1);
     expect(result[0]).toHaveProperty("id", "doc_1");
     expect(result[0]).toHaveProperty("title", "ML Guide");
+    expect(result[0]).toHaveProperty("_score", 0.95);
   });
 });
 

package/src/client.ts

@@ -2912,7 +2912,10 @@ export class EkoDBClient {
     };
 
     const response = await this.search(collection, searchQuery);
-    return response.results.map((r) => r.record);
+    return response.results.map((r) => ({
+      ...r.record,
+      _score: r.score,
+    }));
   }
 
   /**
@@ -3026,11 +3029,128 @@ export class EventStream<_T = unknown> {
 /**
  * WebSocket client for real-time queries, subscriptions, and chat streaming.
  */
+/**
+ * In-memory schema cache with TTL for primary_key_alias resolution.
+ */
+export class SchemaCache {
+  private entries: Map<
+    string,
+    { primaryKeyAlias: string; version: number; cachedAt: number }
+  > = new Map();
+  private lruOrder: string[] = [];
+  private enabled: boolean;
+  private maxEntries: number;
+  private ttlMs: number;
+
+  constructor(
+    options: {
+      enabled?: boolean;
+      maxEntries?: number;
+      ttlSeconds?: number;
+    } = {},
+  ) {
+    this.enabled = options.enabled ?? false;
+    this.maxEntries = options.maxEntries ?? 100;
+    this.ttlMs = (options.ttlSeconds ?? 300) * 1000;
+  }
+
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+  setEnabled(enabled: boolean): void {
+    this.enabled = enabled;
+  }
+
+  getAlias(collection: string): string | undefined {
+    if (!this.enabled) return undefined;
+    const entry = this.entries.get(collection);
+    if (!entry) return undefined;
+    if (Date.now() - entry.cachedAt > this.ttlMs) {
+      this.entries.delete(collection);
+      this.lruOrder = this.lruOrder.filter((c) => c !== collection);
+      return undefined;
+    }
+    this.touchLRU(collection);
+    return entry.primaryKeyAlias;
+  }
+
+  insert(collection: string, primaryKeyAlias: string, version: number): void {
+    if (!this.enabled) return;
+    const isNew = !this.entries.has(collection);
+    this.entries.set(collection, {
+      primaryKeyAlias,
+      version,
+      cachedAt: Date.now(),
+    });
+    if (isNew) {
+      this.lruOrder.push(collection);
+      while (this.lruOrder.length > this.maxEntries) {
+        const oldest = this.lruOrder.shift()!;
+        this.entries.delete(oldest);
+      }
+    } else {
+      this.touchLRU(collection);
+    }
+  }
+
+  invalidate(collection: string): void {
+    this.entries.delete(collection);
+    this.lruOrder = this.lruOrder.filter((c) => c !== collection);
+  }
+  invalidateAll(): void {
+    this.entries.clear();
+    this.lruOrder = [];
+  }
+
+  handleSchemaChanged(
+    collection: string,
+    version: number,
+    primaryKeyAlias: string,
+  ): void {
+    if (!this.enabled) return;
+    const existing = this.entries.get(collection);
+    if (existing && version <= existing.version) return;
+    this.insert(collection, primaryKeyAlias, version);
+  }
+
+  get size(): number {
+    return this.entries.size;
+  }
+
+  private touchLRU(collection: string): void {
+    this.lruOrder = this.lruOrder.filter((c) => c !== collection);
+    this.lruOrder.push(collection);
+  }
+}
+
+/**
+ * Extract record ID from a record object, trying custom alias, "id", then "_id".
+ */
+export function extractRecordId(
+  record: Record,
+  extraCandidates: string[] = [],
+): string | undefined {
+  for (const key of extraCandidates) {
+    const val = record[key];
+    if (typeof val === "string") return val;
+    if (val && typeof val === "object" && "value" in val)
+      return String(val.value);
+  }
+  for (const key of ["id", "_id"]) {
+    const val = record[key];
+    if (typeof val === "string") return val;
+    if (val && typeof val === "object" && "value" in val)
+      return String(val.value);
+  }
+  return undefined;
+}
+
 export class WebSocketClient {
   private wsURL: string;
   private token: string;
   private ws: any = null;
   private dispatcherRunning = false;
+  private schemaCache: SchemaCache | null = null;
 
   // Dispatcher state
   private pendingRequests: Map<
@@ -3230,6 +3350,17 @@ export class WebSocketClient {
         break;
       }
 
+      case "SchemaChanged": {
+        if (this.schemaCache && msg.payload) {
+          this.schemaCache.handleSchemaChanged(
+            msg.payload.collection,
+            msg.payload.version,
+            msg.payload.primary_key_alias,
+          );
+        }
+        break;
+      }
+
       case "ClientToolCall": {
         const chatId = msg.payload?.chat_id || msg.payload?.chatId;
         const stream = this.chatStreams.get(chatId);
@@ -3431,6 +3562,200 @@ export class WebSocketClient {
     return { content: payload?.data?.content || "" };
   }
 
+  /** Attach a schema cache for automatic invalidation on SchemaChanged events. */
+  setSchemaCache(cache: SchemaCache): void {
+    this.schemaCache = cache;
+  }
+
+  /** Extract record ID using the schema cache's primary_key_alias. */
+  extractId(collection: string, record: Record): string | undefined {
+    const alias = this.schemaCache?.getAlias(collection);
+    return extractRecordId(record, alias ? [alias] : []);
+  }
+
+  // =========================================================================
+  // WS CRUD Methods — Full Parity with Server
+  // =========================================================================
+
+  private async sendCRUD(msgType: string, payload: any): Promise<any> {
+    const messageId = this.genMessageId();
+    const response = await this.sendRequest({
+      type: msgType,
+      messageId,
+      payload,
+    });
+    return response?.data ?? response;
+  }
+
+  /** Insert a single record via WebSocket. */
+  async insert(
+    collection: string,
+    record: Record,
+    bypassRipple?: boolean,
+  ): Promise<any> {
+    return this.sendCRUD("Insert", {
+      collection,
+      record,
+      ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+    });
+  }
+
+  /** Query records via WebSocket. */
+  async query(
+    collection: string,
+    options?: {
+      filter?: any;
+      sort?: any;
+      limit?: number;
+      skip?: number;
+    },
+  ): Promise<any[]> {
+    const data = await this.sendCRUD("Query", {
+      collection,
+      ...options,
+    });
+    return Array.isArray(data) ? data : [];
+  }
+
+  /** Find a record by ID via WebSocket. */
+  async findById(collection: string, id: string): Promise<any> {
+    return this.sendCRUD("FindById", { collection, id });
+  }
+
+  /** Update a record by ID via WebSocket. */
+  async update(
+    collection: string,
+    id: string,
+    record: Record,
+    bypassRipple?: boolean,
+  ): Promise<any> {
+    return this.sendCRUD("Update", {
+      collection,
+      id,
+      record,
+      ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+    });
+  }
+
+  /** Delete a record by ID via WebSocket. */
+  async delete(
+    collection: string,
+    id: string,
+    bypassRipple?: boolean,
+  ): Promise<void> {
+    await this.sendCRUD("Delete", {
+      collection,
+      id,
+      ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+    });
+  }
+
+  /** Batch insert multiple records via WebSocket. */
+  async batchInsert(
+    collection: string,
+    records: Record[],
+    bypassRipple?: boolean,
+  ): Promise<any> {
+    return this.sendCRUD("BatchInsert", {
+      collection,
+      records,
+      ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+    });
+  }
+
+  /** Batch update multiple records via WebSocket. */
+  async batchUpdate(
+    collection: string,
+    updates: [string, Record][],
+    bypassRipple?: boolean,
+  ): Promise<any> {
+    return this.sendCRUD("BatchUpdate", {
+      collection,
+      updates,
+      ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+    });
+  }
+
+  /** Batch delete records by IDs via WebSocket. */
+  async batchDelete(
+    collection: string,
+    ids: string[],
+    bypassRipple?: boolean,
+  ): Promise<void> {
+    await this.sendCRUD("BatchDelete", {
+      collection,
+      ids,
+      ...(bypassRipple !== undefined && { bypass_ripple: bypassRipple }),
+    });
+  }
+
+  /** Full-text search via WebSocket. */
+  async textSearch(
+    collection: string,
+    query: string,
+    fields?: string[],
+    limit?: number,
+  ): Promise<any[]> {
+    const options: any = {};
+    if (fields) options.fields = fields;
+    if (limit) options.limit = limit;
+    const data = await this.sendCRUD("TextSearch", {
+      collection,
+      query,
+      ...(Object.keys(options).length > 0 && { options }),
+    });
+    return Array.isArray(data) ? data : [];
+  }
+
+  /** Get distinct values for a field via WebSocket. */
+  async distinctValues(
+    collection: string,
+    field: string,
+    filter?: any,
+  ): Promise<any> {
+    return this.sendCRUD("DistinctValues", {
+      collection,
+      field,
+      ...(filter && { filter }),
+    });
+  }
+
+  /** Apply an atomic field action via WebSocket. */
+  async updateWithAction(
+    collection: string,
+    id: string,
+    action: string,
+    field: string,
+    value?: any,
+  ): Promise<any> {
+    return this.sendCRUD("UpdateWithAction", {
+      collection,
+      id,
+      action,
+      field,
+      ...(value !== undefined && { value }),
+    });
+  }
+
+  /** Create a collection with optional schema via WebSocket. */
+  async createCollection(name: string, schema?: any): Promise<void> {
+    await this.sendCRUD("CreateCollection", {
+      name,
+      schema: schema ?? {},
+    });
+  }
+
+  /** List all collections via WebSocket. */
+  async listCollections(): Promise<string[]> {
+    const data = await this.sendCRUD("GetCollections", {});
+    return Array.isArray(data) ? data : [];
+  }
+
+  /** Delete a collection via WebSocket. */
+  async deleteCollection(name: string): Promise<void> {
+    await this.sendCRUD("DeleteCollection", { name });
+  }
+
   /**
    * Close the WebSocket connection.
    */

package/src/index.ts

@@ -5,6 +5,8 @@ export {
   SerializationFormat,
   MergeStrategy,
   RateLimitError,
+  SchemaCache,
+  extractRecordId,
 } from "./client";
 export { QueryBuilder, SortOrder } from "./query-builder";
 export { SearchQueryBuilder } from "./search";