feat: add try(), which returns the database's error as a value - #88

.try() runs a query as .run() does and resolves to { value }, or to { error } when the database refuses the query. The result is Standard Schema's shape, so if (result.error) narrows either way. .trySync() is the same on the synchronous SQLite clients.

const result = await createUser.try(db, { name: "Ada", email });
if (result.error?.condition === "unique_violation") {
  result.error.constraint; // "users_email_key" …
}

The error

• One shape per database, whichever driver ran the query, typed with every code the database defines:
  • Postgres: code, the SQLSTATE; condition, its name; constraint, table, column, schema, detail, hint, position, where.
  • MySQL: code (ER_DUP_ENTRY), errno, sqlState; key, constraint, table, column, read from the message.
  • SQLite: code, the most specific result code the driver gives; errcode; table, columns, constraint, read from the message.
• cause is the driver's own error. The object is an Error named QueryError, so throwing it keeps a stack.
• Only an error the database raised is returned. A refused connection, a client Reylo can't run on, a value Reylo refuses, or a row-count error still rejects, as from .run().
• Each .sql module exports the type as QueryError.

Code lists

• scripts/error-codes.ts writes src/error-codes-{postgres,mysql,sqlite}.ts from each database's own source:
  • Postgres 18's errcodes.txt: 251 codes.
  • MySQL 8.4.11's messages_to_clients.txt: 1,777 numbers, the same as the installed mysqld_error.h.
  • SQLite 3.53.4's sqlite3.h: 108 codes.
• The Postgres and MySQL lists load lazily, the first time an error needs one, so a bundle keeps them out of the main chunk.
• A Postgres function can raise any five-character code, so code also takes any string. condition is the strict union, so compare it to have TypeScript catch a typo.

Drivers

The driver matrix gains S6c and S6d, run through every job and client shape: a unique violation and a syntax error each resolve to the database's error, read into the dialect's fields; rows resolve to the value; Reylo's own row-count error rejects. On a synchronous client, trySync must give the same. The new rows are merged into RESULTS.md; compare.ts finds no difference. Where drivers differ:

• Bun.sql keeps the SQLSTATE in errno and writes its own stack column over column.
• mariadb numbers its own errors 45001 to 45999, with a state.
• @planetscale/database writes errno and sqlstate into the message.
• sqlite3 and the sqlite package give only the primary code.
• D1 and Durable Objects append the codes to the message.
• Turso's engine gives the primary code before 0.8, and none from 0.8 on.

Checks

• tests/run-safe.test.ts:
  • every driver's measured error shape;
  • live constraint, syntax and custom-code errors on pg, postgres.js, mysql2 and mariadb;
  • trySync on node:sqlite;
  • type tests that a misspelled code or condition is an error.
• The type check, the loader's tests (235, none skipped), the package build, the docs site, every lab, the driver matrix with its containers, and every example pass.

Docs: a .try() section under Usage, a Database errors section on each database's page, and the agent skill.