@framers/sql-storage-adapter 0.7.1 → 0.7.3

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

@@ -0,0 +1,93 @@
+/**
+ * A versioned schema-migration runner over StorageAdapter, for PostgreSQL and
+ * SQLite alike. It applies hand-written SQL files in number order, each in its
+ * own transaction, records each in a ledger table with the SHA-256 of its text,
+ * refuses an applied file whose text changed, and stops at the first error.
+ *
+ * Locking: on PostgreSQL each file's transaction first takes a
+ * transaction-scoped advisory lock, and checks the ledger again under it, so
+ * two runners at once apply each file once. A file marked to run outside a
+ * transaction (CREATE INDEX CONCURRENTLY) runs under the session-level lock on
+ * one held connection. On SQLite the file's write transaction is the lock.
+ *
+ * @module
+ */
+import type { StorageAdapter } from '../../core/contracts/index.js';
+/** One migration: its file name, which orders it, and its SQL. */
+export interface SchemaMigration {
+    name: string;
+    sql: string;
+}
+/** How the runner names its ledger and lock, and what it does with surprises. */
+export interface SchemaMigrationOptions {
+    /** The ledger table, schema-qualified if need be. Default: `schema_migrations`. */
+    table?: string;
+    /** The ledger column that holds each file's SHA-256 in hex. Default: `checksum`. */
+    checksumColumn?: string;
+    /**
+     * The PostgreSQL advisory lock key: an integer, or text hashed with
+     * `hashtext()`. Default: 724313571. Runners that share a database share a key.
+     */
+    lockKey?: number | string;
+    /**
+     * A ledger row whose file the list lacks (the database is ahead of the
+     * code): `'refuse'` (the default) stops before applying anything; `'ignore'`
+     * goes on.
+     */
+    unknown?: 'refuse' | 'ignore';
+    /**
+     * A file whose first line, trimmed, is this runs outside a transaction.
+     * Default: `-- outside transaction`.
+     */
+    outsideTransactionMarker?: string;
+}
+/** What a run or a status check found. */
+export interface SchemaMigrationReport {
+    /** Applied by this run, in order (a status check applies none, and lists the files the ledger holds unchanged). */
+    applied: string[];
+    /** Already in the ledger with the same checksum: a run skipped them. */
+    skipped: string[];
+    /** In the list and not in the ledger: a status check's pending files. */
+    pending: string[];
+    /** In the ledger with a different checksum. */
+    changed: string[];
+    /** In the ledger and not in the list. */
+    unknown: string[];
+}
+/** Options for reading a migrations folder. */
+export interface ReadSchemaMigrationsOptions {
+    /** Reads `<dir>/<dialect>` when that folder exists, else `<dir>`. */
+    dialect?: 'postgres' | 'sqlite';
+    /**
+     * The file-name form, whose first capture group is the number that orders
+     * the file. Default: digits, an underscore, then lower-case letters, digits
+     * and underscores, `.sql` (`001_init.sql`, `0001_accounts.sql`).
+     */
+    namePattern?: RegExp;
+}
+/**
+ * Reads the migrations of a folder in number order: `<dir>/<dialect>` when
+ * that folder exists, else `<dir>`. Files not ending in `.sql` are left out; a
+ * `.sql` name out of form, or a number used twice, is refused. Node only.
+ */
+export declare function readSchemaMigrations(dir: string, options?: ReadSchemaMigrationsOptions): Promise<SchemaMigration[]>;
+/**
+ * Compares the list with the ledger and applies nothing: `applied` lists the
+ * files the ledger holds unchanged, `pending` the files it lacks, `changed`
+ * the files whose text differs from what was applied, `unknown` the ledger
+ * rows the list lacks. Creates the ledger when it is missing.
+ */
+export declare function schemaMigrationStatus(adapter: StorageAdapter, migrations: SchemaMigration[], options?: SchemaMigrationOptions): Promise<SchemaMigrationReport>;
+/**
+ * Applies every migration the ledger lacks, in list order, and reports what
+ * it did: `applied` (this run) and `skipped` (already applied). Refuses to
+ * start when an applied file's text changed, or (unless `unknown: 'ignore'`)
+ * when the ledger holds a file the list lacks. A file runs in its own
+ * transaction and holds no BEGIN or COMMIT; a file whose first line is the
+ * outside-transaction marker runs outside one (on PostgreSQL that needs
+ * `withConnection`, which PostgresAdapter has). Stops at the first error,
+ * after rolling that file back, with an error that names it and carries the
+ * database's error as `cause`.
+ */
+export declare function runSchemaMigrations(adapter: StorageAdapter, migrations: SchemaMigration[], options?: SchemaMigrationOptions): Promise<SchemaMigrationReport>;
+//# sourceMappingURL=schemaMigrations.d.ts.map

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

