@drakkar.software/starfish-client 1.3.2 → 1.4.0

package/dist/fetch.js

@@ -0,0 +1,156 @@
+/** Classify an error from a fetch response or network failure. */
+export function classifyError(err) {
+    if (err instanceof Response || (err && typeof err === "object" && "status" in err)) {
+        const status = err.status;
+        if (status === 401 || status === 403)
+            return "auth";
+        if (status === 409)
+            return "conflict";
+        if (status === 429)
+            return "rate-limited";
+        if (status >= 500)
+            return "server";
+        if (status >= 400)
+            return "client";
+    }
+    if (err instanceof Error && /failed to fetch|fetch failed|network|load failed|ECONNREFUSED|ENOTFOUND/i.test(err.message))
+        return "network";
+    return "unknown";
+}
+/**
+ * Wraps a fetch function with automatic retry for retriable errors
+ * (network failures, 429, 5xx). Respects Retry-After headers.
+ */
+export function createRetryFetch(options) {
+    const maxRetries = Math.max(0, options?.maxRetries ?? 3);
+    const initialDelay = options?.initialDelayMs ?? 500;
+    const maxDelay = options?.maxDelayMs ?? 10_000;
+    return async (input, init) => {
+        let attempt = 0;
+        while (true) {
+            try {
+                const res = await globalThis.fetch(input, init);
+                if (res.ok || attempt >= maxRetries)
+                    return res;
+                const category = classifyError(res);
+                if (category !== "rate-limited" && category !== "server")
+                    return res;
+                const retryAfter = res.headers.get("Retry-After");
+                let delay;
+                if (retryAfter) {
+                    const seconds = Number(retryAfter);
+                    if (!isNaN(seconds)) {
+                        delay = Math.min(seconds * 1000, maxDelay);
+                    }
+                    else {
+                        const date = Date.parse(retryAfter);
+                        delay = isNaN(date) ? initialDelay : Math.min(Math.max(date - Date.now(), 0), maxDelay);
+                    }
+                }
+                else {
+                    delay = Math.min(initialDelay * Math.pow(2, attempt), maxDelay);
+                }
+                await new Promise((r) => setTimeout(r, delay));
+                attempt++;
+            }
+            catch (err) {
+                if (attempt >= maxRetries)
+                    throw err;
+                const category = classifyError(err);
+                if (category !== "network")
+                    throw err;
+                const delay = Math.min(initialDelay * Math.pow(2, attempt), maxDelay);
+                await new Promise((r) => setTimeout(r, delay));
+                attempt++;
+            }
+        }
+    };
+}
+/** Circuit breaker that prevents requests when the backend is unavailable. */
+export class CircuitBreaker {
+    state = "closed";
+    failures = 0;
+    openedAt = 0;
+    threshold;
+    cooldownMs;
+    constructor(options) {
+        this.threshold = options?.threshold ?? 5;
+        this.cooldownMs = options?.cooldownMs ?? 30_000;
+    }
+    getState() {
+        this.maybeTransition();
+        return this.state;
+    }
+    isOpen() {
+        return this.getState() === "open";
+    }
+    recordSuccess() {
+        this.failures = 0;
+        this.state = "closed";
+    }
+    recordFailure() {
+        this.failures++;
+        if (this.state === "half-open" || this.failures >= this.threshold) {
+            this.state = "open";
+            this.openedAt = Date.now();
+        }
+    }
+    maybeTransition() {
+        if (this.state === "open" && Date.now() - this.openedAt >= this.cooldownMs) {
+            this.state = "half-open";
+        }
+    }
+}
+/**
+ * Wraps fetch to gzip-compress string request bodies using the CompressionStream API.
+ * Adds Content-Encoding: gzip header. Non-string bodies (ArrayBuffer, Blob, etc.)
+ * are passed through uncompressed. Requires CompressionStream (browsers, Node.js 18+, Deno).
+ */
+export function createCompressedFetch(inner) {
+    const baseFetch = inner ?? globalThis.fetch.bind(globalThis);
+    return async (input, init) => {
+        if (!init?.body || typeof CompressionStream === "undefined") {
+            return baseFetch(input, init);
+        }
+        const bodyText = typeof init.body === "string" ? init.body : null;
+        if (!bodyText)
+            return baseFetch(input, init);
+        const stream = new Blob([bodyText]).stream().pipeThrough(new CompressionStream("gzip"));
+        const compressed = await new Response(stream).arrayBuffer();
+        const normalized = Object.fromEntries(new Headers(init.headers).entries());
+        normalized["content-encoding"] = "gzip";
+        return baseFetch(input, {
+            ...init,
+            body: compressed,
+            headers: normalized,
+        });
+    };
+}
+/**
+ * Combines retry and circuit breaker into a single resilient fetch wrapper.
+ * Rejects immediately when the circuit is open.
+ */
+export function createResilientFetch(retryOptions, breakerOptions) {
+    const breaker = new CircuitBreaker(breakerOptions);
+    const retryFetch = createRetryFetch(retryOptions);
+    const resilientFetch = async (input, init) => {
+        if (breaker.isOpen()) {
+            throw new Error(`Circuit breaker is open (${breaker.getState()}, cooldown ${breakerOptions?.cooldownMs ?? 30_000}ms)`);
+        }
+        try {
+            const res = await retryFetch(input, init);
+            if (res.ok) {
+                breaker.recordSuccess();
+            }
+            else if (res.status >= 500) {
+                breaker.recordFailure();
+            }
+            return res;
+        }
+        catch (err) {
+            breaker.recordFailure();
+            throw err;
+        }
+    };
+    return { fetch: resilientFetch, breaker };
+}

