@gqlite/tag

Runtime-facing helpers for GQLite applications.

Installation

bun add @gqlite/tag

Use this package with @gqlite/vite-plugin for build-time direct SQL transforms or persisted query client transforms.

Tagged Template Stub

gqlite<T>(db) is intentionally a small runtime stub. In direct transform mode, @gqlite/vite-plugin replaces tagged template literals with SQL execution code at build time.

import { gqlite } from "@gqlite/tag";

const users = gqlite<GQL.ListUsers>(db)`
  query ListUsers {
    users { id name email }
  }
`;

Persisted Query Client API

Persisted mode transforms source queries into ID-based calls. Configure a transport once in browser code, then generated gqliteQuery() calls use it.

import {
	configureGqlitePersistedTransport,
	createFetchPersistedTransport,
	gqliteQuery,
} from "@gqlite/tag";

configureGqlitePersistedTransport(createFetchPersistedTransport("/api/gqlite"));

const users = await gqliteQuery<GQL.ListUsers>(1);

Persisted Query Server API

executePersistedQuery() executes a compact persisted map generated by the Vite plugin.

import {
	createBetterSqliteAdapter,
	createPersistedQueryHandler,
	executePersistedQuery,
} from "@gqlite/tag";
import Database from "better-sqlite3";
import { q } from "./.gqlite/persisted-map.ts";

const db = new Database("./example.db");
const adapter = createBetterSqliteAdapter(db);

const result = await executePersistedQuery(
	body.id,
	body.variables,
	adapter,
	q,
	{
		strict: true,
		expectedSchemaHash: q.h,
		expectedCompilerVersion: q.c,
	},
);

For HTTP endpoints, use the generic Request handler and adapt it to your framework.

const handler = createPersistedQueryHandler({
	database: createBetterSqliteAdapter(db),
	compactMap: q,
	execution: { strict: true, expectedSchemaHash: q.h },
});

app.post("/api/gqlite", (c) => handler(c.req.raw));

Adapters

• createSqlAdapter(database) supports objects with prepare(sql).all(...params) or query(sql).all(...params).
• createBetterSqliteAdapter(database) wraps better-sqlite3.
• createBunSqliteAdapter(database) wraps Bun SQLite.
• createD1Adapter(database) wraps Cloudflare D1 and uses batch() for multi-step plans.

Result Shape

• Single SQL plans (k: 1) return transformed row arrays.
• Multi-step plans (k: 2) return an object keyed by each root field name.