@rippledb/bind-tanstack 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+import type { RippleSchema } from '@rippledb/core';
+import type { DbEvent, Store } from '@rippledb/client';
+import type { QueryClient } from '@tanstack/query-core';
+export type ListRegistryEntry = {
+    /**
+     * The query key prefix to invalidate (e.g. ['todos'], ['todoList']).
+     */
+    queryKey: readonly unknown[];
+    /**
+     * Entity names this query depends on.
+     * When a DbEvent for any of these entities fires, the query is invalidated.
+     */
+    deps: readonly string[];
+};
+export type ListRegistry = {
+    entries: ListRegistryEntry[];
+};
+/**
+ * Fluent builder for defining which query keys depend on which entities.
+ *
+ * @example
+ * ```ts
+ * const registry = defineListRegistry()
+ *   .list(['todos'], { deps: ['todos'] })
+ *   .list(['todoWithTags'], { deps: ['todos', 'tags'] })
+ *   .list(['dashboard'], { deps: ['todos', 'users', 'projects'] });
+ * ```
+ */
+export declare function defineListRegistry(): ListRegistryBuilder;
+declare class ListRegistryBuilder implements ListRegistry {
+    readonly entries: ListRegistryEntry[];
+    constructor(entries: ListRegistryEntry[]);
+    /**
+     * Register a list query key and its entity dependencies.
+     *
+     * @param queryKey - The query key prefix to invalidate
+     * @param opts - Configuration with `deps` array of entity names
+     */
+    list(queryKey: readonly unknown[], opts: {
+        deps: readonly string[];
+    }): ListRegistryBuilder;
+}
+export type WireTanstackInvalidationOptions<S extends RippleSchema = RippleSchema> = {
+    /**
+     * TanStack QueryClient instance.
+     */
+    queryClient: QueryClient;
+    /**
+     * The store to listen to for DbEvents.
+     * Must implement `onEvent(cb)`.
+     */
+    store?: Store<S>;
+    /**
+     * Alternative: provide onEvent callback directly (useful for testing).
+     */
+    onEvent?: (cb: (event: DbEvent<S>) => void) => () => void;
+    /**
+     * Registry mapping list query keys to their entity dependencies.
+     */
+    registry?: ListRegistry;
+    /**
+     * Debounce time in milliseconds to coalesce rapid-fire invalidations.
+     * Set to 0 to disable debouncing.
+     * @default 50
+     */
+    debounceMs?: number;
+    /**
+     * Whether to invalidate row queries ([entity, id]) directly.
+     * @default true
+     */
+    invalidateRows?: boolean;
+};
+/**
+ * Wire RippleDB DbEvents to TanStack Query cache invalidation.
+ *
+ * @example
+ * ```ts
+ * import { wireTanstackInvalidation, defineListRegistry } from '@rippledb/bind-tanstack';
+ *
+ * const registry = defineListRegistry()
+ *   .list(['todos'], { deps: ['todos'] })
+ *   .list(['dashboard'], { deps: ['todos', 'users'] });
+ *
+ * const cleanup = wireTanstackInvalidation({
+ *   queryClient,
+ *   store,
+ *   registry,
+ *   debounceMs: 50,
+ * });
+ *
+ * // Later: cleanup() to unsubscribe
+ * ```
+ *
+ * @returns Cleanup function to unsubscribe from events
+ */
+export declare function wireTanstackInvalidation<S extends RippleSchema = RippleSchema>(opts: WireTanstackInvalidationOptions<S>): () => void;
+export type { DbEvent, Store } from '@rippledb/client';
+export type { QueryClient } from '@tanstack/query-core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAMxD,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;OAEG;IACH,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAC7B;;;OAGG;IACH,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,IAAI,mBAAmB,CAExD;AAED,cAAM,mBAAoB,YAAW,YAAY;aACnB,OAAO,EAAE,iBAAiB,EAAE;gBAA5B,OAAO,EAAE,iBAAiB,EAAE;IAExD;;;;;OAKG;IACH,IAAI,CACF,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,IAAI,EAAE;QAAE,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GAChC,mBAAmB;CAMvB;AAMD,MAAM,MAAM,+BAA+B,CACzC,CAAC,SAAS,YAAY,GAAG,YAAY,IACnC;IACF;;OAEG;IACH,WAAW,EAAE,WAAW,CAAC;IAEzB;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAEjB;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAE1D;;OAEG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;IAExB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAC5E,IAAI,EAAE,+BAA+B,CAAC,CAAC,CAAC,GACvC,MAAM,IAAI,CA+EZ;AAMD,YAAY,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,85 @@
+// src/index.ts
+function defineListRegistry() {
+  return new ListRegistryBuilder([]);
+}
+var ListRegistryBuilder = class _ListRegistryBuilder {
+  constructor(entries) {
+    this.entries = entries;
+  }
+  /**
+   * Register a list query key and its entity dependencies.
+   *
+   * @param queryKey - The query key prefix to invalidate
+   * @param opts - Configuration with `deps` array of entity names
+   */
+  list(queryKey, opts) {
+    return new _ListRegistryBuilder([
+      ...this.entries,
+      { queryKey, deps: opts.deps }
+    ]);
+  }
+};
+function wireTanstackInvalidation(opts) {
+  const {
+    queryClient,
+    store,
+    onEvent,
+    registry,
+    debounceMs = 50,
+    invalidateRows = true
+  } = opts;
+  const subscribe = onEvent ?? (store?.onEvent ? (cb) => store.onEvent(cb) : void 0);
+  if (!subscribe) {
+    throw new Error(
+      "wireTanstackInvalidation: either `store` (with onEvent) or `onEvent` callback is required"
+    );
+  }
+  let pendingEntities = /* @__PURE__ */ new Set();
+  let pendingRows = [];
+  let debounceTimeout = null;
+  const flush = () => {
+    debounceTimeout = null;
+    if (invalidateRows) {
+      for (const { entity, id } of pendingRows) {
+        queryClient.invalidateQueries({ queryKey: [entity, id] });
+      }
+    }
+    if (registry) {
+      for (const entry of registry.entries) {
+        const shouldInvalidate = entry.deps.some(
+          (dep) => pendingEntities.has(dep)
+        );
+        if (shouldInvalidate) {
+          queryClient.invalidateQueries({ queryKey: [...entry.queryKey] });
+        }
+      }
+    }
+    for (const entity of pendingEntities) {
+      queryClient.invalidateQueries({ queryKey: [entity] });
+    }
+    pendingEntities = /* @__PURE__ */ new Set();
+    pendingRows = [];
+  };
+  const handleEvent = (event) => {
+    pendingEntities.add(event.entity);
+    if (event.id) {
+      pendingRows.push({ entity: event.entity, id: event.id });
+    }
+    if (debounceMs > 0) {
+      if (debounceTimeout) clearTimeout(debounceTimeout);
+      debounceTimeout = setTimeout(flush, debounceMs);
+    } else {
+      flush();
+    }
+  };
+  const unsubscribe = subscribe(handleEvent);
+  return () => {
+    if (debounceTimeout) clearTimeout(debounceTimeout);
+    unsubscribe();
+  };
+}
+export {
+  defineListRegistry,
+  wireTanstackInvalidation
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { RippleSchema } from '@rippledb/core';\nimport type { DbEvent, Store } from '@rippledb/client';\nimport type { QueryClient } from '@tanstack/query-core';\n\n// ============================================================================\n// List Registry\n// ============================================================================\n\nexport type ListRegistryEntry = {\n  /**\n   * The query key prefix to invalidate (e.g. ['todos'], ['todoList']).\n   */\n  queryKey: readonly unknown[];\n  /**\n   * Entity names this query depends on.\n   * When a DbEvent for any of these entities fires, the query is invalidated.\n   */\n  deps: readonly string[];\n};\n\nexport type ListRegistry = {\n  entries: ListRegistryEntry[];\n};\n\n/**\n * Fluent builder for defining which query keys depend on which entities.\n *\n * @example\n * ```ts\n * const registry = defineListRegistry()\n *   .list(['todos'], { deps: ['todos'] })\n *   .list(['todoWithTags'], { deps: ['todos', 'tags'] })\n *   .list(['dashboard'], { deps: ['todos', 'users', 'projects'] });\n * ```\n */\nexport function defineListRegistry(): ListRegistryBuilder {\n  return new ListRegistryBuilder([]);\n}\n\nclass ListRegistryBuilder implements ListRegistry {\n  constructor(public readonly entries: ListRegistryEntry[]) {}\n\n  /**\n   * Register a list query key and its entity dependencies.\n   *\n   * @param queryKey - The query key prefix to invalidate\n   * @param opts - Configuration with `deps` array of entity names\n   */\n  list(\n    queryKey: readonly unknown[],\n    opts: { deps: readonly string[] },\n  ): ListRegistryBuilder {\n    return new ListRegistryBuilder([\n      ...this.entries,\n      { queryKey, deps: opts.deps },\n    ]);\n  }\n}\n\n// ============================================================================\n// Invalidation Wiring\n// ============================================================================\n\nexport type WireTanstackInvalidationOptions<\n  S extends RippleSchema = RippleSchema,\n> = {\n  /**\n   * TanStack QueryClient instance.\n   */\n  queryClient: QueryClient;\n\n  /**\n   * The store to listen to for DbEvents.\n   * Must implement `onEvent(cb)`.\n   */\n  store?: Store<S>;\n\n  /**\n   * Alternative: provide onEvent callback directly (useful for testing).\n   */\n  onEvent?: (cb: (event: DbEvent<S>) => void) => () => void;\n\n  /**\n   * Registry mapping list query keys to their entity dependencies.\n   */\n  registry?: ListRegistry;\n\n  /**\n   * Debounce time in milliseconds to coalesce rapid-fire invalidations.\n   * Set to 0 to disable debouncing.\n   * @default 50\n   */\n  debounceMs?: number;\n\n  /**\n   * Whether to invalidate row queries ([entity, id]) directly.\n   * @default true\n   */\n  invalidateRows?: boolean;\n};\n\n/**\n * Wire RippleDB DbEvents to TanStack Query cache invalidation.\n *\n * @example\n * ```ts\n * import { wireTanstackInvalidation, defineListRegistry } from '@rippledb/bind-tanstack';\n *\n * const registry = defineListRegistry()\n *   .list(['todos'], { deps: ['todos'] })\n *   .list(['dashboard'], { deps: ['todos', 'users'] });\n *\n * const cleanup = wireTanstackInvalidation({\n *   queryClient,\n *   store,\n *   registry,\n *   debounceMs: 50,\n * });\n *\n * // Later: cleanup() to unsubscribe\n * ```\n *\n * @returns Cleanup function to unsubscribe from events\n */\nexport function wireTanstackInvalidation<S extends RippleSchema = RippleSchema>(\n  opts: WireTanstackInvalidationOptions<S>,\n): () => void {\n  const {\n    queryClient,\n    store,\n    onEvent,\n    registry,\n    debounceMs = 50,\n    invalidateRows = true,\n  } = opts;\n\n  // Get the event subscription function (bind to store if using store.onEvent)\n  const subscribe = onEvent ?? (store?.onEvent ? (cb: (event: DbEvent<S>) => void) => store.onEvent!(cb) : undefined);\n  if (!subscribe) {\n    throw new Error(\n      'wireTanstackInvalidation: either `store` (with onEvent) or `onEvent` callback is required',\n    );\n  }\n\n  // Track pending invalidations for debouncing\n  let pendingEntities = new Set<string>();\n  let pendingRows: Array<{ entity: string; id: string }> = [];\n  let debounceTimeout: ReturnType<typeof setTimeout> | null = null;\n\n  const flush = () => {\n    debounceTimeout = null;\n\n    // Invalidate row queries\n    if (invalidateRows) {\n      for (const { entity, id } of pendingRows) {\n        queryClient.invalidateQueries({ queryKey: [entity, id] });\n      }\n    }\n\n    // Invalidate list queries based on registry\n    if (registry) {\n      for (const entry of registry.entries) {\n        const shouldInvalidate = entry.deps.some((dep) =>\n          pendingEntities.has(dep),\n        );\n        if (shouldInvalidate) {\n          queryClient.invalidateQueries({ queryKey: [...entry.queryKey] });\n        }\n      }\n    }\n\n    // Also invalidate entity-level queries (e.g. ['todos'])\n    for (const entity of pendingEntities) {\n      queryClient.invalidateQueries({ queryKey: [entity] });\n    }\n\n    // Clear pending\n    pendingEntities = new Set();\n    pendingRows = [];\n  };\n\n  const handleEvent = (event: DbEvent<S>) => {\n    pendingEntities.add(event.entity as string);\n\n    if (event.id) {\n      pendingRows.push({ entity: event.entity as string, id: event.id });\n    }\n\n    // Schedule flush\n    if (debounceMs > 0) {\n      if (debounceTimeout) clearTimeout(debounceTimeout);\n      debounceTimeout = setTimeout(flush, debounceMs);\n    } else {\n      flush();\n    }\n  };\n\n  // Subscribe to events\n  const unsubscribe = subscribe(handleEvent);\n\n  // Return cleanup function\n  return () => {\n    if (debounceTimeout) clearTimeout(debounceTimeout);\n    unsubscribe();\n  };\n}\n\n// ============================================================================\n// Re-exports for convenience\n// ============================================================================\n\nexport type { DbEvent, Store } from '@rippledb/client';\nexport type { QueryClient } from '@tanstack/query-core';\n"],"mappings":";AAmCO,SAAS,qBAA0C;AACxD,SAAO,IAAI,oBAAoB,CAAC,CAAC;AACnC;AAEA,IAAM,sBAAN,MAAM,qBAA4C;AAAA,EAChD,YAA4B,SAA8B;AAA9B;AAAA,EAA+B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQ3D,KACE,UACA,MACqB;AACrB,WAAO,IAAI,qBAAoB;AAAA,MAC7B,GAAG,KAAK;AAAA,MACR,EAAE,UAAU,MAAM,KAAK,KAAK;AAAA,IAC9B,CAAC;AAAA,EACH;AACF;AAmEO,SAAS,yBACd,MACY;AACZ,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,aAAa;AAAA,IACb,iBAAiB;AAAA,EACnB,IAAI;AAGJ,QAAM,YAAY,YAAY,OAAO,UAAU,CAAC,OAAoC,MAAM,QAAS,EAAE,IAAI;AACzG,MAAI,CAAC,WAAW;AACd,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAGA,MAAI,kBAAkB,oBAAI,IAAY;AACtC,MAAI,cAAqD,CAAC;AAC1D,MAAI,kBAAwD;AAE5D,QAAM,QAAQ,MAAM;AAClB,sBAAkB;AAGlB,QAAI,gBAAgB;AAClB,iBAAW,EAAE,QAAQ,GAAG,KAAK,aAAa;AACxC,oBAAY,kBAAkB,EAAE,UAAU,CAAC,QAAQ,EAAE,EAAE,CAAC;AAAA,MAC1D;AAAA,IACF;AAGA,QAAI,UAAU;AACZ,iBAAW,SAAS,SAAS,SAAS;AACpC,cAAM,mBAAmB,MAAM,KAAK;AAAA,UAAK,CAAC,QACxC,gBAAgB,IAAI,GAAG;AAAA,QACzB;AACA,YAAI,kBAAkB;AACpB,sBAAY,kBAAkB,EAAE,UAAU,CAAC,GAAG,MAAM,QAAQ,EAAE,CAAC;AAAA,QACjE;AAAA,MACF;AAAA,IACF;AAGA,eAAW,UAAU,iBAAiB;AACpC,kBAAY,kBAAkB,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC;AAAA,IACtD;AAGA,sBAAkB,oBAAI,IAAI;AAC1B,kBAAc,CAAC;AAAA,EACjB;AAEA,QAAM,cAAc,CAAC,UAAsB;AACzC,oBAAgB,IAAI,MAAM,MAAgB;AAE1C,QAAI,MAAM,IAAI;AACZ,kBAAY,KAAK,EAAE,QAAQ,MAAM,QAAkB,IAAI,MAAM,GAAG,CAAC;AAAA,IACnE;AAGA,QAAI,aAAa,GAAG;AAClB,UAAI,gBAAiB,cAAa,eAAe;AACjD,wBAAkB,WAAW,OAAO,UAAU;AAAA,IAChD,OAAO;AACL,YAAM;AAAA,IACR;AAAA,EACF;AAGA,QAAM,cAAc,UAAU,WAAW;AAGzC,SAAO,MAAM;AACX,QAAI,gBAAiB,cAAa,eAAe;AACjD,gBAAY;AAAA,EACd;AACF;","names":[]}

package/dist/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@rippledb/bind-tanstack",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "description": "TanStack Query invalidation binding for RippleDB",
+  "keywords": [
+    "rippledb",
+    "tanstack",
+    "tanstack-query",
+    "react-query",
+    "invalidation",
+    "sync",
+    "local-first",
+    "offline-first"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eckerlein/rippledb.git",
+    "directory": "packages/bind-tanstack"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@rippledb/core": "0.1.0",
+    "@rippledb/client": "0.1.0"
+  },
+  "peerDependencies": {
+    "@tanstack/query-core": "^5.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/query-core": "^5.60.5",
+    "eslint": "^9.37.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@rippledb/store-memory": "0.1.0"
+  },
+  "tsup": {
+    "entry": [
+      "src/index.ts"
+    ],
+    "format": [
+      "esm"
+    ],
+    "dts": false,
+    "sourcemap": true,
+    "clean": true
+  },
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest --passWithNoTests",
+    "lint": "eslint ."
+  }
+}