@nxgt/httpyz-query 0.1.0

package/README.md

@@ -0,0 +1,614 @@
+# @nxgt/httpyz-query
+
+[TanStack Query](https://tanstack.com/query) options for the calls of an
+[`@nxgt/httpyz`](https://www.npmjs.com/package/@nxgt/httpyz) client. Each
+function returns a plain options object, with a key that tells calls apart by
+what they send, and a `queryFn` that sends the call with the query's
+`signal`: a query TanStack cancels aborts its request.
+
+It adds no runtime of TanStack's, so any adapter takes the objects:
+`useQuery` in React or Vue, `createQuery` in Solid or Svelte, `injectQuery`
+in Angular.
+
+> **0.x.** The API is still settling.
+
+## Install
+
+```sh
+bun add @nxgt/httpyz @nxgt/httpyz-query @tanstack/react-query
+```
+
+| Peer | | |
+| --- | --- | --- |
+| `@nxgt/httpyz` | required | the client whose calls the queries send |
+| `@tanstack/query-core` | required | TanStack's types. Every adapter depends on it, so installing yours is enough |
+| `typescript` | required | `^6.0.3` |
+| `@nxgt/openapi-httpyz` | optional | only for [`@nxgt/httpyz-query/openapi`](#with-an-openapi-spec) |
+
+## Setup
+
+```ts
+import { createHttpClient } from '@nxgt/httpyz';
+import { createQueries } from '@nxgt/httpyz-query';
+
+export const http = createHttpClient({ baseUrl: 'https://api.example.com' });
+export const queries = createQueries(http);
+```
+
+| Option | Default | |
+| --- | --- | --- |
+| `scope` | none | put first in every key: two clients whose paths are the same keep their queries apart |
+
+## Subpaths
+
+| Import | What it has |
+| --- | --- |
+| `@nxgt/httpyz-query` | `createQueries`, for a client of `createHttpClient`, and the types |
+| `@nxgt/httpyz-query/openapi` | `createOpenApiQueries`, for a client bound to a spec by `@nxgt/openapi-httpyz` |
+
+## Queries
+
+`queryOptions` takes a call as the client's `request` does: the method, the
+path, then its options. The query resolves to the data of a 2xx reply, and
+fails with the client's `ReplyStatusError` on any other:
+
+```ts
+import { useQuery } from '@tanstack/react-query';
+import { z } from 'zod';
+import { queries } from './queries.js';
+
+const Employee = z.object({ id: z.int(), name: z.string() });
+const Problem = z.object({ title: z.string() });
+
+const { data } = useQuery({
+	...queries.queryOptions('get', '/employees/{id}', {
+		param: { id },
+		responses: { 200: Employee, 404: Problem },
+	}),
+	enabled: id !== undefined,
+});
+data?.name; // Employee: the 404 is the query's error
+```
+
+The key is `[method, path, input]`, after the `scope` when there is one.
+`input` holds what the call sends, `param`, `query`, `header` and its body, and
+`decode: false`, since that changes the data; it is left out when empty. The
+call options, `headers`, `timeout`, `signal`, are never in it. The key is
+tagged with the data, so `queryClient.getQueryData(options.queryKey)` is
+typed.
+
+## Cancelling
+
+TanStack aborts a query's `signal` when the query is cancelled, and when its
+last observer unmounts while it still runs. The call is sent with that
+signal, so it is aborted too: its request stops, not only its result. A
+`signal` in the call's own options still ends it, as does its `latest`.
+
+```ts
+await queryClient.cancelQueries({ queryKey: queries.queryKey('get', '/search') });
+```
+
+## Infinite queries
+
+`infiniteQueryOptions` takes the call's options, then how it pages:
+TanStack's own `initialPageParam` and `getNextPageParam`, and
+`pageParamName`, the query parameter each page's param is sent as. A `null`
+page param is left out, so the first page goes without it:
+
+```ts
+import { useInfiniteQuery } from '@tanstack/react-query';
+
+const { data, fetchNextPage } = useInfiniteQuery(
+	queries.infiniteQueryOptions(
+		'post',
+		'/employees/search',
+		{ json: { sort }, query: { first: 20 }, responses: { 200: EmployeePage } },
+		{
+			pageParamName: 'after',
+			initialPageParam: null as string | null,
+			getNextPageParam: (last) => last.cursor,
+		},
+	),
+);
+```
+
+Its key ends with `'infinite'`, apart from the plain query of the same call,
+whose data is one page rather than all of them.
+
+## Mutations
+
+`mutationOptions` takes the method and the path, and what every call shares,
+such as `responses`. Its `mutate()` takes what each call sends:
+
+```ts
+import { useMutation } from '@tanstack/react-query';
+
+const remove = useMutation({
+	...queries.mutationOptions('delete', '/employees/{id}', {
+		responses: { 204: null },
+	}),
+	onSuccess: () =>
+		queryClient.invalidateQueries({ queryKey: queries.queryKey('get', '/employees') }),
+});
+remove.mutate({ param: { id } });
+```
+
+`mutate()` takes nothing when the path has no `{name}`s to fill.
+
+## Keys and filters
+
+`queryKey(method, path?, input?)` is a key, or the start of one: TanStack
+matches a filter's key as a prefix, so every query of a path matches,
+whatever its `param`:
+
+```ts
+queryClient.invalidateQueries({ queryKey: queries.queryKey('get', '/employees/{id}') });
+queryClient.removeQueries({ queryKey: queries.queryKey('get') }); // every GET
+```
+
+## With an OpenAPI spec
+
+`@nxgt/httpyz-query/openapi` does the same for a client bound to a
+generated spec by
+[`@nxgt/openapi-httpyz`](https://www.npmjs.com/package/@nxgt/openapi-httpyz),
+an optional peer. It takes the bound client, and reads the spec from the
+`operations` the client was bound to, as the client does:
+
+```ts
+import { createOpenApiQueries } from '@nxgt/httpyz-query/openapi';
+import { api } from './api.js'; // createOpenApiClient(http, operations)
+
+export const queries = createOpenApiQueries(api);
+
+// As api.get() takes it: the path, the input, then the init
+useQuery(queries.queryOptions('get', '/employees/{id}', { param: { id } }));
+useQuery(queries.queryOptions('get', '/health'));
+
+useInfiniteQuery(
+	queries.infiniteQueryOptions(
+		'post',
+		'/employees/search',
+		{ json: { sort }, query: { first: 20 } },
+		{
+			pageParamName: 'after',
+			initialPageParam: null as string | null,
+			getNextPageParam: (last) => last.cursor,
+		},
+	),
+);
+
+const remove = useMutation(queries.mutationOptions('delete', '/employees/{id}'));
+remove.mutate({ param: { id } });
+```
+
+- Every call is typed by the spec, as the bound client's are: the method, one
+  the spec has an operation for, the path, the input, and the data, a 2xx
+  reply's, decoded when the client decodes.
+- The key holds the input, header parameters included, and never the init.
+- `pageParamName` is one of the operation's query parameters.
+- `mutate()` takes the operation's input; `mutationOptions`' third argument
+  is the init every call shares.
+
+Coming from `openapi-react-query`: `$api.queryOptions('get', path, { params:
+{ path, query }, body })` becomes `queries.queryOptions('get', path, { param,
+query, json })`, and `$api.useQuery(...)` becomes
+`useQuery(queries.queryOptions(...))`.
+
+## API
+
+### `@nxgt/httpyz-query`
+
+#### Functions
+
+##### `createQueries`
+
+```ts
+function createQueries(http: HttpClient, options?: QueriesOptions): HttpQueries;
+```
+
+The options objects for the calls of `http`, a client of `createHttpClient`.
+Its calls go through `http.request`, so the client's middleware, retries and
+timeouts apply. See [Setup](#setup).
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `http` | `HttpClient` | | the client whose calls the queries send |
+| `options.scope` | `string` | none | put first in every key |
+
+Returns an [`HttpQueries`](#httpqueries). Throws nothing.
+
+#### The queries object
+
+##### `queryOptions`
+
+```ts
+queryOptions<Path extends string, R extends Responses | undefined = undefined, Decoded extends boolean = true>(
+	method: Method,
+	path: Path,
+	...args: RequestArgs<Path, R, Decoded> // [options?], or [options] when the path has {name}s
+): HttpQueryOptions<QueryData<R, Decoded>>;
+```
+
+The options of a query of one call. See [Queries](#queries).
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `method` | `Method` | | `'get'`, `'post'`, `'query'`… |
+| `path` | `Path` | | the path, `{name}`s unfilled: `'/employees/{id}'` |
+| `options` | `RequestOptions<Path, R, Decoded>` | | what the client's `request` takes: `param`, `query`, a body, `responses`, `decode`, and call options such as `signal` or `latest`. Required when the path has `{name}`s |
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `queryKey` | `HttpQueryKey<Data>` | `[scope?, method, path, input?]`, tagged with the data |
+| `queryFn` | `({ signal }) => Promise<Data>` | sends the call with the query's `signal`, joined with the options' own |
+
+The `queryFn` resolves to the data of a 2xx reply, and rejects with a
+`ReplyStatusError` on any other, or with whatever the call throws:
+`UndeclaredStatusError`, `ValidationError`, `TimeoutError`, an abort.
+
+##### `infiniteQueryOptions`
+
+```ts
+infiniteQueryOptions<Path extends string, PageParam, R extends Responses | undefined = undefined, Decoded extends boolean = true>(
+	method: Method,
+	path: Path,
+	options: RequestOptions<Path, R, Decoded>,
+	paging: Paging<QueryData<R, Decoded>, PageParam>,
+): HttpInfiniteQueryOptions<QueryData<R, Decoded>, PageParam>;
+```
+
+The options of an infinite query: each page is the call sent with its
+`pageParam` as the query parameter `pageParamName`, left out when `null` or
+`undefined`. See [Infinite queries](#infinite-queries).
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `method` | `Method` | | as `queryOptions` |
+| `path` | `Path` | | as `queryOptions` |
+| `options` | `RequestOptions<Path, R, Decoded>` | | as `queryOptions`, always given. Its `query` may be an object or a `URLSearchParams` |
+| `paging` | [`Paging`](#paging) | | `pageParamName`, and TanStack's paging options |
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `queryKey` | `HttpQueryKey<InfiniteData<Data, PageParam>>` | the call's key, then `'infinite'` |
+| `queryFn` | `({ signal, pageParam }) => Promise<Data>` | sends one page |
+| `initialPageParam` | `PageParam` | from `paging` |
+| `getNextPageParam` | `GetNextPageParamFunction<PageParam, Data>` | from `paging` |
+| `getPreviousPageParam` | `GetPreviousPageParamFunction<PageParam, Data>` | from `paging`, when given |
+| `maxPages` | `number` | from `paging`, when given |
+
+Each page rejects as a `queryOptions` query does.
+
+##### `mutationOptions`
+
+```ts
+mutationOptions<Path extends string, R extends Responses | undefined = undefined, Decoded extends boolean = true>(
+	method: Method,
+	path: Path,
+	options?: CallOptions & ReplyOptions<R, Decoded>,
+): HttpMutationOptions<Path, QueryData<R, Decoded>>;
+```
+
+The options of a mutation of one call, whose `mutate()` takes what each call
+sends. See [Mutations](#mutations).
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `method` | `Method` | | as `queryOptions` |
+| `path` | `Path` | | as `queryOptions` |
+| `options` | `CallOptions & ReplyOptions<R, Decoded>` | none | what every call shares: `responses`, `validate`, `decode`, `headers`, `timeout`… |
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `mutationKey` | `readonly unknown[]` | `[scope?, method, path]` |
+| `mutationFn` | `(variables: MutationVariables<Path>) => Promise<Data>` | sends the call with `options`, then `variables` over them. `variables` may be left out when the path has no `{name}`s |
+
+The `mutationFn` rejects as a `queryOptions` query does. It is sent with no
+signal of TanStack's: a mutation is not cancelled.
+
+##### `queryKey`
+
+```ts
+queryKey(method: Method, path?: string, input?: KeyInput): readonly unknown[];
+```
+
+A key, or the start of one, for a filter: `[scope?, method, path?, input?]`,
+built as the options' keys are. It is not tagged with any data. See
+[Keys and filters](#keys-and-filters).
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `method` | `Method` | | the method |
+| `path` | `string` | none | the path, `{name}`s unfilled |
+| `input` | [`KeyInput`](#keyinput) | none | what the calls send: `param`, `query`, a body |
+
+#### Types
+
+##### `HttpQueries`
+
+What `createQueries` returns: [`queryOptions`](#queryoptions),
+[`infiniteQueryOptions`](#infinitequeryoptions),
+[`mutationOptions`](#mutationoptions) and [`queryKey`](#querykey).
+
+##### `QueriesOptions`
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `scope` | `string` | optional: put first in every key, `'catalog'` |
+
+The second argument of `createQueries` and `createOpenApiQueries`.
+
+##### `HttpQueryOptions`
+
+```ts
+interface HttpQueryOptions<Data> {
+	readonly queryKey: HttpQueryKey<Data>;
+	readonly queryFn: (context: { readonly signal: AbortSignal }) => Promise<Data>;
+}
+```
+
+What `queryOptions` returns, in both entry points.
+
+##### `HttpInfiniteQueryOptions`
+
+```ts
+interface HttpInfiniteQueryOptions<Data, PageParam> extends Omit<Paging<Data, PageParam>, 'pageParamName'> {
+	readonly queryKey: HttpQueryKey<InfiniteData<Data, PageParam>>;
+	readonly queryFn: (context: { readonly signal: AbortSignal; readonly pageParam: PageParam }) => Promise<Data>;
+}
+```
+
+What `infiniteQueryOptions` returns, in both entry points.
+
+##### `HttpMutationOptions`
+
+```ts
+interface HttpMutationOptions<Path extends string, Data> {
+	readonly mutationKey: readonly unknown[];
+	// MutationVariables<Path> | void when the path has no {name}s
+	readonly mutationFn: (variables: MutationVariables<Path>) => Promise<Data>;
+}
+```
+
+What `mutationOptions` of `createQueries` returns.
+
+##### `Paging`
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `pageParamName` | `string` | the query parameter each page's `pageParam` is sent as: `'after'`, `'page'` |
+| `initialPageParam` | `PageParam` | the first page's param |
+| `getNextPageParam` | `GetNextPageParamFunction<PageParam, Data>` | the next page's param, from the last page |
+| `getPreviousPageParam` | `GetPreviousPageParamFunction<PageParam, Data>` | optional: the previous page's param |
+| `maxPages` | `number` | optional: how many pages TanStack keeps |
+
+The fourth argument of `infiniteQueryOptions`. In `./openapi`,
+`pageParamName` is narrowed to the operation's query parameters.
+
+##### `KeyInput`
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `param` | `{ readonly [name: string]: unknown }` | the path's parameters |
+| `query` | `QueryInput` | the query: an object, or a `URLSearchParams` |
+| `json` | `unknown` | a JSON body |
+| `form` | `unknown` | a form body |
+| `text` | `string` | a text body |
+| `body` | `unknown` | a raw body |
+
+What `queryKey` takes as its `input`, every field optional.
+
+##### `HttpQueryKey`
+
+A key tagged with its data, `DataTag<readonly unknown[], Data>`, which is
+what types `queryClient.getQueryData(key)`.
+
+```ts
+const key: HttpQueryKey<Employee> = queries.queryOptions('get', '/employees/{id}', options).queryKey;
+```
+
+##### `QueryData`
+
+The data of a call's 2xx replies, from its `responses` and whether it
+decodes.
+
+```ts
+type Data = QueryData<{ 200: typeof Employee; 404: typeof Problem }, true>; // z.output<typeof Employee>
+```
+
+##### `MutationVariables`
+
+What `mutate()` takes: what the call to `Path` sends, `RequestInput<Path>`,
+and its `CallOptions`.
+
+```ts
+type Variables = MutationVariables<'/employees/{id}'>; // { param: { id }, query?, json?… } & CallOptions
+```
+
+### `@nxgt/httpyz-query/openapi`
+
+#### Functions
+
+##### `createOpenApiQueries`
+
+```ts
+function createOpenApiQueries<Ops extends OperationsShape<Ops>, Routes, Decoded extends boolean>(
+	api: OpenApiClient<Ops, Routes, Decoded>,
+	options?: QueriesOptions,
+): OpenApiQueries<Ops, Routes, Decoded>;
+```
+
+The options objects for the operations of `api`, a client of
+`createOpenApiClient`, whose types it infers. It reads `api.operations` to
+tell an operation's input from its init, as the client does: an operation
+that takes nothing is called with its init alone. The calls are the client's
+own, `api.get(path, …)` and the other methods. See
+[With an OpenAPI spec](#with-an-openapi-spec).
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `api` | `OpenApiClient<Ops, Routes, Decoded>` | | the bound client |
+| `options.scope` | `string` | none | put first in every key |
+
+Returns an [`OpenApiQueries`](#openapiqueries). Throws nothing itself; its
+members throw an `Error`, `The spec has no GET /x operation`, for a method
+and path the spec has no operation at, which the types already refuse.
+
+#### The queries object
+
+##### `queryOptions`
+
+```ts
+queryOptions<M extends MethodsOf<Routes>, P extends PathsOf<Routes, M>>(
+	method: M,
+	path: P,
+	...args: Args<Ops, IdOf<Ops, Routes, M, P>> // [input, init?], or [init?] for an operation that takes nothing
+): HttpQueryOptions<OperationData<Ops, IdOf<Ops, Routes, M, P>, Decoded>>;
+```
+
+The options of a query of the operation at `method` and `path`, taking what
+`api[method](path, …)` takes.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `method` | `MethodsOf<Routes>` | | a method the spec has an operation for |
+| `path` | `PathsOf<Routes, M>` | | a path with an operation for that method |
+| `input` | the operation's input | | `param`, `query`, `header`, a body. Absent for an operation that takes nothing |
+| `init` | `OperationInit` | none | the core client's call options: `signal`, `timeout`, `headers`, `latest`… |
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `queryKey` | `HttpQueryKey<Data>` | `[scope?, method, path, input?]`: the input, never the init |
+| `queryFn` | `({ signal }) => Promise<Data>` | calls the operation with the query's `signal`, joined with the init's own |
+
+The `queryFn` resolves to the data of a 2xx reply, and rejects with a
+`ReplyStatusError` on any other, or with whatever the call throws.
+`queryOptions` throws at once for an operation the spec does not have.
+
+##### `infiniteQueryOptions`
+
+```ts
+infiniteQueryOptions<M extends MethodsOf<Routes>, P extends PathsOf<Routes, M>, PageParam>(
+	method: M,
+	path: P,
+	input: Ops[IdOf<Ops, Routes, M, P>]['args'][0],
+	paging: Omit<Paging<Data, PageParam>, 'pageParamName'> & { readonly pageParamName: QueryNames<Input> },
+	init?: OperationInit,
+): HttpInfiniteQueryOptions<Data, PageParam>;
+// Input: Ops[IdOf<Ops, Routes, M, P>]['args'][0]; Data: OperationData<Ops, IdOf<Ops, Routes, M, P>, Decoded>
+```
+
+The options of an infinite query of an operation, each page sent with its
+`pageParam` as one of the operation's query parameters.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `method` | `MethodsOf<Routes>` | | as `queryOptions` |
+| `path` | `PathsOf<Routes, M>` | | as `queryOptions` |
+| `input` | the operation's input | | as `queryOptions`, always given |
+| `paging` | [`Paging`](#paging) | | `pageParamName` is one of the input's query parameters |
+| `init` | `OperationInit` | none | the call options every page is sent with |
+
+Returns the fields of [`infiniteQueryOptions`](#infinitequeryoptions) above.
+A page of an operation the spec does not have rejects when it is fetched.
+
+##### `mutationOptions`
+
+```ts
+mutationOptions<M extends MethodsOf<Routes>, P extends PathsOf<Routes, M>>(
+	method: M,
+	path: P,
+	init?: OperationInit,
+): OpenApiMutationOptions<
+	OperationVariables<Ops[IdOf<Ops, Routes, M, P>]['args']>,
+	OperationData<Ops, IdOf<Ops, Routes, M, P>, Decoded>
+>;
+```
+
+The options of a mutation of an operation, whose `mutate()` takes its input.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `method` | `MethodsOf<Routes>` | | as `queryOptions` |
+| `path` | `PathsOf<Routes, M>` | | as `queryOptions` |
+| `init` | `OperationInit` | none | the call options every call shares |
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `mutationKey` | `readonly unknown[]` | `[scope?, method, path]` |
+| `mutationFn` | `(variables: OperationVariables<Args>) => Promise<Data>` | calls the operation with `variables` as its input, and `init` |
+
+The `mutationFn` rejects as a query does, and is sent with no signal of
+TanStack's. `mutationOptions` throws at once for an operation the spec does
+not have.
+
+##### `queryKey`
+
+```ts
+queryKey(method: Method, path?: string, input?: KeyInput): readonly unknown[];
+```
+
+As [`queryKey`](#querykey) of `createQueries`: any method and path, untyped
+by the spec.
+
+#### Types
+
+`QueriesOptions`, `HttpQueryOptions`, `HttpInfiniteQueryOptions`, `Paging`
+and `KeyInput` are exported from `@nxgt/httpyz-query`.
+
+##### `OpenApiQueries`
+
+What `createOpenApiQueries` returns: [`queryOptions`](#queryoptions-1),
+[`infiniteQueryOptions`](#infinitequeryoptions-1),
+[`mutationOptions`](#mutationoptions-1) and [`queryKey`](#querykey-1), typed
+by the client's `Ops`, `Routes` and `Decoded`.
+
+##### `OpenApiMutationOptions`
+
+```ts
+interface OpenApiMutationOptions<Variables, Data> {
+	readonly mutationKey: readonly unknown[];
+	readonly mutationFn: (variables: Variables) => Promise<Data>;
+}
+```
+
+What `mutationOptions` of `createOpenApiQueries` returns.
+
+##### `OperationData`
+
+The data of an operation's 2xx replies, decoded when `Decoded` is `true`.
+
+```ts
+type Employee = OperationData<ClientOperations, 'getEmployee', false>;
+```
+
+##### `OperationVariables`
+
+What `mutate()` takes, from an operation's arguments: `void` when it takes
+nothing, its input, or its input or nothing when none of it is required.
+
+```ts
+type Variables = OperationVariables<ClientOperations['deleteEmployee']['args']>; // { param: { id: number } }
+```
+
+##### `QueryNames`
+
+The names of the query parameters of an operation's input: what
+`pageParamName` may be.
+
+```ts
+type Names = QueryNames<{ query?: { first?: number; after?: string } }>; // 'first' | 'after'
+```
+
+## Traps
+
+- **A binary body is not told apart in a key.** A `Blob` or a stream hashes
+  as `{}`: give such a query a `queryKey` of your own after the spread.
+- **A status the call does not declare fails differently.** A declared
+  non-2xx reply fails the query with a `ReplyStatusError`, but one missing
+  from `responses` throws the client's `UndeclaredStatusError` first: declare
+  every status the API replies with.
+- **`queryKey()` is not tagged.** `queryClient.getQueryData(queries.queryKey(...))`
+  is `unknown`: read the cache with the options' own `queryKey`.
+- **Set `initialPageParam`'s type.** `null` alone types every page param as
+  `null`: `null as string | null`.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createQueries } from './queries/create-queries';
+export type { HttpInfiniteQueryOptions, HttpMutationOptions, HttpQueries, HttpQueryKey, HttpQueryOptions, KeyInput, MutationVariables, Paging, QueriesOptions, QueryData, } from './queries/types';
+//# 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,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,YAAY,EACX,wBAAwB,EACxB,mBAAmB,EACnB,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,QAAQ,EACR,iBAAiB,EACjB,MAAM,EACN,cAAc,EACd,SAAS,GACT,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,87 @@
+// src/queries/create-queries.ts
+import { ok } from "@nxgt/httpyz";
+
+// src/key/key.ts
+var joined = (given, query) => given ? AbortSignal.any([given, query]) : query;
+var hashable = (value) => value instanceof URLSearchParams || typeof FormData !== "undefined" && value instanceof FormData ? [...value.entries()] : value;
+var PARTS = [
+  "param",
+  "query",
+  "header",
+  "json",
+  "form",
+  "text",
+  "body"
+];
+function keyed(input) {
+  if (!input)
+    return;
+  const given = input;
+  const key = {};
+  for (const part of PARTS) {
+    if (given[part] !== undefined)
+      key[part] = hashable(given[part]);
+  }
+  if (given.decode === false)
+    key.decode = false;
+  return Object.keys(key).length > 0 ? key : undefined;
+}
+function keyOf(scope, method, path, input) {
+  const key = scope === undefined ? [method] : [scope, method];
+  if (path !== undefined)
+    key.push(path);
+  const rest = keyed(input);
+  if (rest !== undefined)
+    key.push(rest);
+  return key;
+}
+function paged(input, name, pageParam) {
+  const given = input?.query;
+  if (given instanceof URLSearchParams) {
+    const query = new URLSearchParams(given);
+    if (pageParam === null || pageParam === undefined)
+      query.delete(name);
+    else
+      query.set(name, String(pageParam));
+    return { ...input, query };
+  }
+  return {
+    ...input,
+    query: { ...given, [name]: pageParam }
+  };
+}
+
+// src/queries/create-queries.ts
+function createQueries(http, { scope } = {}) {
+  const send = http.request;
+  const queryKey = (method, path, input) => keyOf(scope, method, path, input);
+  const call = (method, path, options, signal) => send(method, path, {
+    ...options,
+    signal: joined(options?.signal, signal)
+  }).then(ok);
+  return {
+    queryKey,
+    queryOptions: (method, path, options) => ({
+      queryKey: queryKey(method, path, options),
+      queryFn: ({ signal }) => call(method, path, options, signal)
+    }),
+    infiniteQueryOptions: (method, path, options, { pageParamName, ...paging }) => ({
+      ...paging,
+      queryKey: [...queryKey(method, path, options), "infinite"],
+      queryFn: ({
+        signal,
+        pageParam
+      }) => call(method, path, paged(options, pageParamName, pageParam), signal)
+    }),
+    mutationOptions: (method, path, options) => ({
+      mutationKey: queryKey(method, path),
+      mutationFn: (variables) => send(method, path, { ...options, ...variables || {} }).then(ok)
+    })
+  };
+}
+export {
+  createQueries
+};
+
+//# debugId=E5A4FC415731130364756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["../src/queries/create-queries.ts", "../src/key/key.ts"],
+  "sourcesContent": [
+    "/**\n * `createQueries`: TanStack Query options for the calls of a client of\n * `createHttpClient`. It adds no runtime of TanStack's: each function returns\n * a plain object, whose `queryFn` sends the call with the query's `signal`.\n */\nimport { type HttpClient, type Method, ok } from '@nxgt/httpyz';\nimport { joined, keyOf, paged } from '../key/key';\nimport type { HttpQueries, KeyInput, Paging, QueriesOptions } from './types';\n\ntype Send = (\n\tmethod: Method,\n\tpath: string,\n\toptions: object,\n) => Promise<{ readonly status: number; readonly data: unknown }>;\n\ntype Options = KeyInput & { readonly signal?: AbortSignal | null };\n\n/**\n * TanStack Query options for the calls of `http`.\n *\n * ```ts\n * const queries = createQueries(http);\n * const { data } = useQuery(\n *   queries.queryOptions('get', '/items/{id}', { param: { id }, responses: { 200: Item } }),\n * );\n * ```\n */\nexport function createQueries(\n\thttp: HttpClient,\n\t{ scope }: QueriesOptions = {},\n): HttpQueries {\n\tconst send = http.request as unknown as Send;\n\tconst queryKey = (method: Method, path?: string, input?: KeyInput) =>\n\t\tkeyOf(scope, method, path, input);\n\tconst call = (\n\t\tmethod: Method,\n\t\tpath: string,\n\t\toptions: Options | undefined,\n\t\tsignal: AbortSignal,\n\t) =>\n\t\tsend(method, path, {\n\t\t\t...options,\n\t\t\tsignal: joined(options?.signal, signal),\n\t\t}).then(ok);\n\n\treturn {\n\t\tqueryKey,\n\t\tqueryOptions: (method: Method, path: string, options?: Options) => ({\n\t\t\tqueryKey: queryKey(method, path, options),\n\t\t\tqueryFn: ({ signal }: { signal: AbortSignal }) =>\n\t\t\t\tcall(method, path, options, signal),\n\t\t}),\n\t\tinfiniteQueryOptions: (\n\t\t\tmethod: Method,\n\t\t\tpath: string,\n\t\t\toptions: Options,\n\t\t\t{ pageParamName, ...paging }: Paging<unknown, unknown>,\n\t\t) => ({\n\t\t\t...paging,\n\t\t\t// Apart from the query of the same call, whose data is one page, not all of them.\n\t\t\tqueryKey: [...queryKey(method, path, options), 'infinite'],\n\t\t\tqueryFn: ({\n\t\t\t\tsignal,\n\t\t\t\tpageParam,\n\t\t\t}: {\n\t\t\t\tsignal: AbortSignal;\n\t\t\t\tpageParam: unknown;\n\t\t\t}) =>\n\t\t\t\tcall(method, path, paged(options, pageParamName, pageParam), signal),\n\t\t}),\n\t\tmutationOptions: (method: Method, path: string, options?: object) => ({\n\t\t\tmutationKey: queryKey(method, path),\n\t\t\tmutationFn: (variables: object | undefined) =>\n\t\t\t\tsend(method, path, { ...options, ...(variables || {}) }).then(ok),\n\t\t}),\n\t} as unknown as HttpQueries;\n}\n",
+    "/** What the keys and calls of both entry points share. */\n\n/** Both signals: the call ends on either. */\nexport const joined = (\n\tgiven: AbortSignal | null | undefined,\n\tquery: AbortSignal,\n): AbortSignal => (given ? AbortSignal.any([given, query]) : query);\n\n/** A value TanStack hashes as it is: a `URLSearchParams` or `FormData` as its entries. */\nconst hashable = (value: unknown): unknown =>\n\tvalue instanceof URLSearchParams ||\n\t(typeof FormData !== 'undefined' && value instanceof FormData)\n\t\t? [...value.entries()]\n\t\t: value;\n\n/** The parts of an input that tell two calls to one path apart. */\nconst PARTS = [\n\t'param',\n\t'query',\n\t'header',\n\t'json',\n\t'form',\n\t'text',\n\t'body',\n] as const;\n\n/** What tells two calls to one path apart: what they send, and `decode: false`. */\nfunction keyed(input: object | undefined): object | undefined {\n\tif (!input) return undefined;\n\tconst given = input as { readonly [part: string]: unknown };\n\tconst key: Record<string, unknown> = {};\n\tfor (const part of PARTS) {\n\t\tif (given[part] !== undefined) key[part] = hashable(given[part]);\n\t}\n\tif (given.decode === false) key.decode = false;\n\treturn Object.keys(key).length > 0 ? key : undefined;\n}\n\n/** A key, or the start of one: `[scope?, method, path?, input?]`. */\nexport function keyOf(\n\tscope: string | undefined,\n\tmethod: string,\n\tpath?: string,\n\tinput?: object,\n): unknown[] {\n\tconst key: unknown[] = scope === undefined ? [method] : [scope, method];\n\tif (path !== undefined) key.push(path);\n\tconst rest = keyed(input);\n\tif (rest !== undefined) key.push(rest);\n\treturn key;\n}\n\n/** `input` with `pageParam` as its query parameter `name`: left out when `null`. */\nexport function paged<Input extends { readonly query?: unknown }>(\n\tinput: Input | undefined,\n\tname: string,\n\tpageParam: unknown,\n): Input {\n\tconst given = input?.query;\n\tif (given instanceof URLSearchParams) {\n\t\tconst query = new URLSearchParams(given);\n\t\tif (pageParam === null || pageParam === undefined) query.delete(name);\n\t\telse query.set(name, String(pageParam));\n\t\treturn { ...input, query } as Input;\n\t}\n\treturn {\n\t\t...input,\n\t\tquery: { ...(given as object | undefined), [name]: pageParam },\n\t} as Input;\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "E5A4FC415731130364756E2164756E21",
+  "names": []
+}

package/dist/key/key.d.ts

@@ -0,0 +1,10 @@
+/** What the keys and calls of both entry points share. */
+/** Both signals: the call ends on either. */
+export declare const joined: (given: AbortSignal | null | undefined, query: AbortSignal) => AbortSignal;
+/** A key, or the start of one: `[scope?, method, path?, input?]`. */
+export declare function keyOf(scope: string | undefined, method: string, path?: string, input?: object): unknown[];
+/** `input` with `pageParam` as its query parameter `name`: left out when `null`. */
+export declare function paged<Input extends {
+    readonly query?: unknown;
+}>(input: Input | undefined, name: string, pageParam: unknown): Input;
+//# sourceMappingURL=key.d.ts.map

package/dist/key/key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../../src/key/key.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAE1D,6CAA6C;AAC7C,eAAO,MAAM,MAAM,GAClB,OAAO,WAAW,GAAG,IAAI,GAAG,SAAS,EACrC,OAAO,WAAW,KAChB,WAAgE,CAAC;AAgCpE,qEAAqE;AACrE,wBAAgB,KAAK,CACpB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,GACZ,OAAO,EAAE,CAMX;AAED,oFAAoF;AACpF,wBAAgB,KAAK,CAAC,KAAK,SAAS;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,EAC/D,KAAK,EAAE,KAAK,GAAG,SAAS,EACxB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,OAAO,GAChB,KAAK,CAYP"}

package/dist/openapi/create-openapi-queries.d.ts

@@ -0,0 +1,15 @@
+import type { OpenApiClient, OperationsShape } from '@nxgt/openapi-httpyz';
+import type { QueriesOptions } from '../queries/types';
+import type { OpenApiQueries } from './types';
+/**
+ * TanStack Query options for the operations of `api`. The client's own
+ * `operations` tell an operation's input from its init, as they do for its
+ * calls: one that takes nothing is called with its init alone.
+ *
+ * ```ts
+ * const queries = createOpenApiQueries(api);
+ * const { data } = useQuery(queries.queryOptions('get', '/employees/{id}', { param: { id } }));
+ * ```
+ */
+export declare function createOpenApiQueries<Ops extends OperationsShape<Ops>, Routes, Decoded extends boolean>(api: OpenApiClient<Ops, Routes, Decoded>, { scope }?: QueriesOptions): OpenApiQueries<Ops, Routes, Decoded>;
+//# sourceMappingURL=create-openapi-queries.d.ts.map

package/dist/openapi/create-openapi-queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-openapi-queries.d.ts","sourceRoot":"","sources":["../../src/openapi/create-openapi-queries.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACX,aAAa,EAEb,eAAe,EAEf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAoB,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAO9C;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CACnC,GAAG,SAAS,eAAe,CAAC,GAAG,CAAC,EAChC,MAAM,EACN,OAAO,SAAS,OAAO,EAEvB,GAAG,EAAE,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EACxC,EAAE,KAAK,EAAE,GAAE,cAAmB,GAC5B,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,CAwFtC"}

package/dist/openapi/types.d.ts

@@ -0,0 +1,42 @@
+/** The options `createOpenApiQueries()` returns, typed by the generated spec. */
+import type { Method, Success } from '@nxgt/httpyz';
+import type { Args, IdOf, MethodsOf, OperationInit, OperationReply, OperationsShape, PathsOf } from '@nxgt/openapi-httpyz';
+import type { HttpInfiniteQueryOptions, HttpQueryOptions, KeyInput, Paging } from '../queries/types';
+/** Each reply's `data`. */
+type DataOf<Reply> = Reply extends {
+    readonly data: infer Data;
+} ? Data : never;
+/** What a query of an operation resolves to: the data of its 2xx replies. */
+export type OperationData<Ops extends OperationsShape<Ops>, K extends keyof Ops, Decoded extends boolean> = DataOf<Success<OperationReply<Ops, K, Decoded>>>;
+/** An operation's input: `void` when it takes none, and may be left out when nothing in it is required. */
+export type OperationVariables<Args> = Args extends readonly [] ? void : Args extends readonly [infer Input] ? Input : Args extends readonly [(infer Input)?] ? // biome-ignore lint/suspicious/noConfusingVoidType: void, not undefined, is what lets `mutate()` be called with nothing
+Input | void : never;
+/** The query parameters of an operation's input. */
+export type QueryNames<Input> = Input extends {
+    readonly query?: infer Query;
+} ? keyof NonNullable<Query> & string : never;
+export interface OpenApiMutationOptions<Variables, Data> {
+    readonly mutationKey: readonly unknown[];
+    readonly mutationFn: (variables: Variables) => Promise<Data>;
+}
+export type OpenApiQueries<Ops extends OperationsShape<Ops>, Routes, Decoded extends boolean> = {
+    /**
+     * A query of the operation at a path, taking what `api.get(path, ...)`
+     * takes. It resolves to the data of a 2xx reply, and throws a
+     * `ReplyStatusError` for any other.
+     */
+    queryOptions<M extends MethodsOf<Routes>, P extends PathsOf<Routes, M>>(method: M, path: P, ...args: Args<Ops, IdOf<Ops, Routes, M, P>>): HttpQueryOptions<OperationData<Ops, IdOf<Ops, Routes, M, P>, Decoded>>;
+    /** An infinite query of an operation: each page sent with its `pageParam` as one of its query parameters. */
+    infiniteQueryOptions<M extends MethodsOf<Routes>, P extends PathsOf<Routes, M>, PageParam>(method: M, path: P, input: Ops[IdOf<Ops, Routes, M, P>]['args'][0], paging: Omit<Paging<OperationData<Ops, IdOf<Ops, Routes, M, P>, Decoded>, PageParam>, 'pageParamName'> & {
+        readonly pageParamName: QueryNames<Ops[IdOf<Ops, Routes, M, P>]['args'][0]>;
+    }, init?: OperationInit): HttpInfiniteQueryOptions<OperationData<Ops, IdOf<Ops, Routes, M, P>, Decoded>, PageParam>;
+    /**
+     * A mutation of the operation at a path, whose `mutate()` takes its input.
+     * `init` holds what every call shares.
+     */
+    mutationOptions<M extends MethodsOf<Routes>, P extends PathsOf<Routes, M>>(method: M, path: P, init?: OperationInit): OpenApiMutationOptions<OperationVariables<Ops[IdOf<Ops, Routes, M, P>]['args']>, OperationData<Ops, IdOf<Ops, Routes, M, P>, Decoded>>;
+    /** A key, or the start of one, for a filter: `queries.queryKey('get', '/items')`. */
+    queryKey(method: Method, path?: string, input?: KeyInput): readonly unknown[];
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/openapi/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/openapi/types.ts"],"names":[],"mappings":"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"}

package/dist/openapi.d.ts

@@ -0,0 +1,3 @@
+export { createOpenApiQueries } from './openapi/create-openapi-queries';
+export type { OpenApiMutationOptions, OpenApiQueries, OperationData, OperationVariables, QueryNames, } from './openapi/types';
+//# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,YAAY,EACX,sBAAsB,EACtB,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,UAAU,GACV,MAAM,iBAAiB,CAAC"}

package/dist/openapi.js

@@ -0,0 +1,105 @@
+// src/openapi/create-openapi-queries.ts
+import { ok } from "@nxgt/httpyz";
+
+// src/key/key.ts
+var joined = (given, query) => given ? AbortSignal.any([given, query]) : query;
+var hashable = (value) => value instanceof URLSearchParams || typeof FormData !== "undefined" && value instanceof FormData ? [...value.entries()] : value;
+var PARTS = [
+  "param",
+  "query",
+  "header",
+  "json",
+  "form",
+  "text",
+  "body"
+];
+function keyed(input) {
+  if (!input)
+    return;
+  const given = input;
+  const key = {};
+  for (const part of PARTS) {
+    if (given[part] !== undefined)
+      key[part] = hashable(given[part]);
+  }
+  if (given.decode === false)
+    key.decode = false;
+  return Object.keys(key).length > 0 ? key : undefined;
+}
+function keyOf(scope, method, path, input) {
+  const key = scope === undefined ? [method] : [scope, method];
+  if (path !== undefined)
+    key.push(path);
+  const rest = keyed(input);
+  if (rest !== undefined)
+    key.push(rest);
+  return key;
+}
+function paged(input, name, pageParam) {
+  const given = input?.query;
+  if (given instanceof URLSearchParams) {
+    const query = new URLSearchParams(given);
+    if (pageParam === null || pageParam === undefined)
+      query.delete(name);
+    else
+      query.set(name, String(pageParam));
+    return { ...input, query };
+  }
+  return {
+    ...input,
+    query: { ...given, [name]: pageParam }
+  };
+}
+
+// src/openapi/create-openapi-queries.ts
+function createOpenApiQueries(api, { scope } = {}) {
+  const takes = new Map;
+  for (const operation of Object.values(api.operations)) {
+    takes.set(`${operation.method} ${operation.path}`, operation.parameters.length > 0 || Object.keys(operation.body?.content ?? {}).length > 0);
+  }
+  const takesInput = (method, path) => {
+    const found = takes.get(`${method} ${path}`);
+    if (found === undefined) {
+      throw new Error(`The spec has no ${method.toUpperCase()} ${path} operation`);
+    }
+    return found;
+  };
+  const split = (method, path, args) => takesInput(method, path) ? { input: args[0], init: args[1] } : { input: undefined, init: args[0] };
+  const call = (method, path, input, init, signal) => {
+    const sent = signal ? { ...init, signal: joined(init?.signal, signal) } : init;
+    const at = api[method];
+    return (takesInput(method, path) ? at(path, input, sent) : at(path, sent)).then(ok);
+  };
+  const queryKey = (method, path, input) => keyOf(scope, method, path, input);
+  return {
+    queryKey,
+    queryOptions: (method, path, ...args) => {
+      const { input, init } = split(method, path, args);
+      return {
+        queryKey: queryKey(method, path, input),
+        queryFn: ({ signal }) => call(method, path, input, init, signal)
+      };
+    },
+    infiniteQueryOptions: (method, path, input, { pageParamName, ...paging }, init) => ({
+      ...paging,
+      queryKey: [...queryKey(method, path, input), "infinite"],
+      queryFn: ({
+        signal,
+        pageParam
+      }) => call(method, path, paged(input, pageParamName, pageParam), init, signal)
+    }),
+    mutationOptions: (method, path, init) => {
+      takesInput(method, path);
+      return {
+        mutationKey: queryKey(method, path),
+        mutationFn: (input) => call(method, path, input || undefined, init)
+      };
+    }
+  };
+}
+export {
+  createOpenApiQueries
+};
+
+//# debugId=21510642E24588C464756E2164756E21
+//# sourceMappingURL=openapi.js.map

package/dist/openapi.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["../src/openapi/create-openapi-queries.ts", "../src/key/key.ts"],
+  "sourcesContent": [
+    "/**\n * `createOpenApiQueries`: TanStack Query options for the operations of a\n * client bound to a generated spec by `@nxgt/openapi-httpyz`. It imports that\n * package's types only: the calls are the bound client's own.\n */\nimport { type Method, ok } from '@nxgt/httpyz';\nimport type {\n\tOpenApiClient,\n\tOperationInit,\n\tOperationsShape,\n\tRuntimeOperation,\n} from '@nxgt/openapi-httpyz';\nimport { joined, keyOf, paged } from '../key/key';\nimport type { KeyInput, Paging, QueriesOptions } from '../queries/types';\nimport type { OpenApiQueries } from './types';\n\ntype Call = (\n\tpath: string,\n\t...args: unknown[]\n) => Promise<{ readonly status: number; readonly data: unknown }>;\n\n/**\n * TanStack Query options for the operations of `api`. The client's own\n * `operations` tell an operation's input from its init, as they do for its\n * calls: one that takes nothing is called with its init alone.\n *\n * ```ts\n * const queries = createOpenApiQueries(api);\n * const { data } = useQuery(queries.queryOptions('get', '/employees/{id}', { param: { id } }));\n * ```\n */\nexport function createOpenApiQueries<\n\tOps extends OperationsShape<Ops>,\n\tRoutes,\n\tDecoded extends boolean,\n>(\n\tapi: OpenApiClient<Ops, Routes, Decoded>,\n\t{ scope }: QueriesOptions = {},\n): OpenApiQueries<Ops, Routes, Decoded> {\n\t// As the bound client reads its arguments: an operation that takes nothing has no input.\n\tconst takes = new Map<string, boolean>();\n\tfor (const operation of Object.values<RuntimeOperation>(\n\t\tapi.operations as unknown as { readonly [id: string]: RuntimeOperation },\n\t)) {\n\t\ttakes.set(\n\t\t\t`${operation.method} ${operation.path}`,\n\t\t\toperation.parameters.length > 0 ||\n\t\t\t\tObject.keys(operation.body?.content ?? {}).length > 0,\n\t\t);\n\t}\n\tconst takesInput = (method: Method, path: string): boolean => {\n\t\tconst found = takes.get(`${method} ${path}`);\n\t\tif (found === undefined) {\n\t\t\tthrow new Error(\n\t\t\t\t`The spec has no ${method.toUpperCase()} ${path} operation`,\n\t\t\t);\n\t\t}\n\t\treturn found;\n\t};\n\t/** The input and the init of a call's arguments. */\n\tconst split = (method: Method, path: string, args: readonly unknown[]) =>\n\t\ttakesInput(method, path)\n\t\t\t? { input: args[0] as object | undefined, init: args[1] as OperationInit }\n\t\t\t: { input: undefined, init: args[0] as OperationInit };\n\tconst call = (\n\t\tmethod: Method,\n\t\tpath: string,\n\t\tinput: object | undefined,\n\t\tinit: OperationInit | undefined,\n\t\tsignal?: AbortSignal,\n\t) => {\n\t\tconst sent = signal\n\t\t\t? { ...init, signal: joined(init?.signal, signal) }\n\t\t\t: init;\n\t\tconst at = (api as unknown as Record<Method, Call>)[method];\n\t\treturn (\n\t\t\ttakesInput(method, path) ? at(path, input, sent) : at(path, sent)\n\t\t).then(ok);\n\t};\n\tconst queryKey = (method: Method, path?: string, input?: KeyInput) =>\n\t\tkeyOf(scope, method, path, input);\n\n\treturn {\n\t\tqueryKey,\n\t\tqueryOptions: (method: Method, path: string, ...args: unknown[]) => {\n\t\t\tconst { input, init } = split(method, path, args);\n\t\t\treturn {\n\t\t\t\tqueryKey: queryKey(method, path, input),\n\t\t\t\tqueryFn: ({ signal }: { signal: AbortSignal }) =>\n\t\t\t\t\tcall(method, path, input, init, signal),\n\t\t\t};\n\t\t},\n\t\tinfiniteQueryOptions: (\n\t\t\tmethod: Method,\n\t\t\tpath: string,\n\t\t\tinput: object | undefined,\n\t\t\t{ pageParamName, ...paging }: Paging<unknown, unknown>,\n\t\t\tinit?: OperationInit,\n\t\t) => ({\n\t\t\t...paging,\n\t\t\t// Apart from the query of the same call, whose data is one page, not all of them.\n\t\t\tqueryKey: [...queryKey(method, path, input), 'infinite'],\n\t\t\tqueryFn: ({\n\t\t\t\tsignal,\n\t\t\t\tpageParam,\n\t\t\t}: {\n\t\t\t\tsignal: AbortSignal;\n\t\t\t\tpageParam: unknown;\n\t\t\t}) =>\n\t\t\t\tcall(\n\t\t\t\t\tmethod,\n\t\t\t\t\tpath,\n\t\t\t\t\tpaged(input, pageParamName, pageParam),\n\t\t\t\t\tinit,\n\t\t\t\t\tsignal,\n\t\t\t\t),\n\t\t}),\n\t\tmutationOptions: (method: Method, path: string, init?: OperationInit) => {\n\t\t\ttakesInput(method, path);\n\t\t\treturn {\n\t\t\t\tmutationKey: queryKey(method, path),\n\t\t\t\tmutationFn: (input: object | undefined) =>\n\t\t\t\t\tcall(method, path, input || undefined, init),\n\t\t\t};\n\t\t},\n\t} as unknown as OpenApiQueries<Ops, Routes, Decoded>;\n}\n",
+    "/** What the keys and calls of both entry points share. */\n\n/** Both signals: the call ends on either. */\nexport const joined = (\n\tgiven: AbortSignal | null | undefined,\n\tquery: AbortSignal,\n): AbortSignal => (given ? AbortSignal.any([given, query]) : query);\n\n/** A value TanStack hashes as it is: a `URLSearchParams` or `FormData` as its entries. */\nconst hashable = (value: unknown): unknown =>\n\tvalue instanceof URLSearchParams ||\n\t(typeof FormData !== 'undefined' && value instanceof FormData)\n\t\t? [...value.entries()]\n\t\t: value;\n\n/** The parts of an input that tell two calls to one path apart. */\nconst PARTS = [\n\t'param',\n\t'query',\n\t'header',\n\t'json',\n\t'form',\n\t'text',\n\t'body',\n] as const;\n\n/** What tells two calls to one path apart: what they send, and `decode: false`. */\nfunction keyed(input: object | undefined): object | undefined {\n\tif (!input) return undefined;\n\tconst given = input as { readonly [part: string]: unknown };\n\tconst key: Record<string, unknown> = {};\n\tfor (const part of PARTS) {\n\t\tif (given[part] !== undefined) key[part] = hashable(given[part]);\n\t}\n\tif (given.decode === false) key.decode = false;\n\treturn Object.keys(key).length > 0 ? key : undefined;\n}\n\n/** A key, or the start of one: `[scope?, method, path?, input?]`. */\nexport function keyOf(\n\tscope: string | undefined,\n\tmethod: string,\n\tpath?: string,\n\tinput?: object,\n): unknown[] {\n\tconst key: unknown[] = scope === undefined ? [method] : [scope, method];\n\tif (path !== undefined) key.push(path);\n\tconst rest = keyed(input);\n\tif (rest !== undefined) key.push(rest);\n\treturn key;\n}\n\n/** `input` with `pageParam` as its query parameter `name`: left out when `null`. */\nexport function paged<Input extends { readonly query?: unknown }>(\n\tinput: Input | undefined,\n\tname: string,\n\tpageParam: unknown,\n): Input {\n\tconst given = input?.query;\n\tif (given instanceof URLSearchParams) {\n\t\tconst query = new URLSearchParams(given);\n\t\tif (pageParam === null || pageParam === undefined) query.delete(name);\n\t\telse query.set(name, String(pageParam));\n\t\treturn { ...input, query } as Input;\n\t}\n\treturn {\n\t\t...input,\n\t\tquery: { ...(given as object | undefined), [name]: pageParam },\n\t} as Input;\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "21510642E24588C464756E2164756E21",
+  "names": []
+}

package/dist/queries/create-queries.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `createQueries`: TanStack Query options for the calls of a client of
+ * `createHttpClient`. It adds no runtime of TanStack's: each function returns
+ * a plain object, whose `queryFn` sends the call with the query's `signal`.
+ */
+import { type HttpClient } from '@nxgt/httpyz';
+import type { HttpQueries, QueriesOptions } from './types';
+/**
+ * TanStack Query options for the calls of `http`.
+ *
+ * ```ts
+ * const queries = createQueries(http);
+ * const { data } = useQuery(
+ *   queries.queryOptions('get', '/items/{id}', { param: { id }, responses: { 200: Item } }),
+ * );
+ * ```
+ */
+export declare function createQueries(http: HttpClient, { scope }?: QueriesOptions): HttpQueries;
+//# sourceMappingURL=create-queries.d.ts.map

package/dist/queries/create-queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-queries.d.ts","sourceRoot":"","sources":["../../src/queries/create-queries.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,KAAK,UAAU,EAAmB,MAAM,cAAc,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAoB,cAAc,EAAE,MAAM,SAAS,CAAC;AAU7E;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC5B,IAAI,EAAE,UAAU,EAChB,EAAE,KAAK,EAAE,GAAE,cAAmB,GAC5B,WAAW,CA8Cb"}

package/dist/queries/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The options objects `createQueries()` returns. They are plain objects, so
+ * any TanStack Query adapter takes them: `useQuery(queries.queryOptions(...))`
+ * in React, `createQuery` in Solid, `injectQuery` in Angular.
+ */
+import type { CallOptions, HttpReply, Method, PathParamNames, QueryInput, ReplyOptions, RequestArgs, RequestInput, RequestOptions, Responses, Success } from '@nxgt/httpyz';
+import type { DataTag, GetNextPageParamFunction, GetPreviousPageParamFunction, InfiniteData } from '@tanstack/query-core';
+/** What a query resolves to: the data of the call's 2xx replies. */
+export type QueryData<R extends Responses | undefined, Decoded extends boolean> = Success<HttpReply<R, Decoded>>['data'];
+/**
+ * A key: `[method, path, input]`, after the client's `scope`, tagged with its
+ * data so that `queryClient.getQueryData(key)` is typed.
+ */
+export type HttpQueryKey<Data> = DataTag<readonly unknown[], Data>;
+export interface HttpQueryOptions<Data> {
+    readonly queryKey: HttpQueryKey<Data>;
+    /** Sends the call with the query's `signal`: a cancelled query aborts it. */
+    readonly queryFn: (context: {
+        readonly signal: AbortSignal;
+    }) => Promise<Data>;
+}
+/** How an infinite query pages: TanStack's own options, and where the page goes. */
+export interface Paging<Data, PageParam> {
+    /**
+     * The query parameter each page's `pageParam` is sent as: `'after'`,
+     * `'page'`. A `null` or `undefined` page param is left out.
+     */
+    readonly pageParamName: string;
+    readonly initialPageParam: PageParam;
+    readonly getNextPageParam: GetNextPageParamFunction<PageParam, Data>;
+    readonly getPreviousPageParam?: GetPreviousPageParamFunction<PageParam, Data>;
+    readonly maxPages?: number;
+}
+export interface HttpInfiniteQueryOptions<Data, PageParam> extends Omit<Paging<Data, PageParam>, 'pageParamName'> {
+    readonly queryKey: HttpQueryKey<InfiniteData<Data, PageParam>>;
+    readonly queryFn: (context: {
+        readonly signal: AbortSignal;
+        readonly pageParam: PageParam;
+    }) => Promise<Data>;
+}
+/** What a mutation's `mutate()` takes: what the call sends, and its call options. */
+export type MutationVariables<Path extends string> = RequestInput<Path> & CallOptions;
+export interface HttpMutationOptions<Path extends string, Data> {
+    readonly mutationKey: readonly unknown[];
+    /** Optional when the path has no `{name}`s: `mutate()`. */
+    readonly mutationFn: (variables: [PathParamNames<Path>] extends [never] ? // biome-ignore lint/suspicious/noConfusingVoidType: void, not undefined, is what lets `mutate()` be called with nothing
+    MutationVariables<Path> | void : MutationVariables<Path>) => Promise<Data>;
+}
+/** What a key may hold, for a filter: any part of an input. */
+export interface KeyInput {
+    readonly param?: {
+        readonly [name: string]: unknown;
+    };
+    readonly query?: QueryInput;
+    readonly json?: unknown;
+    readonly form?: unknown;
+    readonly text?: string;
+    readonly body?: unknown;
+}
+export interface HttpQueries {
+    /**
+     * A query of a call: `useQuery(queries.queryOptions('get', '/items/{id}', { param: { id }, responses }))`.
+     * It resolves to the data of a 2xx reply, and throws a `ReplyStatusError`
+     * for any other.
+     */
+    queryOptions<Path extends string, R extends Responses | undefined = undefined, Decoded extends boolean = true>(method: Method, path: Path, ...args: RequestArgs<Path, R, Decoded>): HttpQueryOptions<QueryData<R, Decoded>>;
+    /** An infinite query of a call: each page sent with its `pageParam` as a query parameter. */
+    infiniteQueryOptions<Path extends string, PageParam, R extends Responses | undefined = undefined, Decoded extends boolean = true>(method: Method, path: Path, options: RequestOptions<Path, R, Decoded>, paging: Paging<QueryData<R, Decoded>, PageParam>): HttpInfiniteQueryOptions<QueryData<R, Decoded>, PageParam>;
+    /**
+     * A mutation of a call, whose `mutate()` takes what it sends:
+     * `useMutation(queries.mutationOptions('delete', '/items/{id}'))`, then
+     * `mutate({ param: { id } })`. `options` holds what every call shares.
+     */
+    mutationOptions<Path extends string, R extends Responses | undefined = undefined, Decoded extends boolean = true>(method: Method, path: Path, options?: CallOptions & ReplyOptions<R, Decoded>): HttpMutationOptions<Path, QueryData<R, Decoded>>;
+    /**
+     * A key, or the start of one, for a filter:
+     * `queryClient.invalidateQueries({ queryKey: queries.queryKey('get', '/items') })`
+     * matches every query of `GET /items`, whatever its input.
+     */
+    queryKey(method: Method, path?: string, input?: KeyInput): readonly unknown[];
+}
+export interface QueriesOptions {
+    /**
+     * Put first in every key, to keep two clients' queries apart when their
+     * paths are the same: `'catalog'`.
+     */
+    readonly scope?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/queries/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/queries/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,66 @@
+{
+	"name": "@nxgt/httpyz-query",
+	"version": "0.1.0",
+	"license": "UNLICENSED",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"README.md",
+		"package.json"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./openapi": {
+			"types": "./dist/openapi.d.ts",
+			"import": "./dist/openapi.js",
+			"default": "./dist/openapi.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"nxgt": {
+		"entrypoints": [
+			"src/index.ts",
+			"src/openapi.ts"
+		]
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/softistx/nxgt-http.git",
+		"directory": "packages/httpyz-query"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bun run ../../build.ts",
+		"fixtures": "bun run test/generate.ts",
+		"test": "bun run fixtures && bun test src",
+		"typecheck": "bun run fixtures && tsc --noEmit"
+	},
+	"devDependencies": {
+		"@nxgt/httpyz": "^0.0.0",
+		"@nxgt/openapi-codegen": "^0.1.0",
+		"@nxgt/openapi-httpyz": "^0.0.0",
+		"@tanstack/query-core": "^5.102.8",
+		"@types/bun": "^1.4.0",
+		"zod": "^4.5.4"
+	},
+	"peerDependencies": {
+		"@nxgt/httpyz": "^0.0.0",
+		"@nxgt/openapi-httpyz": "^0.0.0",
+		"@tanstack/query-core": "^5.90.0",
+		"typescript": "^6.0.3"
+	},
+	"peerDependenciesMeta": {
+		"@nxgt/openapi-httpyz": {
+			"optional": true
+		}
+	}
+}