@ekodb/ekodb-client 0.1.0

package/dist/schema.d.ts

@@ -0,0 +1,189 @@
+/**
+ * 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 declare 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 declare 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 declare class FieldTypeSchemaBuilder {
+    private schema;
+    constructor(fieldType: string);
+    /**
+     * Set the field as required
+     */
+    required(): this;
+    /**
+     * Set the field as unique
+     */
+    unique(): this;
+    /**
+     * Set a default value
+     */
+    defaultValue(value: any): this;
+    /**
+     * Set enum values
+     */
+    enums(values: any[]): this;
+    /**
+     * Set min/max range
+     */
+    range(min?: any, max?: any): this;
+    /**
+     * Set regex pattern
+     */
+    pattern(regex: string): this;
+    /**
+     * Add a text index
+     */
+    textIndex(language?: string, analyzer?: string): this;
+    /**
+     * Add a vector index
+     */
+    vectorIndex(algorithm?: VectorIndexAlgorithm, metric?: DistanceMetric, m?: number, efConstruction?: number): this;
+    /**
+     * Add a B-tree index
+     */
+    btreeIndex(): this;
+    /**
+     * Add a hash index
+     */
+    hashIndex(): this;
+    /**
+     * Build the final FieldTypeSchema
+     */
+    build(): FieldTypeSchema;
+}
+/**
+ * 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 declare class SchemaBuilder {
+    private schema;
+    constructor();
+    /**
+     * Add a field to the schema
+     */
+    addField(name: string, field: FieldTypeSchema | FieldTypeSchemaBuilder): this;
+    /**
+     * Set bypass_ripple flag
+     */
+    bypassRipple(bypass: boolean): this;
+    /**
+     * Set schema version
+     */
+    version(version: number): this;
+    /**
+     * Build the final Schema
+     */
+    build(): Schema;
+}

package/dist/schema.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * Schema management for collections
+ *
+ * This module provides types and utilities for defining and managing
+ * collection schemas with field types, constraints, and indexes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaBuilder = exports.FieldTypeSchemaBuilder = exports.DistanceMetric = exports.VectorIndexAlgorithm = void 0;
+/**
+ * Vector index algorithm
+ */
+var VectorIndexAlgorithm;
+(function (VectorIndexAlgorithm) {
+    /** Simple flat index (brute force) */
+    VectorIndexAlgorithm["Flat"] = "flat";
+    /** Hierarchical Navigable Small World */
+    VectorIndexAlgorithm["HNSW"] = "hnsw";
+    /** Inverted File Index (for future) */
+    VectorIndexAlgorithm["IVF"] = "ivf";
+})(VectorIndexAlgorithm || (exports.VectorIndexAlgorithm = VectorIndexAlgorithm = {}));
+/**
+ * Distance metric for vector similarity
+ */
+var DistanceMetric;
+(function (DistanceMetric) {
+    DistanceMetric["Cosine"] = "cosine";
+    DistanceMetric["Euclidean"] = "euclidean";
+    DistanceMetric["DotProduct"] = "dotproduct";
+})(DistanceMetric || (exports.DistanceMetric = DistanceMetric = {}));
+/**
+ * Builder for constructing field type schemas
+ *
+ * @example
+ * ```typescript
+ * const field = new FieldTypeSchemaBuilder("string")
+ *   .required()
+ *   .unique()
+ *   .pattern("^[a-z]+$")
+ *   .build();
+ * ```
+ */
+class FieldTypeSchemaBuilder {
+    constructor(fieldType) {
+        this.schema = { field_type: fieldType };
+    }
+    /**
+     * Set the field as required
+     */
+    required() {
+        this.schema.required = true;
+        return this;
+    }
+    /**
+     * Set the field as unique
+     */
+    unique() {
+        this.schema.unique = true;
+        return this;
+    }
+    /**
+     * Set a default value
+     */
+    defaultValue(value) {
+        this.schema.default = value;
+        return this;
+    }
+    /**
+     * Set enum values
+     */
+    enums(values) {
+        this.schema.enums = values;
+        return this;
+    }
+    /**
+     * Set min/max range
+     */
+    range(min, max) {
+        this.schema.min = min;
+        this.schema.max = max;
+        return this;
+    }
+    /**
+     * Set regex pattern
+     */
+    pattern(regex) {
+        this.schema.regex = regex;
+        return this;
+    }
+    /**
+     * Add a text index
+     */
+    textIndex(language = "english", analyzer) {
+        this.schema.index = {
+            type: "text",
+            language,
+            analyzer,
+        };
+        return this;
+    }
+    /**
+     * Add a vector index
+     */
+    vectorIndex(algorithm = VectorIndexAlgorithm.Flat, metric = DistanceMetric.Cosine, m = 16, efConstruction = 200) {
+        this.schema.index = {
+            type: "vector",
+            algorithm,
+            metric,
+            m,
+            ef_construction: efConstruction,
+        };
+        return this;
+    }
+    /**
+     * Add a B-tree index
+     */
+    btreeIndex() {
+        this.schema.index = { type: "btree" };
+        return this;
+    }
+    /**
+     * Add a hash index
+     */
+    hashIndex() {
+        this.schema.index = { type: "hash" };
+        return this;
+    }
+    /**
+     * Build the final FieldTypeSchema
+     */
+    build() {
+        return this.schema;
+    }
+}
+exports.FieldTypeSchemaBuilder = FieldTypeSchemaBuilder;
+/**
+ * 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);
+ * ```
+ */
+class SchemaBuilder {
+    constructor() {
+        this.schema = {
+            fields: {},
+            version: 1,
+            bypass_ripple: true,
+        };
+    }
+    /**
+     * Add a field to the schema
+     */
+    addField(name, field) {
+        this.schema.fields[name] = field instanceof FieldTypeSchemaBuilder ? field.build() : field;
+        return this;
+    }
+    /**
+     * Set bypass_ripple flag
+     */
+    bypassRipple(bypass) {
+        this.schema.bypass_ripple = bypass;
+        return this;
+    }
+    /**
+     * Set schema version
+     */
+    version(version) {
+        this.schema.version = version;
+        return this;
+    }
+    /**
+     * Build the final Schema
+     */
+    build() {
+        return this.schema;
+    }
+}
+exports.SchemaBuilder = SchemaBuilder;

