@framers/sql-storage-adapter 0.7.2 → 0.7.4

package/dist/cjs/features/migrations/dataImport.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Data import utilities for cross-adapter migration and restoration.
+ * Supports importing from JSON, SQL dumps, and CSV files.
+ */
+import type { StorageAdapter } from '../../core/contracts/index.js';
+import type { ExportedData } from './dataExport.js';
+/**
+ * Options for data import.
+ */
+export interface DataImportOptions {
+    /** Drop existing tables before import */
+    dropTables?: boolean;
+    /** Skip schema creation (data only) */
+    skipSchema?: boolean;
+    /** Skip data import (schema only) */
+    skipData?: boolean;
+    /** Batch size for inserts */
+    batchSize?: number;
+    /** Tables to import (all if not specified) */
+    tables?: string[];
+    /** On conflict strategy */
+    onConflict?: 'replace' | 'ignore' | 'error';
+}
+/**
+ * Import result with statistics.
+ */
+export interface ImportResult {
+    success: boolean;
+    tablesImported: number;
+    rowsImported: number;
+    errors?: string[];
+    duration: number;
+}
+/**
+ * Import data from exported JSON format.
+ */
+export declare function importData(adapter: StorageAdapter, data: ExportedData, options?: DataImportOptions): Promise<ImportResult>;
+/**
+ * Import data from JSON string.
+ */
+export declare function importFromJSON(adapter: StorageAdapter, jsonString: string, options?: DataImportOptions): Promise<ImportResult>;
+/**
+ * Import data from SQL dump.
+ */
+export declare function importFromSQL(adapter: StorageAdapter, sqlDump: string, options?: DataImportOptions): Promise<ImportResult>;
+/**
+ * Import data from CSV.
+ */
+export declare function importFromCSV(adapter: StorageAdapter, tableName: string, csvContent: string, options?: DataImportOptions): Promise<ImportResult>;
+/**
+ * Migrate data from one adapter to another.
+ */
+export declare function migrateAdapter(sourceAdapter: StorageAdapter, targetAdapter: StorageAdapter, options?: DataImportOptions): Promise<ImportResult>;
+//# sourceMappingURL=dataImport.d.ts.map

package/dist/cjs/features/migrations/dataImport.js

