meshql-persisted-queries (@meshql/persisted-queries)

Register MeshQL queries once, then send a short X-Mesh-Query-Id header instead of the full base64 payload on every request.

Install

npm install meshql-persisted-queries meshql-core meshql-http
# or
npx jsr add @meshql/persisted-queries @meshql/core @meshql/http

Published on npm as meshql-persisted-queries and JSR as @meshql/persisted-queries.

Server

import { createMesh } from "meshql-core";
import { meshPersistedQueriesExpressRouter } from "meshql-persisted-queries/express";
import express from "express";

const mesh = createMesh({ entities: { /* … */ } }).resolve("user", userResolver);

const app = express();
app.use(express.json());
app.use(meshPersistedQueriesExpressRouter(mesh, {}, "/mesh"));
app.listen(3001);

POST /mesh/queries registers a query:

curl -s -X POST http://localhost:3001/mesh/queries \
  -H "Content-Type: application/json" \
  -d '{"query":"{\"user\":{\"id\":true,\"name\":true}}","format":"json"}'
# → { "id": "q_a3f1b2c8" }

Execute with the ID:

curl -s "http://localhost:3001/mesh/user/1" \
  -H "X-Mesh-Query-Id: q_a3f1b2c8" \
  -H "X-Mesh-Format: json"

Client

Enable transparent registration and ID transport:

import { createClient } from "meshql-client";

const client = createClient({
  url: "http://localhost:3001/mesh",
  persistedQueries: true,
});

const user = await client.query(
  { user: { id: true, name: true } },
  { entityId: "1" },
);

The client registers on first use, caches IDs in memory, and sends X-Mesh-Query-Id on subsequent requests. Integrity signing covers the ID string when enabled.

See HTTP wire spec and quickstart.