package/dist/history.d.ts

@@ -0,0 +1,29 @@
+export interface Snapshot {
+    timestamp: number;
+    label: string;
+    data: string;
+}
+export interface SnapshotHistoryOptions {
+    /** Maximum number of snapshots to retain. Oldest are trimmed first. Default: 20. */
+    maxSnapshots?: number;
+    /** localStorage key for persistence. Pass to enable auto-save/load. */
+    storageKey?: string;
+}
+export declare class SnapshotHistory {
+    private snapshots;
+    private readonly maxSnapshots;
+    private readonly storageKey;
+    constructor(options?: SnapshotHistoryOptions);
+    /** Take a labeled snapshot of the given data. */
+    take(label: string, data: Record<string, unknown>): void;
+    /** Restore data from a snapshot at the given index. Returns undefined if index is invalid. */
+    restore(index: number): Record<string, unknown> | undefined;
+    /** List available snapshots (metadata only, no data payload). */
+    list(): Array<{
+        timestamp: number;
+        label: string;
+    }>;
+    /** Clear all snapshots. */
+    clear(): void;
+    private persist;
+}

package/dist/history.js

@@ -0,0 +1,53 @@
+export class SnapshotHistory {
+    snapshots = [];
+    maxSnapshots;
+    storageKey;
+    constructor(options) {
+        this.maxSnapshots = options?.maxSnapshots ?? 20;
+        this.storageKey = options?.storageKey;
+        if (this.storageKey) {
+            try {
+                const raw = localStorage.getItem(this.storageKey);
+                if (raw)
+                    this.snapshots = JSON.parse(raw);
+            }
+            catch { /* corrupted or unavailable — start fresh */ }
+        }
+    }
+    /** Take a labeled snapshot of the given data. */
+    take(label, data) {
+        this.snapshots.push({
+            timestamp: Date.now(),
+            label,
+            data: JSON.stringify(data),
+        });
+        if (this.snapshots.length > this.maxSnapshots) {
+            this.snapshots = this.snapshots.slice(-this.maxSnapshots);
+        }
+        this.persist();
+    }
+    /** Restore data from a snapshot at the given index. Returns undefined if index is invalid. */
+    restore(index) {
+        const snapshot = this.snapshots[index];
+        if (!snapshot)
+            return undefined;
+        return JSON.parse(snapshot.data);
+    }
+    /** List available snapshots (metadata only, no data payload). */
+    list() {
+        return this.snapshots.map(({ timestamp, label }) => ({ timestamp, label }));
+    }
+    /** Clear all snapshots. */
+    clear() {
+        this.snapshots = [];
+        this.persist();
+    }
+    persist() {
+        if (!this.storageKey)
+            return;
+        try {
+            localStorage.setItem(this.storageKey, JSON.stringify(this.snapshots));
+        }
+        catch { /* quota exceeded — skip silently */ }
+    }
+}

package/dist/index.d.ts

@@ -3,9 +3,23 @@ export type { CryptoProvider, Base64Provider, PlatformConfig } from "@drakkar.so
 export { stableStringify, computeHash } from "@drakkar.software/starfish-protocol";
 export type { PullResult, PushSuccess } from "@drakkar.software/starfish-protocol";
 export { StarfishClient } from "./client.js";
