@ekodb/ekodb-client 0.16.0 → 0.17.0

package/dist/functions.test.js

@@ -0,0 +1,327 @@
+"use strict";
+/**
+ * Unit tests for the stored-function builder helpers (Stage + parameterRef).
+ *
+ * These tests cover the pure-data construction helpers and the structural
+ * parameter placeholder. They don't hit a running ekoDB — server-side
+ * behavior is covered by the Rust integration tests in
+ * `ekodb/ekodb_server/tests/function_parameters_tests.rs`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const functions_1 = require("./functions");
+(0, vitest_1.describe)("parameterRef", () => {
+    (0, vitest_1.it)("produces the structural placeholder shape ekoDB's resolver expects", () => {
+        (0, vitest_1.expect)((0, functions_1.parameterRef)("record")).toEqual({
+            type: "Parameter",
+            name: "record",
+        });
+    });
+    (0, vitest_1.it)("preserves an arbitrary parameter name verbatim", () => {
+        (0, vitest_1.expect)((0, functions_1.parameterRef)("user_id").name).toBe("user_id");
+    });
+});
+(0, vitest_1.describe)("Stage.param", () => {
+    (0, vitest_1.it)("is an alias for parameterRef(name)", () => {
+        (0, vitest_1.expect)(functions_1.Stage.param("x")).toEqual((0, functions_1.parameterRef)("x"));
+    });
+});
+(0, vitest_1.describe)("Stage.insert with a structural parameter placeholder", () => {
+    (0, vitest_1.it)("embeds the whole-record placeholder into Insert.record", () => {
+        const stage = functions_1.Stage.insert("users", functions_1.Stage.param("record"));
+        (0, vitest_1.expect)(stage.type).toBe("Insert");
+        (0, vitest_1.expect)(stage.collection).toBe("users");
+        (0, vitest_1.expect)(stage.record).toEqual({ type: "Parameter", name: "record" });
+    });
+    (0, vitest_1.it)("also accepts per-field placeholders mixed with literal values", () => {
+        const stage = functions_1.Stage.insert("items", {
+            label: "{{label}}",
+            parent_id: functions_1.Stage.param("parent_id"),
+            kind: "item",
+            tags: functions_1.Stage.param("tags"),
+        });
+        (0, vitest_1.expect)(stage.record.label).toBe("{{label}}");
+        (0, vitest_1.expect)(stage.record.parent_id).toEqual({
+            type: "Parameter",
+            name: "parent_id",
+        });
+        (0, vitest_1.expect)(stage.record.kind).toBe("item");
+        (0, vitest_1.expect)(stage.record.tags).toEqual({ type: "Parameter", name: "tags" });
+    });
+});
+(0, vitest_1.describe)("Stage.updateById with a structural parameter placeholder", () => {
+    (0, vitest_1.it)("embeds the whole-updates placeholder into UpdateById.updates", () => {
+        const stage = functions_1.Stage.updateById("items", "{{id}}", functions_1.Stage.param("updates"));
+        (0, vitest_1.expect)(stage.type).toBe("UpdateById");
+        (0, vitest_1.expect)(stage.collection).toBe("items");
+        (0, vitest_1.expect)(stage.record_id).toBe("{{id}}");
+        (0, vitest_1.expect)(stage.updates).toEqual({ type: "Parameter", name: "updates" });
+    });
+    (0, vitest_1.it)("accepts per-field placeholders for partial fine-grained updates", () => {
+        const stage = functions_1.Stage.updateById("items", "{{id}}", {
+            label: "{{label}}",
+            updated_at: "{{updated_at}}",
+        });
+        (0, vitest_1.expect)(stage.updates.label).toBe("{{label}}");
+        (0, vitest_1.expect)(stage.updates.updated_at).toBe("{{updated_at}}");
+    });
+});
+(0, vitest_1.describe)("Stage.update (filter-based) with structural updates", () => {
+    (0, vitest_1.it)("accepts a Parameter placeholder in both filter values and the updates body", () => {
+        const stage = functions_1.Stage.update("items", {
+            type: "Condition",
+            content: {
+                field: "id",
+                operator: "Eq",
+                value: functions_1.Stage.param("id"),
+            },
+        }, functions_1.Stage.param("updates"));
+        (0, vitest_1.expect)(stage.type).toBe("Update");
+        (0, vitest_1.expect)(stage.filter).toEqual({
+            type: "Condition",
+            content: {
+                field: "id",
+                operator: "Eq",
+                value: { type: "Parameter", name: "id" },
+            },
+        });
+        (0, vitest_1.expect)(stage.updates).toEqual({ type: "Parameter", name: "updates" });
+    });
+});
+(0, vitest_1.describe)("Stage.batchInsert with structural placeholders inside each record", () => {
+    (0, vitest_1.it)("lets callers template each record's record-body from params", () => {
+        const stage = functions_1.Stage.batchInsert("audit_log", [
+            { actor: functions_1.Stage.param("user_id"), at: "{{now}}", message: "created" },
+            { actor: functions_1.Stage.param("user_id"), at: "{{now}}", message: "initialized" },
+        ]);
+        (0, vitest_1.expect)(stage.type).toBe("BatchInsert");
+        (0, vitest_1.expect)(stage.records).toHaveLength(2);
+        (0, vitest_1.expect)(stage.records[0].actor).toEqual({
+            type: "Parameter",
+            name: "user_id",
+        });
+        (0, vitest_1.expect)(stage.records[0].at).toBe("{{now}}");
+        (0, vitest_1.expect)(stage.records[1].message).toBe("initialized");
+    });
+});
+(0, vitest_1.describe)("JSON serialization round-trip (what actually goes on the wire)", () => {
+    (0, vitest_1.it)("serializes a structural placeholder exactly as ekoDB expects", () => {
+        const stage = functions_1.Stage.insert("users", functions_1.Stage.param("record"));
+        const wire = JSON.parse(JSON.stringify(stage));
+        (0, vitest_1.expect)(stage.ttl).toBeUndefined();
+        (0, vitest_1.expect)("ttl" in wire).toBe(false);
+        (0, vitest_1.expect)(wire).toEqual({
+            type: "Insert",
+            collection: "users",
+            record: { type: "Parameter", name: "record" },
+            bypass_ripple: false,
+        });
+    });
+});
+// ============================================================================
+// Crypto primitives: BcryptHash, BcryptVerify, RandomToken (ekoDB >= 0.41.0)
+// ============================================================================
+(0, vitest_1.describe)("Stage.bcryptHash", () => {
+    (0, vitest_1.it)("produces a BcryptHash stage with text placeholder + explicit cost", () => {
+        const stage = functions_1.Stage.bcryptHash("{{password}}", "password_hash", 12);
+        (0, vitest_1.expect)(stage.type).toBe("BcryptHash");
+        (0, vitest_1.expect)(stage.plain).toBe("{{password}}");
+        (0, vitest_1.expect)(stage.cost).toBe(12);
+        (0, vitest_1.expect)(stage.output_field).toBe("password_hash");
+    });
+    (0, vitest_1.it)("leaves cost undefined when the caller omits it", () => {
+        const stage = functions_1.Stage.bcryptHash("{{password}}", "pw_hash");
+        (0, vitest_1.expect)(stage.cost).toBeUndefined();
+    });
+});
+(0, vitest_1.describe)("Stage.bcryptVerify", () => {
+    (0, vitest_1.it)("produces a BcryptVerify stage wiring hash_field and output_field", () => {
+        const stage = functions_1.Stage.bcryptVerify("{{password}}", "password_hash", "valid");
+        (0, vitest_1.expect)(stage.type).toBe("BcryptVerify");
+        (0, vitest_1.expect)(stage.plain).toBe("{{password}}");
+        (0, vitest_1.expect)(stage.hash_field).toBe("password_hash");
+        (0, vitest_1.expect)(stage.output_field).toBe("valid");
+    });
+});
+(0, vitest_1.describe)("Stage.randomToken", () => {
+    (0, vitest_1.it)("produces a RandomToken stage with explicit encoding", () => {
+        const stage = functions_1.Stage.randomToken(32, "session_token", "hex");
+        (0, vitest_1.expect)(stage.type).toBe("RandomToken");
+        (0, vitest_1.expect)(stage.bytes).toBe(32);
+        (0, vitest_1.expect)(stage.encoding).toBe("hex");
+        (0, vitest_1.expect)(stage.output_field).toBe("session_token");
+    });
+    (0, vitest_1.it)("leaves encoding undefined by default (server treats as hex)", () => {
+        const stage = functions_1.Stage.randomToken(16, "token");
+        (0, vitest_1.expect)(stage.encoding).toBeUndefined();
+    });
+    (0, vitest_1.it)("accepts base64 and base64url encodings", () => {
+        const a = functions_1.Stage.randomToken(16, "t", "base64");
+        const b = functions_1.Stage.randomToken(16, "t", "base64url");
+        (0, vitest_1.expect)(a.encoding).toBe("base64");
+        (0, vitest_1.expect)(b.encoding).toBe("base64url");
+    });
+});
+(0, vitest_1.describe)("Crypto stages JSON wire format", () => {
+    (0, vitest_1.it)("BcryptHash round-trips through JSON unchanged", () => {
+        const stage = functions_1.Stage.bcryptHash("{{password}}", "password_hash", 12);
+        const wire = JSON.parse(JSON.stringify(stage));
+        (0, vitest_1.expect)(wire).toEqual({
+            type: "BcryptHash",
+            plain: "{{password}}",
+            cost: 12,
+            output_field: "password_hash",
+        });
+    });
+    (0, vitest_1.it)("BcryptVerify round-trips through JSON unchanged", () => {
+        const stage = functions_1.Stage.bcryptVerify("{{password}}", "password_hash", "valid");
+        const wire = JSON.parse(JSON.stringify(stage));
+        (0, vitest_1.expect)(wire).toEqual({
+            type: "BcryptVerify",
+            plain: "{{password}}",
+            hash_field: "password_hash",
+            output_field: "valid",
+        });
+    });
+    (0, vitest_1.it)("RandomToken round-trips through JSON unchanged", () => {
+        const stage = functions_1.Stage.randomToken(32, "token", "hex");
+        const wire = JSON.parse(JSON.stringify(stage));
+        (0, vitest_1.expect)(wire).toEqual({
+            type: "RandomToken",
+            bytes: 32,
+            encoding: "hex",
+            output_field: "token",
+        });
+    });
+});
+// ============================================================================
+// Error Handling & Control Flow: TryCatch, Parallel, Sleep (ekoDB >= 0.42.0)
+// ============================================================================
+(0, vitest_1.describe)("Stage.tryCatch", () => {
+    (0, vitest_1.it)("produces a TryCatch stage with try/catch function lists", () => {
+        const stage = functions_1.Stage.tryCatch([functions_1.Stage.httpRequest("https://api.example.com/data")], [functions_1.Stage.insert("fallback_log", { error: "{{error}}" })], "api_error");
+        (0, vitest_1.expect)(stage.type).toBe("TryCatch");
+        (0, vitest_1.expect)(stage.try_functions).toHaveLength(1);
+        (0, vitest_1.expect)(stage.catch_functions).toHaveLength(1);
+        (0, vitest_1.expect)(stage.output_error_field).toBe("api_error");
+    });
+    (0, vitest_1.it)("leaves output_error_field undefined when omitted", () => {
+        const stage = functions_1.Stage.tryCatch([functions_1.Stage.findAll("users")], [functions_1.Stage.insert("errors", { msg: "failed" })]);
+        (0, vitest_1.expect)(stage.output_error_field).toBeUndefined();
+    });
+});
+(0, vitest_1.describe)("Stage.parallel", () => {
+    (0, vitest_1.it)("produces a Parallel stage with functions and wait_for_all", () => {
+        const stage = functions_1.Stage.parallel([functions_1.Stage.findAll("users"), functions_1.Stage.findAll("orders")], true);
+        (0, vitest_1.expect)(stage.type).toBe("Parallel");
+        (0, vitest_1.expect)(stage.functions).toHaveLength(2);
+        (0, vitest_1.expect)(stage.wait_for_all).toBe(true);
+    });
+    (0, vitest_1.it)("defaults wait_for_all to true", () => {
+        const stage = functions_1.Stage.parallel([functions_1.Stage.findAll("users")]);
+        (0, vitest_1.expect)(stage.wait_for_all).toBe(true);
+    });
+    (0, vitest_1.it)("accepts wait_for_all = false for race semantics", () => {
+        const stage = functions_1.Stage.parallel([functions_1.Stage.findAll("users"), functions_1.Stage.findAll("cache")], false);
+        (0, vitest_1.expect)(stage.wait_for_all).toBe(false);
+    });
+});
+(0, vitest_1.describe)("Stage.sleep", () => {
+    (0, vitest_1.it)("produces a Sleep stage with numeric duration", () => {
+        const stage = functions_1.Stage.sleep(1000);
+        (0, vitest_1.expect)(stage.type).toBe("Sleep");
+        (0, vitest_1.expect)(stage.duration_ms).toBe(1000);
+    });
+    (0, vitest_1.it)("accepts a text placeholder for parameter substitution", () => {
+        const stage = functions_1.Stage.sleep("{{delay}}");
+        (0, vitest_1.expect)(stage.duration_ms).toBe("{{delay}}");
+    });
+});
+// ============================================================================
+// Response Formatting: Return (ekoDB >= 0.42.0)
+// ============================================================================
+(0, vitest_1.describe)("Stage.returnResponse", () => {
+    (0, vitest_1.it)("produces a Return stage with fields and status_code", () => {
+        const stage = functions_1.Stage.returnResponse({ message: "ok", user_id: "{{id}}" }, 201);
+        (0, vitest_1.expect)(stage.type).toBe("Return");
+        (0, vitest_1.expect)(stage.fields).toEqual({ message: "ok", user_id: "{{id}}" });
+        (0, vitest_1.expect)(stage.status_code).toBe(201);
+    });
+    (0, vitest_1.it)("leaves status_code undefined when omitted (server defaults to 200)", () => {
+        const stage = functions_1.Stage.returnResponse({ success: true });
+        (0, vitest_1.expect)(stage.status_code).toBeUndefined();
+    });
+});
+// ============================================================================
+// Data Validation: Validate (ekoDB >= 0.42.0)
+// ============================================================================
+(0, vitest_1.describe)("Stage.validate", () => {
+    (0, vitest_1.it)("produces a Validate stage with schema, data_field, and on_error", () => {
+        const schema = {
+            type: "object",
+            required: ["name", "email"],
+            properties: {
+                name: { type: "string" },
+                email: { type: "string", format: "email" },
+            },
+        };
+        const stage = functions_1.Stage.validate(schema, "{{input}}", [
+            functions_1.Stage.returnResponse({ error: "validation failed" }, 400),
+        ]);
+        (0, vitest_1.expect)(stage.type).toBe("Validate");
+        (0, vitest_1.expect)(stage.schema).toEqual(schema);
+        (0, vitest_1.expect)(stage.data_field).toBe("{{input}}");
+        (0, vitest_1.expect)(stage.on_error).toHaveLength(1);
+    });
+    (0, vitest_1.it)("leaves on_error undefined when omitted", () => {
+        const stage = functions_1.Stage.validate({ type: "object" }, "record");
+        (0, vitest_1.expect)(stage.on_error).toBeUndefined();
+    });
+});
+// ============================================================================
+// New stages JSON wire format
+// ============================================================================
+(0, vitest_1.describe)("New stages JSON wire format", () => {
+    (0, vitest_1.it)("TryCatch round-trips through JSON unchanged", () => {
+        const stage = functions_1.Stage.tryCatch([functions_1.Stage.findAll("users")], [functions_1.Stage.insert("errors", { msg: "failed" })], "err");
+        const wire = JSON.parse(JSON.stringify(stage));
+        (0, vitest_1.expect)(wire.type).toBe("TryCatch");
+        (0, vitest_1.expect)(wire.try_functions).toHaveLength(1);
+        (0, vitest_1.expect)(wire.catch_functions).toHaveLength(1);
+        (0, vitest_1.expect)(wire.output_error_field).toBe("err");
+    });
+    (0, vitest_1.it)("Parallel round-trips through JSON unchanged", () => {
+        const stage = functions_1.Stage.parallel([functions_1.Stage.findAll("a"), functions_1.Stage.findAll("b")], false);
+        const wire = JSON.parse(JSON.stringify(stage));
+        (0, vitest_1.expect)(wire).toEqual({
+            type: "Parallel",
+            functions: [
+                { type: "FindAll", collection: "a" },
+                { type: "FindAll", collection: "b" },
+            ],
+            wait_for_all: false,
+        });
+    });
+    (0, vitest_1.it)("Sleep round-trips through JSON unchanged", () => {
+        const wire = JSON.parse(JSON.stringify(functions_1.Stage.sleep(500)));
+        (0, vitest_1.expect)(wire).toEqual({ type: "Sleep", duration_ms: 500 });
+    });
+    (0, vitest_1.it)("Return round-trips through JSON unchanged", () => {
+        const stage = functions_1.Stage.returnResponse({ ok: true }, 201);
+        const wire = JSON.parse(JSON.stringify(stage));
+        (0, vitest_1.expect)(wire).toEqual({
+            type: "Return",
+            fields: { ok: true },
+            status_code: 201,
+        });
+    });
+    (0, vitest_1.it)("Validate round-trips through JSON unchanged", () => {
+        const stage = functions_1.Stage.validate({ type: "object" }, "data");
+        const wire = JSON.parse(JSON.stringify(stage));
+        (0, vitest_1.expect)(wire).toEqual({
+            type: "Validate",
+            schema: { type: "object" },
+            data_field: "data",
+        });
+    });
+});

package/dist/index.d.ts

@@ -3,7 +3,8 @@ export { QueryBuilder, SortOrder } from "./query-builder";
 export { SearchQueryBuilder } from "./search";
 export { SchemaBuilder, FieldTypeSchemaBuilder, VectorIndexAlgorithm, DistanceMetric, } from "./schema";
 export { JoinBuilder } from "./join";
-export { Stage, ChatMessage } from "./functions";
+export { Stage, ChatMessage, parameterRef } from "./functions";
+export type { ParameterRef } from "./functions";
 export { getValue, getValues, extractRecord, getDateTimeValue, getUUIDValue, getDecimalValue, getDurationValue, getBytesValue, getBinaryValue, getArrayValue, getSetValue, getVectorValue, getObjectValue, Field, } from "./utils";
 export type { WrappedFieldValue } from "./utils";
 export type { SearchQuery, SearchResult, SearchResponse } from "./search";

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.extractRecordId = exports.SchemaCache = 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.parameterRef = 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; } });
@@ -25,6 +25,7 @@ Object.defineProperty(exports, "JoinBuilder", { enumerable: true, get: function
 var functions_1 = require("./functions");
 Object.defineProperty(exports, "Stage", { enumerable: true, get: function () { return functions_1.Stage; } });
 Object.defineProperty(exports, "ChatMessage", { enumerable: true, get: function () { return functions_1.ChatMessage; } });
+Object.defineProperty(exports, "parameterRef", { enumerable: true, get: function () { return functions_1.parameterRef; } });
 var utils_1 = require("./utils");
 Object.defineProperty(exports, "getValue", { enumerable: true, get: function () { return utils_1.getValue; } });
 Object.defineProperty(exports, "getValues", { enumerable: true, get: function () { return utils_1.getValues; } });

package/package.json

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