crudy/restloom
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: MySQL, SQL Server and SQLite dialects; writes without RETURNING; one null order on every database

Browse Source
This commit is contained in:
marc
2026-11-02 01:45:55 +01:00
parent 6801f257fb
commit 3c78bd97c1
43 changed files with 2776 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/core/src/catalog.ts
+2
View File
@@ -37,6 +37,8 @@ export interface CatalogFunction {
name: string;
args: { name: string; type: LogicalType; nativeType: string; hasDefault: boolean }[];
returnsSet: boolean;
/** The columns of each returned row, when the dialect can read them. */
columns?: CatalogColumn[];
}
export interface Catalog {
packages/core/src/dialect.ts
+4
View File
@@ -15,6 +15,8 @@ export interface Capabilities {
estimatedCount: boolean;
/** Row security enforced by the database for the session's role. */
rowSecurity: boolean;
/** Database functions can be called as procedures. */
procedures: boolean;
}
export interface Dialect {
@@ -25,6 +27,8 @@ export interface Dialect {
introspect(scope: { schemas: string[]; tables: string[] }): Promise<Catalog>;
/** Runs fn in one transaction with a statement timeout; read-only when asked. */
transaction<T>(fn: (tx: Tx) => Promise<T>, options: { timeoutMs: number; readOnly: boolean }): Promise<T>;
/** The JSON value of a statement's `r` column as a JavaScript value: drivers that parse JSON return it as is, others parse text. */
decode(value: unknown): unknown;
/** A database error the client caused, as a RestError; null for anything else, which stays a 500. */
mapError(err: unknown): RestError | null;
/** The planner's row estimate for a count query, when estimatedCount is supported. */
packages/core/src/read.ts
+1 -6
View File
@@ -6,11 +6,6 @@ import type { Filter, ReadPlan } from './plan.js';
import type { Resource } from './resources.js';
import { typed } from './grammar/values.js';
function decode(row: Record<string, unknown>): unknown {
const r = row.r;
return typeof r === 'string' ? JSON.parse(r) : r;
}
async function total(db: Dialect, tx: Tx, plan: ReadPlan, scope: (r: Resource) => Filter[]): Promise<number | null> {
if (plan.count === 'none') return null;
const stmt = db.renderer.count(plan, db.renderer.context(scope));
@@ -42,7 +37,7 @@ export async function readRows(db: Dialect, tx: Tx, resource: Resource, request:
plan.count = 'none';
}
const stmt = db.renderer.read(plan, db.renderer.context(scope));
const rows = (await tx.query(stmt.sql, stmt.params)).map(decode);
const rows = (await tx.query(stmt.sql, stmt.params)).map((row) => db.decode(row.r));
if (id !== undefined) {
if (rows.length === 0) throw notFound();
return { status: 200, headers: {}, body: rows[0] };
packages/core/src/rest.ts
+1 -1
View File
@@ -67,7 +67,7 @@ export function createREST<C = unknown>(options: RestOptions<C>): Rest<C> {
const args = procedureArgs(call.procedure.fn, call.values, request.body);
return inTransaction(request, false, async (tx) => {
const stmt = db.renderer.call(call.procedure.fn, args, db.renderer.context(scope));
const rows = (await tx.query(stmt.sql, stmt.params)).map((r) => (typeof r.r === 'string' ? JSON.parse(r.r) : r.r));
const rows = (await tx.query(stmt.sql, stmt.params)).map((row) => db.decode(row.r));
return { status: 200, headers: {}, body: call.procedure.fn.returnsSet ? rows : rows[0] ?? null };
});
}
packages/core/src/sql/renderer.ts
+13
View File
@@ -22,6 +22,19 @@ export class SqlRenderer extends SqlReader {
return ctx.params.finalize(sql, (i) => this.placeholder(i));
}
/** For databases without RETURNING: the keys a write will reach, locked until the transaction ends. */
selectKeys(resource: Resource, where: Filter[], ctx: RenderContext): Statement {
const alias = ctx.alias();
const conditions = this.filters(resource, alias, where, ctx);
const sql = `SELECT ${resource.key.map((k) => `${this.column(alias, k)} AS ${this.quote(k)}`).join(', ')} FROM ${this.table(resource.schema, resource.table)} ${alias}${conditions.length ? ` WHERE ${conditions.join(' AND ')}` : ''} FOR UPDATE`;
return ctx.params.finalize(sql, (i) => this.placeholder(i));
}
/** For databases without RETURNING: the first generated key of the last insert, as `id`. */
lastInsertId(): string {
return 'SELECT LAST_INSERT_ID() AS id';
}
writeTarget(resource: Resource, alias: string): string {
return `${this.table(resource.schema, resource.table)} AS ${alias}`;
}
packages/core/src/write.ts
+31 -5
View File
@@ -47,6 +47,34 @@ async function readBack(c: WriteContext, keys: Record<string, unknown>[], status
return { status, headers: {}, body: read.body };
}
/**
* Runs an update or delete and returns the keys it reached. A database
* without RETURNING locks and reads the keys first, then writes by key, which
* also keeps it from reading the table it is changing.
*/
async function writeByKeys(c: WriteContext, where: Filter[], write: (where: Filter[]) => { sql: string; params: unknown[] }): Promise<Record<string, unknown>[]> {
if (c.db.capabilities.returning) {
const stmt = write(where);
return c.tx.query(stmt.sql, stmt.params);
}
const sel = c.db.renderer.selectKeys(c.resource, where, c.db.renderer.context(c.scope));
const keys = await c.tx.query(sel.sql, sel.params);
if (keys.length === 0) return keys;
const stmt = write([keysFilter(c.resource, keys)]);
await c.tx.query(stmt.sql, stmt.params);
return keys;
}
/** The keys of inserted rows: returned by the database, given in the body, or generated in sequence. */
async function insertedKeys(c: WriteContext, returned: Record<string, unknown>[], columns: string[], values: unknown[][]): Promise<Record<string, unknown>[]> {
if (c.db.capabilities.returning) return returned;
const key = c.resource.key;
if (key.every((k) => columns.includes(k))) return values.map((row) => Object.fromEntries(key.map((k) => [k, row[columns.indexOf(k)]])));
if (key.length !== 1) return [];
const [first] = await c.tx.query(c.db.renderer.lastInsertId(), []);
return values.map((_, i) => ({ [key[0]]: Number(first.id) + i }));
}
/** The filters a PATCH or DELETE applies: the id, or the query's filters on a bulk-enabled resource. */
function target(c: WriteContext, id: string | undefined): Filter[] {
if (id !== undefined) return [keyFilter(c.resource, id)];
@@ -66,7 +94,7 @@ export async function create(c: WriteContext): Promise<RestResponse> {
return scope.has(col) ? scope.get(col) : row.get(col);
}));
const stmt = c.db.renderer.insert(c.resource, columns, values, c.db.renderer.context(c.scope));
const keys = await c.tx.query(stmt.sql, stmt.params);
const keys = await insertedKeys(c, await c.tx.query(stmt.sql, stmt.params), columns, values);
return wantsRows(c.request) ? readBack(c, keys, 201) : { status: 201, headers: {}, body: undefined };
}
@@ -76,8 +104,7 @@ export async function update(c: WriteContext, id: string | undefined): Promise<R
const scope = pinned(c);
for (const [col, v] of row) if (scope.has(col) && v !== scope.get(col)) throw new RestError(403, 'out_of_scope', col);
const where = [...c.scope(c.resource), ...target(c, id)];
const stmt = c.db.renderer.update(c.resource, [...row], where, c.db.renderer.context(c.scope));
const keys = await c.tx.query(stmt.sql, stmt.params);
const keys = await writeByKeys(c, where, (w) => c.db.renderer.update(c.resource, [...row], w, c.db.renderer.context(c.scope)));
if (id !== undefined && keys.length === 0) throw notFound();
if (!wantsRows(c.request)) return { status: 204, headers: {}, body: undefined };
const back = await readBack(c, keys, 200);
@@ -90,8 +117,7 @@ export async function remove(c: WriteContext, id: string | undefined): Promise<R
const before = wantsRows(c.request)
? await readRows(c.db, c.tx, c.resource, { ...c.request, query: selectOnly(c.request, c.limits.maxPage) }, c.limits, c.scope, undefined, where)
: null;
const stmt = c.db.renderer.delete(c.resource, where, c.db.renderer.context(c.scope));
const keys = await c.tx.query(stmt.sql, stmt.params);
const keys = await writeByKeys(c, where, (w) => c.db.renderer.delete(c.resource, w, c.db.renderer.context(c.scope)));
if (id !== undefined && keys.length === 0) throw notFound();
if (!before) return { status: 204, headers: {}, body: undefined };
return { status: 200, headers: {}, body: id !== undefined ? (before.body as unknown[])[0] : before.body };
packages/core/test/fake-dialect.mjs
+2 -1
View File
@@ -6,7 +6,8 @@ export function fakeDialect(rows = [{ id: 1, name: 'one' }]) {
return {
statements,
name: 'fake',
capabilities: { returning: true, estimatedCount: false, rowSecurity: false },
capabilities: { returning: true, estimatedCount: false, rowSecurity: false, procedures: false },
decode: (v) => v,
renderer: new SqlRenderer(),
async introspect() {
const col = (name, type) => ({ name, type, nativeType: type, nullable: false, generated: false });
packages/mssql/package.json
+51
View File
@@ -0,0 +1,51 @@
{
"name": "@crudy/restloom-mssql",
"version": "0.1.0",
"type": "module",
"description": "SQL Server dialect for restloom",
"keywords": [
"restloom",
"mssql",
"sql-server",
"rest",
"api"
],
"author": "Marc Villain",
"homepage": "https://restloom.crudy.fr",
"repository": {
"type": "git",
"url": "git+https://github.com/crudylabs/restloom.git",
"directory": "packages/mssql"
},
"license": "Apache-2.0",
"exports": {
".": {
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
}
},
"files": [
"dist",
"LICENSE",
"README.md"
],
"engines": {
"node": ">=20"
},
"scripts": {
"build": "tsc -p .",
"prepack": "npm run build"
},
"dependencies": {
"@crudy/restloom": "^0.1.0"
},
"peerDependencies": {
"mssql": "^12.0.0"
},
"devDependencies": {
"@types/node": "^24.0.0",
"@types/mssql": "^12.0.0",
"mssql": "12.7.10",
"typescript": "^5.9.0"
}
}
packages/mssql/src/index.ts
+76
View File
@@ -0,0 +1,76 @@
import { RestError, type Dialect, type SqlRenderer } from '@crudy/restloom';
import mssqlDriver, { type ConnectionPool } from 'mssql';
import { introspect } from './introspect.js';
import { MssqlRenderer } from './renderer.js';
export { MssqlRenderer } from './renderer.js';
const CODES: Record<number, [number, string]> = {
2627: [409, 'duplicate'],
2601: [409, 'duplicate'],
515: [400, 'value_required'],
245: [400, 'invalid_value'],
241: [400, 'invalid_value'],
242: [400, 'invalid_value'],
8114: [400, 'invalid_value'],
8115: [400, 'invalid_value'],
2628: [400, 'invalid_value'],
229: [403, 'forbidden'],
230: [403, 'forbidden'],
};
/** Error 547 covers both foreign keys and checks; its message tells which. */
export function mapError(err: unknown): RestError | null {
const e = err as { number?: unknown; code?: unknown; message?: unknown; originalError?: { info?: { number?: unknown; message?: unknown } } };
if (e?.code === 'ETIMEOUT') return new RestError(503, 'timeout');
const number = e?.number ?? e?.originalError?.info?.number;
if (number === 547) {
const text = String(e.message ?? e.originalError?.info?.message ?? '');
return /CHECK constraint/i.test(text) ? new RestError(400, 'value_rejected') : new RestError(409, 'reference_missing');
}
const hit = typeof number === 'number' ? CODES[number] : undefined;
return hit ? new RestError(hit[0], hit[1]) : null;
}
export interface MssqlOptions {
renderer?: SqlRenderer;
}
/**
* The SQL Server 2022 dialect over an mssql ConnectionPool. Each request is one
* transaction; the statement timeout is the pool's `requestTimeout`, since the
* driver sets it per pool. Row security is SQL Server's security policies,
* which a `transaction` hook feeds through sp_set_session_context.
*/
export function mssql(pool: ConnectionPool, options: MssqlOptions = {}): Dialect {
return {
name: 'mssql',
capabilities: { returning: true, estimatedCount: false, rowSecurity: true, procedures: true },
renderer: options.renderer ?? new MssqlRenderer(),
decode: (value) => (typeof value === 'string' ? JSON.parse(value) : value),
introspect: (scope) => introspect(pool, scope),
async transaction(fn) {
const tx = new mssqlDriver.Transaction(pool);
await tx.begin();
try {
const out = await fn({
async query(sql, params) {
const req = new mssqlDriver.Request(tx);
params.forEach((v, i) => {
// Whole numbers beyond 32 bits go as BigInt, or the driver overflows them as Int.
if (typeof v === 'number' && Number.isInteger(v) && Math.abs(v) > 2147483647) req.input(`p${i + 1}`, mssqlDriver.BigInt, v);
else req.input(`p${i + 1}`, v);
});
return ((await req.query(sql)).recordset ?? []) as Record<string, unknown>[];
},
});
await tx.commit();
return out;
} catch (err) {
await tx.rollback().catch(() => undefined);
throw err;
}
},
mapError,
};
}
packages/mssql/src/introspect.ts
+75
View File
@@ -0,0 +1,75 @@
import type { Catalog, CatalogTable } from '@crudy/restloom';
import type { ConnectionPool } from 'mssql';
import { logical } from './types.js';
type Row = Record<string, unknown>;
const OBJECTS = `
SELECT o.object_id AS id, SCHEMA_NAME(o.schema_id) AS s, o.name AS n, RTRIM(o.type) AS t
FROM sys.objects o
WHERE o.type IN ('U', 'V', 'FN', 'IF', 'TF')
AND (SCHEMA_NAME(o.schema_id) IN (SELECT value FROM STRING_SPLIT(@schemas, ','))
OR (o.type IN ('U', 'V') AND SCHEMA_NAME(o.schema_id) + '.' + o.name IN (SELECT value FROM STRING_SPLIT(@tables, ','))))`;
const COLUMNS = `
SELECT c.object_id AS id, c.name, TYPE_NAME(c.user_type_id) AS type, c.is_nullable AS nullable,
CAST(CASE WHEN c.is_computed = 1 OR c.is_identity = 1 THEN 1 ELSE 0 END AS bit) AS generated
FROM sys.columns c WHERE c.object_id IN (SELECT value FROM STRING_SPLIT(@ids, ','))
ORDER BY c.object_id, c.column_id`;
const PRIMARY_KEYS = `
SELECT i.object_id AS id, c.name FROM sys.indexes i
JOIN sys.index_columns ic ON ic.object_id = i.object_id AND ic.index_id = i.index_id
JOIN sys.columns c ON c.object_id = ic.object_id AND c.column_id = ic.column_id
WHERE i.is_primary_key = 1 AND i.object_id IN (SELECT value FROM STRING_SPLIT(@ids, ','))
ORDER BY i.object_id, ic.key_ordinal`;
const FOREIGN_KEYS = `
SELECT fk.object_id AS fk, fk.parent_object_id AS id, pc.name AS col, SCHEMA_NAME(t.schema_id) AS ts, t.name AS tt, rc.name AS rcol
FROM sys.foreign_keys fk
JOIN sys.foreign_key_columns fkc ON fkc.constraint_object_id = fk.object_id
JOIN sys.columns pc ON pc.object_id = fkc.parent_object_id AND pc.column_id = fkc.parent_column_id
JOIN sys.columns rc ON rc.object_id = fkc.referenced_object_id AND rc.column_id = fkc.referenced_column_id
JOIN sys.tables t ON t.object_id = fk.referenced_object_id
WHERE fk.parent_object_id IN (SELECT value FROM STRING_SPLIT(@ids, ','))
ORDER BY fk.object_id, fkc.constraint_column_id`;
const PARAMETERS = `
SELECT p.object_id AS id, SUBSTRING(p.name, 2, 200) AS name, TYPE_NAME(p.user_type_id) AS type
FROM sys.parameters p WHERE p.parameter_id > 0 AND p.object_id IN (SELECT value FROM STRING_SPLIT(@ids, ','))
ORDER BY p.object_id, p.parameter_id`;
/** Reads tables, views and functions from the catalog views. T-SQL does not expose parameter defaults, so every argument is required. */
export async function introspect(pool: ConnectionPool, scope: { schemas: string[]; tables: string[] }): Promise<Catalog> {
const run = async (sql: string, params: Record<string, string>) => {
const req = pool.request();
for (const [k, v] of Object.entries(params)) req.input(k, v);
return (await req.query(sql)).recordset as Row[];
};
const objects = await run(OBJECTS, { schemas: scope.schemas.join(','), tables: scope.tables.join(',') });
const ids = { ids: objects.map((o) => String(o.id)).join(',') };
const [columns, keys, fks, params] = await Promise.all([run(COLUMNS, ids), run(PRIMARY_KEYS, ids), run(FOREIGN_KEYS, ids), run(PARAMETERS, ids)]);
const columnsOf = (id: unknown) => columns.filter((c) => c.id === id).map((c) => ({
name: c.name as string, nativeType: c.type as string, type: logical(c.type as string), nullable: !!c.nullable, generated: !!c.generated,
}));
const tables = new Map<number, CatalogTable>();
for (const o of objects) {
if (o.t !== 'U' && o.t !== 'V') continue;
tables.set(o.id as number, { schema: o.s as string, name: o.n as string, kind: o.t === 'V' ? 'view' : 'table', columns: [], primaryKey: [], foreignKeys: [] });
}
for (const [id, table] of tables) table.columns = columnsOf(id);
for (const k of keys) tables.get(k.id as number)?.primaryKey.push(k.name as string);
const byFk = new Map<number, Row[]>();
for (const f of fks) byFk.set(f.fk as number, [...(byFk.get(f.fk as number) ?? []), f]);
for (const parts of byFk.values()) {
tables.get(parts[0].id as number)?.foreignKeys.push({
columns: parts.map((p) => p.col as string), targetColumns: parts.map((p) => p.rcol as string),
target: { schema: parts[0].ts as string, table: parts[0].tt as string },
});
}
const functions = objects.filter((o) => o.t === 'FN' || o.t === 'IF' || o.t === 'TF').map((o) => ({
schema: o.s as string, name: o.n as string, returnsSet: o.t !== 'FN', columns: o.t === 'FN' ? undefined : columnsOf(o.id),
args: params.filter((p) => p.id === o.id).map((p) => ({ name: p.name as string, type: logical(p.type as string), nativeType: p.type as string, hasDefault: false })),
}));
return { tables: [...tables.values()], functions };
}
packages/mssql/src/renderer.ts
+112
View File
@@ -0,0 +1,112 @@
import { SqlRenderer, type CatalogColumn, type CatalogFunction, type Filter, type OrderTerm, type RenderContext, type Resource, type Statement } from '@crudy/restloom';
/**
* SQL Server 2022: bracketed names, @p placeholders, JSON_OBJECT for rows and
* STRING_AGG for arrays (JSON_ARRAYAGG is not in 2022), OFFSET/FETCH paging,
* OUTPUT in place of RETURNING.
*/
export class MssqlRenderer extends SqlRenderer {
quote(identifier: string): string {
return `[${identifier.replace(/]/g, ']]')}]`;
}
literal(text: string): string {
return `N'${text.replace(/'/g, "''")}'`;
}
placeholder(index: number): string {
return `@p${index}`;
}
jsonObject(pairs: [string, string][]): string {
return `JSON_OBJECT(${pairs.map(([k, v]) => `${this.literal(k)}: ${v}`).join(', ')} NULL ON NULL)`;
}
jsonArray(rowExpr: string, orderExpr: string): string {
return `COALESCE(N'[' + STRING_AGG(CAST(${rowExpr} AS nvarchar(max)), N',') WITHIN GROUP (ORDER BY ${orderExpr}) + N']', N'[]')`;
}
nested(expr: string): string {
return `JSON_QUERY(${expr})`;
}
jsonValue(expr: string, column: CatalogColumn): string {
if (column.type === 'boolean') return `CAST(${expr} AS bit)`;
if (column.nativeType === 'datetimeoffset') return `CONVERT(varchar(19), SWITCHOFFSET(${expr}, '+00:00'), 126) + '+00:00'`;
if (column.type === 'timestamp') return `CONVERT(varchar(19), ${expr}, 126)`;
if (column.type === 'date') return `CONVERT(varchar(10), ${expr}, 23)`;
return expr;
}
like(expr: string, pattern: string, insensitive: boolean): string {
return insensitive
? `LOWER(${expr}) LIKE LOWER(${pattern}) ESCAPE '\\'`
: `${expr} COLLATE Latin1_General_100_CS_AS LIKE ${pattern} ESCAPE '\\'`;
}
isBoolean(expr: string, value: boolean): string {
return `${expr} = ${value ? 1 : 0}`;
}
/** SQL Server sorts nulls first ascending; this keeps the Postgres order: last ascending, first descending. */
orderBy(expr: string, desc: boolean, nulls?: 'first' | 'last'): string {
const first = (nulls ?? (desc ? 'first' : 'last')) === 'first';
return `CASE WHEN ${expr} IS NULL THEN ${first ? 0 : 1} ELSE ${first ? 1 : 0} END, ${expr} ${desc ? 'DESC' : 'ASC'}`;
}
/** OFFSET/FETCH needs an ORDER BY, so an unordered read orders by nothing in particular. */
order(terms: OrderTerm[], alias: string, ctx: RenderContext): string {
return super.order(terms, alias, ctx) || '(SELECT NULL)';
}
page(limit: number | undefined, offset: number | undefined): string {
if (limit === undefined && !offset) return '';
return ` OFFSET ${offset ?? 0} ROWS${limit !== undefined ? ` FETCH NEXT ${limit} ROWS ONLY` : ''}`;
}
first(selectSql: string): string {
return selectSql.replace(/^SELECT /, 'SELECT TOP 1 ');
}
aggregate(fn: Parameters<SqlRenderer['aggregate']>[0], expr: string | null): string {
return fn === 'count' ? 'COUNT_BIG(*)' : super.aggregate(fn, expr);
}
private output(resource: Resource, side: 'INSERTED' | 'DELETED'): string {
return ` OUTPUT ${resource.key.map((k) => `${side}.${this.quote(k)}`).join(', ')}`;
}
insert(resource: Resource, columns: string[], rows: unknown[][], ctx: RenderContext): Statement {
const values = rows.map((row) => `(${row.map((v) => ctx.params.add(v)).join(', ')})`).join(', ');
const sql = `INSERT INTO ${this.table(resource.schema, resource.table)} (${columns.map((c) => this.quote(c)).join(', ')})${this.output(resource, 'INSERTED')} VALUES ${values}`;
return ctx.params.finalize(sql, (i) => this.placeholder(i));
}
update(resource: Resource, set: [string, unknown][], where: Filter[], ctx: RenderContext): Statement {
const alias = ctx.alias();
const assignments = set.map(([c, v]) => `${this.column(alias, c)} = ${ctx.params.add(v)}`).join(', ');
const conditions = this.filters(resource, alias, where, ctx);
const sql = `UPDATE ${alias} SET ${assignments}${this.output(resource, 'INSERTED')} FROM ${this.table(resource.schema, resource.table)} ${alias}${conditions.length ? ` WHERE ${conditions.join(' AND ')}` : ''}`;
return ctx.params.finalize(sql, (i) => this.placeholder(i));
}
delete(resource: Resource, where: Filter[], ctx: RenderContext): Statement {
const alias = ctx.alias();
const conditions = this.filters(resource, alias, where, ctx);
const sql = `DELETE ${alias}${this.output(resource, 'DELETED')} FROM ${this.table(resource.schema, resource.table)} ${alias}${conditions.length ? ` WHERE ${conditions.join(' AND ')}` : ''}`;
return ctx.params.finalize(sql, (i) => this.placeholder(i));
}
/** T-SQL calls by position. A scalar comes back as JSON text through JSON_ARRAY, a table function row by row. */
call(fn: CatalogFunction, args: [string, unknown][], ctx: RenderContext): Statement {
const byName = new Map(args);
const call = `${this.table(fn.schema, fn.name)}(${fn.args.map((a) => ctx.params.add(byName.get(a.name))).join(', ')})`;
const row = fn.columns?.length
? this.jsonObject(fn.columns.map((c) => [c.name, this.jsonValue(this.column('x', c.name), c)]))
: '(SELECT x.* FOR JSON PATH, WITHOUT_ARRAY_WRAPPER, INCLUDE_NULL_VALUES)';
const sql = fn.returnsSet
? `SELECT ${row} AS r FROM ${call} x`
: `SELECT SUBSTRING(j, 2, LEN(j + N'x') - 3) AS r FROM (SELECT JSON_ARRAY(${call} NULL ON NULL) AS j) v`;
return ctx.params.finalize(sql, (i) => this.placeholder(i));
}
}
packages/mssql/src/types.ts
+16
View File
@@ -0,0 +1,16 @@
import type { LogicalType } from '@crudy/restloom';
/** A SQL Server type name as a logical type. JSON lives in text columns, so it reads as text. */
export function logical(type: string): LogicalType {
const t = type.toLowerCase();
if (['tinyint', 'smallint', 'int', 'bigint'].includes(t)) return 'integer';
if (['decimal', 'numeric', 'money', 'smallmoney', 'float', 'real'].includes(t)) return 'number';
if (t === 'bit') return 'boolean';
if (t === 'uniqueidentifier') return 'uuid';
if (t === 'date') return 'date';
if (['datetime', 'datetime2', 'smalldatetime', 'datetimeoffset'].includes(t)) return 'timestamp';
if (t === 'time') return 'time';
if (['char', 'varchar', 'nchar', 'nvarchar', 'text', 'ntext', 'sysname'].includes(t)) return 'text';
if (['binary', 'varbinary', 'image', 'rowversion', 'timestamp'].includes(t)) return 'binary';
return 'other';
}
packages/mssql/tsconfig.json
+5
View File
@@ -0,0 +1,5 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": { "outDir": "dist", "rootDir": "src" },
"include": ["src"]
}
packages/mysql/package.json
+49
View File
@@ -0,0 +1,49 @@
{
"name": "@crudy/restloom-mysql",
"version": "0.1.0",
"type": "module",
"description": "MySQL dialect for restloom",
"keywords": [
"restloom",
"mysql",
"rest",
"api"
],
"author": "Marc Villain",
"homepage": "https://restloom.crudy.fr",
"repository": {
"type": "git",
"url": "git+https://github.com/crudylabs/restloom.git",
"directory": "packages/mysql"
},
"license": "Apache-2.0",
"exports": {
".": {
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
}
},
"files": [
"dist",
"LICENSE",
"README.md"
],
"engines": {
"node": ">=20"
},
"scripts": {
"build": "tsc -p .",
"prepack": "npm run build"
},
"dependencies": {
"@crudy/restloom": "^0.1.0"
},
"peerDependencies": {
"mysql2": "^3.11.0"
},
"devDependencies": {
"@types/node": "^24.0.0",
"mysql2": "^3.24.5",
"typescript": "^5.9.0"
}
}
packages/mysql/src/index.ts
+68
View File
@@ -0,0 +1,68 @@
import { RestError, type Dialect, type SqlRenderer } from '@crudy/restloom';
import type { Pool } from 'mysql2/promise';
import { introspect } from './introspect.js';
import { MysqlRenderer } from './renderer.js';
export { MysqlRenderer } from './renderer.js';
const CODES: Record<number, [number, string]> = {
1062: [409, 'duplicate'],
1452: [409, 'reference_missing'],
1451: [409, 'still_referenced'],
1048: [400, 'value_required'],
1364: [400, 'value_required'],
3819: [400, 'value_rejected'],
1292: [400, 'invalid_value'],
1264: [400, 'invalid_value'],
1366: [400, 'invalid_value'],
1406: [400, 'invalid_value'],
1142: [403, 'forbidden'],
3024: [503, 'timeout'],
};
export function mapError(err: unknown): RestError | null {
const errno = (err as { errno?: unknown })?.errno;
const hit = typeof errno === 'number' ? CODES[errno] : undefined;
return hit ? new RestError(hit[0], hit[1]) : null;
}
export interface MysqlOptions {
renderer?: SqlRenderer;
}
/**
* The MySQL 8 dialect over a mysql2/promise Pool. Each request is one
* transaction on one connection, in UTC, with MAX_EXECUTION_TIME for reads.
* Text compares with each column's collation, so with a case-insensitive
* collation `eq` ignores case.
*/
export function mysql(pool: Pool, options: MysqlOptions = {}): Dialect {
return {
name: 'mysql',
capabilities: { returning: false, estimatedCount: false, rowSecurity: false, procedures: true },
renderer: options.renderer ?? new MysqlRenderer(),
decode: (value) => value,
introspect: (scope) => introspect(pool, scope),
async transaction(fn, { timeoutMs, readOnly }) {
const conn = await pool.getConnection();
try {
await conn.query(`SET SESSION time_zone = '+00:00', SESSION group_concat_max_len = 1073741824, SESSION MAX_EXECUTION_TIME = ${Math.max(1, Math.floor(timeoutMs))}`);
await conn.query(readOnly ? 'START TRANSACTION READ ONLY' : 'START TRANSACTION');
const out = await fn({
async query(sql, params) {
const [rows] = await conn.query(sql, params);
return Array.isArray(rows) ? (rows as Record<string, unknown>[]) : [];
},
});
await conn.query('COMMIT');
return out;
} catch (err) {
await conn.query('ROLLBACK').catch(() => undefined);
throw err;
} finally {
conn.release();
}
},
mapError,
};
}
packages/mysql/src/introspect.ts
+59
View File
@@ -0,0 +1,59 @@
import type { Catalog, CatalogTable } from '@crudy/restloom';
import type { Pool } from 'mysql2/promise';
import { logical } from './types.js';
type Row = Record<string, unknown>;
const IN_SCOPE = '(t.TABLE_SCHEMA IN (?) OR CONCAT(t.TABLE_SCHEMA, \'.\', t.TABLE_NAME) IN (?))';
/** Reads tables, views, columns, keys and functions from information_schema. MySQL's schemas are its databases. */
export async function introspect(pool: Pool, scope: { schemas: string[]; tables: string[] }): Promise<Catalog> {
const schemas = scope.schemas.length ? scope.schemas : [''];
const tablesIn = scope.tables.length ? scope.tables : [''];
const q = async (sql: string, params: unknown[]) => (await pool.query(sql, params))[0] as Row[];
const [tables, columns, keys, params, functions] = await Promise.all([
q(`SELECT TABLE_SCHEMA AS s, TABLE_NAME AS n, TABLE_TYPE AS k FROM information_schema.TABLES t WHERE ${IN_SCOPE}`, [schemas, tablesIn]),
q(`SELECT c.TABLE_SCHEMA AS s, c.TABLE_NAME AS n, c.COLUMN_NAME AS name, c.DATA_TYPE AS dt, c.COLUMN_TYPE AS ct, c.IS_NULLABLE AS nullable, c.EXTRA AS extra
FROM information_schema.COLUMNS c JOIN information_schema.TABLES t ON t.TABLE_SCHEMA = c.TABLE_SCHEMA AND t.TABLE_NAME = c.TABLE_NAME
WHERE ${IN_SCOPE} ORDER BY c.TABLE_SCHEMA, c.TABLE_NAME, c.ORDINAL_POSITION`, [schemas, tablesIn]),
q(`SELECT k.TABLE_SCHEMA AS s, k.TABLE_NAME AS n, k.CONSTRAINT_NAME AS c, k.COLUMN_NAME AS col,
k.REFERENCED_TABLE_SCHEMA AS rs, k.REFERENCED_TABLE_NAME AS rt, k.REFERENCED_COLUMN_NAME AS rc
FROM information_schema.KEY_COLUMN_USAGE k JOIN information_schema.TABLES t ON t.TABLE_SCHEMA = k.TABLE_SCHEMA AND t.TABLE_NAME = k.TABLE_NAME
WHERE ${IN_SCOPE} AND (k.CONSTRAINT_NAME = 'PRIMARY' OR k.REFERENCED_TABLE_NAME IS NOT NULL)
ORDER BY k.CONSTRAINT_NAME, k.ORDINAL_POSITION`, [schemas, tablesIn]),
q(`SELECT SPECIFIC_SCHEMA AS s, SPECIFIC_NAME AS n, PARAMETER_NAME AS name, DATA_TYPE AS dt, DTD_IDENTIFIER AS ct
FROM information_schema.PARAMETERS WHERE SPECIFIC_SCHEMA IN (?) AND ORDINAL_POSITION > 0 ORDER BY ORDINAL_POSITION`, [schemas]),
q(`SELECT ROUTINE_SCHEMA AS s, ROUTINE_NAME AS n FROM information_schema.ROUTINES WHERE ROUTINE_SCHEMA IN (?) AND ROUTINE_TYPE = 'FUNCTION'`, [schemas]),
]);
const byName = new Map<string, CatalogTable>();
for (const t of tables) {
byName.set(`${t.s}.${t.n}`, { schema: t.s as string, name: t.n as string, kind: t.k === 'VIEW' ? 'view' : 'table', columns: [], primaryKey: [], foreignKeys: [] });
}
for (const c of columns) {
byName.get(`${c.s}.${c.n}`)?.columns.push({
name: c.name as string, nativeType: c.ct as string, type: logical(c.dt as string, c.ct as string),
nullable: c.nullable === 'YES', generated: /GENERATED/i.test(c.extra as string),
});
}
const fks = new Map<string, { table: CatalogTable; columns: string[]; targetColumns: string[]; target: { schema: string; table: string } }>();
for (const k of keys) {
const table = byName.get(`${k.s}.${k.n}`);
if (!table) continue;
if (k.c === 'PRIMARY') { table.primaryKey.push(k.col as string); continue; }
const id = `${k.s}.${k.n}.${k.c}`;
const fk = fks.get(id) ?? { table, columns: [], targetColumns: [], target: { schema: k.rs as string, table: k.rt as string } };
fk.columns.push(k.col as string);
fk.targetColumns.push(k.rc as string);
fks.set(id, fk);
}
for (const { table, ...fk } of fks.values()) table.foreignKeys.push(fk);
return {
tables: [...byName.values()],
functions: functions.map((f) => ({
schema: f.s as string, name: f.n as string, returnsSet: false,
args: params.filter((p) => p.s === f.s && p.n === f.n).map((p) => ({
name: p.name as string, type: logical(p.dt as string, p.ct as string), nativeType: p.ct as string, hasDefault: false,
})),
})),
};
}
packages/mysql/src/renderer.ts
+67
View File
@@ -0,0 +1,67 @@
import { SqlRenderer, type CatalogColumn, type CatalogFunction, type RenderContext, type Statement } from '@crudy/restloom';
/**
* MySQL 8: backquoted names, positional placeholders, no RETURNING. Arrays are
* built with GROUP_CONCAT, which keeps an order where JSON_ARRAYAGG does not.
*/
export class MysqlRenderer extends SqlRenderer {
quote(identifier: string): string {
return `\`${identifier.replace(/`/g, '``')}\``;
}
literal(text: string): string {
return `'${text.replace(/\\/g, '\\\\').replace(/'/g, "''")}'`;
}
placeholder(_index: number): string {
return '?';
}
jsonObject(pairs: [string, string][]): string {
return `JSON_OBJECT(${pairs.map(([k, v]) => `${this.literal(k)}, ${v}`).join(', ')})`;
}
jsonArray(rowExpr: string, orderExpr: string): string {
return `COALESCE(CAST(CONCAT('[', GROUP_CONCAT(${rowExpr} ORDER BY ${orderExpr} SEPARATOR ','), ']') AS JSON), JSON_ARRAY())`;
}
nested(expr: string): string {
return `CAST(${expr} AS JSON)`;
}
jsonValue(expr: string, column: CatalogColumn): string {
if (column.type === 'boolean') return `IF(${expr} IS NULL, NULL, CAST(IF(${expr}, 'true', 'false') AS JSON))`;
if (column.type === 'timestamp') return `DATE_FORMAT(${expr}, '%Y-%m-%dT%H:%i:%s${/^timestamp/i.test(column.nativeType) ? '+00:00' : ''}')`;
return expr;
}
like(expr: string, pattern: string, insensitive: boolean): string {
return insensitive
? `LOWER(${expr}) LIKE LOWER(${pattern}) ESCAPE '\\\\'`
: `${expr} COLLATE utf8mb4_bin LIKE ${pattern} ESCAPE '\\\\'`;
}
isBoolean(expr: string, value: boolean): string {
return `${expr} = ${value ? 1 : 0}`;
}
/** MySQL sorts nulls first ascending; this keeps the Postgres order: last ascending, first descending. */
orderBy(expr: string, desc: boolean, nulls?: 'first' | 'last'): string {
const first = (nulls ?? (desc ? 'first' : 'last')) === 'first';
return `(${expr} IS NULL) ${first ? 'DESC' : 'ASC'}, ${expr} ${desc ? 'DESC' : 'ASC'}`;
}
page(limit: number | undefined, offset: number | undefined): string {
return limit === undefined && !offset ? '' : ` LIMIT ${limit ?? '18446744073709551615'}${offset ? ` OFFSET ${offset}` : ''}`;
}
returning(): string {
return '';
}
call(fn: CatalogFunction, args: [string, unknown][], ctx: RenderContext): Statement {
const byName = new Map(args);
const call = `${this.table(fn.schema, fn.name)}(${fn.args.map((a) => ctx.params.add(byName.get(a.name))).join(', ')})`;
return ctx.params.finalize(`SELECT JSON_EXTRACT(JSON_ARRAY(${call}), '$[0]') AS r`, (i) => this.placeholder(i));
}
}
packages/mysql/src/types.ts
+16
View File
@@ -0,0 +1,16 @@
import type { LogicalType } from '@crudy/restloom';
/** A MySQL column type as a logical type. TINYINT(1) is MySQL's boolean. */
export function logical(dataType: string, columnType: string): LogicalType {
const t = dataType.toLowerCase();
if (columnType.toLowerCase().startsWith('tinyint(1)') || t === 'boolean') return 'boolean';
if (['tinyint', 'smallint', 'mediumint', 'int', 'integer', 'bigint', 'year'].includes(t)) return 'integer';
if (['decimal', 'numeric', 'float', 'double', 'real'].includes(t)) return 'number';
if (['char', 'varchar', 'tinytext', 'text', 'mediumtext', 'longtext', 'enum', 'set'].includes(t)) return 'text';
if (t === 'date') return 'date';
if (t === 'datetime' || t === 'timestamp') return 'timestamp';
if (t === 'time') return 'time';
if (t === 'json') return 'json';
if (['binary', 'varbinary', 'tinyblob', 'blob', 'mediumblob', 'longblob', 'bit'].includes(t)) return 'binary';
return 'other';
}
packages/mysql/tsconfig.json
+5
View File
@@ -0,0 +1,5 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": { "outDir": "dist", "rootDir": "src" },
"include": ["src"]
}
packages/postgres/src/index.ts
+2 -1
View File
@@ -20,7 +20,8 @@ export interface PostgresOptions {
export function postgres(pool: Pool, options: PostgresOptions = {}): Dialect {
return {
name: 'postgres',
capabilities: { returning: true, estimatedCount: true, rowSecurity: true },
capabilities: { returning: true, estimatedCount: true, rowSecurity: true, procedures: true },
decode: (value) => value,
renderer: options.renderer ?? new PostgresRenderer(),
introspect: (scope) => introspect(pool, scope),
async transaction(fn, { timeoutMs, readOnly }) {
packages/sqlite/package.json
+50
View File
@@ -0,0 +1,50 @@
{
"name": "@crudy/restloom-sqlite",
"version": "0.1.0",
"type": "module",
"description": "SQLite dialect for restloom",
"keywords": [
"restloom",
"sqlite",
"rest",
"api"
],
"author": "Marc Villain",
"homepage": "https://restloom.crudy.fr",
"repository": {
"type": "git",
"url": "git+https://github.com/crudylabs/restloom.git",
"directory": "packages/sqlite"
},
"license": "Apache-2.0",
"exports": {
".": {
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
}
},
"files": [
"dist",
"LICENSE",
"README.md"
],
"engines": {
"node": ">=20"
},
"scripts": {
"build": "tsc -p .",
"prepack": "npm run build"
},
"dependencies": {
"@crudy/restloom": "^0.1.0"
},
"peerDependencies": {
"better-sqlite3": ">=12"
},
"devDependencies": {
"@types/node": "^24.0.0",
"@types/better-sqlite3": "^7.6.0",
"better-sqlite3": "^12.11.1",
"typescript": "^5.9.0"
}
}
packages/sqlite/src/index.ts
+69
View File
@@ -0,0 +1,69 @@
import { RestError, type Dialect, type SqlRenderer } from '@crudy/restloom';
import type { Database } from 'better-sqlite3';
import { introspect } from './introspect.js';
import { SqliteRenderer } from './renderer.js';
export { SqliteRenderer } from './renderer.js';
const CODES: Record<string, [number, string]> = {
SQLITE_CONSTRAINT_UNIQUE: [409, 'duplicate'],
SQLITE_CONSTRAINT_PRIMARYKEY: [409, 'duplicate'],
SQLITE_CONSTRAINT_FOREIGNKEY: [409, 'reference_missing'],
SQLITE_CONSTRAINT_NOTNULL: [400, 'value_required'],
SQLITE_CONSTRAINT_CHECK: [400, 'value_rejected'],
SQLITE_MISMATCH: [400, 'invalid_value'],
};
export function mapError(err: unknown): RestError | null {
const code = (err as { code?: unknown })?.code;
const hit = typeof code === 'string' ? CODES[code] : undefined;
return hit ? new RestError(hit[0], hit[1]) : null;
}
const bindable = (v: unknown) => (v === true ? 1 : v === false ? 0 : v);
export interface SqliteOptions {
renderer?: SqlRenderer;
}
/**
* The SQLite dialect over a better-sqlite3 Database. It turns on foreign keys
* and case-sensitive LIKE for the connection. One connection runs one
* transaction at a time, so requests are queued. SQLite cannot stop a running
* statement, so `limits.timeoutMs` does not apply, and it has no functions to
* call as procedures.
*/
export function sqlite(db: Database, options: SqliteOptions = {}): Dialect {
db.pragma('foreign_keys = ON');
db.pragma('case_sensitive_like = ON');
let queue: Promise<unknown> = Promise.resolve();
return {
name: 'sqlite',
capabilities: { returning: true, estimatedCount: false, rowSecurity: false, procedures: false },
renderer: options.renderer ?? new SqliteRenderer(),
decode: (value) => (typeof value === 'string' ? JSON.parse(value) : value),
introspect: async (scope) => introspect(db, scope),
transaction(fn) {
const run = queue.then(async () => {
db.exec('BEGIN');
try {
const out = await fn({
async query(sql, params) {
const stmt = db.prepare(sql);
const bound = params.map(bindable);
return (stmt.reader ? stmt.all(...bound) : (stmt.run(...bound), [])) as Record<string, unknown>[];
},
});
db.exec('COMMIT');
return out;
} catch (err) {
if (db.inTransaction) db.exec('ROLLBACK');
throw err;
}
});
queue = run.catch(() => undefined);
return run;
},
mapError,
};
}
packages/sqlite/src/introspect.ts
+42
View File
@@ -0,0 +1,42 @@
import type { Catalog, CatalogTable } from '@crudy/restloom';
import type { Database } from 'better-sqlite3';
import { logical } from './types.js';
type Row = Record<string, unknown>;
/** Reads tables and views of the main database or of attached ones; SQLite's schemas are its attached databases. */
export function introspect(db: Database, scope: { schemas: string[]; tables: string[] }): Catalog {
const schemas = new Set([...scope.schemas, ...scope.tables.map((t) => t.split('.')[0])]);
const attached = new Set((db.prepare('PRAGMA database_list').all() as Row[]).map((r) => r.name as string));
const tables: CatalogTable[] = [];
for (const schema of schemas) {
if (!attached.has(schema)) continue;
const q = (s: string) => `"${s.replace(/"/g, '""')}"`;
const rows = db.prepare(`SELECT name, type FROM ${q(schema)}.sqlite_schema WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%'`).all() as Row[];
for (const r of rows) {
const name = r.name as string;
if (!scope.schemas.includes(schema) && !scope.tables.includes(`${schema}.${name}`)) continue;
const cols = db.prepare(`PRAGMA ${q(schema)}.table_xinfo(${q(name)})`).all() as Row[];
const fks = db.prepare(`PRAGMA ${q(schema)}.foreign_key_list(${q(name)})`).all() as Row[];
const byId = new Map<number, Row[]>();
for (const f of fks) byId.set(f.id as number, [...(byId.get(f.id as number) ?? []), f]);
tables.push({
schema, name, kind: r.type === 'view' ? 'view' : 'table',
columns: cols.filter((c) => c.hidden !== 1).map((c) => ({
name: c.name as string, nativeType: c.type as string, type: logical(c.type as string),
nullable: !c.notnull, generated: c.hidden === 2 || c.hidden === 3,
})),
primaryKey: cols.filter((c) => (c.pk as number) > 0).sort((a, b) => (a.pk as number) - (b.pk as number)).map((c) => c.name as string),
foreignKeys: [...byId.values()].map((parts) => {
const ordered = parts.sort((a, b) => (a.seq as number) - (b.seq as number));
return {
columns: ordered.map((p) => p.from as string),
target: { schema, table: ordered[0].table as string },
targetColumns: ordered.map((p) => p.to as string),
};
}),
});
}
}
return { tables, functions: [] };
}
packages/sqlite/src/renderer.ts
+43
View File
@@ -0,0 +1,43 @@
import { SqlRenderer, type CatalogColumn } from '@crudy/restloom';
/** SQLite: JSON through json_object and json_group_array, booleans as 0 and 1, positional placeholders. */
export class SqliteRenderer extends SqlRenderer {
placeholder(_index: number): string {
return '?';
}
jsonObject(pairs: [string, string][]): string {
return `json_object(${pairs.map(([k, v]) => `${this.literal(k)}, ${v}`).join(', ')})`;
}
jsonArray(rowExpr: string, orderExpr: string): string {
return `COALESCE(json_group_array(json(${rowExpr}) ORDER BY ${orderExpr}), json('[]'))`;
}
nested(expr: string): string {
return `json(${expr})`;
}
jsonValue(expr: string, column: CatalogColumn): string {
if (column.type === 'boolean') return `CASE WHEN ${expr} IS NULL THEN NULL WHEN ${expr} THEN json('true') ELSE json('false') END`;
if (column.type === 'json') return `json(${expr})`;
return expr;
}
like(expr: string, pattern: string, insensitive: boolean): string {
return insensitive ? `lower(${expr}) LIKE lower(${pattern}) ESCAPE '\\'` : `${expr} LIKE ${pattern} ESCAPE '\\'`;
}
isBoolean(expr: string, value: boolean): string {
return `${expr} = ${value ? 1 : 0}`;
}
/** SQLite sorts nulls first ascending; this keeps the Postgres order: last ascending, first descending. */
orderBy(expr: string, desc: boolean, nulls?: 'first' | 'last'): string {
return super.orderBy(expr, desc, nulls ?? (desc ? 'first' : 'last'));
}
page(limit: number | undefined, offset: number | undefined): string {
return limit === undefined && !offset ? '' : ` LIMIT ${limit ?? -1}${offset ? ` OFFSET ${offset}` : ''}`;
}
}
packages/sqlite/src/types.ts
+17
View File
@@ -0,0 +1,17 @@
import type { LogicalType } from '@crudy/restloom';
/** A declared SQLite column type as a logical type, by the same keyword rules SQLite uses for affinity, refined for common names. */
export function logical(declared: string): LogicalType {
const t = declared.toUpperCase();
if (t === 'BOOLEAN' || t === 'BOOL') return 'boolean';
if (t === 'UUID') return 'uuid';
if (t === 'DATE') return 'date';
if (t.includes('DATETIME') || t.includes('TIMESTAMP')) return 'timestamp';
if (t === 'TIME') return 'time';
if (t === 'JSON' || t === 'JSONB') return 'json';
if (t.includes('INT')) return 'integer';
if (t.includes('CHAR') || t.includes('CLOB') || t.includes('TEXT')) return 'text';
if (t.includes('BLOB') || t === '') return t === '' ? 'other' : 'binary';
if (t.includes('REAL') || t.includes('FLOA') || t.includes('DOUB') || t.includes('NUMERIC') || t.includes('DECIMAL')) return 'number';
return 'other';
}
packages/sqlite/tsconfig.json
+5
View File
@@ -0,0 +1,5 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": { "outDir": "dist", "rootDir": "src" },
"include": ["src"]
}