local-lite 0.0.12 → 0.0.14

package/dist/backups/encryption.d.ts

@@ -0,0 +1,18 @@
+import type { BackupDatabase, BackupStorage } from './index.js';
+export interface EncryptedBackupOptions {
+    passphrase: string;
+    fileName?: string;
+    iterations?: number;
+}
+export interface RestoreEncryptedBackupOptions {
+    passphrase: string;
+}
+export declare function isEncryptedBackup(data: Uint8Array): boolean;
+export declare function encryptBackupData(plainData: Uint8Array, passphrase: string, options?: {
+    iterations?: number;
+}): Promise<Uint8Array>;
+export declare function decryptBackupData(encryptedData: Uint8Array, passphrase: string, options?: {
+    iterations?: number;
+}): Promise<Uint8Array>;
+export declare function createEncryptedDatabaseBackup(database: BackupDatabase, storage: BackupStorage, options: EncryptedBackupOptions): Promise<string>;
+export declare function restoreEncryptedDatabaseBackup(database: BackupDatabase, storage: BackupStorage, fileName: string, options: RestoreEncryptedBackupOptions): Promise<void>;

package/dist/backups/encryption.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEncryptedBackup = isEncryptedBackup;
+exports.encryptBackupData = encryptBackupData;
+exports.decryptBackupData = decryptBackupData;
+exports.createEncryptedDatabaseBackup = createEncryptedDatabaseBackup;
+exports.restoreEncryptedDatabaseBackup = restoreEncryptedDatabaseBackup;
+const pbkdf2_js_1 = require("@noble/hashes/pbkdf2.js");
+const sha2_js_1 = require("@noble/hashes/sha2.js");
+const utils_js_1 = require("@noble/hashes/utils.js");
+const MAGIC_HEADER = new Uint8Array([0x4c, 0x4c, 0x45, 0x4e, 0x43, 0x31]); // "LLENC1"
+const SALT_LENGTH = 16;
+const IV_LENGTH = 12;
+const DEFAULT_ITERATIONS = 50000;
+function getRandomBytes(length) {
+    const crypto = globalThis.crypto;
+    if (!crypto?.getRandomValues) {
+        throw new Error('Secure random generation is unavailable for backup encryption.');
+    }
+    return crypto.getRandomValues(new Uint8Array(length));
+}
+const ITERATIONS_LENGTH = 4;
+function isEncryptedBackup(data) {
+    if (data.length < MAGIC_HEADER.length + ITERATIONS_LENGTH + SALT_LENGTH + IV_LENGTH + 16) {
+        return false;
+    }
+    for (let i = 0; i < MAGIC_HEADER.length; i++) {
+        if (data[i] !== MAGIC_HEADER[i])
+            return false;
+    }
+    return true;
+}
+async function encryptBackupData(plainData, passphrase, options = {}) {
+    if (!passphrase || !passphrase.trim()) {
+        throw new Error('A non-empty passphrase is required for backup encryption.');
+    }
+    const iterations = options.iterations ?? DEFAULT_ITERATIONS;
+    const salt = getRandomBytes(SALT_LENGTH);
+    const iv = getRandomBytes(IV_LENGTH);
+    // Derive 256-bit AES key using PBKDF2 with SHA-256
+    const keyBytes = (0, pbkdf2_js_1.pbkdf2)(sha2_js_1.sha256, (0, utils_js_1.utf8ToBytes)(passphrase), salt, {
+        c: iterations,
+        dkLen: 32,
+    });
+    const crypto = globalThis.crypto;
+    if (!crypto?.subtle) {
+        throw new Error('WebCrypto subtle is unavailable for AES-GCM encryption.');
+    }
+    const cryptoKey = await crypto.subtle.importKey('raw', keyBytes, 'AES-GCM', false, ['encrypt']);
+    const encryptedBuffer = await crypto.subtle.encrypt({ name: 'AES-GCM', iv: iv }, cryptoKey, plainData);
+    const ciphertext = new Uint8Array(encryptedBuffer);
+    // Payload format: [MAGIC(6)][ITERATIONS(4)][SALT(16)][IV(12)][CIPHERTEXT+TAG]
+    const headerSize = MAGIC_HEADER.length + ITERATIONS_LENGTH + SALT_LENGTH + IV_LENGTH;
+    const result = new Uint8Array(headerSize + ciphertext.length);
+    result.set(MAGIC_HEADER, 0);
+    const view = new DataView(result.buffer, result.byteOffset, result.byteLength);
+    view.setUint32(MAGIC_HEADER.length, iterations, false); // big-endian
+    result.set(salt, MAGIC_HEADER.length + ITERATIONS_LENGTH);
+    result.set(iv, MAGIC_HEADER.length + ITERATIONS_LENGTH + SALT_LENGTH);
+    result.set(ciphertext, headerSize);
+    return result;
+}
+async function decryptBackupData(encryptedData, passphrase, options = {}) {
+    if (!passphrase || !passphrase.trim()) {
+        throw new Error('A non-empty passphrase is required for backup decryption.');
+    }
+    if (!isEncryptedBackup(encryptedData)) {
+        throw new Error('Invalid backup file format: missing LLENC1 encryption header.');
+    }
+    const view = new DataView(encryptedData.buffer, encryptedData.byteOffset, encryptedData.byteLength);
+    const storedIterations = view.getUint32(MAGIC_HEADER.length, false);
+    const iterations = options.iterations ?? (storedIterations > 0 ? storedIterations : DEFAULT_ITERATIONS);
+    const saltOffset = MAGIC_HEADER.length + ITERATIONS_LENGTH;
+    const ivOffset = saltOffset + SALT_LENGTH;
+    const ciphertextOffset = ivOffset + IV_LENGTH;
+    const salt = encryptedData.slice(saltOffset, ivOffset);
+    const iv = encryptedData.slice(ivOffset, ciphertextOffset);
+    const ciphertext = encryptedData.slice(ciphertextOffset);
+    const keyBytes = (0, pbkdf2_js_1.pbkdf2)(sha2_js_1.sha256, (0, utils_js_1.utf8ToBytes)(passphrase), salt, {
+        c: iterations,
+        dkLen: 32,
+    });
+    const crypto = globalThis.crypto;
+    if (!crypto?.subtle) {
+        throw new Error('WebCrypto subtle is unavailable for AES-GCM decryption.');
+    }
+    const cryptoKey = await crypto.subtle.importKey('raw', keyBytes, 'AES-GCM', false, ['decrypt']);
+    try {
+        const decryptedBuffer = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: iv }, cryptoKey, ciphertext);
+        return new Uint8Array(decryptedBuffer);
+    }
+    catch {
+        throw new Error('Backup decryption failed: Incorrect passphrase or corrupted database backup.');
+    }
+}
+async function createEncryptedDatabaseBackup(database, storage, options) {
+    const fileName = options.fileName ??
+        `local-lite-enc-${new Date().toISOString().replace(/[:.]/g, '-')}.enc.db`;
+    if (!fileName || /[\\/]/.test(fileName)) {
+        throw new Error('Backup file name must be a single file name.');
+    }
+    const plainBytes = await database.exportDatabase();
+    if (plainBytes.length === 0) {
+        throw new Error('Cannot create a backup from an empty database.');
+    }
+    const encryptedBytes = await encryptBackupData(plainBytes, options.passphrase, {
+        iterations: options.iterations,
+    });
+    await storage.save(fileName, encryptedBytes);
+    return fileName;
+}
+async function restoreEncryptedDatabaseBackup(database, storage, fileName, options) {
+    if (!fileName || /[\\/]/.test(fileName)) {
+        throw new Error('Backup file name must be a single file name.');
+    }
+    const rawBytes = await storage.read(fileName);
+    if (rawBytes.length === 0) {
+        throw new Error('Cannot restore an empty database backup.');
+    }
+    const decryptedBytes = await decryptBackupData(rawBytes, options.passphrase);
+    await database.importDatabase(decryptedBytes);
+}

