@xacos/orm 1.0.0

package/dist/utils/paginate.d.ts

@@ -0,0 +1,14 @@
+import type { Knex } from 'knex';
+import type { PaginatedResult } from '@xacos/shared';
+/**
+ * Paginate any Knex query builder.
+ *
+ * @example
+ * const result = await paginate(
+ *   User.query().where('role', 'admin'),
+ *   req.query.page,
+ *   15
+ * );
+ */
+export declare function paginate<T>(query: Knex.QueryBuilder, page?: number | string, perPage?: number | string): Promise<PaginatedResult<T>>;
+//# sourceMappingURL=paginate.d.ts.map

package/dist/utils/paginate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginate.d.ts","sourceRoot":"","sources":["../../src/utils/paginate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,KAAK,EAAE,IAAI,CAAC,YAAY,EACxB,IAAI,GAAE,MAAM,GAAG,MAAU,EACzB,OAAO,GAAE,MAAM,GAAG,MAAW,GAC5B,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAmB7B"}

package/dist/utils/paginate.js

@@ -0,0 +1,28 @@
+/**
+ * Paginate any Knex query builder.
+ *
+ * @example
+ * const result = await paginate(
+ *   User.query().where('role', 'admin'),
+ *   req.query.page,
+ *   15
+ * );
+ */
+export async function paginate(query, page = 1, perPage = 15) {
+    const p = Math.max(1, Number(page));
+    const pp = Math.min(100, Math.max(1, Number(perPage))); // cap at 100
+    const offset = (p - 1) * pp;
+    // Clone the query for count — without order/limit
+    const countQuery = query.clone().clearOrder().clearSelect().count('* as total').first();
+    const countResult = await countQuery;
+    const total = Number(countResult?.total ?? 0);
+    const data = await query.offset(offset).limit(pp);
+    return {
+        data,
+        total,
+        page: p,
+        perPage: pp,
+        lastPage: Math.ceil(total / pp),
+    };
+}
+//# sourceMappingURL=paginate.js.map

package/dist/utils/paginate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginate.js","sourceRoot":"","sources":["../../src/utils/paginate.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,KAAwB,EACxB,OAAwB,CAAC,EACzB,UAA2B,EAAE;IAE7B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACpC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa;IACrE,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;IAE5B,kDAAkD;IAClD,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,UAAU,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,KAAK,EAAE,CAAC;IACxF,MAAM,WAAW,GAAG,MAAM,UAAwC,CAAC;IACnE,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC;IAE9C,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,EAAE,CAAQ,CAAC;IAEzD,OAAO;QACL,IAAI;QACJ,KAAK;QACL,IAAI,EAAE,CAAC;QACP,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;KAChC,CAAC;AACJ,CAAC"}

package/dist/utils/paginate.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=paginate.test.d.ts.map

package/dist/utils/paginate.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginate.test.d.ts","sourceRoot":"","sources":["../../src/utils/paginate.test.ts"],"names":[],"mappings":""}

package/dist/utils/paginate.test.js

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "bun:test";
+import { paginate } from "./paginate";
+describe("paginate", () => {
+    it("caps perPage at 100 and ensures page is at least 1", async () => {
+        const mockQuery = {
+            clone: () => mockQuery,
+            clearOrder: () => mockQuery,
+            clearSelect: () => mockQuery,
+            count: () => mockQuery,
+            first: async () => ({ total: 50 }),
+            offset: (off) => ({
+                limit: async (lim) => [{ id: 1, off, lim }],
+            }),
+        };
+        const res = await paginate(mockQuery, -5, 999);
+        expect(res.page).toBe(1);
+        expect(res.perPage).toBe(100);
+        expect(res.total).toBe(50);
+        expect(res.lastPage).toBe(1);
+        expect(res.data).toEqual([{ id: 1, off: 0, lim: 100 }]);
+    });
+});
+//# sourceMappingURL=paginate.test.js.map

