@tylix/orm 0.1.0

package/src/model/Model.test.js

@@ -0,0 +1,91 @@
+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", "body"];
+}
+
+let tmpDir;
+let adapter;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "tylix-model-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 NOT NULL,
+      body TEXT,
+      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("create() inserts a row and returns it", async () => {
+  const post = await Post.create({ title: "Hello Tylix", body: "First post" });
+  assert.equal(post.title, "Hello Tylix");
+  assert.equal(post.body, "First post");
+  assert.ok(post.id);
+});
+
+test("create() populates created_at and updated_at", async () => {
+  const post = await Post.create({ title: "Timestamped", body: "..." });
+  assert.ok(post.created_at, "created_at should be set");
+  assert.ok(post.updated_at, "updated_at should be set");
+  assert.ok(!Number.isNaN(Date.parse(post.created_at)), "created_at should be a valid date string");
+});
+
+test("all() returns every row", async () => {
+  await Post.create({ title: "One", body: "..." });
+  await Post.create({ title: "Two", body: "..." });
+  const posts = await Post.all();
+  assert.equal(posts.length, 2);
+});
+
+test("find() returns a single row by id", async () => {
+  const created = await Post.create({ title: "Findable", body: "..." });
+  const found = await Post.find(created.id);
+  assert.equal(found.title, "Findable");
+});
+
+test("update() modifies a row and returns the updated version", async () => {
+  const created = await Post.create({ title: "Original", body: "..." });
+  const updated = await Post.update(created.id, { title: "Updated" });
+  assert.equal(updated.title, "Updated");
+});
+
+test("update() bumps updated_at without changing created_at", async () => {
+  const created = await Post.create({ title: "Original", body: "..." });
+  await new Promise((resolve) => setTimeout(resolve, 10));
+  const updated = await Post.update(created.id, { title: "Changed" });
+
+  assert.equal(updated.created_at, created.created_at);
+  assert.notEqual(updated.updated_at, created.updated_at);
+});
+
+test("delete() removes a row", async () => {
+  const created = await Post.create({ title: "ToDelete", body: "..." });
+  await Post.delete(created.id);
+  const found = await Post.find(created.id);
+  assert.equal(found, null);
+});
+
+test("create() throws if no fillable fields are provided", async () => {
+  await assert.rejects(() => Post.create({ nonExistentField: "x" }));
+});

package/src/query/QueryBuilder.js

@@ -0,0 +1,66 @@
+/**
+ * Fluent query builder returned by Model.query(). Accumulates a
+ * structured descriptor and only hits the database when a terminal
+ * method (get/first/count) is called.
+ */
+export class QueryBuilder {
+  constructor(ModelClass) {
+    this.ModelClass = ModelClass;
+    this.wheres = [];
+    this.orders = [];
+    this.limitValue = undefined;
+    this.offsetValue = undefined;
+  }
+
+  where(field, operatorOrValue, maybeValue) {
+    const hasExplicitOperator = maybeValue !== undefined;
+    const operator = hasExplicitOperator ? operatorOrValue : "=";
+    const value = hasExplicitOperator ? maybeValue : operatorOrValue;
+
+    this.wheres.push({ field, operator, value });
+    return this;
+  }
+
+  orderBy(field, direction = "ASC") {
+    const normalized = direction.toUpperCase();
+    if (normalized !== "ASC" && normalized !== "DESC") {
+      throw new Error(`orderBy direction must be "ASC" or "DESC", got "${direction}"`);
+    }
+    this.orders.push({ field, direction: normalized });
+    return this;
+  }
+
+  limit(value) {
+    this.limitValue = value;
+    return this;
+  }
+
+  offset(value) {
+    this.offsetValue = value;
+    return this;
+  }
+
+  toDescriptor() {
+    return {
+      wheres: this.wheres,
+      orders: this.orders,
+      limitValue: this.limitValue,
+      offsetValue: this.offsetValue,
+    };
+  }
+
+  async get() {
+    const adapter = this.ModelClass.getAdapter();
+    return adapter.query(this.ModelClass.getTable(), this.toDescriptor());
+  }
+
+  async first() {
+    const results = await this.limit(1).get();
+    return results[0] ?? null;
+  }
+
+  async count() {
+    const rows = await this.get();
+    return rows.length;
+  }
+}

package/src/query/QueryBuilder.test.js

