Skip to content

Speak reylo's Standard Query interface - #158

Draft
mmkal wants to merge 6 commits into
mainfrom
standard-query
Draft

mmkal wants to merge 6 commits into
mainfrom
standard-query

Conversation

@mmkal

@mmkal mmkal commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

sqlfu now speaks reylo's Standard Query spec (StandardQueryV1) both ways. A Standard Query is a query object carrying its SQL plus encode (input → values to bind) and decode (rows, as arrays in select order → output).

A sqlfu client runs any Standard Query, e.g. a reylo .sql import:

import listPosts from './sql/list-posts.sql' // reylo

const posts = await client.execute(listPosts, {limit: 10}) // typed from listPosts

sqlfu's generated wrappers are Standard Queries, so a driver that has never heard of sqlfu can run them:

import {findPostBySlug} from './sql/.generated/queries.sql.ts'

const {text, encode, decode} = findPostBySlug['~standard'].query
const statement = db.prepare(text) // bare node:sqlite
statement.setReturnArrays(true)
const post = decode(statement.all(...encode({slug: 'hello'}))) // same as findPostBySlug(client, {slug: 'hello'})

decode needs rows as arrays, so every client also gets client.values(query): rows as arrays in select order, so duplicate column names survive. It's read natively in every adapter, because rebuilding arrays from object rows fails silently: select a.id, b.id collapses to one key, and JS reorders integer-like column names.