package/dist/utils/paginate.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginate.test.js","sourceRoot":"","sources":["../../src/utils/paginate.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE;IACxB,EAAE,CAAC,oDAAoD,EAAE,KAAK,IAAI,EAAE;QAClE,MAAM,SAAS,GAAG;YAChB,KAAK,EAAE,GAAG,EAAE,CAAC,SAAS;YACtB,UAAU,EAAE,GAAG,EAAE,CAAC,SAAS;YAC3B,WAAW,EAAE,GAAG,EAAE,CAAC,SAAS;YAC5B,KAAK,EAAE,GAAG,EAAE,CAAC,SAAS;YACtB,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;YAClC,MAAM,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,CAAC;gBACxB,KAAK,EAAE,KAAK,EAAE,GAAW,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;aACpD,CAAC;SACH,CAAC;QAEF,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,SAAgB,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACtD,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACzB,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC9B,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC3B,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC7B,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,CAAQ,CAAC,CAAC;IACjE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@xacos/orm",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "bun test src --seq",
+    "test:integration": "DB_DRIVER=sqlite DB_PATH=./tmp-integration.sqlite bun test src/__tests__/sqlite.integration.test.ts",
+    "type-check": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@faker-js/faker": "^10.4.0",
+    "@xacos/shared": "workspace:*",
+    "knex": "^3.1.0",
+    "mongoose": "^8.10.1",
+    "sqlite3": "^5.1.7"
+  },
+  "optionalDependencies": {
+    "mysql2": "^3.11.5",
+    "pg": "^8.13.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "bun-types": "^1.3.12"
+  },
+  "license": "MIT",
+  "author": "XAOCS Team",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zoherr/xaocs.git",
+    "directory": "packages/orm"
+  },
+  "homepage": "https://xaocs.dev",
+  "bugs": {
+    "url": "https://github.com/zoherr/xaocs/issues"
+  },
+  "keywords": [
+    "xaocs",
+    "xacos",
+    "framework",
+    "typescript",
+    "fullstack",
+    "fastify",
+    "react",
+    "orm",
+    "knex",
+    "sqlite",
+    "postgres",
+    "mysql",
+    "active-record"
+  ],
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "provenance": false
+  },
+  "engines": {
+    "bun": ">=1.0.0",
+    "node": ">=18.0.0"
+  }
+}

package/src/XModel.test.ts

