@tylix/orm 0.5.0 → 0.6.0

package/src/adapters/MongoAdapter.js

@@ -1,5 +1,50 @@
 import { MongoClient } from 'mongodb'
 import { DatabaseAdapter } from './DatabaseAdapter.js'
+import { normalizeDatabaseError } from './DatabaseError.js'
+
+// Same rule the SQL builder uses: plain identifiers only, with optional
+// dots for nested fields. Rejects "$where", "$or", spaces, quotes, etc.
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/
+
+// Same cap as the SQL builder, so a query that works on one driver
+// doesn't fail on another.
+const MAX_LIST_VALUES = 1000
+
+function assertField(name) {
+  if (typeof name !== 'string' || !IDENTIFIER.test(name)) {
+    throw new Error(`Invalid column name "${String(name)}".`)
+  }
+  return name
+}
+
+// Validates the array given to IN / NOT IN, with the same rules as SQL.
+function assertList(values, operator) {
+  if (!Array.isArray(values)) {
+    throw new Error(`Operator "${operator}" needs an array of values.`)
+  }
+  if (values.length > MAX_LIST_VALUES) {
+    throw new Error(
+      `Operator "${operator}" accepts at most ${MAX_LIST_VALUES} values, got ${values.length}.`,
+    )
+  }
+  if (values.some((v) => v === null || v === undefined)) {
+    throw new Error(
+      `"${operator}" lists cannot contain null or undefined. Use whereNull() / whereNotNull() for null checks.`,
+    )
+  }
+  return values
+}
+
+// SQL LIKE -> anchored, case-insensitive regex ("%" = any run, "_" = any
+// single character). Case-insensitive to match MySQL and SQLite.
+function likeToRegex(pattern) {
+  if (typeof pattern !== 'string') {
+    throw new Error('LIKE needs a string pattern.')
+  }
+  const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const source = escaped.replace(/%/g, '.*').replace(/_/g, '.')
+  return new RegExp(`^${source}$`, 'is')
+}
 
 export function parseQuery(sql) {
   const trimmed = sql.trim().replace(/\s+/g, ' ')
@@ -26,10 +71,6 @@ export function parseQuery(sql) {
     return { type: 'findOne', table: match[1], field: match[2] }
   }
 
-  if ((match = /^SELECT \* FROM (\w+) WHERE (\w+) = \?$/i.exec(trimmed))) {
-    return { type: 'findOne', table: match[1], field: match[2] }
-  }
-
   if ((match = /^SELECT \* FROM (\w+)$/i.exec(trimmed))) {
     return { type: 'findAll', table: match[1] }
   }
@@ -71,9 +112,22 @@ export class MongoAdapter extends DatabaseAdapter {
   }
 
   async connect() {
-    this.client = new MongoClient(this.url)
-    await this.client.connect()
-    this.db = this.client.db(this.dbName)
+    try {
+      // Fail after 5s instead of the driver's default 30s, so a stopped
+      // MongoDB server shows up quickly.
+      this.client = new MongoClient(this.url, { serverSelectionTimeoutMS: 5000 })
+      await this.client.connect()
+      this.db = this.client.db(this.dbName)
+    } catch (err) {
+      const error = normalizeDatabaseError('mongodb', err)
+      // Never print credentials: mongodb://user:pass@host -> mongodb://***@host
+      const safeUrl = String(this.url).replace(/\/\/[^@/]*@/, '//***@')
+      error.detail = `Tried ${safeUrl}, database "${this.dbName}"`
+      await this.client?.close().catch(() => {})
+      this.client = null
+      this.db = null
+      throw error
+    }
     return this
   }
 
@@ -95,6 +149,18 @@ export class MongoAdapter extends DatabaseAdapter {
     }
   }
 