@@ -0,0 +1,300 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var dataImport_exports = {};
+__export(dataImport_exports, {
+  importData: () => importData,
+  importFromCSV: () => importFromCSV,
+  importFromJSON: () => importFromJSON,
+  importFromSQL: () => importFromSQL,
+  migrateAdapter: () => migrateAdapter
+});
+module.exports = __toCommonJS(dataImport_exports);
+var import_splitSqlStatements = require("../../shared/splitSqlStatements.js");
+async function importData(adapter, data, options = {}) {
+  const startTime = Date.now();
+  const { dropTables = false, skipSchema = false, skipData = false, batchSize = 100, tables, onConflict = "error" } = options;
+  const errors = [];
+  let tablesImported = 0;
+  let rowsImported = 0;
+  let tablesToImport;
+  if (tables) {
+    tablesToImport = tables;
+  } else {
+    const dataTables = Object.keys(data.data);
+    const schemaTables = data.schema?.map((s) => s.name) || [];
+    tablesToImport = Array.from(/* @__PURE__ */ new Set([...dataTables, ...schemaTables]));
+  }
+  try {
+    if (!skipSchema && data.schema) {
+      for (const tableSchema of data.schema) {
+        if (!tablesToImport.includes(tableSchema.name))
+          continue;
+        try {
+          if (dropTables) {
+            await adapter.run(`DROP TABLE IF EXISTS ${escapeIdentifier(tableSchema.name)}`);
+          }
+          await createTable(adapter, tableSchema);
+          if (skipData) {
+            tablesImported++;
+          }
+        } catch (error) {
+          const errorMsg = `Schema error for ${tableSchema.name}: ${error.message}`;
+          errors.push(errorMsg);
+          if (onConflict === "error") {
+            return {
+              success: false,
+              tablesImported,
+              rowsImported,
+              errors,
+              duration: Date.now() - startTime
+            };
+          }
+        }
+      }
+    }
+    if (!skipData) {
+      for (const [tableName, rows] of Object.entries(data.data)) {
+        if (!tablesToImport.includes(tableName))
+          continue;
+        if (!Array.isArray(rows) || rows.length === 0)
+          continue;
+        try {
+          const imported = await importTableData(adapter, tableName, rows, {
+            batchSize,
+            onConflict
+          });
+          rowsImported += imported;
+          tablesImported++;
+        } catch (error) {
+          errors.push(`Data error for ${tableName}: ${error.message}`);
+        }
+      }
+    }
+    return {
+      success: errors.length === 0,
+      tablesImported,
+      rowsImported,
+      errors: errors.length > 0 ? errors : void 0,
+      duration: Date.now() - startTime
+    };
+  } catch (error) {
+    return {
+      success: false,
+      tablesImported,
+      rowsImported,
+      errors: [...errors, `Fatal error: ${error.message}`],
+      duration: Date.now() - startTime
+    };
+  }
+}
+async function importFromJSON(adapter, jsonString, options = {}) {
+  try {
+    const data = JSON.parse(jsonString);
+    return await importData(adapter, data, options);
+  } catch (error) {
+    return {
+      success: false,
+      tablesImported: 0,
+      rowsImported: 0,
+      errors: [`JSON parse error: ${error.message}`],
+      duration: 0
+    };
+  }
+}
+async function importFromSQL(adapter, sqlDump, options = {}) {
+  const startTime = Date.now();
+  const errors = [];
+  let statementsExecuted = 0;
+  try {
+    const statements = (0, import_splitSqlStatements.splitSqlStatements)(sqlDump);
+    for (const statement of statements) {
+      try {
+        if (options.tables) {
+          const matchesTable = options.tables.some((table) => statement.toLowerCase().includes(table.toLowerCase()));
+          if (!matchesTable)
+            continue;
+        }
+        await adapter.run(statement);
+        statementsExecuted++;
+      } catch (error) {
+        errors.push(`SQL error in statement: ${error.message}`);
+      }
+    }
+    return {
+      success: errors.length === 0,
+      tablesImported: statementsExecuted,
+      rowsImported: 0,
+      // Cannot accurately count from SQL
+      errors: errors.length > 0 ? errors : void 0,
+      duration: Date.now() - startTime
+    };
+  } catch (error) {
+    return {
+      success: false,
+      tablesImported: 0,
+      rowsImported: 0,
+      errors: [...errors, `Fatal error: ${error.message}`],
+      duration: Date.now() - startTime
+    };
+  }
+}
+async function importFromCSV(adapter, tableName, csvContent, options = {}) {
+  const startTime = Date.now();
+  try {
+    const rows = parseCSV(csvContent);
+    if (rows.length === 0) {
+      return {
+        success: true,
+        tablesImported: 0,
+        rowsImported: 0,
+        duration: Date.now() - startTime
+      };
+    }
+    const imported = await importTableData(adapter, tableName, rows, {
+      batchSize: options.batchSize || 100,
+      onConflict: options.onConflict || "error"
+    });
+    return {
+      success: true,
+      tablesImported: 1,
+      rowsImported: imported,
+      duration: Date.now() - startTime
+    };
+  } catch (error) {
+    return {
+      success: false,
+      tablesImported: 0,
+      rowsImported: 0,
+      errors: [`CSV import error: ${error.message}`],
+      duration: Date.now() - startTime
+    };
+  }
+}
+async function migrateAdapter(sourceAdapter, targetAdapter, options = {}) {
+  const { exportData } = await Promise.resolve().then(() => __toESM(require("./dataExport.js")));
+  const exportedData = await exportData(sourceAdapter, {
+    tables: options.tables,
+    includeSchema: !options.skipSchema
+  });
+  return await importData(targetAdapter, exportedData, options);
+}
+async function createTable(adapter, schema) {
+  if (schema.columns.length === 0) {
+    throw new Error(`Cannot create table ${schema.name} without column definitions`);
+  }
+  const columnDefs = schema.columns.map((col) => {
+    let def = `${escapeIdentifier(col.name)} ${col.type}`;
+    if (!col.nullable)
+      def += " NOT NULL";
+    if (col.defaultValue)
+      def += ` DEFAULT ${col.defaultValue}`;
+    return def;
+  });
+  const createSQL = `CREATE TABLE IF NOT EXISTS ${escapeIdentifier(schema.name)} (
+    ${columnDefs.join(",\n    ")}
+  )`;
+  await adapter.run(createSQL);
+}
+async function importTableData(adapter, tableName, rows, options) {
+  let imported = 0;
+  const { batchSize, onConflict } = options;
+  for (let i = 0; i < rows.length; i += batchSize) {
+    const batch = rows.slice(i, i + batchSize);
+    for (const row of batch) {
+      const record = row;
+      const columns = Object.keys(record);
+      const placeholders = columns.map(() => "?");
+      let insertSQL = `INSERT `;
+      if (onConflict === "replace") {
+        insertSQL = `INSERT OR REPLACE `;
+      } else if (onConflict === "ignore") {
+        insertSQL = `INSERT OR IGNORE `;
+      }
+      insertSQL += `INTO ${escapeIdentifier(tableName)} (${columns.map(escapeIdentifier).join(", ")}) VALUES (${placeholders.join(", ")})`;
+      try {
+        await adapter.run(insertSQL, columns.map((col) => record[col]));
+        imported++;
+      } catch (error) {
+        if (onConflict === "error") {
+          throw error;
+        }
+      }
+    }
+  }
+  return imported;
+}
+function parseCSV(content) {
+  const lines = content.split("\n").filter((line) => line.trim().length > 0);
+  if (lines.length === 0)
+    return [];
+  const headers = parseCSVLine(lines[0]);
+  const rows = [];
+  for (let i = 1; i < lines.length; i++) {
+    const values = parseCSVLine(lines[i]);
+    const row = {};
+    headers.forEach((header, idx) => {
+      row[header] = values[idx] ?? null;
+    });
+    rows.push(row);
+  }
+  return rows;
+}
+function parseCSVLine(line) {
+  const values = [];
+  let current = "";
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    if (char === '"') {
+      if (inQuotes && line[i + 1] === '"') {
+        current += '"';
+        i++;
+      } else {
+        inQuotes = !inQuotes;
+      }
+    } else if (char === "," && !inQuotes) {
+      values.push(current);
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+  values.push(current);
+  return values;
+}
+function escapeIdentifier(identifier) {
+  return `"${identifier.replace(/"/g, '""')}"`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  importData,
+  importFromCSV,
+  importFromJSON,
+  importFromSQL,
+  migrateAdapter
+});

