Repository navigation
Conversation
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>
commit: |
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
sqlfu now speaks reylo's Standard Query spec (
StandardQueryV1) both ways. A Standard Query is a query object carrying its SQL plusencode(input → values to bind) anddecode(rows, as arrays in select order → output).A sqlfu client runs any Standard Query, e.g. a reylo
.sqlimport:sqlfu's generated wrappers are Standard Queries, so a driver that has never heard of sqlfu can run them:
decodeneeds rows as arrays, so every client also getsclient.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.idcollapses to one key, and JS reorders integer-like column names.src/vendor/standard-query.ts(+ row insrc/vendor/CLAUDE.md)StandardQueryV1+StandardTypedV1types 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)executeis the one operation the spec defines: bind, read arrays, returndecode(rows). It's a new method rather than anall/runoverload becausedecodeowns cardinality, soclient.all(findOne)would return a single row.src/standard-query.ts:executeStandardQueryexecute. It refuses a query for another database (postgresqlsystem = spec'spostgres) and reads throughclient.values, so hooks and error mapping apply.valuesin all 12 adapters, the node host client,src/cloudflare/d1-http.ts.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/rawendpoint. BLOBs that a driver reads asnumber[]/ArrayBufferbecomeUint8Array. Statements that return no rows still run.NodePostgresArrayQueryConfigoverload onqueryvalueson 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.tsvaluesas operation'values'and map its errors, soexecutegets both for free.standardQuery({sql, query, columns, output})helper (exported) + typegen (renderAttachedProperties,renderStandardQueryOutput)~standardproperty.decodekeys rows by the raw column names, thenoutputrepeats the wrapper body's own mapping and cardinality.test/generate/fixtures/*.md)test/standard-query.test.ts(direction 1),test/generate/runtime.test.ts(direction 2 via bare node:sqlite), sharedvaluessuite intest/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, sidebarGenerated wrapper: before / after
Deliberately left out
Each of these has no
~standard, so passing it toclient.executeis a type error rather than a runtime one:in (:ids),values :posts): their text depends on the input, which the spec doesn't allow.update ... setwrappers (data+params): the spec takes one input, and the shape for that needs its own decision.decode; Postgres would need per-column text decoders.sqltemplates: they have no column list at runtime, sodecodecan't build rows. reylo has the same limit for hand-defined queries but throws at decode time instead.Writes without
returningdecode toundefined: a Standard Query reads rows, notrowsAffected.Not verified
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 withSQLITE_WASM_TEST=1(passed locally).test/resolve-sqlfu-ui.test.tsfails 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 session1137ecd6-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
dist/vendor/*.jsbundlesvendor/sha256.jsvendor/sql-formatter/*.jsvendor/sqlfu-sqlite-parser/*.jsvendor/standard-query.jsvendor/standard-schema/*.jsvendor/typesql/*.jsMeasured with
npm pack --dry-run --jsononsqlfu(0.0.0-dev on main vs 0.0.0-dev on this PR).