mongo.do 0.1.0

package/dist/durable-object/schema.d.ts

@@ -0,0 +1,192 @@
+/**
+ * SQLite Schema Management for MondoDB
+ *
+ * This module handles the initialization and management of SQLite tables
+ * for MongoDB-compatible document storage in Cloudflare Durable Objects.
+ *
+ * UNIFIED SCHEMA TYPES:
+ * This module serves as the single source of truth for all schema-related types
+ * used by both IndexManager and MondoDatabase.
+ */
+export type { IndexSpec, IndexInfo, CreateIndexOptions, CreateIndexResult, DropIndexResult, Document, InsertOneResult, InsertManyResult, DeleteResult, UpdateResult, FindOptions, CollectionMetadata, } from '../types';
+/**
+ * Current schema version - derived from migrations module
+ */
+export declare const SCHEMA_VERSION: number;
+/**
+ * Schema key used for storing version in Durable Object storage
+ */
+export declare const SCHEMA_VERSION_KEY = "schema_version";
+/**
+ * Table definitions for the schema (exported for reference/testing)
+ *
+ * UNIFIED SCHEMA: This schema supports both MondoDatabase and IndexManager:
+ * - collections table: stores collection metadata including indexes JSON
+ * - documents table: stores documents with _id as the document identifier
+ *
+ * Note: The actual table creation is handled by migrations.ts.
+ * These definitions are kept in sync for reference and testing.
+ */
+export declare const SCHEMA_TABLES: {
+    readonly collections: {
+        readonly name: "collections";
+        readonly sql: string;
+    };
+    readonly documents: {
+        readonly name: "documents";
+        readonly sql: string;
+    };
+};
+/**
+ * Index definitions for optimized queries
+ */
+export declare const SCHEMA_INDEXES: {
+    readonly documents_id: {
+        readonly name: "idx_documents_id";
+        readonly sql: "CREATE INDEX IF NOT EXISTS idx_documents_id ON documents(_id)";
+    };
+    readonly documents_collection_id: {
+        readonly name: "idx_documents_collection_id";
+        readonly sql: "CREATE INDEX IF NOT EXISTS idx_documents_collection_id ON documents(collection_id, _id)";
+    };
+};
+/**
+ * Interface for SQL query result with parameter binding
+ * Used by MondoDatabase with Cloudflare's native SQL interface
+ */
+export interface SqlQueryResult {
+    toArray(): unknown[];
+    run(): void;
+    bind(...params: unknown[]): SqlQueryResult;
+}
+/**
+ * Interface for Cloudflare Durable Object SQL storage
+ * Used by MondoDatabase for direct SQL execution
+ */
+export interface SqlStorage {
+    exec(sql: string, ...params: unknown[]): SqlQueryResult;
+}
+/**
+ * Interface for Cloudflare Durable Object storage
+ * Used by MondoDatabase and SchemaManager
+ */
+export interface DurableObjectStorage {
+    sql: SqlStorage;
+    get<T>(key: string): Promise<T | undefined>;
+    put(key: string, value: unknown): Promise<void>;
+    /**
+     * Execute a synchronous callback wrapped in a transaction.
+     * If the callback throws, the transaction is rolled back.
+     * Only available for SQLite-backed Durable Objects.
+     */
+    transactionSync<T>(callback: () => T): T;
+}
+/**
+ * Interface for SQL prepared statement
+ * Used by IndexManager for prepared statement execution
+ */
+export interface SQLStatement {
+    bind(...params: unknown[]): SQLStatement;
+    run(): void;
+    first<T = unknown>(): T | null;
+    all<T = unknown>(): T[];
+}
+/**
+ * Interface for SQLite-compatible storage with SQL execution
+ * Used by IndexManager for prepared statement-based operations
+ *
+ * This is an alternative interface to DurableObjectStorage that provides
+ * a prepare() method for creating prepared statements, which is useful
+ * for operations that need to retrieve results or bind parameters.
+ */
+export interface SQLStorage {
+    exec(sql: string): void;
+    prepare(sql: string): SQLStatement;
+}
+/**
+ * TTL Index information with collection context
+ */
+export interface TTLIndexInfo {
+    collectionName: string;
+    collectionId: number;
+    indexName: string;
+    field: string;
+    expireAfterSeconds: number;
+}
+/**
+ * TTL metadata for tracking cleanup operations
+ */
+export interface TTLMetadata {
+    field: string;
+    expireAfterSeconds: number;
+    lastCleanupAt?: string;
+    lastCleanupCount?: number;
+}
+/**
+ * Result of a TTL cleanup operation
+ */
+export interface TTLCleanupResult {
+    ok: 1;
+    collectionsProcessed: number;
+    documentsDeleted: number;
+    errors?: string[];
+}
+/**
+ * Query info for deleting expired documents
+ */
+export interface ExpiredDocumentsQuery {
+    sql: string;
+    params: unknown[];
+}
+/**
+ * Legacy migration type (kept for backwards compatibility)
+ * @deprecated Use migrations module instead
+ */
+export type MigrationFn = (storage: DurableObjectStorage) => Promise<void>;
+/**
+ * Legacy migration registry (kept for backwards compatibility)
+ * @deprecated Use migrations module instead
+ */
+export declare const MIGRATIONS: Record<number, MigrationFn>;
+/**
+ * Schema validation result
+ */
+export interface SchemaValidationResult {
+    valid: boolean;
+    missingTables: string[];
+    missingIndexes: string[];
+    errors: string[];
+}
+/**
+ * SchemaManager handles SQLite schema initialization and migrations
+ */
+export declare class SchemaManager {
+    private storage;
+    constructor(storage: DurableObjectStorage);
+    /**
+     * Initialize the schema, running migrations if needed
+     */
+    initializeSchema(): Promise<void>;
+    /**
+     * Validate that the schema is properly initialized
+     * Returns true if all required tables exist
+     */
+    validateSchema(): Promise<boolean>;
+    /**
+     * Detailed schema validation with specific error information
+     */
+    validateSchemaDetailed(): Promise<SchemaValidationResult>;
+    /**
+     * Get the current schema version from storage
+     */
+    getSchemaVersion(): Promise<number>;
+    /**
+     * Check if schema needs migration
+     */
+    needsMigration(): Promise<boolean>;
+    /**
+     * Get list of pending migrations
+     */
+    getPendingMigrations(): Promise<number[]>;
+}
+//# sourceMappingURL=schema.d.ts.map

