@beignet/nuqs 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @beignet/nuqs
+
+## 0.0.1
+
+- Initial Beignet release under the `@beignet` npm scope.

package/README.md

@@ -0,0 +1,104 @@
+# @beignet/nuqs
+
+> nuqs integration for Beignet
+
+This package gives you a thin bridge between contract query params and [`nuqs`](https://nuqs.dev) URL state.
+
+It does not replace `@beignet/react-query`. Instead, it helps you keep URL-backed filters aligned with a contract's `query` shape and then pass that state into `rq(contract).queryOptions(...)`.
+
+## Installation
+
+```bash
+npm install @beignet/nuqs @beignet/react-query nuqs react @tanstack/react-query
+```
+
+In Next.js App Router, mount the `NuqsAdapter` once near the root:
+
+```tsx
+import { NuqsAdapter } from "@beignet/nuqs/next/app";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <NuqsAdapter>{children}</NuqsAdapter>;
+}
+```
+
+## Setup
+
+```ts
+import { createClient } from "@beignet/core/client";
+import { createReactQuery } from "@beignet/react-query";
+import { createNuqs } from "@beignet/nuqs";
+
+const client = createClient({ baseUrl: "/api" });
+
+export const rq = createReactQuery(client);
+export const nq = createNuqs();
+```
+
+## Usage
+
+```tsx
+import { parseAsInteger, parseAsString } from "nuqs";
+import { useQuery } from "@tanstack/react-query";
+import { nq } from "@/client/nq";
+import { rq } from "@/client/rq";
+import { listContacts } from "@/features/contacts/contracts";
+
+const contactsSearch = nq(listContacts).query({
+  parsers: {
+    search: parseAsString.withDefault(""),
+    offset: parseAsInteger.withDefault(0),
+  },
+});
+
+function ContactsPage() {
+  const [filters, setFilters] = contactsSearch.useState();
+
+  const query = useQuery(
+    contactsSearch.toQueryOptions(rq(listContacts), filters)
+  );
+
+  return null;
+}
+```
+
+## API
+
+### `createNuqs()`
+
+Creates the Beignet `nuqs` adapter factory.
+
+### `nq(contract).query({ parsers, ...options })`
+
+Creates a contract-aware URL query helper.
+
+- `parsers`: required `nuqs` parser map keyed by the contract's query params
+- `history`, `shallow`, `scroll`, `urlKeys`, etc.: forwarded to `useQueryStates`
+
+### `.useState(options?)`
+
+Wraps `nuqs` `useQueryStates(parsers, options)` with the configured parser map.
+
+### `.toQuery(state, { omitNullish })`
+
+Converts `nuqs` state into a Beignet query object.
+
+- `omitNullish` defaults to `true`
+- `null` and `undefined` are removed
+- valid falsy values like `0`, `false`, and `""` are preserved
+
+### `.toQueryOptions(rq(contract), state, options?)`
+
+Convenience helper that calls `rq(contract).queryOptions({ query, ...options })`.
+
+## When to use this
+
+`@beignet/nuqs` is a good fit for pages where the URL should reflect search or filter state:
+
+- admin tables
+- search screens
+- dashboards
+- reporting pages
+- index/list views with tabs, pagination, or filters
+
+If you just need typed fetching, use `@beignet/react-query` directly.

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import type { EndpointCallArgs, InferQuery } from "@beignet/core/client";
+import { type ContractLike, type HttpContractConfig, type ResolveContract } from "@beignet/core/contracts";
+import type { ContractUseQueryOptions, ReactQueryContractHelper } from "@beignet/react-query";
+import { type inferParserType, type UrlKeys, type UseQueryStatesKeysMap, type UseQueryStatesOptions, type UseQueryStatesReturn } from "./runtime";
+type QueryShape<TContract extends HttpContractConfig> = NonNullable<InferQuery<TContract>>;
+type QueryRecord<TContract extends HttpContractConfig> = QueryShape<TContract> extends Record<string, unknown> ? QueryShape<TContract> : never;
+type QueryKeys<TContract extends HttpContractConfig> = keyof QueryRecord<TContract> & string;
+type QueryParsers<TContract extends HttpContractConfig> = Partial<{
+    [K in QueryKeys<TContract>]: UseQueryStatesKeysMap<{
+        [P in K]: Exclude<QueryRecord<TContract>[P], undefined>;
+    }>[K];
+}>;
+export type NuqsParserMap<TContract extends HttpContractConfig> = QueryParsers<TContract>;
+export type NuqsState<TParsers extends UseQueryStatesKeysMap> = inferParserType<TParsers>;
+type ContractQueryHookOptions<TParsers extends UseQueryStatesKeysMap> = Partial<UseQueryStatesOptions<TParsers>>;
+type ContractQueryConfig<TContract extends HttpContractConfig, TParsers extends NuqsParserMap<TContract> & UseQueryStatesKeysMap> = ContractQueryHookOptions<TParsers> & {
+    parsers: TParsers;
+};
+type HasRequiredKeys<T> = {
+    [K in keyof T]-?: Record<string, never> extends Pick<T, K> ? never : K;
+}[keyof T];
+type NuqsQueryOptionsRequiredInput<TContract extends HttpContractConfig> = Omit<EndpointCallArgs<TContract>, "query" | "rawBody" | "signal">;
+type NuqsQueryOptions<TContract extends HttpContractConfig> = Omit<ContractUseQueryOptions<TContract>, "query"> & {
+    query?: EndpointCallArgs<TContract>["query"];
+    omitNullish?: boolean;
+};
+type NuqsQueryOptionsCallArgs<TContract extends HttpContractConfig> = HasRequiredKeys<NuqsQueryOptionsRequiredInput<TContract>> extends never ? [opts?: NuqsQueryOptions<TContract>] : [opts: NuqsQueryOptions<TContract>];
+export declare class NuqsQueryHelper<TContract extends HttpContractConfig, TParsers extends NuqsParserMap<TContract> & UseQueryStatesKeysMap> {
+    private contract;
+    private config;
+    constructor(contract: TContract, config: ContractQueryConfig<TContract, TParsers>);
+    useState(options?: ContractQueryHookOptions<TParsers>): UseQueryStatesReturn<TParsers>;
+    toQuery(state: NuqsState<TParsers>, opts?: {
+        omitNullish?: boolean;
+    }): EndpointCallArgs<TContract>["query"];
+    toQueryOptions(rq: ReactQueryContractHelper<TContract>, state: NuqsState<TParsers>, ...callArgs: NuqsQueryOptionsCallArgs<TContract>): ReturnType<ReactQueryContractHelper<TContract>["queryOptions"]>;
+    get contractName(): string;
+}
+export declare class NuqsContractHelper<TContract extends HttpContractConfig> {
+    private contract;
+    constructor(contract: TContract);
+    query<TParsers extends NuqsParserMap<TContract> & UseQueryStatesKeysMap>(config: ContractQueryConfig<TContract, TParsers>): NuqsQueryHelper<TContract, TParsers>;
+}
+export declare function createNuqs(): <TContractLike extends ContractLike>(contract: TContractLike) => NuqsContractHelper<ResolveContract<TContractLike>>;
+export type { UrlKeys };
+//# 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":"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"}

package/dist/index.js

@@ -0,0 +1,64 @@
+import { resolveContract, } from "@beignet/core/contracts";
+import { useQueryStates, } from "./runtime";
+export class NuqsQueryHelper {
+    contract;
+    config;
+    constructor(contract, config) {
+        this.contract = contract;
+        this.config = config;
+    }
+    useState(options = {}) {
+        const { parsers, ...baseOptions } = this.config;
+        return useQueryStates(parsers, {
+            ...baseOptions,
+            ...options,
+        });
+    }
+    toQuery(state, opts = {}) {
+        const { omitNullish = true } = opts;
+        const query = {};
+        const entries = Object.entries(state);
+        for (const [key, value] of entries) {
+            if (omitNullish && (value === null || value === undefined))
+                continue;
+            query[key] = value;
+        }
+        return query;
+    }
+    toQueryOptions(rq, state, ...callArgs) {
+        const opts = (callArgs[0] ?? {});
+        const { omitNullish, query: baseQuery, ...queryOptions } = opts;
+        const stateQuery = this.toQuery(state, { omitNullish });
+        const queryOptionsFn = rq.queryOptions.bind(rq);
+        return queryOptionsFn({
+            ...queryOptions,
+            query: {
+                ...baseQuery,
+                ...stateQuery,
+            },
+        });
+    }
+    get contractName() {
+        return this.contract.name;
+    }
+}
+export class NuqsContractHelper {
+    contract;
+    constructor(contract) {
+        this.contract = contract;
+    }
+    query(config) {
+        if (!this.contract.query) {
+            throw new Error(`nq(${this.contract.name}): Contract has no query schema. ` +
+                "@beignet/nuqs requires a query schema to bind URL state.");
+        }
+        return new NuqsQueryHelper(this.contract, config);
+    }
+}
+export function createNuqs() {
+    return function nq(contract) {
+        const resolvedContract = resolveContract(contract);
+        return new NuqsContractHelper(resolvedContract);
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,eAAe,GAChB,MAAM,yBAAyB,CAAC;AAKjC,OAAO,EAML,cAAc,GACf,MAAM,WAAW,CAAC;AA2DnB,MAAM,OAAO,eAAe;IAKhB;IACA;IAFV,YACU,QAAmB,EACnB,MAAgD;QADhD,aAAQ,GAAR,QAAQ,CAAW;QACnB,WAAM,GAAN,MAAM,CAA0C;IACvD,CAAC;IAEJ,QAAQ,CACN,UAA8C,EAAE;QAEhD,MAAM,EAAE,OAAO,EAAE,GAAG,WAAW,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QAChD,OAAO,cAAc,CAAC,OAAO,EAAE;YAC7B,GAAG,WAAW;YACd,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED,OAAO,CACL,KAA0B,EAC1B,OAEI,EAAE;QAEN,MAAM,EAAE,WAAW,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;QACpC,MAAM,KAAK,GAA4B,EAAE,CAAC;QAC1C,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,CAAC;QAEjE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;YACnC,IAAI,WAAW,IAAI,CAAC,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,CAAC;gBAAE,SAAS;YACrE,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACrB,CAAC;QAED,OAAO,KAA6C,CAAC;IACvD,CAAC;IAED,cAAc,CACZ,EAAuC,EACvC,KAA0B,EAC1B,GAAG,QAA6C;QAEhD,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAgC,CAAC;QAChE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,YAAY,EAAE,GAAG,IAAI,CAAC;QAChE,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;QACxD,MAAM,cAAc,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAEsB,CAAC;QAErE,OAAO,cAAc,CAAC;YACpB,GAAG,YAAY;YACf,KAAK,EAAE;gBACL,GAAI,SAAiD;gBACrD,GAAI,UAAkD;aACf;SACJ,CAAC,CAAC;IAC3C,CAAC;IAED,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC5B,CAAC;CACF;AAED,MAAM,OAAO,kBAAkB;IACT;IAApB,YAAoB,QAAmB;QAAnB,aAAQ,GAAR,QAAQ,CAAW;IAAG,CAAC;IAE3C,KAAK,CACH,MAAgD;QAEhD,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACb,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,mCAAmC;gBACzD,0DAA0D,CAC7D,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,eAAe,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACpD,CAAC;CACF;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,SAAS,EAAE,CAChB,QAAuB;QAEvB,MAAM,gBAAgB,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;QACnD,OAAO,IAAI,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;IAClD,CAAC,CAAC;AACJ,CAAC"}

package/dist/next/app.d.ts

@@ -0,0 +1,2 @@
+export { NuqsAdapter } from "nuqs/adapters/next/app";
+//# sourceMappingURL=app.d.ts.map

package/dist/next/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/next/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/next/app.js

@@ -0,0 +1,2 @@
+export { NuqsAdapter } from "nuqs/adapters/next/app";
+//# sourceMappingURL=app.js.map

package/dist/next/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/next/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,2 @@
+export { type inferParserType, type UrlKeys, type UseQueryStatesKeysMap, type UseQueryStatesOptions, type UseQueryStatesReturn, useQueryStates, } from "nuqs";
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,OAAO,EACZ,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,cAAc,GACf,MAAM,MAAM,CAAC"}

package/dist/runtime.js

@@ -0,0 +1,2 @@
+export { useQueryStates, } from "nuqs";
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,cAAc,GACf,MAAM,MAAM,CAAC"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@beignet/nuqs",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "nuqs integration for Beignet",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./next/app": {
+      "types": "./dist/next/app.d.ts",
+      "default": "./dist/next/app.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist coverage .turbo",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "biome check ."
+  },
+  "keywords": [
+    "contract",
+    "api",
+    "typescript",
+    "nuqs",
+    "search-params"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taylorbryant/beignet.git",
+    "directory": "packages/nuqs"
+  },
+  "author": "Taylor Bryant",
+  "homepage": "https://github.com/taylorbryant/beignet#readme",
+  "bugs": "https://github.com/taylorbryant/beignet/issues",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "nuqs": "^2.8.9",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@beignet/core": "*",
+    "@beignet/react-query": "*"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.13",
+    "@types/node": "^20.10.0",
+    "@types/react": "^19.0.0",
+    "nuqs": "^2.8.9",
+    "react": "^19.0.0",
+    "typescript": "^5.3.0",
+    "zod": "^4.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,167 @@
+import type { EndpointCallArgs, InferQuery } from "@beignet/core/client";
+import {
+  type ContractLike,
+  type HttpContractConfig,
+  type ResolveContract,
+  resolveContract,
+} from "@beignet/core/contracts";
+import type {
+  ContractUseQueryOptions,
+  ReactQueryContractHelper,
+} from "@beignet/react-query";
+import {
+  type inferParserType,
+  type UrlKeys,
+  type UseQueryStatesKeysMap,
+  type UseQueryStatesOptions,
+  type UseQueryStatesReturn,
+  useQueryStates,
+} from "./runtime";
+
+type QueryShape<TContract extends HttpContractConfig> = NonNullable<
+  InferQuery<TContract>
+>;
+
+type QueryRecord<TContract extends HttpContractConfig> =
+  QueryShape<TContract> extends Record<string, unknown>
+    ? QueryShape<TContract>
+    : never;
+
+type QueryKeys<TContract extends HttpContractConfig> =
+  keyof QueryRecord<TContract> & string;
+
+type QueryParsers<TContract extends HttpContractConfig> = Partial<{
+  [K in QueryKeys<TContract>]: UseQueryStatesKeysMap<{
+    [P in K]: Exclude<QueryRecord<TContract>[P], undefined>;
+  }>[K];
+}>;
+
+export type NuqsParserMap<TContract extends HttpContractConfig> =
+  QueryParsers<TContract>;
+
+export type NuqsState<TParsers extends UseQueryStatesKeysMap> =
+  inferParserType<TParsers>;
+
+type ContractQueryHookOptions<TParsers extends UseQueryStatesKeysMap> = Partial<
+  UseQueryStatesOptions<TParsers>
+>;
+
+type ContractQueryConfig<
+  TContract extends HttpContractConfig,
+  TParsers extends NuqsParserMap<TContract> & UseQueryStatesKeysMap,
+> = ContractQueryHookOptions<TParsers> & {
+  parsers: TParsers;
+};
+
+type HasRequiredKeys<T> = {
+  [K in keyof T]-?: Record<string, never> extends Pick<T, K> ? never : K;
+}[keyof T];
+
+type NuqsQueryOptionsRequiredInput<TContract extends HttpContractConfig> = Omit<
+  EndpointCallArgs<TContract>,
+  "query" | "rawBody" | "signal"
+>;
+
+type NuqsQueryOptions<TContract extends HttpContractConfig> = Omit<
+  ContractUseQueryOptions<TContract>,
+  "query"
+> & {
+  query?: EndpointCallArgs<TContract>["query"];
+  omitNullish?: boolean;
+};
+
+type NuqsQueryOptionsCallArgs<TContract extends HttpContractConfig> =
+  HasRequiredKeys<NuqsQueryOptionsRequiredInput<TContract>> extends never
+    ? [opts?: NuqsQueryOptions<TContract>]
+    : [opts: NuqsQueryOptions<TContract>];
+
+export class NuqsQueryHelper<
+  TContract extends HttpContractConfig,
+  TParsers extends NuqsParserMap<TContract> & UseQueryStatesKeysMap,
+> {
+  constructor(
+    private contract: TContract,
+    private config: ContractQueryConfig<TContract, TParsers>,
+  ) {}
+
+  useState(
+    options: ContractQueryHookOptions<TParsers> = {},
+  ): UseQueryStatesReturn<TParsers> {
+    const { parsers, ...baseOptions } = this.config;
+    return useQueryStates(parsers, {
+      ...baseOptions,
+      ...options,
+    });
+  }
+
+  toQuery(
+    state: NuqsState<TParsers>,
+    opts: {
+      omitNullish?: boolean;
+    } = {},
+  ): EndpointCallArgs<TContract>["query"] {
+    const { omitNullish = true } = opts;
+    const query: Record<string, unknown> = {};
+    const entries = Object.entries(state as Record<string, unknown>);
+
+    for (const [key, value] of entries) {
+      if (omitNullish && (value === null || value === undefined)) continue;
+      query[key] = value;
+    }
+
+    return query as EndpointCallArgs<TContract>["query"];
+  }
+
+  toQueryOptions(
+    rq: ReactQueryContractHelper<TContract>,
+    state: NuqsState<TParsers>,
+    ...callArgs: NuqsQueryOptionsCallArgs<TContract>
+  ): ReturnType<ReactQueryContractHelper<TContract>["queryOptions"]> {
+    const opts = (callArgs[0] ?? {}) as NuqsQueryOptions<TContract>;
+    const { omitNullish, query: baseQuery, ...queryOptions } = opts;
+    const stateQuery = this.toQuery(state, { omitNullish });
+    const queryOptionsFn = rq.queryOptions.bind(rq) as (
+      args: ContractUseQueryOptions<TContract>,
+    ) => ReturnType<ReactQueryContractHelper<TContract>["queryOptions"]>;
+
+    return queryOptionsFn({
+      ...queryOptions,
+      query: {
+        ...(baseQuery as Record<string, unknown> | undefined),
+        ...(stateQuery as Record<string, unknown> | undefined),
+      } as EndpointCallArgs<TContract>["query"],
+    } as ContractUseQueryOptions<TContract>);
+  }
+
+  get contractName(): string {
+    return this.contract.name;
+  }
+}
+
+export class NuqsContractHelper<TContract extends HttpContractConfig> {
+  constructor(private contract: TContract) {}
+
+  query<TParsers extends NuqsParserMap<TContract> & UseQueryStatesKeysMap>(
+    config: ContractQueryConfig<TContract, TParsers>,
+  ): NuqsQueryHelper<TContract, TParsers> {
+    if (!this.contract.query) {
+      throw new Error(
+        `nq(${this.contract.name}): Contract has no query schema. ` +
+          "@beignet/nuqs requires a query schema to bind URL state.",
+      );
+    }
+
+    return new NuqsQueryHelper(this.contract, config);
+  }
+}
+
+export function createNuqs() {
+  return function nq<TContractLike extends ContractLike>(
+    contract: TContractLike,
+  ): NuqsContractHelper<ResolveContract<TContractLike>> {
+    const resolvedContract = resolveContract(contract);
+    return new NuqsContractHelper(resolvedContract);
+  };
+}
+
+export type { UrlKeys };

package/src/next/app.ts

@@ -0,0 +1 @@
+export { NuqsAdapter } from "nuqs/adapters/next/app";

package/src/runtime.ts

@@ -0,0 +1,8 @@
+export {
+  type inferParserType,
+  type UrlKeys,
+  type UseQueryStatesKeysMap,
+  type UseQueryStatesOptions,
+  type UseQueryStatesReturn,
+  useQueryStates,
+} from "nuqs";