Replies: 6 comments 22 replies
|
I think I generally understand your idea. You want to introduce GraphQL in a lightweight manner, without needing more advanced features for now, but you hope to have a complete GraphQL experience someday. The current Could you please further explain what functionality Nested executors aim to achieve? |
|
It would probably be a cheap gql client to be run either on the back or on the front. "cheap" because it would be an overkill to completely mimic a gql client / server and we dont' want to reinvent the square wheel. In itself a resolver is no more than a function i.e. with arguments and a return type + a context (parent, runtime context + "query" info context). GQL is nice because the language understands the relations between types and therefore nest a query within the result of another query. The same way we could chain method in a builder pattern for instance. The idea would be to have those executors to work as builders we can chain and which would eventually return what we asked for. Something like that: const johnUsersWithAddress = await query
.resolve({
users: users({ name: "John" }).resolve({
id: true, // true means the field is kept as is with the same name
familyName: "surname", // renamed from "surname"
address: address().resolve({
city: false, // false means we omit the field
gps: location(),
}),
}),
})
.run(ctx);This would return something like: {
"users": [
{
"id": "u1",
"familyName": "Doe",
"address": {
"gps": {
"lat": 46.5197,
"lon": 6.6323
}
}
},
{
"id": "u2",
"familyName": "Smith",
"address": {
"gps": {
"lat": 47.3769,
"lon": 8.5417
}
}
}
]
}Here is it to mimic the gql syntax, but perhaps we can improve something. Questions:
|
|
a problem of the syntax here I see is that the "users", "address" and other properties depending on inputs must exist somewhere. Idea: query.resolve(({users})=>{
users: users({name: "John"}).resolve(({id, surname, address})=>{
id,
familyName: surname,
address: address().resolve((location)=>{
gps: location() // probably better than "location" alone even without any args.
})
})
}).run(ctx)With possible helpers where this resolve: : address.resolve(({city, street1, street2, country})=>{city, street1, street2, country});Could take a second arguments (or a prefixed property ?) address.resolve((_, allFields)=>{...allFields); |
|
In a GraphQL Application, Objects Contain Two Types of Properties: Intrinsic Properties and Derived Properties Consider the following code: // Define intrinsic properties for User
const User = v.object({
id: v.string(),
name: v.string(),
email: v.string(),
addressId: v.string(),
birthDate: v.date(),
})
// Define intrinsic properties for Address
const Address = v.object({
id: v.string(),
street: v.string(),
city: v.string(),
})
const userResolver = resolver.of(User, {
/** address is a derived property of User */
address: field(Address).resolve((user) => db.address.find(user.addressId)),
/** age is a derived property of User */
age: field(v.number()).resolve((user) => {
const now = new Date()
const birthDate = new Date(user.birthDate)
return now.getFullYear() - birthDate.getFullYear()
}),
users: query(v.array(User)).resolve(() => db.users.find()),
})
const addressResolver = resolver.of(Address, {
/** users is a derived property of Address */
users: field(v.array(User))
.input({ name: v.nullish(v.string()) })
.resolve((address, { name }) =>
db.users.find({ addressId: address.id, name: { like: `%${name}%` } })
),
addresses: query(Address)
.input({
treet: v.nullable(v.string()),
city: v.nullable(v.string()),
})
.resolve(({ street, city }) => db.address.find({ street, city })),
})In the code above, the Based on my experience, retrieving all intrinsic properties in backend applications incurs almost no overhead (no additional database queries required), but selecting intrinsic properties on the frontend is cumbersome. Personally, I prefer to forgo the ability to select intrinsic properties in Ideas for Client API Design1. Chained Query Constructionexport const client = toExecutor({
user: userResolver,
address: addressResolver,
})
// Retrieve only intrinsic properties of Address
const addresses1 = await client.query.addresses({ city: "Singapore" })
// Retrieve nested properties
const addresses2 = await client.query.addresses({ city: "Singapore" }).with(
client.address.users({ name: "John" }).with({
// Rename field
year: client.user.age(),
})
)This design aligns with JavaScript conventions for parameter passing, but its downside is verbose syntax. 2. Nested Query Constructionexport const client = toExecutor(userResolver, addressResolver)
// Retrieve only intrinsic properties of Address
const { addresses: addresses1 } = await client.query({ addresses: true })
// Retrieve all Addresses in a specific city
const { addresses: addresses2 } = await client.query({
addresses: {
$city: "Singapore", // Use $ prefix for input parameters (consistent with GraphQL parameter syntax)
},
})
// Retrieve intrinsic properties of Address and its derived property "users"
const { addresses: addresses3 } = await client.query({
addresses: {
$city: "Singapore",
users: 1,
},
})
// Add input parameters for "users"
const { addresses: addresses4 } = await client.query({
addresses: {
$city: "Singapore",
users: {
$name: "John",
age: 1,
},
},
})This design is more concise, but the parameter passing approach may feel unintuitive. 3. Single-Query Nested ConstructionConsidering that parameters are used more frequently than selections, and we usually only call one query per GraphQL request, we could use an API like this: export const client = toExecutor(userResolver, addressResolver)
const addresses1 = await client.query.address({ city: "Singapore" })
// Retrieve intrinsic properties of Address, its derived property "users", and add input parameters
const addresses2 = await client.query.addresses({
city: "Singapore",
$with: {
users: 1,
},
})
// Add input parameters for "users"
const addresses4 = await client.query.addresses({
city: "Singapore",
$with: {
users: {
name: "John",
$with: { age: 1 },
},
},
}) |
|
In
Other features, such as field renaming, have very low usage frequency and therefore don't need to be prioritized in my opinion. |
|
note that it would also be quite simple to create helpers cased on the arguments passed to the "select" function. For instance, a "scalars" helper could filter and return an object containing only the scalar fields: ...user({name:"john"}).select((user)=>scalars(user)) |
|
Here is a rewrite of the previous DSL way await client.query(({ me, user }) => ({
...me().select(({ id, email, locale }) => ({ id, email, locale })), // we might even have only ...me.select (no args) but it's tricky
...user({ id: "42" }).select(({ id, name, address, orders }, u) => ({
id,
fullName: name, // alias
// local sub-object (no network call)
...address(({ city, country }) => ({ city, country })),
...address(({ city, country }) => ({ city, country })).as("sameAddress"), // silly field rename
...orders({ limit: 10 }).select(({ id, total, currency, items, payments }) => ({
id,
total,
currency,
...items().select(({ sku, qty, product }) => ({
sku,
qty,
...product({ locale: user.value().locale }) // idea: as every property is a kind of pointer on another resolved property, we should be able to get the value of any of them regarding the current resolution stack (something we cannot do without a hack in gql). Note that adding a non owned resolver faking it's parent argument might also be possible but is out of this scope (wundergraph does something like that).
.select(({ id, title, price }) => ({ id, title, price }))
})),
...payments()
.select((payment) => scalars(payment))
.on({
CardPayment: ({ brand, last4 }) => ({ brand, last4 }),
PaypalPayment: ({ email, id }) => ({ email, txId: id }),
}),
})),
})),
})); |
|
It seems that using arrays can make the query builder more concise: await client.query((q) => [
q.me(), // select all intrinsic fields
q.user({ id: "42" }).include((u) => [
"id", // allow string literal
u.name().as("fullName"),
u.address().include((a) => [a.city, a.country]),
u
.address()
.include((a) => [a.city, a.country])
.as("sameAddress"),
u.orders({ limit: 10 }).select((o) => [
o.id,
o.total,
o.currency,
o
.items()
.include((i) => [
i.sku,
i.qty,
i
.product({ locale: u.$value.locale })
.include((p) => [p.id(), p.title(), p.price()]),
]),
o
.payments()
.include((p) => [p.brand(), p.last4()])
.on({
CardPayment: (c) => [c.brand, c.last4],
PaypalPayment: (c) => [c.email, c.txId],
}),
]),
]),
])This is equivalent to the following query that doesn't use a query builder: await client.query([
"me",
{
field: "user",
args: { id: "42" },
include: [
"id",
{ field: "name", as: "fullName" },
{ field: "address", include: ["city", "country"] },
{ field: "address", as: "sameAddress", include: ["city", "country"] },
{
field: "orders",
include: [
"id",
"total",
"currency",
{
field: "items",
include: [
"sku",
"qty",
{ field: "product", include: ["id", "title", "price"] },
],
},
{
field: "payments",
include: ["brand", "last4"],
on: {
CardPayment: ["brand", "last4"],
PaypalPayment: ["email", "txId"],
},
},
],
},
],
},
]) |
|
efficient (because concise) but slightly less intuitive than using keys for renaming. It's however the closest to what is required to build a query, I think this is how the GQL AST works. I'm wondering if we can improve the "include" + "on" part for the union type, for instance what is your opinion about adding a syntactic sugar like: on: {
"*": ["id", "commonProperty"],
CardPayment: ["brand", "last4"],
PaypalPayment: ["email", "txId"],
},(I'm not convinced) |
|
As I mentioned in my previous reply, in the "cheap" mode, I don't plan to add the This will greatly simplify the client's query: // select all intrinsic fields: id, email, locale
const me = await client.query.me()
// build query with derived fields
const user42 = await client.query.user({
$id: "42",
order: {
$id: 10,
items: {
product: true,
},
payments: true, // select all intrinsic fields in all types
},
})
// build query with derived fields
const user43 = await client.query.user({
$id: "43",
order: {
$id: 10,
items: {
product: true,
},
payments: {
// include derived fields for union types
"...CardPayment": {
bank: true,
},
},
},
})Since the "cheap" mode saves the client a lot of |
|
Based on our discussions, the query builder (client) in
To implement these four features, I think the following query builder looks good: const user43 = await client.query.user({
$id: "43", // argument
order: { // include derived fields
$id: 10,
address: 1,
"sameAddress:address": true, // renaming
items: {
product: true,
},
payments: {
"...CardPayment": { // include derived fields for union types
bank: true,
},
},
},
}) |
|
In many languages and environments, |
|
I have some other designs: Argument in $argsconst user44 = await client.query.user({
$args: { id: "44" }, // argument
order: {
// include derived fields
$args: { id: 10 },
address: 1,
"sameAddress:address": true, // renaming
items: {
product: true,
},
payments: {
"...CardPayment": {
bank: true,
},
},
},
})Argument in tuple, zeus-styleconst user45 = await client.query.user([
{ id: "45" },
{
order: [
{ id: 10 },
{
address: 1,
"sameAddress:address": true,
items: {
product: true,
},
payments: {
"...CardPayment": {
bank: true,
},
},
},
],
},
]) |
|
I see we arrive to the same kind of attempt of design. In the same idea of zeus-style, and taking your example back: we could also have swapped: { field: "address", include: ["city", "country"] },with ["address", {include: ["city", "country"]}]as an attempt to remove the cumbersome "{field: address}". I also prefer to group the arguments under either a "$" or "$args" key.
This is what I assumed, but wasn't sure if it was a first typo or not. Also in a few case I do have several item in my root query, meaning the shorthand I will have a little of free time on Thursday to dig a little more, right now I like the most powerful solution even if this is arrays instead of key-value. Tweaking ts string unions like this way why not, but it will lack of a good refactoring support. While the prefix conventions are weird, they are quite close from the gql syntax and people would probably understand them. But we kind of reinvent a language. |
|
btw, something really weird to avoid using key: true would be to mixup an array with a dictionary =) const user44 = await client.query.user({
$args: { id: "44" }, // argument
order: {
// include derived fields
$args: { id: 10 },
...["address", "sameAddress:address"],
items: {
product: true,
},
payments: {
"...CardPayment": {
bank: true,
},
},
},
})But I doubt we should go this way… (and I also doubt TS will like extracting types from an expanded array/object hybrid)
|
|
Here is a POC for renamed fields (and array hack) |
|
Hello, I spent the day exploring a DSL builder, I'm able to, based on GqlObject and the equivalent of the root query resolvers to recursively build all the intrinsic and deterministic fields required to then build our DSL. In short, given types for instance: type User = GqlObject<"User", CommonProperties & {
firstName:string
surname:string
email:string
address:Address
union:Address | Sale
bestFriend:User
pixels:Array<Array<Pixel>>
}>And derived properties (root one are derived properties) // Create a root query type and add some fields
export type RootQuery = {}
type QueryGetUsers = FieldExtension<RootQuery, "getUsers", Array<User>>
type QueryGetUser = FieldExtension<RootQuery, "getUser", User, {id: "string"}>
// Add a derived field to User
type UserBestFriend = FieldExtension<User, "bestFriend", User>I can have a union of all the possible FieldExtension to care about // The type to add a property field of a given type to another type
export type FieldExtension<
OnType extends GqlObject<string, any>,
FieldName extends string,
FieldType extends MaybeDeepArray<any>,// I was using GqlType instead of any perhaps it could even be any type
Args extends Record<string, unknown> = {},
> = {
/** The GraphQL type on which the field is added */
onType: OnType;
/** The name of the field being added */
fieldName: FieldName;
/** The GraphQL type(s) this field returns */
fieldType: FieldType;
/** The arguments this field accepts */
args: Args;
};For instance I get: QueryGetUsers
|QueryGetUser
| UserBestFriend
| FieldExtension<GqlTypeName<"Address"> & {street:string, city:string, zipcode:string}, "street", string, {}>
| FieldExtension<GqlTypeName<"Address"> & {street:string, city:string, zipcode:string}, "city", string, {}>
| FieldExtension<GqlTypeName<"Address"> & {street:string, city:string, zipcode:string}, "zipcode", string, {}>
| FieldExtensionsUsingGqlObject<GqlTypeName<"Sale"> & {amount:number}>
| FieldExtension<GqlTypeName<"Pixel"> & {r:number, g:number, b:number}, "r", number, {}>
| FieldExtension<GqlTypeName<"Pixel"> & {r:number, g:number, b:number}, "g", number, {}>
| FieldExtension<GqlTypeName<"Pixel"> & {r:number, g:number, b:number}, "b", number, {}>
| FieldExtension<GqlTypeName<"User"> & CommonProperties & {firstName:string, surname:string, email:string, address:Address, union:Address | Sale, bestFriend:User, pixels:Array<Array<Pixel>>}, "createdOn", Date, {}>
| ...Those are the only bricks I identified to then build our DLS from them. I still need to work on, I really hope to have time to work on we have exploration days every 3 months, then I will post this POC when it will be ready. Note that I still don't feel completely confident with a DLS way (typescript neither) my intuition is that it is better to scope the properties and intent with a builder. See you |
|
Thank you for your work —it's been incredibly inspiring for me! I'm very confident in implementing such a DSL in TypeScript. |
|
I will also continue digging this DLS as much as I can because I feel like it's something we do lack on frontend. There is still much work to go especially with the query runner part. |
|
Small update: I've made the DSL we talk about, only union types are yet not supported but this is because of a bug. My first opinion is while it is handy to have a close to gql json syntax, it becomes hard to ts to quickly suggest the upcomming types / properties (name completion). Renaming the fields for instance does not really helps. I will however continue working on this poc when I will have time. Have a good day |
|
update: I did not had a lot of time lately, but I'm really wondering if this DSL is the good way to go. Using the piped way would allow supporting custom types within the query itself, for instance "defer", which could be an observable, or a promise or even a react hook. This would allow the queries to be extended for any other purpose we do not think about yet. |
|
I ended up yet on running a fake server instance in a web-worker and I do generate the schema for my webstorm gql plugin using a little script import { printSchema, lexicographicSortSchema } from 'graphql';
import { writeFile } from 'node:fs/promises';
import { schema } from '../src/gql/server/schema';
// First CLI arg = output file path, defaults to "schema.graphql"
const outFile = process.argv[2] ?? 'schema.graphql';
async function main() {
const sdl = printSchema(lexicographicSortSchema(schema));
await writeFile(outFile, sdl, 'utf-8');
console.log(`✅ SDL schema generated at ${outFile}`);
}
main().catch((err) => {
console.error('❌ Failed to generate SDL schema:', err);
process.exit(1);
}); |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
I've realize there is a "client free gql" executor https://gqloom.dev/en/docs/advanced/executor
I haven't seen yet and trace of nesting but I'm wondering it it would worth digging more the concept of those executors so that we could have a gql resolvers without gql. Perhaps it's a stupid idea but I feel like we could spare the cost of converting to a schema to then generate queries back to result and so on. Of course, using a gql client is great for caching, writing proper queries with fragments, having an opinion on subscriptions and everything but in a few case, we might want to simply nest resolvers in a simple way and that's why I'm wondering if the executors can / could achieve such task ?
The idea is that it would not pick specific properties, i.e. all the properties supposed to be returned by default will be returned (because it does not cost anything) however any resolved property would require to be explicitly called (with arguments, context and everything if mandatory). The big pro for this is the progressive adoption for frontend, where one could possibly write the resolvers on the client without any gql and then port the logic in a middle ware the time being. I had to deal with several companies reluctant in adding a new BFF (gql middleware) for some reason while I had to aggregate all their apis in some manner. Reinventing the wheel is quite boring while using an executor would be an excellent first step into a GQL adoption. Just to say: in a former company, I had absolutely no way to host any new server, I therefore ran a gql server on the client, while it worked even with the apollo google extension it did lack of most of the real benefits of gql (n+1, sharing logic, simplified CORS request, server observability and so on).
All reactions