@anfenn/dync 1.0.0

package/src/core/pullOperations.ts

@@ -0,0 +1,212 @@
+import { createLocalId } from '../helpers';
+import type { Logger } from '../logger';
+import type { ApiFunctions, BatchSync, ConflictResolutionStrategy, FieldConflict, SyncedRecord } from '../types';
+import { SyncAction } from '../types';
+import type { StorageTable } from '../storage/types';
+import { DYNC_STATE_TABLE, type StateHelpers } from './StateManager';
+import type { WithTransaction } from './types';
+
+export interface PullContext {
+    logger: Logger;
+    state: StateHelpers;
+    table: <T>(name: string) => StorageTable<T>;
+    withTransaction: WithTransaction;
+    conflictResolutionStrategy: ConflictResolutionStrategy;
+}
+
+export interface PullAllContext extends PullContext {
+    syncApis: Record<string, ApiFunctions>;
+}
+
+export interface PullAllBatchContext extends PullContext {
+    batchSync: BatchSync;
+}
+
+export async function pullAll(ctx: PullAllContext): Promise<{ error?: Error; changedTables: string[] }> {
+    let firstSyncError: Error | undefined;
+    const changedTables: string[] = [];
+    for (const [stateKey, api] of Object.entries(ctx.syncApis)) {
+        try {
+            const lastPulled = ctx.state.getState().lastPulled[stateKey];
+            const since = lastPulled ? new Date(lastPulled) : new Date(0);
+
+            ctx.logger.debug(`[dync] pull:start stateKey=${stateKey} since=${since.toISOString()}`);
+
+            const serverData = (await api.list(since)) as SyncedRecord[];
+            const changed = await processPullData(stateKey, serverData, since, ctx);
+            if (changed) changedTables.push(stateKey);
+        } catch (err) {
+            firstSyncError = firstSyncError ?? (err as Error);
+            ctx.logger.error(`[dync] pull:error stateKey=${stateKey}`, err);
+        }
+    }
+    return { error: firstSyncError, changedTables };
+}
+
+async function handleRemoteItemUpdate(table: StorageTable<any>, stateKey: string, localItem: any, remote: any, ctx: PullContext): Promise<void> {
+    const pendingChange = ctx.state.getState().pendingChanges.find((p) => p.stateKey === stateKey && p.localId === localItem._localId);
+    const conflictStrategy = ctx.conflictResolutionStrategy;
+
+    if (pendingChange) {
+        ctx.logger.debug(`[dync] pull:conflict-strategy:${conflictStrategy} stateKey=${stateKey} id=${remote.id}`);
+
+        switch (conflictStrategy) {
+            case 'local-wins':
+                break;
+
+            case 'remote-wins': {
+                const merged = { ...remote, _localId: localItem._localId };
+                await table.raw.update(localItem._localId, merged);
+                await ctx.state.removePendingChange(localItem._localId, stateKey);
+                break;
+            }
+
+            case 'try-shallow-merge': {
+                const changes = pendingChange.changes || {};
+                const before = pendingChange.before || {};
+                const fields: FieldConflict[] = Object.entries(changes)
+                    .filter(([k, localValue]) => k in before && k in remote && before[k] !== remote[k] && localValue !== remote[k])
+                    .map(([key, localValue]) => ({ key, localValue, remoteValue: remote[key] }));
+
+                if (fields.length > 0) {
+                    ctx.logger.warn(`[dync] pull:${conflictStrategy}:conflicts-found`, JSON.stringify(fields, null, 4));
+                    // Store or update conflict with CURRENT field values (prevents stale conflicts)
+                    await ctx.state.setState((syncState) => ({
+                        ...syncState,
+                        conflicts: {
+                            ...(syncState.conflicts || {}),
+                            [localItem._localId]: { stateKey, fields },
+                        },
+                    }));
+                } else {
+                    const localChangedKeys = Object.keys(changes);
+                    const preservedLocal: any = { _localId: localItem._localId };
+                    for (const k of localChangedKeys) {
+                        if (k in localItem) preservedLocal[k] = localItem[k];
+                    }
+
+                    const merged = { ...remote, ...preservedLocal };
+                    await table.raw.update(localItem._localId, merged);
+
+                    // Clear conflict for the current pending change - it no longer conflicts
+                    await ctx.state.setState((syncState) => {
+                        const ss = { ...syncState };
+                        delete ss.conflicts?.[localItem._localId];
+                        return ss;
+                    });
+                }
+                break;
+            }
+        }
+    } else {
+        const merged = { ...localItem, ...remote };
+        await table.raw.update(localItem._localId, merged);
+        ctx.logger.debug(`[dync] pull:merge-remote stateKey=${stateKey} id=${remote.id}`);
+    }
+}
+
+// ============================================================================
+// Batch Mode Pull Operations
+// ============================================================================
+
+export async function pullAllBatch(ctx: PullAllBatchContext): Promise<{ error?: Error; changedTables: string[] }> {
+    let firstSyncError: Error | undefined;
+    const changedTables: string[] = [];
+
+    try {
+        // Build since map for all synced tables
+        const sinceMap: Record<string, Date> = {};
+        for (const tableName of ctx.batchSync.syncTables) {
+            const lastPulled = ctx.state.getState().lastPulled[tableName];
+            sinceMap[tableName] = lastPulled ? new Date(lastPulled) : new Date(0);
+        }
+
+        ctx.logger.debug(`[dync] pull:batch:start tables=${[...ctx.batchSync.syncTables].join(',')}`, sinceMap);
+
+        // Single batch pull request
+        const serverDataByTable = await ctx.batchSync.pull(sinceMap);
+
+        // Process each table's data
+        for (const [stateKey, serverData] of Object.entries(serverDataByTable)) {
+            if (!ctx.batchSync.syncTables.includes(stateKey)) {
+                ctx.logger.warn(`[dync] pull:batch:unknown-table stateKey=${stateKey}`);
+                continue;
+            }
+
+            try {
+                const changed = await processPullData(stateKey, serverData as SyncedRecord[], sinceMap[stateKey]!, ctx);
+                if (changed) changedTables.push(stateKey);
+            } catch (err) {
+                firstSyncError = firstSyncError ?? (err as Error);
+                ctx.logger.error(`[dync] pull:batch:error stateKey=${stateKey}`, err);
+            }
+        }
+    } catch (err) {
+        firstSyncError = err as Error;
+        ctx.logger.error(`[dync] pull:batch:error`, err);
+    }
+
+    return { error: firstSyncError, changedTables };
+}
+
+async function processPullData(stateKey: string, serverData: SyncedRecord[], since: Date, ctx: PullContext): Promise<boolean> {
+    if (!serverData?.length) return false;
+
+    ctx.logger.debug(`[dync] pull:process stateKey=${stateKey} count=${serverData.length}`);
+
+    let newest = since;
+    let hasChanges = false;
+
+    await ctx.withTransaction('rw', [stateKey, DYNC_STATE_TABLE], async (tables) => {
+        const txTable = tables[stateKey]!;
+        const pendingRemovalById = new Set(
+            ctx.state
+                .getState()
+                .pendingChanges.filter((p) => p.stateKey === stateKey && p.action === SyncAction.Remove)
+                .map((p) => p.id),
+        );
+
+        for (const remote of serverData) {
+            const remoteUpdated = new Date(remote.updated_at);
+            if (remoteUpdated > newest) newest = remoteUpdated;
+
+            if (pendingRemovalById.has(remote.id)) {
+                ctx.logger.debug(`[dync] pull:skip-pending-remove stateKey=${stateKey} id=${remote.id}`);
+                continue;
+            }
+
+            const localItem = await txTable.where('id').equals(remote.id).first();
+
+            if (remote.deleted) {
+                if (localItem) {
+                    await txTable.raw.delete(localItem._localId);
+                    ctx.logger.debug(`[dync] pull:remove stateKey=${stateKey} id=${remote.id}`);
+                    hasChanges = true;
+                }
+                continue;
+            }
+
+            delete remote.deleted;
+
+            if (localItem) {
+                await handleRemoteItemUpdate(txTable, stateKey, localItem, remote, ctx);
+                hasChanges = true;
+            } else {
+                const newLocalItem = { ...remote, _localId: createLocalId() };
+                await txTable.raw.add(newLocalItem);
+                ctx.logger.debug(`[dync] pull:add stateKey=${stateKey} id=${remote.id}`);
+                hasChanges = true;
+            }
+        }
+
+        await ctx.state.setState((syncState) => ({
+            ...syncState,
+            lastPulled: {
+                ...syncState.lastPulled,
+                [stateKey]: newest.toISOString(),
+            },
+        }));
+    });
+
+    return hasChanges;
+}