@@ -0,0 +1,220 @@
+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 schemaMigrations_exports = {};
+__export(schemaMigrations_exports, {
+  readSchemaMigrations: () => readSchemaMigrations,
+  runSchemaMigrations: () => runSchemaMigrations,
+  schemaMigrationStatus: () => schemaMigrationStatus
+});
+module.exports = __toCommonJS(schemaMigrations_exports);
+var import_features = require("../../core/contracts/features.js");
+var import_logger = require("../../shared/logger.js");
+const DEFAULT_TABLE = "schema_migrations";
+const DEFAULT_CHECKSUM_COLUMN = "checksum";
+const DEFAULT_LOCK_KEY = 724313571;
+const DEFAULT_MARKER = "-- outside transaction";
+const DEFAULT_NAME = /^(\d+)_[a-z0-9_]+\.sql$/;
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/;
+const sha256Hex = async (text) => {
+  const subtle = globalThis.crypto?.subtle;
+  if (subtle) {
+    const digest = await subtle.digest("SHA-256", new TextEncoder().encode(text));
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+  }
+  const { createHash } = await Promise.resolve().then(() => __toESM(require("crypto")));
+  return createHash("sha256").update(text).digest("hex");
+};
+const checkIdentifier = (what, value) => {
+  if (typeof value !== "string" || !IDENTIFIER.test(value)) {
+    throw new Error(`${what} must be an SQL identifier (letters, digits and underscores, optionally schema-qualified); got ${JSON.stringify(value)}.`);
+  }
+  return value;
+};
+async function readSchemaMigrations(dir, options = {}) {
+  const { readdir, readFile, stat } = await Promise.resolve().then(() => __toESM(require("fs/promises")));
+  const path = await Promise.resolve().then(() => __toESM(require("path")));
+  const pattern = options.namePattern ?? DEFAULT_NAME;
+  let folder = dir;
+  if (options.dialect) {
+    const own = path.join(dir, options.dialect);
+    const isFolder = await stat(own).then((entry) => entry.isDirectory(), () => false);
+    if (isFolder)
+      folder = own;
+  }
+  const numbers = /* @__PURE__ */ new Map();
+  const entries = [];
+  for (const name of await readdir(folder)) {
+    if (!name.endsWith(".sql"))
+      continue;
+    const number = pattern.exec(name)?.[1];
+    if (number === void 0) {
+      throw new Error(`${name}: a migration's name is digits, an underscore and a lower-case name, ending in .sql.`);
+    }
+    const key = String(Number(number));
+    if (numbers.has(key))
+      throw new Error(`${name}: the number ${number} is used twice (also ${numbers.get(key)}).`);
+    numbers.set(key, name);
+    entries.push({ name, number: Number(number) });
+  }
+  entries.sort((a, b) => a.number - b.number || a.name.localeCompare(b.name));
+  return Promise.all(entries.map(async ({ name }) => ({ name, sql: await readFile(path.join(folder, name), "utf8") })));
+}
+const resolve = (adapter, options) => {
+  const table = checkIdentifier("table", options.table ?? DEFAULT_TABLE);
+  const checksumColumn = checkIdentifier("checksumColumn", options.checksumColumn ?? DEFAULT_CHECKSUM_COLUMN);
+  const key = options.lockKey ?? DEFAULT_LOCK_KEY;
+  if (typeof key === "number" && !Number.isSafeInteger(key))
+    throw new Error(`lockKey must be a safe integer or text; got ${key}.`);
+  const dialect = (0, import_features.createStorageFeatures)(adapter).dialect.name;
+  const keyExpr = typeof key === "number" ? "?" : "hashtext(?)";
+  return {
+    table,
+    checksumColumn,
+    lock: dialect === "postgres" ? {
+      sql: `SELECT pg_advisory_xact_lock(${keyExpr})`,
+      session: `SELECT pg_advisory_lock(${keyExpr})`,
+      unlock: `SELECT pg_advisory_unlock(${keyExpr})`,
+      params: [key]
+    } : null,
+    unknown: options.unknown ?? "refuse",
+    marker: options.outsideTransactionMarker ?? DEFAULT_MARKER,
+    dialect
+  };
+};
+const ledgerDdl = (r) => r.dialect === "postgres" ? `CREATE TABLE IF NOT EXISTS ${r.table} (name TEXT PRIMARY KEY, ${r.checksumColumn} TEXT NOT NULL, applied_at TIMESTAMPTZ NOT NULL DEFAULT now())` : `CREATE TABLE IF NOT EXISTS ${r.table} (name TEXT PRIMARY KEY, ${r.checksumColumn} TEXT NOT NULL, applied_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')))`;
+const inLockedTransaction = (adapter, r, work) => adapter.transaction(async (trx) => {
+  if (r.lock)
+    await trx.get(r.lock.sql, r.lock.params);
+  return work(trx);
+});
+const ledgerRows = async (db, r) => {
+  const rows = await db.all(`SELECT name, ${r.checksumColumn} AS checksum FROM ${r.table}`);
+  return new Map(rows.map((row) => [row.name, row.checksum]));
+};
+const compare = (list, ledger) => {
+  const report = { applied: [], pending: [], changed: [], unknown: [] };
+  const carried = new Set(list.map((migration) => migration.name));
+  for (const migration of list) {
+    const recorded2 = ledger.get(migration.name);
+    if (recorded2 === void 0)
+      report.pending.push(migration.name);
+    else if (recorded2 !== migration.checksum)
+      report.changed.push(migration.name);
+    else
+      report.applied.push(migration.name);
+  }
+  report.unknown = [...ledger.keys()].filter((name) => !carried.has(name)).sort();
+  return report;
+};
+const withChecksums = (migrations) => Promise.all(migrations.map(async (migration) => ({ ...migration, checksum: await sha256Hex(migration.sql) })));
+const ensureLedger = (adapter, r) => inLockedTransaction(adapter, r, async (trx) => {
+  await trx.exec(ledgerDdl(r));
+});
+async function schemaMigrationStatus(adapter, migrations, options = {}) {
+  const r = resolve(adapter, options);
+  await ensureLedger(adapter, r);
+  return { ...compare(await withChecksums(migrations), await ledgerRows(adapter, r)), skipped: [] };
+}
+async function runSchemaMigrations(adapter, migrations, options = {}) {
+  const r = resolve(adapter, options);
+  const list = await withChecksums(migrations);
+  await ensureLedger(adapter, r);
+  const before = compare(list, await ledgerRows(adapter, r));
+  if (before.changed.length) {
+    throw new Error(`Applied migrations differ from the files given: ${before.changed.join(", ")}. An applied migration never changes.`);
+  }
+  if (before.unknown.length && r.unknown === "refuse") {
+    throw new Error(`The database has applied migrations the list lacks: ${before.unknown.join(", ")}. Run the newer code, or pass unknown: 'ignore'.`);
+  }
+  const report = { applied: [], skipped: [...before.applied], pending: [], changed: [], unknown: before.unknown };
+  for (const migration of list) {
+    if (!before.pending.includes(migration.name))
+      continue;
+    let applied;
+    try {
+      applied = outsideTransaction(migration, r) ? await applyOutside(adapter, r, migration) : await applyInside(adapter, r, migration);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const failure = new Error(`Migration ${migration.name} failed: ${message}`);
+      failure.cause = error;
+      throw failure;
+    }
+    (applied ? report.applied : report.skipped).push(migration.name);
+    if (applied)
+      (0, import_logger.getStorageLogger)().info({ migration: migration.name, table: r.table }, `Applied migration ${migration.name}.`);
+  }
+  return report;
+}
+const outsideTransaction = (migration, r) => migration.sql.split("\n", 1)[0]?.trim() === r.marker;
+const recorded = async (db, r, name) => (await db.get(`SELECT ${r.checksumColumn} AS checksum FROM ${r.table} WHERE name = ?`, [name]))?.checksum;
+const appliedAlready = (migration, checksum) => {
+  if (checksum === void 0)
+    return false;
+  if (checksum !== migration.checksum) {
+    throw new Error(`it was applied with checksum ${checksum} and now reads ${migration.checksum}`);
+  }
+  return true;
+};
+const record = (db, r, migration) => db.run(`INSERT INTO ${r.table} (name, ${r.checksumColumn}) VALUES (?, ?)`, [migration.name, migration.checksum]);
+const applyInside = (adapter, r, migration) => inLockedTransaction(adapter, r, async (trx) => {
+  if (appliedAlready(migration, await recorded(trx, r, migration.name)))
+    return false;
+  await trx.exec(migration.sql);
+  await record(trx, r, migration);
+  return true;
+});
+const applyOutside = async (adapter, r, migration) => {
+  const work = async (db) => {
+    if (appliedAlready(migration, await recorded(db, r, migration.name)))
+      return false;
+    await db.exec(migration.sql);
+    await record(db, r, migration);
+    return true;
+  };
+  if (!r.lock)
+    return work(adapter);
+  const held = adapter;
+  if (typeof held.withConnection !== "function") {
+    throw new Error("a file outside a transaction needs an adapter with withConnection() on PostgreSQL, to hold the lock on one session");
+  }
+  const { params, session, unlock } = r.lock;
+  return held.withConnection(async (connection) => {
+    await connection.get(session, params);
+    try {
+      return await work(connection);
+    } finally {
+      await connection.get(unlock, params);
+    }
+  });
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  readSchemaMigrations,
+  runSchemaMigrations,
+  schemaMigrationStatus
+});

