@tylix/orm 0.1.0

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@tylix/orm",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.js",
+  "scripts": {
+    "test": "node --test src/**/*.test.js"
+  },
+  "dependencies": {
+    "@tylix/shared": "*",
+    "mongodb": "^6.5.0",
+    "mysql2": "^3.9.0",
+    "pg": "^8.11.0"
+  }
+}

package/src/adapters/AdapterFactory.js

@@ -0,0 +1,24 @@
+import { SqliteAdapter } from "./SqliteAdapter.js";
+import { PostgresAdapter } from "./PostgresAdapter.js";
+import { MysqlAdapter } from "./MysqlAdapter.js";
+import { MongoAdapter } from "./MongoAdapter.js";
+
+const ADAPTERS = {
+  sqlite: SqliteAdapter,
+  postgres: PostgresAdapter,
+  mysql: MysqlAdapter,
+  mongodb: MongoAdapter,
+};
+
+export function createAdapter(databaseConfig) {
+  const { driver, ...options } = databaseConfig;
+
+  const AdapterClass = ADAPTERS[driver];
+  if (!AdapterClass) {
+    throw new Error(
+      `Unknown database driver "${driver}". Available drivers: ${Object.keys(ADAPTERS).join(", ")}`
+    );
+  }
+
+  return new AdapterClass(options);
+}

package/src/adapters/AdapterFactory.test.js

@@ -0,0 +1,35 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createAdapter } from "./AdapterFactory.js";
+import { SqliteAdapter } from "./SqliteAdapter.js";
+import { PostgresAdapter } from "./PostgresAdapter.js";
+import { MysqlAdapter } from "./MysqlAdapter.js";
+import { MongoAdapter } from "./MongoAdapter.js";
+
+test("creates a SqliteAdapter for driver: sqlite", () => {
+  const adapter = createAdapter({ driver: "sqlite", filename: "test.sqlite" });
+  assert.ok(adapter instanceof SqliteAdapter);
+  assert.equal(adapter.filename, "test.sqlite");
+});
+
+test("throws on unknown driver", () => {
+  assert.throws(
+    () => createAdapter({ driver: "oracle" }),
+    /Unknown database driver "oracle"/
+  );
+});
+
+test("creates a PostgresAdapter for driver: postgres", () => {
+  const adapter = createAdapter({ driver: "postgres", database: "test" });
+  assert.ok(adapter instanceof PostgresAdapter);
+});
+
+test("creates a MysqlAdapter for driver: mysql", () => {
+  const adapter = createAdapter({ driver: "mysql", database: "test" });
+  assert.ok(adapter instanceof MysqlAdapter);
+});
+
+test("creates a MongoAdapter for driver: mongodb", () => {
+  const adapter = createAdapter({ driver: "mongodb", database: "test" });
+  assert.ok(adapter instanceof MongoAdapter);
+});

package/src/adapters/DatabaseAdapter.js

@@ -0,0 +1,61 @@
+import { buildSelectSql } from '../query/buildSelectSql.js'
+
+/**
+ * Base contract every Tylix database adapter must implement.
+ * Concrete adapters (SqliteAdapter, PostgresAdapter, MysqlAdapter,
+ * MongoAdapter...) extend this and implement each method. Model and the
+ * migration runner only ever talk to this interface, never to a specific
+ * driver.
+ */
+export class DatabaseAdapter {
+  async connect() {
+    throw new Error('connect() not implemented')
+  }
+
+  async close() {
+    throw new Error('close() not implemented')
+  }
+
+  async run(sql, params = []) {
+    throw new Error('run() not implemented')
+  }
+
+  async get(sql, params = []) {
+    throw new Error('get() not implemented')
+  }
+
+  async all(sql, params = []) {
+    throw new Error('all() not implemented')
+  }
+
+  columnType(logicalType) {
+    throw new Error('columnType() not implemented')
+  }
+
+  async count(table) {
+    throw new Error('count() not implemented')
+  }
+
+  async paginate(table, limit, offset) {
+    throw new Error('paginate() not implemented')
+  }
+
+  async listTables() {
+    throw new Error('listTables() not implemented')
+  }
+
+  /**
+   * Runs a structured query descriptor ({ wheres, orders, limitValue,
+   * offsetValue }) against `table` and returns matching rows.
+   *
+   * Default implementation translates the descriptor to "?"-placeholder
+   * SQL via buildSelectSql() and delegates to this.all(), which every
+   * SQL adapter (Sqlite/Postgres/Mysql) already implements correctly
+   * for its own placeholder dialect and type conversions. MongoAdapter
+   * overrides this entirely since it has no SQL layer to delegate to.
+   */
+  async query(table, descriptor = {}) {
+    const { sql, params } = buildSelectSql(table, descriptor)
+    return this.all(sql, params)
+  }
+}

