/**
 * @db4/core - Engine Interfaces
 *
 * Defines the core engine interfaces for the db4 ecosystem:
 * - StorageEngine: Low-level document storage
 * - QueryEngine: Query execution and optimization
 * - TransactionManager: Transaction coordination
 * - CDCEngine: Change data capture and streaming
 *
 * @packageDocumentation
 */
import type { Document, StoredDocument, QueryOptions, QueryResult, QueryPlan, TransactionOptions, IsolationLevel, ConflictInfo, CDCLogEntry, CDCCursor, CDCBatch, CDCStreamOptions, CDCStreamResult, CDCCheckpoint, CDCFilter, CollectionStats } from './types.js';
/**
 * Storage engine configuration options.
 */
export interface StorageEngineConfig {
    /** Maximum document size in bytes */
    maxDocumentSize?: number;
    /** Maximum batch size in bytes */
    maxBatchSize?: number;
    /** Documents per batch (batch size tier) */
    batchSizeTier?: 64 | 128 | 256;
    /** Enable compression */
    compression?: boolean;
    /** Compression algorithm */
    compressionAlgorithm?: 'gzip' | 'lz4' | 'zstd';
}
/**
 * Write options for storage operations.
 */
export interface WriteOptions {
    /** Skip validation (use with caution) */
    skipValidation?: boolean;
    /** Force overwrite without version check */
    force?: boolean;
    /** Transaction ID for batched writes */
    transactionId?: string;
}
/**
 * Read options for storage operations.
 */
export interface ReadOptions {
    /** Fields to include in the result */
    projection?: string[];
    /** Include metadata in result */
    includeMetadata?: boolean;
    /** Consistency level for reads */
    consistency?: 'strong' | 'eventual';
}
/**
 * Delete options for storage operations.
 */
export interface DeleteOptions {
    /** Soft delete (mark as deleted) instead of hard delete */
    soft?: boolean;
    /** Transaction ID for batched deletes */
    transactionId?: string;
    /** Version check for optimistic concurrency */
    expectedVersion?: number;
}
/**
 * Batch write operation descriptor.
 */
export interface BatchWriteOperation {
    /** Operation type */
    type: 'insert' | 'update' | 'upsert' | 'delete';
    /** Document to write (for insert/update/upsert) */
    document?: Document;
    /** Document ID (for delete) */
    documentId?: string;
    /** Collection name */
    collection: string;
    /** Write options */
    options?: WriteOptions;
}
/**
 * Batch write result for a single operation.
 */
export interface BatchWriteResult {
    /** Whether the operation succeeded */
    success: boolean;
    /** Document ID affected */
    documentId: string;
    /** Error message if failed */
    error?: string;
    /** New version after write */
    version?: number;
}
/**
 * Storage engine interface for low-level document storage.
 * Implementations provide the actual persistence layer.
 */
export interface StorageEngine {
    /**
     * Get a document by ID.
     */
    get(collection: string, documentId: string, options?: ReadOptions): Promise<StoredDocument | null>;
    /**
     * Get multiple documents by IDs.
     */
    getMany(collection: string, documentIds: string[], options?: ReadOptions): Promise<Map<string, StoredDocument>>;
    /**
     * Check if a document exists.
     */
    exists(collection: string, documentId: string): Promise<boolean>;
    /**
     * Insert a new document.
     * @throws if document already exists
     */
    insert(collection: string, document: Document, options?: WriteOptions): Promise<StoredDocument>;
    /**
     * Update an existing document.
     * @throws if document does not exist
     */
    update(collection: string, documentId: string, updates: Partial<Document>, options?: WriteOptions): Promise<StoredDocument>;
    /**
     * Insert or update a document.
     */
    upsert(collection: string, document: Document, options?: WriteOptions): Promise<StoredDocument>;
    /**
     * Delete a document.
     */
    delete(collection: string, documentId: string, options?: DeleteOptions): Promise<boolean>;
    /**
     * Insert multiple documents atomically.
     */
    insertMany(collection: string, documents: Document[], options?: WriteOptions): Promise<StoredDocument[]>;
    /**
     * Update multiple documents.
     */
    updateMany(collection: string, updates: Array<{
        id: string;
        changes: Partial<Document>;
    }>, options?: WriteOptions): Promise<StoredDocument[]>;
    /**
     * Delete multiple documents.
     */
    deleteMany(collection: string, documentIds: string[], options?: DeleteOptions): Promise<number>;
    /**
     * Execute a batch of mixed operations.
     */
    batchWrite(operations: BatchWriteOperation[]): Promise<BatchWriteResult[]>;
    /**
     * List all documents in a collection (for iteration).
     * Returns an async iterator for memory efficiency.
     */
    list(collection: string, options?: {
        limit?: number;
        cursor?: string;
    }): AsyncIterable<StoredDocument>;
    /**
     * Count documents in a collection.
     */
    count(collection: string): Promise<number>;
    /**
     * Clear all documents in a collection.
     */
    clear(collection: string): Promise<void>;
    /**
     * Get collection statistics.
     */
    stats(collection: string): Promise<CollectionStats>;
    /**
     * List all collection names.
     */
    listCollections(): Promise<string[]>;
    /**
     * Initialize the storage engine.
     */
    initialize(): Promise<void>;
    /**
     * Shutdown the storage engine gracefully.
     */
    shutdown(): Promise<void>;
    /**
     * Check if the engine is healthy.
     */
    healthCheck(): Promise<boolean>;
}
/**
 * Query engine configuration options.
 */
