@ekodb/ekodb-client 0.15.2 → 0.17.0

package/dist/functions.d.ts

@@ -1,7 +1,9 @@
 /**
- * Scripts API for ekoDB TypeScript client
+ * Functions API for ekoDB TypeScript client
  */
-export interface Script {
+/** A reusable sequence of Functions stored in ekoDB. */
+export interface UserFunction {
+    id?: string;
     label: string;
     name: string;
     description?: string;
@@ -140,7 +142,7 @@ export type FunctionStageConfig = {
     value: any;
 } | {
     type: "If";
-    condition: ScriptCondition;
+    condition: FunctionCondition;
     then_functions: FunctionStageConfig[];
     else_functions?: FunctionStageConfig[];
 } | {
@@ -205,6 +207,72 @@ export type FunctionStageConfig = {
     timeout_seconds?: number;
     output_field?: string;
     collection?: string;
+} | {
+    /**
+     * Bcrypt-hash a plaintext value and add the result to every record in
+     * the working data as `output_field`. Requires ekoDB >= 0.41.0.
+     */
+    type: "BcryptHash";
+    plain: string;
+    cost?: number;
+    output_field: string;
+} | {
+    /**
+     * Verify a plaintext against a bcrypt hash stored on the first record
+     * in the working data and write a boolean result into `output_field`.
+     * Pair with an `If` stage for login flows. Requires ekoDB >= 0.41.0.
+     */
+    type: "BcryptVerify";
+    plain: string;
+    hash_field: string;
+    output_field: string;
+} | {
+    /**
+     * Generate a cryptographically-random token and add it to every
+     * record in the working data. Requires ekoDB >= 0.41.0.
+     */
+    type: "RandomToken";
+    bytes: number;
+    encoding?: "hex" | "base64" | "base64url";
+    output_field: string;
+} | {
+    /**
+     * Try/Catch error handling for graceful failure recovery.
+     * Executes try_functions, and if any fail, executes catch_functions.
+     */
+    type: "TryCatch";
+    try_functions: FunctionStageConfig[];
+    catch_functions: FunctionStageConfig[];
+    output_error_field?: string;
+} | {
+    /**
+     * Execute multiple functions in parallel (concurrently).
+     * All functions run simultaneously, results are merged.
+     */
+    type: "Parallel";
+    functions: FunctionStageConfig[];
+    wait_for_all: boolean;
+} | {
+    /** Sleep/delay execution for rate limiting or timing control. */
+    type: "Sleep";
+    duration_ms: string | number;
+} | {
+    /**
+     * Return a shaped response (final output formatting).
+     * Constructs the final response object from current execution context.
+     */
+    type: "Return";
+    fields: Record<string, any>;
+    status_code?: number;
+} | {
+    /**
+     * Validate data against a JSON schema before processing.
+     * Prevents invalid data from corrupting database or causing errors downstream.
+     */
+    type: "Validate";
+    schema: Record<string, any>;
+    data_field: string;
+    on_error?: FunctionStageConfig[];
 };
 export interface ChatMessage {
     role: string;
@@ -224,7 +292,7 @@ export interface SortFieldConfig {
     field: string;
     ascending: boolean;
 }
-export type ScriptCondition = {
+export type FunctionCondition = {
     type: "FieldEquals";
     value: {
         field: string;
@@ -255,17 +323,17 @@ export type ScriptCondition = {
 } | {
     type: "And";
     value: {
-        conditions: ScriptCondition[];
+        conditions: FunctionCondition[];
     };
 } | {
     type: "Or";
     value: {
-        conditions: ScriptCondition[];
+        conditions: FunctionCondition[];
     };
 } | {
     type: "Not";
     value: {
-        condition: ScriptCondition;
+        condition: FunctionCondition;
     };
 };
 export interface FunctionResult {
@@ -285,15 +353,56 @@ export interface StageStats {
     output_count: number;
     execution_time_ms: number;
 }
+/**
+ * Reference a call-time function parameter inside a stored-function stage
+ * body (Insert.record, Update.updates, UpdateById.updates,
+ * FindOneAndUpdate.updates, BatchInsert.records, or any nested JSON value).
+ *
+ * Returns the structural placeholder `{"type": "Parameter", "name": "<name>"}`.
+ * ekoDB's `resolve_json_parameters` recognizes this shape and substitutes the
+ * actual parameter value at execution time, preserving the original FieldType
+ * (Binary, DateTime, UUID, Decimal, Duration, Number, Set, Vector) via the
+ * `{type,value}` wrapped form. Safe to use for any type.
+ *
+ * This is the structural alternative to the text-level `"{{name}}"` form;
+ * both are accepted but structural placeholders are preferred when the
+ * parameter is a whole-object Record or a value whose type would be lost in
+ * raw JSON.
+ *
+ * @example
+ * ```ts
+ * const createUser: UserFunction = {
+ *   label: "users_create",
+ *   name: "Create user",
+ *   parameters: {
+ *     record: { required: true },
+ *   },
+ *   functions: [
+ *     Stage.insert("users", Stage.param("record")),
+ *   ],
+ * };
+ * ```
+ */
+export interface ParameterRef {
+    type: "Parameter";
+    name: string;
+}
+export declare function parameterRef(name: string): ParameterRef;
 export declare const Stage: {
+    /**
+     * Shorthand for `parameterRef(name)` — builds the structural placeholder
+     * `{"type": "Parameter", "name": name}`. See `parameterRef` for the full
+     * explanation and example.
+     */
+    param: (name: string) => ParameterRef;
     findAll: (collection: string) => FunctionStageConfig;
     query: (collection: string, filter?: Record<string, any>, sort?: SortFieldConfig[], limit?: number, skip?: number) => FunctionStageConfig;
     project: (fields: string[], exclude?: boolean) => FunctionStageConfig;
     group: (by_fields: string[], functions: GroupFunctionConfig[]) => FunctionStageConfig;
     count: (output_field?: string) => FunctionStageConfig;
-    insert: (collection: string, record: Record<string, any>, bypassRipple?: boolean, ttl?: number) => FunctionStageConfig;
-    update: (collection: string, filter: Record<string, any>, updates: Record<string, any>, bypassRipple?: boolean, ttl?: number) => FunctionStageConfig;
-    updateById: (collection: string, record_id: string, updates: Record<string, any>, bypassRipple?: boolean, ttl?: number) => FunctionStageConfig;
+    insert: (collection: string, record: Record<string, any> | ParameterRef, bypassRipple?: boolean, ttl?: number) => FunctionStageConfig;
+    update: (collection: string, filter: Record<string, any>, updates: Record<string, any> | ParameterRef, bypassRipple?: boolean, ttl?: number) => FunctionStageConfig;
+    updateById: (collection: string, record_id: string, updates: Record<string, any> | ParameterRef, bypassRipple?: boolean, ttl?: number) => FunctionStageConfig;
     delete: (collection: string, filter: Record<string, any>, bypassRipple?: boolean) => FunctionStageConfig;
     deleteById: (collection: string, record_id: string, bypassRipple?: boolean) => FunctionStageConfig;
     batchInsert: (collection: string, records: Record<string, any>[], bypassRipple?: boolean) => FunctionStageConfig;
@@ -314,10 +423,10 @@ export declare const Stage: {
     embed: (input_field: string, output_field: string, model?: string) => FunctionStageConfig;
     findById: (collection: string, record_id: string) => FunctionStageConfig;
     findOne: (collection: string, key: string, value: any) => FunctionStageConfig;
-    if: (condition: ScriptCondition, thenFunctions: FunctionStageConfig[], elseFunctions?: FunctionStageConfig[]) => FunctionStageConfig;
+    if: (condition: FunctionCondition, thenFunctions: FunctionStageConfig[], elseFunctions?: FunctionStageConfig[]) => FunctionStageConfig;
     forEach: (functions: FunctionStageConfig[]) => FunctionStageConfig;
     callFunction: (function_label: string, params?: Record<string, any>) => FunctionStageConfig;
-    findOneAndUpdate: (collection: string, record_id: string, updates: Record<string, any>, bypassRipple?: boolean, ttl?: number) => FunctionStageConfig;
+    findOneAndUpdate: (collection: string, record_id: string, updates: Record<string, any> | ParameterRef, bypassRipple?: boolean, ttl?: number) => FunctionStageConfig;
     updateWithAction: (collection: string, record_id: string, action: string, field: string, value: any, bypassRipple?: boolean) => FunctionStageConfig;
     createSavepoint: (name: string) => FunctionStageConfig;
     rollbackToSavepoint: (name: string) => FunctionStageConfig;
@@ -342,4 +451,75 @@ export declare const Stage: {
      * @param collection - Optional collection for audit trail storage
      */
     swr: (cache_key: string, ttl: string | number, url: string, method?: string, headers?: Record<string, string>, body?: any, timeout_seconds?: number, output_field?: string, collection?: string) => FunctionStageConfig;
+    /**
+     * Bcrypt-hash a plaintext value and write the result into every record
+     * in the working data as `output_field`. Requires ekoDB >= 0.41.0.
+     *
+     * @param plain - Plaintext to hash. Typically a `"{{password}}"`
+     *   placeholder that the substituter replaces with the call-time param
+     *   before this stage runs.
+     * @param output_field - Field name to write the bcrypt hash into.
+     * @param cost - bcrypt cost factor (4..=31). Defaults to 12 when undefined.
+     */
+    bcryptHash: (plain: string, output_field: string, cost?: number) => FunctionStageConfig;
+    /**
+     * Verify a plaintext against a bcrypt hash stored on the first record in
+     * the working data. Writes a boolean into `output_field` on every
+     * working record. Pair with `Stage.if` to branch on success / failure.
+     * Requires ekoDB >= 0.41.0.
+     *
+     * @param plain - Plaintext to verify (typically `"{{password}}"`).
+     * @param hash_field - Name of the field on the current record that
+     *   holds the stored bcrypt hash (e.g. `"password_hash"`).
+     * @param output_field - Field name to write the boolean result into.
+     */
+    bcryptVerify: (plain: string, hash_field: string, output_field: string) => FunctionStageConfig;
+    /**
+     * Generate a cryptographically-random token and add it to every record
+     * in the working data. Requires ekoDB >= 0.41.0.
+     *
+     * @param bytes - Number of random bytes to draw (1..=1024).
+     * @param output_field - Field name to write the encoded token into.
+     * @param encoding - `"hex"` (default) | `"base64"` | `"base64url"`.
+     */
+    randomToken: (bytes: number, output_field: string, encoding?: "hex" | "base64" | "base64url") => FunctionStageConfig;
+    /**
+     * Try/Catch error handling for graceful failure recovery.
+     * Executes tryFunctions, and if any fail, executes catchFunctions.
+     *
+     * @param tryFunctions - Functions to attempt.
+     * @param catchFunctions - Functions to execute on failure.
+     * @param outputErrorField - Field name to store error details (default: "error").
+     */
+    tryCatch: (tryFunctions: FunctionStageConfig[], catchFunctions: FunctionStageConfig[], outputErrorField?: string) => FunctionStageConfig;
+    /**
+     * Execute multiple functions in parallel (concurrently).
+     * All functions run simultaneously, results are merged.
+     *
+     * @param functions - Functions to execute concurrently.
+     * @param waitForAll - true = wait for all to complete, false = return on first completion.
+     */
+    parallel: (functions: FunctionStageConfig[], waitForAll?: boolean) => FunctionStageConfig;
+    /**
+     * Sleep/delay execution for rate limiting or timing control.
+     *
+     * @param durationMs - Duration in milliseconds: `1000` or `"{{delay_param}}"`.
+     */
+    sleep: (durationMs: string | number) => FunctionStageConfig;
+    /**
+     * Return a shaped response (final output formatting).
+     * Constructs the final response object from current execution context.
+     *
+     * @param fields - Fields to include in response with `{{param}}` substitution.
+     * @param statusCode - HTTP status code (default: 200).
+     */
+    returnResponse: (fields: Record<string, any>, statusCode?: number) => FunctionStageConfig;
+    /**
+     * Validate data against a JSON schema before processing.
+     *
+     * @param schema - JSON Schema to validate against.
+     * @param dataField - Field containing data to validate.
+     * @param onError - Functions to execute on validation failure.
+     */
+    validate: (schema: Record<string, any>, dataField: string, onError?: FunctionStageConfig[]) => FunctionStageConfig;
 };

package/dist/functions.js

@@ -1,9 +1,10 @@
 "use strict";
 /**
- * Scripts API for ekoDB TypeScript client
+ * Functions API for ekoDB TypeScript client
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Stage = exports.ChatMessage = void 0;
+exports.parameterRef = parameterRef;
 exports.ChatMessage = {
     system: (content) => ({
         role: "system",
@@ -18,8 +19,17 @@ exports.ChatMessage = {
         content: content,
     }),
 };
+function parameterRef(name) {
+    return { type: "Parameter", name };
+}
 // Stage builder functions
 exports.Stage = {
+    /**
+     * Shorthand for `parameterRef(name)` — builds the structural placeholder
+     * `{"type": "Parameter", "name": name}`. See `parameterRef` for the full
+     * explanation and example.
+     */
+    param: (name) => parameterRef(name),
     findAll: (collection) => ({
         type: "FindAll",
         collection,
@@ -258,4 +268,111 @@ exports.Stage = {
         output_field,
         collection,
     }),
+    /**
+     * Bcrypt-hash a plaintext value and write the result into every record
+     * in the working data as `output_field`. Requires ekoDB >= 0.41.0.
+     *
+     * @param plain - Plaintext to hash. Typically a `"{{password}}"`
+     *   placeholder that the substituter replaces with the call-time param
+     *   before this stage runs.
+     * @param output_field - Field name to write the bcrypt hash into.
+     * @param cost - bcrypt cost factor (4..=31). Defaults to 12 when undefined.
+     */
+    bcryptHash: (plain, output_field, cost) => ({
+        type: "BcryptHash",
+        plain,
+        cost,
+        output_field,
+    }),
+    /**
+     * Verify a plaintext against a bcrypt hash stored on the first record in
+     * the working data. Writes a boolean into `output_field` on every
+     * working record. Pair with `Stage.if` to branch on success / failure.
+     * Requires ekoDB >= 0.41.0.
+     *
+     * @param plain - Plaintext to verify (typically `"{{password}}"`).
+     * @param hash_field - Name of the field on the current record that
+     *   holds the stored bcrypt hash (e.g. `"password_hash"`).
+     * @param output_field - Field name to write the boolean result into.
+     */
+    bcryptVerify: (plain, hash_field, output_field) => ({
+        type: "BcryptVerify",
+        plain,
+        hash_field,
+        output_field,
+    }),
+    /**
+     * Generate a cryptographically-random token and add it to every record
+     * in the working data. Requires ekoDB >= 0.41.0.
+     *
+     * @param bytes - Number of random bytes to draw (1..=1024).
+     * @param output_field - Field name to write the encoded token into.
+     * @param encoding - `"hex"` (default) | `"base64"` | `"base64url"`.
+     */
+    randomToken: (bytes, output_field, encoding) => ({
+        type: "RandomToken",
+        bytes,
+        encoding,
+        output_field,
+    }),
+    /**
+     * Try/Catch error handling for graceful failure recovery.
+     * Executes tryFunctions, and if any fail, executes catchFunctions.
+     *
+     * @param tryFunctions - Functions to attempt.
+     * @param catchFunctions - Functions to execute on failure.
+     * @param outputErrorField - Field name to store error details (default: "error").
+     */
+    tryCatch: (tryFunctions, catchFunctions, outputErrorField) => ({
+        type: "TryCatch",
+        try_functions: tryFunctions,
+        catch_functions: catchFunctions,
+        output_error_field: outputErrorField,
+    }),
+    /**
+     * Execute multiple functions in parallel (concurrently).
+     * All functions run simultaneously, results are merged.
+     *
+     * @param functions - Functions to execute concurrently.
+     * @param waitForAll - true = wait for all to complete, false = return on first completion.
+     */
+    parallel: (functions, waitForAll = true) => ({
+        type: "Parallel",
+        functions,
+        wait_for_all: waitForAll,
+    }),
+    /**
+     * Sleep/delay execution for rate limiting or timing control.
+     *
+     * @param durationMs - Duration in milliseconds: `1000` or `"{{delay_param}}"`.
+     */
+    sleep: (durationMs) => ({
+        type: "Sleep",
+        duration_ms: durationMs,
+    }),
+    /**
+     * Return a shaped response (final output formatting).
+     * Constructs the final response object from current execution context.
+     *
+     * @param fields - Fields to include in response with `{{param}}` substitution.
+     * @param statusCode - HTTP status code (default: 200).
+     */
+    returnResponse: (fields, statusCode) => ({
+        type: "Return",
+        fields,
+        status_code: statusCode,
+    }),
+    /**
+     * Validate data against a JSON schema before processing.
+     *
+     * @param schema - JSON Schema to validate against.
+     * @param dataField - Field containing data to validate.
+     * @param onError - Functions to execute on validation failure.
+     */
+    validate: (schema, dataField, onError) => ({
+        type: "Validate",
+        schema,
+        data_field: dataField,
+        on_error: onError,
+    }),
 };

package/dist/functions.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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`.
+ */
+export {};