@tylix/orm 0.1.0

package/src/adapters/PostgresAdapter.js

@@ -0,0 +1,113 @@
+import pg from 'pg'
+import { DatabaseAdapter } from './DatabaseAdapter.js'
+
+const COLUMN_TYPES = {
+  increments: 'SERIAL PRIMARY KEY',
+  string: 'TEXT',
+  text: 'TEXT',
+  boolean: 'BOOLEAN',
+  integer: 'INTEGER',
+  date: 'DATE',
+  datetime: 'TIMESTAMP',
+  json: 'JSONB',
+  timestamp: 'TIMESTAMP',
+}
+
+export function toPositionalPlaceholders(sql) {
+  let index = 0
+  return sql.replace(/\?/g, () => `$${++index}`)
+}
+
+export function ensureReturningId(sql) {
+  const isInsert = /^\s*INSERT\s+INTO/i.test(sql)
+  const hasReturning = /RETURNING/i.test(sql)
+  if (isInsert && !hasReturning) {
+    return `${sql.trim().replace(/;$/, '')} RETURNING id`
+  }
+  return sql
+}
+
+export class PostgresAdapter extends DatabaseAdapter {
+  constructor({ connectionString, host, port, user, password, database } = {}) {
+    super()
+    this.config = connectionString
+      ? { connectionString }
+      : { host, port, user, password, database }
+    this.pool = null
+  }
+
+  async connect() {
+    this.pool = new pg.Pool(this.config)
+    return this
+  }
+
+  async close() {
+    if (this.pool) {
+      await this.pool.end()
+      this.pool = null
+    }
+  }
+
+  ensureConnected() {
+    if (!this.pool) {
+      throw new Error('PostgresAdapter is not connected. Call connect() first.')
+    }
+  }
+
+  async run(sql, params = []) {
+    this.ensureConnected()
+    const finalSql = toPositionalPlaceholders(ensureReturningId(sql))
+    const result = await this.pool.query(finalSql, 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)
+    return result.rows[0] ?? null
+  }
+
+  async all(sql, params = []) {
+    this.ensureConnected()
+    const finalSql = toPositionalPlaceholders(sql)
+    const result = await this.pool.query(finalSql, params)
+    return result.rows
+  }
+
+  async count(table) {
+    this.ensureConnected()
+    const result = await this.pool.query(
+      `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(
+      `SELECT * FROM ${table} ORDER BY id ASC LIMIT $1 OFFSET $2`,
+      [limit, offset],
+    )
+    return result.rows
+  }
+
+  async listTables() {
+    this.ensureConnected()
+    const result = await this.pool.query(
+      "SELECT tablename FROM pg_tables WHERE schemaname = 'public'",
+    )
+    return result.rows.map((r) => r.tablename)
+  }
+
+  columnType(logicalType) {
+    const sql = COLUMN_TYPES[logicalType]
+    if (!sql) {
+      throw new Error(
+        `PostgresAdapter has no mapping for column type "${logicalType}"`,
+      )
+    }
+    return sql
+  }
+}

package/src/adapters/PostgresAdapter.test.js

@@ -0,0 +1,47 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { PostgresAdapter, toPositionalPlaceholders, ensureReturningId } from "./PostgresAdapter.js";
+
+test("toPositionalPlaceholders converts ? to $1, $2, $3...", () => {
+  const sql = "INSERT INTO posts (title, body) VALUES (?, ?)";
+  assert.equal(
+    toPositionalPlaceholders(sql),
+    "INSERT INTO posts (title, body) VALUES ($1, $2)"
+  );
+});
+
+test("toPositionalPlaceholders handles a single placeholder", () => {
+  assert.equal(toPositionalPlaceholders("SELECT * FROM posts WHERE id = ?"), "SELECT * FROM posts WHERE id = $1");
+});
+
+test("ensureReturningId appends RETURNING id to bare INSERT statements", () => {
+  const sql = "INSERT INTO posts (title) VALUES (?)";
+  assert.equal(ensureReturningId(sql), "INSERT INTO posts (title) VALUES (?) RETURNING id");
+});
+
+test("ensureReturningId does not duplicate an existing RETURNING clause", () => {
+  const sql = "INSERT INTO posts (title) VALUES (?) RETURNING id";
+  assert.equal(ensureReturningId(sql), sql);
+});
+
+test("ensureReturningId leaves non-INSERT statements untouched", () => {
+  const sql = "UPDATE posts SET title = ? WHERE id = ?";
+  assert.equal(ensureReturningId(sql), sql);
+});
+
+test("columnType maps logical types to Postgres SQL types", () => {
+  const adapter = new PostgresAdapter({ database: "test" });
+  assert.equal(adapter.columnType("increments"), "SERIAL PRIMARY KEY");
+  assert.equal(adapter.columnType("boolean"), "BOOLEAN");
+  assert.equal(adapter.columnType("json"), "JSONB");
+});
+
+test("columnType throws on unknown logical type", () => {
+  const adapter = new PostgresAdapter({ database: "test" });
+  assert.throws(() => adapter.columnType("nonsense"), /no mapping/);
+});
+
+test("ensureConnected throws before connect() is called", async () => {
+  const adapter = new PostgresAdapter({ database: "test" });
+  await assert.rejects(() => adapter.all("SELECT 1"));
+});

package/src/adapters/SqliteAdapter.js

@@ -0,0 +1,92 @@
+import { DatabaseAdapter } from './DatabaseAdapter.js'
+
+const COLUMN_TYPES = {
+  increments: 'INTEGER PRIMARY KEY AUTOINCREMENT',
+  string: 'TEXT',
+  text: 'TEXT',
+  boolean: 'INTEGER',
+  integer: 'INTEGER',
+  date: 'TEXT',
+  datetime: 'TEXT',
+  json: 'TEXT',
+  timestamp: 'TEXT',
+}
+
+export class SqliteAdapter extends DatabaseAdapter {
+  constructor({ filename = 'database.sqlite' } = {}) {
+    super()
+    this.filename = filename
+    this.db = null
+  }
+
+  async connect() {
+    const { DatabaseSync } = await import('node:sqlite')
+    this.db = new DatabaseSync(this.filename)
+    return this
+  }
+
+  async close() {
+    if (this.db) {
+      this.db.close()
+      this.db = null
+    }
+  }
+
+  ensureConnected() {
+    if (!this.db) {
+      throw new Error('SqliteAdapter is not connected. Call connect() first.')
+    }
+  }
+
+  async run(sql, params = []) {
+    this.ensureConnected()
+    const stmt = this.db.prepare(sql)
+    return stmt.run(...params)
+  }
+
+  async get(sql, params = []) {
+    this.ensureConnected()
+    const stmt = this.db.prepare(sql)
+    return stmt.get(...params) ?? null
+  }
+
+  async all(sql, params = []) {
+    this.ensureConnected()
+    const stmt = this.db.prepare(sql)
+    return stmt.all(...params)
+  }
+
+  async count(table) {
+    this.ensureConnected()
+    const row = this.db.prepare(`SELECT COUNT(*) as count FROM ${table}`).get()
+    return row.count
+  }
+
+  async paginate(table, limit, offset) {
+    this.ensureConnected()
+    const stmt = this.db.prepare(
+      `SELECT * FROM ${table} ORDER BY id ASC 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()
+    return rows.map((r) => r.name)
+  }
+
+  columnType(logicalType) {
+    const sql = COLUMN_TYPES[logicalType]
+    if (!sql) {
+      throw new Error(
+        `SqliteAdapter has no mapping for column type "${logicalType}"`,
+      )
+    }
+    return sql
+  }
+}

package/src/adapters/SqliteAdapter.test.js

@@ -0,0 +1,39 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { SqliteAdapter } from "./SqliteAdapter.js";
+
+test("connects, creates a table, inserts, and queries rows", async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "tylix-orm-test-"));
+  const dbFile = path.join(tmpDir, "test.sqlite");
+
+  const adapter = new SqliteAdapter({ filename: dbFile });
+  await adapter.connect();
+
+  await adapter.run(`
+    CREATE TABLE posts (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      title TEXT NOT NULL
+    )
+  `);
+
+  await adapter.run("INSERT INTO posts (title) VALUES (?)", ["Hello Tylix"]);
+  await adapter.run("INSERT INTO posts (title) VALUES (?)", ["Second Post"]);
+
+  const all = await adapter.all("SELECT * FROM posts");
+  assert.equal(all.length, 2);
+  assert.equal(all[0].title, "Hello Tylix");
+
+  const one = await adapter.get("SELECT * FROM posts WHERE id = ?", [1]);
+  assert.equal(one.title, "Hello Tylix");
+
+  await adapter.close();
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+test("ensureConnected throws if used before connect()", async () => {
+  const adapter = new SqliteAdapter({ filename: ":memory:" });
+  await assert.rejects(() => adapter.all("SELECT 1"));
+});

package/src/adapters/query.test.js

@@ -0,0 +1,60 @@
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { SqliteAdapter } from "./SqliteAdapter.js";
+
+let tmpDir;
+let adapter;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "tylix-query-test-"));
+  adapter = new SqliteAdapter({ filename: path.join(tmpDir, "test.sqlite") });
+  await adapter.connect();
+  await adapter.run(`
+    CREATE TABLE posts (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      title TEXT,
+      views INTEGER,
+      status TEXT
+    )
+  `);
+  await adapter.run("INSERT INTO posts (title, views, status) VALUES (?, ?, ?)", ["A", 50, "draft"]);
+  await adapter.run("INSERT INTO posts (title, views, status) VALUES (?, ?, ?)", ["B", 150, "published"]);
+  await adapter.run("INSERT INTO posts (title, views, status) VALUES (?, ?, ?)", ["C", 300, "published"]);
+});
+
+afterEach(async () => {
+  await adapter.close();
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+test("query() with a where filter", async () => {
+  const rows = await adapter.query("posts", {
+    wheres: [{ field: "status", operator: "=", value: "published" }],
+  });
+  assert.equal(rows.length, 2);
+});
+
+test("query() with where + orderBy + limit combined", async () => {
+  const rows = await adapter.query("posts", {
+    wheres: [{ field: "status", operator: "=", value: "published" }],
+    orders: [{ field: "views", direction: "DESC" }],
+    limitValue: 1,
+  });
+  assert.equal(rows.length, 1);
+  assert.equal(rows[0].title, "C");
+});
+
+test("query() with a > comparison operator", async () => {
+  const rows = await adapter.query("posts", {
+    wheres: [{ field: "views", operator: ">", value: 100 }],
+  });
+  assert.equal(rows.length, 2);
+});
+
+test("query() with no descriptor returns all rows", async () => {
+  const rows = await adapter.query("posts", {});
+  assert.equal(rows.length, 3);
+});

package/src/index.js

@@ -0,0 +1,9 @@
+export * from "./adapters/DatabaseAdapter.js";
+export * from "./adapters/SqliteAdapter.js";
+export * from "./model/ConnectionManager.js";
+export * from "./model/Model.js";
+export * from "./adapters/AdapterFactory.js";
+export * from "./adapters/MysqlAdapter.js";
+export * from "./adapters/MongoAdapter.js";
+export * from "./query/QueryBuilder.js";
+export * from "./query/buildSelectSql.js";

package/src/model/ConnectionManager.js

@@ -0,0 +1,20 @@
+let activeAdapter = null;
+
+export const ConnectionManager = {
+  setAdapter(adapter) {
+    activeAdapter = adapter;
+  },
+
+  getAdapter() {
+    if (!activeAdapter) {
+      throw new Error(
+        "No database adapter configured. Call ConnectionManager.setAdapter() before using models."
+      );
+    }
+    return activeAdapter;
+  },
+
+  reset() {
+    activeAdapter = null;
+  },
+};

package/src/model/Model.js

@@ -0,0 +1,141 @@
+import { ConnectionManager } from './ConnectionManager.js'
+import { QueryBuilder } from '../query/QueryBuilder.js'
+
+export class Model {
+  static table = null
+  static fillable = []
+  static timestamps = true
+
+  static getTable() {
+    if (!this.table) {
+      throw new Error(`${this.name} must define a static "table" property.`)
+    }
+    return this.table
+  }
+
+  static getAdapter() {
+    return ConnectionManager.getAdapter()
+  }
+
+  static async all() {
+    const adapter = ConnectionManager.getAdapter()
+    return adapter.all(`SELECT * FROM ${this.getTable()}`)
+  }
+
+  /**
+   * Returns a QueryBuilder for fluent filtering:
+   *   await Post.query().where("status", "published").orderBy("created_at", "DESC").get()
+   */
+  static query() {
+    return new QueryBuilder(this)
+  }
+
+  static async paginate({ page = 1, limit = 20 } = {}) {
+    const adapter = ConnectionManager.getAdapter()
+    const safePage = Math.max(1, Math.floor(page))
+    const safeLimit = Math.max(1, Math.min(100, Math.floor(limit)))
+    const offset = (safePage - 1) * safeLimit
+
+    const total = await adapter.count(this.getTable())
+    const data = await adapter.paginate(this.getTable(), safeLimit, offset)
+
+    return {
+      data,
+      meta: {
+        page: safePage,
+        limit: safeLimit,
+        total,
+        totalPages: Math.ceil(total / safeLimit),
+      },
+    }
+  }
+
+  static async find(id) {
+    const adapter = ConnectionManager.getAdapter()
+    return adapter.get(`SELECT * FROM ${this.getTable()} WHERE id = ?`, [id])
+  }
+
+  static async create(data) {
+    const adapter = ConnectionManager.getAdapter()
+    const fields = this.fillable.filter((f) => f in data)
+
+    if (fields.length === 0) {
+      throw new Error(`No fillable fields provided for ${this.name}.create()`)
+    }
+
+    const values = { ...Object.fromEntries(fields.map((f) => [f, data[f]])) }
+
+    if (this.timestamps) {
+      const now = new Date().toISOString()
+      values.created_at = now
+      values.updated_at = now
+    }
+
+    const columns = Object.keys(values)
+    const placeholders = columns.map(() => '?').join(', ')
+    const columnValues = Object.values(values)
+
+    const result = await adapter.run(
+      `INSERT INTO ${this.getTable()} (${columns.join(', ')}) VALUES (${placeholders})`,
+      columnValues,
+    )
+
+    return this.find(result.lastInsertRowid)
+  }
+
+  static async update(id, data) {
+    const adapter = ConnectionManager.getAdapter()
+    const fields = this.fillable.filter((f) => f in data)
+
+    if (fields.length === 0) {
+      throw new Error(`No fillable fields provided for ${this.name}.update()`)
+    }
+
+    const values = { ...Object.fromEntries(fields.map((f) => [f, data[f]])) }
+
+    if (this.timestamps) {
+      values.updated_at = new Date().toISOString()
+    }
+
+    const setClause = Object.keys(values)
+      .map((f) => `${f} = ?`)
+      .join(', ')
+    const columnValues = Object.values(values)
+
+    await adapter.run(
+      `UPDATE ${this.getTable()} SET ${setClause} WHERE id = ?`,
+      [...columnValues, id],
+    )
+
+    return this.find(id)
+  }
+
+  static async delete(id) {
+    const adapter = ConnectionManager.getAdapter()
+    await adapter.run(`DELETE FROM ${this.getTable()} WHERE id = ?`, [id])
+    return true
+  }
+
+  static async belongsTo(row, foreignKey, RelatedModel) {
+    if (!row || row[foreignKey] === undefined || row[foreignKey] === null) {
+      return null
+    }
+    return RelatedModel.find(row[foreignKey])
+  }
+
+  static async hasMany(row, RelatedModel, foreignKey) {
+    const adapter = ConnectionManager.getAdapter()
+    return adapter.all(
+      `SELECT * FROM ${RelatedModel.getTable()} WHERE ${foreignKey} = ?`,
+      [row.id],
+    )
+  }
+
+  static async first() {
+    return this.query().first()
+  }
+
+  static async count() {
+    return this.query().count()
+  }
+}

package/src/model/Model.paginate.test.js

@@ -0,0 +1,74 @@
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { SqliteAdapter } from "../adapters/SqliteAdapter.js";
+import { ConnectionManager } from "./ConnectionManager.js";
+import { Model } from "./Model.js";
+
+class Post extends Model {
+  static table = "posts";
+  static fillable = ["title"];
+}
+
+let tmpDir;
+let adapter;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "tylix-paginate-test-"));
+  adapter = new SqliteAdapter({ filename: path.join(tmpDir, "test.sqlite") });
+  await adapter.connect();
+  await adapter.run(`
+    CREATE TABLE posts (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      title TEXT,
+      created_at TEXT,
+      updated_at TEXT
+    )
+  `);
+  ConnectionManager.setAdapter(adapter);
+
+  for (let i = 1; i <= 25; i++) {
+    await Post.create({ title: `Post ${i}` });
+  }
+});
+
+afterEach(async () => {
+  await adapter.close();
+  await fs.rm(tmpDir, { recursive: true, force: true });
+  ConnectionManager.reset();
+});
+
+test("paginate() defaults to page 1, limit 20", async () => {
+  const result = await Post.paginate();
+  assert.equal(result.data.length, 20);
+  assert.equal(result.data[0].title, "Post 1");
+  assert.equal(result.meta.page, 1);
+  assert.equal(result.meta.limit, 20);
+  assert.equal(result.meta.total, 25);
+  assert.equal(result.meta.totalPages, 2);
+});
+
+test("paginate() returns the second page correctly", async () => {
+  const result = await Post.paginate({ page: 2, limit: 20 });
+  assert.equal(result.data.length, 5);
+  assert.equal(result.data[0].title, "Post 21");
+});
+
+test("paginate() respects a custom limit", async () => {
+  const result = await Post.paginate({ page: 1, limit: 10 });
+  assert.equal(result.data.length, 10);
+  assert.equal(result.meta.totalPages, 3);
+});
+
+test("paginate() clamps limit to a maximum of 100", async () => {
+  const result = await Post.paginate({ page: 1, limit: 9999 });
+  assert.equal(result.meta.limit, 100);
+});
+
+test("paginate() clamps page to a minimum of 1", async () => {
+  const result = await Post.paginate({ page: -5, limit: 20 });
+  assert.equal(result.meta.page, 1);
+  assert.equal(result.data[0].title, "Post 1");
+});

