@alxia/graphql 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -217,6 +217,46 @@ Prefer a `derive` on the app for what every route needs — the user, a
217
217
  database handle — and the `context` option for what only resolvers do, such
218
218
  as per-request data loaders.
219
219
 
220
+ ## Batching with DataLoader (N+1)
221
+
222
+ A field that loads a record for each parent, `Note.author` over a list of
223
+ notes, runs a query per parent: 50 notes, 51 queries. A
224
+ [DataLoader](https://github.com/graphql/dataloader) collects the `load` calls
225
+ of one tick and calls your batch function once. Build the loaders in the
226
+ `context` option, so each request has its own, and type them through
227
+ `GraphQLContext`'s second argument, so every resolver reads `loaders` typed:
228
+
229
+ ```ts
230
+ import DataLoader from 'dataloader';
231
+
232
+ // `findUsers` is your batch query: one result per id, in the order of the ids.
233
+
234
+ const createLoaders = () => ({
235
+ user: new DataLoader(async (ids: readonly string[]) => findUsers(ids)), // one query for all ids
236
+ });
237
+ type Loaders = ReturnType<typeof createLoaders>;
238
+ type Context = GraphQLContext<typeof base, { loaders: Loaders }>;
239
+
240
+ const schema = createSchema<Context>({
241
+ typeDefs: /* GraphQL */ `type User { id: ID!, name: String! } type Note { author: User! } type Query { notes: [Note!]! }`,
242
+ resolvers: { Note: { author: (note: { authorId: string }, _, { loaders }) => loaders.user.load(note.authorId) } },
243
+ });
244
+
245
+ const app = base.plugin((app) =>
246
+ graphql(app, { schema, context: () => ({ loaders: createLoaders() }) }),
247
+ );
248
+ ```
249
+
250
+ **The loaders must be per request.** A DataLoader caches every key it loads.
251
+ Created once, at module level or with `decorate`, its cache outlives the
252
+ request: it keeps serving a record after an update, grows for the life of the
253
+ process, and a loader that reads with the viewer's permissions hands one
254
+ user's data to the next. Per request, the cache lives and dies with one
255
+ response, and the same user loaded twice in it is one lookup.
256
+
257
+ The [GraphQL recipe](https://github.com/softistx/alxia/blob/develop/docs/recipes/graphql-api.md)
258
+ builds this step by step, with a spec that counts the calls to the store: five notes, one batch.
259
+
220
260
  ## See also
221
261
 
222
262
  - [Mounting the endpoint](endpoint.md): which middlewares run before it.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alxia/graphql",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "description": "GraphQL for alxia with GraphQL Yoga: its plugins, subscriptions over SSE and GraphiQL, behind the app's hooks, its resolvers reading the app's typed context",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -41,13 +41,14 @@
41
41
  ]
42
42
  },
43
43
  "devDependencies": {
44
- "@alxia/core": "^0.5.0",
44
+ "@alxia/core": "^0.6.0",
45
45
  "@types/bun": "^1.4.2",
46
+ "dataloader": "^2.2.3",
46
47
  "graphql": "^16.11.0",
47
48
  "graphql-yoga": "^5.16.0"
48
49
  },
49
50
  "peerDependencies": {
50
- "@alxia/core": "^0.5.0",
51
+ "@alxia/core": "^0.6.0",
51
52
  "graphql": "^16.11.0 || ^17.0.0",
52
53
  "graphql-yoga": "^5.16.0",
53
54
  "typescript": "^6.0.3 || ^7.0.0"