package/dist/cjs/features/migrations/migration.d.ts

@@ -0,0 +1,89 @@
+/**
+ * High-level migration utilities for moving data between adapters.
+ * Simplifies common migration scenarios like local -> Supabase, Supabase -> local, etc.
+ */
+import type { StorageAdapter } from '../../core/contracts/index.js';
+import { type ImportResult, type DataImportOptions } from './dataImport.js';
+/**
+ * Migration strategy for handling conflicts and errors.
+ */
+export interface MigrationStrategy {
+    /** Whether to drop existing tables */
+    dropExisting?: boolean;
+    /** How to handle conflicts during import */
+    onConflict?: 'replace' | 'ignore' | 'error';
+    /** Whether to verify data after migration */
+    verify?: boolean;
+    /** Batch size for operations */
+    batchSize?: number;
+    /** Tables to migrate (all if not specified) */
+    tables?: string[];
+}
+/**
+ * Migration result with detailed statistics.
+ */
+export interface MigrationResult extends ImportResult {
+    sourceAdapter: string;
+    targetAdapter: string;
+    verification?: VerificationResult;
+}
+/**
+ * Verification result after migration.
+ */
+export interface VerificationResult {
+    passed: boolean;
+    tableCounts: Record<string, {
+        source: number;
+        target: number;
+        match: boolean;
+    }>;
+    errors?: string[];
+}
+/**
+ * Migrate from Better-SQLite3 (local) to Supabase.
+ */
+export declare function migrateLocalToSupabase(localAdapter: StorageAdapter, supabaseAdapter: StorageAdapter, strategy?: MigrationStrategy): Promise<MigrationResult>;
+/**
+ * Migrate from Supabase to Better-SQLite3 (local).
+ */
+export declare function migrateSupabaseToLocal(supabaseAdapter: StorageAdapter, localAdapter: StorageAdapter, strategy?: MigrationStrategy): Promise<MigrationResult>;
+/**
+ * Migrate from Supabase to PostgreSQL.
+ */
+export declare function migrateSupabaseToPostgres(supabaseAdapter: StorageAdapter, postgresAdapter: StorageAdapter, strategy?: MigrationStrategy): Promise<MigrationResult>;
+/**
+ * Migrate from SQL.js (browser) to Capacitor SQLite (mobile).
+ */
+export declare function migrateBrowserToMobile(sqlJsAdapter: StorageAdapter, capacitorAdapter: StorageAdapter, strategy?: MigrationStrategy): Promise<MigrationResult>;
+/**
+ * Generic migration between any two adapters.
+ */
+export declare function migrateAdapters(sourceAdapter: StorageAdapter, targetAdapter: StorageAdapter, strategy?: MigrationStrategy): Promise<MigrationResult>;
+/**
+ * Create a backup of an adapter to JSON file.
+ */
+export declare function createBackup(adapter: StorageAdapter, options?: {
+    tables?: string[];
+    pretty?: boolean;
+}): Promise<string>;
+/**
+ * Restore from a backup JSON string.
+ */
+export declare function restoreFromBackup(adapter: StorageAdapter, backupJSON: string, options?: DataImportOptions): Promise<ImportResult>;
+/**
+ * Clone an adapter's data to another adapter.
+ */
+export declare function cloneAdapter(sourceAdapter: StorageAdapter, targetAdapter: StorageAdapter, options?: MigrationStrategy): Promise<MigrationResult>;
+/**
+ * Sync data between two adapters (bidirectional).
+ * NOTE: This is a simple implementation - for production use, implement proper conflict resolution.
+ */
+export declare function syncAdapters(adapter1: StorageAdapter, adapter2: StorageAdapter, strategy?: MigrationStrategy): Promise<{
+    toAdapter2: MigrationResult;
+    toAdapter1: MigrationResult;
+}>;
+/**
+ * Get migration summary for display.
+ */
+export declare function formatMigrationResult(result: MigrationResult): string;
+//# sourceMappingURL=migration.d.ts.map