package/dist/durable-object/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/durable-object/schema.ts"],"names":[],"mappings":"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"}

package/dist/durable-object/schema.js

@@ -0,0 +1,186 @@
+/**
+ * SQLite Schema Management for MondoDB
+ *
+ * This module handles the initialization and management of SQLite tables
+ * for MongoDB-compatible document storage in Cloudflare Durable Objects.
+ *
+ * UNIFIED SCHEMA TYPES:
+ * This module serves as the single source of truth for all schema-related types
+ * used by both IndexManager and MondoDatabase.
+ */
+import { migrations, getMigrationsInRange, getLatestVersion, validateMigrations, } from './migrations';
+/**
+ * Current schema version - derived from migrations module
+ */
+export const SCHEMA_VERSION = getLatestVersion();
+/**
+ * Schema key used for storing version in Durable Object storage
+ */
+export const SCHEMA_VERSION_KEY = 'schema_version';
+/**
+ * Table definitions for the schema (exported for reference/testing)
+ *
+ * UNIFIED SCHEMA: This schema supports both MondoDatabase and IndexManager:
+ * - collections table: stores collection metadata including indexes JSON
+ * - documents table: stores documents with _id as the document identifier
+ *
+ * Note: The actual table creation is handled by migrations.ts.
+ * These definitions are kept in sync for reference and testing.
+ */
+export const SCHEMA_TABLES = {
+    collections: {
+        name: 'collections',
+        sql: `
+      CREATE TABLE IF NOT EXISTS collections (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL UNIQUE,
+        options TEXT DEFAULT '{}',
+        indexes TEXT DEFAULT '[]',
+        created_at TEXT DEFAULT (datetime('now')),
+        updated_at TEXT DEFAULT (datetime('now'))
+      )
+    `.trim(),
+    },
+    documents: {
+        name: 'documents',
+        sql: `
+      CREATE TABLE IF NOT EXISTS documents (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        collection_id INTEGER NOT NULL,
+        _id TEXT NOT NULL,
+        data TEXT NOT NULL DEFAULT '{}',
+        created_at TEXT DEFAULT (datetime('now')),
+        updated_at TEXT DEFAULT (datetime('now')),
+        UNIQUE(collection_id, _id),
+        FOREIGN KEY (collection_id) REFERENCES collections(id) ON DELETE CASCADE
+      )
+    `.trim(),
+    },
+};
+/**
+ * Index definitions for optimized queries
+ */
+export const SCHEMA_INDEXES = {
+    documents_id: {
+        name: 'idx_documents_id',
+        sql: `CREATE INDEX IF NOT EXISTS idx_documents_id ON documents(_id)`,
+    },
+    documents_collection_id: {
+        name: 'idx_documents_collection_id',
+        sql: `CREATE INDEX IF NOT EXISTS idx_documents_collection_id ON documents(collection_id, _id)`,
+    },
+};
+/**
+ * Legacy migration registry (kept for backwards compatibility)
+ * @deprecated Use migrations module instead
+ */
+export const MIGRATIONS = Object.fromEntries(migrations.map((m) => [m.version, m.up]));
+/**
+ * Required tables for schema integrity
+ */
+const REQUIRED_TABLES = ['collections', 'documents'];
+/**
+ * Required indexes for schema integrity
+ */
+const REQUIRED_INDEXES = ['idx_documents_id', 'idx_documents_collection_id'];
+/**
+ * SchemaManager handles SQLite schema initialization and migrations
+ */
+export class SchemaManager {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+        // Validate migrations on construction
+        const validation = validateMigrations();
+        if (!validation.valid) {
+            throw new Error(`Invalid migrations: ${validation.error}`);
+        }
+    }
+    /**
+     * Initialize the schema, running migrations if needed
+     */
+    async initializeSchema() {
+        const currentVersion = await this.storage.get(SCHEMA_VERSION_KEY);
+        // Skip if already at current version
+        if (currentVersion === SCHEMA_VERSION) {
+            return;
+        }
+        const startVersion = currentVersion ?? 0;
+        // Get and run all applicable migrations
+        const migrationsToRun = getMigrationsInRange(startVersion, SCHEMA_VERSION);
+        for (const migration of migrationsToRun) {
+            await migration.up(this.storage);
+        }
+        // Update schema version
+        await this.storage.put(SCHEMA_VERSION_KEY, SCHEMA_VERSION);
+    }
+    /**
+     * Validate that the schema is properly initialized
+     * Returns true if all required tables exist
+     */
+    async validateSchema() {
+        const result = await this.validateSchemaDetailed();
+        return result.valid;
+    }
+    /**
+     * Detailed schema validation with specific error information
+     */
+    async validateSchemaDetailed() {
+        const result = {
+            valid: true,
+            missingTables: [],
+            missingIndexes: [],
+            errors: [],
+        };
+        try {
+            // Check for required tables
+            const tablesResult = this.storage.sql.exec(`SELECT name FROM sqlite_master WHERE type='table' AND name IN ('collections', 'documents')`);
+            const tables = tablesResult.toArray();
+            const tableNames = new Set(tables.map((t) => t.name));
+            for (const requiredTable of REQUIRED_TABLES) {
+                if (!tableNames.has(requiredTable)) {
+                    result.missingTables.push(requiredTable);
+                    result.valid = false;
+                }
+            }
+            // Check for required indexes
+            const indexesResult = this.storage.sql.exec(`SELECT name FROM sqlite_master WHERE type='index' AND name LIKE 'idx_%'`);
+            const indexes = indexesResult.toArray();
+            const indexNames = new Set(indexes.map((i) => i.name));
+            for (const requiredIndex of REQUIRED_INDEXES) {
+                if (!indexNames.has(requiredIndex)) {
+                    result.missingIndexes.push(requiredIndex);
+                    result.valid = false;
+                }
+            }
+        }
+        catch (error) {
+            result.valid = false;
+            result.errors.push(error instanceof Error ? error.message : 'Unknown error during validation');
+        }
+        return result;
+    }
+    /**
+     * Get the current schema version from storage
+     */
+    async getSchemaVersion() {
+        const version = await this.storage.get(SCHEMA_VERSION_KEY);
+        return version ?? 0;
+    }
+    /**
+     * Check if schema needs migration
+     */
+    async needsMigration() {
+        const currentVersion = await this.getSchemaVersion();
+        return currentVersion < SCHEMA_VERSION;
+    }
+    /**
+     * Get list of pending migrations
+     */
+    async getPendingMigrations() {
+        const currentVersion = await this.getSchemaVersion();
+        const pending = getMigrationsInRange(currentVersion, SCHEMA_VERSION);
+        return pending.map((m) => m.version);
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/durable-object/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/durable-object/schema.ts"],"names":[],"mappings":"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"}

package/dist/embedding/document-serializer.d.ts

@@ -0,0 +1,118 @@
+import type { VectorizeMetadata, VectorizeMetadataValue } from '../types/vectorize';
+/**
+ * Document Serializer - Unified document serialization for embedding generation
+ *
+ * This module provides document serialization for vector embedding by:
+ * - Extracting text content from specified fields
+ * - Handling nested objects and arrays
+ * - Supporting configurable field selection (include/exclude)
+ * - Extracting metadata for vector storage
+ * - Supporting multiple output formats (yaml, json, text)
+ *
+ * Consolidates functionality from both embedding and vectorize serializers.
+ */
+/**
+ * Configuration options for automatic embedding generation
+ */
+export interface AutoEmbeddingConfig {
+    /**
+     * Maximum depth for nested object traversal (default: 3)
+     */
+    maxDepth?: number;
+    /**
+     * Fields to exclude from serialization (in addition to defaults)
+     * Supports dot notation for nested fields (e.g., 'metadata.internal')
+     */
+    excludeFields?: string[];
+    /**
+     * Fields to include (if specified, only these fields are included)
+     * Supports dot notation for nested fields (e.g., 'metadata.author')
+     * Supports wildcards (e.g., 'details.*' for all fields under details)
+     */
+    includeFields?: string[];
+    /**
+     * Fields to extract as metadata for vector storage
+     * Supports dot notation for nested fields
+     */
+    metadataFields?: string[];
+    /**
+     * Separator to use between field values in text mode
+     * Default: ' ' (space)
+     */
+    separator?: string;
+}
+/**
+ * Serialization options for document embedding
+ */
+export interface SerializationOptions {
+    /**
+     * Serialization format: 'yaml' (default), 'json', or 'text'
+     */
+    serializer?: 'yaml' | 'json' | 'text';
+    /**
+     * Automatic embedding configuration
+     */
+    auto?: AutoEmbeddingConfig;
+}
+/**
+ * Result of document serialization with metadata
+ */
+export interface SerializedDocument {
+    /** The document ID */
+    documentId: string;
+    /** The serialized text content for embedding */
+    text: string;
+    /** Optional metadata extracted from the document */
+    metadata?: VectorizeMetadata;
+}
+/**
+ * Serialize a document for embedding generation
+ *
+ * @param doc - The document to serialize
+ * @param options - Serialization options
+ * @returns Serialized string representation of the document
+ */
+export declare function serializeForEmbedding(doc: Record<string, unknown>, options?: SerializationOptions): string;
+/**
+ * Serialize a document with full metadata extraction
+ *
+ * This is the advanced API that returns a structured result including
+ * the document ID and extracted metadata for vector storage.
+ *
+ * @param doc - The document to serialize
+ * @param options - Serialization options
+ * @returns Serialized document with text and metadata
+ */
+export declare function serializeDocument(doc: Record<string, unknown>, options?: SerializationOptions): SerializedDocument;
+/**
+ * Serialize multiple documents in batch
+ *
+ * @param docs - Array of MongoDB documents
+ * @param options - Serialization options applied to all documents
+ * @returns Array of serialized documents
+ */
+export declare function serializeDocuments(docs: Record<string, unknown>[], options?: SerializationOptions): SerializedDocument[];
+/**
+ * DocumentSerializer class - Object-oriented API for document serialization
+ *
+ * Provides a class-based interface for cases where you need to reuse
+ * serialization options across multiple operations.
+ */
+export declare class DocumentSerializer {
+    private options;
+    constructor(options?: SerializationOptions);
+    /**
+     * Serialize a single document to text for embedding
+     */
+    serialize(doc: Record<string, unknown>, options?: SerializationOptions): SerializedDocument;
+    /**
+     * Serialize multiple documents in batch
+     */
+    serializeBatch(docs: Record<string, unknown>[], options?: SerializationOptions): SerializedDocument[];
+    /**
+     * Get just the text representation (simple API)
+     */
+    serializeToText(doc: Record<string, unknown>, options?: SerializationOptions): string;
+}
+export type { VectorizeMetadata, VectorizeMetadataValue };
+//# sourceMappingURL=document-serializer.d.ts.map

package/dist/embedding/document-serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-serializer.d.ts","sourceRoot":"","sources":["../../src/embedding/document-serializer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEpF;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAEtC;;OAEG;IACH,IAAI,CAAC,EAAE,mBAAmB,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sBAAsB;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAmRD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,GAAE,oBAAyB,GACjC,MAAM,CAwBR;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,GAAE,oBAAyB,GACjC,kBAAkB,CAqBpB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,OAAO,GAAE,oBAAyB,GACjC,kBAAkB,EAAE,CAEtB;AAED;;;;;GAKG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,OAAO,CAAuB;gBAE1B,OAAO,GAAE,oBAAyB;IAI9C;;OAEG;IACH,SAAS,CACP,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,kBAAkB;IAIrB;;OAEG;IACH,cAAc,CACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,kBAAkB,EAAE;IAIvB;;OAEG;IACH,eAAe,CACb,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,MAAM;CAGV;AAGD,YAAY,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,CAAC"}