dune2-tools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

@dune2/tools consumer guide

@dune2/tools 使用者指南

This is a user-facing skill for projects that consume

@dune2/tools

. It is not contributor guidance for developing the

next-tools

repository itself.

Use the library's existing abstractions instead of rebuilding them with raw TanStack Query, storage listeners, Valtio boilerplate, Context boilerplate, prop wrapper components, string field constants, or floating-point helpers.

本指南面向使用

@dune2/tools

的项目，并非针对

next-tools

仓库本身的开发贡献者指导。

请使用库中已有的抽象能力，而非通过原生TanStack Query、存储监听器、Valtio模板代码、Context模板代码、属性包装组件、字符串字段常量或浮点工具函数重新实现相同功能。

First checks

前期检查

Confirm the consumer project depends on
```
@dune2/tools
```
in its package manifest or lockfile.
Search the consumer codebase for existing
```
@dune2/tools/*
```
imports and generated API modules before adding a new abstraction.
Prefer the package's subpath exports. Do not expect runtime utilities from
@dune2/tools
root; import from paths such as
```
@dune2/tools/rq
```
,
```
@dune2/tools/storage
```
,
```
@dune2/tools/store
```
,
```
@dune2/tools/numbro
```
, or
```
@dune2/tools/factory/*
```
.
Match the application's existing request client, query client, namespaces, store conventions, and generated API patterns instead of introducing parallel infrastructure.
Read only the reference relevant to the current task.

确认使用者项目的package清单或锁文件中依赖了
```
@dune2/tools
```
。
在添加新的抽象实现前，先搜索使用者代码库中已有的
```
@dune2/tools/*
```
导入语句和生成的API模块。
优先使用包的子路径导出。不要期望从
@dune2/tools
根路径获取运行时工具；请从
```
@dune2/tools/rq
```
、
```
@dune2/tools/storage
```
、
```
@dune2/tools/store
```
、
```
@dune2/tools/numbro
```
或
```
@dune2/tools/factory/*
```
这类路径导入。
匹配应用程序现有的请求客户端、查询客户端、命名空间、存储约定和生成的API模式，而非引入并行的基础设施。
仅阅读与当前任务相关的参考文档。

References

参考文档

Load references progressively instead of reading every API guide up front:

API requests, TanStack Query, cache operations, generated APIs, SDK/worker async operations: references/rq.md
localStorage, sessionStorage, React persistence subscriptions, cookies: references/storage.md
Valtio application state, snapshots, selectors, subscriptions: references/store.md
React Context factories, prop adapters, typed field names: references/factory.md
Precise decimal arithmetic, currency/percentage/number formatting: references/numbro.md

Do not load unrelated references merely because

@dune2/tools

is present.

渐进式加载参考文档，无需预先阅读所有API指南：

API请求、TanStack Query、缓存操作、生成的API、SDK/Worker异步操作：references/rq.md
localStorage、sessionStorage、React持久化订阅、Cookie：references/storage.md
Valtio应用状态、快照、选择器、订阅：references/store.md
React Context工厂、属性适配器、类型化字段名称：references/factory.md
精确小数运算、货币/百分比/数字格式化：references/numbro.md

不要仅仅因为存在

@dune2/tools

就加载无关的参考文档。

Choose the existing primitive first

优先选择现有基础能力

Need	Prefer
HTTP API + TanStack Query	`RequestBuilder` from `@dune2/tools/rq`
SDK/contract/worker/local async operation that still needs Query caching/status	`createApi` from `@dune2/tools/rq/createApi`
Imperative request using an existing API definition	`api.request(...)`
Prefetch/fetch/ensure/invalidate/refetch/read/write query cache	The matching `RequestBuilder` method
Exceptional request needing separate query/body or per-call transport config	`requestWithConfig(...)` , only when `request(...)` cannot express it
Typed request/response field names	`api.reqFields` , `api.resFields` , or `fieldsMap`
localStorage/sessionStorage + typed defaults + React subscription	`createStorage`
Client-readable string cookies	`createCookieStorage`
Valtio state with typed actions/hooks	`createStore`
React Context whose value is produced by a hook	`createStateContext`
Adapt/default/enhance component props while preserving refs	`mapProps`
Precise decimal arithmetic/formatting	`numbro` / `Numbro`

需求	优先选择
HTTP API + TanStack Query	`@dune2/tools/rq` 中的 `RequestBuilder`
需要Query缓存/状态的SDK/合约/Worker/本地异步操作	`@dune2/tools/rq/createApi` 中的 `createApi`
使用现有API定义的命令式请求	`api.request(...)`
预取/获取/确保/失效/重新获取/读取/写入查询缓存	对应的 `RequestBuilder` 方法
需要单独查询/请求体或每次调用传输配置的特殊请求	`requestWithConfig(...)` ，仅当 `request(...)` 无法满足需求时使用
类型化的请求/响应字段名称	`api.reqFields` 、 `api.resFields` 或 `fieldsMap`
localStorage/sessionStorage + 类型化默认值 + React订阅	`createStorage`
客户端可读的字符串Cookie	`createCookieStorage`
带有类型化操作/钩子的Valtio状态	`createStore`
值由钩子生成的React Context	`createStateContext`
在保留refs的同时适配/默认值/增强组件属性	`mapProps`
精确小数运算/格式化	`numbro` / `Numbro`

High-value rules

高价值规则

