\nA typesafe key schema builder for @tanstack/query. Inspired by TkDodo's \"Effective Query Keys\" pattern.\n
\n\n## Install\n\n```bash\nnpm install @arkida39/effective-query-kit\n```\n\n## Quick Start\n\nStart by defining the schema:\n\n```ts\nimport { defineQuerySchema } from \"@arkida39/effective-query-kit\";\n\nexport const queries = defineQuerySchema((b) => ({\n users: b.group({\n me: b.leaf(),\n profile: b.param((id: number) => ({ id })),\n }),\n todos: b.group(\n { recent: b.leaf() },\n b.param((id: number) => ({ id }), {\n details: b.leaf(),\n comments: b.param((page: number) => ({ page })),\n }),\n ),\n}));\n```\n\nUsage:\n\n```ts\n// Static keys\n\nq.users.me.$key\n// ↳ ['users', 'me']\n\nq.todos.$key\n// ↳ ['todos']\n\nq.todos.recent.$key\n// ↳ ['todos', 'recent']\n```\n\n```ts\n// Parameterized keys\n\nq.users.profile({ id: 1 }).$key\n// ↳ ['users', 'profile', { id: 1 }]\n```\n\n```ts\n// Collection keys\n\nq.todos.$entity({ id: 2 }).$key\n// ↳ ['todos', { id: 2 }]\n\nq.todos.$entity({ id: 2 }).details.$key \n// ↳ ['todos', { id: 2 }, 'details']\n\nq.todos.$entity({ id: 2 }).comments({ page: 2 }).$key \n// ↳ ['todos', { id: 2 }, 'comments', { page: 2 }]\n```\n\n## DSL\n\nThe DSL has 3 constructors that are used to compose the schema.\n\n### `b.leaf()`\n \nA terminal static key.\n \n```ts\nconst q = defineQuerySchema((b) => ({\n health: b.leaf(),\n}))\n \nq.health.$key\n// ↳ ['health']\n```\n\n### `b.param(build, children?, options?)`\n \nA parameterized node. The `build` function declares the parameters shape via its return type.\n \n```ts\nconst q = defineQuerySchema((b) => ({\n user: b.param((id: number) => ({ id })),\n}))\n \nq.user({ id: 1 }).$key\n// ↳ ['user', { id: 1 }]\n```\n\nWith children, it becomes a scope - children are nested under the parameterized prefix:\n \n```ts\nconst q = defineQuerySchema((b) => ({\n post: b.param((id: number) => ({ id }), {\n comments: b.param((page: number) => ({ page })),\n details: b.leaf(),\n }),\n}))\n \nq.post({ id: 1 }).details.$key\n// ↳ ['post', { id: 1 }, 'details']\nq.post({ id: 1 }).comments({ page: 2 }).$key\n// ↳ ['post', { id: 1 }, 'comments', { page: 2 }]\n```\n\n### `b.group(children, entity?)`\n \nA static grouping. Children share the group's prefix. Groups are just namespaces.\n \n```ts\nconst q = defineQuerySchema((b) => ({\n settings: b.group({\n theme: b.leaf(),\n notifications: b.leaf(),\n }),\n}))\n \nq.settings.$key\n// ↳ ['settings']\nq.settings.theme.$key\n// ↳ ['settings', 'theme']\nq.settings.notifications.$key\n// ↳ ['settings', 'notifications']\n```\n \nPass a `b.param(...)` as the second argument to create a **collection** - a group that's both fetchable as a whole and has parameterized entity access via `$entity(...)`:\n \n```ts\nconst q = defineQuerySchema((b) => ({\n todos: b.group(\n { recent: b.leaf() },\n b.param((id: number) => ({ id }), {\n details: b.leaf(),\n }),\n ),\n}))\n \nq.todos.$key\n// ↳ ['todos'] - whole collection\nq.todos.recent.$key\n// ↳ ['todos', 'recent'] - static child\nq.todos.$entity({ id: 1 }).$key\n// ↳ ['todos', { id: 1 }] - particular entity\nq.todos.$entity({ id: 1 }).details.$key\n// ↳ ['todos', { id: 1 }, 'details'] - dynamic child\n```\n\n## Object-wrapped key segments\n \nParameter values are wrapped as `{ key: value }` objects in the query key, not spread as bare values. This prevents ambiguity between path segments and parameter values:\n \n```ts\nconst q = defineQuerySchema((b) => ({\n todos: b.group(\n { recent: b.leaf() },\n b.param((board: string, id: number) => ({ board, id }), {\n details: b.leaf(),\n }),\n ),\n}))\n\n\nq.todos.recent.$key\n// ↳ ['todos', 'recent'] - two path segments\nq.todos.$entity({ board: 'a', id: 1 }).$key\n// ↳ ['todos', { board: 'a' }, { id: 1 }] - path + param + param\nq.todos.$entity({ board: 'a', id: 1 }).details.$key\n// ↳ ['todos', { board: 'a' }, { id: 1 }, 'details'] - path + param + param + path\n```\n\n## Parameter extraction with `$params`\n \nEvery parameterized schema node has a `$params(ctx)` method that extracts the typed parameters object from a `QueryFunctionContext`:\n\n```ts\nconst q = defineQuerySchema((b) => ({\n users: b.group({\n profile: b.param((id: number) => ({ id })),\n }),\n todos: b.group(\n { recent: b.leaf() },\n b.param((board: string, id: number) => ({ board, id }), {\n details: b.leaf(),\n }),\n ),\n}))\n\nqueryOptions({\n // ...\n queryFn: (ctx) => {\n // On a param node - no need to call with parameters first\n const parameters = q.users.profile.$params(ctx)\n // ↳ { id: number }\n // ...\n }\n // ...\n})\n\nqueryOptions({\n // ...\n queryFn: (ctx) => {\n // On a collection - extracts entity parameters\n const parameters = q.todos.$params(ctx)\n // ↳ { board: string, id: number }\n // ...\n }\n // ...\n})\n```\n\n## Query options with `$queryOptions`\n \nEvery fetchable entry (leaf, param, collection) exposes `$queryOptions(fetcher)`, which returns `{ queryKey, queryFn }` ready to be used in `useQuery`:\n \n```ts\n// Static entry - fetcher receives (QueryFunctionContext)\nuseQuery(\n q.users.me.$queryOptions(async (context) => {\n const res = await fetch('/api/me')\n return res.json()\n }),\n)\n \n// Dynamic entry - fetcher receives (QueryFunctionContext, params)\nuseQuery(\n q.todos.$entity({ board: 'a', id: 1 }).$queryOptions(async (context, { board, id }) => {\n const res = await fetch(`/api/todos/${board}-${id}`)\n return res.json()\n }),\n)\n \n// Spread with additional options\nuseQuery({\n ...q.todos.$entity({ board: 'a', id: 1 }).$queryOptions(fetchTodo),\n staleTime: 60_000,\n})\n```\n\n## Param propagation\n \nBy default, all parameters, except the ones that start with `_`, from a scope propagate into children's keys. Use `propagate` predicate to override this behavior:\n \n```ts\nconst q = defineQuerySchema((b) => ({\n sessions: b.param(\n (userId: string, token: string) => ({ userId, token }),\n { activity: b.leaf() },\n { propagate: (key) => key !== 'token' },\n ),\n}))\n \nconst s = q.sessions({ userId: 'u_1', token: 't_abc' })\ns.$key\n// ↳ ['sessions', { userId: 'u_1' }, { token: 't_abc' }]\ns.activity.$key\n// ↳ ['sessions', { userId: 'u_1' }, 'activity'] - 'token' excluded from children\n```\n \nThe scope's own `$key` always contains every parameter. `propagate` only affects what children inherit.\n\n## Modular schemas\n \nDefine schemas per feature and merge with spread:\n \n```ts\n// features/users.ts\nexport const users = defineQuerySchema((b) => ({\n users: b.group({\n me: b.leaf(),\n profile: b.param((id: number) => ({ id })),\n }),\n}))\n \n// features/todos.ts\nexport const todos = defineQuerySchema((b) => ({\n todos: b.group(\n { recent: b.leaf() },\n b.param((id: number) => ({ id })),\n ),\n}))\n \n// queries.ts\nimport { users } from './features/users'\nimport { todos } from './features/todos'\n \nexport const q = { ...users, ...todos }\n```\n \nTypes merge via intersection. No special utility needed.\n\n## License\n\nLicensed under the [MIT license](https://github.com/arkida39/effective-query-kit/blob/main/LICENSE).","readmeFilename":"README.md"}