@haddowg/json-api-query

中文文档
1.7.2发布于 2026/11/17MITTypeScriptESM + CJS构建来源已验证近 30 天下载 4604

TanStack 查询 JSON:API客户端的绑定:选项/关键工厂+类型:id缓存正常化.

中文使用文档
文档目录8 节
  1. 安装
  2. 绑定客户端
  3. 读取 - 查询选项工厂
  4. 查询键厂
  5. 正常化 type:id 写入补丁)
  6. 写作——可变选择工厂
  7. 工作实例(直接用克瑞-核心)
  8. 许可证

@ haddowg/ json- api- query

部分 jsonapi.rest (英语) 套间 - 完整、符合规格 JSON: API 1. 1 堆栈: 框架不可知 PHP 核心项目页:1 符号捆绑页:1 Laravel 软件包这个 键入类型脚本 客户端,由经过检测的OpenAPI 3.1合同捆绑在一起. 完整文档: (原始内容存档于2018-10-21) (韩语). haddog.github.io/json-api-ts。 。 。 .

TanStack 查询绑定 @haddowg/json-api-client 运行时间: 查询/更改 选项工厂 (不是先入为主的钩子),一个决定式的查询键厂,然后说 type:id 写入缓存正常化.

因为表面是选择工厂 @tanstack/query-core,一个装订盖 反应 / Vue / Svelte / Solid —— 您通过返回 { queryKey, queryFn } 编号 : MutationOptions 到你的框架 useQuery 编号 : useMutation。 。 。 .

安装

pnpm add @haddowg/json-api-query @tanstack/query-core

@tanstack/query-core 是同级依赖.

绑定客户端

读取工厂接受 Client<D, A> 和写作厂 Client<D, A, W> - 也没有 包含客户端的自定义动作类型(动作不是可缓存的资源). 生成的 createClient 返回客户端 (单位:千美元) 带有动作类型,因此通过 动作不可知性 Client 查询边界上的类型——每平面投出一个:

import type { Client } from '@haddowg/json-api-client'
import { createClient } from './api/music.gen'
import type { Attributes, ResourceMap, WriteAttributes } from './api/music.gen'

const client = createClient({ baseUrl: 'https://music.example' })

type ReadClient = Client<ResourceMap, Attributes>
type WriteClient = Client<ResourceMap, Attributes, WriteAttributes>

读取 - 查询选项工厂

每个工厂都返回平原 { queryKey, queryFn },在结构上与查询核心兼容 QueryOptions,保留客户端的全静态收缩(include 宽度, fields (原始内容存档于2018-09-25). Grains. 两种同等形式:

import { createQueryApi, listQueryOptions } from '@haddowg/json-api-query'

// Bound API — the cleanest per-type call shape.
const reads = createQueryApi(client as unknown as ReadClient)
const listOpts = reads.albums.list({ include: ['artist'] })
const getOpts = reads.albums.get('1')
const relOpts = reads.albums.relationship('1', 'tracks') // linkage
const relatedOpts = reads.albums.related('1', 'tracks') // related collection

// Standalone factories — equivalent, with `client`/`type` passed explicitly.
const listOpts2 = listQueryOptions(client as unknown as ReadClient, 'albums', {
  include: ['artist'],
})

// Pass to your framework's useQuery, or fetch directly:
const albums = await queryClient.fetchQuery(listOpts)

独立的工厂是 listQueryOptions, (中文(简体) ), getQueryOptions, (中文(简体) ), relationshipQueryOptions, (中文(简体) ), relatedQueryOptions。 。 。 .

查询键厂

键是稳定的,等级化的只读的tuple—— [type, operation, id?, rel?, params?]编辑 分级是合同目标无效 : [type] 无效整个类型, [type, operation] 一个操作的子树, [type, 'fetchOne', id] (单位:千美元) 单资源。 params 将最后一个部分作为正态对象来骑行,所以两个相模相等 查询(按键重排,等值)共享一键.

import { keyFor, operationKey, resourceKey, typeKey } from '@haddowg/json-api-query'

keyFor({ type: 'albums', operation: 'fetchOne', id: '1' }) // ['albums', 'fetchOne', '1']
typeKey('albums') // ['albums']
operationKey('albums', 'fetchMany') // ['albums', 'fetchMany']
resourceKey('albums', '1') // ['albums', 'fetchOne', '1']

queryClient.invalidateQueries({ queryKey: typeKey('albums') }) // every albums read

也导出 : relationKey, (中文(简体) ), normalizeParams。 。 。 .

单通键类型键不包含 id (['inboxes', 'fetchOne']) (中文(简体) ). 它的工厂 undefined iD,类型只允许单通,绑定的 API 将 参数 : reads.inboxes.get(), (中文(简体) ), writes.inboxes.update(),其变量包含资源 id 请求机构.

正常化type:id 写入补丁)