package/src/adapters/MongoAdapter.js

@@ -0,0 +1,274 @@
+import { MongoClient } from 'mongodb'
+import { DatabaseAdapter } from './DatabaseAdapter.js'
+
+export function parseQuery(sql) {
+  const trimmed = sql.trim().replace(/\s+/g, ' ')
+
+  let match
+
+  if ((match = /^CREATE TABLE IF NOT EXISTS (\w+)/i.exec(trimmed))) {
+    return { type: 'createTable', table: match[1] }
+  }
+
+  if ((match = /^DROP TABLE IF EXISTS (\w+)/i.exec(trimmed))) {
+    return { type: 'dropTable', table: match[1] }
+  }
+
+  if ((match = /^ALTER TABLE (\w+) ADD COLUMN (\w+)/i.exec(trimmed))) {
+    return { type: 'alterAddColumn', table: match[1], column: match[2] }
+  }
+
+  if ((match = /^ALTER TABLE (\w+) DROP COLUMN (\w+)$/i.exec(trimmed))) {
+    return { type: 'alterDropColumn', table: match[1], column: 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+) 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] }
+  }
+
+  if (
+    (match = /^INSERT INTO (\w+) \(([^)]+)\) VALUES \(([^)]+)\)$/i.exec(
+      trimmed,
+    ))
+  ) {
+    const columns = match[2].split(',').map((c) => c.trim())
+    return { type: 'insert', table: match[1], columns }
+  }
+
+  if ((match = /^UPDATE (\w+) SET (.+) WHERE (\w+) = \?$/i.exec(trimmed))) {
+    const setClause = match[2]
+    const columns = setClause
+      .split(',')
+      .map((pair) => pair.trim().split('=')[0].trim())
+    return { type: 'update', table: match[1], columns, whereField: match[3] }
+  }
+
+  if ((match = /^DELETE FROM (\w+) WHERE (\w+) = \?$/i.exec(trimmed))) {
+    return { type: 'delete', table: match[1], field: match[2] }
+  }
+
+  throw new Error(
+    `MongoAdapter does not recognize this query shape: "${trimmed}"`,
+  )
+}
+
+export class MongoAdapter extends DatabaseAdapter {
+  constructor({ url = 'mongodb://localhost:27017', database } = {}) {
+    super()
+    this.url = url
+    this.dbName = database
+    this.client = null
+    this.db = null
+    this.counters = {}
+  }
+
+  async connect() {
+    this.client = new MongoClient(this.url)
+    await this.client.connect()
+    this.db = this.client.db(this.dbName)
+    return this
+  }
+
+  async close() {
+    if (this.client) {
+      await this.client.close()
+      this.client = null
+      this.db = null
+    }
+  }
+
+  ensureConnected() {
+    if (!this.db) {
+      throw new Error('MongoAdapter is not connected. Call connect() first.')
+    }
+  }
+
+  async nextId(table) {
+    const counters = this.db.collection('__tylix_counters')
+    const result = await counters.findOneAndUpdate(
+      { _id: table },
+      { $inc: { seq: 1 } },
+      { upsert: true, returnDocument: 'after' },
+    )
+    return result.seq
+  }
+
+  async run(sql, params = []) {
+    this.ensureConnected()
+    const query = parseQuery(sql)
+
+    if (query.type === 'createTable') {
+      const collections = await this.db
+        .listCollections({ name: query.table })
+        .toArray()
+      if (collections.length === 0) {
+        await this.db.createCollection(query.table)
+      }
+      return {}
+    }
+
+    if (query.type === 'dropTable') {
+      const collections = await this.db
+        .listCollections({ name: query.table })
+        .toArray()
+      if (collections.length > 0) {
+        await this.db.collection(query.table).drop()
+      }
+      return {}
+    }
+
+    if (query.type === 'alterAddColumn') {
+      return {}
+    }
+
+    // Unlike ADD, DROP needs a real write: old documents still carry
+    // the removed field's data, and it would keep coming back in
+    // find()/query() results (Model.all(), etc.) forever unless
+    // explicitly stripped from every existing document.
+    if (query.type === 'alterDropColumn') {
+      await this.db
+        .collection(query.table)
+        .updateMany({}, { $unset: { [query.column]: '' } })
+      return {}
+    }
+
+    if (query.type === 'insert') {
+      const id = await this.nextId(query.table)
+      const doc = { id }
+      query.columns.forEach((col, i) => {
+        doc[col] = params[i]
+      })
+      await this.db.collection(query.table).insertOne(doc)
+      return { lastInsertRowid: id }
+    }
+
+    if (query.type === 'update') {
+      const whereValue = params[params.length - 1]
+      const setValues = params.slice(0, params.length - 1)
+      const $set = {}
+      query.columns.forEach((col, i) => {
+        $set[col] = setValues[i]
+      })
+      await this.db
+        .collection(query.table)
+        .updateOne({ [query.whereField]: whereValue }, { $set })
+      return {}
+    }
+
+    if (query.type === 'delete') {
+      await this.db
+        .collection(query.table)
+        .deleteOne({ [query.field]: params[0] })
+      return {}
+    }
+
+    throw new Error(`run() cannot handle query type "${query.type}"`)
+  }
+
+  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
+    }
+
+    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()
+    }
+
+    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}"`)
+  }
+
+  async count(table) {
+    this.ensureConnected()
+    return 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()
+  }
+
+  async listTables() {
+    this.ensureConnected()
+    const collections = await this.db.listCollections().toArray()
+    return collections.map((c) => c.name)
+  }
+
+  columnType() {
+    return null
+  }
+}
+
+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 cursor = this.db
+    .collection(table)
+    .find(filter, { projection: { _id: 0 } })
+
+  if (orders.length > 0) {
+    const sort = {}
+    orders.forEach((o) => {
+      sort[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()
+}

package/src/adapters/MongoAdapter.test.js

@@ -0,0 +1,52 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parseQuery, MongoAdapter } from "./MongoAdapter.js";
+
+test("recognizes SELECT * FROM table", () => {
+  assert.deepEqual(parseQuery("SELECT * FROM posts"), { type: "findAll", table: "posts" });
+});
+
+test("recognizes SELECT * FROM table WHERE field = ?", () => {
+  assert.deepEqual(parseQuery("SELECT * FROM posts WHERE id = ?"), {
+    type: "findOne",
+    table: "posts",
+    field: "id",
+  });
+});
+
+test("recognizes INSERT INTO table (cols) VALUES (?...)", () => {
+  const result = parseQuery("INSERT INTO posts (title, body) VALUES (?, ?)");
+  assert.equal(result.type, "insert");
+  assert.equal(result.table, "posts");
+  assert.deepEqual(result.columns, ["title", "body"]);
+});
+
+test("recognizes UPDATE table SET col=?,col=? WHERE field = ?", () => {
+  const result = parseQuery("UPDATE posts SET title = ?, body = ? WHERE id = ?");
+  assert.equal(result.type, "update");
+  assert.deepEqual(result.columns, ["title", "body"]);
+  assert.equal(result.whereField, "id");
+});
+
+test("recognizes DELETE FROM table WHERE field = ?", () => {
+  assert.deepEqual(parseQuery("DELETE FROM posts WHERE id = ?"), {
+    type: "delete",
+    table: "posts",
+    field: "id",
+  });
+});
+
+test("recognizes CREATE TABLE IF NOT EXISTS as a no-op shape", () => {
+  const result = parseQuery("CREATE TABLE IF NOT EXISTS posts (id INT)");
+  assert.equal(result.type, "createTable");
+  assert.equal(result.table, "posts");
+});
+
+test("throws clearly on an unrecognized query shape", () => {
+  assert.throws(() => parseQuery("SELECT COUNT(*) FROM posts"), /does not recognize/);
+});
+
+test("ensureConnected throws before connect() is called", async () => {
+  const adapter = new MongoAdapter({ database: "test" });
+  await assert.rejects(() => adapter.all("SELECT * FROM posts"));
+});

package/src/adapters/MysqlAdapter.js

@@ -0,0 +1,107 @@
+import mysql from 'mysql2/promise'
+import { DatabaseAdapter } from './DatabaseAdapter.js'
+
+const COLUMN_TYPES = {
+  increments: 'INT AUTO_INCREMENT PRIMARY KEY',
+  string: 'VARCHAR(255)',
+  text: 'TEXT',
+  boolean: 'TINYINT(1)',
+  integer: 'INT',
+  date: 'DATE',
+  datetime: 'DATETIME',
+  json: 'JSON',
+  timestamp: 'DATETIME',
+}
+
+const ISO_DATETIME_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/
+
+export function toMysqlDateTime(value) {
+  if (typeof value === 'string' && ISO_DATETIME_PATTERN.test(value)) {
+    return value.slice(0, 19).replace('T', ' ')
+  }
+  return value
+}
+
+export class MysqlAdapter extends DatabaseAdapter {
+  constructor({ host, port, user, password, database } = {}) {
+    super()
+    this.config = { host, port, user, password, database }
+    this.connection = null
+  }
+
+  async connect() {
+    this.connection = await mysql.createConnection(this.config)
+    return this
+  }
+
+  async close() {
+    if (this.connection) {
+      await this.connection.end()
+      this.connection = null
+    }
+  }
+
+  ensureConnected() {
+    if (!this.connection) {
+      throw new Error('MysqlAdapter is not connected. Call connect() first.')
+    }
+  }
+
+  async run(sql, params = []) {
+    this.ensureConnected()
+    const converted = params.map(toMysqlDateTime)
+    const [result] = await this.connection.execute(sql, converted)
+    return { ...result, lastInsertRowid: result.insertId }
+  }
+
+  async get(sql, params = []) {
+    this.ensureConnected()
+    const converted = params.map(toMysqlDateTime)
+    const [rows] = await this.connection.execute(sql, converted)
+    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
+  }
+
+  async count(table) {
+    this.ensureConnected()
+    const [rows] = await this.connection.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(
+      `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')
+    return rows.map((r) => Object.values(r)[0])
+  }
+
+  columnType(logicalType) {
+    const sql = COLUMN_TYPES[logicalType]
+    if (!sql) {
+      throw new Error(
+        `MysqlAdapter has no mapping for column type "${logicalType}"`,
+      )
+    }
+    return sql
+  }
+}

package/src/adapters/MysqlAdapter.test.js

@@ -0,0 +1,36 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { MysqlAdapter } from "./MysqlAdapter.js";
+
+test("columnType maps logical types to MySQL SQL types", () => {
+  const adapter = new MysqlAdapter({ database: "test" });
+  assert.equal(adapter.columnType("increments"), "INT AUTO_INCREMENT PRIMARY KEY");
+  assert.equal(adapter.columnType("string"), "VARCHAR(255)");
+  assert.equal(adapter.columnType("boolean"), "TINYINT(1)");
+  assert.equal(adapter.columnType("json"), "JSON");
+});
+
+test("columnType throws on unknown logical type", () => {
+  const adapter = new MysqlAdapter({ database: "test" });
+  assert.throws(() => adapter.columnType("nonsense"), /no mapping/);
+});
+
+test("ensureConnected throws before connect() is called", async () => {
+  const adapter = new MysqlAdapter({ database: "test" });
+  await assert.rejects(() => adapter.all("SELECT 1"));
+});
+
+test("toMysqlDateTime converts ISO 8601 strings to MySQL DATETIME format", async () => {
+  const { toMysqlDateTime } = await import("./MysqlAdapter.js");
+  assert.equal(
+    toMysqlDateTime("2026-07-14T03:35:14.083Z"),
+    "2026-07-14 03:35:14"
+  );
+});
+
+test("toMysqlDateTime leaves non-ISO-datetime values untouched", async () => {
+  const { toMysqlDateTime } = await import("./MysqlAdapter.js");
+  assert.equal(toMysqlDateTime("Hello Tylix"), "Hello Tylix");
+  assert.equal(toMysqlDateTime(42), 42);
+  assert.equal(toMysqlDateTime(true), true);
+});