@@ -0,0 +1,147 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { registerColumnMeta, registerRelation } from "./decorators";
+import { closeDb, getKnex, initDb } from "./index";
+import { XModel } from "./XModel";
+
+class Post extends XModel {
+  static override table = "posts";
+}
+
+class User extends XModel {
+  static override table = "users";
+  posts?: unknown;
+}
+
+registerRelation(User, {
+  kind: "hasMany",
+  related: () => Post,
+  foreignKey: "user_id",
+  propertyKey: "posts",
+});
+
+class UserSoft extends XModel {
+  static override table = "users";
+  static override softDeletes = true;
+}
+
+class Profile extends XModel {
+  static override table = "profiles";
+  secret?: string;
+}
+
+registerColumnMeta(Profile, "secret", { hidden: true });
+
+describe("XModel", () => {
+  beforeAll(async () => {
+    initDb({ __memorySqlite: true });
+    const knex = getKnex();
+
+    await knex.schema.dropTableIfExists("posts");
+    await knex.schema.dropTableIfExists("profiles");
+    await knex.schema.dropTableIfExists("users");
+
+    await knex.schema.createTable("users", (table) => {
+      table.increments("id").primary();
+      table.string("name", 255).notNullable();
+      table.timestamp("created_at").defaultTo(knex.fn.now());
+      table.timestamp("updated_at").defaultTo(knex.fn.now());
+      table.timestamp("deleted_at").nullable();
+    });
+
+    await knex.schema.createTable("posts", (table) => {
+      table.increments("id").primary();
+      table.integer("user_id").unsigned().notNullable();
+      table.string("title", 255).notNullable();
+      table.timestamp("created_at").defaultTo(knex.fn.now());
+      table.timestamp("updated_at").defaultTo(knex.fn.now());
+    });
+
+    await knex.schema.createTable("profiles", (table) => {
+      table.increments("id").primary();
+      table.string("secret", 255).notNullable();
+      table.timestamp("created_at").defaultTo(knex.fn.now());
+      table.timestamp("updated_at").defaultTo(knex.fn.now());
+    });
+  });
+
+  afterAll(async () => {
+    await closeDb();
+  });
+
+  it("creates, finds, and lists rows", async () => {
+    const created = await User.create({ name: "alice" });
+    expect(created.name).toBe("alice");
+
+    const found = await User.find(created.id as number);
+    expect(found?.name).toBe("alice");
+
+    const all = await User.all();
+    expect(all.length).toBeGreaterThan(0);
+  });
+
+  it("throws findOrFail when missing", async () => {
+    await expect(User.findOrFail(9_007_199_254_740_991)).rejects.toThrow("Not found");
+  });
+
+  it("supports where filters", async () => {
+    const rows = await User.where("name", "alice").select();
+    expect(rows.length).toBeGreaterThan(0);
+  });
+
+  it("updates rows via static update and instance save", async () => {
+    const created = await User.create({ name: "bob" });
+    await User.update(created.id as number, { name: "bobby" });
+    const updated = await User.find(created.id as number);
+    expect(updated?.name).toBe("bobby");
+
+    const instance = Object.assign(new User(), updated);
+    await instance.save();
+    const reloaded = await User.find(created.id as number);
+    expect(reloaded?.name).toBe("bobby");
+  });
+
+  it("destroys rows", async () => {
+    const created = await User.create({ name: "tmp" });
+    await User.destroy(created.id as number);
+    expect(await User.find(created.id as number)).toBeNull();
+  });
+
+  it("paginates with the shared envelope shape", async () => {
+    const page = await User.paginate(1, 5);
+    expect(page.data.length).toBeGreaterThan(0);
+    expect(page.total).toBeGreaterThan(0);
+    expect(page.page).toBe(1);
+    expect(page.perPage).toBe(5);
+    expect(page.lastPage).toBeGreaterThan(0);
+  });
+
+  it("eager-loads hasMany relations", async () => {
+    const unique = `owner-${Math.random().toString(16).slice(2)}`;
+    const owner = await User.create({ name: unique });
+    await Post.create({ user_id: owner.id, title: "hello" });
+
+    const rows = await User.with("posts").where("name", unique).get();
+    expect(rows[0]?.posts).toBeDefined();
+    expect(Array.isArray(rows[0]?.posts)).toBe(true);
+    expect((rows[0]?.posts as { title: string }[])[0]?.title).toBe("hello");
+  });
+
+  it("applies soft deletes", async () => {
+    const created = await UserSoft.create({ name: "ghost" });
+    const instance = Object.assign(new UserSoft(), created);
+    await instance.delete();
+
+    expect(await UserSoft.find(created.id as number)).toBeNull();
+    const trashed = await UserSoft.withTrashed().where("id", created.id as number).first();
+    expect(trashed).not.toBeNull();
+  });
+
+  it("strips hidden columns from toJSON", async () => {
+    const created = await Profile.create({ secret: "hide-me" });
+    const instance = Object.assign(new Profile(), created);
+    const json = instance.toJSON();
+    expect(json.secret).toBeUndefined();
+    expect(json.id).toBeDefined();
+  });
+});
+

package/src/XModel.ts