@@ -0,0 +1,82 @@
+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 "../model/ConnectionManager.js";
+import { Model } from "../model/Model.js";
+
+class Post extends Model {
+  static table = "posts";
+  static fillable = ["title", "views", "status"];
+}
+
+let tmpDir;
+let adapter;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "tylix-querybuilder-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,
+      created_at TEXT,
+      updated_at TEXT
+    )
+  `);
+  ConnectionManager.setAdapter(adapter);
+
+  await Post.create({ title: "Draft Post", views: 10, status: "draft" });
+  await Post.create({ title: "Popular Post", views: 500, status: "published" });
+  await Post.create({ title: "Medium Post", views: 150, status: "published" });
+});
+
+afterEach(async () => {
+  await adapter.close();
+  await fs.rm(tmpDir, { recursive: true, force: true });
+  ConnectionManager.reset();
+});
+
+test("Post.query() with where() filters correctly", async () => {
+  const results = await Post.query().where("status", "published").get();
+  assert.equal(results.length, 2);
+});
+
+test("where() with explicit operator", async () => {
+  const results = await Post.query().where("views", ">", 100).get();
+  assert.equal(results.length, 2);
+});
+
+test("orderBy() and limit() chain correctly", async () => {
+  const results = await Post.query()
+    .where("status", "published")
+    .orderBy("views", "DESC")
+    .limit(1)
+    .get();
+
+  assert.equal(results.length, 1);
+  assert.equal(results[0].title, "Popular Post");
+});
+
+test("first() returns a single row or null", async () => {
+  const found = await Post.query().where("status", "draft").first();
+  assert.equal(found.title, "Draft Post");
+
+  const notFound = await Post.query().where("status", "archived").first();
+  assert.equal(notFound, null);
+});
+
+test("count() returns the number of matching rows", async () => {
+  const count = await Post.query().where("status", "published").count();
+  assert.equal(count, 2);
+});
+
+test("query() with no where() returns all rows", async () => {
+  const results = await Post.query().get();
+  assert.equal(results.length, 3);
+});

package/src/query/buildSelectSql.js

@@ -0,0 +1,50 @@
+const SUPPORTED_OPERATORS = ["=", "!=", ">", "<", ">=", "<="];
+
+/**
+ * Translates a structured query descriptor into a "?"-placeholder SQL
+ * string + params array. Shared by SqliteAdapter, PostgresAdapter, and
+ * MysqlAdapter via DatabaseAdapter's default query() implementation --
+ * each adapter's existing all()/run() already handles placeholder
+ * translation and datetime conversion correctly per driver, so this
+ * only needs to speak the common "?" dialect.
+ *
+ * limit/offset are inlined as validated integers rather than passed as
+ * placeholders, since mysql2 does not reliably support placeholders in
+ * LIMIT/OFFSET position (same reasoning as Model.paginate()).
+ */
+export function buildSelectSql(table, { wheres = [], orders = [], limitValue, offsetValue } = {}) {
+  const params = [];
+  let sql = `SELECT * FROM ${table}`;
+
+  if (wheres.length > 0) {
+    const clauses = wheres.map((w) => {
+      if (!SUPPORTED_OPERATORS.includes(w.operator)) {
+        throw new Error(
+          `Unsupported where operator "${w.operator}". Supported: ${SUPPORTED_OPERATORS.join(", ")}`
+        );
+      }
+      params.push(w.value);
+      return `${w.field} ${w.operator} ?`;
+    });
+    sql += ` WHERE ${clauses.join(" AND ")}`;
+  }
+
+  if (orders.length > 0) {
+    const clauses = orders.map((o) => `${o.field} ${o.direction}`);
+    sql += ` ORDER BY ${clauses.join(", ")}`;
+  }
+
+  if (limitValue !== undefined) {
+    const safeLimit = Number.isInteger(limitValue) ? limitValue : parseInt(limitValue, 10);
+    if (!Number.isFinite(safeLimit)) throw new Error("limit must be a valid integer");
+    sql += ` LIMIT ${safeLimit}`;
+  }
+
+  if (offsetValue !== undefined) {
+    const safeOffset = Number.isInteger(offsetValue) ? offsetValue : parseInt(offsetValue, 10);
+    if (!Number.isFinite(safeOffset)) throw new Error("offset must be a valid integer");
+    sql += ` OFFSET ${safeOffset}`;
+  }
+
+  return { sql, params };
+}

package/src/query/buildSelectSql.test.js

@@ -0,0 +1,58 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildSelectSql } from "./buildSelectSql.js";
+
+test("builds a plain SELECT with no conditions", () => {
+  const { sql, params } = buildSelectSql("posts", {});
+  assert.equal(sql, "SELECT * FROM posts");
+  assert.deepEqual(params, []);
+});
+
+test("builds a WHERE clause with = operator", () => {
+  const { sql, params } = buildSelectSql("posts", {
+    wheres: [{ field: "status", operator: "=", value: "published" }],
+  });
+  assert.equal(sql, "SELECT * FROM posts WHERE status = ?");
+  assert.deepEqual(params, ["published"]);
+});
+
+test("builds multiple WHERE clauses joined by AND", () => {
+  const { sql, params } = buildSelectSql("posts", {
+    wheres: [
+      { field: "status", operator: "=", value: "published" },
+      { field: "views", operator: ">", value: 100 },
+    ],
+  });
+  assert.equal(sql, "SELECT * FROM posts WHERE status = ? AND views > ?");
+  assert.deepEqual(params, ["published", 100]);
+});
+
+test("builds an ORDER BY clause", () => {
+  const { sql } = buildSelectSql("posts", {
+    orders: [{ field: "created_at", direction: "DESC" }],
+  });
+  assert.equal(sql, "SELECT * FROM posts ORDER BY created_at DESC");
+});
+
+test("inlines LIMIT and OFFSET as validated integers, not placeholders", () => {
+  const { sql, params } = buildSelectSql("posts", { limitValue: 10, offsetValue: 20 });
+  assert.equal(sql, "SELECT * FROM posts LIMIT 10 OFFSET 20");
+  assert.deepEqual(params, []);
+});
+
+test("combines where, orderBy, and limit together", () => {
+  const { sql, params } = buildSelectSql("posts", {
+    wheres: [{ field: "status", operator: "=", value: "published" }],
+    orders: [{ field: "created_at", direction: "ASC" }],
+    limitValue: 5,
+  });
+  assert.equal(sql, "SELECT * FROM posts WHERE status = ? ORDER BY created_at ASC LIMIT 5");
+  assert.deepEqual(params, ["published"]);
+});
+
+test("throws on an unsupported operator", () => {
+  assert.throws(
+    () => buildSelectSql("posts", { wheres: [{ field: "x", operator: "LIKE", value: "y" }] }),
+    /Unsupported where operator/
+  );
+});