@xacos/orm 1.0.0

package/src/factories/Factory.ts

@@ -0,0 +1,61 @@
+import { faker } from '@faker-js/faker';
+import type { XModel } from '../XModel';
+
+type DefinitionFn<T> = () => Promise<Partial<T>> | Partial<T>;
+
+class FactoryBuilder {
+  constructor(private count: number) {}
+
+  /**
+   * Create `count` instances of a model using the provided definition function.
+   *
+   * @example
+   * await Factory.times(10).create(User, () => ({
+   *   name: Factory.faker.person.fullName(),
+   *   email: Factory.faker.internet.email(),
+   * }));
+   */
+  async create<T extends XModel>(
+    ModelClass: typeof XModel & { create(data: Partial<T>): Promise<T> },
+    definition: DefinitionFn<T>
+  ): Promise<T[]> {
+    const results: T[] = [];
+    for (let i = 0; i < this.count; i++) {
+      const data = await definition();
+      const instance = await ModelClass.create(data as Partial<T>);
+      results.push(instance as T);
+    }
+    return results;
+  }
+
+  /**
+   * Build plain objects without persisting to DB.
+   * Useful for unit tests that don't need a DB.
+   */
+  async build<T>(definition: DefinitionFn<T>): Promise<T[]> {
+    const results: T[] = [];
+    for (let i = 0; i < this.count; i++) {
+      results.push((await definition()) as T);
+    }
+    return results;
+  }
+}
+
+export class Factory {
+  /** Access Faker directly: Factory.faker.person.fullName() */
+  static faker = faker;
+
+  static times(count: number): FactoryBuilder {
+    return new FactoryBuilder(count);
+  }
+
+  /** Shorthand for Factory.times(1).create(...) */
+  static async create<T extends XModel>(
+    ModelClass: typeof XModel & { create(data: Partial<T>): Promise<T> },
+    definition: DefinitionFn<T>
+  ): Promise<T> {
+    const [result] = await Factory.times(1).create(ModelClass, definition);
+    return result!;
+  }
+}
+

package/src/index.ts

@@ -0,0 +1,18 @@
+export { initDb, closeDb, getKnex, initMongo, initOrmFromEnv, getMongoose, isKnexInitialized, isMongooseConnected, type InitDbOptions, type InitMongoOptions } from "./connection/db";
+export { buildKnexConfig } from "./connection/drivers";
+export { buildMongoUri } from "./connection/mongoUri";
+export { XModel, RelationScope } from "./XModel";
+export { default } from "./XModel";
+export { XMongoModel } from "./XMongoModel";
+export * from "./decorators";
+export { Migration } from "./migrations/Migration";
+export { Schema } from "./migrations/Schema";
+export { MigrationRunner } from "./migrations/MigrationRunner";
+export { augmentTable, type XCreateTableBuilder } from "./migrations/columnHelpers";
+export { Seeder } from "./seeders/Seeder";
+export { SeederRunner } from "./seeders/SeederRunner";
+export { Factory } from "./factories/Factory";
+export { paginate } from "./utils/paginate";
+
+
+

package/src/migrations/Migration.ts

@@ -0,0 +1,8 @@
+import type { Schema } from "./Schema";
+
+export abstract class Migration {
+  abstract up(schema: Schema): Promise<void>;
+
+  abstract down(schema: Schema): Promise<void>;
+}
+

package/src/migrations/MigrationRunner.test.ts

@@ -0,0 +1,33 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { closeDb, getKnex, initDb, MigrationRunner } from "../index";
+
+describe("MigrationRunner", () => {
+  const fixturesDir = join(fileURLToPath(new URL(".", import.meta.url)), "..", "..", "test-fixtures", "migrations");
+
+  beforeAll(() => {
+    initDb({ __memorySqlite: true });
+  });
+
+  afterAll(async () => {
+    await closeDb();
+  });
+
+  it("runs pending migrations, rolls back the last batch, and reapplies on fresh", async () => {
+    const runner = new MigrationRunner();
+    const knex = getKnex();
+
+    await runner.run(fixturesDir);
+    expect(await knex.schema.hasTable("migration_test")).toBe(true);
+    expect((await runner.getPending(fixturesDir)).length).toBe(0);
+
+    await runner.rollback(fixturesDir);
+    expect(await knex.schema.hasTable("migration_test")).toBe(false);
+
+    await runner.fresh(fixturesDir);
+    expect(await knex.schema.hasTable("migration_test")).toBe(true);
+    expect(await knex.schema.hasTable("xacos_migrations")).toBe(true);
+  });
+});
+

package/src/migrations/MigrationRunner.ts

@@ -0,0 +1,171 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { Knex } from "knex";
+import { getKnex } from "../connection/db";
+import type { Migration } from "./Migration";
+import { Schema } from "./Schema";
+
+async function listUserTables(knex: Knex): Promise<string[]> {
+  const client = knex.client.config.client;
+
+  if (client === "better-sqlite3" || client === "sqlite3") {
+    const rows = (await knex
+      .select<{ name: string }>("name")
+      .from("sqlite_master")
+      .where("type", "table")
+      .whereNotIn("name", ["sqlite_sequence", "sqlite_stat1"])) as unknown as Array<{ name: string }>;
+
+    return rows.map((row) => row.name);
+  }
+
+  if (client === "mysql2" || client === "mysql") {
+    const dbName = (knex.client.config.connection as { database?: string }).database;
+    if (!dbName) return [];
+    const rows = (await knex
+      .select<{ TABLE_NAME: string }>("TABLE_NAME")
+      .from("information_schema.tables")
+      .where({
+        table_schema: dbName,
+        table_type: "BASE TABLE",
+      })) as unknown as Array<{ TABLE_NAME: string }>;
+    return rows.map((row) => row.TABLE_NAME);
+  }
+
+  if (client === "pg") {
+    const rows = (await knex
+      .select<{ tablename: string }>("tablename")
+      .from("pg_tables")
+      .where("schemaname", "public")) as unknown as Array<{ tablename: string }>;
+    return rows.map((row) => row.tablename);
+  }
+
+  throw new Error(`[XAOCS ORM] Unsupported SQL client for migrations: ${String(client)}`);
+}
+
+export class MigrationRunner {
+  private readonly schema = new Schema();
+
+  private async ensureMigrationsTable(): Promise<void> {
+    const knex = getKnex();
+    const exists = await knex.schema.hasTable("xacos_migrations");
+    if (exists) return;
+
+    await knex.schema.createTable("xacos_migrations", (table) => {
+      table.increments("id").primary();
+      table.string("name", 255).notNullable();
+      table.integer("batch").notNullable();
+      table.timestamp("ran_at").defaultTo(knex.fn.now());
+    });
+  }
+
+  async getPending(migrationsDir: string): Promise<string[]> {
+    await this.ensureMigrationsTable();
+    const knex = getKnex();
+    const ranRows = (await knex.select<{ name: string }>("name").from("xacos_migrations")) as unknown as Array<{
+      name: string;
+    }>;
+    const ran = new Set(ranRows.map((row) => row.name));
+
+    let files: string[];
+    try {
+      files = readdirSync(migrationsDir);
+    } catch {
+      return [];
+    }
+
+    return files
+      .filter((file) => file.endsWith(".ts") || file.endsWith(".js"))
+      .filter((file) => !ran.has(file))
+      .sort((a, b) => a.localeCompare(b));
+  }
+
+  async run(migrationsDir: string): Promise<void> {
+    await this.ensureMigrationsTable();
+    const knex = getKnex();
+    const pending = await this.getPending(migrationsDir);
+    if (pending.length === 0) return;
+
+    const lastBatchRow = await knex("xacos_migrations").max<{ b: number | string | null }>({ b: "batch" }).first();
+    const batch = Number(lastBatchRow?.b ?? 0) + 1;
+
+    for (const file of pending) {
+      const abs = join(migrationsDir, file);
+      const mod = (await import(pathToFileURL(abs).href)) as { default?: new () => Migration };
+      const MigrationClass = mod.default;
+      if (!MigrationClass) {
+        throw new Error(`[XAOCS ORM] Migration file must default-export a Migration class: ${file}`);
+      }
+
+      const migration = new MigrationClass();
+      await migration.up(this.schema);
+      await knex("xacos_migrations").insert({ name: file, batch, ran_at: knex.fn.now() });
+    }
+  }
+
+  async rollback(migrationsDir: string): Promise<void> {
+    await this.ensureMigrationsTable();
+    const knex = getKnex();
+    const lastBatchRow = await knex("xacos_migrations").max<{ b: number | string | null }>({ b: "batch" }).first();
+    const lastBatch = Number(lastBatchRow?.b ?? 0);
+    if (!lastBatch) return;
+
+    const rows = (await knex("xacos_migrations").where("batch", lastBatch).orderBy("id", "desc")) as Array<{
+      id: number | string;
+      name: string;
+    }>;
+    const schema = new Schema();
+
+    for (const row of rows) {
+      const abs = join(migrationsDir, row.name);
+      const mod = (await import(pathToFileURL(abs).href)) as { default?: new () => Migration };
+      const MigrationClass = mod.default;
+      if (!MigrationClass) {
+        throw new Error(`[XAOCS ORM] Migration file must default-export a Migration class: ${row.name}`);
+      }
+
+      const migration = new MigrationClass();
+      await migration.down(schema);
+      await knex("xacos_migrations").where("id", row.id as number | string).del();
+    }
+  }
+
+  async fresh(migrationsDir: string): Promise<void> {
+    const knex = getKnex();
+    const tables = await listUserTables(knex);
+
+    for (const name of tables) {
+      await knex.schema.dropTableIfExists(name);
+    }
+
+    await this.run(migrationsDir);
+  }
+
+  async status(migrationsDir: string): Promise<Array<{ name: string; ran: boolean; batch?: number | undefined }>> {
+    await this.ensureMigrationsTable();
+    const knex = getKnex();
+    const ranRows = (await knex.select<{ name: string; batch: number }>("name", "batch").from("xacos_migrations")) as unknown as Array<{
+      name: string;
+      batch: number;
+    }>;
+    const ranMap = new Map(ranRows.map((row) => [row.name, row.batch]));
+
+    let files: string[];
+    try {
+      files = readdirSync(migrationsDir);
+    } catch {
+      files = [];
+    }
+
+    const migrationFiles = files
+      .filter((file) => file.endsWith(".ts") || file.endsWith(".js"))
+      .sort((a, b) => a.localeCompare(b));
+
+    return migrationFiles.map((file) => ({
+      name: file,
+      ran: ranMap.has(file),
+      batch: ranMap.get(file),
+    }));
+  }
+}
+

package/src/migrations/Schema.ts

@@ -0,0 +1,20 @@
+import { getKnex } from "../connection/db";
+import { augmentTable, type XCreateTableBuilder } from "./columnHelpers";
+
+export class Schema {
+  async createTable(name: string, callback: (table: XCreateTableBuilder) => void): Promise<void> {
+    const knex = getKnex();
+    await knex.schema.createTable(name, (table) => {
+      callback(augmentTable(table, knex));
+    });
+  }
+
+  async dropTable(name: string): Promise<void> {
+    await getKnex().schema.dropTableIfExists(name);
+  }
+
+  async hasTable(name: string): Promise<boolean> {
+    return getKnex().schema.hasTable(name);
+  }
+}
+

package/src/migrations/columnHelpers.ts

@@ -0,0 +1,28 @@
+import type { Knex } from "knex";
+
+/** Augmented table builder: use `xacosTimestamps()` / `xacosSoftDeletes()` to avoid clashing with Knex's `timestamps()`. */
+export type XCreateTableBuilder = Knex.CreateTableBuilder & {
+  id(): void;
+  xacosTimestamps(): void;
+  xacosSoftDeletes(): void;
+};
+
+export function augmentTable(table: Knex.CreateTableBuilder, knex: Knex): XCreateTableBuilder {
+  const extended = table as XCreateTableBuilder;
+
+  extended.id = () => {
+    table.bigIncrements("id").primary();
+  };
+
+  extended.xacosTimestamps = () => {
+    table.timestamp("created_at").defaultTo(knex.fn.now()).notNullable();
+    table.timestamp("updated_at").defaultTo(knex.fn.now()).notNullable();
+  };
+
+  extended.xacosSoftDeletes = () => {
+    table.timestamp("deleted_at").nullable();
+  };
+
+  return extended;
+}
+

