You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
"Polymorphism re-overhauled for greater efficiency and ergonomics. This is the
13
-
last breaking change to plan resolvers we are expecting before becoming
14
-
stable."
12
+
"Polymorphism overhauled for greater efficiency and ergonomics. This is the
13
+
last breaking change to plan resolvers we are expecting for v1."
15
14
---
16
15
17
16
_Announced 2025-06-06 by the Graphile Team_
18
17
19
18
<pclass='intro'>
20
-
In the first Gra<em>fast</em> Working Group, we outlined 4 <em>major</em> issues in Gra<em>fast</em> that needed to be addressed before we could think about general release. The fourth, and final, Epic has now been reached!
19
+
In the first Gra<em>fast</em> Working Group, we outlined 4 <em>major</em> issues in Gra<em>fast</em> that needed to be addressed before we could think about general release. The fourth, and final, epic has now been solved!
21
20
</p>
22
21
23
22
- ✅ Global dependencies — solved via “unary” steps
@@ -27,9 +26,9 @@ In the first Gra<em>fast</em> Working Group, we outlined 4 <em>major</em> issues
27
26
28
27
In previous versions of Gra*fast* there was the possibility of exponential plan
29
28
branching due to the naive method of resolution of abstract types — a known
30
-
issue raised in the first Gra*fast* working group as one of four “Epics” to be
29
+
issue raised in the first Gra*fast* working group as one of four “epics” to be
31
30
solved before v1.0. This release of `[email protected]` (used as the core
32
-
execution engine in `[email protected]`) fixes this final Epic through
31
+
execution engine in `[email protected]`) fixes this final epic through
33
32
a complete overhaul of the polymorphism system. Let’s take a look!
34
33
35
34
### Polymorphism Epic Achieved
@@ -38,49 +37,55 @@ By moving the responsibility of polymorphic resolution from field plan resolvers
38
37
into the abstract types themselves, we’ve centralized this logic, simplified
39
38
field plan resolvers, and unlocked more optimization opportunities and greater
40
39
execution efficiency. We no longer have the concept of “polymorphic capable”
41
-
steps: any step may now be used for polymorphism. The abstract types now gain a
40
+
steps: any step may now be used for polymorphism. Abstract types now gain a
42
41
`planType` method responsible for taking a “specifier” from the field plan
43
-
resolver and determining how to resolve its concrete object type and the
44
-
associated step.
42
+
resolver and returning a step representing the name of its concrete object type
43
+
along with subplans for each possible object types.
45
44
46
-
To solve the problem of exponential branching, we merge the previous polymorphic
47
-
branch into a single “specifier” step before planning the next level of
48
-
polymorphism.
45
+
To solve the problem of exponential branching, we merge the new “specifier”
46
+
steps from all of the previous polymorphic branches into a single combined step
47
+
before planning the next level of polymorphism.
49
48
50
-
Users of PostGraphile’s polymorphism should not need to take any action to
51
-
benefit from these changes and may notice that their SQL queries are now
52
-
slightly smaller and in general fewer requests to the database are required.
49
+
Users of PostGraphile’s Postgres-based polymorphism should not need to take any
50
+
action to benefit from these changes, and may notice that their SQL queries are
51
+
now slightly smaller.
53
52
54
53
For the few of you who have been brave enough to hand write polymorphic plan
55
-
resolvers: first of all, thank you for trying our new system! Hand written
56
-
polymorphic plan resolvers will need to be updated to match the new paradigm,
57
-
this will involve moving the polymorphic resolution from field plan resolvers
58
-
into the new `planType` method on the relevant abstract type and adjusting the
59
-
logic to fit the new pattern. Steps such as `polymorphicBranch`,
54
+
resolvers: first of all, thank you for trying it out! Hand written polymorphic
55
+
plan resolvers will need to be updated to match the new paradigm, this will
56
+
involve moving the polymorphic resolution from field plan resolvers into the new
57
+
`planType` method on the relevant abstract type (interface or union) and
58
+
adjusting the logic to fit the new pattern. Steps such as `polymorphicBranch`,
60
59
`pgPolymorphism`, and other polymorphism related steps no longer exist as they
61
-
are no longer supported in this new paradigm. For guidance on how to write the
62
-
`planType` method, see
60
+
are no longer supported or needed in this new paradigm. For guidance on how to
61
+
write the `planType` method, see
63
62
[the Gra*fast* docs](https://grafast.org/grafast/polymorphism) and please reach
64
-
out to us on Discord — we’d love to help you get migrated.
63
+
out to us on Discord or GitHub issues — we’d love to help you get migrated.
65
64
66
-
Fortunately, this is the last change to hand written plan resolvers that we
67
-
expect to make before the v1.0 release (other than some improvements around
68
-
TypeScript types).
65
+
Excitingly this is the last change to hand written plan resolvers that we expect
66
+
to make for v1.0 (other than some improvements around TypeScript types), so
67
+
we're getting a lot closer to release candidate stage!
69
68
70
69
### TypeDefs / plans overhaul
71
70
72
71
In order to make the libraries more type safe, `makeGrafastSchema` (from
73
72
`grafast`) and `makeExtendSchemaPlugin` (from `postgraphile/utils`) have
74
73
deprecated the `typeDefs`/`plans` pattern since `plans` (like `resolvers` in the
75
-
traditional format) ended up being a mish-mash of lots of different types and
76
-
`__`-prefixed fields for special cases.
74
+
traditional format) ended up being a mish-mash of lots of different types
75
+
(objects, scalars, enums, etc) and `__`-prefixed fields (`__resolveType`,
76
+
`__isTypeOf`, etc) for methods on the type itself.
77
77
78
78
Going forwards, the configuration should be split into `typeDefs` with
79
-
`objects`, `interfaces`, `unions`, `inputObjects`, `scalars` and `enums`.
80
-
Type-level properties such as `resolveType`/`isTypeOf`/`planType`/`scope`/etc
81
-
should now be presented without their `__` prefix; to avoid conflicts with
82
-
type-level properties, object and input object fields should be specified inside
83
-
a new `plans` property and enum values within the new `values` property.
79
+
`objects`, `interfaces`, `unions`, `inputObjects`, `scalars` and `enums` as
80
+
appropriate. Type-level properties such as
81
+
`resolveType`/`isTypeOf`/`planType`/`scope`/etc are no longer prefixed with `__`
82
+
and, to avoid conflicts with these type-level properties, object and input
83
+
object fields should be specified inside a new `plans` property and enum values
84
+
within the new `values` property.
85
+
86
+
**The old pattern will still work** (this is not a breaking change), but we
87
+
recommend moving to the new shape and will use it for all of our examples in the
88
+
documentation from now on.
84
89
85
90
Migration is quite straightforward:
86
91
@@ -90,20 +95,20 @@ Migration is quite straightforward:
90
95
where you’re not defining types of that kind.
91
96
92
97
1.**Split definitions based on type kind**. For each type defined in `plans`
93
-
move it into the appropriate new property based on the keyword used to define
94
-
the type in the `typeDefs` (`type`→`objects`, `interface`→
0 commit comments