package/src/model/Model.relations.test.js

@@ -0,0 +1,86 @@
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { SqliteAdapter } from "../adapters/SqliteAdapter.js";
+import { ConnectionManager } from "./ConnectionManager.js";
+import { Model } from "./Model.js";
+
+class Post extends Model {
+  static table = "posts";
+  static fillable = ["title"];
+}
+
+class Comment extends Model {
+  static table = "comments";
+  static fillable = ["content", "post_id"];
+}
+
+let tmpDir;
+let adapter;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "tylix-relations-test-"));
+  adapter = new SqliteAdapter({ filename: path.join(tmpDir, "test.sqlite") });
+  await adapter.connect();
+
+  await adapter.run(`
+    CREATE TABLE posts (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      title TEXT,
+      created_at TEXT,
+      updated_at TEXT
+    )
+  `);
+
+  await adapter.run(`
+    CREATE TABLE comments (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      content TEXT,
+      post_id INTEGER,
+      created_at TEXT,
+      updated_at TEXT
+    )
+  `);
+
+  ConnectionManager.setAdapter(adapter);
+});
+
+afterEach(async () => {
+  await adapter.close();
+  await fs.rm(tmpDir, { recursive: true, force: true });
+  ConnectionManager.reset();
+});
+
+test("belongsTo() loads the parent row via foreign key", async () => {
+  const post = await Post.create({ title: "Hello" });
+  const comment = await Comment.create({ content: "Nice post!", post_id: post.id });
+
+  const loadedPost = await Comment.belongsTo(comment, "post_id", Post);
+  assert.equal(loadedPost.title, "Hello");
+});
+
+test("belongsTo() returns null when foreign key is missing", async () => {
+  const orphan = { content: "no post", post_id: null };
+  const result = await Comment.belongsTo(orphan, "post_id", Post);
+  assert.equal(result, null);
+});
+
+test("hasMany() loads all child rows for a parent", async () => {
+  const post = await Post.create({ title: "Popular Post" });
+  await Comment.create({ content: "First!", post_id: post.id });
+  await Comment.create({ content: "Second!", post_id: post.id });
+  await Comment.create({ content: "Unrelated", post_id: 9999 });
+
+  const comments = await Post.hasMany(post, Comment, "post_id");
+  assert.equal(comments.length, 2);
+  assert.equal(comments[0].content, "First!");
+  assert.equal(comments[1].content, "Second!");
+});
+
+test("hasMany() returns an empty array when there are no children", async () => {
+  const post = await Post.create({ title: "Lonely Post" });
+  const comments = await Post.hasMany(post, Comment, "post_id");
+  assert.deepEqual(comments, []);
+});