colinhacks/reylo

Import .sql files into TypeScript with full type inference and zero codegen

Summary

Reylo is a TypeScript tool that lets you import .sql files directly and get fully inferred return types without generating code. The engine (written in Rust) uses TypeScript 7.1's content mappers to ask your dev database to prepare each query, then reads column and parameter types back into the editor and tsc.

What it is useful for

Projects that already use TypeScript and want types to stay in lockstep with SQL without maintaining a separate ORM schema or codegen pipeline. It targets teams that want the full power of their database dialect (window functions, CTEs, JSON operators, vendor extensions) but still want a tsc error when a column name is wrong, a parameter is missing, or a table has been dropped. The README describes it as "agent-friendly" because SQL is the single source of truth: an assistant editing one query cannot leave a stale type behind, and the type checker finds every caller that was missed.

The inference covers shapes beyond Row:

• Row | null on a primary-key match, limit 1, or an aggregate without group by
• void for insert/update/delete without returning
• Row[] otherwise
• Nullable columns, except where a join or where test rules null out
• Enum unions from check constraints or native enums
• JSON shape preservation for JSON columns with JSON Schema checks

It works with drivers you already use: pg, postgres.js, PGlite, Neon, pg-promise, @vercel/postgres, mysql2, PlanetScale, better-sqlite3, node:sqlite, libSQL, Turso, Cloudflare D1, and others.

How engineers can use it

The README lists concrete setup steps. You need TypeScript 7.1 (currently in beta), Node 24 or later, and a running dev database, or a schema file for Postgres and SQLite.

npm install reylo
npm install -D @reylosql/postgres  # or mysql, sqlite
npm install -D typescript@beta

Add the content mapper to tsconfig.json:

"contentMappers": [{ "package": "reylo", "extensions": [".sql"] }]

Point at your database with DATABASE_URL in .env, then type-check with tsc --noEmit --runExternalCode. At runtime on Node: node --env-file=.env --import reylo/register main.ts. Plugins for Bun, Vite, Next.js, esbuild, webpack, Rspack, Cloudflare Workers, and Jest are linked from the README, along with an examples directory.

A query file like get_user.sql containing select id, name, email from users where id = :id::int imports as a default export with a .run(db, params) method. Beyond .run(), an imported query also exposes .runSync(), .with(), .sql, .raw, .inputSchema, and .outputSchema.

Documented limitations: TypeScript 7.1 is still in beta, MySQL support requires 8.0.22 or later, and a dev database must be reachable at type-check time (schema files are accepted as an alternative for Postgres and SQLite). License is MIT.