@absolutejs/sync 1.7.9 → 1.8.1

package/README.md

@@ -217,6 +217,30 @@ await orders.mutate({
 });
 ```
 
+TanStack DB can own the client-side collection graph while Absolute Sync handles
+the live transport:
+
+```ts
+import { createCollection } from '@tanstack/db';
+import { createSyncTanStackCollectionOptions } from '@absolutejs/sync/tanstack-db';
+
+type Order = { id: string; total: number; status: string };
+
+const orders = createCollection(
+	createSyncTanStackCollectionOptions<Order>({
+		id: 'orders',
+		url: 'ws://localhost:3000/sync/ws',
+		collection: 'orders',
+		getKey: (order) => order.id,
+		mutations: {
+			insert: 'createOrder',
+			update: 'updateOrder',
+			delete: 'deleteOrder'
+		}
+	})
+);
+```
+
 - **Incremental vs refetch.** A single-table filtered collection is matched
   incrementally (only the changed rows move). Joins/aggregations and filters the
   matcher can't evaluate fall back to a correct re-hydrate. `createAggregate`

package/dist/adapters/tanstack-db/index.d.ts

@@ -0,0 +1,40 @@
+import type { CollectionConfig, PendingMutation } from '@tanstack/db';
+import { type CollectionCache, type MutationStorage, type SyncCollection } from '../../client/syncCollection';
+import type { RowKey } from '../../engine/types';
+export type TanStackRowKey = Extract<RowKey, string | number>;
+export type TanStackMutationCall = {
+    name: string;
+    args?: unknown;
+};
+export type TanStackMutationMapper<T extends object, TOperation extends 'insert' | 'update' | 'delete'> = string | ((mutation: PendingMutation<T, TOperation>) => TanStackMutationCall | undefined);
+export type SyncTanStackMutations<T extends object> = {
+    insert?: TanStackMutationMapper<T, 'insert'>;
+    update?: TanStackMutationMapper<T, 'update'>;
+    delete?: TanStackMutationMapper<T, 'delete'>;
+};
+export type SyncTanStackCollectionOptions<T extends object, TKey extends TanStackRowKey = TanStackRowKey> = Omit<CollectionConfig<T, TKey>, 'sync' | 'getKey' | 'onInsert' | 'onUpdate' | 'onDelete'> & {
+    /** WebSocket URL of the Absolute Sync endpoint. */
+    url: string;
+    /** Registered Absolute Sync collection name. */
+    collection: string;
+    /** Query params forwarded to the server collection hydrate/match/authorize hooks. */
+    params?: unknown;
+    /** Row identity shared by TanStack DB and Absolute Sync. */
+    getKey: (row: T) => TKey;
+    webSocketImpl?: typeof WebSocket;
+    reconnectMs?: number;
+    maxReconnectMs?: number;
+    storage?: MutationStorage;
+    cache?: CollectionCache<T>;
+    onError?: (error: unknown) => void;
+    /**
+     * Optional mapping from TanStack mutations to registered Absolute Sync
+     * mutation names. TanStack already applies optimistic writes, so forwarded
+     * sync mutations intentionally do not add another optimistic overlay.
+     */
+    mutations?: SyncTanStackMutations<T>;
+    /** Optional prebuilt Absolute Sync collection, useful when sharing lifecycle externally. */
+    syncCollection?: SyncCollection<T>;
+};
+export declare const createSyncTanStackCollectionOptions: <T extends object, TKey extends TanStackRowKey = TanStackRowKey>(options: SyncTanStackCollectionOptions<T, TKey>) => CollectionConfig<T, TKey>;
+export { createSyncTanStackCollectionOptions as syncTanStackCollectionOptions };

package/dist/adapters/tanstack-db/index.js

@@ -0,0 +1,523 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __name = (target, name) => {
+  Object.defineProperty(target, "name", {
+    value: name,
+    enumerable: false,
+    configurable: true
+  });
+  return target;
+};
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __defNormalProp = (obj, key, value) => (key in obj) ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateIn = (member, obj) => Object(obj) !== obj ? __typeError('Cannot use the "in" operator on this value') : member.has(obj);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+var __decoratorStart = (base) => [, , , __create(base?.[__knownSymbol("metadata")] ?? null)];
+var __decoratorStrings = ["class", "method", "getter", "setter", "accessor", "field", "value", "get", "set"];
+var __expectFn = (fn) => fn !== undefined && typeof fn !== "function" ? __typeError("Function expected") : fn;
+var __decoratorContext = (kind, name, done, metadata, fns) => ({
+  kind: __decoratorStrings[kind],
+  name,
+  metadata,
+  addInitializer: (fn) => done._ ? __typeError("Already initialized") : fns.push(__expectFn(fn || null))
+});
+var __decoratorMetadata = (array, target) => __defNormalProp(target, __knownSymbol("metadata"), array[3]);
+var __runInitializers = (array, flags, self, value) => {
+  for (var i = 0, fns = array[flags >> 1], n = fns && fns.length;i < n; i++)
+    flags & 1 ? fns[i].call(self) : value = fns[i].call(self, value);
+  return value;
+};
+var __decorateElement = (array, flags, name, decorators, target, extra) => {
+  var fn, it, done, ctx, access, k = flags & 7, s = !!(flags & 8), p = !!(flags & 16);
+  var j = k > 3 ? array.length + 1 : k ? s ? 1 : 2 : 0, key = __decoratorStrings[k + 5];
+  var initializers = k > 3 && (array[j - 1] = []), extraInitializers = array[j] || (array[j] = []);
+  var desc = k && (!p && !s && (target = target.prototype), k < 5 && (k > 3 || !p) && __getOwnPropDesc(k < 4 ? target : {
+    get [name]() {
+      return __privateGet(this, extra);
+    },
+    set [name](x) {
+      __privateSet(this, extra, x);
+    }
+  }, name));
+  k ? p && k < 4 && __name(extra, (k > 2 ? "set " : k > 1 ? "get " : "") + name) : __name(target, name);
+  for (var i = decorators.length - 1;i >= 0; i--) {
+    ctx = __decoratorContext(k, name, done = {}, array[3], extraInitializers);
+    if (k) {
+      ctx.static = s, ctx.private = p, access = ctx.access = { has: p ? (x) => __privateIn(target, x) : (x) => (name in x) };
+      if (k ^ 3)
+        access.get = p ? (x) => (k ^ 1 ? __privateGet : __privateMethod)(x, target, k ^ 4 ? extra : desc.get) : (x) => x[name];
+      if (k > 2)
+        access.set = p ? (x, y) => __privateSet(x, target, y, k ^ 4 ? extra : desc.set) : (x, y) => x[name] = y;
+    }
+    it = (0, decorators[i])(k ? k < 4 ? p ? extra : desc[key] : k > 4 ? undefined : { get: desc.get, set: desc.set } : target, ctx);
+    done._ = 1;
+    if (k ^ 4 || it === undefined)
+      __expectFn(it) && (k > 4 ? initializers.unshift(it) : k ? p ? extra = it : desc[key] = it : target = it);
+    else if (typeof it !== "object" || it === null)
+      __typeError("Object expected");
+    else
+      __expectFn(fn = it.get) && (desc.get = fn), __expectFn(fn = it.set) && (desc.set = fn), __expectFn(fn = it.init) && initializers.unshift(fn);
+  }
+  return k || __decoratorMetadata(array, target), desc && __defProp(target, name, desc), p ? k ^ 4 ? extra : desc : target;
+};
+
+// src/client/syncCollection.ts
+var localStorageMutationStorage = (key) => ({
+  load: () => {
+    const raw = globalThis.localStorage?.getItem(key);
+    return raw ? JSON.parse(raw) : [];
+  },
+  save: (records) => {
+    globalThis.localStorage?.setItem(key, JSON.stringify(records));
+  }
+});
+var localStorageCollectionCache = (key) => ({
+  load: () => {
+    const raw = globalThis.localStorage?.getItem(key);
+    return raw ? JSON.parse(raw) : undefined;
+  },
+  save: (snapshot) => {
+    globalThis.localStorage?.setItem(key, JSON.stringify(snapshot));
+  },
+  clear: () => {
+    globalThis.localStorage?.removeItem(key);
+  }
+});
+var openIndexedDb = (databaseName, storeName) => new Promise((resolve, reject) => {
+  const request = globalThis.indexedDB.open(databaseName, 1);
+  request.onupgradeneeded = () => {
+    request.result.createObjectStore(storeName);
+  };
+  request.onsuccess = () => resolve(request.result);
+  request.onerror = () => reject(request.error);
+});
+var indexedDbCollectionCache = ({
+  key,
+  databaseName = "absolutejs-sync",
+  storeName = "collections"
+}) => {
+  let handle;
+  const database = () => {
+    handle ??= openIndexedDb(databaseName, storeName);
+    return handle;
+  };
+  const withStore = async (mode, run) => {
+    if (globalThis.indexedDB === undefined) {
+      return;
+    }
+    const db = await database();
+    return new Promise((resolve, reject) => {
+      const request = run(db.transaction(storeName, mode).objectStore(storeName));
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  };
+  return {
+    load: () => withStore("readonly", (store) => store.get(key)),
+    save: async (snapshot) => {
+      await withStore("readwrite", (store) => store.put(snapshot, key));
+    },
+    clear: async () => {
+      await withStore("readwrite", (store) => store.delete(key));
+    }
+  };
+};
+var SUBSCRIPTION_ID = "s";
+var createSyncCollection = (options) => {
+  const key = options.key ?? ((row) => row.id);
+  const reconnectMs = options.reconnectMs ?? 500;
+  const maxReconnectMs = options.maxReconnectMs ?? 1e4;
+  const Impl = options.webSocketImpl ?? globalThis.WebSocket;
+  if (!Impl) {
+    throw new Error("createSyncCollection requires WebSocket. Run in a browser or pass webSocketImpl.");
+  }
+  const confirmed = new Map;
+  const pending = [];
+  let mutationSeq = 0;
+  let state = {
+    data: [],
+    status: "connecting",
+    error: undefined
+  };
+  const listeners = new Set;
+  const setState = (patch) => {
+    state = { ...state, ...patch };
+    for (const listener of listeners) {
+      listener(state);
+    }
+  };
+  const recompute = (patch = {}) => {
+    const working = new Map(confirmed);
+    const draft = {
+      set: (row) => working.set(key(row), row),
+      delete: (rowKey) => working.delete(rowKey)
+    };
+    for (const mutation of pending) {
+      mutation.optimistic?.(draft);
+    }
+    setState({ ...patch, data: [...working.values()] });
+  };
+  let socket;
+  let connected = false;
+  let closed = false;
+  let attempt = 0;
+  let reconnectTimer;
+  let appliedVersion = 0;
+  const persist = () => {
+    options.storage?.save(pending.map((mutation) => ({
+      mutationId: mutation.mutationId,
+      name: mutation.name,
+      args: mutation.args
+    })));
+  };
+  let cacheScheduled = false;
+  const persistCache = () => {
+    if (options.cache === undefined || cacheScheduled) {
+      return;
+    }
+    cacheScheduled = true;
+    queueMicrotask(() => {
+      cacheScheduled = false;
+      options.cache?.save({
+        rows: [...confirmed.values()],
+        version: appliedVersion
+      });
+    });
+  };
+  const settlePending = (mutationId) => {
+    const index = pending.findIndex((mutation2) => mutation2.mutationId === mutationId);
+    if (index === -1) {
+      return;
+    }
+    const [mutation] = pending.splice(index, 1);
+    persist();
+    return mutation;
+  };
+  const applyFrame = (frame) => {
+    if (frame.type === "snapshot") {
+      confirmed.clear();
+      for (const row of frame.rows) {
+        confirmed.set(key(row), row);
+      }
+      if (frame.version !== undefined) {
+        appliedVersion = frame.version;
+      }
+      persistCache();
+      recompute({ status: "ready", error: undefined });
+    } else if (frame.type === "diff") {
+      for (const row of frame.removed) {
+        confirmed.delete(key(row));
+      }
+      for (const row of frame.added) {
+        confirmed.set(key(row), row);
+      }
+      for (const row of frame.changed) {
+        confirmed.set(key(row), row);
+      }
+      if (frame.version !== undefined) {
+        appliedVersion = Math.max(appliedVersion, frame.version);
+      }
+      persistCache();
+      recompute({ status: "ready", error: undefined });
+    } else if (frame.type === "error") {
+      setState({ error: frame.message });
+      options.onError?.(frame.message);
+    } else if (frame.type === "ack") {
+      const mutation = settlePending(frame.mutationId);
+      if (mutation !== undefined) {
+        recompute();
+        mutation.resolve(frame.result);
+      }
+    } else if (frame.type === "reject") {
+      const mutation = settlePending(frame.mutationId);
+      if (mutation !== undefined) {
+        recompute();
+        mutation.reject(new Error(String(frame.message)));
+      }
+    }
+  };
+  const sendMutate = (mutation) => {
+    if (connected) {
+      socket?.send(JSON.stringify({
+        type: "mutate",
+        mutationId: mutation.mutationId,
+        name: mutation.name,
+        args: mutation.args
+      }));
+    }
+  };
+  const connect = () => {
+    if (closed) {
+      return;
+    }
+    setState({ status: "connecting" });
+    const ws = new Impl(options.url);
+    socket = ws;
+    ws.onopen = () => {
+      attempt = 0;
+      connected = true;
+      ws.send(JSON.stringify({
+        type: "subscribe",
+        id: SUBSCRIPTION_ID,
+        collection: options.collection,
+        params: options.params,
+        since: appliedVersion > 0 ? appliedVersion : undefined
+      }));
+      for (const mutation of pending) {
+        sendMutate(mutation);
+      }
+    };
+    ws.onmessage = (event) => {
+      try {
+        applyFrame(JSON.parse(event.data));
+      } catch {}
+    };
+    ws.onclose = () => {
+      connected = false;
+      if (closed || reconnectMs <= 0) {
+        return;
+      }
+      const delay = Math.min(reconnectMs * 2 ** attempt, maxReconnectMs);
+      attempt += 1;
+      reconnectTimer = setTimeout(connect, delay);
+    };
+  };
+  const hydratePersisted = async () => {
+    if (options.storage === undefined) {
+      return;
+    }
+    const records = await options.storage.load();
+    for (const record of records) {
+      if (pending.some((m) => m.mutationId === record.mutationId)) {
+        continue;
+      }
+      pending.push({
+        mutationId: record.mutationId,
+        name: record.name,
+        args: record.args,
+        resolve: () => {},
+        reject: () => {}
+      });
+      mutationSeq = Math.max(mutationSeq, record.mutationId);
+    }
+    if (connected) {
+      for (const mutation of pending) {
+        sendMutate(mutation);
+      }
+    }
+  };
+  const hydrateCache = async () => {
+    if (options.cache === undefined) {
+      return;
+    }
+    let snapshot;
+    try {
+      snapshot = await options.cache.load();
+    } catch {
+      return;
+    }
+    if (snapshot === undefined || appliedVersion > 0) {
+      return;
+    }
+    for (const row of snapshot.rows) {
+      confirmed.set(key(row), row);
+    }
+    appliedVersion = snapshot.version;
+    recompute();
+  };
+  if (options.cache === undefined) {
+    connect();
+    hydratePersisted();
+  } else {
+    (async () => {
+      await hydrateCache();
+      await hydratePersisted();
+      connect();
+    })();
+  }
+  return {
+    get: () => state,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    mutate: (mutateOptions) => new Promise((resolve, reject) => {
+      const mutation = {
+        mutationId: mutationSeq += 1,
+        name: mutateOptions.name,
+        args: mutateOptions.args,
+        optimistic: mutateOptions.optimistic,
+        resolve: (result) => resolve(result),
+        reject
+      };
+      pending.push(mutation);
+      persist();
+      recompute();
+      sendMutate(mutation);
+    }),
+    disconnect: () => {
+      if (closed || socket === undefined) {
+        return;
+      }
+      try {
+        socket.close();
+      } catch {}
+    },
+    close: () => {
+      if (closed) {
+        return;
+      }
+      closed = true;
+      connected = false;
+      if (reconnectTimer !== undefined) {
+        clearTimeout(reconnectTimer);
+      }
+      try {
+        socket?.send(JSON.stringify({ type: "unsubscribe", id: SUBSCRIPTION_ID }));
+        socket?.close();
+      } catch {}
+      for (const mutation of pending.splice(0)) {
+        mutation.reject(new Error("sync collection closed"));
+      }
+      persist();
+      setState({ status: "closed" });
+      listeners.clear();
+    }
+  };
+};
+
+// src/adapters/tanstack-db/index.ts
+var toMutationCall = (mapper, mutation) => {
+  if (typeof mapper === "function") {
+    return mapper(mutation);
+  }
+  if (mutation.type === "insert") {
+    return {
+      name: mapper,
+      args: { row: mutation.modified, metadata: mutation.metadata }
+    };
+  }
+  if (mutation.type === "update") {
+    return {
+      name: mapper,
+      args: {
+        key: mutation.key,
+        row: mutation.modified,
+        changes: mutation.changes,
+        metadata: mutation.metadata
+      }
+    };
+  }
+  return {
+    name: mapper,
+    args: {
+      key: mutation.key,
+      row: mutation.original,
+      metadata: mutation.metadata
+    }
+  };
+};
+var createMutationHandler = (sync, mapper) => async ({
+  transaction
+}) => {
+  if (mapper === undefined) {
+    return;
+  }
+  await Promise.all(transaction.mutations.map((mutation) => {
+    const call = toMutationCall(mapper, mutation);
+    return call === undefined ? Promise.resolve() : sync.mutate({ name: call.name, args: call.args });
+  }));
+};
+var createSyncConfig = (sync, getKey) => ({
+  rowUpdateMode: "full",
+  sync: ({ begin, write, commit, markReady }) => {
+    let previous = new Map;
+    let markedReady = false;
+    const flush = () => {
+      const state = sync.get();
+      const next = new Map;
+      for (const row of state.data) {
+        next.set(getKey(row), row);
+      }
+      begin();
+      for (const [key, row] of next) {
+        const old = previous.get(key);
+        if (old === undefined) {
+          write({ type: "insert", value: row });
+        } else if (!Object.is(old, row)) {
+          write({ type: "update", value: row, previousValue: old });
+        }
+      }
+      for (const key of previous.keys()) {
+        if (!next.has(key)) {
+          write({ type: "delete", key });
+        }
+      }
+      previous = next;
+      commit();
+      if (state.status === "ready" && !markedReady) {
+        markedReady = true;
+        markReady();
+      }
+    };
+    flush();
+    const unsubscribe = sync.subscribe(flush);
+    return () => {
+      unsubscribe();
+      sync.close();
+    };
+  }
+});
+var createSyncTanStackCollectionOptions = (options) => {
+  const {
+    url,
+    collection,
+    params,
+    getKey,
+    webSocketImpl,
+    reconnectMs,
+    maxReconnectMs,
+    storage,
+    cache,
+    onError,
+    mutations,
+    syncCollection,
+    ...collectionOptions
+  } = options;
+  const sync = syncCollection ?? createSyncCollection({
+    url,
+    collection,
+    params,
+    key: getKey,
+    webSocketImpl,
+    reconnectMs,
+    maxReconnectMs,
+    storage,
+    cache,
+    onError
+  });
+  return {
+    ...collectionOptions,
+    getKey,
+    sync: createSyncConfig(sync, getKey),
+    onInsert: createMutationHandler(sync, mutations?.insert),
+    onUpdate: createMutationHandler(sync, mutations?.update),
+    onDelete: createMutationHandler(sync, mutations?.delete)
+  };
+};
+export {
+  createSyncTanStackCollectionOptions as syncTanStackCollectionOptions,
+  createSyncTanStackCollectionOptions
+};
+
+//# debugId=87BE1F94279A349864756E2164756E21
+//# sourceMappingURL=index.js.map