@ekodb/ekodb-client 0.1.0

package/src/schema.ts

@@ -0,0 +1,285 @@
+/**
+ * Schema management for collections
+ * 
+ * This module provides types and utilities for defining and managing
+ * collection schemas with field types, constraints, and indexes.
+ */
+
+/**
+ * Vector index algorithm
+ */
+export enum VectorIndexAlgorithm {
+  /** Simple flat index (brute force) */
+  Flat = "flat",
+  /** Hierarchical Navigable Small World */
+  HNSW = "hnsw",
+  /** Inverted File Index (for future) */
+  IVF = "ivf",
+}
+
+/**
+ * Distance metric for vector similarity
+ */
+export enum DistanceMetric {
+  Cosine = "cosine",
+  Euclidean = "euclidean",
+  DotProduct = "dotproduct",
+}
+
+/**
+ * Index configuration for a field
+ */
+export type IndexConfig =
+  | {
+      type: "text";
+      language?: string;
+      analyzer?: string;
+    }
+  | {
+      type: "vector";
+      algorithm?: VectorIndexAlgorithm;
+      metric?: DistanceMetric;
+      m?: number;
+      ef_construction?: number;
+    }
+  | {
+      type: "btree";
+    }
+  | {
+      type: "hash";
+    };
+
+/**
+ * Field type schema with constraints
+ * 
+ * Valid field types (case-sensitive):
+ * - String, Integer, Float, Boolean, DateTime
+ * - Array, Object, Vector, Set
+ * - UUID, Decimal, Binary, Bytes, Duration, Number, Null
+ */
+export interface FieldTypeSchema {
+  /** Field type - must be one of the valid types (case-sensitive, e.g., "String", "Integer", "Float") */
+  field_type: string;
+  /** Default value for the field */
+  default?: any;
+  /** Whether the field must be unique across records */
+  unique?: boolean;
+  /** Whether the field is required */
+  required?: boolean;
+  /** Allowed enum values */
+  enums?: any[];
+  /** Maximum value (for numbers/dates) */
+  max?: any;
+  /** Minimum value (for numbers/dates) */
+  min?: any;
+  /** Regex pattern for string validation */
+  regex?: string;
+  /** Index configuration */
+  index?: IndexConfig;
+}
+
+/**
+ * Collection schema
+ */
+export interface Schema {
+  /** Field definitions */
+  fields: Record<string, FieldTypeSchema>;
+  /** Schema version */
+  version?: number;
+  /** Creation timestamp */
+  created_at?: string;
+  /** Last modification timestamp */
+  last_modified?: string;
+  /** Whether to bypass ripple replication */
+  bypass_ripple?: boolean;
+}
+
+/**
+ * Collection metadata with analytics
+ */
+export interface CollectionMetadata {
+  /** Schema definition */
+  collection: Schema;
+  /** Analytics data (if available) */
+  analytics?: any;
+}
+
+/**
+ * Builder for constructing field type schemas
+ * 
+ * @example
+ * ```typescript
+ * const field = new FieldTypeSchemaBuilder("string")
+ *   .required()
+ *   .unique()
+ *   .pattern("^[a-z]+$")
+ *   .build();
+ * ```
+ */
+export class FieldTypeSchemaBuilder {
+  private schema: FieldTypeSchema;
+
+  constructor(fieldType: string) {
+    this.schema = { field_type: fieldType };
+  }
+
+  /**
+   * Set the field as required
+   */
+  required(): this {
+    this.schema.required = true;
+    return this;
+  }
+
+  /**
+   * Set the field as unique
+   */
+  unique(): this {
+    this.schema.unique = true;
+    return this;
+  }
+
+  /**
+   * Set a default value
+   */
+  defaultValue(value: any): this {
+    this.schema.default = value;
+    return this;
+  }
+
+  /**
+   * Set enum values
+   */
+  enums(values: any[]): this {
+    this.schema.enums = values;
+    return this;
+  }
+
+  /**
+   * Set min/max range
+   */
+  range(min?: any, max?: any): this {
+    this.schema.min = min;
+    this.schema.max = max;
+    return this;
+  }
+
+  /**
+   * Set regex pattern
+   */
+  pattern(regex: string): this {
+    this.schema.regex = regex;
+    return this;
+  }
+
+  /**
+   * Add a text index
+   */
+  textIndex(language: string = "english", analyzer?: string): this {
+    this.schema.index = {
+      type: "text",
+      language,
+      analyzer,
+    };
+    return this;
+  }
+
+  /**
+   * Add a vector index
+   */
+  vectorIndex(
+    algorithm: VectorIndexAlgorithm = VectorIndexAlgorithm.Flat,
+    metric: DistanceMetric = DistanceMetric.Cosine,
+    m: number = 16,
+    efConstruction: number = 200
+  ): this {
+    this.schema.index = {
+      type: "vector",
+      algorithm,
+      metric,
+      m,
+      ef_construction: efConstruction,
+    };
+    return this;
+  }
+
+  /**
+   * Add a B-tree index
+   */
+  btreeIndex(): this {
+    this.schema.index = { type: "btree" };
+    return this;
+  }
+
+  /**
+   * Add a hash index
+   */
+  hashIndex(): this {
+    this.schema.index = { type: "hash" };
+    return this;
+  }
+
+  /**
+   * Build the final FieldTypeSchema
+   */
+  build(): FieldTypeSchema {
+    return this.schema;
+  }
+}
+
+/**
+ * Builder for constructing collection schemas
+ * 
+ * @example
+ * ```typescript
+ * const schema = new SchemaBuilder()
+ *   .addField("name", new FieldTypeSchemaBuilder("string").required())
+ *   .addField("email", new FieldTypeSchemaBuilder("string").unique())
+ *   .addField("age", new FieldTypeSchemaBuilder("number").range(0, 150))
+ *   .build();
+ * 
+ * await client.createCollection("users", schema);
+ * ```
+ */
+export class SchemaBuilder {
+  private schema: Schema;
+
+  constructor() {
+    this.schema = {
+      fields: {},
+      version: 1,
+      bypass_ripple: true,
+    };
+  }
+
+  /**
+   * Add a field to the schema
+   */
+  addField(name: string, field: FieldTypeSchema | FieldTypeSchemaBuilder): this {
+    this.schema.fields[name] = field instanceof FieldTypeSchemaBuilder ? field.build() : field;
+    return this;
+  }
+
+  /**
+   * Set bypass_ripple flag
+   */
+  bypassRipple(bypass: boolean): this {
+    this.schema.bypass_ripple = bypass;
+    return this;
+  }
+
+  /**
+   * Set schema version
+   */
+  version(version: number): this {
+    this.schema.version = version;
+    return this;
+  }
+
+  /**
+   * Build the final Schema
+   */
+  build(): Schema {
+    return this.schema;
+  }
+}