+export type { BlobPullResult, BlobPushResult } from "./client.js";
 export { SyncManager } from "./sync.js";
 export type { SyncManagerOptions } from "./sync.js";
 export { createEncryptor, ENCRYPTED_KEY } from "./crypto.js";
 export type { Encryptor } from "./crypto.js";
 export { ConflictError, StarfishHttpError, } from "./types.js";
 export type { StarfishClientOptions, AuthProvider, ConflictResolver, } from "./types.js";
+export { consoleSyncLogger, noopSyncLogger } from "./logger.js";
+export type { SyncLogger } from "./logger.js";
+export { createMigrator } from "./migrate.js";
+export type { MigrationFn, MigrationConfig } from "./migrate.js";
+export { ValidationError, createSchemaValidator } from "./validate.js";
+export type { Validator, ValidationResult } from "./validate.js";
+export { classifyError } from "./fetch.js";
+export type { ErrorCategory } from "./fetch.js";
+export { createUnionMerge, createSoftDeleteResolver, timestampWinner, pruneTombstones, } from "./resolvers.js";
+export { SnapshotHistory } from "./history.js";
+export type { Snapshot, SnapshotHistoryOptions } from "./history.js";
+export { startPolling, startAdaptivePolling } from "./polling.js";
+export type { PollableState, AdaptivePollingOptions, AdaptivePollingControls } from "./polling.js";

package/dist/index.js

@@ -4,3 +4,10 @@ export { StarfishClient } from "./client.js";
 export { SyncManager } from "./sync.js";
 export { createEncryptor, ENCRYPTED_KEY } from "./crypto.js";
 export { ConflictError, StarfishHttpError, } from "./types.js";
+export { consoleSyncLogger, noopSyncLogger } from "./logger.js";
+export { createMigrator } from "./migrate.js";
+export { ValidationError, createSchemaValidator } from "./validate.js";
+export { classifyError } from "./fetch.js";
+export { createUnionMerge, createSoftDeleteResolver, timestampWinner, pruneTombstones, } from "./resolvers.js";
+export { SnapshotHistory } from "./history.js";
+export { startPolling, startAdaptivePolling } from "./polling.js";

package/dist/logger.d.ts

@@ -0,0 +1,14 @@
+/** Structured logger for sync operations. */
+export interface SyncLogger {
+    pullStart(store: string): void;
+    pullSuccess(store: string, durationMs: number): void;
+    pullError(store: string, error: string): void;
+    pushStart(store: string): void;
+    pushSuccess(store: string, durationMs: number): void;
+    pushError(store: string, error: string): void;
+    conflict(store: string, attempt: number): void;
+}
+/** Console-based sync logger with structured output. */
+export declare const consoleSyncLogger: SyncLogger;
+/** Silent sync logger (no output). */
+export declare const noopSyncLogger: SyncLogger;

package/dist/logger.js

@@ -0,0 +1,20 @@
+/** Console-based sync logger with structured output. */
+export const consoleSyncLogger = {
+    pullStart: (s) => console.log(`[starfish:${s}] pull started`),
+    pullSuccess: (s, ms) => console.log(`[starfish:${s}] pull OK (${ms}ms)`),
+    pullError: (s, err) => console.error(`[starfish:${s}] pull failed: ${err}`),
+    pushStart: (s) => console.log(`[starfish:${s}] push started`),
+    pushSuccess: (s, ms) => console.log(`[starfish:${s}] push OK (${ms}ms)`),
+    pushError: (s, err) => console.error(`[starfish:${s}] push failed: ${err}`),
+    conflict: (s, n) => console.warn(`[starfish:${s}] conflict (attempt ${n})`),
+};
+/** Silent sync logger (no output). */
+export const noopSyncLogger = {
+    pullStart: () => { },
+    pullSuccess: () => { },
+    pullError: () => { },
+    pushStart: () => { },
+    pushSuccess: () => { },
+    pushError: () => { },
+    conflict: () => { },
+};

package/dist/migrate.d.ts

@@ -0,0 +1,16 @@
+/** A function that migrates data from one schema version to the next. */
+export type MigrationFn = (data: Record<string, unknown>) => Record<string, unknown>;
+export interface MigrationConfig {
+    /** The current schema version of the application. */
+    currentVersion: number;
+    /** Map of version number to the migration that upgrades FROM that version. */
+    migrations: Record<number, MigrationFn>;
+}
+/**
+ * Creates a migration runner that upgrades documents to the current schema version.
+ *
+ * Given a document with `_schemaVersion`, applies each migration in sequence
+ * until the document reaches `currentVersion`. Throws if the document version
+ * is ahead of the app (forward compatibility guard).
+ */
+export declare function createMigrator(config: MigrationConfig): (data: Record<string, unknown>) => Record<string, unknown>;