TanStack 保持非正常化的结果; 此软件包索引了每个资源(data + 键 included作者: type:id 和,在一个变化, 补丁每个缓存查询 type:id 到位 - "编辑 一次,随时更新。" 补丁替换节点 属性 (描述器知道属性) vs关系),同时保留边缘-局部关系 $pivot 编号 : $edge。每个被触摸的查询然后获得一个新的 根引用于同值上,因此组件观察它重递. 读取工厂的设定 structuralSharing: false,因为结构共享会重建一个被重置为平面阵列的值 和对象 $page, (中文(简体) ), $next() 或者说 $self; 设置在您创建的任意查询上 .

installNormalization 自动运行每个成功查询/调试的补丁 :

import { installNormalization } from '@haddowg/json-api-query'
import { resourceMap } from './api/music.gen'
import { QueryClient } from '@tanstack/query-core'

const queryClient = new QueryClient()
const teardown = installNormalization(queryClient, resourceMap)
// … later: teardown() removes the subscriptions.

每个查询站一个描述符 . 补丁匹配由 type:id 独自一人,所以两个描述 共享查询客户端会交叉污染属性 。 正在安装 a 不同 显示 相同的查询 client 抛出。 给每个输入的客户端/服务器自己的查询站.

更倾向于明确的控制? 跳过安装和调用 normalize(queryClient, result, resourceMap) 从选择工厂 onSuccess - 相同的书写补丁.

写作——可变选择工厂

每个返回 a MutationOptions (单位:千美元)mutationFn + 生命周期召回绑定线条 正常化/失效/乐观),结构上与查询-核心兼容. 这个 补丁- vs- 无效拆分数字 :

  • a 一个 更新 (或关系) set 编号 : replace)只更改一个节点的属性/链接 ~ 它通过成功补丁 normalize (无回放);
  • (单位:千美元) 创建 编号 : 删除 更改收集成员 —— 在结算时取消相关 列表 / 关系子树, 因此它们会重新绘制 .
import { createMutationApi } from '@haddowg/json-api-query'

const writes = createMutationApi(queryClient, client as unknown as WriteClient, resourceMap)

// Create — invalidates the type's lists on settle; normalizes the new resource on success.
const createOpts = writes.albums.create()

// Update — patches across the cache on success. `{ optimistic: true }` pre-applies the patch's
// attributes through the normalized patch and rolls back on error.
const updateOpts = writes.albums.id('1').update({ optimistic: true })

// Delete — invalidates the type's lists + the resource's own reads.
const deleteOpts = writes.albums.id('1').delete()

// Relationship mutations — invalidate the parent's relation reads (never the type's lists).
const addOpts = writes.albums.id('1').rel('tracks').add()
const setOpts = writes.albums.id('1').rel('artist').set()

变异的变量会镜像客户端: create() 使用平面创建输入, update() 补丁, add/remove/replace() 联系参考:, set() 参考或 null。 。 。 .

独立的工厂是 createMutationOptions, (中文(简体) ), updateMutationOptions, (中文(简体) ), deleteMutationOptions, (中文(简体) ), addRelationshipMutationOptions, (中文(简体) ), removeRelationshipMutationOptions, (中文(简体) ), replaceRelationshipMutationOptions, (中文(简体) ), setRelationshipMutationOptions和细 atomicMutationOptions 传球.

工作实例(直接用克瑞-核心)

const reads = createQueryApi(client as unknown as ReadClient)
const writes = createMutationApi(queryClient, client as unknown as WriteClient, resourceMap)

const listOpts = reads.albums.list()
const getOpts = reads.albums.get('1')
await queryClient.fetchQuery(listOpts)
await queryClient.fetchQuery(getOpts)

const updateOpts = writes.albums.id('1').update()
await queryClient
  .getMutationCache()
  .build(queryClient, updateOpts as never)
  .execute({ title: 'Fresh title' })

// Both the cached list AND the cached get now reflect the fresh title — patched by `type:id`,
// not refetched.
queryClient.getQueryData(listOpts.queryKey)
queryClient.getQueryData(getOpts.queryKey)

许可证

麻省理工学院

版本与发布记录

@haddowg/json-api-query 共发布 29 个版本,首次发布于 2026/07/13;过去 12 个月发布了 29 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.7.2latest2026/11/17今天
1.7.12026/11/171 天前
1.7.02026/11/161 天前
1.6.02026/11/134 天前
1.5.02026/11/135 天前
1.4.22026/11/125 天前

关于 @haddowg/json-api-query 的常见问题

@haddowg/json-api-query 是什么?

TanStack 查询 JSON:API客户端的绑定:选项/关键工厂+类型:id缓存正常化.

如何安装 @haddowg/json-api-query?

在项目目录运行 npm install @haddowg/json-api-query,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@tanstack/query-core(^5.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@haddowg/json-api-query 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@haddowg/json-api-query 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@haddowg/json-api-query 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@haddowg/json-api-query 可以商用吗?

@haddowg/json-api-query 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@haddowg/json-api-query 的下载量有多少?

根据 npm 官方下载统计,@haddowg/json-api-query 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,604 次,日均约 153 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@haddowg/json-api-query 还在维护吗?

最新版本 1.7.2 发布于 2026/11/17(今天);至今共发布 29 个版本,其中过去 12 个月发布了 29 个;首次发布于 2026/07/13。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。