@rippledb/client-query 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# @rippledb/client-query
+
+Final DX package combining:
+
+- `@rippledb/client-controllers` (CRUD controllers)
+- `@rippledb/bind-tanstack-query` (TanStack Query invalidation wiring)
+
+This package is intended to be the ergonomic “one import” for client apps using RippleDB + TanStack Query.
+
+📚 **Documentation:** [rippledb.dev/docs/reference/client-query](https://rippledb.dev/docs/reference/client-query)
+
+## Installation
+
+```bash
+pnpm add @rippledb/client-query @tanstack/query-core
+```
+
+If you use a framework adapter (e.g. `@tanstack/react-query`), you already have `@tanstack/query-core`.
+
+## Usage
+
+```ts
+import { QueryClient } from '@tanstack/query-core';
+import { MemoryStore } from '@rippledb/store-memory';
+import { defineSchema } from '@rippledb/core';
+import { createClientQueryApi } from '@rippledb/client-query';
+
+type Schema = {
+  todos: { id: string; title: string; done: boolean };
+  users: { id: string; name: string; email: string };
+};
+
+const store = new MemoryStore<Schema>();
+const queryClient = new QueryClient();
+
+// Runtime descriptor (entity + field discovery)
+const schema = defineSchema({
+  todos: { id: '', title: '', done: false },
+  users: { id: '', name: '', email: '' },
+});
+
+const api = createClientQueryApi({
+  store,
+  stream: 'user-123',
+  queryClient,
+  schema,
+});
+
+// CRUD via dynamic controllers
+const todo = await api.todos.create({ title: 'Buy milk', done: false });
+await api.todos.update(todo.id, { done: true });
+
+// Cached query helper + automatic invalidation
+const todos = await api.query({
+  key: ['todos'],
+  deps: ['todos'],
+  fn: () => api.todos.list({ entity: 'todos' }),
+});
+```
+
+## Query registry
+
+If you want to register “list queries” up-front (recommended), build a registry and pass it in:
+
+```ts
+import { defineListRegistry } from '@rippledb/bind-tanstack-query';
+
+const registry = defineListRegistry()
+  .list(['todos'], { deps: ['todos'] })
+  .list(['dashboard'], { deps: ['todos', 'users'] });
+
+const api = createClientQueryApi({ store, stream, queryClient, schema, registry });
+```
+
+## License
+
+MIT
+

package/dist/index.js

@@ -0,0 +1,60 @@
+// src/index.ts
+import { createEntityController } from "@rippledb/client-controllers";
+import { wireTanstackInvalidation } from "@rippledb/bind-tanstack-query";
+function createClientQueryApi(options) {
+  const {
+    store,
+    stream,
+    queryClient,
+    schema,
+    registry: providedRegistry,
+    debounceMs = 50
+  } = options;
+  const controllers = {};
+  for (const entity of schema.entities) {
+    controllers[entity] = createEntityController({
+      store,
+      entity,
+      stream
+    });
+  }
+  const registry = providedRegistry ?? { entries: [] };
+  const cleanup = wireTanstackInvalidation({
+    queryClient,
+    store,
+    registry,
+    debounceMs
+  });
+  const registerQueryIfNeeded = (opts) => {
+    const exists = registry.entries.some((e) => {
+      if (e.queryKey.length !== opts.key.length) return false;
+      for (let i = 0; i < e.queryKey.length; i += 1) {
+        if (!Object.is(e.queryKey[i], opts.key[i])) return false;
+      }
+      return true;
+    });
+    if (!exists) {
+      registry.entries.push({
+        queryKey: opts.key,
+        deps: opts.deps
+      });
+    }
+  };
+  const api = {
+    ...controllers,
+    async query(queryOptions) {
+      registerQueryIfNeeded(queryOptions);
+      return await queryClient.fetchQuery({
+        // TanStack queryKey expects readonly unknown[]; our key matches.
+        queryKey: queryOptions.key,
+        queryFn: async () => queryOptions.fn()
+      });
+    },
+    cleanup
+  };
+  return api;
+}
+export {
+  createClientQueryApi
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { Store } from '@rippledb/client';\nimport type { RippleSchema, EntityName, SchemaDescriptor } from '@rippledb/core';\nimport type { QueryClient } from '@tanstack/query-core';\nimport { createEntityController, type EntityController } from '@rippledb/client-controllers';\nimport { wireTanstackInvalidation, type ListRegistry } from '@rippledb/bind-tanstack-query';\n\n/**\n * Query helper options for registering list queries with automatic invalidation.\n */\nexport type QueryOptions<\n  S extends RippleSchema = RippleSchema,\n  T = unknown,\n> = {\n  /**\n   * The query key prefix to invalidate (e.g. ['todos'], ['todoList']).\n   */\n  key: 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 EntityName<S>[];\n  /**\n   * The query function to execute.\n   */\n  fn: () => Promise<T>;\n};\n\n/**\n * Client Query API that combines controllers with TanStack Query invalidation.\n * \n * Provides:\n * - Dynamic entity controllers (api.todos, api.users, etc.)\n * - Automatic cache invalidation\n * - Query helpers with dependency tracking\n * \n * @example\n * ```ts\n * const api = createClientQueryApi({\n *   store,\n *   stream: 'user-123',\n *   queryClient,\n *   schema: schemaDescriptor,\n * });\n * \n * // CRUD operations\n * const todo = await api.todos.create({ title: 'Buy milk' });\n * const fetched = await api.todos.read('todo-1');\n * \n * // Query helpers with automatic invalidation\n * const todos = await api.query({\n *   key: ['todos'],\n *   deps: ['todos'],\n *   fn: () => api.todos.list({ entity: 'todos' }),\n * });\n * ```\n */\nexport type ClientQueryApi<\n  S extends RippleSchema = RippleSchema,\n  ListQuery = unknown,\n> = {\n  /**\n   * Entity controllers, dynamically created from schema.entities.\n   * Each entity gets a controller with CRUD operations.\n   */\n  [K in EntityName<S>]: EntityController<S, K, ListQuery>;\n} & {\n  /**\n   * Query helper that registers a query with automatic invalidation.\n   * \n   * @param options - Query options with key, deps, and fn\n   * @returns The result of the query function\n   */\n  query<T>(options: QueryOptions<S, T>): Promise<T>;\n  \n  /**\n   * Cleanup function to unsubscribe from invalidation events.\n   */\n  cleanup(): void;\n};\n\nexport type CreateClientQueryApiOptions<\n  S extends RippleSchema = RippleSchema,\n  ListQuery = unknown,\n> = {\n  /**\n   * The Store instance to operate on.\n   */\n  store: Store<S, ListQuery>;\n  \n  /**\n   * The stream ID for all changes created by controllers.\n   */\n  stream: string;\n  \n  /**\n   * TanStack QueryClient instance.\n   */\n  queryClient: QueryClient;\n  \n  /**\n   * Schema descriptor for runtime entity discovery.\n   */\n  schema: SchemaDescriptor<S>;\n  \n  /**\n   * Optional list registry for custom query key mappings.\n   * If not provided, a default registry is created from query() calls.\n   */\n  registry?: ListRegistry;\n  \n  /**\n   * Debounce time in milliseconds for invalidation coalescing.\n   * @default 50\n   */\n  debounceMs?: number;\n};\n\n/**\n * Creates a Client Query API that combines controllers with TanStack Query invalidation.\n * \n * The API dynamically creates entity controllers from the schema descriptor,\n * allowing you to use `api.todos`, `api.users`, etc. without manually creating\n * controllers for each entity.\n * \n * @example\n * ```ts\n * import { defineSchema } from '@rippledb/core';\n * import { createClientQueryApi } from '@rippledb/client-query';\n * \n * const schema = defineSchema({\n *   todos: { id: '', title: '', done: false },\n *   users: { id: '', name: '', email: '' },\n * });\n * \n * const api = createClientQueryApi({\n *   store,\n *   stream: 'user-123',\n *   queryClient,\n *   schema,\n * });\n * \n * // Use dynamic controllers\n * const todo = await api.todos.create({ title: 'Buy milk' });\n * const user = await api.users.read('user-1');\n * ```\n */\nexport function createClientQueryApi<\n  S extends RippleSchema = RippleSchema,\n  ListQuery = unknown,\n>(options: CreateClientQueryApiOptions<S, ListQuery>): ClientQueryApi<S, ListQuery> {\n  const {\n    store,\n    stream,\n    queryClient,\n    schema,\n    registry: providedRegistry,\n    debounceMs = 50,\n  } = options;\n\n  // Create controllers for each entity dynamically\n  const controllers = {} as Record<EntityName<S>, EntityController<S, EntityName<S>, ListQuery>>;\n  \n  for (const entity of schema.entities) {\n    controllers[entity] = createEntityController({\n      store,\n      entity,\n      stream,\n    });\n  }\n\n  // If the caller doesn't provide a registry, we create a new mutable registry.\n  // If a registry *is* provided, it is expected to be mutable and `api.query()`\n  // will add entries to it dynamically (so invalidation works automatically).\n  const registry: ListRegistry = providedRegistry ?? { entries: [] };\n\n  // Wire up invalidation once\n  const cleanup = wireTanstackInvalidation({\n    queryClient,\n    store,\n    registry,\n    debounceMs,\n  });\n\n  const registerQueryIfNeeded = (opts: QueryOptions<S, unknown>) => {\n    // Avoid duplicate registrations for identical query keys (shallow compare)\n    const exists = registry.entries.some((e) => {\n      if (e.queryKey.length !== opts.key.length) return false;\n      for (let i = 0; i < e.queryKey.length; i += 1) {\n        if (!Object.is(e.queryKey[i], opts.key[i])) return false;\n      }\n      return true;\n    });\n    if (!exists) {\n      registry.entries.push({\n        queryKey: opts.key,\n        deps: opts.deps as readonly string[],\n      });\n    }\n  };\n\n  // Create the API object with dynamic entity controllers\n  const api = {\n    ...controllers,\n    \n    async query<T>(queryOptions: QueryOptions<S, T>): Promise<T> {\n      registerQueryIfNeeded(queryOptions);\n\n      // Use TanStack Query for caching + consistent invalidation\n      return await queryClient.fetchQuery({\n        // TanStack queryKey expects readonly unknown[]; our key matches.\n        queryKey: queryOptions.key,\n        queryFn: async () => queryOptions.fn(),\n      });\n    },\n    \n    cleanup,\n  } as ClientQueryApi<S, ListQuery>;\n\n  return api;\n}\n\n// Re-export types for convenience\nexport type { EntityController } from '@rippledb/client-controllers';\nexport type { ListRegistry } from '@rippledb/bind-tanstack-query';\n"],"mappings":";AAGA,SAAS,8BAAqD;AAC9D,SAAS,gCAAmD;AA+IrD,SAAS,qBAGd,SAAkF;AAClF,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,UAAU;AAAA,IACV,aAAa;AAAA,EACf,IAAI;AAGJ,QAAM,cAAc,CAAC;AAErB,aAAW,UAAU,OAAO,UAAU;AACpC,gBAAY,MAAM,IAAI,uBAAuB;AAAA,MAC3C;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAC;AAAA,EACH;AAKA,QAAM,WAAyB,oBAAoB,EAAE,SAAS,CAAC,EAAE;AAGjE,QAAM,UAAU,yBAAyB;AAAA,IACvC;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AAED,QAAM,wBAAwB,CAAC,SAAmC;AAEhE,UAAM,SAAS,SAAS,QAAQ,KAAK,CAAC,MAAM;AAC1C,UAAI,EAAE,SAAS,WAAW,KAAK,IAAI,OAAQ,QAAO;AAClD,eAAS,IAAI,GAAG,IAAI,EAAE,SAAS,QAAQ,KAAK,GAAG;AAC7C,YAAI,CAAC,OAAO,GAAG,EAAE,SAAS,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,EAAG,QAAO;AAAA,MACrD;AACA,aAAO;AAAA,IACT,CAAC;AACD,QAAI,CAAC,QAAQ;AACX,eAAS,QAAQ,KAAK;AAAA,QACpB,UAAU,KAAK;AAAA,QACf,MAAM,KAAK;AAAA,MACb,CAAC;AAAA,IACH;AAAA,EACF;AAGA,QAAM,MAAM;AAAA,IACV,GAAG;AAAA,IAEH,MAAM,MAAS,cAA8C;AAC3D,4BAAsB,YAAY;AAGlC,aAAO,MAAM,YAAY,WAAW;AAAA;AAAA,QAElC,UAAU,aAAa;AAAA,QACvB,SAAS,YAAY,aAAa,GAAG;AAAA,MACvC,CAAC;AAAA,IACH;AAAA,IAEA;AAAA,EACF;AAEA,SAAO;AACT;","names":[]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@rippledb/client-query",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "description": "Final DX package combining controllers + bind-tanstack-query for RippleDB",
+  "keywords": [
+    "rippledb",
+    "tanstack-query",
+    "react-query",
+    "controllers",
+    "crud",
+    "local-first",
+    "offline-first"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eckerlein/rippledb.git",
+    "directory": "packages/client-query"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@rippledb/core": "0.1.1",
+    "@rippledb/client": "0.1.1",
+    "@rippledb/client-controllers": "0.1.0",
+    "@rippledb/bind-tanstack-query": "0.1.1"
+  },
+  "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.1"
+  },
+  "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 ."
+  }
+}