package/dist/migrate.js

@@ -0,0 +1,33 @@
+/**
+ * Creates a migration runner that upgrades documents to the current schema version.
+ *
+ * Given a document with `_schemaVersion`, applies each migration in sequence
+ * until the document reaches `currentVersion`. Throws if the document version
+ * is ahead of the app (forward compatibility guard).
+ */
+export function createMigrator(config) {
+    // Eagerly validate the migration chain
+    for (let v = 1; v < config.currentVersion; v++) {
+        if (!config.migrations[v]) {
+            throw new Error(`Missing migration for version ${v} -> ${v + 1}`);
+        }
+    }
+    return (data) => {
+        const version = typeof data._schemaVersion === "number" ? data._schemaVersion : 1;
+        if (version > config.currentVersion) {
+            throw new Error(`Document schema version ${version} is newer than app version ${config.currentVersion}. Update the app.`);
+        }
+        if (version === config.currentVersion)
+            return data;
+        let result = { ...data };
+        for (let v = version; v < config.currentVersion; v++) {
+            const fn = config.migrations[v];
+            if (!fn) {
+                throw new Error(`Missing migration for version ${v} -> ${v + 1}`);
+            }
+            result = fn(result);
+        }
+        result._schemaVersion = config.currentVersion;
+        return result;
+    };
+}

package/dist/polling.d.ts

@@ -0,0 +1,28 @@
+/** Minimal state needed by polling utilities. */
+export interface PollableState {
+    online: boolean;
+    syncing: boolean;
+}
+/**
+ * Start periodic pulling at a fixed interval.
+ * Skips pulls when offline or already syncing.
+ * Returns a cleanup function that stops polling.
+ */
+export declare function startPolling(pullFn: () => Promise<void>, getState: () => PollableState, intervalMs?: number): () => void;
+export interface AdaptivePollingOptions {
+    /** Override the base interval in ms. If set, skips network quality detection. */
+    intervalMs?: number;
+    /** Custom mapping from effectiveType to interval in ms. */
+    intervals?: Record<string, number>;
+}
+export interface AdaptivePollingControls {
+    pause: () => void;
+    resume: () => void;
+    stop: () => void;
+}
+/**
+ * Start polling with adaptive intervals based on network quality.
+ * Uses the Network Information API (`navigator.connection.effectiveType`) when available.
+ * Returns controls to pause, resume, or stop polling.
+ */
+export declare function startAdaptivePolling(pullFn: () => Promise<void>, getState: () => PollableState, options?: AdaptivePollingOptions): AdaptivePollingControls;

package/dist/polling.js

@@ -0,0 +1,52 @@
+const DEFAULT_INTERVALS = {
+    "slow-2g": 120_000,
+    "2g": 60_000,
+    "3g": 30_000,
+    "4g": 10_000,
+};
+const DEFAULT_FALLBACK_MS = 15_000;
+/**
+ * Start periodic pulling at a fixed interval.
+ * Skips pulls when offline or already syncing.
+ * Returns a cleanup function that stops polling.
+ */
+export function startPolling(pullFn, getState, intervalMs = 30_000) {
+    const timer = setInterval(() => {
+        const { online, syncing } = getState();
+        if (online && !syncing)
+            pullFn();
+    }, intervalMs);
+    return () => clearInterval(timer);
+}
+/**
+ * Start polling with adaptive intervals based on network quality.
+ * Uses the Network Information API (`navigator.connection.effectiveType`) when available.
+ * Returns controls to pause, resume, or stop polling.
+ */
+export function startAdaptivePolling(pullFn, getState, options) {
+    let intervalMs;
+    if (options?.intervalMs != null) {
+        intervalMs = options.intervalMs;
+    }
+    else {
+        const intervals = options?.intervals ?? DEFAULT_INTERVALS;
+        let effectiveType;
+        if (typeof navigator !== "undefined" && "connection" in navigator) {
+            effectiveType = navigator.connection.effectiveType;
+        }
+        intervalMs = (effectiveType != null ? intervals[effectiveType] : undefined) ?? DEFAULT_FALLBACK_MS;
+    }
+    let paused = false;
+    const timer = setInterval(() => {
+        if (paused)
+            return;
+        const { online, syncing } = getState();
+        if (online && !syncing)
+            pullFn();
+    }, intervalMs);
+    return {
+        pause: () => { paused = true; },
+        resume: () => { paused = false; },
+        stop: () => clearInterval(timer),
+    };
+}