export interface QueryEngineConfig {
    /** Default query limit */
    defaultLimit?: number;
    /** Maximum query limit */
    maxLimit?: number;
    /** Query timeout in milliseconds */
    timeout?: number;
    /** Enable query caching */
    enableCache?: boolean;
    /** Cache TTL in milliseconds */
    cacheTTL?: number;
    /** Maximum result size in bytes */
    maxResultSize?: number;
}
/**
 * Compiled query for execution.
 */
export interface CompiledQuery {
    /** Original query options */
    options: QueryOptions;
    /** Execution plan */
    plan: QueryPlan;
    /** SQL query (if applicable) */
    sql?: string;
    /** Bound parameters */
    params?: unknown[];
    /** Cached query ID */
    cacheKey?: string;
}
/**
 * Query execution context.
 */
export interface QueryContext {
    /** Collection being queried */
    collection: string;
    /** Shard ID */
    shardId?: string;
    /** Transaction ID (if within a transaction) */
    transactionId?: string;
    /** Correlation ID for tracing */
    correlationId?: string;
    /** Start time for timeout tracking */
    startTime?: number;
}
/**
 * Query engine interface for executing queries.
 */
export interface QueryEngine {
    /**
     * Execute a query and return results.
     */
    query<T extends StoredDocument = StoredDocument>(collection: string, options: QueryOptions, context?: QueryContext): Promise<QueryResult<T>>;
    /**
     * Execute a query with streaming results.
     */
    queryStream<T extends StoredDocument = StoredDocument>(collection: string, options: QueryOptions, context?: QueryContext): AsyncIterable<T>;
    /**
     * Compile a query for later execution.
     */
    compile(collection: string, options: QueryOptions): CompiledQuery;
    /**
     * Execute a pre-compiled query.
     */
    executeCompiled<T extends StoredDocument = StoredDocument>(compiled: CompiledQuery, context?: QueryContext): Promise<QueryResult<T>>;
    /**
     * Explain a query without executing it.
     */
    explain(collection: string, options: QueryOptions): Promise<QueryPlan>;
    /**
     * Count documents matching a query.
     */
    count(collection: string, options: Omit<QueryOptions, 'limit' | 'offset'>): Promise<number>;
    /**
     * Check if any documents match the query.
     */
    exists(collection: string, options: Omit<QueryOptions, 'limit' | 'offset'>): Promise<boolean>;
    /**
     * Find a single document matching the query.
     */
    findOne<T extends StoredDocument = StoredDocument>(collection: string, options: Omit<QueryOptions, 'limit'>): Promise<T | null>;
    /**
     * Aggregate query results (count, sum, avg, min, max).
     */
    aggregate(collection: string, options: QueryOptions, aggregations: AggregationSpec[]): Promise<AggregationResult>;
    /**
     * Clear query cache (if caching is enabled).
     */
    clearCache(): void;
}
/**
 * Aggregation specification.
 */
export interface AggregationSpec {
    /** Aggregation function */
    function: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'distinct';
    /** Field to aggregate */
    field?: string;
    /** Alias for the result */
    alias: string;
}
/**
 * Aggregation result.
 */
export interface AggregationResult {
    /** Aggregated values by alias */
    values: Record<string, number | string | null>;
    /** Number of documents processed */
    documentCount: number;
}
/**
 * Transaction state.
 */
export type TransactionState = 'pending' | 'active' | 'committed' | 'aborted' | 'rolled_back';
/**
 * Transaction metadata.
 */
export interface TransactionMeta {
    /** Unique transaction ID */
    transactionId: string;
    /** Current state */
    state: TransactionState;
    /** Isolation level */
    isolationLevel: IsolationLevel;
    /** Start timestamp */
    startedAt: number;
    /** Timeout timestamp */
    timeoutAt: number;
    /** Documents read within this transaction */
    readSet: Set<string>;
    /** Documents written within this transaction */
    writeSet: Set<string>;
    /** Shard ID */
    shardId?: string;
}
/**
 * Transaction handle for managing a transaction's lifecycle.
 */
export interface Transaction {
    /** Get the transaction ID */
    getId(): string;
    /** Get the transaction state */
    getState(): TransactionState;
    /** Get the isolation level */
    getIsolationLevel(): IsolationLevel;
    /**
     * Get a document within the transaction.
     */
    get(collection: string, documentId: string): Promise<StoredDocument | null>;
    /**
     * Insert a document within the transaction.
     */
    insert(collection: string, document: Document): Promise<StoredDocument>;
    /**
     * Update a document within the transaction.
     */
    update(collection: string, documentId: string, updates: Partial<Document>): Promise<StoredDocument>;
    /**
     * Delete a document within the transaction.
     */
    delete(collection: string, documentId: string): Promise<boolean>;
    /**
     * Execute a query within the transaction.
     */
    query<T extends StoredDocument = StoredDocument>(collection: string, options: QueryOptions): Promise<QueryResult<T>>;
    /**
     * Commit the transaction.
     * @throws ConflictError if there are version conflicts
     */
    commit(): Promise<void>;
    /**
     * Rollback the transaction.
     */
    rollback(): Promise<void>;
    /**
     * Check if the transaction is still active.
     */
    isActive(): boolean;
    /**
     * Get time remaining before timeout.
     */
    getTimeRemaining(): number;
}
/**
 * Transaction manager interface for coordinating transactions.
 */
export interface TransactionManager {
    /**
     * Begin a new transaction.
     */
    begin(options?: TransactionOptions): Promise<Transaction>;
    /**
     * Execute a function within a transaction.
     * Automatically commits on success, rolls back on error.
     */
    withTransaction<T>(fn: (tx: Transaction) => Promise<T>, options?: TransactionOptions): Promise<T>;
    /**
     * Get an active transaction by ID.
     */
    getTransaction(transactionId: string): Transaction | undefined;
    /**
     * List all active transactions.
     */
    listActiveTransactions(): TransactionMeta[];
    /**
     * Check for conflicts before commit.
     */
    detectConflicts(transactionId: string): Promise<ConflictInfo[]>;
    /**
     * Force abort a transaction (admin operation).
     */
    forceAbort(transactionId: string): Promise<void>;
    /**
     * Clean up expired transactions.
     */
    cleanupExpired(): Promise<number>;
    /**
     * Get transaction statistics.
     */
    getStats(): TransactionStats;
}
/**
 * Transaction statistics.
 */
export interface TransactionStats {
    /** Total transactions started */
    totalStarted: number;
    /** Total transactions committed */
    totalCommitted: number;
    /** Total transactions rolled back */
    totalRolledBack: number;
    /** Total transactions aborted due to conflict */
    totalConflicts: number;
    /** Total transactions timed out */
    totalTimeouts: number;
    /** Currently active transactions */
    activeCount: number;
    /** Average transaction duration in ms */
    avgDurationMs: number;
    /** 95th percentile transaction duration in ms */
    p95DurationMs: number;
}
/**
 * CDC engine configuration options.
 */
export interface CDCEngineConfig {
    /** Enable CDC logging */
    enabled?: boolean;
    /** Maximum batch size for CDC entries */
    batchSize?: number;
    /** Flush interval in milliseconds */
    flushInterval?: number;
    /** Retention period in milliseconds */
    retentionPeriod?: number;
    /** Maximum log size before compaction */
    maxLogSize?: number;
    /** Include before/after state in entries */
    includeState?: boolean;
}
/**
 * CDC subscription for streaming changes.
 */
export interface CDCSubscription {
    /** Subscription ID */
    subscriptionId: string;
    /** Collections to watch */
    collections?: string[];
    /** Operations to watch */
    operations?: Array<'INSERT' | 'UPDATE' | 'DELETE'>;
    /** Starting cursor */
    cursor: CDCCursor;
    /** Callback for new entries */
    callback: (batch: CDCBatch) => void | Promise<void>;
    /** Error callback */
    onError?: (error: Error) => void;
    /** Close the subscription */
    close(): void;
}
/**
 * CDC engine interface for change data capture.
 */
export interface CDCEngine {
    /**
     * Log a change event.
     */
    log(entry: Omit<CDCLogEntry, 'sequenceId' | 'timestamp'>): Promise<CDCLogEntry>;
    /**
     * Log multiple change events.
     */
    logBatch(entries: Array<Omit<CDCLogEntry, 'sequenceId' | 'timestamp'>>): Promise<CDCLogEntry[]>;
    /**
     * Get CDC entries since a cursor.
     */
    getEntries(cursor: CDCCursor, options?: CDCStreamOptions): Promise<CDCStreamResult>;
    /**
     * Stream CDC entries.
     */
    stream(options?: CDCStreamOptions): AsyncIterable<CDCLogEntry>;
    /**
     * Subscribe to CDC changes.
     */
    subscribe(callback: (batch: CDCBatch) => void | Promise<void>, options?: CDCStreamOptions): CDCSubscription;
    /**
     * Get the current cursor position.
     */
    getCurrentCursor(): Promise<CDCCursor>;
    /**
     * Get a checkpoint for resuming sync.
     */
    getCheckpoint(checkpointId: string): Promise<CDCCheckpoint | null>;
    /**
     * Save a checkpoint.
     */
    saveCheckpoint(checkpoint: CDCCheckpoint): Promise<void>;
    /**
     * Filter CDC entries.
     */
    filter(entries: CDCLogEntry[], filter: CDCFilter): CDCLogEntry[];
    /**
     * Mark entries as synced.
     */
    markSynced(sequenceIds: number[]): Promise<void>;
    /**
     * Compact the CDC log (remove old entries).
     */
    compact(beforeSequence?: number): Promise<number>;
    /**
     * Get CDC statistics.
     */
    getStats(): Promise<CDCStats>;
    /**
     * Flush any buffered entries.
     */
    flush(): Promise<void>;
}
/**
 * CDC statistics.
 */
export interface CDCStats {
    /** Total entries logged */
    totalEntries: number;
    /** Total entries synced */
    totalSynced: number;
    /** Pending entries (not synced) */
    pendingCount: number;
    /** Oldest pending entry timestamp */
    oldestPendingTimestamp?: number;
    /** Current sequence ID */
    currentSequenceId: number;
    /** Log size in bytes */
    logSizeBytes: number;
    /** Entries by operation type */
    entriesByOperation: Record<string, number>;
    /** Entries by collection */
    entriesByCollection: Record<string, number>;
}
/**
 * Index type.
 */
export type IndexType = 'btree' | 'hash' | 'fulltext' | 'spatial' | 'unique';
/**
 * Index definition.
 */
export interface IndexDef {
    /** Index name */
    name: string;
    /** Collection the index belongs to */
    collection: string;
    /** Fields to index */
    fields: string[];
    /** Index type */
    type: IndexType;
    /** Whether the index enforces uniqueness */
    unique: boolean;
    /** Partial index condition (SQL WHERE clause) */
    where?: string;
    /** Index options */
    options?: Record<string, unknown>;
}
/**
 * Index statistics.
 */
export interface IndexStats {
    /** Index name */
    name: string;
    /** Number of entries in the index */
    entryCount: number;
    /** Index size in bytes */
    sizeBytes: number;
    /** Number of lookups */
    lookups: number;
    /** Number of scans */
    scans: number;
    /** Average lookup time in ms */
    avgLookupTimeMs: number;
}
/**
 * Index manager interface for managing collection indexes.
 */
export interface IndexManager {
    /**
     * Create a new index.
     */
    createIndex(definition: Omit<IndexDef, 'name'> & {
        name?: string;
    }): Promise<IndexDef>;
    /**
     * Drop an index.
     */
    dropIndex(collection: string, indexName: string): Promise<void>;
    /**
     * List all indexes for a collection.
     */
    listIndexes(collection: string): Promise<IndexDef[]>;
    /**
     * Get index by name.
     */
    getIndex(collection: string, indexName: string): Promise<IndexDef | null>;
    /**
     * Check if an index exists.
     */
    indexExists(collection: string, indexName: string): Promise<boolean>;
    /**
     * Rebuild an index.
     */
    rebuildIndex(collection: string, indexName: string): Promise<void>;
    /**
     * Get index statistics.
     */
    getIndexStats(collection: string, indexName: string): Promise<IndexStats>;
    /**
     * Suggest indexes based on query patterns.
     */
    suggestIndexes(collection: string, queryPatterns: QueryOptions[]): Promise<Array<Omit<IndexDef, 'name'>>>;
}
/**
 * Combined engine context providing access to all engines.
 */
export interface EngineContext {
    /** Storage engine instance */
    storage: StorageEngine;
    /** Query engine instance */
    query: QueryEngine;
    /** Transaction manager instance */
    transactions: TransactionManager;
    /** CDC engine instance */
    cdc: CDCEngine;
    /** Index manager instance */
    indexes: IndexManager;
    /** Shard ID for this context */
    shardId: string;
    /** Configuration */
    config: EngineContextConfig;
}
/**
 * Engine context configuration.
 */
export interface EngineContextConfig {
    storage: StorageEngineConfig;
    query: QueryEngineConfig;
    cdc: CDCEngineConfig;
}
/**
 * Factory for creating engine contexts.
 */
export interface EngineContextFactory {
    /**
     * Create a new engine context.
     */
    create(shardId: string, config?: Partial<EngineContextConfig>): Promise<EngineContext>;
    /**
     * Destroy an engine context.
     */
    destroy(context: EngineContext): Promise<void>;
}
//# sourceMappingURL=engines.d.ts.map