@liorandb/core 1.0.16 → 1.0.18

package/src/core/migration.ts

@@ -0,0 +1,162 @@
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+import type { LioranDB } from "./database.js";
+
+export type MigrationFn = (db: LioranDB) => Promise<void>;
+
+type MigrationRecord = {
+  from: string;
+  to: string;
+  checksum: string;
+  appliedAt: number;
+};
+
+const LOCK_FILE = "__migration.lock";
+const HISTORY_FILE = "__migration_history.json";
+
+export class MigrationEngine {
+  private migrations = new Map<string, MigrationFn>();
+
+  constructor(private db: LioranDB) {}
+
+  /* ------------------------------------------------------------ */
+  /* Public API */
+  /* ------------------------------------------------------------ */
+
+  register(from: string, to: string, fn: MigrationFn) {
+    const key = `${from}→${to}`;
+
+    if (this.migrations.has(key)) {
+      throw new Error(`Duplicate migration: ${key}`);
+    }
+
+    this.migrations.set(key, fn);
+  }
+
+  async migrate(from: string, to: string, fn: MigrationFn) {
+    this.register(from, to, fn);
+    await this.execute();
+  }
+
+  async upgradeToLatest() {
+    await this.execute();
+  }
+
+  /* ------------------------------------------------------------ */
+  /* Core Execution Logic */
+  /* ------------------------------------------------------------ */
+
+  private async execute() {
+    let current = this.db.getSchemaVersion();
+
+    while (true) {
+      const next = this.findNext(current);
+      if (!next) break;
+
+      const fn = this.migrations.get(`${current}→${next}`)!;
+      await this.runMigration(current, next, fn);
+      current = next;
+    }
+  }
+
+  private findNext(current: string): string | null {
+    for (const key of this.migrations.keys()) {
+      const [from, to] = key.split("→");
+      if (from === current) return to;
+    }
+    return null;
+  }
+
+  /* ------------------------------------------------------------ */
+  /* Atomic Migration Execution */
+  /* ------------------------------------------------------------ */
+
+  private async runMigration(from: string, to: string, fn: MigrationFn) {
+    const current = this.db.getSchemaVersion();
+    if (current !== from) {
+      throw new Error(
+        `Schema mismatch: DB=${current}, expected=${from}`
+      );
+    }
+
+    const lockPath = path.join(this.db.basePath, LOCK_FILE);
+
+    if (fs.existsSync(lockPath)) {
+      throw new Error(
+        "Previous migration interrupted. Resolve manually before continuing."
+      );
+    }
+
+    this.acquireLock(lockPath);
+
+    try {
+      await this.db.transaction(async () => {
+        await fn(this.db);
+        this.writeHistory(from, to, fn);
+        this.db.setSchemaVersion(to);
+      });
+    } finally {
+      this.releaseLock(lockPath);
+    }
+  }
+
+  /* ------------------------------------------------------------ */
+  /* Locking */
+  /* ------------------------------------------------------------ */
+
+  private acquireLock(file: string) {
+    const token = crypto.randomBytes(16).toString("hex");
+
+    fs.writeFileSync(
+      file,
+      JSON.stringify({
+        pid: process.pid,
+        token,
+        time: Date.now(),
+      })
+    );
+  }
+
+  private releaseLock(file: string) {
+    if (fs.existsSync(file)) fs.unlinkSync(file);
+  }
+
+  /* ------------------------------------------------------------ */
+  /* Migration History */
+  /* ------------------------------------------------------------ */
+
+  private historyPath() {
+    return path.join(this.db.basePath, HISTORY_FILE);
+  }
+
+  private readHistory(): MigrationRecord[] {
+    if (!fs.existsSync(this.historyPath())) return [];
+    return JSON.parse(fs.readFileSync(this.historyPath(), "utf8"));
+  }
+
+  private writeHistory(from: string, to: string, fn: MigrationFn) {
+    const history = this.readHistory();
+
+    history.push({
+      from,
+      to,
+      checksum: this.hash(fn.toString()),
+      appliedAt: Date.now(),
+    });
+
+    fs.writeFileSync(this.historyPath(), JSON.stringify(history, null, 2));
+  }
+
+  private hash(data: string) {
+    return crypto.createHash("sha256").update(data).digest("hex");
+  }
+
+  /* ------------------------------------------------------------ */
+  /* Diagnostics */
+  /* ------------------------------------------------------------ */
+
+  getHistory(): MigrationRecord[] {
+    return this.readHistory();
+  }
+}

package/src/core/migration.types.ts

@@ -0,0 +1,22 @@
+import type { LioranDB } from "./database.js";
+
+export type MigrationVersion = string;
+
+export type MigrationFn = (db: LioranDB) => Promise<void>;
+
+export interface Migration {
+  from: MigrationVersion;
+  to: MigrationVersion;
+  run: MigrationFn;
+}
+
+export interface MigrationRecord {
+  version: MigrationVersion;
+  appliedAt: number;
+}
+
+export interface MigrationMeta {
+  id?: string;
+  currentVersion: MigrationVersion;
+  history: MigrationRecord[];
+}

