sql

class MigrationParseError extends Error {

Error thrown when a SQL module cannot be parsed.

Raised for invalid TypeScript syntax in an import or function directive, malformed parameter names, and placeholder problems such as unbalanced braces or empty {{ }} slots. The message is prefixed with source:lineNum so parse failures point at the offending line of the original .sql text. Also re-exported from fino:database/migrate.

import { MigrationParseError, parseSqlModule } from 'fino:database/sql';

try {
  parseSqlModule('-- function bad(input: )\nSELECT 1', { source: 'bad.sql' });
} catch (err) {
  if (err instanceof MigrationParseError) {
    console.error(err.source, err.lineNum, err.message); // 'bad.sql' 1 'bad.sql:1 ...'
  }
}

Properties

Constructors

interface SqlParamIR {

Parameter parsed from a -- function directive.

One entry per parameter in the signature. A parameter written without a type annotation defaults to string.

import { parseSqlModule } from 'fino:database/sql';

const ir = parseSqlModule('-- function q(id: number, name)\nSELECT 1');
ir.functions[0].params;
// [{ name: 'id', type: 'number' }, { name: 'name', type: 'string' }]

Properties

interface SqlFunctionIR {

One SQL function parsed from a module.

Produced by parseSqlModule() for each -- function directive and consumed by compileSqlModule() and toSqlModuleSource().

import { parseSqlModule } from 'fino:database/sql';

const [fn] = parseSqlModule(`-- function findUser(input: { id: string })
-- Look up a single user.
SELECT * FROM users WHERE id = '{{ input.id }}'
`).functions;

fn.name;        // 'findUser'
fn.returnType;  // 'string'
fn.description; // ['Look up a single user.']

Properties

interface SqlModuleIR {

Parsed SQL module with preserved type imports and named functions.

The intermediate representation shared by every consumer of the SQL module pipeline: compileSqlModule() turns it into live functions, toSqlModuleSource() renders it back out as a TypeScript module.

import { parseSqlModule, type SqlModuleIR } from 'fino:database/sql';

const ir: SqlModuleIR = parseSqlModule('-- function ping()\nSELECT 1', { source: 'queries.sql' });
for (const fn of ir.functions) console.log(fn.name);

Properties

interface ParseSqlModuleOptions {

Options for parsing a SQL module.

import { parseSqlModule } from 'fino:database/sql';

parseSqlModule('-- function up()\nCREATE TABLE t (id TEXT)', { source: 'migrations/001-init.sql' });

Properties

interface CompileSqlModuleOptions {

Options for compiling SQL functions.

import { compileSqlModule, parseSqlModule, escapeSqlLiteral } from 'fino:database/sql';

const queries = compileSqlModule(parseSqlModule("-- function q(id)\nSELECT * FROM t WHERE id = '{{ id }}'"), {
  escape: (value) => escapeSqlLiteral(value, 'postgres'),
});

Properties

function parseSqlModule(text: string, options: ParseSqlModuleOptions = {}): SqlModuleIR

Parse SQL directives into a typed SQL module IR.

The parser accepts -- import type ... and -- function name(...) directives. TypeScript syntax in imports and signatures is validated with OXC, while SQL bodies remain plain text except for placeholder validation.

A function's body runs from its directive to the next directive or end of input. Comment lines before the first SQL line are captured as the function's description; comment lines and blank lines never become part of the SQL body. Positional ? markers are rewritten to {{ param }} placeholders in declaration order, and any ? beyond the parameter count is left untouched. Lines outside any directive are ignored, so a plain SQL file with no directives parses to an empty module.

Throws MigrationParseError when a directive fails TypeScript validation, a parameter name is invalid, or a SQL line has unbalanced or empty placeholder braces.

import { parseSqlModule } from 'fino:database/sql';

const ir = parseSqlModule(`-- import type { User } from './types.ts'

-- function findUser(input: User): string
-- Find a user by id.
SELECT * FROM users WHERE id = '{{ input.id }}'

-- function byStatus(status)
SELECT * FROM users WHERE status = '?'
`, { source: 'queries.sql' });

ir.functions[1].sql; // "SELECT * FROM users WHERE status = '{{ status }}'"

function escapeSqlLiteral(value: unknown, dialect: 'sqlite' | 'postgres' = 'sqlite'): unknown

Escape a value for SQL literal interpolation.

Strings use backslash escaping by default: the SQLite dialect prefixes single quotes and backslashes with \. PostgreSQL mode doubles single quotes and leaves backslashes untouched. Non-string values (numbers, booleans, null) pass through unchanged.

This is the default escape function for compileSqlModule(); pass a bound dialect through CompileSqlModuleOptions.escape to switch databases.

import { escapeSqlLiteral } from 'fino:database/sql';

escapeSqlLiteral("O'Brien");             // "O\\'Brien"
escapeSqlLiteral("O'Brien", 'postgres'); // "O''Brien"
escapeSqlLiteral(42);                    // 42

function compileSqlModule( ir: SqlModuleIR, options: CompileSqlModuleOptions = { } ): Record<string, ( ...args: unknown[] ) => string>

Compile a parsed SQL module into callable JavaScript functions.

Each generated function takes positional arguments matching the directive's parameter list and returns the rendered SQL string. {{ path }} placeholders resolve dotted or bracketed paths against those arguments and are escaped; {{! path }} placeholders are raw and must only receive trusted SQL fragments. A raw placeholder whose path is a bare name of another function in the same module (and not a parameter) calls that function with no arguments and splices its output, which allows shared SQL fragments to be composed.

Rendering throws if a placeholder path is malformed or if any segment of the path is missing from the arguments. Nullish raw values render as an empty string.

import { compileSqlModule, parseSqlModule } from 'fino:database/sql';

const queries = compileSqlModule(parseSqlModule(`-- function userColumns()
id, name, status

-- function findUser(input: { id: string })
SELECT {{! userColumns }} FROM users WHERE id = '{{ input.id }}'
`));

queries.findUser({ id: "O'Brien" });
// "SELECT id, name, status FROM users WHERE id = 'O\\'Brien'"

function toSqlModuleSource(ir: SqlModuleIR): string

Generate a TypeScript module from parsed SQL functions.

Type imports are preserved, named functions are exported with their declared parameter and return types, and the default export contains every generated function by name. Function descriptions become doc comments on the exports. The generated source is self-contained: placeholder path reading and SQLite-style literal escaping are inlined as private helpers, so the output has no runtime dependency on this module. Unlike compileSqlModule(), raw placeholders in generated code only read argument values — they do not splice sibling functions.

This is how the module loader supports importing .sql files directly: the file is parsed, converted with this function, and transpiled like any other TypeScript module.

import { parseSqlModule, toSqlModuleSource } from 'fino:database/sql';

const source = toSqlModuleSource(parseSqlModule(`-- import type { User } from './types.ts'
-- function up(input: User)
CREATE TABLE users (id TEXT PRIMARY KEY, name TEXT NOT NULL);

-- function down()
DROP TABLE users;
`));

source.includes('export function up(input: User): string'); // true
source.includes('export default { up, down };');            // true