smartmongo/ts/ts_tsmdb/storage/IStorageAdapter.ts

import type * as plugins from '../plugins.js';
import type { IStoredDocument, IOpLogEntry, Document } from '../types/interfaces.js';

/**
 * Storage adapter interface for TsmDB
 * Implementations can provide different storage backends (memory, file, etc.)
 */
export interface IStorageAdapter {
  /**
   * Initialize the storage adapter
   */
  initialize(): Promise<void>;

  /**
   * Close the storage adapter and release resources
   */
  close(): Promise<void>;

  // ============================================================================
  // Database Operations
  // ============================================================================

  /**
   * List all database names
   */
  listDatabases(): Promise<string[]>;

  /**
   * Create a database (typically lazy - just marks it as existing)
   */
  createDatabase(dbName: string): Promise<void>;

  /**
   * Drop a database and all its collections
   */
  dropDatabase(dbName: string): Promise<boolean>;

  /**
   * Check if a database exists
   */
  databaseExists(dbName: string): Promise<boolean>;

  // ============================================================================
  // Collection Operations
  // ============================================================================

  /**
   * List all collection names in a database
   */
  listCollections(dbName: string): Promise<string[]>;

  /**
   * Create a collection
   */
  createCollection(dbName: string, collName: string): Promise<void>;

  /**
   * Drop a collection
   */
  dropCollection(dbName: string, collName: string): Promise<boolean>;

  /**
   * Check if a collection exists
   */
  collectionExists(dbName: string, collName: string): Promise<boolean>;

  /**
   * Rename a collection
   */
  renameCollection(dbName: string, oldName: string, newName: string): Promise<void>;

  // ============================================================================
  // Document Operations
  // ============================================================================

  /**
   * Insert a single document
   * @returns The inserted document with _id
   */
  insertOne(dbName: string, collName: string, doc: Document): Promise<IStoredDocument>;

  /**
   * Insert multiple documents
   * @returns Array of inserted documents with _ids
   */
  insertMany(dbName: string, collName: string, docs: Document[]): Promise<IStoredDocument[]>;

  /**
   * Find all documents in a collection
   */
  findAll(dbName: string, collName: string): Promise<IStoredDocument[]>;

  /**
   * Find documents by a set of _id strings (hex format)
   * Used for index-accelerated queries
   */
  findByIds(dbName: string, collName: string, ids: Set<string>): Promise<IStoredDocument[]>;

  /**
   * Find a document by _id
   */
  findById(dbName: string, collName: string, id: plugins.bson.ObjectId): Promise<IStoredDocument | null>;

  /**
   * Update a document by _id
   * @returns true if document was updated
   */
  updateById(dbName: string, collName: string, id: plugins.bson.ObjectId, doc: IStoredDocument): Promise<boolean>;

  /**
   * Delete a document by _id
   * @returns true if document was deleted
   */
  deleteById(dbName: string, collName: string, id: plugins.bson.ObjectId): Promise<boolean>;

  /**
   * Delete multiple documents by _id
   * @returns Number of deleted documents
   */
  deleteByIds(dbName: string, collName: string, ids: plugins.bson.ObjectId[]): Promise<number>;

  /**
   * Get the count of documents in a collection
   */
  count(dbName: string, collName: string): Promise<number>;

  // ============================================================================
  // Index Operations
  // ============================================================================

  /**
   * Store index metadata
   */
  saveIndex(
    dbName: string,
    collName: string,
    indexName: string,
    indexSpec: { key: Record<string, any>; unique?: boolean; sparse?: boolean; expireAfterSeconds?: number }
  ): Promise<void>;

  /**
   * Get all index metadata for a collection
   */
  getIndexes(dbName: string, collName: string): Promise<Array<{
    name: string;
    key: Record<string, any>;
    unique?: boolean;
    sparse?: boolean;
    expireAfterSeconds?: number;
  }>>;

  /**
   * Drop an index
   */
  dropIndex(dbName: string, collName: string, indexName: string): Promise<boolean>;

  // ============================================================================
  // OpLog Operations (for change streams)
  // ============================================================================

  /**
   * Append an operation to the oplog
   */
  appendOpLog(entry: IOpLogEntry): Promise<void>;

  /**
   * Get oplog entries after a timestamp
   */
  getOpLogAfter(ts: plugins.bson.Timestamp, limit?: number): Promise<IOpLogEntry[]>;

  /**
   * Get the latest oplog timestamp
   */
  getLatestOpLogTimestamp(): Promise<plugins.bson.Timestamp | null>;

  // ============================================================================
  // Transaction Support
  // ============================================================================

  /**
   * Create a snapshot of current data for transaction isolation
   */
  createSnapshot(dbName: string, collName: string): Promise<IStoredDocument[]>;

  /**
   * Check if any documents have been modified since the snapshot
   */
  hasConflicts(
    dbName: string,
    collName: string,
    ids: plugins.bson.ObjectId[],
    snapshotTime: plugins.bson.Timestamp
  ): Promise<boolean>;

  // ============================================================================
  // Persistence (optional, for MemoryStorageAdapter with file backup)
  // ============================================================================

  /**
   * Persist current state to disk (if supported)
   */
  persist?(): Promise<void>;

  /**
   * Load state from disk (if supported)
   */
  restore?(): Promise<void>;
}