package/dist/resolvers.d.ts

@@ -0,0 +1,50 @@
+import type { ConflictResolver } from "./types.js";
+/**
+ * Creates a conflict resolver that merges arrays by ID with per-item
+ * timestamp comparison, and uses document-level timestamp for scalars.
+ *
+ * For arrays: builds a union of both sets keyed by `idKey`. When both
+ * sides have the same item, the one with the newer `timestampKey` wins.
+ * For scalars: the document with the newer `documentTimestampKey` wins.
+ *
+ * @example
+ * ```ts
+ * const merge = createUnionMerge()
+ * const sync = new SyncManager({ ..., onConflict: merge })
+ * ```
+ */
+export declare function createUnionMerge(options?: {
+    /** Key used to identify items in arrays (default: "id"). */
+    idKey?: string;
+    /** Key used for per-item timestamp comparison (default: "updatedAt"). */
+    timestampKey?: string;
+    /** Key used for document-level timestamp comparison (default: "timestamp"). */
+    documentTimestampKey?: string;
+}): ConflictResolver;
+/**
+ * Creates a conflict resolver that handles soft-deleted items (tombstones).
+ * Extends union merge with tombstone awareness: if an item exists on one side
+ * with a `deletedAtKey` set, that deletion is respected even if the other side
+ * still has the item alive — as long as the deletion timestamp is newer.
+ */
+export declare function createSoftDeleteResolver(options?: {
+    idKey?: string;
+    timestampKey?: string;
+    documentTimestampKey?: string;
+    /** Key marking an item as deleted (default: "_deletedAt"). */
+    deletedAtKey?: string;
+}): ConflictResolver;
+/**
+ * Simple resolver: the document with the newer timestamp wins entirely.
+ * No per-field or per-item merging.
+ */
+export declare function timestampWinner(timestampKey?: string): ConflictResolver;
+/**
+ * Remove expired tombstones from an array of items.
+ * Items with a `deletedAtKey` older than `ttlMs` are pruned.
+ *
+ * @param items - Array of items, some with a deletedAt timestamp
+ * @param ttlMs - Time-to-live in ms for tombstones (default: 30 days)
+ * @param deletedAtKey - Key marking deletion timestamp (default: "_deletedAt")
+ */
+export declare function pruneTombstones<T extends Record<string, unknown>>(items: T[], ttlMs?: number, deletedAtKey?: string): T[];

package/dist/resolvers.js