Change Purpose
src/vendor/standard-query.ts (+ row in src/vendor/CLAUDE.md) StandardQueryV1 + StandardTypedV1 types copied verbatim from reylo @ e77a021, with attribution. The spec is built to be copied, and it's young enough to churn, so sqlfu doesn't depend on reylo.
SyncClient/AsyncClient: values, execute (src/types.ts) execute is the one operation the spec defines: bind, read arrays, return decode(rows). It's a new method rather than an all/run overload because decode owns cardinality, so client.all(findOne) would return a single row.
src/standard-query.ts: executeStandardQuery Shared body of every client's execute. It refuses a query for another database (postgresql system = spec's postgres) and reads through client.values, so hooks and error mapping apply.
values in all 12 adapters, the node host client, src/cloudflare/d1-http.ts Native array reads: .raw() (better-sqlite3, libsql, turso, D1, DO), .values() (bun), setReturnArrays (node:sqlite), rowMode: 'array' (sqlite-wasm, pg), executeForRawResultAsync (expo), array-like rows (@libsql/client, turso-serverless). The D1 HTTP shim uses Cloudflare's /raw endpoint. BLOBs that a driver reads as number[]/ArrayBuffer become Uint8Array. Statements that return no rows still run.
pg: NodePostgresArrayQueryConfig overload on query values on Postgres reads with every type parser off, so each value is the text the server sent: the spec's raw form there. The transaction session pool forwards both call shapes.
instrument.ts, adapter-errors.ts Hook values as operation 'values' and map its errors, so execute gets both for free.
standardQuery({sql, query, columns, output}) helper (exported) + typegen (renderAttachedProperties, renderStandardQueryOutput) Gives generated SQLite wrappers a ~standard property. decode keys rows by the raw column names, then output repeats the wrapper body's own mapping and cardinality.
Typegen fixtures (test/generate/fixtures/*.md) Regenerated; see before/after below.
Tests test/standard-query.test.ts (direction 1), test/generate/runtime.test.ts (direction 2 via bare node:sqlite), shared values suite in test/adapters/prepare-suite.ts + DO/D1/D1 HTTP/bun/sqlite-wasm/pg cases, packages/pg/test/standard-query.test.ts (real Postgres, text values, inside a transaction too).
docs/integrations/standard-query.md, docs/client.md, sidebar Niche feature, so one integrations page plus two bullets in the client surface list. No README or landing-page change.

Generated wrapper: before / after

// before
export const findPostBySlug = Object.assign(
	async function findPostBySlug(client: Client, params: findPostBySlug.Params): Promise<findPostBySlug.Result | null> { ... },
	{ sql, query },
);

// after (+ `import {standardQuery} from 'sqlfu';`)
export const findPostBySlug = Object.assign(
	async function findPostBySlug(client: Client, params: findPostBySlug.Params): Promise<findPostBySlug.Result | null> { ... },
	{
		sql,
		query,
		"~standard": standardQuery({
			sql,
			query,
			columns: ["id", "slug", "excerpt"],
			output: (rows: findPostBySlug.Result[]) => (rows.length > 0 ? rows[0]! : null),
		}),
	},
);

Deliberately left out

Each of these has no ~standard, so passing it to client.execute is a type error rather than a runtime one:

  • Wrappers with runtime-expanded params (in (:ids), values :posts): their text depends on the input, which the spec doesn't allow.
  • update ... set wrappers (data + params): the spec takes one input, and the shape for that needs its own decision.
  • Validator wrappers, Effect/native runtimes, Postgres wrappers: not yet. Validators would mean validating rows inside decode; Postgres would need per-column text decoders.
  • Inline sql templates: they have no column list at runtime, so decode can't build rows. reylo has the same limit for hand-defined queries but throws at decode time instead.

Writes without returning decode to undefined: a Standard Query reads rows, not rowsAffected.

Not verified

  • expo-sqlite's values (prepareAsync → executeForRawResultAsync) isn't run by any test: the expo test needs an Expo web build and is env-gated. sqlite-wasm's is, but only with SQLITE_WASM_TEST=1 (passed locally).
  • test/resolve-sqlfu-ui.test.ts fails locally only because this worktree has no built @sqlfu/ui. It's unrelated.

Follow-ups are listed in tasks/complete/2026-10-29-standard-query.md.


Session: local_81761d93-60c4-42b5-996d-13a3643328ba "Standard Query interop with reylo" (CLI session 1137ecd6-97d5-414e-9d41-2626780cd170), started from the reylo evaluation session

🤖 Generated with Claude Code

Package size — packed 293.9 kB (+6.1 kB, +2.1%)

Package size

main this PR Δ
packed 287.8 kB 293.9 kB +2.1%
unpacked 1.16 MB 1.18 MB +1.9%
files 226 230 +4

dist/vendor/*.js bundles

main this PR Δ
vendor/sha256.js 4.3 kB 4.3 kB 0
vendor/sql-formatter/*.js 94.5 kB 94.5 kB 0
vendor/sqlfu-sqlite-parser/*.js 17.2 kB 17.2 kB 0
vendor/standard-query.js 0 B 1003 B new
vendor/standard-schema/*.js 2.8 kB 2.8 kB 0
vendor/typesql/*.js 135.2 kB 135.2 kB 0

Measured with npm pack --dry-run --json on sqlfu (0.0.0-dev on main vs 0.0.0-dev on this PR).

Fleshed-out spec with the decisions made on the user's behalf: vendor the
StandardQueryV1 types, add client.values (array rows) and client.execute
(run any Standard Query), and give generated wrappers a ~standard property.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@pkg-pr-new

pkg-pr-new Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/sqlfu@158

commit: 5b2586c

mmkal and others added 5 commits October 29, 2026 09:13
client.execute(query, input) runs any StandardQueryV1 (reylo's spec, e.g.
a reylo .sql import): it binds query.encode(input), reads every row as an
array of raw values, and returns query.decode(rows). It refuses a query
written for another database.

decode takes rows as arrays in select order, so every client gets a new
primitive, client.values(query). Turning object rows back into arrays is
wrong in ways that fail silently (duplicate column names collapse;
integer-like column names are reordered by JS), so each adapter reads
arrays natively: better-sqlite3/libsql/turso .raw(), bun .values(),
node:sqlite setReturnArrays, D1 .raw() (and the D1 HTTP shim's /raw
endpoint), DO cursor .raw(), sqlite-wasm rowMode 'array', expo
executeForRawResultAsync, @libsql/client and turso-serverless array-like
rows, pg rowMode 'array' with type parsers off (each value's text, the
spec's raw form on Postgres). BLOBs read as ArrayBuffer/byte arrays (DO,
D1) become Uint8Array, the spec's raw form.

instrument hooks see values as operation 'values' and adapter error
mapping covers it, so execute gets both through values.

The StandardQueryV1/StandardTypedV1 types are vendored from reylo at
e77a021 (src/vendor/standard-query.ts) rather than depended on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Generated SQLite wrappers (runtime: 'sqlfu', sync or async) now carry a
"~standard" property built by a new runtime helper, standardQuery({sql,
query, columns, output}). Any Standard Query driver (including a sqlfu
client's execute) can run them: encode binds what the wrapper's query
binds, and decode keys each row by the raw column names, then applies the
same mapping and cardinality the wrapper body does.

Left out, each a type error rather than a runtime one: wrappers with
runtime-expanded params (their text depends on the input), update
wrappers taking data + params (the spec takes one input), validator
wrappers, Effect/native runtimes, and Postgres wrappers.

Also tests a Postgres Standard Query against a real server: decode gets
each value as the text the server sent, inside a transaction too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
New docs/integrations/standard-query.md page (both directions, and which
wrappers don't get ~standard), client.values / client.execute in the
client surface list, and a sidebar entry. Task file moved to complete
with follow-ups.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The website build failed: the sidebar entry for
docs/integrations/standard-query had no page, because website pages come
from the explicit list in scripts/sync-docs.mjs, not from the docs
folder. Adds the page there, plus the llms.txt line its prebuild
regenerates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts:
#	packages/sqlfu/test/generate/runtime.test.ts
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant