@xacos/orm 1.0.0

package/src/XMongoModel.ts

@@ -0,0 +1,119 @@
+import mongoose, {
+  type FilterQuery,
+  type Model,
+  type Schema,
+  type SortOrder,
+  type UpdateQuery,
+  Types,
+} from "mongoose";
+import type { PaginatedResult } from "@xacos/shared";
+
+type MongoDoc = Record<string, unknown>;
+
+/**
+ * Mongoose-backed persistence. With MongoDB you define a {@link Schema} on the subclass
+ * and use this API directly — **no Knex migrations** (`MigrationRunner` is SQL-only).
+ */
+export abstract class XMongoModel {
+  /** Registered name for `mongoose.model()` (must be unique per connection). */
+  static modelName = "";
+  /** Optional Mongo collection name (passed to the schema via `collection` option). */
+  static collection = "";
+
+  static getSchema(): Schema {
+    throw new Error("[XAOCS ORM] Override getSchema() and return a Mongoose Schema for this model.");
+  }
+
+  static get model(): Model<MongoDoc & mongoose.Document> {
+    const ctor = this as typeof XMongoModel;
+    if (!ctor.modelName) {
+      throw new Error("[XAOCS ORM] static modelName is required on XMongoModel subclasses.");
+    }
+
+    const existing = mongoose.models[ctor.modelName] as Model<MongoDoc & mongoose.Document> | undefined;
+    if (existing) {
+      return existing;
+    }
+
+    const schema = ctor.getSchema();
+    if (ctor.collection) {
+      schema.set("collection", ctor.collection);
+    }
+
+    return mongoose.model<MongoDoc & mongoose.Document>(ctor.modelName, schema);
+  }
+
+  static async findById(id: string | Types.ObjectId): Promise<MongoDoc | null> {
+    const doc = await this.model.findById(id).lean<MongoDoc>().exec();
+    return doc ?? null;
+  }
+
+  static async findByIdOrFail(id: string | Types.ObjectId): Promise<MongoDoc> {
+    const row = await this.findById(id);
+    if (!row) {
+      const err = new Error("Not found");
+      (err as Error & { statusCode: number }).statusCode = 404;
+      throw err;
+    }
+    return row;
+  }
+
+  static async findOne(filter: FilterQuery<MongoDoc>): Promise<MongoDoc | null> {
+    const doc = await this.model.findOne(filter).lean<MongoDoc>().exec();
+    return doc ?? null;
+  }
+
+  static async find(filter: FilterQuery<MongoDoc> = {}): Promise<MongoDoc[]> {
+    return (await this.model.find(filter).lean<MongoDoc[]>().exec()) as MongoDoc[];
+  }
+
+  static async create(data: MongoDoc): Promise<MongoDoc> {
+    const created = await this.model.create(data);
+    const plain = created.toObject() as MongoDoc;
+    const id = plain["_id"];
+    if (id !== undefined) {
+      plain["id"] = String(id);
+    }
+    return plain;
+  }
+
+  static async updateById(
+    id: string | Types.ObjectId,
+    update: UpdateQuery<MongoDoc>,
+  ): Promise<MongoDoc | null> {
+    const doc = await this.model
+      .findByIdAndUpdate(id, update, { new: true, runValidators: true })
+      .lean<MongoDoc>()
+      .exec();
+    return doc ?? null;
+  }
+
+  static async deleteById(id: string | Types.ObjectId): Promise<boolean> {
+    const res = await this.model.findByIdAndDelete(id).exec();
+    return res !== null;
+  }
+
+  static async paginate(
+    filter: FilterQuery<MongoDoc> = {},
+    page = 1,
+    perPage = 15,
+    sort: Record<string, SortOrder> = { _id: -1 },
+  ): Promise<PaginatedResult<MongoDoc>> {
+    const skip = (page - 1) * perPage;
+    const [total, data] = await Promise.all([
+      this.model.countDocuments(filter).exec(),
+      this.model.find(filter).sort(sort).skip(skip).limit(perPage).lean<MongoDoc[]>().exec(),
+    ]);
+    const lastPage = Math.max(1, Math.ceil(total / perPage));
+    return {
+      data: data as MongoDoc[],
+      total,
+      page,
+      perPage,
+      lastPage,
+    };
+  }
+}
+
+export default XMongoModel;
+

package/src/__tests__/sqlite.integration.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
+import { initDb, getKnex, closeDb } from '../connection/db';
+import { MigrationRunner } from '../migrations/MigrationRunner';
+import { XModel } from '../XModel';
+import { Column } from '../decorators';
+import { resolve } from 'path';
+import { unlinkSync, existsSync } from 'fs';
+
+const DB_PATH = './tmp-test.sqlite';
+
+process.env['DB_DRIVER'] = 'sqlite';
+process.env['DB_PATH'] = DB_PATH;
+
+class TestUser extends XModel {
+  static table = 'test_users';
+
+  @Column()
+  declare id: number;
+
+  @Column()
+  declare name: string;
+
+  @Column()
+  declare email: string;
+
+  @Column()
+  declare created_at: Date;
+
+  @Column()
+  declare updated_at: Date;
+}
+
+beforeAll(async () => {
+  initDb();
+  const knex = getKnex();
+
+  // Create the test table directly
+  await knex.schema.createTableIfNotExists('test_users', t => {
+    t.increments('id');
+    t.string('name').notNullable();
+    t.string('email').notNullable().unique();
+    t.timestamps(true, true);
+  });
+});
+
+afterAll(async () => {
+  await closeDb();
+  if (existsSync(DB_PATH)) unlinkSync(DB_PATH);
+});
+
+beforeEach(async () => {
+  await getKnex()('test_users').delete();
+});
+
+describe('SQLite Integration — XModel', () => {
+  it('creates a record', async () => {
+    const user = await TestUser.create({ name: 'Alice', email: 'alice@test.com' } as any);
+    expect((user as any).id).toBeGreaterThan(0);
+    expect((user as any).name).toBe('Alice');
+  });
+
+  it('finds a record by id', async () => {
+    const created = await TestUser.create({ name: 'Bob', email: 'bob@test.com' } as any);
+    const found = await TestUser.find((created as any).id) as any;
+    expect(found).not.toBeNull();
+    expect(found.name).toBe('Bob');
+  });
+
+  it('returns null for missing id', async () => {
+    const found = await TestUser.find(9999);
+    expect(found).toBeNull();
+  });
+
+  it('findOrFail throws for missing id', async () => {
+    await expect(TestUser.findOrFail(9999)).rejects.toThrow();
+  });
+
+  it('queries with where()', async () => {
+    await TestUser.create({ name: 'Carol', email: 'carol@test.com' } as any);
+    await TestUser.create({ name: 'Dave', email: 'dave@test.com' } as any);
+    const results = await TestUser.where('name', 'Carol').select() as any[];
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('Carol');
+  });
+
+  it('returns all records', async () => {
+    await TestUser.create({ name: 'Eve', email: 'eve@test.com' } as any);
+    await TestUser.create({ name: 'Frank', email: 'frank@test.com' } as any);
+    const all = await TestUser.all() as any[];
+    expect(all.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('updates a record', async () => {
+    const user = await TestUser.create({ name: 'Grace', email: 'grace@test.com' } as any) as any;
+    await TestUser.update(user.id, { name: 'Grace Updated' });
+    const updated = await TestUser.find(user.id) as any;
+    expect(updated.name).toBe('Grace Updated');
+  });
+
+  it('deletes a record', async () => {
+    const user = await TestUser.create({ name: 'Heidi', email: 'heidi@test.com' } as any) as any;
+    await TestUser.destroy(user.id);
+    const found = await TestUser.find(user.id);
+    expect(found).toBeNull();
+  });
+
+  it('paginates results', async () => {
+    for (let i = 0; i < 20; i++) {
+      await TestUser.create({ name: `User${i}`, email: `user${i}@test.com` } as any);
+    }
+    const page = await TestUser.paginate(1, 5) as any;
+    expect(page.data).toHaveLength(5);
+    expect(page.total).toBe(20);
+    expect(page.lastPage).toBe(4);
+  });
+});

package/src/connection/db.ts

@@ -0,0 +1,127 @@
+import knex, { type Knex } from "knex";
+import mongoose from "mongoose";
+import { buildKnexConfig } from "./drivers";
+import { buildMongoUri } from "./mongoUri";
+
+let knexInstance: Knex | null = null;
+
+export type InitDbOptions =
+  | { readonly __memorySqlite: true }
+  | Knex.Config;
+
+export function isKnexInitialized(): boolean {
+  return knexInstance !== null;
+}
+
+export function isMongooseConnected(): boolean {
+  return mongoose.connection.readyState === 1;
+}
+
+export function initDb(config?: InitDbOptions): Knex {
+  if (mongoose.connection.readyState === 1) {
+    throw new Error("[XAOCS ORM] Cannot initialize Knex while Mongoose is connected. Call closeDb() first.");
+  }
+
+  const driver = process.env["DB_DRIVER"] ?? "sqlite";
+  if (!config && driver === "mongodb") {
+    throw new Error(
+      "[XAOCS ORM] DB_DRIVER is mongodb: use await initMongo() for Mongoose. Knex SQL migrations are not used with MongoDB.",
+    );
+  }
+
+  if (knexInstance) {
+    return knexInstance;
+  }
+
+  let knexConfig: Knex.Config;
+  if (config && typeof config === "object" && "__memorySqlite" in config && config.__memorySqlite) {
+    knexConfig = {
+      client: "sqlite3",
+      connection: {
+        filename: ":memory:",
+      },
+      useNullAsDefault: true,
+      pool: {
+        min: 1,
+        max: 1,
+      },
+    };
+  } else if (config && typeof config === "object" && "client" in config) {
+    knexConfig = config;
+  } else {
+    knexConfig = buildKnexConfig();
+  }
+
+  knexInstance = knex(knexConfig);
+  return knexInstance;
+}
+
+export function getKnex(): Knex {
+  if (knexInstance) {
+    return knexInstance;
+  }
+  if (mongoose.connection.readyState === 1) {
+    throw new Error(
+      "[XAOCS ORM] Knex is not initialized; Mongoose is active. SQL helpers and MigrationRunner require Knex — with MongoDB define schemas on XMongoModel subclasses instead of migrations.",
+    );
+  }
+  throw new Error("[XAOCS ORM] DB not initialized. Call initDb() or await initMongo() first.");
+}
+
+export type InitMongoOptions = Readonly<{
+  uri?: string;
+  /** Passed to `mongoose.connect` (pool size, timeouts, TLS, etc.). */
+  connectOptions?: mongoose.ConnectOptions;
+}>;
+
+/**
+ * Connect Mongoose (MongoDB). Does not use Knex; do not run SQL migrations — define schemas on {@link XMongoModel} instead.
+ */
+export async function initMongo(options?: InitMongoOptions): Promise<typeof mongoose> {
+  if (knexInstance) {
+    throw new Error("[XAOCS ORM] Cannot connect Mongoose while Knex is active. Call closeDb() first.");
+  }
+
+  if (mongoose.connection.readyState === 1) {
+    return mongoose;
+  }
+
+  const uri = options?.uri ?? buildMongoUri();
+  const defaults: mongoose.ConnectOptions = {
+    serverSelectionTimeoutMS: 10_000,
+    maxPoolSize: 10,
+  };
+  await mongoose.connect(uri, { ...defaults, ...options?.connectOptions });
+  return mongoose;
+}
+
+/**
+ * Auto-select Knex vs Mongoose from `DB_DRIVER` (mongodb → Mongoose, otherwise → Knex).
+ */
+export async function initOrmFromEnv(): Promise<"knex" | "mongoose"> {
+  const driver = process.env["DB_DRIVER"] ?? "sqlite";
+  if (driver === "mongodb") {
+    await initMongo();
+    return "mongoose";
+  }
+  initDb();
+  return "knex";
+}
+
+export function getMongoose(): typeof mongoose {
+  if (mongoose.connection.readyState !== 1) {
+    throw new Error("[XAOCS ORM] Mongoose is not connected. Call await initMongo() first.");
+  }
+  return mongoose;
+}
+
+export async function closeDb(): Promise<void> {
+  if (knexInstance) {
+    await knexInstance.destroy();
+    knexInstance = null;
+  }
+  if (mongoose.connection.readyState !== 0) {
+    await mongoose.disconnect();
+  }
+}
+

package/src/connection/drivers.ts

@@ -0,0 +1,65 @@
+import type { Knex } from "knex";
+
+function mysqlConnection(): Knex.MySql2ConnectionConfig {
+  const database = process.env["DB_DATABASE"];
+  const user = process.env["DB_USERNAME"];
+  const password = process.env["DB_PASSWORD"];
+  if (!database || !user) {
+    throw new Error("[XAOCS ORM] DB_DATABASE and DB_USERNAME are required for mysql driver");
+  }
+  return {
+    host: process.env["DB_HOST"] ?? "localhost",
+    port: Number(process.env["DB_PORT"] ?? 3306),
+    database,
+    user,
+    password: password ?? "",
+  };
+}
+
+function postgresConnection(): Knex.PgConnectionConfig {
+  const database = process.env["DB_DATABASE"];
+  const user = process.env["DB_USERNAME"];
+  const password = process.env["DB_PASSWORD"];
+  if (!database || !user) {
+    throw new Error("[XAOCS ORM] DB_DATABASE and DB_USERNAME are required for postgres driver");
+  }
+  return {
+    host: process.env["DB_HOST"] ?? "localhost",
+    port: Number(process.env["DB_PORT"] ?? 5432),
+    database,
+    user,
+    password: password ?? "",
+  };
+}
+
+export function buildKnexConfig(): Knex.Config {
+  const driver = process.env["DB_DRIVER"] ?? "sqlite";
+
+  switch (driver) {
+    case "mysql":
+      return {
+        client: "mysql2",
+        connection: mysqlConnection(),
+      };
+    case "postgres":
+      return {
+        client: "pg",
+        connection: postgresConnection(),
+      };
+    case "sqlite":
+      return {
+        client: "sqlite3",
+        connection: {
+          filename: process.env["DB_PATH"] ?? "./database/db.sqlite",
+        },
+        useNullAsDefault: true,
+      };
+    case "mongodb":
+      throw new Error(
+        "[XAOCS ORM] MongoDB does not use Knex. Set DB_DRIVER=mongodb and call await initMongo() (or initOrmFromEnv()). Define Mongoose schemas on XMongoModel subclasses — SQL migrations do not apply.",
+      );
+    default:
+      throw new Error(`[XAOCS ORM] Unsupported driver: ${driver}`);
+  }
+}
+

package/src/connection/mongoUri.ts

@@ -0,0 +1,25 @@
+/**
+ * Builds a Mongo connection URI from env.
+ * Prefer `MONGODB_URI` or `DATABASE_URL` when set.
+ */
+export function buildMongoUri(): string {
+  const direct = process.env["MONGODB_URI"] ?? process.env["DATABASE_URL"];
+  if (direct) {
+    return direct;
+  }
+
+  const user = process.env["DB_USERNAME"] ?? "";
+  const password = process.env["DB_PASSWORD"] ?? "";
+  const host = process.env["DB_HOST"] ?? "localhost";
+  const port = process.env["DB_PORT"] ?? "27017";
+  const database = process.env["DB_DATABASE"] ?? "xacos";
+
+  if (user) {
+    const u = encodeURIComponent(user);
+    const p = encodeURIComponent(password);
+    return `mongodb://${u}:${p}@${host}:${port}/${database}`;
+  }
+
+  return `mongodb://${host}:${port}/${database}`;
+}
+

package/src/decorators.ts

@@ -0,0 +1,200 @@
+export type ModelConstructor = { new (...args: never[]): unknown; readonly table: string };
+
+export type RelationMeta =
+  | Readonly<{
+      kind: "hasMany";
+      related: () => ModelConstructor;
+      foreignKey: string;
+      propertyKey: string;
+    }>
+  | Readonly<{
+      kind: "belongsTo";
+      related: () => ModelConstructor;
+      foreignKey: string;
+      propertyKey: string;
+    }>
+  | Readonly<{
+      kind: "hasOne";
+      related: () => ModelConstructor;
+      foreignKey: string;
+      propertyKey: string;
+    }>
+  | Readonly<{
+      kind: "belongsToMany";
+      related: () => ModelConstructor;
+      pivotTable: string;
+      propertyKey: string;
+    }>;
+
+export type ColumnOptions = Readonly<{
+  hidden?: boolean;
+  default?: unknown;
+}>;
+
+type WithRelations = { __xacosRelations?: RelationMeta[] };
+type WithColumns = { __xacosColumns?: Map<string, ColumnOptions> };
+
+type StandardDecoratorContext = {
+  kind: string;
+  name: string | symbol;
+  addInitializer?: (initializer: () => void) => void;
+};
+
+function constructorFromTarget(target: object | undefined): object {
+  if (!target || typeof target !== "object") {
+    throw new Error("[XAOCS ORM] Decorators must be applied to class members with a valid prototype target");
+  }
+  const ctor = (target as { constructor?: object }).constructor;
+  if (!ctor) {
+    throw new Error("[XAOCS ORM] Decorators require a constructor on the decorated target");
+  }
+  return ctor;
+}
+
+function isStandardDecoratorContext(value: unknown): value is StandardDecoratorContext {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "kind" in value &&
+    "name" in value
+  );
+}
+
+function pushRelation(constructor: object, meta: RelationMeta): void {
+  const ctor = constructor as WithRelations;
+  if (!ctor.__xacosRelations) ctor.__xacosRelations = [];
+  ctor.__xacosRelations.push(meta);
+}
+
+/** Register relation metadata when runtime decorators receive no prototype (e.g. some Bun/TS field transforms). */
+export function registerRelation(constructor: object, meta: RelationMeta): void {
+  pushRelation(constructor, meta);
+}
+
+/** Register column metadata without a decorator. */
+export function registerColumnMeta(constructor: object, propertyKey: string, options: ColumnOptions): void {
+  ensureColumnMap(constructor).set(propertyKey, options);
+}
+
+function ensureColumnMap(constructor: object): Map<string, ColumnOptions> {
+  const ctor = constructor as WithColumns;
+  if (!ctor.__xacosColumns) ctor.__xacosColumns = new Map();
+  return ctor.__xacosColumns;
+}
+
+export function HasMany(related: () => ModelConstructor, foreignKey: string) {
+  return (targetOrInitialValue: object | undefined, propertyKeyOrContext: string | symbol | StandardDecoratorContext): void => {
+    if (isStandardDecoratorContext(propertyKeyOrContext)) {
+      const context = propertyKeyOrContext;
+      if (context.kind !== "field" && context.kind !== "accessor") return;
+      const key = String(context.name);
+      context.addInitializer?.(function (this: object) {
+        const ctor = constructorFromTarget(this);
+        pushRelation(ctor, { kind: "hasMany", related, foreignKey, propertyKey: key });
+      });
+      return;
+    }
+    const key = String(propertyKeyOrContext);
+    const ctor = constructorFromTarget(targetOrInitialValue);
+    pushRelation(ctor, { kind: "hasMany", related, foreignKey, propertyKey: key });
+  };
+}
+
+export function BelongsTo(related: () => ModelConstructor, foreignKey: string) {
+  return (targetOrInitialValue: object | undefined, propertyKeyOrContext: string | symbol | StandardDecoratorContext): void => {
+    if (isStandardDecoratorContext(propertyKeyOrContext)) {
+      const context = propertyKeyOrContext;
+      if (context.kind !== "field" && context.kind !== "accessor") return;
+      const key = String(context.name);
+      context.addInitializer?.(function (this: object) {
+        const ctor = constructorFromTarget(this);
+        pushRelation(ctor, { kind: "belongsTo", related, foreignKey, propertyKey: key });
+      });
+      return;
+    }
+    const key = String(propertyKeyOrContext);
+    const ctor = constructorFromTarget(targetOrInitialValue);
+    pushRelation(ctor, { kind: "belongsTo", related, foreignKey, propertyKey: key });
+  };
+}
+
+export function HasOne(related: () => ModelConstructor, foreignKey: string) {
+  return (targetOrInitialValue: object | undefined, propertyKeyOrContext: string | symbol | StandardDecoratorContext): void => {
+    if (isStandardDecoratorContext(propertyKeyOrContext)) {
+      const context = propertyKeyOrContext;
+      if (context.kind !== "field" && context.kind !== "accessor") return;
+      const key = String(context.name);
+      context.addInitializer?.(function (this: object) {
+        const ctor = constructorFromTarget(this);
+        pushRelation(ctor, { kind: "hasOne", related, foreignKey, propertyKey: key });
+      });
+      return;
+    }
+    const key = String(propertyKeyOrContext);
+    const ctor = constructorFromTarget(targetOrInitialValue);
+    pushRelation(ctor, { kind: "hasOne", related, foreignKey, propertyKey: key });
+  };
+}
+
+export function BelongsToMany(related: () => ModelConstructor, pivotTable: string) {
+  return (targetOrInitialValue: object | undefined, propertyKeyOrContext: string | symbol | StandardDecoratorContext): void => {
+    if (isStandardDecoratorContext(propertyKeyOrContext)) {
+      const context = propertyKeyOrContext;
+      if (context.kind !== "field" && context.kind !== "accessor") return;
+      const key = String(context.name);
+      context.addInitializer?.(function (this: object) {
+        const ctor = constructorFromTarget(this);
+        pushRelation(ctor, { kind: "belongsToMany", related, pivotTable, propertyKey: key });
+      });
+      return;
+    }
+    const key = String(propertyKeyOrContext);
+    const ctor = constructorFromTarget(targetOrInitialValue);
+    pushRelation(ctor, { kind: "belongsToMany", related, pivotTable, propertyKey: key });
+  };
+}
+
+export function Column(options: ColumnOptions = {}) {
+  return (targetOrInitialValue: object | undefined, propertyKeyOrContext: string | symbol | StandardDecoratorContext): void => {
+    if (isStandardDecoratorContext(propertyKeyOrContext)) {
+      const context = propertyKeyOrContext;
+      if (context.kind !== "field" && context.kind !== "accessor") {
+        return;
+      }
+
+      const key = String(context.name);
+      context.addInitializer?.(function (this: object) {
+        const ctor = constructorFromTarget(this);
+        ensureColumnMap(ctor).set(key, options);
+      });
+      return;
+    }
+
+    const key = String(propertyKeyOrContext);
+    const ctor = constructorFromTarget(targetOrInitialValue);
+    ensureColumnMap(ctor).set(key, options);
+  };
+}
+
+export function getColumnOptions(constructor: object, propertyKey: string): ColumnOptions | undefined {
+  let current: object | null = constructor;
+  while (current) {
+    const map = (current as WithColumns).__xacosColumns;
+    const hit = map?.get(propertyKey);
+    if (hit) return hit;
+    current = Object.getPrototypeOf(current);
+  }
+  return undefined;
+}
+
+export function getRelations(ctor: object): RelationMeta[] {
+  const collected: RelationMeta[] = [];
+  let current: object | null = ctor;
+  while (current) {
+    const own = (current as WithRelations).__xacosRelations ?? [];
+    collected.push(...own);
+    current = Object.getPrototypeOf(current);
+  }
+  return collected;
+}
+

package/src/factories/Factory.test.ts

@@ -0,0 +1,18 @@
+import { describe, it, expect } from 'bun:test';
+import { Factory } from './Factory';
+
+describe('Factory', () => {
+  it('builds N plain objects', async () => {
+    const items = await Factory.times(3).build(() => ({
+      name: Factory.faker.person.fullName(),
+    }));
+    expect(items).toHaveLength(3);
+    expect(typeof items[0]?.name).toBe('string');
+  });
+
+  it('times(0) returns empty array', async () => {
+    const items = await Factory.times(0).build(() => ({ x: 1 }));
+    expect(items).toHaveLength(0);
+  });
+});
+