package/dist/cjs/features/migrations/migration.js

@@ -0,0 +1,187 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var migration_exports = {};
+__export(migration_exports, {
+  cloneAdapter: () => cloneAdapter,
+  createBackup: () => createBackup,
+  formatMigrationResult: () => formatMigrationResult,
+  migrateAdapters: () => migrateAdapters,
+  migrateBrowserToMobile: () => migrateBrowserToMobile,
+  migrateLocalToSupabase: () => migrateLocalToSupabase,
+  migrateSupabaseToLocal: () => migrateSupabaseToLocal,
+  migrateSupabaseToPostgres: () => migrateSupabaseToPostgres,
+  restoreFromBackup: () => restoreFromBackup,
+  syncAdapters: () => syncAdapters
+});
+module.exports = __toCommonJS(migration_exports);
+var import_dataExport = require("./dataExport.js");
+var import_dataImport = require("./dataImport.js");
+async function migrateLocalToSupabase(localAdapter, supabaseAdapter, strategy = {}) {
+  return await executeMigration(localAdapter, supabaseAdapter, "better-sqlite3", "supabase", strategy);
+}
+async function migrateSupabaseToLocal(supabaseAdapter, localAdapter, strategy = {}) {
+  return await executeMigration(supabaseAdapter, localAdapter, "supabase", "better-sqlite3", strategy);
+}
+async function migrateSupabaseToPostgres(supabaseAdapter, postgresAdapter, strategy = {}) {
+  return await executeMigration(supabaseAdapter, postgresAdapter, "supabase", "postgres", strategy);
+}
+async function migrateBrowserToMobile(sqlJsAdapter, capacitorAdapter, strategy = {}) {
+  return await executeMigration(sqlJsAdapter, capacitorAdapter, "sql.js", "capacitor-sqlite", strategy);
+}
+async function migrateAdapters(sourceAdapter, targetAdapter, strategy = {}) {
+  return await executeMigration(sourceAdapter, targetAdapter, "unknown", "unknown", strategy);
+}
+async function executeMigration(sourceAdapter, targetAdapter, sourceName, targetName, strategy) {
+  const importOptions = {
+    dropTables: strategy.dropExisting,
+    onConflict: strategy.onConflict,
+    batchSize: strategy.batchSize,
+    tables: strategy.tables
+  };
+  const result = await (0, import_dataImport.migrateAdapter)(sourceAdapter, targetAdapter, importOptions);
+  const migrationResult = {
+    ...result,
+    sourceAdapter: sourceName,
+    targetAdapter: targetName
+  };
+  if (strategy.verify && result.success) {
+    migrationResult.verification = await verifyMigration(sourceAdapter, targetAdapter, strategy.tables);
+  }
+  return migrationResult;
+}
+async function verifyMigration(sourceAdapter, targetAdapter, tables) {
+  const errors = [];
+  const tableCounts = {};
+  try {
+    const sourceData = await (0, import_dataExport.exportData)(sourceAdapter, { tables, includeSchema: false });
+    const targetData = await (0, import_dataExport.exportData)(targetAdapter, { tables, includeSchema: false });
+    for (const tableName of Object.keys(sourceData.data)) {
+      const sourceCount = sourceData.data[tableName]?.length || 0;
+      const targetCount = targetData.data[tableName]?.length || 0;
+      const match = sourceCount === targetCount;
+      tableCounts[tableName] = {
+        source: sourceCount,
+        target: targetCount,
+        match
+      };
+      if (!match) {
+        errors.push(`Table ${tableName}: source has ${sourceCount} rows, target has ${targetCount} rows`);
+      }
+    }
+    for (const tableName of Object.keys(targetData.data)) {
+      if (!sourceData.data[tableName]) {
+        errors.push(`Table ${tableName} exists in target but not in source`);
+      }
+    }
+    return {
+      passed: errors.length === 0,
+      tableCounts,
+      errors: errors.length > 0 ? errors : void 0
+    };
+  } catch (error) {
+    return {
+      passed: false,
+      tableCounts,
+      errors: [`Verification failed: ${error.message}`]
+    };
+  }
+}
+async function createBackup(adapter, options = {}) {
+  return await (0, import_dataExport.exportAsJSON)(adapter, {
+    tables: options.tables,
+    includeSchema: true,
+    pretty: options.pretty ?? true
+  });
+}
+async function restoreFromBackup(adapter, backupJSON, options = {}) {
+  const { importFromJSON } = await Promise.resolve().then(() => __toESM(require("./dataImport.js")));
+  return await importFromJSON(adapter, backupJSON, options);
+}
+async function cloneAdapter(sourceAdapter, targetAdapter, options = {}) {
+  return await migrateAdapters(sourceAdapter, targetAdapter, {
+    ...options,
+    verify: options.verify ?? true
+  });
+}
+async function syncAdapters(adapter1, adapter2, strategy = {}) {
+  const toAdapter2 = await migrateAdapters(adapter1, adapter2, {
+    ...strategy,
+    onConflict: "replace"
+  });
+  const toAdapter1 = await migrateAdapters(adapter2, adapter1, {
+    ...strategy,
+    onConflict: "replace"
+  });
+  return { toAdapter2, toAdapter1 };
+}
+function formatMigrationResult(result) {
+  const lines = [];
+  lines.push("=".repeat(60));
+  lines.push("Migration Result");
+  lines.push("=".repeat(60));
+  lines.push(`Source: ${result.sourceAdapter}`);
+  lines.push(`Target: ${result.targetAdapter}`);
+  lines.push(`Status: ${result.success ? "[OK] SUCCESS" : "[X] FAILED"}`);
+  lines.push(`Duration: ${result.duration}ms`);
+  lines.push(`Tables: ${result.tablesImported}`);
+  lines.push(`Rows: ${result.rowsImported}`);
+  if (result.errors && result.errors.length > 0) {
+    lines.push("\nErrors:");
+    result.errors.forEach((err) => lines.push(`  [X] ${err}`));
+  }
+  if (result.verification) {
+    lines.push("\nVerification:");
+    lines.push(`Status: ${result.verification.passed ? "[OK] PASSED" : "[X] FAILED"}`);
+    if (Object.keys(result.verification.tableCounts).length > 0) {
+      lines.push("\nTable Counts:");
+      for (const [table, counts] of Object.entries(result.verification.tableCounts)) {
+        const status = counts.match ? "[OK]" : "[X]";
+        lines.push(`  ${status} ${table}: source=${counts.source}, target=${counts.target}`);
+      }
+    }
+    if (result.verification.errors && result.verification.errors.length > 0) {
+      lines.push("\nVerification Errors:");
+      result.verification.errors.forEach((err) => lines.push(`  [X] ${err}`));
+    }
+  }
+  lines.push("=".repeat(60));
+  return lines.join("\n");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cloneAdapter,
+  createBackup,
+  formatMigrationResult,
+  migrateAdapters,
+  migrateBrowserToMobile,
+  migrateLocalToSupabase,
+  migrateSupabaseToLocal,
+  migrateSupabaseToPostgres,
+  restoreFromBackup,
+  syncAdapters
+});