@@ -0,0 +1,301 @@
+import type { Knex } from "knex";
+import type { PaginatedResult } from "@xacos/shared";
+import { getColumnOptions, getRelations, type ModelConstructor, type RelationMeta } from "./decorators";
+import { getKnex } from "./connection/db";
+
+async function resolveInsertedId(
+  knex: Knex,
+  table: string,
+  insertResult: unknown,
+  payload: Record<string, unknown>,
+): Promise<number | string> {
+  if (Array.isArray(insertResult)) {
+    const first = insertResult[0];
+    if (typeof first === "number" || typeof first === "string") {
+      return first;
+    }
+    if (first && typeof first === "object" && "id" in first) {
+      return (first as { id: number | string }).id;
+    }
+  }
+  if (typeof insertResult === "number" || typeof insertResult === "string") {
+    return insertResult;
+  }
+  if (payload.id != null) {
+    return payload.id as number | string;
+  }
+
+  const row = await knex(table).select<{ id: number | string }>("id").orderBy("id", "desc").first();
+  if (!row) {
+    throw new Error("[XAOCS ORM] Unable to resolve inserted primary key");
+  }
+  return row.id;
+}
+
+async function attachHasMany(
+  rows: Record<string, unknown>[],
+  propertyKey: string,
+  Related: ModelConstructor,
+  foreignKey: string,
+): Promise<void> {
+  if (rows.length === 0) return;
+
+  const ids = rows
+    .map((row) => row.id)
+    .filter((id): id is number | string => id !== undefined && id !== null);
+
+  if (ids.length === 0) return;
+
+  const relatedModel = Related as unknown as { query(): Knex.QueryBuilder };
+  const relatedRows = (await relatedModel.query().whereIn(foreignKey, ids).select()) as Record<string, unknown>[];
+  const grouped = new Map<number | string, Record<string, unknown>[]>();
+
+  for (const rel of relatedRows) {
+    const fk = rel[foreignKey] as number | string;
+    const bucket = grouped.get(fk) ?? [];
+    bucket.push(rel);
+    grouped.set(fk, bucket);
+  }
+
+  for (const row of rows) {
+    const id = row.id as number | string;
+    row[propertyKey] = grouped.get(id) ?? [];
+  }
+}
+
+export class RelationScope {
+  private base: Knex.QueryBuilder;
+
+  constructor(
+    private readonly Model: typeof XModel,
+    private readonly relations: readonly string[],
+    base: Knex.QueryBuilder,
+  ) {
+    this.base = base;
+  }
+
+  where(column: string, value: unknown): this {
+    this.base = this.base.clone().where(column, value as Knex.Value);
+    return this;
+  }
+
+  whereIn(column: string, values: readonly unknown[]): this {
+    this.base = this.base.clone().whereIn(column, values as readonly Knex.Value[]);
+    return this;
+  }
+
+  orderBy(column: string, direction: "asc" | "desc" = "asc"): this {
+    this.base = this.base.clone().orderBy(column, direction);
+    return this;
+  }
+
+  limit(value: number): this {
+    this.base = this.base.clone().limit(value);
+    return this;
+  }
+
+  offset(value: number): this {
+    this.base = this.base.clone().offset(value);
+    return this;
+  }
+
+  async first(): Promise<Record<string, unknown> | null> {
+    const row = (await this.base.clone().first()) as Record<string, unknown> | undefined;
+    if (!row) return null;
+    const rows = [row];
+    await this.Model.hydrateRelations(rows, this.relations);
+    return rows[0] ?? null;
+  }
+
+  async get(): Promise<Record<string, unknown>[]> {
+    const rows = (await this.base.clone().select()) as Record<string, unknown>[];
+    await this.Model.hydrateRelations(rows, this.relations);
+    return rows;
+  }
+}
+
+export abstract class XModel {
+  static table = "";
+  static softDeletes = false;
+
+  static query(): Knex.QueryBuilder {
+    const knex = getKnex();
+    const Model = this as typeof XModel;
+    if (!Model.table) {
+      throw new Error("[XAOCS ORM] static table must be set on the model");
+    }
+
+    let builder = knex(Model.table);
+    if (Model.softDeletes) {
+      builder = builder.whereNull("deleted_at");
+    }
+    return builder;
+  }
+
+  static withTrashed(): Knex.QueryBuilder {
+    const Model = this as typeof XModel;
+    if (!Model.table) {
+      throw new Error("[XAOCS ORM] static table must be set on the model");
+    }
+    return getKnex()(Model.table);
+  }
+
+  /**
+   * @security WARNING: Never pass user input directly to raw().
+   * Always use parameterized bindings: db.raw('WHERE id = ?', [userInput])
+   */
+  static raw(sql: string, bindings?: readonly Knex.RawBinding[]): Knex.Raw {
+    return getKnex().raw(sql, bindings ?? []);
+  }
+
+  static with(...relations: string[]): RelationScope {
+    const Model = this as typeof XModel;
+    return new RelationScope(Model, relations, Model.query());
+  }
+
+  static async hydrateRelations(rows: Record<string, unknown>[], relations: readonly string[]): Promise<void> {
+    const ctor = this as typeof XModel;
+    const metas = getRelations(ctor);
+
+    for (const relationName of relations) {
+      const meta = metas.find((m: RelationMeta) => m.propertyKey === relationName);
+      if (!meta) continue;
+
+      if (meta.kind === "hasMany") {
+        const Related = meta.related();
+        await attachHasMany(rows, meta.propertyKey, Related, meta.foreignKey);
+      }
+    }
+  }
+
+  static async find(id: number | string): Promise<Record<string, unknown> | null> {
+    const row = await (this as typeof XModel).query().where("id", id).first();
+    return row ? (row as Record<string, unknown>) : null;
+  }
+
+  static async findOrFail(id: number | string): Promise<Record<string, unknown>> {
+    const row = await (this as typeof XModel).find(id);
+    if (!row) {
+      const err = new Error("Not found");
+      (err as Error & { statusCode: number }).statusCode = 404;
+      throw err;
+    }
+    return row;
+  }
+
+  static async all(): Promise<Record<string, unknown>[]> {
+    const rows = await (this as typeof XModel).query().select();
+    return rows as Record<string, unknown>[];
+  }
+
+  static where(column: string, value: unknown): Knex.QueryBuilder;
+  static where(criteria: Record<string, unknown>): Knex.QueryBuilder;
+  static where(column: string | Record<string, unknown>, value?: unknown): Knex.QueryBuilder {
+    const Model = this as typeof XModel;
+    if (typeof column === "string") {
+      return Model.query().where(column, value as Knex.Value);
+    }
+    return Model.query().where(column);
+  }
+
+  static async create(data: Record<string, unknown>): Promise<Record<string, unknown>> {
+    const Model = this as typeof XModel;
+    const knex = getKnex();
+    const now = new Date();
+    const payload: Record<string, unknown> = {
+      ...data,
+      created_at: data.created_at ?? now,
+      updated_at: data.updated_at ?? now,
+    };
+
+    const insertResult = await knex(Model.table).insert(payload);
+    const id = await resolveInsertedId(knex, Model.table, insertResult, payload);
+    const created = await Model.find(id);
+    if (!created) {
+      throw new Error("[XAOCS ORM] Row missing after insert");
+    }
+    return created;
+  }
+
+  static async update(id: number | string, data: Record<string, unknown>): Promise<void> {
+    const Model = this as typeof XModel;
+    await Model.withTrashed().where("id", id).update({ ...data, updated_at: new Date() });
+  }
+
+  static async destroy(id: number | string): Promise<void> {
+    const Model = this as typeof XModel;
+    const existing = await Model.withTrashed().where("id", id).first();
+    if (!existing) return;
+
+    if (Model.softDeletes) {
+      await Model.withTrashed().where("id", id).update({ deleted_at: new Date(), updated_at: new Date() });
+      return;
+    }
+
+    await Model.withTrashed().where("id", id).del();
+  }
+
+  static async paginate(page = 1, perPage = 15): Promise<PaginatedResult<Record<string, unknown>>> {
+    const Model = this as typeof XModel;
+    const offset = (page - 1) * perPage;
+
+    const countRows = (await Model.query()
+      .clone()
+      .clearOrder()
+      .count<{ count: string | number }>("* as count")) as unknown as Array<{ count: string | number }>;
+    const total = Number(countRows[0]?.count ?? 0);
+
+    const data = (await Model.query().clone().offset(offset).limit(perPage).select()) as Record<string, unknown>[];
+    const lastPage = Math.max(1, Math.ceil(total / perPage));
+
+    return {
+      data,
+      total,
+      page,
+      perPage,
+      lastPage,
+    };
+  }
+
+  toJSON(): Record<string, unknown> {
+    const ctor = this.constructor as typeof XModel;
+    const source = this as Record<string, unknown>;
+    const result: Record<string, unknown> = { ...source };
+
+    for (const key of Object.keys(result)) {
+      const meta = getColumnOptions(ctor, key);
+      if (meta?.hidden) {
+        delete result[key];
+      }
+    }
+
+    return result;
+  }
+
+  async save(): Promise<void> {
+    const Model = this.constructor as typeof XModel;
+    const row = this as Record<string, unknown>;
+    const id = row.id;
+    if (id === undefined || id === null) {
+      throw new Error("[XAOCS ORM] save() requires an id — use Model.create() for inserts");
+    }
+
+    const { id: _ignored, ...rest } = row;
+    await getKnex()(Model.table).where("id", id).update({ ...rest, updated_at: new Date() });
+  }
+
+  async delete(): Promise<void> {
+    const Model = this.constructor as typeof XModel;
+    const id = (this as Record<string, unknown>).id as number | string;
+
+    if (Model.softDeletes) {
+      await Model.withTrashed().where("id", id).update({ deleted_at: new Date(), updated_at: new Date() });
+      return;
+    }
+
+    await Model.withTrashed().where("id", id).del();
+  }
+}
+
+export default XModel;
+

package/src/XMongoModel.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "bun:test";
+import { Schema } from "mongoose";
+import { XMongoModel } from "./XMongoModel";
+
+class MissingModelName extends XMongoModel {
+  static getSchema(): Schema {
+    return new Schema({ label: { type: String } });
+  }
+}
+
+describe("XMongoModel", () => {
+  it("requires modelName before accessing model", () => {
+    expect(() => MissingModelName.model).toThrow("modelName");
+  });
+});
+