package/src/core/pushOperations.ts

@@ -0,0 +1,290 @@
+import { createLocalId, orderFor } from '../helpers';
+import type { Logger } from '../logger';
+import type { ApiFunctions, BatchPushPayload, BatchPushResult, BatchSync, PendingChange, SyncOptions } from '../types';
+import { SyncAction } from '../types';
+import type { StorageTable } from '../storage/types';
+import { DYNC_STATE_TABLE, type StateHelpers } from './StateManager';
+import type { WithTransaction } from './types';
+
+export interface PushContext {
+    logger: Logger;
+    state: StateHelpers;
+    table: <T>(name: string) => StorageTable<T>;
+    withTransaction: WithTransaction;
+    syncOptions: SyncOptions;
+}
+
+export interface PushAllContext extends PushContext {
+    syncApis: Record<string, ApiFunctions>;
+}
+
+export interface PushAllBatchContext extends PushContext {
+    batchSync: BatchSync;
+}
+
+async function handleRemoveSuccess(change: PendingChange, ctx: PushContext): Promise<void> {
+    const { stateKey, localId, id } = change;
+    ctx.logger.debug(`[dync] push:remove:success stateKey=${stateKey} localId=${localId} id=${id}`);
+    await ctx.state.removePendingChange(localId, stateKey);
+}
+
+async function handleUpdateSuccess(change: PendingChange, ctx: PushContext): Promise<void> {
+    const { stateKey, localId, version, changes } = change;
+    ctx.logger.debug(`[dync] push:update:success stateKey=${stateKey} localId=${localId} id=${change.id}`);
+    if (ctx.state.samePendingVersion(stateKey, localId, version)) {
+        await ctx.state.removePendingChange(localId, stateKey);
+    } else {
+        await ctx.state.setPendingChangeBefore(stateKey, localId, changes);
+    }
+}
+
+async function handleCreateSuccess(change: PendingChange, serverResult: { id: unknown; updated_at?: string }, ctx: PushContext): Promise<void> {
+    const { stateKey, localId, version, changes, id } = change;
+    ctx.logger.debug(`[dync] push:create:success stateKey=${stateKey} localId=${localId} id=${id ?? serverResult.id}`);
+
+    await ctx.withTransaction('rw', [stateKey, DYNC_STATE_TABLE], async (tables) => {
+        const txTable = tables[stateKey]!;
+        const wasChanged = (await txTable.raw.update(localId, serverResult)) ?? 0;
+
+        if (wasChanged && ctx.state.samePendingVersion(stateKey, localId, version)) {
+            await ctx.state.removePendingChange(localId, stateKey);
+        } else {
+            const nextAction = wasChanged ? SyncAction.Update : SyncAction.Remove;
+            await ctx.state.updatePendingChange(stateKey, localId, nextAction, serverResult.id);
+            if (nextAction === SyncAction.Remove) return;
+        }
+    });
+
+    const finalItem = { ...changes, ...serverResult, _localId: localId };
+    ctx.syncOptions.onAfterRemoteAdd?.(stateKey, finalItem);
+}
+
+export async function pushAll(ctx: PushAllContext): Promise<Error | undefined> {
+    let firstSyncError: Error | undefined;
+    const changesSnapshot = [...ctx.state.getState().pendingChanges].sort((a, b) => orderFor(a.action) - orderFor(b.action));
+
+    for (const change of changesSnapshot) {
+        try {
+            await pushOne(change, ctx);
+        } catch (err) {
+            firstSyncError = firstSyncError ?? (err as Error);
+            ctx.logger.error(`[dync] push:error change=${JSON.stringify(change)}`, err);
+        }
+    }
+    return firstSyncError;
+}
+
+async function pushOne(change: PendingChange, ctx: PushAllContext): Promise<void> {
+    const api = ctx.syncApis[change.stateKey];
+    if (!api) return;
+
+    ctx.logger.debug(`[dync] push:attempt action=${change.action} stateKey=${change.stateKey} localId=${change.localId}`);
+
+    const { action, stateKey, localId, id, changes, after } = change;
+
+    switch (action) {
+        case SyncAction.Remove:
+            if (!id) {
+                ctx.logger.warn(`[dync] push:remove:no-id stateKey=${stateKey} localId=${localId}`);
+                await ctx.state.removePendingChange(localId, stateKey);
+                return;
+            }
+            await api.remove(id);
+            await handleRemoveSuccess(change, ctx);
+            break;
+
+        case SyncAction.Update: {
+            if (ctx.state.hasConflicts(localId)) {
+                ctx.logger.warn(`[dync] push:update:skipping-with-conflicts stateKey=${stateKey} localId=${localId} id=${id}`);
+                return;
+            }
+
+            const exists = await api.update(id, changes, after);
+            if (exists) {
+                await handleUpdateSuccess(change, ctx);
+            } else {
+                await handleMissingRemoteRecord(change, ctx);
+            }
+            break;
+        }
+
+        case SyncAction.Create: {
+            const result = await api.add(changes);
+            if (result) {
+                await handleCreateSuccess(change, result, ctx);
+            } else {
+                ctx.logger.warn(`[dync] push:create:no-result stateKey=${stateKey} localId=${localId} id=${id}`);
+                if (ctx.state.samePendingVersion(stateKey, localId, change.version)) {
+                    await ctx.state.removePendingChange(localId, stateKey);
+                }
+            }
+            break;
+        }
+    }
+}
+
+async function handleMissingRemoteRecord(change: PendingChange, ctx: PushContext): Promise<void> {
+    const { stateKey, localId } = change;
+    const strategy = ctx.syncOptions.missingRemoteRecordDuringUpdateStrategy!;
+
+    let localItem: any;
+
+    await ctx.withTransaction('rw', [stateKey, DYNC_STATE_TABLE], async (tables) => {
+        const txTable = tables[stateKey]!;
+        localItem = await txTable.get(localId);
+
+        if (!localItem) {
+            ctx.logger.warn(`[dync] push:missing-remote:no-local-item stateKey=${stateKey} localId=${localId}`);
+            await ctx.state.removePendingChange(localId, stateKey);
+            return;
+        }
+
+        switch (strategy) {
+            case 'delete-local-record':
+                await txTable.raw.delete(localId);
+                ctx.logger.debug(`[dync] push:missing-remote:${strategy} stateKey=${stateKey} id=${localItem.id}`);
+                break;
+
+            case 'insert-remote-record': {
+                const newItem = {
+                    ...localItem,
+                    _localId: createLocalId(),
+                    updated_at: new Date().toISOString(),
+                };
+
+                await txTable.raw.add(newItem);
+                await txTable.raw.delete(localId);
+
+                await ctx.state.addPendingChange({
+                    action: SyncAction.Create,
+                    stateKey,
+                    localId: newItem._localId,
+                    changes: newItem,
+                    before: null,
+                });
+
+                ctx.logger.debug(`[dync] push:missing-remote:${strategy} stateKey=${stateKey} id=${newItem.id}`);
+                break;
+            }
+
+            case 'ignore':
+                ctx.logger.debug(`[dync] push:missing-remote:${strategy} stateKey=${stateKey} id=${localItem.id}`);
+                break;
+
+            default:
+                ctx.logger.error(`[dync] push:missing-remote:unknown-strategy stateKey=${stateKey} id=${localItem.id} strategy=${strategy}`);
+                break;
+        }
+
+        await ctx.state.removePendingChange(localId, stateKey);
+    });
+
+    ctx.syncOptions.onAfterMissingRemoteRecordDuringUpdate?.(strategy, localItem);
+}
+
+// ============================================================================
+// Batch Mode Push Operations
+// ============================================================================
+
+export async function pushAllBatch(ctx: PushAllBatchContext): Promise<Error | undefined> {
+    let firstSyncError: Error | undefined;
+
+    try {
+        const changesSnapshot = [...ctx.state.getState().pendingChanges]
+            .filter((change) => ctx.batchSync.syncTables.includes(change.stateKey))
+            .sort((a, b) => orderFor(a.action) - orderFor(b.action));
+
+        if (changesSnapshot.length === 0) {
+            ctx.logger.debug('[dync] push:batch:no-changes');
+            return undefined;
+        }
+
+        // Filter out changes with conflicts
+        const changesToPush = changesSnapshot.filter((change) => {
+            if (change.action === SyncAction.Update && ctx.state.hasConflicts(change.localId)) {
+                ctx.logger.warn(`[dync] push:batch:skipping-with-conflicts stateKey=${change.stateKey} localId=${change.localId}`);
+                return false;
+            }
+            return true;
+        });
+
+        if (changesToPush.length === 0) {
+            ctx.logger.debug('[dync] push:batch:all-skipped');
+            return undefined;
+        }
+
+        // Build batch payload
+        const payloads: BatchPushPayload[] = changesToPush.map((change) => ({
+            table: change.stateKey,
+            action: change.action === SyncAction.Create ? 'add' : change.action === SyncAction.Update ? 'update' : 'remove',
+            localId: change.localId,
+            id: change.id,
+            data: change.action === SyncAction.Remove ? undefined : change.changes,
+        }));
+
+        ctx.logger.debug(`[dync] push:batch:start count=${payloads.length}`);
+
+        // Single batch push request
+        const results = await ctx.batchSync.push(payloads);
+
+        // Create a map of results by localId for easy lookup
+        const resultMap = new Map<string, BatchPushResult>();
+        for (const result of results) {
+            resultMap.set(result.localId, result);
+        }
+
+        // Process each result
+        for (const change of changesToPush) {
+            const result = resultMap.get(change.localId);
+            if (!result) {
+                ctx.logger.warn(`[dync] push:batch:missing-result localId=${change.localId}`);
+                continue;
+            }
+
+            try {
+                await processBatchPushResult(change, result, ctx);
+            } catch (err) {
+                firstSyncError = firstSyncError ?? (err as Error);
+                ctx.logger.error(`[dync] push:batch:error localId=${change.localId}`, err);
+            }
+        }
+    } catch (err) {
+        firstSyncError = err as Error;
+        ctx.logger.error('[dync] push:batch:error', err);
+    }
+
+    return firstSyncError;
+}
+
+async function processBatchPushResult(change: PendingChange, result: BatchPushResult, ctx: PushAllBatchContext): Promise<void> {
+    const { action, stateKey, localId } = change;
+
+    if (!result.success) {
+        if (action === SyncAction.Update) {
+            // Update failed - might be missing remote record
+            await handleMissingRemoteRecord(change, ctx);
+        } else {
+            ctx.logger.warn(`[dync] push:batch:failed stateKey=${stateKey} localId=${localId} error=${result.error}`);
+        }
+        return;
+    }
+
+    switch (action) {
+        case SyncAction.Remove:
+            handleRemoveSuccess(change, ctx);
+            break;
+
+        case SyncAction.Update:
+            handleUpdateSuccess(change, ctx);
+            break;
+
+        case SyncAction.Create: {
+            const serverResult: { id: unknown; updated_at?: string } = { id: result.id };
+            if (result.updated_at) {
+                serverResult.updated_at = result.updated_at;
+            }
+            await handleCreateSuccess(change, serverResult, ctx);
+            break;
+        }
+    }
+}