diff --git a/website/docs/migrations/from-pothos.md b/website/docs/migrations/from-pothos.md index 78a4c710..2f447bdb 100644 --- a/website/docs/migrations/from-pothos.md +++ b/website/docs/migrations/from-pothos.md @@ -55,7 +55,7 @@ The table below highlights concepts and APIs with notable differences: | `t.arg.*` / `args` | `.input({ ... })` | Arguments become one object | | `builder.enumType` | `z.enum([...]).meta({ title })` | | | `builder.unionType` + `resolveType` | `z.discriminatedUnion("__typename", [...]).meta({ title })` | Or `z.union` with `asUnionType` / `resolveType` | -| `builder.interfaceType` + `interfaces: [I]` | `asObjectType({ interfaces: [I] })` | Do not return an interface silk directly (see [Gotchas](#gotchas)) | +| `builder.interfaceType` + `interfaces: [I]` | `silk(new GraphQLInterfaceType(...))` + `asObjectType({ interfaces: [I] })` | Wrap `GraphQLInterfaceType` with `silk()` when queries/fields return the interface; pass unreferenced implementors to `weave()` | | `builder.scalarType` / `addScalarType` | `ZodWeaver.config({ presetGraphQLType })` or `asField({ type })` | Map `Date` (`z.ZodDate`) globally in `presetGraphQLType` | | `context` argument | [`useContext()`](../context.md) | Requires `asyncContextProvider` | | `info` argument | `useResolverPayload().info` | | @@ -67,7 +67,11 @@ The table below highlights concepts and APIs with notable differences: | `@pothos/plugin-simple-objects` (`builder.simpleObject`) | `z.object` | | | `@pothos/plugin-with-input` (`t.fieldWithInput`) | `.input({ input: NamedInputSilk })` | Name the input silk explicitly | | `@pothos/plugin-prisma` / `@pothos/plugin-drizzle` | Resolver factories and `relationField` | See [Prisma and Drizzle plugins](#prisma-and-drizzle-plugins) | -| `@pothos/plugin-relay`, `-errors`, `-sub-graph`, `-smart-subscriptions` | Stop; keep Pothos for that module | See [When to stop](#when-to-migrate-when-to-stop) | +| `@pothos/plugin-relay` (`builder.node`, `t.connection`) | `silk(new GraphQLInterfaceType(...))` for `Node`; Zod silks for `PageInfo`, `*Edge`, `*Connection` | Keep exact SDL and ID/cursor encoding; see [Relay](#relay) | +| `@pothos/plugin-errors` (`errors: { types }`) | Result union (`z.discriminatedUnion` / `z.union`) or `GraphQLError` with `extensions` | Pick by whether `before.graphql` has a union; see [Errors](#errors) | +| `@pothos/plugin-sub-graph` (`subGraphs`) | Separate `weave()` per audience | Pass only that audience's resolvers; see [Sub-graphs](#sub-graphs) | +| `@pothos/plugin-smart-subscriptions` (`smartSubscriptions`) | `subscription()` + pubsub (`createPubSub`) | Publish explicitly from mutations; see [Smart Subscriptions](#smart-subscriptions) | +| `variant`, `@pothos/plugin-prisma-utils` / Drizzle filter & order inputs | Separate silks named with `.meta({ title })` | Keep original SDL type names; see [Variants and generated inputs](#variants-and-generated-inputs) | Common field options mapping: @@ -82,7 +86,7 @@ Declare ordinary names and descriptions with `z.describe()` or `z.meta()`, and m A model that only reads this page must follow these rules. Each rule is repeated with its snippet later on. -1. MUST save the Pothos SDL before touching code: `printSchema(lexicographicSortSchema(builder.toSchema()))` written to `before.graphql`. The migration is done only when the GQLoom SDL has an empty `diff` and replayed requests return the same JSON. +1. MUST save the Pothos SDL before touching code: `printSchema(lexicographicSortSchema(builder.toSchema()))` written to `before.graphql`. The migration is done only when every module is migrated, the GQLoom SDL has an empty `diff` (aside from any intentionally documented contract changes), and replayed requests return the expected JSON. 2. MUST copy nullability from the printed SDL, never from memory. Pothos 4 prints nullable outputs and optional args unless the builder sets `defaultFieldNullability: false`; Pothos 3 printed non-null outputs. Port every nullable output and every optional input as `.nullish()` (one spelling; `.nullable()` makes TypeScript reject a resolver that returns `undefined`). Everything else is the bare Zod type. 3. MUST turn each Pothos object type into one `z.object({ ... }).meta({ title: "Name" })`. Do not copy `objectRef`, `implement`, or `builder`. 4. MUST define every computed or relational field with `resolver.of(Silk, { name: field(type).resolve((parent) => ...) })`. The parent is the first argument of `resolve`; there is no `t` callback and no `ctx` argument. @@ -94,29 +98,15 @@ A model that only reads this page must follow these rules. Each rule is repeated 10. MUST turn each `authScopes` into a `Middleware`. On operations use `.use(guard)`; on a property of an object use `field(...).use(guard).resolve(...)` inside `resolver.of`. A guard on a query does not protect fields of the object it returns. 11. MUST map `builder.addScalarType` and `Date` to `ZodWeaver.config({ presetGraphQLType })`. Enums are `z.enum([...]).meta({ title })`. Union members are `z.object` with a `__typename` literal, combined by `z.discriminatedUnion("__typename", [...]).meta({ title })`. 12. MUST replace N+1 patterns (`loadableObject`, `t.loadable`, Prisma/Drizzle relation plugins) with `field(...).load(...)` or the resolver factory's `relationField()`. In tests, execute with `contextValue: {}` or batching is disabled. -13. MUST replace `builder.toSchema()` with `weave(ZodWeaver, config, ...resolvers)` (add `asyncContextProvider` only when rule 9 applies). A silk that no resolver can reach is not in the SDL. -14. MUST NOT return an interface silk from a query or field. Declare `asObjectType({ interfaces: [Iface] })` on the implementors and return a union. -15. MUST NOT hand-translate Relay (`builder.node`, `t.connection`), `@pothos/plugin-errors`, `@pothos/plugin-sub-graph`, or `@pothos/plugin-smart-subscriptions`. Stop and keep Pothos for that module. -16. MUST NOT uninstall any `@pothos/*` package or mix `builder` and GQLoom resolvers in one file until rule 1 passes for every module. - -## When to migrate, when to stop - -Migrate when: - -- the schema is plain objects, enums, unions, inputs, and simple resolvers, and the `t.exposeX` and `objectRef` ceremony is the main cost; -- you already keep a Zod or Valibot schema, a Prisma model, or a Drizzle table for each type and Pothos is a third declaration; -- you use `@pothos/plugin-zod` or `@pothos/plugin-validation` only to validate arguments; -- you use `@pothos/plugin-scope-auth` for role checks that a middleware can express. - -Stop and evaluate the architecture first when you depend on: - -- Relay: `builder.node`, `t.connection`, `prismaConnection`, `drizzleConnection`, global IDs. GQLoom has no Relay helpers; you would hand-write the `Connection`, `Edge`, `PageInfo` types and cursor logic, and the SDL will differ. -- `@pothos/plugin-errors`, `@pothos/plugin-sub-graph`, `@pothos/plugin-smart-subscriptions`, and Pothos "variants" (`variant`, `Viewer` style prisma/drizzle variants). They have no GQLoom equivalent. -- Fields whose declared type is a GraphQL interface (for example `node(id): Node`). GQLoom cannot return an interface silk from a field (see [gotchas](#gotchas)); a union changes the SDL. -- `@pothos/plugin-prisma-utils` or `@pothos/plugin-drizzle` generated filter and order inputs. The GQLoom resolver factories generate different input type names, so keep those operations hand-written until clients move. -- Query planning that the Pothos Prisma or Drizzle plugin does across nested selections (a single `include` tree). GQLoom batches per relation field. Measure query counts before and after. - -Migrate module by module. Keep `@pothos/core` installed during the migration. Both `GraphQLSchema` instances can coexist and be combined with [`mergeSchemas`](https://the-guild.dev/graphql/tools/docs/schema-merging), or mounted on separate HTTP endpoints. +13. MUST replace `builder.toSchema()` with `weave(ZodWeaver, config, ...resolvers)` (add `asyncContextProvider` only when rule 9 applies). A silk that no resolver can reach is not in the SDL; pass unreferenced interface or union implementors directly to `weave()`. +14. MUST wrap `new GraphQLInterfaceType({ ... })` with `silk()` when a query or field returns an interface (such as Relay `Node` or `Error`), and reference it in `asObjectType({ interfaces: [Iface] })`. MUST NOT pass a `z.object` interface definition directly to `query()` or `field()` alongside `asObjectType({ interfaces: [Iface] })`—that creates duplicate types with the same name. +15. MUST migrate every Pothos module and plugin completely to GQLoom—never leave a Pothos module behind: + - Relay: model `Node` with `silk(new GraphQLInterfaceType(...))`, and `PageInfo`, `*Edge`, and `*Connection` with Zod silks whose SDL matches `before.graphql`. + - Errors: model result unions (`z.discriminatedUnion` / `z.union`) when `before.graphql` has a union, or throw `GraphQLError` with `extensions` when it does not (documenting the contract change if switching away from a union). + - Sub-graphs: create a separate `weave()` per audience with only the resolvers that audience needs. + - Smart Subscriptions: use ordinary `subscription()` + pubsub and publish explicitly from mutations. + - Variants and generated filter/order inputs: create separate silks using the original SDL type names so clients do not notice. +16. MUST NOT uninstall any `@pothos/*` package or mix `builder` and GQLoom resolvers in one file until every module is migrated and passes rule 1. ## Migration practices @@ -536,7 +526,482 @@ export const postFields = resolver.of(Post, { On the example's data (5 posts, `posts { id author { id } }`), the batch function ran 1 time with a context object and 5 times without one: batching is keyed by the request context object. Servers such as Yoga always provide one; in unit tests pass `contextValue: {}` to `graphql()`. -Check query counts yourself before and after: enable `log: ["query"]` (Prisma) or `logger: true` (Drizzle) and compare the number of statements for the same request. With the ORM plugins, `relationField` replaces `t.relation`; do not assume it produces the same single joined query. +Check query counts yourself before and after: enable `log: ["query"]` (Prisma) or `logger: true` (Drizzle) and compare the number of statements for the same request. With the ORM plugins, `relationField` replaces `t.relation`; do not assume it produces the same single joined query. When a hot path needs a single joined query or `include` / `with` tree instead of per-field batching, write that query explicitly in `resolver` using Prisma `include` (or `useSelectedFields`) or Drizzle `db.query.*.findMany({ with: ... })` (or `useSelectedColumns`). + +### Relay + +`@pothos/plugin-relay` generates the `Node` interface, `node`/`nodes` queries, global IDs, `PageInfo`, `*Edge`, and `*Connection` types. Model every piece with GQLoom silks so `after.graphql` matches `before.graphql` verbatim: + +- Define `Node` with `silk(new GraphQLInterfaceType(...))` (never a `z.object` if a query or field returns `Node`; see rule 14). +- Implement `Node` on each node object via `.register(asObjectType, { interfaces: [Node] })`, override `id` in `resolver.of` to return the encoded global ID (preserving Pothos's `TypeName:id` base64 format), and pass any unreferenced implementor silks to `weave(...)`. +- Define `PageInfo`, `*Edge`, and `*Connection` as Zod object silks whose `.meta({ title })` names and field nullability match `before.graphql` (`z.array(Edge.nullish())` for `[UserEdge]!`, `z.array(Edge.nullish()).nullish()` for `[UserEdge]`, `z.array(Edge)` for `[UserEdge!]!`). + +```ts +// Pothos (@pothos/plugin-relay) +builder.node(User, { + id: { resolve: (user) => user.id }, + loadOne: (id) => usersDb.get(id), + fields: (t) => ({ name: t.exposeString("name") }), +}) + +builder.queryType({ + fields: (t) => ({ + users: t.connection({ + type: User, + resolve: (_root, args) => resolveArrayConnection({ args }, [...usersDb.values()]), + }), + }), +}) +``` + +```ts twoslash +import { field, query, resolver, silk, weave } from "@gqloom/core" +import { ZodWeaver, asField, asObjectType } from "@gqloom/zod" +import { + GraphQLID, + GraphQLInterfaceType, + GraphQLList, + GraphQLNonNull, +} from "graphql" +import * as z from "zod" + +const ID = z.string().register(asField, { type: new GraphQLNonNull(GraphQLID) }) + +function encodeGlobalId(type: string, id: string) { + return Buffer.from(`${type}:${id}`).toString("base64") +} + +function decodeGlobalId(globalId: string) { + const decoded = Buffer.from(globalId, "base64").toString("utf8") + const sep = decoded.indexOf(":") + if (sep === -1) throw new Error(`Invalid global ID: ${globalId}`) + return { type: decoded.slice(0, sep), id: decoded.slice(sep + 1) } +} + +interface INode { + id: string +} + +const NodeInterface = new GraphQLInterfaceType({ + name: "Node", + fields: () => ({ id: { type: new GraphQLNonNull(GraphQLID) } }), + resolveType: (value: { __typename?: string }) => value.__typename, +}) + +const Node = silk(NodeInterface) +const NullableNodeList = silk<(INode | null)[]>( + new GraphQLNonNull(new GraphQLList(NodeInterface)) +) + +const User = z + .object({ + __typename: z.literal("User").nullish(), + id: ID, + name: z.string(), + }) + // Zod v4 registry's $replace drops GraphQLInterfaceType private members + .register(asObjectType, { interfaces: [Node as never] }) + +const PageInfo = z + .object({ + hasNextPage: z.boolean(), + hasPreviousPage: z.boolean(), + startCursor: z.string().nullish(), + endCursor: z.string().nullish(), + }) + .meta({ title: "PageInfo" }) + +function createConnectionSilks( + namePrefix: string, + nodeSilk: TNode +) { + const Edge = z + .object({ cursor: z.string(), node: nodeSilk }) + .meta({ title: `${namePrefix}Edge` }) + const Connection = z + .object({ + pageInfo: PageInfo, + edges: z.array(Edge.nullish()), + }) + .meta({ title: `${namePrefix}Connection` }) + return { Edge, Connection } +} + +const { Connection: UserConnection } = createConnectionSilks("User", User) + +const usersDb = new Map([ + ["1", { id: "1", name: "Ada" }], +]) + +function resolveNode(globalId: string) { + const { type, id } = decodeGlobalId(globalId) + if (type === "User") { + const user = usersDb.get(id) + return user ? { ...user, __typename: "User" as const } : null + } + return null +} + +function paginateSlice( + items: T[], + args: { + first?: number | null + after?: string | null + last?: number | null + before?: string | null + } +) { + const decodeCursor = (c: string) => + Number(Buffer.from(c, "base64").toString("utf8").replace("cursor:", "")) + const encodeCursor = (idx: number) => + Buffer.from(`cursor:${idx}`).toString("base64") + + const start = args.after ? Math.max(0, decodeCursor(args.after) + 1) : 0 + const end = args.before + ? Math.min(items.length, decodeCursor(args.before)) + : items.length + const window = items.slice(start, end) + const sliced = + args.first != null + ? window.slice(0, args.first) + : args.last != null + ? window.slice(Math.max(0, window.length - args.last)) + : window + + const edges = sliced.map((node, i) => ({ + cursor: encodeCursor(start + i), + node, + })) + return { + edges, + pageInfo: { + hasPreviousPage: start > 0, + hasNextPage: start + sliced.length < end, + startCursor: edges[0]?.cursor ?? null, + endCursor: edges.at(-1)?.cursor ?? null, + }, + } +} + +const userFields = resolver.of(User, { + id: field(ID).resolve((user) => encodeGlobalId("User", user.id)), +}) + +const relayQueries = resolver({ + node: query(silk.nullable(Node)) + .input({ id: ID }) + .resolve(({ id }) => resolveNode(id)), + nodes: query(NullableNodeList) + .input({ ids: z.array(ID) }) + .resolve(({ ids }) => ids.map((id) => resolveNode(id))), + users: query(UserConnection) + .input({ + first: z.int().nullish(), + after: z.string().nullish(), + last: z.int().nullish(), + before: z.string().nullish(), + }) + .resolve((args) => paginateSlice([...usersDb.values()], args)), +}) + +export const schema = weave(ZodWeaver, relayQueries, userFields, User) +``` + +For nested connection fields on an object (`t.connection` / `t.relatedConnection`), add `field(PostConnection).input({ ... }).resolve(...)` (or `.load(...)` for batching) inside `resolver.of(User, { ... })`. If `before.graphql` uses `ID` for cursors (`cursorType: "ID"`), swap `z.string()` on `cursor`, `startCursor`, `endCursor`, `after`, and `before` for `NullableID` / `ID`. If you use Drizzle or Prisma column selection alongside the `id` override above, chain `.derivedFrom("id")` on `id: field(ID)` so the primary key is always fetched. + +### Errors + +Check `before.graphql` to choose between the two GQLoom patterns: + +1. **Original SDL has a result union** (`union MutationCreatePostResult = BaseError | MutationCreatePostSuccess` or `directResult: true` unions): keep the exact SDL using `silk(new GraphQLInterfaceType(...))` for `Error` and `z.discriminatedUnion` (or `z.union` with `asUnionType`) for the result union. +2. **Original SDL does not have a union** (or you intentionally migrate away from error unions): throw `new GraphQLError(message, { extensions: { code } })` inside resolvers or map domain error classes in a global middleware passed to `weave`. + +```ts twoslash +import { mutation, query, resolver, silk, weave, type Middleware } from "@gqloom/core" +import { ZodWeaver, asField, asObjectType } from "@gqloom/zod" +import { + GraphQLError, + GraphQLID, + GraphQLInterfaceType, + GraphQLNonNull, + GraphQLString, +} from "graphql" +import * as z from "zod" + +const ID = z.string().register(asField, { type: new GraphQLNonNull(GraphQLID) }) +const Post = z.object({ id: ID, title: z.string() }).meta({ title: "Post" }) + +// Option A: before.graphql has a result union (SDL unchanged) +const ErrorInterface = silk<{ message: string }>( + new GraphQLInterfaceType({ + name: "Error", + fields: () => ({ message: { type: new GraphQLNonNull(GraphQLString) } }), + resolveType: (value: { __typename?: string }) => value.__typename, + }) +) + +const BaseError = z + .object({ __typename: z.literal("BaseError"), message: z.string() }) + // Zod v4 registry's $replace drops GraphQLInterfaceType private members + .register(asObjectType, { interfaces: [ErrorInterface as never] }) + +const MutationCreatePostSuccess = z + .object({ + __typename: z.literal("MutationCreatePostSuccess"), + data: Post, + }) + .meta({ title: "MutationCreatePostSuccess" }) + +const MutationCreatePostResult = z + .discriminatedUnion("__typename", [BaseError, MutationCreatePostSuccess]) + .meta({ title: "MutationCreatePostResult" }) + +// Option B: no union in SDL -> throw GraphQLError with extensions +class NotFoundError extends Error { + public readonly code = "NOT_FOUND" +} + +const mapDomainErrors: Middleware = async (next) => { + try { + return await next() + } catch (err) { + if (err instanceof NotFoundError) { + throw new GraphQLError(err.message, { extensions: { code: err.code } }) + } + throw err + } +} + +const postResolver = resolver({ + post: query(Post).input({ id: ID }).resolve(() => { + throw new NotFoundError("Post not found") + }), + createPost: mutation(MutationCreatePostResult) + .input({ title: z.string() }) + .resolve(({ title }) => { + if (!title.trim()) { + return { __typename: "BaseError", message: "Title is required" } + } + return { + __typename: "MutationCreatePostSuccess", + data: { id: "1", title }, + } + }), +}) + +export const schema = weave(ZodWeaver, mapDomainErrors, postResolver) +``` + +For Pothos `directResult: true` unions (for example `union CreatePostResult = BaseError | Post`), use `z.union([BaseError, Post]).register(asUnionType, { name: "CreatePostResult", resolveType: (v) => ("message" in v ? "BaseError" : "Post") })`. + +Contract change when switching away from an error union to `GraphQLError`: `interface Error`, `*Error`, `*Success`, and `union *Result` are removed from the SDL, and the operation returns `Post!` (or `Post`) directly. Runtime errors move from `data.` (`{ __typename: "BaseError", message }`) to the top-level `errors` array (`errors[0].extensions.code`) with `data.: null` (or `data: null` if non-null). Update clients to drop `... on *Success` / `... on Error` fragments, select fields directly on the return type, and inspect `result.errors`. + +### Sub-graphs + +`@pothos/plugin-sub-graph` tags fields and types on a shared builder and emits filtered schemas with `builder.toSchema({ subGraph })`. In GQLoom, compose a separate `weave()` call for each audience, passing only the resolvers and silks that audience should see: + +```ts twoslash +import { field, query, resolver, weave } from "@gqloom/core" +import { ZodWeaver } from "@gqloom/zod" +import * as z from "zod" + +const User = z + .object({ + id: z.string(), + name: z.string(), + internalNotes: z.string(), + }) + .meta({ title: "User" }) + +// Hide internal-only columns in the public sub-graph without affecting other weaves +const publicUserFields = resolver.of(User, { + internalNotes: field.hidden, +}) + +const publicQueries = resolver({ + user: query(User.nullish()).resolve(() => null), +}) + +const internalQueries = resolver({ + user: query(User.nullish()).resolve(() => null), + auditLog: query(z.array(z.string())).resolve(() => []), +}) + +export const publicSchema = weave(ZodWeaver, publicQueries, publicUserFields) +export const internalSchema = weave(ZodWeaver, internalQueries) +``` + +Each `weave()` runs in its own isolated context, so `field.hidden` in `publicUserFields` only hides `internalNotes` from `publicSchema`. Any type reachable only from `internalQueries` is omitted automatically from `publicSchema`. Add `asyncContextProvider` to every `weave()` whose resolvers or middlewares call `useContext()`. Diff each audience schema separately (`before.public.graphql` vs `after.public.graphql`). + +### Smart Subscriptions + +`@pothos/plugin-smart-subscriptions` hooks live invalidation into queries and fields via topic registration. In GQLoom, replace it with standard `subscription()` operations backed by a pubsub (such as `createPubSub` from `graphql-yoga`, or Redis pubsub in multi-instance deployments), and call `pubSub.publish(...)` explicitly from mutations: + +```ts twoslash +import { mutation, query, resolver, subscription, weave } from "@gqloom/core" +import { ZodWeaver } from "@gqloom/zod" +import { createPubSub } from "graphql-yoga" +import * as z from "zod" + +const Post = z.object({ id: z.string(), title: z.string() }).meta({ title: "Post" }) +type IPost = z.infer + +const pubSub = createPubSub<{ + postsUpdated: [] + postUpdated: [postId: string, post: IPost] +}>() + +const postsStore: IPost[] = [] + +export const postResolver = resolver({ + posts: query(z.array(Post)).resolve(() => postsStore), + + createPost: mutation(Post) + .input({ title: z.string() }) + .resolve(({ title }) => { + const post = { id: String(postsStore.length + 1), title } + postsStore.push(post) + pubSub.publish("postsUpdated") + pubSub.publish("postUpdated", post.id, post) + return post + }), + + watchPosts: subscription(z.array(Post)) + .subscribe(() => pubSub.subscribe("postsUpdated")) + .resolve(() => postsStore), + + watchPost: subscription(Post) + .input({ id: z.string() }) + .subscribe(({ id }) => pubSub.subscribe("postUpdated", id)) + .resolve((post) => post), +}) + +export const schema = weave(ZodWeaver, postResolver) +``` + +Contract and behavior differences to account for: + +- If `before.graphql` already exposed the field on `type Subscription`, matching the field name, input args, and output silk keeps the SDL identical. +- If Pothos Smart Subscriptions exposed a live field on `type Query` or relied on automatic child-type invalidation (for example, re-running a `posts` subscription automatically whenever a nested `Comment` mutated), GQLoom does not turn `Query` fields into subscriptions or track nested selection dependencies implicitly. Move any live operation onto `Subscription` (clients send `subscription { ... }` instead of a smart `query`), and publish all affected parent and item topics explicitly from every relevant mutation or domain service. + +### Variants and generated inputs + +One ORM silk maps to one GraphQL object type name (`User` or `users`), and GQLoom's resolver factories emit their own input type names (`UserWhereInput`, `UsersFilters`, `UsersOrderBy`). To preserve Pothos `variant` types and `@pothos/plugin-prisma-utils` / `@pothos/plugin-drizzle` generated filter and order input types without changing the SDL, define separate silks with the original SDL names: + +```ts twoslash +import { field, query, resolver, weave } from "@gqloom/core" +import { asyncContextProvider } from "@gqloom/core/context" +import { DrizzleWeaver, drizzleSilk } from "@gqloom/drizzle" +import { useSelectedColumns } from "@gqloom/drizzle/context" +import { ZodWeaver, asField } from "@gqloom/zod" +import { and, asc, desc, eq, ilike, or, type SQL } from "drizzle-orm" +import * as t from "drizzle-orm/sqlite-core" +import { GraphQLID, GraphQLNonNull } from "graphql" +import * as z from "zod" + +const IntID = z.int().register(asField, { type: new GraphQLNonNull(GraphQLID) }) + +const users = drizzleSilk( + t.sqliteTable("users", { + id: t.int().primaryKey({ autoIncrement: true }), + email: t.text().notNull(), + firstName: t.text().notNull(), + lastName: t.text().notNull(), + passwordHash: t.text().notNull(), + }), + { name: "User" } +) + +// Variant: separate silk with the original SDL type name "Viewer" +const Viewer = z + .object({ + id: IntID, + email: z.string(), + firstName: z.string(), + lastName: z.string(), + }) + .meta({ title: "Viewer" }) + +const viewerFields = resolver.of(Viewer, { + firstName: field.hidden, + lastName: field.hidden, + fullName: field(z.string()) + .derivedFrom("firstName", "lastName") + .resolve((u) => `${u.firstName} ${u.lastName}`), +}) + +// Generated filter & order inputs: match exact names from before.graphql +const OrderBy = z.enum(["asc", "desc"]).meta({ title: "OrderBy" }) + +const StringFilter = z + .object({ + equals: z.string().nullish(), + contains: z.string().nullish(), + }) + .meta({ title: "StringFilter" }) + +const UserFilter = z + .object({ + email: StringFilter.nullish(), + get AND() { + return z.array(UserFilter).nullish() + }, + get OR() { + return z.array(UserFilter).nullish() + }, + }) + .meta({ title: "UserFilter" }) + +const UserOrderBy = z + .object({ email: OrderBy.nullish() }) + .meta({ title: "UserOrderBy" }) + +function toUserWhere(filter?: z.infer | null): SQL | undefined { + if (!filter) return undefined + const parts: (SQL | undefined)[] = [] + if (filter.email?.equals != null) parts.push(eq(users.email, filter.email.equals)) + if (filter.email?.contains != null) { + parts.push(ilike(users.email, `%${filter.email.contains}%`)) + } + if (filter.AND?.length) parts.push(and(...filter.AND.map(toUserWhere))) + if (filter.OR?.length) parts.push(or(...filter.OR.map(toUserWhere))) + return and(...parts) +} + +const userResolver = resolver.of(users, { + passwordHash: field.hidden, + viewer: query(Viewer.nullish()).resolve(() => { + const columns = useSelectedColumns(users) + void columns + return { id: 1, email: "ada@example.com", firstName: "Ada", lastName: "Lovelace" } + }), + users: query(users.$list()) + .input({ + where: UserFilter.nullish(), + orderBy: z.array(UserOrderBy).nullish(), + }) + .resolve(({ where, orderBy }) => { + void toUserWhere(where) + void orderBy?.map((o) => + o.email === "desc" ? desc(users.email) : asc(users.email) + ) + return [] + }), +}) + +export const schema = weave( + ZodWeaver, + DrizzleWeaver, + asyncContextProvider, + userResolver, + viewerFields +) +``` + +Note two details when preserving Pothos filter/order inputs: + +- Keep `.meta({ title })` directly on the `z.object(...)` (or inside `z.lazy(() => z.object(...).meta({ title }))`, not outside `z.lazy`); otherwise GQLoom auto-aliases the input type name from the query and field names. +- Match operator semantics during request replay—for example, `ilike` vs `like` in Drizzle or `mode: "insensitive"` in Prisma—so filtered query results match Pothos as well as the SDL. ## Gotchas @@ -591,7 +1056,9 @@ Each item shows the wrong result that was observed and the fix. }) ``` -- Interface-typed fields. `query(Node)` where `Node` is also used in `asObjectType({ interfaces: [Node] })` fails with `Schema must contain uniquely named types but contains multiple types named "Node"`. Return a union of the implementors (`z.discriminatedUnion("__typename", [Dog, Cat])`) and tell clients to use inline fragments; the SDL changes, so treat it as a contract change. +- Interface-typed fields. `query(Node)` where `Node` is a `z.object` also used in `asObjectType({ interfaces: [Node] })` fails with `Schema must contain uniquely named types but contains multiple types named "Node"`. To return a GraphQL interface without changing the SDL (such as Relay `Node` or `Error`), wrap `new GraphQLInterfaceType({ ... })` with `silk()` and pass any unreferenced implementors to `weave(...)`. Only use `z.discriminatedUnion("__typename", [Dog, Cat])` if you intentionally want to replace the interface with a union (a contract change requiring clients to use inline fragments). + +- Putting `.meta({ title })` outside `z.lazy(...)` on recursive input types causes GQLoom to ignore the title and auto-alias the type from the operation and field names (for example `FilterPostsWhereInput` instead of `PostWhereInput`). Put `.meta({ title })` on the `z.object(...)` inside `z.lazy`, or use Zod v4 getter syntax (`get AND() { ... }`). - Validation: GQLoom validates arguments against the Zod schema before `resolve`. A failure rejects the request with `extensions.issues` (for example `{"message":"Invalid email address","extensions":{"issues":[...]}}`). Update clients that parse the error shape of `@pothos/plugin-zod` or `@pothos/plugin-validation`. @@ -604,7 +1071,7 @@ Each item shows the wrong result that was observed and the fix. ## Verification -The goal of migration is an unchanged contract and unchanged behavior. +The goal of migration is an unchanged contract and unchanged behavior (with any unavoidable contract changes—such as dropping an error union for `GraphQLError` or moving a smart subscription to `Subscription`—explicitly documented). 1. Before any change, print the Pothos SDL: @@ -622,7 +1089,7 @@ The goal of migration is an unchanged contract and unchanged behavior. diff before.graphql after.graphql ``` - The output must be empty. Fix the schema, not the file. + The output must be empty (or show only the intentional contract changes you documented). Fix the schema, not the file. 3. Replay requests against both schemas and compare the JSON. The same four requests are used for the reference port: @@ -904,9 +1371,11 @@ After every module passes the SDL diff and request replay: ```sh npm uninstall @pothos/core @pothos/plugin-prisma @pothos/plugin-drizzle \ - @pothos/plugin-scope-auth @pothos/plugin-dataloader @pothos/plugin-relay \ - @pothos/plugin-zod @pothos/plugin-validation @pothos/plugin-with-input \ - @pothos/plugin-simple-objects @pothos/plugin-complexity dataloader + @pothos/plugin-prisma-utils @pothos/plugin-scope-auth @pothos/plugin-dataloader \ + @pothos/plugin-relay @pothos/plugin-errors @pothos/plugin-sub-graph \ + @pothos/plugin-smart-subscriptions @pothos/plugin-zod @pothos/plugin-validation \ + @pothos/plugin-with-input @pothos/plugin-simple-objects @pothos/plugin-complexity \ + @pothos/plugin-federation dataloader ``` Keep `dataloader` only if other code imports it. Run the equivalent `pnpm remove`, `yarn remove`, or `bun remove`. diff --git a/website/zh/docs/migrations/from-pothos.md b/website/zh/docs/migrations/from-pothos.md index a34c2261..50b104ce 100644 --- a/website/zh/docs/migrations/from-pothos.md +++ b/website/zh/docs/migrations/from-pothos.md @@ -55,7 +55,7 @@ GQLoom 则秉持**以运行时类型为中心的编织(Weaving)理念**。 | `t.arg.*` / `args` | `.input({ ... })` | 参数合并为一个对象 | | `builder.enumType` | `z.enum([...]).meta({ title })` | | | `builder.unionType` + `resolveType` | `z.discriminatedUnion("__typename", [...]).meta({ title })` | 或 `z.union` 配合 `asUnionType` / `resolveType` | -| `builder.interfaceType` + `interfaces: [I]` | `asObjectType({ interfaces: [I] })` | 禁止直接返回接口 Silk(见[陷阱](#陷阱)) | +| `builder.interfaceType` + `interfaces: [I]` | `silk(new GraphQLInterfaceType(...))` + `asObjectType({ interfaces: [I] })` | 操作需要返回接口本身时用 `silk()` 包装 `GraphQLInterfaceType`;未直接引用的实现类型传入 `weave()` | | `builder.scalarType` / `addScalarType` | `ZodWeaver.config({ presetGraphQLType })` 或 `asField({ type })` | `Date`(`z.ZodDate`)在 `presetGraphQLType` 中全局映射 | | `context` 参数 | [`useContext()`](../context.md) | 必须传入 `asyncContextProvider` | | `info` 参数 | `useResolverPayload().info` | | @@ -67,7 +67,11 @@ GQLoom 则秉持**以运行时类型为中心的编织(Weaving)理念**。 | `@pothos/plugin-simple-objects`(`builder.simpleObject`) | `z.object` | | | `@pothos/plugin-with-input`(`t.fieldWithInput`) | `.input({ input: NamedInputSilk })` | 显式命名输入 Silk | | `@pothos/plugin-prisma` / `@pothos/plugin-drizzle` | 解析器工厂与 `relationField` | 见 [Prisma 与 Drizzle 插件](#prisma-与-drizzle-插件) | -| `@pothos/plugin-relay`、`-errors`、`-sub-graph`、`-smart-subscriptions` | 停止,该模块保留 Pothos | 见[何时迁移与何时停止](#何时迁移与何时停止) | +| `@pothos/plugin-relay`(`builder.node`、`t.connection`) | 用 `silk(new GraphQLInterfaceType(...))` 定义 `Node`;用 Zod Silk 定义 `PageInfo`、`*Edge`、`*Connection` | 保持 SDL 与 ID/游标编码完全一致;见 [Relay](#relay) | +| `@pothos/plugin-errors`(`errors: { types }`) | 结果联合类型(`z.discriminatedUnion` / `z.union`)或带 `extensions` 的 `GraphQLError` | 按 `before.graphql` 是否已有联合类型选择;见[错误处理](#错误处理) | +| `@pothos/plugin-sub-graph`(`subGraphs`) | 按受众分别调用 `weave()` | 每个 `weave()` 只传入该受众所需的解析器;见[子图](#子图) | +| `@pothos/plugin-smart-subscriptions`(`smartSubscriptions`) | `subscription()` + pubsub(`createPubSub`) | 在 mutation 中显式发布事件;见[智能订阅](#智能订阅) | +| `variant`、`@pothos/plugin-prisma-utils` / Drizzle 过滤与排序输入 | 独立的命名 Silk(`.meta({ title })`) | 保留原 SDL 类型名称;见[变体与生成的输入](#变体与生成的输入) | 常用字段选项映射: @@ -82,7 +86,7 @@ GQLoom 则秉持**以运行时类型为中心的编织(Weaving)理念**。 只读这一页的模型也必须遵守下列规则。每条规则在后文都有对应代码。 -1. 必须在改动代码前保存 Pothos 的 SDL:把 `printSchema(lexicographicSortSchema(builder.toSchema()))` 写入 `before.graphql`。只有当 GQLoom 的 SDL `diff` 为空,且重放的请求返回相同 JSON 时,迁移才算完成。 +1. 必须在改动代码前保存 Pothos 的 SDL:把 `printSchema(lexicographicSortSchema(builder.toSchema()))` 写入 `before.graphql`。只有当所有模块都已完成迁移、GQLoom 的 SDL `diff` 为空(或仅包含已明确记录的契约变更),且重放的请求返回预期 JSON 时,迁移才算完成。 2. 必须从打印出的 SDL 抄可空性,不要凭记忆。Pothos 4 在 builder 未设置 `defaultFieldNullability: false` 时输出可空字段、可选参数;Pothos 3 输出非空字段。每个可空输出与每个可选输入都写成 `.nullish()`(统一写法;`.nullable()` 会让 TypeScript 拒绝返回 `undefined` 的解析函数),其余使用不带修饰的 Zod 类型。 3. 必须把每个 Pothos 对象类型改写为一个 `z.object({ ... }).meta({ title: "Name" })`。不要照搬 `objectRef`、`implement`、`builder`。 4. 必须用 `resolver.of(Silk, { name: field(type).resolve((parent) => ...) })` 定义每个计算字段或关联字段。parent 是 `resolve` 的第一个参数;没有 `t` 回调,也没有 `ctx` 参数。 @@ -94,29 +98,15 @@ GQLoom 则秉持**以运行时类型为中心的编织(Weaving)理念**。 10. 必须把每个 `authScopes` 改写为 `Middleware`。操作使用 `.use(guard)`;对象的属性使用 `resolver.of` 中的 `field(...).use(guard).resolve(...)`。加在 query 上的守卫不会保护其返回对象的字段。 11. 必须把 `builder.addScalarType` 与 `Date` 映射到 `ZodWeaver.config({ presetGraphQLType })`。枚举写成 `z.enum([...]).meta({ title })`。联合成员是带 `__typename` 字面量的 `z.object`,用 `z.discriminatedUnion("__typename", [...]).meta({ title })` 组合。 12. 必须用 `field(...).load(...)` 或解析器工厂的 `relationField()` 替代 N+1 写法(`loadableObject`、`t.loadable`、Prisma/Drizzle 关联插件)。测试中执行时要传入 `contextValue: {}`,否则批处理不会生效。 -13. 必须用 `weave(ZodWeaver, config, ...resolvers)` 替代 `builder.toSchema()`(仅在规则 9 适用时才加入 `asyncContextProvider`)。没有任何解析器可达的 Silk 不会出现在 SDL 中。 -14. 禁止从 query 或字段返回接口 Silk。在实现类型上声明 `asObjectType({ interfaces: [Iface] })`,并返回联合类型。 -15. 禁止凭猜测手工翻译 Relay(`builder.node`、`t.connection`)、`@pothos/plugin-errors`、`@pothos/plugin-sub-graph`、`@pothos/plugin-smart-subscriptions`。应当停下,该模块继续使用 Pothos。 -16. 在每个模块都通过规则 1 之前,禁止卸载任何 `@pothos/*` 包,也禁止在同一文件中混用 `builder` 与 GQLoom 解析器。 - -## 何时迁移与何时停止 - -适合迁移的情形: - -- Schema 主要是普通对象、枚举、联合、输入与简单解析函数,`t.exposeX` 与 `objectRef` 的样板代码是主要成本; -- 项目已经为每个类型维护了 Zod 或 Valibot Schema、Prisma 模型或 Drizzle 表,Pothos 成了第三份声明; -- 只是为了校验参数才使用 `@pothos/plugin-zod` 或 `@pothos/plugin-validation`; -- 使用 `@pothos/plugin-scope-auth` 做中间件即可表达的角色检查。 - -出现下列依赖时,请先评估架构,不要直接迁移: - -- Relay:`builder.node`、`t.connection`、`prismaConnection`、`drizzleConnection`、全局 ID。GQLoom 没有 Relay 辅助工具,需要手写 `Connection`、`Edge`、`PageInfo` 类型与游标逻辑,且 SDL 会不同。 -- `@pothos/plugin-errors`、`@pothos/plugin-sub-graph`、`@pothos/plugin-smart-subscriptions` 以及 Pothos 的“变体”(`variant`、`Viewer` 风格的 Prisma/Drizzle 变体)。GQLoom 没有对应能力。 -- 声明类型为 GraphQL 接口的字段(例如 `node(id): Node`)。GQLoom 无法从字段返回接口 Silk(见[陷阱](#陷阱));改用联合会改变 SDL。 -- `@pothos/plugin-prisma-utils` 或 `@pothos/plugin-drizzle` 生成的过滤与排序输入。GQLoom 解析器工厂生成的输入类型名不同,在客户端迁移之前请保持这些操作手写。 -- Pothos 的 Prisma/Drizzle 插件在嵌套选择集上做的查询规划(单个 `include` 树)。GQLoom 按关联字段分批加载。请在迁移前后对比查询次数。 - -按模块逐步迁移。迁移期间保留 `@pothos/core`。两个 `GraphQLSchema` 实例可以共存,并通过 [`mergeSchemas`](https://the-guild.dev/graphql/tools/docs/schema-merging) 合并,或分别挂载到不同的 HTTP 路由。 +13. 必须用 `weave(ZodWeaver, config, ...resolvers)` 替代 `builder.toSchema()`(仅在规则 9 适用时才加入 `asyncContextProvider`)。没有任何解析器可达的 Silk 不会出现在 SDL 中;未直接被操作引用的接口或联合实现类型需直接传给 `weave()`。 +14. 当 query 或字段需要返回接口本身(例如 Relay `Node` 或 `Error`)时,必须用 `silk()` 包装 `new GraphQLInterfaceType({ ... })`,并在实现类型中通过 `asObjectType({ interfaces: [Iface] })` 引用它。禁止把用 `z.object` 定义的接口 Silk 直接传给 `query()` 或 `field()` 并同时在 `asObjectType({ interfaces: [Iface] })` 中引用它,否则 `weave()` 会因重名类型报错。 +15. 必须把所有 Pothos 模块与插件彻底迁移到 GQLoom,绝不遗留任何 Pothos 模块: + - Relay:用 `silk(new GraphQLInterfaceType(...))` 定义 `Node`,用 Zod Silk 定义 `PageInfo`、`*Edge`、`*Connection`,保持 SDL 与 `before.graphql` 一致。 + - Errors:如果 `before.graphql` 含有结果联合类型,就编织为结果联合(`z.discriminatedUnion` / `z.union`);否则抛出带 `extensions` 的 `GraphQLError`(若主动去掉联合类型,需写明契约变更)。 + - Sub-graphs:为每个受众单独调用一次 `weave()`,只传入该受众需要的解析器。 + - Smart Subscriptions:改用普通 `subscription()` + pubsub,并在 mutation 中显式发布事件。 + - 变体与生成的过滤/排序输入:分别定义独立 Silk,并保留原有的 SDL 类型名称,让客户端无感知。 +16. 在每个模块都完成迁移并通过规则 1 之前,禁止卸载任何 `@pothos/*` 包,也禁止在同一文件中混用 `builder` 与 GQLoom 解析器。 ## 关键迁移实践 @@ -536,7 +526,482 @@ export const postFields = resolver.of(Post, { 在示例数据上(5 篇文章,查询 `posts { id author { id } }`),传入上下文对象时批处理函数只执行 1 次,不传上下文对象时执行 5 次:批处理以请求上下文对象为键。Yoga 等服务端总会提供上下文对象;在单元测试中调用 `graphql()` 时请传入 `contextValue: {}`。 -迁移前后请自行核对查询次数:开启 `log: ["query"]`(Prisma)或 `logger: true`(Drizzle),对比同一请求的语句条数。使用 ORM 插件时,`relationField` 替代 `t.relation`;不要假设它会生成同样的单条联表查询。 +迁移前后请自行核对查询次数:开启 `log: ["query"]`(Prisma)或 `logger: true`(Drizzle),对比同一请求的语句条数。使用 ORM 插件时,`relationField` 替代 `t.relation`;不要假设它会生成同样的单条联表查询。若热点路径需要单条联表查询或 `include` / `with` 树而非逐字段批处理,可在 `resolver` 中显式使用 Prisma 的 `include`(或 `useSelectedFields`)与 Drizzle 的 `db.query.*.findMany({ with: ... })`(或 `useSelectedColumns`)编写该查询。 + +### Relay + +`@pothos/plugin-relay` 会生成 `Node` 接口、`node`/`nodes` 查询、全局 ID、`PageInfo`、`*Edge` 与 `*Connection` 类型。用 GQLoom 的 Silk 对每一部分进行建模,使 `after.graphql` 与 `before.graphql` 完全一致: + +- 用 `silk(new GraphQLInterfaceType(...))` 定义 `Node`(当有 query 或字段返回 `Node` 时,切勿用 `z.object` 定义接口;见规则 14)。 +- 通过 `.register(asObjectType, { interfaces: [Node] })` 让节点类型实现 `Node`,在 `resolver.of` 中覆写 `id` 以返回编码后的全局 ID(保留 Pothos 的 `TypeName:id` base64 格式),并将未被其他操作直接引用的实现类型传入 `weave(...)`。 +- 将 `PageInfo`、`*Edge`、`*Connection` 定义为 Zod 对象 Silk,使 `.meta({ title })` 名称与字段可空性与 `before.graphql` 一一对应(`[UserEdge]!` 对应 `z.array(Edge.nullish())`,`[UserEdge]` 对应 `z.array(Edge.nullish()).nullish()`,`[UserEdge!]!` 对应 `z.array(Edge)`)。 + +```ts +// Pothos (@pothos/plugin-relay) +builder.node(User, { + id: { resolve: (user) => user.id }, + loadOne: (id) => usersDb.get(id), + fields: (t) => ({ name: t.exposeString("name") }), +}) + +builder.queryType({ + fields: (t) => ({ + users: t.connection({ + type: User, + resolve: (_root, args) => resolveArrayConnection({ args }, [...usersDb.values()]), + }), + }), +}) +``` + +```ts twoslash +import { field, query, resolver, silk, weave } from "@gqloom/core" +import { ZodWeaver, asField, asObjectType } from "@gqloom/zod" +import { + GraphQLID, + GraphQLInterfaceType, + GraphQLList, + GraphQLNonNull, +} from "graphql" +import * as z from "zod" + +const ID = z.string().register(asField, { type: new GraphQLNonNull(GraphQLID) }) + +function encodeGlobalId(type: string, id: string) { + return Buffer.from(`${type}:${id}`).toString("base64") +} + +function decodeGlobalId(globalId: string) { + const decoded = Buffer.from(globalId, "base64").toString("utf8") + const sep = decoded.indexOf(":") + if (sep === -1) throw new Error(`Invalid global ID: ${globalId}`) + return { type: decoded.slice(0, sep), id: decoded.slice(sep + 1) } +} + +interface INode { + id: string +} + +const NodeInterface = new GraphQLInterfaceType({ + name: "Node", + fields: () => ({ id: { type: new GraphQLNonNull(GraphQLID) } }), + resolveType: (value: { __typename?: string }) => value.__typename, +}) + +const Node = silk(NodeInterface) +const NullableNodeList = silk<(INode | null)[]>( + new GraphQLNonNull(new GraphQLList(NodeInterface)) +) + +const User = z + .object({ + __typename: z.literal("User").nullish(), + id: ID, + name: z.string(), + }) + // Zod v4 registry 的 $replace 会去掉 GraphQLInterfaceType 的私有成员 + .register(asObjectType, { interfaces: [Node as never] }) + +const PageInfo = z + .object({ + hasNextPage: z.boolean(), + hasPreviousPage: z.boolean(), + startCursor: z.string().nullish(), + endCursor: z.string().nullish(), + }) + .meta({ title: "PageInfo" }) + +function createConnectionSilks( + namePrefix: string, + nodeSilk: TNode +) { + const Edge = z + .object({ cursor: z.string(), node: nodeSilk }) + .meta({ title: `${namePrefix}Edge` }) + const Connection = z + .object({ + pageInfo: PageInfo, + edges: z.array(Edge.nullish()), + }) + .meta({ title: `${namePrefix}Connection` }) + return { Edge, Connection } +} + +const { Connection: UserConnection } = createConnectionSilks("User", User) + +const usersDb = new Map([ + ["1", { id: "1", name: "Ada" }], +]) + +function resolveNode(globalId: string) { + const { type, id } = decodeGlobalId(globalId) + if (type === "User") { + const user = usersDb.get(id) + return user ? { ...user, __typename: "User" as const } : null + } + return null +} + +function paginateSlice( + items: T[], + args: { + first?: number | null + after?: string | null + last?: number | null + before?: string | null + } +) { + const decodeCursor = (c: string) => + Number(Buffer.from(c, "base64").toString("utf8").replace("cursor:", "")) + const encodeCursor = (idx: number) => + Buffer.from(`cursor:${idx}`).toString("base64") + + const start = args.after ? Math.max(0, decodeCursor(args.after) + 1) : 0 + const end = args.before + ? Math.min(items.length, decodeCursor(args.before)) + : items.length + const window = items.slice(start, end) + const sliced = + args.first != null + ? window.slice(0, args.first) + : args.last != null + ? window.slice(Math.max(0, window.length - args.last)) + : window + + const edges = sliced.map((node, i) => ({ + cursor: encodeCursor(start + i), + node, + })) + return { + edges, + pageInfo: { + hasPreviousPage: start > 0, + hasNextPage: start + sliced.length < end, + startCursor: edges[0]?.cursor ?? null, + endCursor: edges.at(-1)?.cursor ?? null, + }, + } +} + +const userFields = resolver.of(User, { + id: field(ID).resolve((user) => encodeGlobalId("User", user.id)), +}) + +const relayQueries = resolver({ + node: query(silk.nullable(Node)) + .input({ id: ID }) + .resolve(({ id }) => resolveNode(id)), + nodes: query(NullableNodeList) + .input({ ids: z.array(ID) }) + .resolve(({ ids }) => ids.map((id) => resolveNode(id))), + users: query(UserConnection) + .input({ + first: z.int().nullish(), + after: z.string().nullish(), + last: z.int().nullish(), + before: z.string().nullish(), + }) + .resolve((args) => paginateSlice([...usersDb.values()], args)), +}) + +export const schema = weave(ZodWeaver, relayQueries, userFields, User) +``` + +对象上的嵌套连接字段(`t.connection` / `t.relatedConnection`)可以在 `resolver.of(User, { ... })` 中用 `field(PostConnection).input({ ... }).resolve(...)`(或 `.load(...)` 进行批处理)定义。如果 `before.graphql` 中游标使用了 `ID`(`cursorType: "ID"`),请把 `cursor`、`startCursor`、`endCursor`、`after`、`before` 上的 `z.string()` 替换为 `NullableID` / `ID`。若配合 Drizzle 或 Prisma 的按列裁剪功能使用上面的 `id` 覆写,请在 `id: field(ID)` 上链式调用 `.derivedFrom("id")`,确保主键始终被查询出来。 + +### 错误处理 + +先查看 `before.graphql` 再二选一: + +1. **原 SDL 包含结果联合类型**(如 `union MutationCreatePostResult = BaseError | MutationCreatePostSuccess` 或 `directResult: true` 联合类型):用 `silk(new GraphQLInterfaceType(...))` 定义 `Error` 接口,并用 `z.discriminatedUnion`(或 `z.union` + `asUnionType`)定义结果联合类型,保持 SDL 完全不变。 +2. **原 SDL 不含结果联合类型**(或明确决定改用标准 GraphQL 错误):在解析器中直接抛出 `new GraphQLError(message, { extensions: { code } })`,或在传入 `weave` 的全局中间件中把领域异常映射为 `GraphQLError`。 + +```ts twoslash +import { mutation, query, resolver, silk, weave, type Middleware } from "@gqloom/core" +import { ZodWeaver, asField, asObjectType } from "@gqloom/zod" +import { + GraphQLError, + GraphQLID, + GraphQLInterfaceType, + GraphQLNonNull, + GraphQLString, +} from "graphql" +import * as z from "zod" + +const ID = z.string().register(asField, { type: new GraphQLNonNull(GraphQLID) }) +const Post = z.object({ id: ID, title: z.string() }).meta({ title: "Post" }) + +// 方案 A:before.graphql 中已有结果联合类型(SDL 不变) +const ErrorInterface = silk<{ message: string }>( + new GraphQLInterfaceType({ + name: "Error", + fields: () => ({ message: { type: new GraphQLNonNull(GraphQLString) } }), + resolveType: (value: { __typename?: string }) => value.__typename, + }) +) + +const BaseError = z + .object({ __typename: z.literal("BaseError"), message: z.string() }) + // Zod v4 registry 的 $replace 会去掉 GraphQLInterfaceType 的私有成员 + .register(asObjectType, { interfaces: [ErrorInterface as never] }) + +const MutationCreatePostSuccess = z + .object({ + __typename: z.literal("MutationCreatePostSuccess"), + data: Post, + }) + .meta({ title: "MutationCreatePostSuccess" }) + +const MutationCreatePostResult = z + .discriminatedUnion("__typename", [BaseError, MutationCreatePostSuccess]) + .meta({ title: "MutationCreatePostResult" }) + +// 方案 B:SDL 中无联合类型 -> 抛出带 extensions 的 GraphQLError +class NotFoundError extends Error { + public readonly code = "NOT_FOUND" +} + +const mapDomainErrors: Middleware = async (next) => { + try { + return await next() + } catch (err) { + if (err instanceof NotFoundError) { + throw new GraphQLError(err.message, { extensions: { code: err.code } }) + } + throw err + } +} + +const postResolver = resolver({ + post: query(Post).input({ id: ID }).resolve(() => { + throw new NotFoundError("Post not found") + }), + createPost: mutation(MutationCreatePostResult) + .input({ title: z.string() }) + .resolve(({ title }) => { + if (!title.trim()) { + return { __typename: "BaseError", message: "Title is required" } + } + return { + __typename: "MutationCreatePostSuccess", + data: { id: "1", title }, + } + }), +}) + +export const schema = weave(ZodWeaver, mapDomainErrors, postResolver) +``` + +对于 Pothos 的 `directResult: true` 联合类型(如 `union CreatePostResult = BaseError | Post`),使用 `z.union([BaseError, Post]).register(asUnionType, { name: "CreatePostResult", resolveType: (v) => ("message" in v ? "BaseError" : "Post") })`。 + +若从原有的错误联合类型切换为抛出 `GraphQLError`,需同步记录以下契约变更:SDL 中的 `interface Error`、`*Error`、`*Success` 与 `union *Result` 会被移除,操作返回值直接变为 `Post!`(或 `Post`);运行时的错误信息不再出现在 `data.`(`{ __typename: "BaseError", message }`),而是进入顶层 `errors` 数组(`errors[0].extensions.code`),同时 `data.` 为 `null`(若字段非空则 `data` 为 `null`)。客户端需要移除查询中的 `... on *Success { data { ... } }` 与 `... on Error { message }` 片段,直接选择返回类型字段,并改从 `result.errors` 处理异常。 + +### 子图 + +`@pothos/plugin-sub-graph` 通过在共享 builder 上标注 `subGraphs` 并调用 `builder.toSchema({ subGraph })` 生成不同受众的 Schema。在 GQLoom 中,为每个受众分别调用一次 `weave()`,只传入该受众所需的解析器与 Silk: + +```ts twoslash +import { field, query, resolver, weave } from "@gqloom/core" +import { ZodWeaver } from "@gqloom/zod" +import * as z from "zod" + +const User = z + .object({ + id: z.string(), + name: z.string(), + internalNotes: z.string(), + }) + .meta({ title: "User" }) + +// 仅在公开子图中隐藏内部字段,不影响其他 weave() +const publicUserFields = resolver.of(User, { + internalNotes: field.hidden, +}) + +const publicQueries = resolver({ + user: query(User.nullish()).resolve(() => null), +}) + +const internalQueries = resolver({ + user: query(User.nullish()).resolve(() => null), + auditLog: query(z.array(z.string())).resolve(() => []), +}) + +export const publicSchema = weave(ZodWeaver, publicQueries, publicUserFields) +export const internalSchema = weave(ZodWeaver, internalQueries) +``` + +每次 `weave()` 都在独立隔离的上下文中执行,因此 `publicUserFields` 中的 `field.hidden` 只会从 `publicSchema` 中隐藏 `internalNotes`,不会影响 `internalSchema`。仅被 `internalQueries` 引用的类型也不会出现在 `publicSchema` 中。只要某个子图的解析器或中间件调用了 `useContext()`,别忘了在该子图的 `weave()` 中传入 `asyncContextProvider`。最后分别对每个受众的 SDL 做 diff(如 `before.public.graphql` 对比 `after.public.graphql`)。 + +### 智能订阅 + +`@pothos/plugin-smart-subscriptions` 通过主题注册把实时刷新逻辑挂在 Query 与对象字段上。在 GQLoom 中,将其替换为普通的 `subscription()` 操作与 pubsub(如 `graphql-yoga` 的 `createPubSub`,或在多实例部署中使用 Redis pubsub),并在 mutation 中显式调用 `pubSub.publish(...)`: + +```ts twoslash +import { mutation, query, resolver, subscription, weave } from "@gqloom/core" +import { ZodWeaver } from "@gqloom/zod" +import { createPubSub } from "graphql-yoga" +import * as z from "zod" + +const Post = z.object({ id: z.string(), title: z.string() }).meta({ title: "Post" }) +type IPost = z.infer + +const pubSub = createPubSub<{ + postsUpdated: [] + postUpdated: [postId: string, post: IPost] +}>() + +const postsStore: IPost[] = [] + +export const postResolver = resolver({ + posts: query(z.array(Post)).resolve(() => postsStore), + + createPost: mutation(Post) + .input({ title: z.string() }) + .resolve(({ title }) => { + const post = { id: String(postsStore.length + 1), title } + postsStore.push(post) + pubSub.publish("postsUpdated") + pubSub.publish("postUpdated", post.id, post) + return post + }), + + watchPosts: subscription(z.array(Post)) + .subscribe(() => pubSub.subscribe("postsUpdated")) + .resolve(() => postsStore), + + watchPost: subscription(Post) + .input({ id: z.string() }) + .subscribe(({ id }) => pubSub.subscribe("postUpdated", id)) + .resolve((post) => post), +}) + +export const schema = weave(ZodWeaver, postResolver) +``` + +需要注意的契约与行为差异: + +- 如果 `before.graphql` 已经把对应操作放在 `type Subscription` 下,保持字段名、参数与返回 Silk 一致即可让 SDL 完全相同。 +- 如果原先依赖 `@pothos/plugin-smart-subscriptions` 将实时订阅挂在 `type Query` 上,或依赖子类型变更自动触发父订阅重算(例如修改了嵌套的 `Comment` 后自动重新执行 `posts` 订阅),GQLoom 不会隐式把 Query 字段转为订阅,也不会自动追踪嵌套选择集依赖。需把实时操作显式定义在 `Subscription` 上(客户端改用 `subscription { ... }`),并在每一个会修改相关数据的 mutation(或领域服务)中显式发布对应的父列表和单条记录主题。 + +### 变体与生成的输入 + +一个 ORM Silk 只对应一个 GraphQL 对象类型名(如 `User` 或 `users`),而 GQLoom 的解析器工厂会生成自己的输入类型名(如 `UserWhereInput`、`UsersFilters`、`UsersOrderBy`)。要迁移 Pothos 的 `variant` 变体以及 `@pothos/plugin-prisma-utils` / `@pothos/plugin-drizzle` 生成的过滤与排序输入且保持 SDL 类型名不变,需要分别定义独立 Silk 并沿用原 SDL 名称: + +```ts twoslash +import { field, query, resolver, weave } from "@gqloom/core" +import { asyncContextProvider } from "@gqloom/core/context" +import { DrizzleWeaver, drizzleSilk } from "@gqloom/drizzle" +import { useSelectedColumns } from "@gqloom/drizzle/context" +import { ZodWeaver, asField } from "@gqloom/zod" +import { and, asc, desc, eq, ilike, or, type SQL } from "drizzle-orm" +import * as t from "drizzle-orm/sqlite-core" +import { GraphQLID, GraphQLNonNull } from "graphql" +import * as z from "zod" + +const IntID = z.int().register(asField, { type: new GraphQLNonNull(GraphQLID) }) + +const users = drizzleSilk( + t.sqliteTable("users", { + id: t.int().primaryKey({ autoIncrement: true }), + email: t.text().notNull(), + firstName: t.text().notNull(), + lastName: t.text().notNull(), + passwordHash: t.text().notNull(), + }), + { name: "User" } +) + +// 变体:使用原 SDL 类型名 "Viewer" 定义独立 Silk +const Viewer = z + .object({ + id: IntID, + email: z.string(), + firstName: z.string(), + lastName: z.string(), + }) + .meta({ title: "Viewer" }) + +const viewerFields = resolver.of(Viewer, { + firstName: field.hidden, + lastName: field.hidden, + fullName: field(z.string()) + .derivedFrom("firstName", "lastName") + .resolve((u) => `${u.firstName} ${u.lastName}`), +}) + +// 生成的过滤与排序输入:严格沿用 before.graphql 中的名称 +const OrderBy = z.enum(["asc", "desc"]).meta({ title: "OrderBy" }) + +const StringFilter = z + .object({ + equals: z.string().nullish(), + contains: z.string().nullish(), + }) + .meta({ title: "StringFilter" }) + +const UserFilter = z + .object({ + email: StringFilter.nullish(), + get AND() { + return z.array(UserFilter).nullish() + }, + get OR() { + return z.array(UserFilter).nullish() + }, + }) + .meta({ title: "UserFilter" }) + +const UserOrderBy = z + .object({ email: OrderBy.nullish() }) + .meta({ title: "UserOrderBy" }) + +function toUserWhere(filter?: z.infer | null): SQL | undefined { + if (!filter) return undefined + const parts: (SQL | undefined)[] = [] + if (filter.email?.equals != null) parts.push(eq(users.email, filter.email.equals)) + if (filter.email?.contains != null) { + parts.push(ilike(users.email, `%${filter.email.contains}%`)) + } + if (filter.AND?.length) parts.push(and(...filter.AND.map(toUserWhere))) + if (filter.OR?.length) parts.push(or(...filter.OR.map(toUserWhere))) + return and(...parts) +} + +const userResolver = resolver.of(users, { + passwordHash: field.hidden, + viewer: query(Viewer.nullish()).resolve(() => { + const columns = useSelectedColumns(users) + void columns + return { id: 1, email: "ada@example.com", firstName: "Ada", lastName: "Lovelace" } + }), + users: query(users.$list()) + .input({ + where: UserFilter.nullish(), + orderBy: z.array(UserOrderBy).nullish(), + }) + .resolve(({ where, orderBy }) => { + void toUserWhere(where) + void orderBy?.map((o) => + o.email === "desc" ? desc(users.email) : asc(users.email) + ) + return [] + }), +}) + +export const schema = weave( + ZodWeaver, + DrizzleWeaver, + asyncContextProvider, + userResolver, + viewerFields +) +``` + +保留 Pothos 过滤与排序输入时需注意两点: + +- 务必把 `.meta({ title })` 直接写在 `z.object(...)` 上(或写在 `z.lazy(() => z.object(...).meta({ title }))` 内部,不要写在 `z.lazy` 外层),否则 GQLoom 会忽略标题并根据操作名与字段名自动生成别名。 +- 请求重放时核对操作符语义(例如 Drizzle 中的 `ilike` 与 `like`,或 Prisma 中的 `mode: "insensitive"`),确保过滤后的查询结果与 Pothos 一致。 ## 陷阱 @@ -591,7 +1056,9 @@ export const postFields = resolver.of(Post, { }) ``` -- 接口类型的字段。如果 `query(Node)` 中的 `Node` 同时用于 `asObjectType({ interfaces: [Node] })`,会失败并报 `Schema must contain uniquely named types but contains multiple types named "Node"`。请返回实现类型的联合(`z.discriminatedUnion("__typename", [Dog, Cat])`),并让客户端使用内联片段;SDL 会改变,应视为契约变更。 +- 接口类型的字段。如果 `query(Node)` 中的 `Node` 是同时用于 `asObjectType({ interfaces: [Node] })` 的 `z.object`,会失败并报 `Schema must contain uniquely named types but contains multiple types named "Node"`。若要在保持 SDL 不变的前提下返回 GraphQL 接口(如 Relay `Node` 或 `Error`),请用 `silk()` 包装 `new GraphQLInterfaceType({ ... })`,并把未直接引用的实现类型传入 `weave(...)`。只有当你有意把接口改造成联合类型时,才使用 `z.discriminatedUnion("__typename", [Dog, Cat])`(属于契约变更,客户端需改用内联片段)。 + +- 在递归输入类型上把 `.meta({ title })` 写在 `z.lazy(...)` 外层会导致 GQLoom 忽略该名称,转而按操作名和字段名自动拼接别名(例如生成 `FilterPostsWhereInput` 而非 `PostWhereInput`)。请把 `.meta({ title })` 写在 `z.lazy` 内部的 `z.object(...)` 上,或直接使用 Zod v4 的 getter 写法(`get AND() { ... }`)。 - 校验:GQLoom 在 `resolve` 之前按 Zod Schema 校验参数。失败时请求被拒绝,并返回 `extensions.issues`(例如 `{"message":"Invalid email address","extensions":{"issues":[...]}}`)。请更新解析 `@pothos/plugin-zod` 或 `@pothos/plugin-validation` 错误格式的客户端。 @@ -604,7 +1071,7 @@ export const postFields = resolver.of(Post, { ## 验证 -迁移的目标是契约不变、行为不变。 +迁移的目标是契约不变、行为不变(若有不可避免的契约变更,例如将错误联合类型替换为 `GraphQLError` 或把智能订阅迁移至 `Subscription`,需明确记录变更与客户端适配方式)。 1. 在改动之前,打印 Pothos 的 SDL: @@ -622,7 +1089,7 @@ export const postFields = resolver.of(Post, { diff before.graphql after.graphql ``` - 输出必须为空。应当修改 Schema,而不是修改文件。 + 输出必须为空(或仅包含你已明确记录的预期契约变更)。应当修改 Schema,而不是修改文件。 3. 对两份 Schema 重放请求并比较 JSON。参考移植使用的是同样的四条请求: @@ -904,9 +1371,11 @@ export const schema = builder.toSchema() ```sh npm uninstall @pothos/core @pothos/plugin-prisma @pothos/plugin-drizzle \ - @pothos/plugin-scope-auth @pothos/plugin-dataloader @pothos/plugin-relay \ - @pothos/plugin-zod @pothos/plugin-validation @pothos/plugin-with-input \ - @pothos/plugin-simple-objects @pothos/plugin-complexity dataloader + @pothos/plugin-prisma-utils @pothos/plugin-scope-auth @pothos/plugin-dataloader \ + @pothos/plugin-relay @pothos/plugin-errors @pothos/plugin-sub-graph \ + @pothos/plugin-smart-subscriptions @pothos/plugin-zod @pothos/plugin-validation \ + @pothos/plugin-with-input @pothos/plugin-simple-objects @pothos/plugin-complexity \ + @pothos/plugin-federation dataloader ``` 只有在其他代码仍导入 `dataloader` 时才保留它。使用 `pnpm remove`、`yarn remove` 或 `bun remove` 执行等价操作。