Frontend Query & Mutation

Intent

• Keep contract as the single source of truth in

  web/contract/*

  .
• Prefer contract-shaped

  queryOptions()

  and

  mutationOptions()

  .
• Keep invalidation and mutation flow knowledge in the service layer.
• Keep abstractions minimal to preserve TypeScript inference.

Workflow

1. Identify the change surface.
   • Read

     references/contract-patterns.md

     for contract files, router composition, client helpers, and query or mutation call-site shape.
   • Read

     references/runtime-rules.md

     for conditional queries, invalidation, error handling, and legacy migrations.
   • Read both references when a task spans contract shape and runtime behavior.
2. Implement the smallest abstraction that fits the task.
   • Default to direct

     useQuery(...)

     or

     useMutation(...)

     calls with oRPC helpers at the call site.
   • Extract a small shared query helper only when multiple call sites share the same extra options.
   • Create

     web/service/use-{domain}.ts

     only for orchestration or shared domain behavior.
3. Preserve Dify conventions.
   • Keep contract inputs in

     { params, query?, body? }

     shape.
   • Bind invalidation in the service-layer mutation definition.
   • Prefer

     mutate(...)

     ; use

     mutateAsync(...)

     only when Promise semantics are required.

Files Commonly Touched

• web/contract/console/*.ts

• web/contract/marketplace.ts

• web/contract/router.ts

• web/service/client.ts

• web/service/use-*.ts

• component and hook call sites using

  consoleQuery

  or

  marketplaceQuery

References

• Use

  references/contract-patterns.md

  for contract shape, router registration, query and mutation helpers, and anti-patterns that degrade inference.
• Use

  references/runtime-rules.md

  for conditional queries, invalidation,

  mutate

  versus

  mutateAsync

  , and legacy migration rules.