package/dist/search.d.ts

@@ -0,0 +1,172 @@
+/**
+ * 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;
+    /** 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;
+    /** 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 declare class SearchQueryBuilder {
+    private query;
+    constructor(queryString: string);
+    /**
+     * Set the language for stemming
+     */
+    language(language: string): this;
+    /**
+     * Enable case-sensitive search
+     */
+    caseSensitive(enabled?: boolean): this;
+    /**
+     * Enable fuzzy matching
+     */
+    fuzzy(enabled?: boolean): this;
+    /**
+     * Set minimum score threshold
+     */
+    minScore(score: number): this;
+    /**
+     * Set fields to search in
+     */
+    fields(fields: string | string[]): this;
+    /**
+     * Set field weights
+     */
+    weights(weights: string | Record<string, number>): this;
+    /**
+     * Enable stemming
+     */
+    enableStemming(enabled?: boolean): this;
+    /**
+     * Boost exact matches
+     */
+    boostExact(enabled?: boolean): this;
+    /**
+     * Set maximum edit distance for fuzzy matching
+     */
+    maxEditDistance(distance: number): this;
+    /**
+     * Set query vector for semantic search
+     */
+    vector(vector: number[]): this;
+    /**
+     * Set vector field name
+     */
+    vectorField(field: string): this;
+    /**
+     * Set vector similarity metric
+     */
+    vectorMetric(metric: "cosine" | "euclidean" | "dotproduct"): this;
+    /**
+     * Set number of vector results (k-nearest neighbors)
+     */
+    vectorK(k: number): this;
+    /**
+     * Set minimum similarity threshold
+     */
+    vectorThreshold(threshold: number): this;
+    /**
+     * Set text search weight for hybrid search
+     */
+    textWeight(weight: number): this;
+    /**
+     * Set vector search weight for hybrid search
+     */
+    vectorWeight(weight: number): this;
+    /**
+     * Bypass ripple cache
+     */
+    bypassRipple(bypass?: boolean): this;
+    /**
+     * Bypass cache
+     */
+    bypassCache(bypass?: boolean): this;
+    /**
+     * Set maximum number of results to return
+     */
+    limit(limit: number): this;
+    /**
+     * Build the final SearchQuery object
+     */
+    build(): SearchQuery;
+}