package/src/types/index.ts

@@ -1,63 +1,136 @@
-/* ----------------------------- MANAGER OPTIONS ----------------------------- */
+/* ============================= MANAGER OPTIONS ============================= */
 
 export interface LioranManagerOptions {
-  rootPath?: string
-  encryptionKey?: string | Buffer
-  ipc?: boolean
+  rootPath?: string;
+  encryptionKey?: string | Buffer;
+  ipc?: boolean;
+
+  /**
+   * If true, database auto-applies pending migrations on startup.
+   */
+  autoMigrate?: boolean;
 }
 
-/* ----------------------------- UPDATE OPTIONS ----------------------------- */
+/* ============================= UPDATE OPTIONS ============================= */
 
 export interface UpdateOptions {
-  upsert?: boolean
+  upsert?: boolean;
+
+  /**
+   * If true, returns the modified document instead of the original.
+   */
+  returnNew?: boolean;
 }
 
-/* --------------------------------- QUERY --------------------------------- */
+/* ================================ QUERY =================================== */
 
-export type Query<T = any> = Partial<T> & {
-  [key: string]: any
-}
+export type Query<T = any> =
+  | Partial<T>
+  | {
+      [K in keyof T]?: any;
+    } & {
+      [key: string]: any;
+    };
 
-/* --------------------------------- INDEX --------------------------------- */
+/* ================================ INDEX =================================== */
 
-export type IndexType = "hash" | "btree"
+export type IndexType = "hash" | "btree";
 
 export interface IndexDefinition<T = any> {
-  field: keyof T | string
-  unique?: boolean
-  sparse?: boolean
-  type?: IndexType
+  field: keyof T | string;
+  unique?: boolean;
+  sparse?: boolean;
+  type?: IndexType;
 }
 
 export interface IndexMetadata {
-  field: string
-  unique: boolean
-  sparse: boolean
-  type: IndexType
-  createdAt: number
+  field: string;
+  unique: boolean;
+  sparse: boolean;
+  type: IndexType;
+  createdAt: number;
 }
 
-/* ----------------------------- QUERY PLANNER ------------------------------ */
+/* =========================== QUERY PLANNER ================================ */
 
 export interface QueryExplainPlan {
-  indexUsed?: string
-  indexType?: IndexType
-  scannedDocuments: number
-  returnedDocuments: number
-  executionTimeMs: number
+  indexUsed?: string;
+  indexType?: IndexType;
+  scannedDocuments: number;
+  returnedDocuments: number;
+  executionTimeMs: number;
+}
+
+/* ========================== SCHEMA VERSIONING ============================= */
+
+/**
+ * Per-collection document schema version
+ */
+export type SchemaVersion = number;
+
+/**
+ * Collection-level migration definition
+ */
+export interface CollectionMigration<T = any> {
+  from: SchemaVersion;
+  to: SchemaVersion;
+  migrate: (doc: any) => T;
+}
+
+/**
+ * Database-level migration definition
+ */
+export interface DatabaseMigration {
+  from: string;
+  to: string;
+  migrate: () => Promise<void>;
 }
 
-/* ------------------------------ COLLECTION -------------------------------- */
+/* ============================== COLLECTION ================================ */
+
+export interface CollectionOptions<T = any> {
+  /**
+   * Zod schema used for validation
+   */
+  schema?: any;
+
+  /**
+   * Current document schema version
+   */
+  schemaVersion?: SchemaVersion;
+
+  /**
+   * Optional migrations for automatic document upgrading
+   */
+  migrations?: CollectionMigration<T>[];
+}
 
 export interface CollectionIndexAPI<T = any> {
-  createIndex(def: IndexDefinition<T>): Promise<void>
-  dropIndex(field: keyof T | string): Promise<void>
-  listIndexes(): Promise<IndexMetadata[]>
-  rebuildIndexes(): Promise<void>
+  createIndex(def: IndexDefinition<T>): Promise<void>;
+  dropIndex(field: keyof T | string): Promise<void>;
+  listIndexes(): Promise<IndexMetadata[]>;
+  rebuildIndexes(): Promise<void>;
 }
 
-/* ------------------------------- DATABASE --------------------------------- */
+/* =============================== DATABASE ================================= */
 
 export interface DatabaseIndexAPI {
-  rebuildAllIndexes(): Promise<void>
+  rebuildAllIndexes(): Promise<void>;
+}
+
+/**
+ * Database migration coordination API
+ */
+export interface DatabaseMigrationAPI {
+  migrate(
+    from: string,
+    to: string,
+    fn: () => Promise<void>
+  ): void;
+
+  applyMigrations(targetVersion: string): Promise<void>;
+
+  getSchemaVersion(): string;
+
+  setSchemaVersion(version: string): void;
 }