@ekodb/ekodb-client 0.15.2 → 0.17.0

package/src/functions.ts

@@ -1,8 +1,10 @@
 /**
- * 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;
@@ -146,7 +148,7 @@ export type FunctionStageConfig =
     }
   | {
       type: "If";
-      condition: ScriptCondition;
+      condition: FunctionCondition;
       then_functions: FunctionStageConfig[];
       else_functions?: FunctionStageConfig[];
     }
@@ -224,6 +226,80 @@ 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 {
@@ -265,18 +341,18 @@ export interface SortFieldConfig {
   ascending: boolean;
 }
 
-// ScriptCondition uses adjacently-tagged format: { type: "...", value: { ...data } }
+// FunctionCondition uses adjacently-tagged format: { type: "...", value: { ...data } }
 // Unit variants (HasRecords) have no value field
-export type ScriptCondition =
+export type FunctionCondition =
   | { type: "FieldEquals"; value: { field: string; value: any } }
   | { type: "FieldExists"; value: { field: string } }
   | { type: "HasRecords" }
   | { type: "CountEquals"; value: { count: number } }
   | { type: "CountGreaterThan"; value: { count: number } }
   | { type: "CountLessThan"; value: { count: number } }
-  | { type: "And"; value: { conditions: ScriptCondition[] } }
-  | { type: "Or"; value: { conditions: ScriptCondition[] } }
-  | { type: "Not"; value: { condition: ScriptCondition } };
+  | { type: "And"; value: { conditions: FunctionCondition[] } }
+  | { type: "Or"; value: { conditions: FunctionCondition[] } }
+  | { type: "Not"; value: { condition: FunctionCondition } };
 
 export interface FunctionResult {
   records: Record<string, any>[];
@@ -298,8 +374,54 @@ export interface StageStats {
   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 function parameterRef(name: string): ParameterRef {
+  return { type: "Parameter", name };
+}
+
 // Stage builder functions
 export 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 => parameterRef(name),
+
   findAll: (collection: string): FunctionStageConfig => ({
     type: "FindAll",
     collection,
@@ -342,7 +464,7 @@ export const Stage = {
 
   insert: (
     collection: string,
-    record: Record<string, any>,
+    record: Record<string, any> | ParameterRef,
     bypassRipple = false,
     ttl?: number,
   ): FunctionStageConfig => ({
@@ -356,7 +478,7 @@ export const Stage = {
   update: (
     collection: string,
     filter: Record<string, any>,
-    updates: Record<string, any>,
+    updates: Record<string, any> | ParameterRef,
     bypassRipple = false,
     ttl?: number,
   ): FunctionStageConfig => ({
@@ -371,7 +493,7 @@ export const Stage = {
   updateById: (
     collection: string,
     record_id: string,
-    updates: Record<string, any>,
+    updates: Record<string, any> | ParameterRef,
     bypassRipple = false,
     ttl?: number,
   ): FunctionStageConfig => ({
@@ -541,7 +663,7 @@ export const Stage = {
   }),
 
   if: (
-    condition: ScriptCondition,
+    condition: FunctionCondition,
     thenFunctions: FunctionStageConfig[],
     elseFunctions?: FunctionStageConfig[],
   ): FunctionStageConfig => ({
@@ -568,7 +690,7 @@ export const Stage = {
   findOneAndUpdate: (
     collection: string,
     record_id: string,
-    updates: Record<string, any>,
+    updates: Record<string, any> | ParameterRef,
     bypassRipple = false,
     ttl?: number,
   ): FunctionStageConfig => ({
@@ -682,4 +804,145 @@ export const 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: string,
+    output_field: string,
+    cost?: number,
+  ): FunctionStageConfig => ({
+    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: string,
+    hash_field: string,
+    output_field: string,
+  ): FunctionStageConfig => ({
+    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: number,
+    output_field: string,
+    encoding?: "hex" | "base64" | "base64url",
+  ): FunctionStageConfig => ({
+    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: FunctionStageConfig[],
+    catchFunctions: FunctionStageConfig[],
+    outputErrorField?: string,
+  ): FunctionStageConfig => ({
+    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: FunctionStageConfig[],
+    waitForAll = true,
+  ): FunctionStageConfig => ({
+    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: string | number): FunctionStageConfig => ({
+    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: Record<string, any>,
+    statusCode?: number,
+  ): FunctionStageConfig => ({
+    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: Record<string, any>,
+    dataField: string,
+    onError?: FunctionStageConfig[],
+  ): FunctionStageConfig => ({
+    type: "Validate",
+    schema,
+    data_field: dataField,
+    on_error: onError,
+  }),
 };

package/src/index.ts

@@ -17,7 +17,8 @@ export {
   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,
@@ -44,7 +45,7 @@ export type {
 } from "./schema";
 export type { JoinConfig } from "./join";
 export type {
-  Script,
+  UserFunction,
   ParameterDefinition,
   FunctionStageConfig,
   GroupFunctionConfig,
@@ -85,7 +86,6 @@ export type {
   EmbedResponse,
   RawCompletionRequest,
   RawCompletionResponse,
-  UserFunction,
   ToolChoice,
   ToolConfig,
 } from "./client";