When an API is already represented by a
```
RequestBuilder
```
, use its query/mutation/cache methods instead of wrapping it in another raw TanStack Query layer or manually rebuilding its query key.
Default to
```
api.request(params)
```
for imperative requests.
```
requestWithConfig(...)
```
is an escape hatch, not the normal calling style.
Reuse the application's shared
```
RequestBuilder.setRequestFn(...)
```
and QueryClient configuration when present instead of creating per-endpoint infrastructure.
Prefer
```
createStorage().<key>.useValue()
```
over custom local/session-storage React synchronization.
Prefer existing
```
createStore
```
state/actions over introducing a parallel state mechanism for the same domain. Be careful when passing Valtio proxy-backed snapshots to code expecting plain objects.
Prefer
```
createStateContext
```
,
```
mapProps
```
, and
```
fieldsMap
```
when their focused abstraction directly matches the problem; do not use them merely for consistency if a simpler local implementation is clearer.
Use
```
numbro
```
for precise decimal business logic and established number formatting rather than native floating-point arithmetic plus ad-hoc
```
toFixed
```
/string formatting.

当API已由
```
RequestBuilder
```
实现时，请使用它的查询/变更/缓存方法，而非将其包装在另一个原生TanStack Query层中，或手动重新构建其查询键。
命令式请求默认使用
```
api.request(params)
```
。
```
requestWithConfig(...)
```
是一个逃生舱，而非常规调用方式。
如果应用程序存在共享的
```
RequestBuilder.setRequestFn(...)
```
和QueryClient配置，请复用它们，而非为每个端点创建单独的基础设施。
优先使用
```
createStorage().<key>.useValue()
```
，而非自定义本地/会话存储的React同步逻辑。
优先使用现有的
```
createStore
```
状态/操作，而非为同一领域引入并行的状态机制。将Valtio代理支持的快照传递给期望普通对象的代码时要格外小心。
当
```
createStateContext
```
、
```
mapProps
```
和
```
fieldsMap
```
的聚焦抽象直接匹配问题时优先使用；如果更简单的本地实现更清晰，不要仅仅为了一致性而使用它们。
使用
```
numbro
```
处理精确的小数业务逻辑和既定的数字格式化，而非原生浮点运算加上临时的
```
toFixed
```
/字符串格式化。

Shared type utilities

共享类型工具

For matching type-level tasks, reuse the package utilities instead of recreating equivalents:

import type { OptionalKeys, Overwrite, Print } from '@dune2/tools/shared';

对于类型层面的任务，请复用包中的工具，而非重新创建等效工具：

import type { OptionalKeys, Overwrite, Print } from '@dune2/tools/shared';

Consumer-project workflow

使用者项目工作流

Identify the nearest existing
```
@dune2/tools
```
pattern in the application.
Load the single most relevant reference above when API details are needed.
Pick the smallest library primitive that directly covers the requirement.
Preserve generated API modules and shared global configuration; extend them rather than bypassing them.
Keep imports on documented/exported subpaths.
Run the consumer project's relevant typecheck/tests after changes.
If the library truly lacks the needed behavior, implement the smallest local gap and explicitly note why an existing
```
@dune2/tools
```
API was not sufficient.

在应用程序中找到最接近的现有
```
@dune2/tools
```
模式。
当需要API细节时，加载上述单个最相关的参考文档。
选择直接满足需求的最小库基础能力。
保留生成的API模块和共享全局配置；扩展它们而非绕过它们。
保持导入路径为已文档化/导出的子路径。
修改后运行使用者项目相关的类型检查/测试。
如果库确实缺少所需功能，请实现最小的本地补充，并明确说明为何现有
```
@dune2/tools
```
API无法满足需求。

Common mistakes to avoid

需避免的常见错误

Importing utilities from the package root.
Reading every reference file when the task only concerns one module.
Recreating a TanStack Query
```
queryKey
```
for an existing
```
RequestBuilder
```
endpoint.
Calling raw
```
fetch
```
/axios in a component when a generated or existing API builder already exists.
Reaching for
```
requestWithConfig(...)
```
when ordinary
```
request(params)
```
is sufficient.
Creating another storage hook around localStorage when
```
createStorage
```
already provides
```
useValue
```
and synchronization.
Building string field-name constants manually when
```
fieldsMap
```
/
```
reqFields
```
/
```
resFields
```
can provide typed names.
Passing proxy-backed store objects blindly into libraries that expect ordinary serializable values.
Using JavaScript
```
number
```
arithmetic for precise decimal business logic when the codebase already uses
```
numbro
```
.

从包的根路径导入工具函数。
当任务仅涉及一个模块时，却阅读所有参考文档。
为已有的
```
RequestBuilder
```
端点重新创建TanStack Query的
```
queryKey
```
。
当生成的或现有的API构建器已存在时，在组件中调用原生
```
fetch
```
/axios。
普通
```
request(params)
```
足够时却使用
```
requestWithConfig(...)
```
。
当
```
createStorage
```
已提供
```
useValue
```
和同步功能时，仍围绕localStorage创建另一个存储钩子。
当
```
fieldsMap
```
/
```
reqFields
```
/
```
resFields
```
可以提供类型化名称时，手动构建字符串字段名称常量。
将代理支持的存储对象盲目传递给期望普通可序列化值的库。
当代码库已使用
```
numbro
```
时，仍使用JavaScript
```
number
```
运算处理精确的小数业务逻辑。