package/dist/cjs/features/sync/conflicts/conflictResolver.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Conflict Detection and Resolution.
+ *
+ * Provides conflict detection using vector clocks and
+ * configurable resolution strategies with UI hooks.
+ *
+ * @packageDocumentation
+ */
+import type { VectorClockData } from '../protocol/vectorClock.js';
+/**
+ * Conflict resolution strategy.
+ */
+export type ConflictStrategy = 'last-write-wins' | 'local-wins' | 'remote-wins' | 'merge' | 'manual';
+/**
+ * Resolution decision for a conflict.
+ */
+export type ResolutionDecision = 'use_local' | 'use_remote' | 'use_merged' | 'keep_both' | 'defer';
+/**
+ * Represents a sync conflict between local and remote data.
+ */
+export interface SyncConflict {
+    /** Unique conflict identifier */
+    conflictId: string;
+    /** Table where conflict occurred */
+    tableName: string;
+    /** Primary key of the conflicting record */
+    recordId: string;
+    /** Local version of the data */
+    localData: Record<string, unknown>;
+    /** Remote version of the data */
+    remoteData: Record<string, unknown>;
+    /** Local vector clock */
+    localClock: VectorClockData;
+    /** Remote vector clock */
+    remoteClock: VectorClockData;
+    /** Local device ID */
+    localDeviceId: string;
+    /** Remote device ID */
+    remoteDeviceId: string;
+    /** When the conflict was detected */
+    detectedAt: number;
+    /** Fields that differ between versions */
+    conflictingFields: string[];
+    /** Conflict status */
+    status: 'pending' | 'resolved' | 'deferred';
+}
+/**
+ * Resolution result after conflict is resolved.
+ */
+export interface ConflictResolution {
+    /** How the conflict was resolved */
+    decision: ResolutionDecision;
+    /** Merged data if decision is 'use_merged' */
+    mergedData?: Record<string, unknown>;
+    /** Merged vector clock */
+    mergedClock: VectorClockData;
+    /** Who/what resolved the conflict */
+    resolvedBy: 'auto' | 'user' | 'strategy';
+    /** Resolution timestamp */
+    resolvedAt: number;
+    /** Optional reason for the resolution */
+    reason?: string;
+}
+/**
+ * UI hooks for conflict resolution.
+ */
+export interface ConflictUIHooks {
+    /**
+     * Called when a conflict requires manual resolution.
+     * Return the resolution decision from the UI.
+     */
+    onConflictNeedsResolution?: (conflict: SyncConflict) => Promise<ConflictResolution>;
+    /**
+     * Called when a conflict is detected (before auto-resolution).
+     */
+    onConflictDetected?: (conflict: SyncConflict) => void;
+    /**
+     * Called after a conflict is resolved.
+     */
+    onConflictResolved?: (conflict: SyncConflict, resolution: ConflictResolution) => void;
+    /**
+     * Called when auto-merge fails and manual intervention is needed.
+     */
+    onMergeFailed?: (conflict: SyncConflict, error: Error) => void;
+}
+/**
+ * Configuration for the conflict resolver.
+ */
+export interface ConflictResolverOptions {
+    /** Default resolution strategy */
+    defaultStrategy: ConflictStrategy;
+    /** Per-table strategy overrides */
+    tableStrategies?: Record<string, ConflictStrategy>;
+    /** Per-field merge functions for 'merge' strategy */
+    fieldMergers?: Record<string, FieldMerger>;
+    /** UI hooks for manual resolution */
+    hooks?: ConflictUIHooks;
+    /** Maximum time to wait for manual resolution (ms) */
+    manualResolutionTimeout?: number;
+    /** Auto-resolve conflicts older than this (ms) */
+    autoResolveAfter?: number;
+}
+/**
+ * Function to merge a single field.
+ */
+export type FieldMerger = (fieldName: string, localValue: unknown, remoteValue: unknown, localTimestamp: number, remoteTimestamp: number) => unknown;
+/**
+ * Built-in field mergers.
+ */
+export declare const FieldMergers: {
+    /**
+     * Use the most recent value based on timestamp.
+     */
+    lastWriteWins: FieldMerger;
+    /**
+     * For numeric fields, take the maximum value.
+     */
+    max: FieldMerger;
+    /**
+     * For numeric fields, sum the values.
+     */
+    sum: FieldMerger;
+    /**
+     * For arrays, union the values.
+     */
+    union: FieldMerger;
+    /**
+     * For strings, concatenate with separator.
+     */
+    concat: FieldMerger;
+};
+/**
+ * Conflict resolver for cross-platform sync.
+ *
+ * Detects conflicts using vector clock comparison and resolves
+ * them using configurable strategies or UI hooks.
+ *
+ * @example
+ * ```typescript
+ * const resolver = new ConflictResolver({
+ *   defaultStrategy: 'last-write-wins',
+ *   tableStrategies: {
+ *     notes: 'merge',
+ *     settings: 'local-wins',
+ *   },
+ *   hooks: {
+ *     onConflictNeedsResolution: async (conflict) => {
+ *       return showConflictDialog(conflict);
+ *     },
+ *   },
+ * });
+ *
+ * const resolution = await resolver.resolve(conflict);
+ * ```
+ */
+export declare class ConflictResolver {
+    private _options;
+    private _pendingConflicts;
+    private _resolvedConflicts;
+    constructor(options: ConflictResolverOptions);
+    /**
+     * Detect if there is a conflict between local and remote data.
+     */
+    detectConflict(tableName: string, recordId: string, localData: Record<string, unknown>, remoteData: Record<string, unknown>, localClock: VectorClockData, remoteClock: VectorClockData, localDeviceId: string, remoteDeviceId: string): SyncConflict | null;
+    /**
+     * Resolve a conflict using the configured strategy.
+     */
+    resolve(conflict: SyncConflict): Promise<ConflictResolution>;
+    /**
+     * Get pending conflicts.
+     */
+    getPendingConflicts(): SyncConflict[];
+    /**
+     * Get a specific pending conflict.
+     */
+    getConflict(conflictId: string): SyncConflict | undefined;
+    /**
+     * Manually resolve a conflict with a user decision.
+     */
+    resolveManually(conflictId: string, decision: ResolutionDecision, mergedData?: Record<string, unknown>): Promise<ConflictResolution>;
+    /**
+     * Auto-resolve old conflicts that have been pending too long.
+     */
+    autoResolveStale(): ConflictResolution[];
+    /**
+     * Get the resolution strategy for a table.
+     */
+    private _getStrategy;
+    /**
+     * Find fields that differ between local and remote data.
+     */
+    private _findConflictingFields;
+    /**
+     * Check if two values are equal (deep comparison for objects/arrays).
+     */
+    private _valuesEqual;
+    /**
+     * Resolve using last-write-wins strategy.
+     */
+    private _resolveLastWriteWins;
+    /**
+     * Resolve using local-wins strategy.
+     */
+    private _resolveLocalWins;
+    /**
+     * Resolve using remote-wins strategy.
+     */
+    private _resolveRemoteWins;
+    /**
+     * Resolve using field-level merge strategy.
+     */
+    private _resolveMerge;
+    /**
+     * Resolve using manual/UI strategy.
+     */
+    private _resolveManual;
+}
+/**
+ * Create a conflict resolver instance.
+ */
+export declare const createConflictResolver: (options: ConflictResolverOptions) => ConflictResolver;
+//# sourceMappingURL=conflictResolver.d.ts.map