@laguzjs/server 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maxence Leguery
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @laguzjs/server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The server side of [laguz](https://github.com/maxenceleguery/laguz). Executes
+each root field of a batched GraphQL query on its own, streams the results as
+they complete, and resolves queries that depend on each other in the same
+request.
+
+```sh
+npm install @laguzjs/server graphql
+```
+
+```ts
+import { batchLoader, createHandler } from "@laguzjs/server";
+
+export const POST = createHandler({
+  schema,
+  rootValue,
+  context: () => ({ users: batchLoader(loadUsersById) }),
+});
+```
+
+`createHandler` takes a `Request` and returns a `Response`, so it runs on Node,
+Bun, Deno, Cloudflare Workers and Next.js route handlers. Pass your server's
+`execute` and `validate` to keep envelop or Yoga plugins.
+
+Documentation: [guide](https://github.com/maxenceleguery/laguz/blob/main/docs/guide.md#server)
+and [protocol](https://github.com/maxenceleguery/laguz/blob/main/docs/protocol.md).
+
+## License
+
+MIT

package/dist/server.d.ts

@@ -0,0 +1,47 @@
+import { execute, validate, type ExecutionResult, type GraphQLSchema } from "graphql";
+/** Protocol version announced in `extensions.laguz`. See PROTOCOL.md. */
+export declare const PROTOCOL = 1;
+export type ExecuteOptions = {
+    schema: GraphQLSchema;
+    source: string;
+    rootValue?: unknown;
+    contextValue?: unknown;
+    /** Your server's `execute`, e.g. from envelop or Yoga, to keep its plugins. */
+    execute?: typeof execute;
+    /** Your server's `validate`. */
+    validate?: typeof validate;
+};
+export type HandlerOptions = Omit<ExecuteOptions, "source" | "contextValue"> & {
+    /** Called once per request. Every field of the request shares the returned context. */
+    context?: (req: Request) => unknown;
+};
+/**
+ * Execute each root field of `source` on its own and yield the results in the
+ * order they complete. A slow field doesn't delay the others, and an invalid
+ * field fails without taking the rest of the query down.
+ *
+ * A field may take an argument from an earlier field's result
+ * (`team(id: $_ref__q0__teamId)`). It runs once that field resolves, with the
+ * value substituted, so a chain of dependent queries costs one round trip.
+ */
+export declare function splitExecute(options: ExecuteOptions): AsyncGenerator<ExecutionResult>;
+/** Fold split results back into one standard GraphQL response. */
+export declare function merged(results: AsyncIterable<ExecutionResult>): Promise<ExecutionResult>;
+/**
+ * A fetch-style handler (Bun, Deno, Cloudflare Workers, Next.js route handlers)
+ * for POST `{ query }`. Streams NDJSON when the client accepts it and answers
+ * with one merged JSON response otherwise.
+ */
+export declare function createHandler(options: HandlerOptions): (req: Request) => Promise<Response>;
+/**
+ * Stream results as newline-delimited JSON. If you compress the response,
+ * flush the compressor after each line, or the stream arrives all at once.
+ */
+export declare function ndjson(results: AsyncIterable<unknown>): Response;
+/**
+ * A minimal DataLoader: keys requested in the same tick are passed to `batch`
+ * together, and each key is loaded once. Create one per request (in `context`)
+ * so all the fields of a request share it.
+ */
+export declare function batchLoader<K, V>(batch: (keys: K[]) => Promise<V[]>): (key: K) => Promise<V>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EAIP,QAAQ,EAIR,KAAK,eAAe,EACpB,KAAK,aAAa,EAInB,MAAM,SAAS,CAAC;AAEjB,yEAAyE;AACzE,eAAO,MAAM,QAAQ,IAAI,CAAC;AAE1B,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,OAAO,OAAO,CAAC;IACzB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,OAAO,QAAQ,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,cAAc,CAAC,GAAG;IAC7E,uFAAuF;IACvF,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;CACrC,CAAC;AA+CF;;;;;;;;GAQG;AACH,wBAAuB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,CAAC,eAAe,CAAC,CAO5F;AAwED,kEAAkE;AAClE,wBAAsB,MAAM,CAAC,OAAO,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAU9F;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,SAChC,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAU/C;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,QAAQ,CAWhE;AAMD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,SAarD,CAAC,KAAG,OAAO,CAAC,CAAC,CAAC,CAQ5B"}

package/dist/server.js

@@ -0,0 +1,199 @@
+import { execute, GraphQLError, Kind, parse, validate, visit, } from "graphql";
+/** Protocol version announced in `extensions.laguz`. See PROTOCOL.md. */
+export const PROTOCOL = 1;
+function toLiteral(v) {
+    if (v === null || v === undefined)
+        return { kind: Kind.NULL };
+    if (Array.isArray(v))
+        return { kind: Kind.LIST, values: v.map(toLiteral) };
+    if (typeof v === "object") {
+        return {
+            kind: Kind.OBJECT,
+            fields: Object.entries(v).map(([key, value]) => ({
+                kind: Kind.OBJECT_FIELD,
+                name: { kind: Kind.NAME, value: key },
+                value: toLiteral(value),
+            })),
+        };
+    }
+    if (typeof v === "number") {
+        return { kind: Number.isInteger(v) ? Kind.INT : Kind.FLOAT, value: String(v) };
+    }
+    if (typeof v === "boolean")
+        return { kind: Kind.BOOLEAN, value: v };
+    return { kind: Kind.STRING, value: String(v) };
+}
+function failed(alias, errors) {
+    const list = typeof errors === "string" ? [new GraphQLError(errors)] : errors;
+    if (!alias)
+        return { errors: list };
+    return {
+        data: { [alias]: null },
+        errors: list.map((err) => new GraphQLError(err.message, { path: [alias] })),
+    };
+}
+// `$_ref__q0__team__id` reads the value at `q0.team.id`.
+function refsIn(node) {
+    const refs = [];
+    visit(node, {
+        Variable(v) {
+            const [tag, alias, ...path] = v.name.value.split("__");
+            if (tag === "_ref" && alias && path.length)
+                refs.push({ variable: v.name.value, alias, path });
+        },
+    });
+    return refs;
+}
+/**
+ * Execute each root field of `source` on its own and yield the results in the
+ * order they complete. A slow field doesn't delay the others, and an invalid
+ * field fails without taking the rest of the query down.
+ *
+ * A field may take an argument from an earlier field's result
+ * (`team(id: $_ref__q0__teamId)`). It runs once that field resolves, with the
+ * value substituted, so a chain of dependent queries costs one round trip.
+ */
+export async function* splitExecute(options) {
+    let first = true;
+    for await (const result of executeFields(options)) {
+        // Announces protocol support so clients can start forwarding refs.
+        yield first ? { ...result, extensions: { ...result.extensions, laguz: PROTOCOL } } : result;
+        first = false;
+    }
+}
+async function* executeFields({ schema, source, rootValue, contextValue, execute: run = execute, validate: check = validate, }) {
+    let doc;
+    try {
+        doc = parse(source);
+    }
+    catch (err) {
+        yield { errors: [err] };
+        return;
+    }
+    const op = doc.definitions[0];
+    // Only plain queries are split. Mutations, variables and fragments run as one document.
+    if (doc.definitions.length !== 1 || op.operation !== "query" || op.variableDefinitions?.length) {
+        const errors = check(schema, doc);
+        yield errors.length
+            ? { errors }
+            : await run({ schema, document: doc, rootValue, contextValue });
+        return;
+    }
+    const single = (sel) => ({
+        ...doc,
+        definitions: [{ ...op, selectionSet: { ...op.selectionSet, selections: [sel] } }],
+    });
+    const byAlias = new Map();
+    const fields = op.selectionSet.selections.map((sel) => {
+        const alias = sel.kind === Kind.FIELD ? (sel.alias ?? sel.name).value : undefined;
+        const refs = refsIn(sel);
+        // Looked up before anything is awaited, when only earlier fields are
+        // registered: a reference can't point forward, so there are no cycles.
+        const deps = refs.map((r) => byAlias.get(r.alias));
+        const result = (async () => {
+            let document = single(sel);
+            if (refs.length) {
+                const values = new Map();
+                for (const [i, r] of refs.entries()) {
+                    const dep = await deps[i];
+                    const value = r.path.reduce((data, key) => data?.[key], dep?.data?.[r.alias]);
+                    if (value === undefined) {
+                        return failed(alias, `unresolved reference to ${r.alias}.${r.path.join(".")}`);
+                    }
+                    values.set(r.variable, toLiteral(value));
+                }
+                document = visit(document, { Variable: (v) => values.get(v.name.value) });
+            }
+            const errors = check(schema, document);
+            if (errors.length)
+                return failed(alias, errors);
+            return run({ schema, document, rootValue, contextValue });
+        })();
+        if (alias)
+            byAlias.set(alias, result);
+        return result;
+    });
+    const pending = new Map(fields.map((p, i) => [i, p.then((r) => [i, r])]));
+    while (pending.size) {
+        const [i, result] = await Promise.race(pending.values());
+        pending.delete(i);
+        yield result;
+    }
+}
+/** Fold split results back into one standard GraphQL response. */
+export async function merged(results) {
+    const data = {};
+    const errors = [];
+    let extensions;
+    for await (const r of results) {
+        Object.assign(data, r.data);
+        if (r.errors)
+            errors.push(...r.errors);
+        if (r.extensions)
+            extensions = { ...extensions, ...r.extensions };
+    }
+    return { data, ...(errors.length && { errors }), ...(extensions && { extensions }) };
+}
+/**
+ * A fetch-style handler (Bun, Deno, Cloudflare Workers, Next.js route handlers)
+ * for POST `{ query }`. Streams NDJSON when the client accepts it and answers
+ * with one merged JSON response otherwise.
+ */
+export function createHandler(options) {
+    return async (req) => {
+        const { query } = (await req.json());
+        const results = splitExecute({
+            ...options,
+            source: query,
+            contextValue: options.context?.(req),
+        });
+        if (req.headers.get("accept")?.includes("application/x-ndjson"))
+            return ndjson(results);
+        return Response.json(await merged(results));
+    };
+}
+/**
+ * Stream results as newline-delimited JSON. If you compress the response,
+ * flush the compressor after each line, or the stream arrives all at once.
+ */
+export function ndjson(results) {
+    const it = results[Symbol.asyncIterator]();
+    const encoder = new TextEncoder();
+    const body = new ReadableStream({
+        async pull(controller) {
+            const { value, done } = await it.next();
+            if (done)
+                controller.close();
+            else
+                controller.enqueue(encoder.encode(JSON.stringify(value) + "\n"));
+        },
+    });
+    return new Response(body, { headers: { "content-type": "application/x-ndjson" } });
+}
+const nextTask = globalThis.setImmediate ??
+    ((fn) => setTimeout(fn, 0));
+/**
+ * A minimal DataLoader: keys requested in the same tick are passed to `batch`
+ * together, and each key is loaded once. Create one per request (in `context`)
+ * so all the fields of a request share it.
+ */
+export function batchLoader(batch) {
+    let queue = [];
+    const cache = new Map();
+    function dispatch() {
+        const jobs = queue;
+        queue = [];
+        batch(jobs.map((job) => job.key)).then((values) => jobs.forEach((job, i) => job.resolve(values[i])), (err) => jobs.forEach((job) => job.reject(err)));
+    }
+    return (key) => {
+        const cached = cache.get(key);
+        if (cached)
+            return cached;
+        const promise = new Promise((resolve, reject) => queue.push({ key, resolve, reject }));
+        cache.set(key, promise);
+        if (queue.length === 1)
+            nextTask(dispatch);
+        return promise;
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@laguzjs/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Server side of laguz: run each root field on its own, stream results, resolve dependent queries in one round trip.",
+  "keywords": [
+    "batching",
+    "dataloader",
+    "graphql",
+    "ndjson",
+    "server",
+    "streaming"
+  ],
+  "homepage": "https://laguz.maxenceleguery.net",
+  "bugs": {
+    "url": "https://github.com/maxenceleguery/laguz/issues"
+  },
+  "license": "MIT",
+  "author": "Maxence Leguery",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maxenceleguery/laguz.git",
+    "directory": "packages/server"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "source": "./src/server.ts",
+      "types": "./dist/server.d.ts",
+      "bun": "./src/server.ts",
+      "default": "./dist/server.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json"
+  },
+  "peerDependencies": {
+    "graphql": ">=16"
+  }
+}

package/src/server.ts

@@ -0,0 +1,247 @@
+import {
+  execute,
+  GraphQLError,
+  Kind,
+  parse,
+  validate,
+  visit,
+  type ASTNode,
+  type DocumentNode,
+  type ExecutionResult,
+  type GraphQLSchema,
+  type OperationDefinitionNode,
+  type SelectionNode,
+  type ValueNode,
+} from "graphql";
+
+/** Protocol version announced in `extensions.laguz`. See PROTOCOL.md. */
+export const PROTOCOL = 1;
+
+export type ExecuteOptions = {
+  schema: GraphQLSchema;
+  source: string;
+  rootValue?: unknown;
+  contextValue?: unknown;
+  /** Your server's `execute`, e.g. from envelop or Yoga, to keep its plugins. */
+  execute?: typeof execute;
+  /** Your server's `validate`. */
+  validate?: typeof validate;
+};
+
+export type HandlerOptions = Omit<ExecuteOptions, "source" | "contextValue"> & {
+  /** Called once per request. Every field of the request shares the returned context. */
+  context?: (req: Request) => unknown;
+};
+
+function toLiteral(v: unknown): ValueNode {
+  if (v === null || v === undefined) return { kind: Kind.NULL };
+  if (Array.isArray(v)) return { kind: Kind.LIST, values: v.map(toLiteral) };
+  if (typeof v === "object") {
+    return {
+      kind: Kind.OBJECT,
+      fields: Object.entries(v).map(([key, value]) => ({
+        kind: Kind.OBJECT_FIELD,
+        name: { kind: Kind.NAME, value: key },
+        value: toLiteral(value),
+      })),
+    };
+  }
+  if (typeof v === "number") {
+    return { kind: Number.isInteger(v) ? Kind.INT : Kind.FLOAT, value: String(v) };
+  }
+  if (typeof v === "boolean") return { kind: Kind.BOOLEAN, value: v };
+  return { kind: Kind.STRING, value: String(v) };
+}
+
+function failed(
+  alias: string | undefined,
+  errors: string | readonly GraphQLError[],
+): ExecutionResult {
+  const list = typeof errors === "string" ? [new GraphQLError(errors)] : errors;
+  if (!alias) return { errors: list };
+  return {
+    data: { [alias]: null },
+    errors: list.map((err) => new GraphQLError(err.message, { path: [alias] })),
+  };
+}
+
+// `$_ref__q0__team__id` reads the value at `q0.team.id`.
+function refsIn(node: ASTNode) {
+  const refs: { variable: string; alias: string; path: string[] }[] = [];
+  visit(node, {
+    Variable(v) {
+      const [tag, alias, ...path] = v.name.value.split("__");
+      if (tag === "_ref" && alias && path.length)
+        refs.push({ variable: v.name.value, alias, path });
+    },
+  });
+  return refs;
+}
+
+/**
+ * Execute each root field of `source` on its own and yield the results in the
+ * order they complete. A slow field doesn't delay the others, and an invalid
+ * field fails without taking the rest of the query down.
+ *
+ * A field may take an argument from an earlier field's result
+ * (`team(id: $_ref__q0__teamId)`). It runs once that field resolves, with the
+ * value substituted, so a chain of dependent queries costs one round trip.
+ */
+export async function* splitExecute(options: ExecuteOptions): AsyncGenerator<ExecutionResult> {
+  let first = true;
+  for await (const result of executeFields(options)) {
+    // Announces protocol support so clients can start forwarding refs.
+    yield first ? { ...result, extensions: { ...result.extensions, laguz: PROTOCOL } } : result;
+    first = false;
+  }
+}
+
+async function* executeFields({
+  schema,
+  source,
+  rootValue,
+  contextValue,
+  execute: run = execute,
+  validate: check = validate,
+}: ExecuteOptions): AsyncGenerator<ExecutionResult> {
+  let doc: DocumentNode;
+  try {
+    doc = parse(source);
+  } catch (err) {
+    yield { errors: [err as GraphQLError] };
+    return;
+  }
+
+  const op = doc.definitions[0] as OperationDefinitionNode;
+  // Only plain queries are split. Mutations, variables and fragments run as one document.
+  if (doc.definitions.length !== 1 || op.operation !== "query" || op.variableDefinitions?.length) {
+    const errors = check(schema, doc);
+    yield errors.length
+      ? { errors }
+      : await run({ schema, document: doc, rootValue, contextValue });
+    return;
+  }
+
+  const single = (sel: SelectionNode): DocumentNode => ({
+    ...doc,
+    definitions: [{ ...op, selectionSet: { ...op.selectionSet, selections: [sel] } }],
+  });
+
+  const byAlias = new Map<string, Promise<ExecutionResult>>();
+  const fields = op.selectionSet.selections.map((sel) => {
+    const alias = sel.kind === Kind.FIELD ? (sel.alias ?? sel.name).value : undefined;
+    const refs = refsIn(sel);
+    // Looked up before anything is awaited, when only earlier fields are
+    // registered: a reference can't point forward, so there are no cycles.
+    const deps = refs.map((r) => byAlias.get(r.alias));
+
+    const result = (async (): Promise<ExecutionResult> => {
+      let document = single(sel);
+      if (refs.length) {
+        const values = new Map<string, ValueNode>();
+        for (const [i, r] of refs.entries()) {
+          const dep = await deps[i];
+          const value = r.path.reduce((data: any, key) => data?.[key], dep?.data?.[r.alias]);
+          if (value === undefined) {
+            return failed(alias, `unresolved reference to ${r.alias}.${r.path.join(".")}`);
+          }
+          values.set(r.variable, toLiteral(value));
+        }
+        document = visit(document, { Variable: (v) => values.get(v.name.value) });
+      }
+      const errors = check(schema, document);
+      if (errors.length) return failed(alias, errors);
+      return run({ schema, document, rootValue, contextValue });
+    })();
+
+    if (alias) byAlias.set(alias, result);
+    return result;
+  });
+
+  const pending = new Map(fields.map((p, i) => [i, p.then((r) => [i, r] as const)]));
+  while (pending.size) {
+    const [i, result] = await Promise.race(pending.values());
+    pending.delete(i);
+    yield result;
+  }
+}
+
+/** Fold split results back into one standard GraphQL response. */
+export async function merged(results: AsyncIterable<ExecutionResult>): Promise<ExecutionResult> {
+  const data: Record<string, unknown> = {};
+  const errors: GraphQLError[] = [];
+  let extensions: Record<string, unknown> | undefined;
+  for await (const r of results) {
+    Object.assign(data, r.data);
+    if (r.errors) errors.push(...r.errors);
+    if (r.extensions) extensions = { ...extensions, ...r.extensions };
+  }
+  return { data, ...(errors.length && { errors }), ...(extensions && { extensions }) };
+}
+
+/**
+ * A fetch-style handler (Bun, Deno, Cloudflare Workers, Next.js route handlers)
+ * for POST `{ query }`. Streams NDJSON when the client accepts it and answers
+ * with one merged JSON response otherwise.
+ */
+export function createHandler(options: HandlerOptions) {
+  return async (req: Request): Promise<Response> => {
+    const { query } = (await req.json()) as { query: string };
+    const results = splitExecute({
+      ...options,
+      source: query,
+      contextValue: options.context?.(req),
+    });
+    if (req.headers.get("accept")?.includes("application/x-ndjson")) return ndjson(results);
+    return Response.json(await merged(results));
+  };
+}
+
+/**
+ * Stream results as newline-delimited JSON. If you compress the response,
+ * flush the compressor after each line, or the stream arrives all at once.
+ */
+export function ndjson(results: AsyncIterable<unknown>): Response {
+  const it = results[Symbol.asyncIterator]();
+  const encoder = new TextEncoder();
+  const body = new ReadableStream({
+    async pull(controller) {
+      const { value, done } = await it.next();
+      if (done) controller.close();
+      else controller.enqueue(encoder.encode(JSON.stringify(value) + "\n"));
+    },
+  });
+  return new Response(body, { headers: { "content-type": "application/x-ndjson" } });
+}
+
+const nextTask: (fn: () => void) => void =
+  (globalThis as { setImmediate?: (fn: () => void) => void }).setImmediate ??
+  ((fn) => setTimeout(fn, 0));
+
+/**
+ * A minimal DataLoader: keys requested in the same tick are passed to `batch`
+ * together, and each key is loaded once. Create one per request (in `context`)
+ * so all the fields of a request share it.
+ */
+export function batchLoader<K, V>(batch: (keys: K[]) => Promise<V[]>) {
+  let queue: { key: K; resolve: (v: V) => void; reject: (err: unknown) => void }[] = [];
+  const cache = new Map<K, Promise<V>>();
+
+  function dispatch() {
+    const jobs = queue;
+    queue = [];
+    batch(jobs.map((job) => job.key)).then(
+      (values) => jobs.forEach((job, i) => job.resolve(values[i]!)),
+      (err) => jobs.forEach((job) => job.reject(err)),
+    );
+  }
+
+  return (key: K): Promise<V> => {
+    const cached = cache.get(key);
+    if (cached) return cached;
+    const promise = new Promise<V>((resolve, reject) => queue.push({ key, resolve, reject }));
+    cache.set(key, promise);
+    if (queue.length === 1) nextTask(dispatch);
+    return promise;
+  };
+}