+  // Wraps any Mongo operation so failures become DatabaseErrors.
+  // `sql` is whatever text best describes what was attempted: the
+  // SQL-like string for run/get/all, or an equivalent db.x.find(...)
+  // description for query/count/paginate.
+  async guard(ctx, fn) {
+    try {
+      return await fn()
+    } catch (err) {
+      throw normalizeDatabaseError('mongodb', err, ctx)
+    }
+  }
+
   async nextId(table) {
     const counters = this.db.collection('__tylix_counters')
     const result = await counters.findOneAndUpdate(
@@ -107,6 +173,10 @@ export class MongoAdapter extends DatabaseAdapter {
 
   async run(sql, params = []) {
     this.ensureConnected()
+    return this.guard({ sql, params }, () => this._run(sql, params))
+  }
+
+  async _run(sql, params) {
     const query = parseQuery(sql)
 
     if (query.type === 'createTable') {
@@ -179,100 +249,145 @@ export class MongoAdapter extends DatabaseAdapter {
 
   async get(sql, params = []) {
     this.ensureConnected()
-    const query = parseQuery(sql)
-
-    if (query.type === 'findOne') {
-      const doc = await this.db
-        .collection(query.table)
-        .findOne({ [query.field]: params[0] }, { projection: { _id: 0 } })
-      return doc ?? null
-    }
+    return this.guard({ sql, params }, async () => {
+      const query = parseQuery(sql)
+
+      if (query.type === 'findOne') {
+        const doc = await this.db
+          .collection(query.table)
+          .findOne({ [query.field]: params[0] }, { projection: { _id: 0 } })
+        return doc ?? null
+      }
 
-    throw new Error(`get() cannot handle query type "${query.type}"`)
+      throw new Error(`get() cannot handle query type "${query.type}"`)
+    })
   }
 
   async all(sql, params = []) {
     this.ensureConnected()
-    const query = parseQuery(sql)
-
-    if (query.type === 'findAll') {
-      return this.db
-        .collection(query.table)
-        .find({}, { projection: { _id: 0 } })
-        .toArray()
-    }
+    return this.guard({ sql, params }, async () => {
+      const query = parseQuery(sql)
+
+      if (query.type === 'findAll') {
+        return this.db
+          .collection(query.table)
+          .find({}, { projection: { _id: 0 } })
+          .toArray()
+      }
 
-    if (query.type === 'findOne') {
-      return this.db
-        .collection(query.table)
-        .find({ [query.field]: params[0] }, { projection: { _id: 0 } })
-        .toArray()
-    }
+      if (query.type === 'findOne') {
+        return this.db
+          .collection(query.table)
+          .find({ [query.field]: params[0] }, { projection: { _id: 0 } })
+          .toArray()
+      }
 
-    throw new Error(`all() cannot handle query type "${query.type}"`)
+      throw new Error(`all() cannot handle query type "${query.type}"`)
+    })
   }
 
   async count(table) {
     this.ensureConnected()
-    return this.db.collection(table).countDocuments()
+    return this.guard({ sql: `db.${table}.countDocuments()` }, () =>
+      this.db.collection(table).countDocuments(),
+    )
   }
 
   async paginate(table, limit, offset) {
     this.ensureConnected()
-    return this.db
-      .collection(table)
-      .find({}, { projection: { _id: 0 } })
-      .sort({ id: 1 })
-      .skip(offset)
-      .limit(limit)
-      .toArray()
+    return this.guard(
+      {
+        sql: `db.${table}.find({}).sort({"id":1}).skip(${offset}).limit(${limit})`,
+      },
+      () =>
+        this.db
+          .collection(table)
+          .find({}, { projection: { _id: 0 } })
+          .sort({ id: 1 })
+          .skip(offset)
+          .limit(limit)
+          .toArray(),
+    )
   }
 
   async listTables() {
     this.ensureConnected()
-    const collections = await this.db.listCollections().toArray()
-    return collections.map((c) => c.name)
+    return this.guard({ sql: 'db.listCollections()' }, async () => {
+      const collections = await this.db.listCollections().toArray()
+      return collections.map((c) => c.name)
+    })
   }
 
-  columnType() {
-    return null
-  }
-}
+  async query(table, { wheres = [], orders = [], limitValue, offsetValue } = {}) {
+    this.ensureConnected()
 
-MongoAdapter.prototype.query = async function (
-  table,
-  { wheres = [], orders = [], limitValue, offsetValue } = {},
-) {
-  this.ensureConnected()
-
-  const filter = {}
-  for (const w of wheres) {
-    if (w.operator === '=') filter[w.field] = w.value
-    else if (w.operator === '!=') filter[w.field] = { $ne: w.value }
-    else if (w.operator === '>') filter[w.field] = { $gt: w.value }
-    else if (w.operator === '<') filter[w.field] = { $lt: w.value }
-    else if (w.operator === '>=') filter[w.field] = { $gte: w.value }
-    else if (w.operator === '<=') filter[w.field] = { $lte: w.value }
-    else
-      throw new Error(
-        `Unsupported where operator "${w.operator}" for MongoAdapter`,
-      )
-  }
+    let filter = {}
+    const sort = {}
+    const description = () => {
+      const show = (value) =>
+        JSON.stringify(value, (key, v) => (v instanceof RegExp ? String(v) : v))
+      let text = `db.${table}.find(${show(filter)})`
+      if (Object.keys(sort).length) text += `.sort(${show(sort)})`
+      if (offsetValue !== undefined) text += `.skip(${offsetValue})`
+      if (limitValue !== undefined) text += `.limit(${limitValue})`
+      return text
+    }
 
-  let cursor = this.db
-    .collection(table)
-    .find(filter, { projection: { _id: 0 } })
+    return this.guard({ get sql() { return description() } }, async () => {
+      // Every condition goes into $and, so several conditions on the same
+      // field (age > 18 AND age < 65) all apply, like SQL. Values are
+      // always wrapped in an operator, so an object from the client can
+      // never be interpreted as a query operator itself.
+      const conditions = wheres.map((w) => {
+        const field = assertField(w.field)
+        const operator = String(w.operator).trim().replace(/\s+/g, ' ').toUpperCase()
+
+        if (operator === '=') return { [field]: { $eq: w.value } }
+        if (operator === '!=' || operator === '<>')
+          return { [field]: { $ne: w.value } }
+        if (operator === '>') return { [field]: { $gt: w.value } }
+        if (operator === '<') return { [field]: { $lt: w.value } }
+        if (operator === '>=') return { [field]: { $gte: w.value } }
+        if (operator === '<=') return { [field]: { $lte: w.value } }
+        if (operator === 'LIKE')
+          return { [field]: { $regex: likeToRegex(w.value) } }
+
+        // Mongo treats a missing field as null, so IS NULL also matches
+        // documents that don't have the field at all.
+        if (operator === 'IS NULL') return { [field]: { $eq: null } }
+        if (operator === 'IS NOT NULL') return { [field]: { $ne: null } }
+        if (operator === 'IN')
+          return { [field]: { $in: assertList(w.value, operator) } }
+        if (operator === 'NOT IN')
+          return { [field]: { $nin: assertList(w.value, operator) } }
+
+        throw new Error(
+          `Unsupported where operator "${w.operator}" for MongoAdapter`,
+        )
+      })
 
-  if (orders.length > 0) {
-    const sort = {}
-    orders.forEach((o) => {
-      sort[o.field] = o.direction.toUpperCase() === 'DESC' ? -1 : 1
+      if (conditions.length > 0) filter = { $and: conditions }
+
+      let cursor = this.db
+        .collection(table)
+        .find(filter, { projection: { _id: 0 } })
+
+      if (orders.length > 0) {
+        orders.forEach((o) => {
+          sort[assertField(o.field)] =
+            o.direction.toUpperCase() === 'DESC' ? -1 : 1
+        })
+        cursor = cursor.sort(sort)
+      }
+
+      if (offsetValue !== undefined) cursor = cursor.skip(offsetValue)
+      if (limitValue !== undefined) cursor = cursor.limit(limitValue)
+
+      return cursor.toArray()
     })
-    cursor = cursor.sort(sort)
   }
 
-  if (offsetValue !== undefined) cursor = cursor.skip(offsetValue)
-  if (limitValue !== undefined) cursor = cursor.limit(limitValue)
-
-  return cursor.toArray()
-}
+  columnType() {
+    return null
+  }
+}

package/src/adapters/MysqlAdapter.js

@@ -1,5 +1,6 @@
 import mysql from 'mysql2/promise'
 import { DatabaseAdapter } from './DatabaseAdapter.js'
+import { normalizeDatabaseError } from './DatabaseError.js'
 
 const COLUMN_TYPES = {
   increments: 'INT AUTO_INCREMENT PRIMARY KEY',
@@ -31,19 +32,28 @@ export class MysqlAdapter extends DatabaseAdapter {
     this.connection = null
   }
 
- async connect() {
-  this.connection = mysql.createPool({
-    ...this.config,
-    waitForConnections: true,
-    connectionLimit: 10,
-    queueLimit: 0,
-    enableKeepAlive: true,
-    keepAliveInitialDelay: 10000,
-  })
-  const conn = await this.connection.getConnection() // fail fast on bad credentials
-  conn.release()
-  return this
-}
+  async connect() {
+    this.connection = mysql.createPool({
+      ...this.config,
+      waitForConnections: true,
+      connectionLimit: 10,
+      queueLimit: 0,
+      enableKeepAlive: true,
+      keepAliveInitialDelay: 10000,
+    })
+    try {
+      const conn = await this.connection.getConnection() // fail fast on bad credentials
+      conn.release()
+    } catch (err) {
+      const error = normalizeDatabaseError('mysql', err)
+      const { host, port, user, database } = this.config
+      error.detail = `Tried ${host}:${port} as "${user}", database "${database}"`
+      await this.connection.end().catch(() => {})
+      this.connection = null
+      throw error
+    }
+    return this
+  }
 
   async close() {
     if (this.connection) {
@@ -62,51 +72,51 @@ export class MysqlAdapter extends DatabaseAdapter {
     }
   }
 
-  async run(sql, params = []) {
+  // The one place every statement runs through, so every MySQL failure
+  // is translated into a DatabaseError that carries the SQL.
+  async execute(sql, params = []) {
     this.ensureConnected()
     const converted = params.map(toMysqlDateTime)
-    const [result] = await this.connection.execute(sql, converted)
+    try {
+      const [result] = await this.connection.execute(sql, converted)
+      return result
+    } catch (err) {
+      throw normalizeDatabaseError('mysql', err, { sql, params: converted })
+    }
+  }
+
+  async run(sql, params = []) {
+    const result = await this.execute(sql, params)
     return { ...result, lastInsertRowid: result.insertId }
   }
 
   async get(sql, params = []) {
-    this.ensureConnected()
-    const converted = params.map(toMysqlDateTime)
-    const [rows] = await this.connection.execute(sql, converted)
+    const rows = await this.execute(sql, params)
     return rows[0] ?? null
   }
 
   async all(sql, params = []) {
-    this.ensureConnected()
-    const converted = params.map(toMysqlDateTime)
-    const [rows] = await this.connection.execute(sql, converted)
-    return rows
+    return this.execute(sql, params)
   }
 
   async count(table) {
-    this.ensureConnected()
-    const [rows] = await this.connection.execute(
-      `SELECT COUNT(*) as count FROM ${table}`,
-    )
+    const rows = await this.execute(`SELECT COUNT(*) as count FROM ${table}`)
     return Number(rows[0].count)
   }
 
   async paginate(table, limit, offset) {
-    this.ensureConnected()
     // mysql2 does not support ? placeholders for LIMIT/OFFSET reliably
     // across versions, so these are inlined after being forced to
     // integers here (never from raw user input) to avoid injection.
     const safeLimit = Number.isInteger(limit) ? limit : parseInt(limit, 10)
     const safeOffset = Number.isInteger(offset) ? offset : parseInt(offset, 10)
-    const [rows] = await this.connection.execute(
+    return this.execute(
       `SELECT * FROM ${table} ORDER BY id ASC LIMIT ${safeLimit} OFFSET ${safeOffset}`,
     )
-    return rows
   }
 
   async listTables() {
-    this.ensureConnected()
-    const [rows] = await this.connection.execute('SHOW TABLES')
+    const rows = await this.execute('SHOW TABLES')
     return rows.map((r) => Object.values(r)[0])
   }
 

package/src/adapters/PostgresAdapter.js

@@ -1,5 +1,6 @@
 import pg from 'pg'
 import { DatabaseAdapter } from './DatabaseAdapter.js'
+import { normalizeDatabaseError } from './DatabaseError.js'
 
 const COLUMN_TYPES = {
   increments: 'SERIAL PRIMARY KEY',
@@ -38,8 +39,24 @@ export class PostgresAdapter extends DatabaseAdapter {
 
   async connect() {
     this.pool = new pg.Pool(this.config)
+    try {
+      // pg connects lazily, so test it now. A wrong password or a
+      // stopped server should fail at startup, not on the first request.
+      const client = await this.pool.connect()
+      client.release()
+    } catch (err) {
+      const error = normalizeDatabaseError('postgres', err)
+      const { host, port, user, database } = this.config
+      error.detail = this.config.connectionString
+        ? 'Using DATABASE_URL connection string'
+        : `Tried ${host}:${port} as "${user}", database "${database}"`
+      await this.pool.end().catch(() => {})
+      this.pool = null
+      throw error
+    }
     return this
   }
+
   async close() {
     if (this.pool) {
       await this.pool.end()
@@ -57,39 +74,43 @@ export class PostgresAdapter extends DatabaseAdapter {
     }
   }
 
-  async run(sql, params = []) {
+  // The one place every statement runs through. `sql` here is the final
+  // SQL (with $1, $2 placeholders), exactly what PostgreSQL received.
+  async execute(sql, params = []) {
     this.ensureConnected()
-    const finalSql = toPositionalPlaceholders(ensureReturningId(sql))
-    const result = await this.pool.query(finalSql, params)
+    try {
+      return await this.pool.query(sql, params)
+    } catch (err) {
+      throw normalizeDatabaseError('postgres', err, { sql, params })
+    }
+  }
+
+  async run(sql, params = []) {
+    const result = await this.execute(
+      toPositionalPlaceholders(ensureReturningId(sql)),
+      params,
+    )
     const lastInsertRowid = result.rows[0]?.id
     return { ...result, lastInsertRowid }
   }
 
   async get(sql, params = []) {
-    this.ensureConnected()
-    const finalSql = toPositionalPlaceholders(sql)
-    const result = await this.pool.query(finalSql, params)
+    const result = await this.execute(toPositionalPlaceholders(sql), params)
     return result.rows[0] ?? null
   }
 
   async all(sql, params = []) {
-    this.ensureConnected()
-    const finalSql = toPositionalPlaceholders(sql)
-    const result = await this.pool.query(finalSql, params)
+    const result = await this.execute(toPositionalPlaceholders(sql), params)
     return result.rows
   }
 
   async count(table) {
-    this.ensureConnected()
-    const result = await this.pool.query(
-      `SELECT COUNT(*) as count FROM ${table}`,
-    )
+    const result = await this.execute(`SELECT COUNT(*) as count FROM ${table}`)
     return Number(result.rows[0].count)
   }
 
   async paginate(table, limit, offset) {
-    this.ensureConnected()
-    const result = await this.pool.query(
+    const result = await this.execute(
       `SELECT * FROM ${table} ORDER BY id ASC LIMIT $1 OFFSET $2`,
       [limit, offset],
     )
@@ -97,8 +118,7 @@ export class PostgresAdapter extends DatabaseAdapter {
   }
 
   async listTables() {
-    this.ensureConnected()
-    const result = await this.pool.query(
+    const result = await this.execute(
       "SELECT tablename FROM pg_tables WHERE schemaname = 'public'",
     )
     return result.rows.map((r) => r.tablename)
@@ -113,4 +133,4 @@ export class PostgresAdapter extends DatabaseAdapter {
     }
     return sql
   }
-}
+}

package/src/adapters/SqliteAdapter.js

@@ -1,4 +1,5 @@
 import { DatabaseAdapter } from './DatabaseAdapter.js'
+import { normalizeDatabaseError } from './DatabaseError.js'
 
 const COLUMN_TYPES = {
   increments: 'INTEGER PRIMARY KEY AUTOINCREMENT',
@@ -20,8 +21,14 @@ export class SqliteAdapter extends DatabaseAdapter {
   }
 
   async connect() {
-    const { DatabaseSync } = await import('node:sqlite')
-    this.db = new DatabaseSync(this.filename)
+    try {
+      const { DatabaseSync } = await import('node:sqlite')
+      this.db = new DatabaseSync(this.filename)
+    } catch (err) {
+      const error = normalizeDatabaseError('sqlite', err)
+      error.detail = `Database file: ${this.filename}`
+      throw error
+    }
     return this
   }
 
@@ -42,45 +49,48 @@ export class SqliteAdapter extends DatabaseAdapter {
     }
   }
 
-  async run(sql, params = []) {
+  // The one place every statement runs through. SQLite reports most
+  // mistakes (missing table or column, bad syntax) when the statement
+  // is prepared, so prepare() is inside the try as well.
+  execute(method, sql, params = []) {
     this.ensureConnected()
-    const stmt = this.db.prepare(sql)
-    return stmt.run(...params)
+    try {
+      return this.db.prepare(sql)[method](...params)
+    } catch (err) {
+      throw normalizeDatabaseError('sqlite', err, { sql, params })
+    }
+  }
+
+  async run(sql, params = []) {
+    return this.execute('run', sql, params)
   }
 
   async get(sql, params = []) {
-    this.ensureConnected()
-    const stmt = this.db.prepare(sql)
-    return stmt.get(...params) ?? null
+    return this.execute('get', sql, params) ?? null
   }
 
   async all(sql, params = []) {
-    this.ensureConnected()
-    const stmt = this.db.prepare(sql)
-    return stmt.all(...params)
+    return this.execute('all', sql, params)
   }
 
   async count(table) {
-    this.ensureConnected()
-    const row = this.db.prepare(`SELECT COUNT(*) as count FROM ${table}`).get()
+    const row = this.execute('get', `SELECT COUNT(*) as count FROM ${table}`)
     return row.count
   }
 
   async paginate(table, limit, offset) {
-    this.ensureConnected()
-    const stmt = this.db.prepare(
+    return this.execute(
+      'all',
       `SELECT * FROM ${table} ORDER BY id ASC LIMIT ? OFFSET ?`,
+      [limit, offset],
     )
-    return stmt.all(limit, offset)
   }
 
   async listTables() {
-    this.ensureConnected()
-    const rows = this.db
-      .prepare(
-        "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'",
-      )
-      .all()
+    const rows = this.execute(
+      'all',
+      "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'",
+    )
     return rows.map((r) => r.name)
   }
 
@@ -93,4 +103,4 @@ export class SqliteAdapter extends DatabaseAdapter {
     }
     return sql
   }
-}
+}