@ekodb/ekodb-client 0.2.1 → 0.4.0

package/src/functions.ts

@@ -0,0 +1,420 @@
+/**
+ * Scripts API for ekoDB TypeScript client
+ */
+
+export interface Script {
+  label: string;
+  name: string;
+  description?: string;
+  version: string;
+  parameters: { [key: string]: ParameterDefinition };
+  functions: FunctionStageConfig[];
+  tags: string[];
+  created_at?: string;
+  updated_at?: string;
+}
+
+export interface ParameterDefinition {
+  required: boolean;
+  default?: any;
+  description?: string;
+  param_type?: string;
+}
+
+// ParameterValue removed - use plain values instead
+
+export type FunctionStageConfig =
+  | { type: "FindAll"; collection: string }
+  | {
+      type: "Query";
+      collection: string;
+      filter?: Record<string, any>;
+      sort?: SortFieldConfig[];
+      limit?: number;
+      skip?: number;
+    }
+  | { type: "Project"; fields: string[]; exclude: boolean }
+  | {
+      type: "Group";
+      by_fields: string[];
+      functions: GroupFunctionConfig[];
+    }
+  | { type: "Count"; output_field: string }
+  | { type: "Filter"; filter: Record<string, any> }
+  | { type: "Sort"; sort: SortFieldConfig[] }
+  | { type: "Limit"; limit: number }
+  | { type: "Skip"; skip: number }
+  | {
+      type: "Insert";
+      collection: string;
+      record: Record<string, any>;
+      bypass_ripple?: boolean;
+      ttl?: number;
+    }
+  | {
+      type: "Update";
+      collection: string;
+      filter: Record<string, any>;
+      updates: Record<string, any>;
+      bypass_ripple?: boolean;
+      ttl?: number;
+    }
+  | {
+      type: "UpdateById";
+      collection: string;
+      record_id: string;
+      updates: Record<string, any>;
+      bypass_ripple?: boolean;
+      ttl?: number;
+    }
+  | {
+      type: "Delete";
+      collection: string;
+      filter: Record<string, any>;
+      bypass_ripple?: boolean;
+    }
+  | {
+      type: "DeleteById";
+      collection: string;
+      record_id: string;
+      bypass_ripple?: boolean;
+    }
+  | {
+      type: "BatchInsert";
+      collection: string;
+      records: Record<string, any>[];
+      bypass_ripple?: boolean;
+    }
+  | {
+      type: "BatchDelete";
+      collection: string;
+      record_ids: string[];
+      bypass_ripple?: boolean;
+    }
+  | {
+      type: "HttpRequest";
+      url: string;
+      method?: string;
+      headers?: Record<string, string>;
+      body?: any;
+    }
+  | {
+      type: "VectorSearch";
+      collection: string;
+      query_vector: number[];
+      limit?: number;
+      threshold?: number;
+    }
+  | {
+      type: "TextSearch";
+      collection: string;
+      query_text: string;
+      fields?: string[];
+      limit?: number;
+      fuzzy?: boolean;
+    }
+  | {
+      type: "HybridSearch";
+      collection: string;
+      query_text: string;
+      query_vector?: number[];
+      limit?: number;
+    }
+  | {
+      type: "Chat";
+      messages: ChatMessage[];
+      model?: string;
+      temperature?: number;
+      max_tokens?: number;
+    }
+  | {
+      type: "Embed";
+      input_field: string;
+      output_field: string;
+      model?: string;
+    };
+
+export interface ChatMessage {
+  role: string;
+  content: string;
+}
+
+export const ChatMessage = {
+  system: (content: string): ChatMessage => ({
+    role: "system",
+    content: content,
+  }),
+  user: (content: string): ChatMessage => ({
+    role: "user",
+    content: content,
+  }),
+  assistant: (content: string): ChatMessage => ({
+    role: "assistant",
+    content: content,
+  }),
+};
+
+export interface GroupFunctionConfig {
+  output_field: string;
+  operation:
+    | "Sum"
+    | "Average"
+    | "Count"
+    | "Min"
+    | "Max"
+    | "First"
+    | "Last"
+    | "Push";
+  input_field?: string;
+}
+
+export interface SortFieldConfig {
+  field: string;
+  ascending: boolean;
+}
+
+export interface FunctionResult {
+  records: Record<string, any>[];
+  stats: FunctionStats;
+}
+
+export interface FunctionStats {
+  input_count: number;
+  output_count: number;
+  execution_time_ms: number;
+  stages_executed: number;
+  stage_stats: StageStats[];
+}
+
+export interface StageStats {
+  stage: string;
+  input_count: number;
+  output_count: number;
+  execution_time_ms: number;
+}
+
+// Stage builder functions
+export const Stage = {
+  findAll: (collection: string): FunctionStageConfig => ({
+    type: "FindAll",
+    collection,
+  }),
+
+  query: (
+    collection: string,
+    filter?: Record<string, any>,
+    sort?: SortFieldConfig[],
+    limit?: number,
+    skip?: number,
+  ): FunctionStageConfig => ({
+    type: "Query",
+    collection,
+    filter,
+    sort,
+    limit,
+    skip,
+  }),
+
+  project: (fields: string[], exclude = false): FunctionStageConfig => ({
+    type: "Project",
+    fields,
+    exclude,
+  }),
+
+  group: (
+    by_fields: string[],
+    functions: GroupFunctionConfig[],
+  ): FunctionStageConfig => ({
+    type: "Group",
+    by_fields,
+    functions,
+  }),
+
+  count: (output_field = "count"): FunctionStageConfig => ({
+    type: "Count",
+    output_field,
+  }),
+
+  insert: (
+    collection: string,
+    record: Record<string, any>,
+    bypassRipple = false,
+    ttl?: number,
+  ): FunctionStageConfig => ({
+    type: "Insert",
+    collection,
+    record,
+    bypass_ripple: bypassRipple,
+    ttl,
+  }),
+
+  update: (
+    collection: string,
+    filter: Record<string, any>,
+    updates: Record<string, any>,
+    bypassRipple = false,
+    ttl?: number,
+  ): FunctionStageConfig => ({
+    type: "Update",
+    collection,
+    filter,
+    updates,
+    bypass_ripple: bypassRipple,
+    ttl,
+  }),
+
+  updateById: (
+    collection: string,
+    record_id: string,
+    updates: Record<string, any>,
+    bypassRipple = false,
+    ttl?: number,
+  ): FunctionStageConfig => ({
+    type: "UpdateById",
+    collection,
+    record_id,
+    updates,
+    bypass_ripple: bypassRipple,
+    ttl,
+  }),
+
+  delete: (
+    collection: string,
+    filter: Record<string, any>,
+    bypassRipple = false,
+  ): FunctionStageConfig => ({
+    type: "Delete",
+    collection,
+    filter,
+    bypass_ripple: bypassRipple,
+  }),
+
+  deleteById: (
+    collection: string,
+    record_id: string,
+    bypassRipple = false,
+  ): FunctionStageConfig => ({
+    type: "DeleteById",
+    collection,
+    record_id,
+    bypass_ripple: bypassRipple,
+  }),
+
+  batchInsert: (
+    collection: string,
+    records: Record<string, any>[],
+    bypassRipple = false,
+  ): FunctionStageConfig => ({
+    type: "BatchInsert",
+    collection,
+    records,
+    bypass_ripple: bypassRipple,
+  }),
+
+  batchDelete: (
+    collection: string,
+    record_ids: string[],
+    bypassRipple = false,
+  ): FunctionStageConfig => ({
+    type: "BatchDelete",
+    collection,
+    record_ids,
+    bypass_ripple: bypassRipple,
+  }),
+
+  filter: (filter: Record<string, any>): FunctionStageConfig => ({
+    type: "Filter",
+    filter,
+  }),
+
+  sort: (sort: SortFieldConfig[]): FunctionStageConfig => ({
+    type: "Sort",
+    sort,
+  }),
+
+  limit: (limit: number): FunctionStageConfig => ({
+    type: "Limit",
+    limit,
+  }),
+
+  skip: (skip: number): FunctionStageConfig => ({
+    type: "Skip",
+    skip,
+  }),
+
+  httpRequest: (
+    url: string,
+    method = "GET",
+    headers?: Record<string, string>,
+    body?: any,
+  ): FunctionStageConfig => ({
+    type: "HttpRequest",
+    url,
+    method,
+    headers,
+    body,
+  }),
+
+  vectorSearch: (
+    collection: string,
+    query_vector: number[],
+    limit?: number,
+    threshold?: number,
+  ): FunctionStageConfig => ({
+    type: "VectorSearch",
+    collection,
+    query_vector,
+    limit,
+    threshold,
+  }),
+
+  textSearch: (
+    collection: string,
+    query_text: string,
+    options?: { fields?: string[]; limit?: number; fuzzy?: boolean },
+  ): FunctionStageConfig => ({
+    type: "TextSearch",
+    collection,
+    query_text,
+    fields: options?.fields,
+    limit: options?.limit,
+    fuzzy: options?.fuzzy,
+  }),
+
+  hybridSearch: (
+    collection: string,
+    query_text: string,
+    query_vector?: number[],
+    limit?: number,
+  ): FunctionStageConfig => ({
+    type: "HybridSearch",
+    collection,
+    query_text,
+    query_vector,
+    limit,
+  }),
+
+  chat: (
+    messages: ChatMessage[],
+    model?: string,
+    temperature?: number,
+    max_tokens?: number,
+  ): FunctionStageConfig => ({
+    type: "Chat",
+    messages,
+    model,
+    temperature,
+    max_tokens,
+  }),
+
+  embed: (
+    input_field: string,
+    output_field: string,
+    model?: string,
+  ): FunctionStageConfig => ({
+    type: "Embed",
+    input_field,
+    output_field,
+    model,
+  }),
+};

package/src/index.ts

@@ -1,6 +1,7 @@
 export {
   EkoDBClient,
   WebSocketClient,
+  SerializationFormat,
   MergeStrategy,
   RateLimitError,
 } from "./client";
@@ -13,6 +14,7 @@ export {
   DistanceMetric,
 } from "./schema";
 export { JoinBuilder } from "./join";
+export { Stage, ChatMessage } from "./functions";
 export type { SearchQuery, SearchResult, SearchResponse } from "./search";
 export type {
   Schema,
@@ -21,6 +23,16 @@ export type {
   CollectionMetadata,
 } from "./schema";
 export type { JoinConfig } from "./join";
+export type {
+  Script,
+  ParameterDefinition,
+  FunctionStageConfig,
+  GroupFunctionConfig,
+  SortFieldConfig,
+  FunctionResult,
+  FunctionStats,
+  StageStats,
+} from "./functions";
 export type {
   Record,
   Query,