package/src/search.ts

@@ -0,0 +1,275 @@
+/**
+ * Full-text and vector search support for ekoDB
+ * 
+ * This module provides comprehensive search capabilities including:
+ * - Full-text search with fuzzy matching
+ * - Vector/semantic search
+ * - Hybrid search (text + vector)
+ * - Field weighting and boosting
+ */
+
+export interface SearchQuery {
+  /** Search query string */
+  query: string;
+  /** Language for stemming (e.g., "english", "spanish", "french") */
+  language?: string;
+  /** Case-sensitive search */
+  case_sensitive?: boolean;
+  /** Enable fuzzy matching (typo tolerance) */
+  fuzzy?: boolean;
+  /** Minimum score threshold (0.0-1.0) */
+  min_score?: number;
+  /** Fields to search in (comma-separated or array) */
+  fields?: string | string[];
+  /** Field weights (format: "field1:2.0,field2:1.5" or object) */
+  weights?: string | Record<string, number>;
+  /** Enable stemming */
+  enable_stemming?: boolean;
+  /** Boost exact matches */
+  boost_exact?: boolean;
+  /** Maximum edit distance for fuzzy matching (0-5) */
+  max_edit_distance?: number;
+  /** Bypass ripple cache */
+  bypass_ripple?: boolean;
+  /** Bypass cache */
+  bypass_cache?: boolean;
+  /** Maximum number of results to return */
+  limit?: number;
+  
+  // Vector search parameters
+  /** Query vector for semantic search */
+  vector?: number[];
+  /** Field containing vectors (default: "embedding") */
+  vector_field?: string;
+  /** Similarity metric: "cosine", "euclidean", "dotproduct" */
+  vector_metric?: string;
+  /** Number of vector results (k-nearest neighbors) */
+  vector_k?: number;
+  /** Minimum similarity threshold */
+  vector_threshold?: number;
+  
+  // Hybrid search parameters
+  /** Weight for text search (0.0-1.0) */
+  text_weight?: number;
+  /** Weight for vector search (0.0-1.0) */
+  vector_weight?: number;
+}
+
+/**
+ * Search result with score and matched fields
+ */
+export interface SearchResult {
+  /** The matched record */
+  record: any;
+  /** Relevance score */
+  score: number;
+  /** Fields that matched the search query */
+  matched_fields: string[];
+}
+
+/**
+ * Search response containing results and metadata
+ */
+export interface SearchResponse {
+  /** Array of search results */
+  results: SearchResult[];
+  /** Total number of results found */
+  total: number;
+  /** Query execution time in milliseconds */
+  took_ms?: number;
+}
+
+/**
+ * Builder for constructing search queries with fluent API
+ * 
+ * @example
+ * ```typescript
+ * const query = new SearchQueryBuilder("john")
+ *   .fields(["name", "email"])
+ *   .fuzzy(true)
+ *   .minScore(0.5)
+ *   .limit(10)
+ *   .build();
+ * 
+ * const results = await client.search("users", query);
+ * ```
+ */
+export class SearchQueryBuilder {
+  private query: SearchQuery;
+
+  constructor(queryString: string) {
+    this.query = { query: queryString };
+  }
+
+  /**
+   * Set the language for stemming
+   */
+  language(language: string): this {
+    this.query.language = language;
+    return this;
+  }
+
+  /**
+   * Enable case-sensitive search
+   */
+  caseSensitive(enabled: boolean = true): this {
+    this.query.case_sensitive = enabled;
+    return this;
+  }
+
+  /**
+   * Enable fuzzy matching
+   */
+  fuzzy(enabled: boolean = true): this {
+    this.query.fuzzy = enabled;
+    return this;
+  }
+
+  /**
+   * Set minimum score threshold
+   */
+  minScore(score: number): this {
+    this.query.min_score = score;
+    return this;
+  }
+
+  /**
+   * Set fields to search in
+   */
+  fields(fields: string | string[]): this {
+    this.query.fields = fields;
+    return this;
+  }
+
+  /**
+   * Set field weights
+   */
+  weights(weights: string | Record<string, number>): this {
+    this.query.weights = weights;
+    return this;
+  }
+
+  /**
+   * Enable stemming
+   */
+  enableStemming(enabled: boolean = true): this {
+    this.query.enable_stemming = enabled;
+    return this;
+  }
+
+  /**
+   * Boost exact matches
+   */
+  boostExact(enabled: boolean = true): this {
+    this.query.boost_exact = enabled;
+    return this;
+  }
+
+  /**
+   * Set maximum edit distance for fuzzy matching
+   */
+  maxEditDistance(distance: number): this {
+    this.query.max_edit_distance = distance;
+    return this;
+  }
+
+  /**
+   * Set query vector for semantic search
+   */
+  vector(vector: number[]): this {
+    this.query.vector = vector;
+    return this;
+  }
+
+  /**
+   * Set vector field name
+   */
+  vectorField(field: string): this {
+    this.query.vector_field = field;
+    return this;
+  }
+
+  /**
+   * Set vector similarity metric
+   */
+  vectorMetric(metric: "cosine" | "euclidean" | "dotproduct"): this {
+    this.query.vector_metric = metric;
+    return this;
+  }
+
+  /**
+   * Set number of vector results (k-nearest neighbors)
+   */
+  vectorK(k: number): this {
+    this.query.vector_k = k;
+    return this;
+  }
+
+  /**
+   * Set minimum similarity threshold
+   */
+  vectorThreshold(threshold: number): this {
+    this.query.vector_threshold = threshold;
+    return this;
+  }
+
+  /**
+   * Set text search weight for hybrid search
+   */
+  textWeight(weight: number): this {
+    this.query.text_weight = weight;
+    return this;
+  }
+
+  /**
+   * Set vector search weight for hybrid search
+   */
+  vectorWeight(weight: number): this {
+    this.query.vector_weight = weight;
+    return this;
+  }
+
+  /**
+   * Bypass ripple cache
+   */
+  bypassRipple(bypass: boolean = true): this {
+    this.query.bypass_ripple = bypass;
+    return this;
+  }
+
+  /**
+   * Bypass cache
+   */
+  bypassCache(bypass: boolean = true): this {
+    this.query.bypass_cache = bypass;
+    return this;
+  }
+
+  /**
+   * Set maximum number of results to return
+   */
+  limit(limit: number): this {
+    this.query.limit = limit;
+    return this;
+  }
+
+  /**
+   * Build the final SearchQuery object
+   */
+  build(): SearchQuery {
+    // Normalize fields to comma-separated string if array
+    if (Array.isArray(this.query.fields)) {
+      this.query.fields = this.query.fields.join(",");
+    }
+
+    // Normalize weights to string format if object
+    if (this.query.weights && typeof this.query.weights === "object") {
+      const weightEntries = Object.entries(this.query.weights)
+        .map(([field, weight]) => `${field}:${weight}`)
+        .join(",");
+      this.query.weights = weightEntries;
+    }
+
+    return this.query;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}