package/src/seeders/Seeder.ts

@@ -0,0 +1,8 @@
+export abstract class Seeder {
+  /**
+   * Implement this method with your seed logic.
+   * Called by the SeederRunner when `xacos db:seed` is invoked.
+   */
+  abstract run(): Promise<void>;
+}
+

package/src/seeders/SeederRunner.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+import { SeederRunner } from './SeederRunner';
+import { writeFileSync, mkdirSync, rmSync } from 'fs';
+import { resolve } from 'path';
+
+const TMP = resolve('./tmp-seeders-test');
+
+describe('SeederRunner', () => {
+  beforeEach(() => {
+    mkdirSync(TMP, { recursive: true });
+    writeFileSync(
+      `${TMP}/TestSeeder.ts`,
+      `export default class TestSeeder { async run() { (global as any).__seederRan = true; } }`
+    );
+  });
+
+  afterEach(() => rmSync(TMP, { recursive: true, force: true }));
+
+  it('throws when seeder file does not exist', async () => {
+    const runner = new SeederRunner(TMP);
+    await expect(runner.runOne('NonExistent')).rejects.toThrow('Seeder not found');
+  });
+
+  it('runs a single seeder', async () => {
+    const runner = new SeederRunner(TMP);
+    (global as any).__seederRan = false;
+    await runner.runOne('TestSeeder');
+    expect((global as any).__seederRan).toBe(true);
+  });
+
+  it('runs all seeders in directory', async () => {
+    writeFileSync(
+      `${TMP}/AnotherSeeder.ts`,
+      `export default class AnotherSeeder { async run() { (global as any).__anotherRan = true; } }`
+    );
+    const runner = new SeederRunner(TMP);
+    (global as any).__seederRan = false;
+    (global as any).__anotherRan = false;
+    await runner.runAll();
+    expect((global as any).__seederRan).toBe(true);
+    expect((global as any).__anotherRan).toBe(true);
+  });
+
+  it('sorts seeders: numbered before alpha', async () => {
+    // create files in reverse to ensure sorting matters
+    writeFileSync(`${TMP}/ZebraSeeder.ts`, 'export default class ZebraSeeder { async run() { (global as any).__order.push("zebra"); } }');
+    writeFileSync(`${TMP}/001_UserSeeder.ts`, 'export default class UserSeeder { async run() { (global as any).__order.push("user"); } }');
+    writeFileSync(`${TMP}/002_PostSeeder.ts`, 'export default class PostSeeder { async run() { (global as any).__order.push("post"); } }');
+    
+    const runner = new SeederRunner(TMP);
+    (global as any).__order = [];
+    
+    // We need to clear out the default seeders created in beforeEach if they interfere
+    rmSync(resolve(TMP, 'TestSeeder.ts'));
+    
+    await runner.runAll();
+    
+    expect((global as any).__order).toEqual(['user', 'post', 'zebra']);
+  });
+});
+
+

package/src/seeders/SeederRunner.ts