package/dist/backups/index.d.ts

@@ -1,4 +1,6 @@
 export { type BackupAccessTokenProvider, type CloudBackupFile, type GoogleDriveAuthorizationRequest, type GoogleDriveAuthorizationResponse, type GoogleDriveBackupClientOptions, type GoogleDriveKeyValueStorage, type GoogleDriveTokenStore, type GoogleDriveTokens, GoogleDriveBackupClient, GoogleDriveBackupStorage, createGoogleDriveTokenStore, } from './cloud-storage.js';
+export { MICROSOFT_GRAPH_DRIVE, OneDriveBackupStorage, OneDriveBackupClient, } from './onedrive.js';
+export { type EncryptedBackupOptions, type RestoreEncryptedBackupOptions, isEncryptedBackup, encryptBackupData, decryptBackupData, createEncryptedDatabaseBackup, restoreEncryptedDatabaseBackup, } from './encryption.js';
 export interface BackupDatabase {
     exportDatabase(): Promise<Uint8Array>;
     importDatabase(data: Uint8Array): Promise<void>;

package/dist/backups/index.js

@@ -1,12 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createGoogleDriveTokenStore = exports.GoogleDriveBackupStorage = exports.GoogleDriveBackupClient = void 0;
+exports.restoreEncryptedDatabaseBackup = exports.createEncryptedDatabaseBackup = exports.decryptBackupData = exports.encryptBackupData = exports.isEncryptedBackup = exports.OneDriveBackupClient = exports.OneDriveBackupStorage = exports.MICROSOFT_GRAPH_DRIVE = exports.createGoogleDriveTokenStore = exports.GoogleDriveBackupStorage = exports.GoogleDriveBackupClient = void 0;
 exports.createDatabaseBackup = createDatabaseBackup;
 exports.restoreDatabaseBackup = restoreDatabaseBackup;
 var cloud_storage_js_1 = require("./cloud-storage.js");
 Object.defineProperty(exports, "GoogleDriveBackupClient", { enumerable: true, get: function () { return cloud_storage_js_1.GoogleDriveBackupClient; } });
 Object.defineProperty(exports, "GoogleDriveBackupStorage", { enumerable: true, get: function () { return cloud_storage_js_1.GoogleDriveBackupStorage; } });
 Object.defineProperty(exports, "createGoogleDriveTokenStore", { enumerable: true, get: function () { return cloud_storage_js_1.createGoogleDriveTokenStore; } });
+var onedrive_js_1 = require("./onedrive.js");
+Object.defineProperty(exports, "MICROSOFT_GRAPH_DRIVE", { enumerable: true, get: function () { return onedrive_js_1.MICROSOFT_GRAPH_DRIVE; } });
+Object.defineProperty(exports, "OneDriveBackupStorage", { enumerable: true, get: function () { return onedrive_js_1.OneDriveBackupStorage; } });
+Object.defineProperty(exports, "OneDriveBackupClient", { enumerable: true, get: function () { return onedrive_js_1.OneDriveBackupClient; } });
+var encryption_js_1 = require("./encryption.js");
+Object.defineProperty(exports, "isEncryptedBackup", { enumerable: true, get: function () { return encryption_js_1.isEncryptedBackup; } });
+Object.defineProperty(exports, "encryptBackupData", { enumerable: true, get: function () { return encryption_js_1.encryptBackupData; } });
+Object.defineProperty(exports, "decryptBackupData", { enumerable: true, get: function () { return encryption_js_1.decryptBackupData; } });
+Object.defineProperty(exports, "createEncryptedDatabaseBackup", { enumerable: true, get: function () { return encryption_js_1.createEncryptedDatabaseBackup; } });
+Object.defineProperty(exports, "restoreEncryptedDatabaseBackup", { enumerable: true, get: function () { return encryption_js_1.restoreEncryptedDatabaseBackup; } });
 function validateFileName(fileName) {
     if (!fileName || /[\\/]/.test(fileName)) {
         throw new Error('Backup file name must be a single file name.');

package/dist/backups/onedrive.d.ts

@@ -0,0 +1,22 @@
+import type { BackupAccessTokenProvider, BackupStorage, CloudBackupFile } from './index.js';
+import { type MicrosoftAuthClientOptions } from '../auth/microsoft.js';
+export declare const MICROSOFT_GRAPH_DRIVE = "https://graph.microsoft.com/v1.0/me/drive";
+export declare class OneDriveBackupStorage implements BackupStorage {
+    private readonly getAccessToken;
+    private readonly fetcher;
+    constructor(getAccessToken: BackupAccessTokenProvider, fetcher?: typeof fetch);
+    save(fileName: string, data: Uint8Array): Promise<void>;
+    read(fileIdOrName: string): Promise<Uint8Array>;
+    list(): Promise<CloudBackupFile[]>;
+}
+export declare class OneDriveBackupClient implements BackupStorage {
+    private readonly storage;
+    private readonly authClient;
+    constructor(options: MicrosoftAuthClientOptions);
+    connect(): Promise<boolean>;
+    disconnect(): Promise<void>;
+    isConnected(): Promise<boolean>;
+    save(fileName: string, data: Uint8Array): Promise<void>;
+    read(fileId: string): Promise<Uint8Array>;
+    list(): Promise<CloudBackupFile[]>;
+}

package/dist/backups/onedrive.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OneDriveBackupClient = exports.OneDriveBackupStorage = exports.MICROSOFT_GRAPH_DRIVE = void 0;
+const microsoft_js_1 = require("../auth/microsoft.js");
+exports.MICROSOFT_GRAPH_DRIVE = 'https://graph.microsoft.com/v1.0/me/drive';
+const BACKUP_FOLDER = 'backups';
+class OneDriveBackupStorage {
+    getAccessToken;
+    fetcher;
+    constructor(getAccessToken, fetcher = fetch) {
+        this.getAccessToken = getAccessToken;
+        this.fetcher = fetcher;
+    }
+    async save(fileName, data) {
+        const token = await this.getAccessToken();
+        const encodedName = encodeURIComponent(fileName);
+        const url = `${exports.MICROSOFT_GRAPH_DRIVE}/special/approot:/${BACKUP_FOLDER}/${encodedName}:/content`;
+        const response = await this.fetcher(url, {
+            method: 'PUT',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/octet-stream',
+            },
+            body: data.slice().buffer,
+        });
+        if (!response.ok) {
+            let detail = '';
+            try {
+                const body = (await response.json());
+                detail = body?.error?.message || response.statusText;
+            }
+            catch {
+                detail = response.statusText;
+            }
+            throw new Error(`OneDrive upload failed (${response.status}): ${detail}`);
+        }
+    }
+    async read(fileIdOrName) {
+        const token = await this.getAccessToken();
+        let url = `${exports.MICROSOFT_GRAPH_DRIVE}/items/${encodeURIComponent(fileIdOrName)}/content`;
+        // Support reading directly by filename inside approot:/backups/
+        if (fileIdOrName.endsWith('.db') && !fileIdOrName.startsWith('item-')) {
+            url = `${exports.MICROSOFT_GRAPH_DRIVE}/special/approot:/${BACKUP_FOLDER}/${encodeURIComponent(fileIdOrName)}:/content`;
+        }
+        const response = await this.fetcher(url, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!response.ok) {
+            throw new Error(`OneDrive download failed (${response.status}): ${response.statusText}`);
+        }
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    async list() {
+        const token = await this.getAccessToken();
+        const url = `${exports.MICROSOFT_GRAPH_DRIVE}/special/approot:/${BACKUP_FOLDER}:/children?$select=id,name,size,lastModifiedDateTime`;
+        const response = await this.fetcher(url, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (response.status === 404) {
+            return []; // Folder does not exist yet
+        }
+        if (!response.ok) {
+            throw new Error(`OneDrive list failed (${response.status}): ${response.statusText}`);
+        }
+        const result = (await response.json());
+        return (result.value ?? [])
+            .filter(item => item.name.endsWith('.db'))
+            .map(item => ({
+            id: item.id,
+            name: item.name,
+            size: item.size,
+            modifiedAt: item.lastModifiedDateTime,
+        }));
+    }
+}
+exports.OneDriveBackupStorage = OneDriveBackupStorage;
+class OneDriveBackupClient {
+    storage;
+    authClient;
+    constructor(options) {
+        const scopes = options.scopes ?? [
+            'openid',
+            'profile',
+            'email',
+            'User.Read',
+            'Files.ReadWrite.AppFolder',
+        ];
+        this.authClient = new microsoft_js_1.MicrosoftAuthClient({
+            ...options,
+            scopes,
+        });
+        this.storage = new OneDriveBackupStorage(() => this.authClient.getValidAccessToken(), options.fetch ?? fetch);
+    }
+    async connect() {
+        const user = await this.authClient.signIn();
+        return user !== null;
+    }
+    async disconnect() {
+        await this.authClient.signOut();
+    }
+    async isConnected() {
+        return this.authClient.isSignedIn();
+    }
+    save(fileName, data) {
+        return this.storage.save(fileName, data);
+    }
+    read(fileId) {
+        return this.storage.read(fileId);
+    }
+    list() {
+        return this.storage.list();
+    }
+}
+exports.OneDriveBackupClient = OneDriveBackupClient;

package/dist/core/client.d.ts

@@ -2,6 +2,7 @@ import { LocalDBAdapter, LocalTransaction } from '../adapters/local/index.js';
 import { RemoteDBAdapter } from '../adapters/remote/index.js';
 import { EventEmitter } from '../reactive/event-emitter.js';
 import { SyncWorker } from './sync-worker.js';
+import { DatabaseMaintenance } from './maintenance.js';
 import { SchemaManager } from './schema-manager.js';
 import { BatchMutation, ConflictResolver, ConflictStrategy, MutateOptions, NetworkStatusProvider, OutboxRecord, OutboxStatus, QueryOptions, RetryConfig, SyncMetrics, SyncOp, TableChangeEvent, WhereFilter } from './types.js';
 import { SyncLogger, CustomLogger, LogLevel } from '../utils/logger.js';
@@ -78,6 +79,7 @@ export declare class LocalFirstClient {
     autoHydrateJSON: boolean;
     /** Local column stamped on INSERT/UPDATE writes, or null when disabled. */
     touchColumn: string | null;
+    readonly maintenance: DatabaseMaintenance;
     private primaryKey;
     private migrations;
     private autoStart;

package/dist/core/client.js

@@ -6,6 +6,7 @@ const sync_worker_js_1 = require("./sync-worker.js");
 const table_manager_js_1 = require("./table-manager.js");
 const outbox_store_js_1 = require("./outbox-store.js");
 const meta_store_js_1 = require("./meta-store.js");
+const maintenance_js_1 = require("./maintenance.js");
 const schema_manager_js_1 = require("./schema-manager.js");
 const uuid_js_1 = require("../utils/uuid.js");
 const sql_js_1 = require("../utils/sql.js");
@@ -156,6 +157,7 @@ class LocalFirstClient {
     autoHydrateJSON;
     /** Local column stamped on INSERT/UPDATE writes, or null when disabled. */
     touchColumn;
+    maintenance;
     primaryKey;
     migrations;
     autoStart;
@@ -180,6 +182,7 @@ class LocalFirstClient {
                     ? touch
                     : this.remote?.updatedAtColumn || 'updated_at';
         this.schemaManager = new schema_manager_js_1.SchemaManager();
+        this.maintenance = new maintenance_js_1.DatabaseMaintenance(this.db, () => this.tables);
         const workerOptions = {
             network: config.network,
             conflictResolver: config.conflictResolver,

package/dist/core/conflict.d.ts

@@ -1,5 +1,12 @@
-import { ConflictResolver, ConflictStrategy } from './types.js';
+import { ConflictContext, ConflictResolution, ConflictResolver, ConflictStrategy, FieldMergeResolverOptions } from './types.js';
+export type { ConflictContext, ConflictResolution, ConflictResolver, ConflictStrategy, FieldMergeResolverOptions, };
 export declare const lastWriteWinsResolver: ConflictResolver;
 export declare const serverWinsResolver: ConflictResolver;
 export declare const clientWinsResolver: ConflictResolver;
+/**
+ * Creates a smart 3-way field-level conflict resolver.
+ * Merges disjoint fields from both local and remote offline mutations,
+ * and resolves overlapping field changes using custom rules, timestamps, or winner strategies.
+ */
+export declare function createFieldMergeResolver(options?: FieldMergeResolverOptions): ConflictResolver;
 export declare function getConflictResolver(strategyOrResolver?: ConflictStrategy | ConflictResolver): ConflictResolver;

package/dist/core/conflict.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.clientWinsResolver = exports.serverWinsResolver = exports.lastWriteWinsResolver = void 0;
+exports.createFieldMergeResolver = createFieldMergeResolver;
 exports.getConflictResolver = getConflictResolver;
 const lastWriteWinsResolver = (context) => {
     const remoteTime = context.remoteChange.timestamp ?? 0;
@@ -22,6 +23,78 @@ const clientWinsResolver = (context) => {
     return 'apply-remote';
 };
 exports.clientWinsResolver = clientWinsResolver;
+/**
+ * Creates a smart 3-way field-level conflict resolver.
+ * Merges disjoint fields from both local and remote offline mutations,
+ * and resolves overlapping field changes using custom rules, timestamps, or winner strategies.
+ */
+function createFieldMergeResolver(options = {}) {
+    const defaultWinner = options.defaultWinner ?? 'newer';
+    const deleteHandling = options.deleteHandling ?? 'delete-wins';
+    const fieldRules = options.fieldRules ?? {};
+    return (context) => {
+        const isRemoteDelete = context.remoteChange.operation === 'DELETE';
+        const isLocalDelete = context.localOutboxRecord?.operation === 'DELETE';
+        if (isRemoteDelete && isLocalDelete) {
+            return 'apply-remote';
+        }
+        if (isRemoteDelete && !isLocalDelete) {
+            return deleteHandling === 'update-wins' ? 'keep-local' : 'apply-remote';
+        }
+        if (isLocalDelete && !isRemoteDelete) {
+            return deleteHandling === 'update-wins' ? 'apply-remote' : 'keep-local';
+        }
+        // Both are non-delete operations (INSERT / UPDATE)
+        const baseRow = context.localRow ?? {};
+        const remotePayload = context.remoteChange.payload ?? {};
+        const localPayload = context.localOutboxRecord?.payload ?? {};
+        const merged = { ...baseRow, ...remotePayload };
+        const tableRules = fieldRules[context.tableName] ?? {};
+        const wildcardRules = fieldRules['*'] ?? {};
+        const localTime = context.localOutboxRecord?.timestamp ?? 0;
+        const remoteTime = context.remoteChange.timestamp ?? 0;
+        for (const key of Object.keys(localPayload)) {
+            if (!(key in remotePayload)) {
+                // Field only changed locally: preserve local modification
+                merged[key] = localPayload[key];
+                continue;
+            }
+            // Field was modified by BOTH local and remote: resolve conflict
+            const rule = tableRules[key] ?? wildcardRules[key];
+            const localVal = localPayload[key];
+            const remoteVal = remotePayload[key];
+            if (typeof rule === 'function') {
+                merged[key] = rule(localVal, remoteVal, context);
+            }
+            else if (rule === 'max') {
+                merged[key] = localVal >= remoteVal ? localVal : remoteVal;
+            }
+            else if (rule === 'min') {
+                merged[key] = localVal <= remoteVal ? localVal : remoteVal;
+            }
+            else if (rule === 'local') {
+                merged[key] = localVal;
+            }
+            else if (rule === 'remote') {
+                merged[key] = remoteVal;
+            }
+            else {
+                const winner = rule === 'newer' ? 'newer' : defaultWinner;
+                if (winner === 'local') {
+                    merged[key] = localVal;
+                }
+                else if (winner === 'remote') {
+                    merged[key] = remoteVal;
+                }
+                else {
+                    // 'newer': compare timestamp
+                    merged[key] = localTime >= remoteTime ? localVal : remoteVal;
+                }
+            }
+        }
+        return { mergePayload: merged };
+    };
+}
 function getConflictResolver(strategyOrResolver) {
     if (typeof strategyOrResolver === 'function') {
         return strategyOrResolver;
@@ -31,6 +104,8 @@ function getConflictResolver(strategyOrResolver) {
             return exports.serverWinsResolver;
         case 'client-wins':
             return exports.clientWinsResolver;
+        case 'field-merge':
+            return createFieldMergeResolver();
         case 'last-write-wins':
         default:
             return exports.lastWriteWinsResolver;

package/dist/core/maintenance.d.ts

@@ -0,0 +1,66 @@
+import { LocalDBAdapter } from '../adapters/local/index.js';
+import { OutboxStatus } from './types.js';
+export interface PruneOutboxOptions {
+    /**
+     * Only delete outbox records older than this many days.
+     * e.g. retentionDays: 7 deletes records older than 7 days.
+     */
+    retentionDays?: number;
+    /**
+     * Explicit cutoff timestamp in milliseconds. Records older than this timestamp are eligible.
+     */
+    beforeTimestamp?: number;
+    /**
+     * Maximum number of outbox entries to retain. If the outbox exceeds this count,
+     * the oldest matching records are pruned.
+     */
+    maxEntries?: number;
+    /**
+     * Target statuses to prune. Defaults to ['COMPLETED', 'FAILED'].
+     * PENDING records are protected from pruning by default unless explicitly included.
+     */
+    statuses?: OutboxStatus[];
+}
+export interface OutboxStorageStats {
+    total: number;
+    pending: number;
+    processing: number;
+    completed: number;
+    failed: number;
+}
+export interface StorageStats {
+    /** Row count per table */
+    tables: Record<string, number>;
+    /** Breakdown of sync outbox items */
+    outbox: OutboxStorageStats;
+    /** SQLite allocation page size in bytes */
+    pageSize: number;
+    /** Total allocated SQLite database pages */
+    pageCount: number;
+    /** Total calculated database size on disk in bytes */
+    databaseSizeBytes: number;
+}
+export type CheckpointMode = 'PASSIVE' | 'FULL' | 'RESTART' | 'TRUNCATE';
+export declare class DatabaseMaintenance {
+    private readonly db;
+    private readonly getKnownTables;
+    constructor(db: LocalDBAdapter, getKnownTables?: () => string[]);
+    /**
+     * Reclaims unused space, defragments the database file, and optimizes internal B-trees.
+     */
+    vacuum(): Promise<void>;
+    /**
+     * Checkpoints WAL (Write-Ahead Log) pages into the main database file.
+     * 'TRUNCATE' (default) copies all WAL frames to the database file and resets WAL size to zero.
+     */
+    checkpoint(mode?: CheckpointMode): Promise<void>;
+    /**
+     * Prunes old or completed mutations from the sync_outbox table to keep database footprint small.
+     * Returns the count of deleted outbox records.
+     */
+    pruneOutbox(options?: PruneOutboxOptions): Promise<number>;
+    /**
+     * Gathers storage metrics: table row counts, outbox status distribution, and database size.
+     */
+    getStorageStats(): Promise<StorageStats>;
+}