ai-database 2.1.3 → 2.3.0

package/dist/worker.d.ts

@@ -0,0 +1,779 @@
+/**
+ * Worker Export - WorkerEntrypoint for RPC access to AI Database
+ *
+ * Exposes database operations via Cloudflare RPC.
+ * Works both in Cloudflare Workers and standalone (with MemoryProvider).
+ *
+ * @example
+ * ```typescript
+ * // wrangler.jsonc
+ * {
+ *   "services": [
+ *     { "binding": "AI_DATABASE", "service": "ai-database" }
+ *   ]
+ * }
+ *
+ * // worker.ts - consuming service
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     const db = env.AI_DATABASE.connect('my-namespace')
+ *     const post = await db.create('Post', { title: 'Hello' })
+ *     return Response.json(post)
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * ExecutionContext interface - matches @cloudflare/workers-types
+ */
+export interface MockExecutionContext {
+    waitUntil(promise: Promise<unknown>): void;
+    passThroughOnException(): void;
+}
+/**
+ * SqlStorage interface - matches DurableObjectStorage.sql from @cloudflare/workers-types
+ */
+export interface SqlStorage {
+    exec(query: string, ...params: unknown[]): SqlStorageResult;
+}
+/**
+ * SqlStorageResult interface
+ */
+export interface SqlStorageResult {
+    toArray(): unknown[];
+}
+/**
+ * DurableObjectStorage interface - subset needed for our use
+ */
+export interface MockDurableObjectStorage {
+    sql: SqlStorage;
+}
+/**
+ * DurableObjectId interface
+ */
+export interface MockDurableObjectId {
+    toString(): string;
+    equals(other: MockDurableObjectId): boolean;
+    readonly name?: string;
+}
+/**
+ * DurableObjectState interface - matches @cloudflare/workers-types
+ */
+export interface MockDurableObjectState {
+    waitUntil(promise: Promise<unknown>): void;
+    readonly id: MockDurableObjectId;
+    readonly storage: MockDurableObjectStorage;
+}
+/**
+ * Database row interfaces for type-safe SQL operations
+ */
+export interface DataRow {
+    id: string;
+    type: string;
+    data: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface RelRow {
+    from_id: string;
+    relation: string;
+    to_id: string;
+    metadata: string | null;
+    created_at: string;
+}
+export interface EventRow {
+    id: string;
+    event: string;
+    actor: string | null;
+    object: string | null;
+    data: string | null;
+    result: string | null;
+    previous_data: string | null;
+    timestamp: string;
+}
+export interface EmbeddingRow {
+    id: string;
+    entity_type: string;
+    entity_id: string;
+    model: string;
+    vector: string;
+    content_hash: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface SubscriptionRow {
+    id: string;
+    pattern: string;
+    webhook: string;
+    created_at: string;
+}
+export interface MetaRow {
+    key: string;
+    value: string;
+}
+export interface CountRow {
+    count: number;
+}
+/**
+ * Environment with AI binding for Cloudflare AI
+ */
+export interface EnvWithAI {
+    AI?: {
+        run(model: string, options: {
+            text: string[];
+        }): Promise<{
+            data: number[][];
+        }>;
+    };
+}
+/**
+ * Deserialized entity types
+ */
+export interface DeserializedDataRow {
+    id: string;
+    type: string;
+    data: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+}
+export interface DeserializedRelRow {
+    from_id: string;
+    relation: string;
+    to_id: string;
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+}
+export interface DeserializedEventRow {
+    id: string;
+    event: string;
+    actor: string | null;
+    object: string | null;
+    data: unknown;
+    result: string | null;
+    previousData: unknown;
+    timestamp: string;
+}
+/**
+ * Event handler type
+ */
+export type DatabaseEventHandler = (event: DeserializedEventRow) => void | Promise<void>;
+/**
+ * Action status type
+ */
+export type ActionStatus = 'pending' | 'in_progress' | 'completed' | 'failed';
+/**
+ * Action interface
+ */
+export interface Action {
+    id: string;
+    action: string;
+    actor: string;
+    object?: string;
+    status: ActionStatus;
+    progress?: number;
+    total?: number;
+    data?: unknown;
+    result?: unknown;
+    error?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Artifact interface
+ */
+export interface Artifact {
+    url: string;
+    type: string;
+    content: unknown;
+    sourceHash: string;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Request body types
+ */
+export interface CreateDataBody {
+    id?: string;
+    type: string;
+    data: Record<string, unknown>;
+}
+export interface UpdateDataBody {
+    data: Record<string, unknown>;
+}
+export interface CreateRelBody {
+    from_id: string;
+    relation: string;
+    to_id: string;
+    metadata?: Record<string, unknown>;
+}
+export interface CreateEventBody {
+    event: string;
+    actor?: string;
+    object?: string;
+    data?: unknown;
+}
+export interface SearchBody {
+    type?: string;
+    query: string;
+    limit?: number;
+    fields?: string[];
+    minScore?: number;
+}
+export interface SemanticSearchBody {
+    type: string;
+    query: string;
+    limit?: number;
+    threshold?: number;
+}
+export interface HybridSearchBody {
+    type: string;
+    query: string;
+    limit?: number;
+    ftsWeight?: number;
+    semanticWeight?: number;
+}
+export interface TraverseFilterBody {
+    from_id: string;
+    relation: string;
+    direction?: 'outgoing' | 'incoming';
+    maxDepth?: number;
+    filter?: Record<string, unknown>;
+}
+export interface ReplayEventsBody {
+    object: string;
+    until?: string;
+}
+export interface SubscribeBody {
+    pattern: string;
+    webhook: string;
+}
+export interface EmbeddingsConfigBody {
+    model?: string;
+}
+export interface EmbeddingsGenerateBody {
+    type: string;
+}
+export interface EmbeddingsBatchBody {
+    type: string;
+    batchSize?: number;
+}
+export interface UpdateRelMetadataBody {
+    from_id: string;
+    relation: string;
+    to_id: string;
+    metadata: Record<string, unknown>;
+}
+export interface QueryListBody {
+    type: string;
+    where?: Record<string, unknown>;
+    orderBy?: string;
+    order?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+}
+export interface QueryFindBody {
+    type: string;
+    where?: Record<string, unknown>;
+}
+export interface PipelineConfigBody {
+    retryEnabled?: boolean;
+    batchSize?: number;
+}
+export interface PipelineTestErrorBody {
+    simulateError?: boolean;
+}
+declare class MockRpcTarget {
+}
+declare class MockWorkerEntrypoint<T = unknown> {
+    protected env: T;
+    protected ctx: MockExecutionContext;
+}
+declare class MockDurableObject {
+    protected ctx: MockDurableObjectState;
+    protected env: unknown;
+    constructor(_state: MockDurableObjectState, _env: unknown);
+}
+declare let WorkerEntrypoint: typeof MockWorkerEntrypoint;
+declare let RpcTarget: typeof MockRpcTarget;
+declare let DurableObjectBase: typeof MockDurableObject;
+import type { MemoryProviderOptions, EmbeddingProvider } from './memory-provider.js';
+import type { ListOptions, SearchOptions, SemanticSearchOptions, HybridSearchOptions, EmbeddingsConfig } from './schema.js';
+/**
+ * Environment bindings for the worker
+ */
+export interface Env {
+}
+/**
+ * Entity result type with standard fields
+ */
+export interface EntityResult {
+    $id: string;
+    $type: string;
+    [key: string]: unknown;
+}
+/**
+ * Search result with score
+ */
+export interface SearchResult extends EntityResult {
+    $score?: number;
+}
+/**
+ * Semantic search result with scores
+ */
+export interface SemanticSearchResult extends EntityResult {
+    $score: number;
+}
+/**
+ * Hybrid search result with RRF and component scores
+ */
+export interface HybridSearchResult extends SemanticSearchResult {
+    $rrfScore: number;
+    $ftsRank: number;
+    $semanticRank: number;
+}
+/**
+ * DatabaseServiceCore - RpcTarget wrapper around MemoryProvider
+ *
+ * Exposes all required methods as RPC-callable methods.
+ * This is the core service class that can be instantiated directly.
+ */
+export declare class DatabaseServiceCore extends RpcTarget {
+    private provider;
+    constructor(namespace?: string, options?: MemoryProviderOptions);
+    /**
+     * Set embeddings configuration for auto-generation
+     */
+    setEmbeddingsConfig(config: EmbeddingsConfig): void;
+    /**
+     * Enable or disable ai-functions for embeddings
+     */
+    setUseAiFunctions(enabled: boolean): void;
+    /**
+     * Set a custom embedding provider
+     */
+    setEmbeddingProvider(provider: EmbeddingProvider | undefined): void;
+    /**
+     * Get an entity by type and ID
+     */
+    get(type: string, id: string): Promise<EntityResult | null>;
+    /**
+     * List entities by type
+     */
+    list(type: string, options?: ListOptions): Promise<EntityResult[]>;
+    /**
+     * Create an entity
+     */
+    create(type: string, data: Record<string, unknown>, id?: string): Promise<EntityResult>;
+    /**
+     * Update an entity
+     */
+    update(type: string, id: string, data: Record<string, unknown>): Promise<EntityResult>;
+    /**
+     * Delete an entity
+     */
+    delete(type: string, id: string): Promise<boolean>;
+    /**
+     * Full-text search
+     */
+    search(type: string, query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Semantic search using vector similarity
+     */
+    semanticSearch(type: string, query: string, options?: SemanticSearchOptions): Promise<SemanticSearchResult[]>;
+    /**
+     * Hybrid search combining FTS and semantic
+     */
+    hybridSearch(type: string, query: string, options?: HybridSearchOptions): Promise<HybridSearchResult[]>;
+    /**
+     * Get related entities
+     */
+    related(type: string, id: string, relation: string): Promise<EntityResult[]>;
+    /**
+     * Create a relationship between two entities
+     */
+    relate(fromType: string, fromId: string, relation: string, toType: string, toId: string, metadata?: {
+        matchMode?: 'exact' | 'fuzzy';
+        similarity?: number;
+        matchedType?: string;
+    }): Promise<void>;
+    /**
+     * Remove a relationship between two entities
+     */
+    unrelate(fromType: string, fromId: string, relation: string, toType: string, toId: string): Promise<void>;
+    /**
+     * Subscribe to events matching a pattern
+     * @returns Unsubscribe function ID (use unsubscribe() to remove)
+     */
+    on(pattern: string, handler: DatabaseEventHandler): string;
+    private _eventHandlers;
+    /**
+     * Unsubscribe from events
+     */
+    unsubscribe(handlerId: string): void;
+    /**
+     * Emit an event
+     */
+    emit(eventOrOptions: string | {
+        event: string;
+        actor: string;
+        object?: string;
+        data?: unknown;
+    }, data?: unknown): Promise<DeserializedEventRow | null>;
+    /**
+     * List events
+     */
+    listEvents(options?: {
+        event?: string;
+        actor?: string;
+        object?: string;
+        since?: Date;
+        until?: Date;
+        limit?: number;
+    }): Promise<DeserializedEventRow[]>;
+    /**
+     * Create a new action
+     */
+    createAction(options: {
+        action: string;
+        actor: string;
+        object?: string;
+        data?: unknown;
+        total?: number;
+    }): Promise<Action | null>;
+    /**
+     * Get an action by ID
+     */
+    getAction(id: string): Promise<Action | null>;
+    /**
+     * Update an action
+     */
+    updateAction(id: string, updates: {
+        status?: string;
+        progress?: number;
+        result?: unknown;
+        error?: string;
+    }): Promise<Action | null>;
+    /**
+     * List actions
+     */
+    listActions(options?: {
+        status?: string;
+        action?: string;
+        actor?: string;
+        object?: string;
+        since?: Date;
+        until?: Date;
+        limit?: number;
+    }): Promise<Action[]>;
+    /**
+     * Get an artifact
+     */
+    getArtifact(url: string, type: string): Promise<Artifact | null>;
+    /**
+     * Set an artifact
+     */
+    setArtifact(url: string, type: string, data: {
+        content: unknown;
+        sourceHash: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Delete an artifact
+     */
+    deleteArtifact(url: string, type?: string): Promise<void>;
+    /**
+     * List artifacts for a URL
+     */
+    listArtifacts(url: string): Promise<Artifact[]>;
+    /**
+     * Clear all data in the provider (useful for testing)
+     */
+    clear(): void;
+}
+/**
+ * DatabaseDO - Durable Object using SQLite for the core schema layer.
+ *
+ * Provides two tables:
+ * - `_data`: id TEXT PRIMARY KEY, type TEXT, data TEXT (JSON), created_at TEXT, updated_at TEXT
+ * - `_rels`: from_id TEXT, relation TEXT, to_id TEXT, metadata TEXT (JSON),
+ *            PRIMARY KEY(from_id, relation, to_id)
+ *
+ * Handles HTTP requests for CRUD operations on data records and relationships,
+ * plus graph traversal queries.
+ */
+export declare class DatabaseDO extends DurableObjectBase {
+    private sql;
+    private initialized;
+    private pipelineBuffer;
+    private pipelineConfig;
+    private pipelineStats;
+    private embeddingsConfig;
+    private embeddingsCacheStats;
+    private batchJobs;
+    constructor(state: MockDurableObjectState, env: unknown);
+    private ensureSchema;
+    fetch(request: Request): Promise<Response>;
+    private handleListData;
+    private handleInsertData;
+    private handleGetData;
+    private handleUpdateData;
+    private handleDeleteData;
+    /**
+     * Cascade delete related entities up to a given depth
+     */
+    private cascadeDelete;
+    private handleQueryRels;
+    private handleCreateRel;
+    private handleDeleteRel;
+    private handleTraverse;
+    /**
+     * Handle bidirectional traversal (both incoming and outgoing)
+     */
+    private handleBidirectionalTraverse;
+    /**
+     * Handle forward (outgoing) traversal with depth control
+     */
+    private handleForwardTraverse;
+    /**
+     * Handle reverse (incoming) traversal
+     */
+    private handleReverseTraverse;
+    /**
+     * Fetch entities by IDs with optional type filter and metadata
+     */
+    private fetchEntitiesByIds;
+    /**
+     * Handle POST /traverse/filter - filter traversal by metadata
+     */
+    private handleTraverseFilter;
+    /**
+     * Check if metadata matches a filter with operator support
+     */
+    private matchesMetadataFilter;
+    /**
+     * Handle PATCH /rels - update relationship metadata
+     */
+    private handleUpdateRel;
+    private handleGetIndexes;
+    private handleGetVersion;
+    /**
+     * Validate a field name to prevent SQL injection.
+     * Only allows alphanumeric characters, underscores, and dots for nested fields.
+     */
+    private isValidFieldName;
+    /**
+     * Build SQL WHERE clause from a where object.
+     * Returns [clause, params] tuple where clause includes the WHERE keyword.
+     */
+    /**
+     * Convert a value for SQLite JSON comparison.
+     * Booleans need to be converted to 1/0 because SQLite stores JSON booleans as integers.
+     */
+    private toSqliteValue;
+    private buildWhereClause;
+    /**
+     * Build ORDER BY clause from orderBy and order parameters.
+     */
+    private buildOrderByClause;
+    /**
+     * Handle GET /query/list - simple query via URL params
+     */
+    private handleQueryList;
+    /**
+     * Handle POST /query/list - complex query via JSON body
+     */
+    private handleQueryListPost;
+    /**
+     * Handle POST /query/find - find first matching record
+     */
+    private handleQueryFind;
+    /**
+     * Escape special characters in LIKE patterns
+     */
+    private escapeLikePattern;
+    /**
+     * Calculate a simple relevance score based on term matches
+     */
+    private calculateRelevanceScore;
+    /**
+     * Handle POST /query/search - full-text search
+     */
+    private handleQuerySearch;
+    /**
+     * Emit an event to the _events table and pipeline
+     */
+    private emitEvent;
+    /**
+     * Handle GET /events - list events with filtering
+     */
+    private handleListEvents;
+    /**
+     * Handle POST /events - create custom event
+     */
+    private handleCreateEvent;
+    /**
+     * Handle POST /events/replay - replay events
+     */
+    private handleReplayEvents;
+    /**
+     * Handle POST /events/rebuild - rebuild entity from events
+     */
+    private handleRebuildEntity;
+    /**
+     * Handle POST /events/subscribe - create subscription
+     */
+    private handleSubscribe;
+    /**
+     * Handle GET /events/subscriptions - list subscriptions
+     */
+    private handleListSubscriptions;
+    /**
+     * Handle DELETE /events/subscriptions/:id - unsubscribe
+     */
+    private handleUnsubscribe;
+    /**
+     * Handle GET /events/subscriptions/:id/deliveries - list deliveries
+     */
+    private handleListDeliveries;
+    /**
+     * Handle GET /pipeline/status - get pipeline status
+     */
+    private handlePipelineStatus;
+    /**
+     * Handle POST /pipeline/flush - flush pipeline buffer to R2
+     */
+    private handlePipelineFlush;
+    /**
+     * Flush the pipeline buffer to R2 storage
+     */
+    private flushPipeline;
+    /**
+     * Handle GET /pipeline/r2/list - list R2 objects
+     */
+    private handlePipelineR2List;
+    /**
+     * Handle POST /pipeline/config - configure pipeline
+     */
+    private handlePipelineConfig;
+    /**
+     * Handle POST /pipeline/test-error - test error handling
+     */
+    private handlePipelineTestError;
+    /**
+     * Deserialize an event row from the database
+     */
+    private deserializeEventRow;
+    private deserializeDataRow;
+    private deserializeRelRow;
+    /**
+     * Configure embeddings model
+     */
+    private handleConfigureEmbeddings;
+    /**
+     * List all embeddings with optional type filter
+     * Generates embeddings lazily for entities that don't have them yet
+     */
+    private handleListEmbeddings;
+    /**
+     * Get embedding cache stats
+     */
+    private handleEmbeddingsStats;
+    /**
+     * Warm up embedding cache for a type
+     */
+    private handleEmbeddingsWarmup;
+    /**
+     * Generate embeddings for all entities of a type
+     */
+    private handleEmbeddingsGenerate;
+    /**
+     * Batch process embeddings for specific entities
+     */
+    private handleEmbeddingsBatch;
+    /**
+     * Start a batch embedding job
+     */
+    private handleEmbeddingsBatchStart;
+    /**
+     * Process a batch job asynchronously
+     */
+    private processBatchJob;
+    /**
+     * Get batch job status
+     */
+    private handleEmbeddingsBatchStatus;
+    /**
+     * Get embedding for a specific entity
+     */
+    private handleGetEmbedding;
+    /**
+     * Semantic search using vector similarity
+     */
+    private handleSemanticSearch;
+    /**
+     * Hybrid search combining FTS and semantic
+     */
+    private handleHybridSearch;
+    /**
+     * Generate embedding for an entity and store it
+     */
+    private generateEmbeddingForEntity;
+    /**
+     * Generate embedding vector for text using AI binding or fallback
+     */
+    private generateEmbedding;
+    /**
+     * Generate a deterministic embedding based on text content
+     * This is used as a fallback when no AI binding is available
+     */
+    private generateDeterministicEmbedding;
+    /**
+     * Extract text content from entity data for embedding
+     */
+    private extractEmbeddableText;
+    /**
+     * Calculate cosine similarity between two vectors
+     */
+    private cosineSimilarity;
+    /**
+     * Simple hash function for deterministic randomness
+     */
+    private simpleHash;
+    /**
+     * Generate deterministic pseudo-random number from seed
+     */
+    private seededRandom;
+    /**
+     * Hash content for change detection
+     */
+    private hashContent;
+}
+/**
+ * DatabaseService - WorkerEntrypoint for RPC access
+ *
+ * Provides `connect(namespace)` method that returns an RpcTarget service
+ * with all database operations.
+ *
+ * When used standalone (in tests), uses an in-memory provider with namespace isolation.
+ */
+export declare class DatabaseService extends WorkerEntrypoint<Env> {
+    /**
+     * Connect to a namespace and get an RPC-enabled service
+     *
+     * @param namespace - The namespace to connect to (defaults to 'default')
+     * @param options - Optional provider configuration
+     * @returns DatabaseServiceCore instance for RPC calls
+     */
+    connect(namespace?: string, options?: MemoryProviderOptions): DatabaseServiceCore;
+    /**
+     * Handle fetch requests - required by vitest-pool-workers for service binding tests
+     * Returns a simple JSON response for health checks or routes to the appropriate service
+     */
+    fetch(request: Request): Promise<Response>;
+}
+export default DatabaseService;
+export { DatabaseService as DatabaseWorker };
+//# sourceMappingURL=worker.d.ts.map