@@ -0,0 +1,76 @@
+import { resolve } from 'path';
+import { existsSync, readdirSync } from 'fs';
+import type { Seeder } from './Seeder';
+
+export class SeederRunner {
+  constructor(private seedersDir: string) {}
+
+  /**
+   * Run a specific seeder by class name.
+   * e.g. runOne('UserSeeder')
+   */
+  async runOne(name: string): Promise<void> {
+    const path = resolve(this.seedersDir, `${name}.ts`);
+    const jsPath = resolve(this.seedersDir, `${name}.js`);
+    
+    let targetPath = path;
+    if (!existsSync(path)) {
+      if (existsSync(jsPath)) {
+        targetPath = jsPath;
+      } else {
+        throw new Error(`[XAOCS] Seeder not found: ${name} at ${path}`);
+      }
+    }
+
+    const mod = await import(targetPath);
+    const SeederClass: new () => Seeder = mod.default ?? mod[name];
+    
+    if (!SeederClass) {
+      throw new Error(`[XAOCS] Seeder class not exported from ${name}.ts`);
+    }
+
+    const instance = new SeederClass();
+    console.log(`  ▶ Running seeder: ${name}`);
+    await instance.run();
+    console.log(`  ✓ Done: ${name}`);
+  }
+
+  /**
+   * Run all seeders in the seeders directory, in alphabetical order.
+   */
+  async runAll(): Promise<void> {
+    const files = this.getSortedFiles();
+    if (files.length === 0) {
+      console.log('[XAOCS] No seeder files found.');
+      return;
+    }
+    
+    for (const file of files) {
+      const name = file.replace(/\.(ts|js)$/, '');
+      await this.runOne(name);
+    }
+  }
+
+  /**
+   * Scan the seeders directory and return file names sorted correctly.
+   * Files prefixed with numbers sort numerically: 001_, 002_, etc.
+   * Files without prefix sort alphabetically after numbered ones.
+   */
+  private getSortedFiles(): string[] {
+    const fullPath = resolve(this.seedersDir);
+    if (!existsSync(fullPath)) return [];
+
+    return readdirSync(fullPath)
+      .filter((f: string) => f.endsWith('.ts') || f.endsWith('.js'))
+      .sort((a: string, b: string) => {
+        // Extract leading number if present: "001_UserSeeder.ts" → 1
+        const numA = parseInt(a.match(/^(\d+)/)?.[1] ?? 'Infinity', 10);
+        const numB = parseInt(b.match(/^(\d+)/)?.[1] ?? 'Infinity', 10);
+        
+        if (numA !== numB) return numA - numB;
+        return a.localeCompare(b);
+      });
+  }
+}
+
+

package/src/types/bun-test.d.ts

@@ -0,0 +1,8 @@
+declare module 'bun:test' {
+  export function describe(name: string, fn: () => void): void;
+  export function it(name: string, fn: () => Promise<void> | void): void;
+  export function expect(value: any): any;
+  export function beforeAll(fn: () => Promise<void> | void): void;
+  export function afterAll(fn: () => Promise<void> | void): void;
+}
+

package/src/utils/paginate.test.ts

@@ -0,0 +1,24 @@
+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: number) => ({
+        limit: async (lim: number) => [{ id: 1, off, lim }],
+      }),
+    };
+
+    const res = await paginate(mockQuery as any, -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 }] as any);
+  });
+});

package/src/utils/paginate.ts

@@ -0,0 +1,37 @@
+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 async function paginate<T>(
+  query: Knex.QueryBuilder,
+  page: number | string = 1,
+  perPage: number | string = 15
+): Promise<PaginatedResult<T>> {
+  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 as { total: string | number };
+  const total = Number(countResult?.total ?? 0);
+
+  const data = await query.offset(offset).limit(pp) as T[];
+
+  return {
+    data,
+    total,
+    page: p,
+    perPage: pp,
+    lastPage: Math.ceil(total / pp),
+  };
+}