@@ -0,0 +1,162 @@
+/** Compare two timestamp values. Handles both numeric (epoch) and string (ISO-8601) timestamps. */
+function compareTimestamps(a, b) {
+    if (typeof a === "number" && typeof b === "number")
+        return a >= b;
+    return String(a ?? "") >= String(b ?? "");
+}
+/**
+ * Creates a conflict resolver that merges arrays by ID with per-item
+ * timestamp comparison, and uses document-level timestamp for scalars.
+ *
+ * For arrays: builds a union of both sets keyed by `idKey`. When both
+ * sides have the same item, the one with the newer `timestampKey` wins.
+ * For scalars: the document with the newer `documentTimestampKey` wins.
+ *
+ * @example
+ * ```ts
+ * const merge = createUnionMerge()
+ * const sync = new SyncManager({ ..., onConflict: merge })
+ * ```
+ */
+export function createUnionMerge(options) {
+    const idKey = options?.idKey ?? "id";
+    const tsKey = options?.timestampKey ?? "updatedAt";
+    const docTsKey = options?.documentTimestampKey ?? "timestamp";
+    return (local, remote) => {
+        const result = {};
+        const localNewer = compareTimestamps(local[docTsKey], remote[docTsKey]);
+        const allKeys = new Set([...Object.keys(local), ...Object.keys(remote)]);
+        for (const key of allKeys) {
+            const lv = local[key];
+            const rv = remote[key];
+            // Both sides have arrays — attempt ID-based union
+            if (Array.isArray(lv) && Array.isArray(rv)) {
+                const map = new Map();
+                // Seed with remote items
+                for (const item of rv) {
+                    if (item && typeof item === "object" && idKey in item) {
+                        map.set(item[idKey], item);
+                    }
+                    else {
+                        map.set(Symbol(), item);
+                    }
+                }
+                // Overlay local items (per-item timestamp wins)
+                for (const item of lv) {
+                    if (item && typeof item === "object" && idKey in item) {
+                        const localItem = item;
+                        const id = localItem[idKey];
+                        const remoteItem = map.get(id);
+                        if (!remoteItem) {
+                            map.set(id, localItem);
+                        }
+                        else {
+                            if (compareTimestamps(localItem[tsKey], remoteItem[tsKey])) {
+                                map.set(id, localItem);
+                            }
+                        }
+                    }
+                    else {
+                        map.set(Symbol(), item);
+                    }
+                }
+                result[key] = [...map.values()];
+            }
+            else if (lv !== undefined && rv !== undefined) {
+                // Scalar: document-level timestamp wins
+                result[key] = localNewer ? lv : rv;
+            }
+            else {
+                // Only one side has the key
+                result[key] = lv ?? rv;
+            }
+        }
+        return result;
+    };
+}
+/**
+ * Creates a conflict resolver that handles soft-deleted items (tombstones).
+ * Extends union merge with tombstone awareness: if an item exists on one side
+ * with a `deletedAtKey` set, that deletion is respected even if the other side
+ * still has the item alive — as long as the deletion timestamp is newer.
+ */
+export function createSoftDeleteResolver(options) {
+    const idKey = options?.idKey ?? "id";
+    const tsKey = options?.timestampKey ?? "updatedAt";
+    const deletedAtKey = options?.deletedAtKey ?? "_deletedAt";
+    const baseMerge = createUnionMerge(options);
+    return (local, remote) => {
+        const merged = baseMerge(local, remote);
+        // Build a tombstone map from both sides: id → deletedAt timestamp
+        const tombstones = new Map();
+        for (const source of [local, remote]) {
+            for (const key of Object.keys(source)) {
+                const arr = source[key];
+                if (!Array.isArray(arr))
+                    continue;
+                for (const item of arr) {
+                    if (item && typeof item === "object" && idKey in item && deletedAtKey in item) {
+                        const rec = item;
+                        const id = rec[idKey];
+                        const deletedAt = rec[deletedAtKey];
+                        if (typeof deletedAt === "number") {
+                            const existing = tombstones.get(id) ?? 0;
+                            if (deletedAt > existing)
+                                tombstones.set(id, deletedAt);
+                        }
+                    }
+                }
+            }
+        }
+        // For merged arrays, ensure tombstoned items stay deleted
+        // (don't resurrect an item if its tombstone is newer than its updatedAt)
+        for (const key of Object.keys(merged)) {
+            const value = merged[key];
+            if (!Array.isArray(value))
+                continue;
+            merged[key] = value.filter((item) => {
+                if (!item || typeof item !== "object" || !(idKey in item))
+                    return true;
+                const rec = item;
+                const id = rec[idKey];
+                const deletedAt = tombstones.get(id);
+                if (deletedAt == null)
+                    return true;
+                // Keep the item if it has a deletedAt (it's the tombstone itself)
+                if (rec[deletedAtKey] != null)
+                    return true;
+                // Filter out alive items that have a newer tombstone
+                return compareTimestamps(rec[tsKey], deletedAt) && rec[tsKey] !== deletedAt;
+            });
+        }
+        return merged;
+    };
+}
+/**
+ * Simple resolver: the document with the newer timestamp wins entirely.
+ * No per-field or per-item merging.
+ */
+export function timestampWinner(timestampKey = "timestamp") {
+    return (local, remote) => {
+        return compareTimestamps(local[timestampKey], remote[timestampKey])
+            ? local
+            : remote;
+    };
+}
+/**
+ * Remove expired tombstones from an array of items.
+ * Items with a `deletedAtKey` older than `ttlMs` are pruned.
+ *
+ * @param items - Array of items, some with a deletedAt timestamp
+ * @param ttlMs - Time-to-live in ms for tombstones (default: 30 days)
+ * @param deletedAtKey - Key marking deletion timestamp (default: "_deletedAt")
+ */
+export function pruneTombstones(items, ttlMs = 30 * 24 * 60 * 60 * 1000, deletedAtKey = "_deletedAt") {
+    const cutoff = Date.now() - ttlMs;
+    return items.filter((item) => {
+        const deletedAt = item[deletedAtKey];
+        if (deletedAt == null)
+            return true;
+        return typeof deletedAt === "number" && deletedAt > cutoff;
+    });
+}