@bunnykit/orm 0.1.24 → 0.1.26

package/README.md

@@ -23,7 +23,8 @@ An **Eloquent-inspired ORM** built specifically for [Bun](https://bun.sh)'s nati
 - 🧬 **Eloquent-style Models** — Property attributes, defaults, casts, dirty tracking, soft deletes, scopes, find-or-fail, first-or-create
 - 🔗 **Relations** — Standard, many-to-many, polymorphic, through, one-of-many, and relation queries
 - 👁️ **Observers** — Lifecycle hooks (`creating`, `created`, `updating`, `updated`, etc.)
-- 🚀 **Migrations & CLI** — Create, run, and rollback migrations from the command line
+- 🚀 **Migrations & CLI** — Create, run, reset, refresh, and inspect migrations from the command line
+- 🌱 **Seeders & Factories** — Run all seeders or target one seeder by name/file, plus lightweight model factories
 - 💬 **REPL** — Inspect models and run queries interactively with `bunny repl`
 - ⚡ **Streaming** — `chunk`, `cursor`, `each`, and `lazy` for memory-efficient large dataset processing
 
@@ -71,6 +72,7 @@ export default {
   //   }),
   //   listTenants: async () => await getAllTenantIds(),
   // },
+  seedersPath: "./database/seeders",
   modelsPath: ["./src/models", "./src/admin/models"],
   // Optional legacy type output directory
   // typesOutDir: "./src/generated/model-types",
@@ -87,6 +89,7 @@ Or use environment variables:
 ```bash
 export DATABASE_URL="sqlite://app.db"
 export MIGRATIONS_PATH="./database/migrations,./database/tenant-migrations"
+export SEEDERS_PATH="./database/seeders"
 export MODELS_PATH="./src/models,./src/admin/models"
 export TYPES_OUT_DIR="./src/generated/model-types"
 ```
@@ -1108,6 +1111,84 @@ ObserverRegistry.register(User, {
 
 ---
 
+## Seeders and Factories
+
+Set `seedersPath` in `bunny.config.ts` to define the default directory used by `db:seed`:
+
+```ts
+export default {
+  connection: { url: "sqlite://app.db" },
+  seedersPath: "./database/seeders",
+};
+```
+
+`seedersPath` can also be an array:
+
+```ts
+export default {
+  connection: { url: "sqlite://app.db" },
+  seedersPath: ["./database/seeders", "./modules/demo/seeders"],
+};
+```
+
+Create a seeder by extending `Seeder`:
+
+```ts
+import { Seeder } from "@bunnykit/orm";
+import { User } from "../models/User";
+
+export default class UserSeeder extends Seeder {
+  async run(): Promise<void> {
+    await User.create({ name: "Ada Lovelace", email: "ada@example.test" });
+  }
+}
+```
+
+Run every seeder in `seedersPath`:
+
+```bash
+bun run bunny db:seed
+```
+
+Run one seeder by class/file name from `seedersPath`:
+
+```bash
+bun run bunny db:seed UserSeeder
+```
+
+Run one seeder by direct file path:
+
+```bash
+bun run bunny db:seed ./database/seeders/UserSeeder.ts
+```
+
+Programmatic seeding is available through `SeederRunner`:
+
+```ts
+import { SeederRunner } from "@bunnykit/orm";
+
+await new SeederRunner(connection).runTarget("UserSeeder", "./database/seeders");
+await new SeederRunner(connection).runFile("./database/seeders/UserSeeder.ts");
+```
+
+Factories can create raw attributes, unsaved models, or persisted records:
+
+```ts
+import { factory } from "@bunnykit/orm";
+import { User } from "../models/User";
+
+const users = factory(User, (sequence) => ({
+  name: `User ${sequence}`,
+  email: `user${sequence}@example.test`,
+}));
+
+const attributes = users.raw();
+const model = users.make();
+const created = await users.count(3).state({ role: "admin" }).create();
+```
+
+---
+
 ## Migrations
 
 ### CLI Commands
@@ -1125,9 +1206,27 @@ bun run bunny migrate
 # Rollback the last batch
 bun run bunny migrate:rollback
 
+# Rollback all migrations
+bun run bunny migrate:reset
+
+# Reset and rerun migrations
+bun run bunny migrate:refresh
+
+# Drop all tables and rerun migrations
+bun run bunny migrate:fresh
+
 # Show migration status
 bun run bunny migrate:status
 
+# Run all seeders in seedersPath
+bun run bunny db:seed
+
+# Run one seeder by name from seedersPath
+bun run bunny db:seed UserSeeder
+
+# Run one seeder by direct file path
+bun run bunny db:seed ./database/seeders/UserSeeder.ts
+
 # Dump the current database schema
 bun run bunny schema:dump ./database/schema.sql
 

package/dist/bin/bunny.js

@@ -5,6 +5,7 @@ import { TenantContext } from "../src/connection/TenantContext.js";
 import { configureBunny } from "../src/config/BunnyConfig.js";
 import { Migrator } from "../src/migration/Migrator.js";
 import { MigrationCreator } from "../src/migration/MigrationCreator.js";
+import { SeederRunner } from "../src/seeding/Seeder.js";
 import { TypeGenerator } from "../src/typegen/TypeGenerator.js";
 import { existsSync } from "fs";
 import { mkdir, rm, writeFile } from "fs/promises";
@@ -64,6 +65,18 @@ async function runMigratorCommand(command, migrator, statusLabel) {
         await migrator.rollback();
         return;
     }
+    if (command === "migrate:reset") {
+        await migrator.reset();
+        return;
+    }
+    if (command === "migrate:refresh") {
+        await migrator.refresh();
+        return;
+    }
+    if (command === "migrate:fresh") {
+        await migrator.fresh();
+        return;
+    }
     const status = await migrator.status();
     if (statusLabel) {
         console.log(statusLabel);
@@ -338,6 +351,7 @@ async function loadConfig(allowFallback = false) {
         return {
             connection: { url },
             migrationsPath: parseEnvPathSetting(process.env.MIGRATIONS_PATH) || "./database/migrations",
+            seedersPath: parseEnvPathSetting(process.env.SEEDERS_PATH),
             modelsPath: parseEnvPathSetting(process.env.MODELS_PATH),
         };
     }
@@ -354,6 +368,7 @@ async function loadConfig(allowFallback = false) {
                 filename: process.env.DB_DATABASE,
             },
             migrationsPath: parseEnvPathSetting(process.env.MIGRATIONS_PATH) || "./database/migrations",
+            seedersPath: parseEnvPathSetting(process.env.SEEDERS_PATH),
             modelsPath: parseEnvPathSetting(process.env.MODELS_PATH),
         };
     }
@@ -361,6 +376,7 @@ async function loadConfig(allowFallback = false) {
         return {
             connection: { url: "sqlite://:memory:" },
             migrationsPath: parseEnvPathSetting(process.env.MIGRATIONS_PATH) || "./database/migrations",
+            seedersPath: parseEnvPathSetting(process.env.SEEDERS_PATH),
             modelsPath: parseEnvPathSetting(process.env.MODELS_PATH),
         };
     }
@@ -432,9 +448,29 @@ async function main() {
     else if (command === "migrate:rollback") {
         await runConfiguredMigrationCommand(command, config, connection, parseMigrationTarget(args.slice(1)));
     }
+    else if (command === "migrate:reset") {
+        await runConfiguredMigrationCommand(command, config, connection, parseMigrationTarget(args.slice(1)));
+    }
+    else if (command === "migrate:refresh") {
+        await runConfiguredMigrationCommand(command, config, connection, parseMigrationTarget(args.slice(1)));
+    }
+    else if (command === "migrate:fresh") {
+        await runConfiguredMigrationCommand(command, config, connection, parseMigrationTarget(args.slice(1)));
+    }
     else if (command === "migrate:status") {
         await runConfiguredMigrationCommand(command, config, connection, parseMigrationTarget(args.slice(1)));
     }
+    else if (command === "db:seed") {
+        const target = args[1];
+        const seederPath = config.seedersPath || "./database/seeders";
+        const runner = new SeederRunner(connection);
+        if (target) {
+            await runner.runTarget(target, seederPath);
+        }
+        else {
+            await runner.runPaths(seederPath);
+        }
+    }
     else {
         console.log("Usage:");
         console.log("  bun run bunny migrate              Run landlord migrations, then all tenant migrations when configured");
@@ -443,7 +479,12 @@ async function main() {
         console.log("  bun run bunny migrate --tenant <id> Run one tenant's migrations only");
         console.log("  bun run bunny migrate:make <name> [dir] Create a new migration");
         console.log("  bun run bunny migrate:rollback     Rollback the last batch");
+        console.log("  bun run bunny migrate:reset        Rollback all migrations");
+        console.log("  bun run bunny migrate:refresh      Reset and rerun migrations");
+        console.log("  bun run bunny migrate:fresh        Drop all tables and rerun migrations");
         console.log("  bun run bunny migrate:status       Show migration status");
+        console.log("  bun run bunny db:seed              Run seeders from seedersPath");
+        console.log("  bun run bunny db:seed <seeder>     Run one seeder by file path or name");
         console.log("  bun run bunny schema:dump [path]   Dump the current database schema");
         console.log("  bun run bunny schema:squash [path] Dump schema and mark configured migrations as ran");
         console.log("  bun run bunny types:generate [dir] Generate model type declarations from DB schema");

package/dist/src/config/BunnyConfig.d.ts

@@ -5,6 +5,7 @@ import type { ConnectionConfig } from "../types/index.js";
 export interface BunnyConfig {
     connection: ConnectionConfig;
     migrationsPath?: string | string[];
+    seedersPath?: string | string[];
     migrations?: {
         landlord?: string | string[];
         tenant?: string | string[];

package/dist/src/connection/Connection.d.ts

@@ -18,10 +18,13 @@ export declare class Connection {
     getDriverName(): "sqlite" | "mysql" | "postgres";
     getGrammar(): Grammar;
     getSchema(): string | undefined;
+    static isSafeIdentifier(value: string): boolean;
+    static assertSafeIdentifier(value: string, label?: string): void;
+    static assertSafeQualifiedIdentifier(value: string, label?: string): void;
     withSchema(schema: string): Connection;
     withoutSchema(): Connection;
     qualifyTable(table: string): string;
-    private quoteIdentifier;
+    quoteIdentifier(value: string): string;
     query(sqlString: string, bindings?: any[]): Promise<any[]>;
     run(sqlString: string, bindings?: any[]): Promise<any>;
     beginTransaction(): Promise<void>;

package/dist/src/connection/Connection.js

@@ -59,7 +59,22 @@ export class Connection {
     getSchema() {
         return this.schema;
     }
+    static isSafeIdentifier(value) {
+        return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+    }
+    static assertSafeIdentifier(value, label = "identifier") {
+        if (!this.isSafeIdentifier(value)) {
+            throw new Error(`Invalid ${label}: ${value}`);
+        }
+    }
+    static assertSafeQualifiedIdentifier(value, label = "identifier") {
+        const parts = value.split(".");
+        if (parts.length === 0 || parts.some((part) => !this.isSafeIdentifier(part))) {
+            throw new Error(`Invalid ${label}: ${value}`);
+        }
+    }
     withSchema(schema) {
+        Connection.assertSafeIdentifier(schema, "schema name");
         if (this.schema === schema)
             return this;
         return new Connection(this.config, { driver: this.driver, schema, ownsDriver: false });
@@ -70,8 +85,14 @@ export class Connection {
         return new Connection(this.config, { driver: this.driver, ownsDriver: false });
     }
     qualifyTable(table) {
-        if (!this.schema || this.driverName === "sqlite" || table.includes("."))
+        if (table.includes(".")) {
+            Connection.assertSafeQualifiedIdentifier(table, "qualified table name");
+            return table;
+        }
+        if (!this.schema || this.driverName === "sqlite")
             return table;
+        Connection.assertSafeIdentifier(this.schema, "schema name");
+        Connection.assertSafeIdentifier(table, "table name");
         return `${this.schema}.${table}`;
     }
     quoteIdentifier(value) {
@@ -144,6 +165,7 @@ export class Connection {
         if (this.driverName !== "postgres") {
             throw new Error("search_path schema switching is only supported for PostgreSQL connections.");
         }
+        Connection.assertSafeIdentifier(schema, "schema name");
         return await this.transaction(async (connection) => {
             await connection.run(`SET LOCAL search_path TO ${connection.quoteIdentifier(schema)}`);
             return await callback(connection.withoutSchema());

package/dist/src/connection/ConnectionManager.d.ts

@@ -1,25 +1,32 @@
 import { Connection } from "./Connection.js";
 import type { ConnectionConfig } from "../types/index.js";
 import type { ActiveTenantContext } from "./TenantContext.js";
-export type TenantResolution = {
+export interface TenantCachePolicy {
+    ttl?: number;
+    closeOnPurge?: boolean;
+}
+type TenantResolutionOptions = TenantCachePolicy & {
+    cache?: TenantCachePolicy;
+};
+export type TenantResolution = ({
     strategy: "database";
     name: string;
     config: ConnectionConfig;
-} | {
+} & TenantResolutionOptions) | ({
     strategy: "schema";
     name: string;
     config?: ConnectionConfig;
     connection?: string | Connection;
     schema: string;
     mode?: "qualify" | "search_path";
-} | {
+} & TenantResolutionOptions) | ({
     strategy: "rls";
     name: string;
     config?: ConnectionConfig;
     connection?: string | Connection;
     tenantId?: string;
     setting?: string;
-};
+} & TenantResolutionOptions);
 export type TenantResolver = (tenantId: string) => TenantResolution | Promise<TenantResolution>;
 export interface PoolConfig {
     maxConnections?: number;
@@ -50,6 +57,10 @@ export declare class ConnectionManager {
     static resolveTenant(tenantId: string): Promise<ActiveTenantContext>;
     static getResolvedTenant(tenantId: string): ActiveTenantContext | undefined;
     static purgeTenant(tenantId: string): void;
+    static purgeExpiredTenants(options?: {
+        close?: boolean;
+    }): Promise<string[]>;
     static closeTenant(tenantId: string): Promise<void>;
     static closeAll(): Promise<void>;
 }
+export {};

package/dist/src/connection/ConnectionManager.js

@@ -139,14 +139,20 @@ export class ConnectionManager {
     }
     static async resolveTenant(tenantId) {
         const cached = this.tenantCache.get(tenantId);
-        if (cached)
-            return cached;
+        if (cached) {
+            if (!cached.expiresAt || cached.expiresAt > Date.now())
+                return cached;
+            await this.closeTenant(tenantId);
+        }
         if (!this.tenantResolver) {
             throw new Error("No tenant resolver configured.");
         }
         const resolution = await this.tenantResolver(tenantId);
+        const policy = { ...resolution.cache, ttl: resolution.ttl ?? resolution.cache?.ttl, closeOnPurge: resolution.closeOnPurge ?? resolution.cache?.closeOnPurge };
+        const resolvedAt = Date.now();
         const schema = resolution.strategy === "schema" ? resolution.schema : undefined;
         const schemaMode = resolution.strategy === "schema" ? resolution.mode || "qualify" : undefined;
+        let ownsConnection = false;
         let connection = (resolution.strategy === "schema" || resolution.strategy === "rls") && resolution.connection instanceof Connection
             ? resolution.connection
             : (resolution.strategy === "schema" || resolution.strategy === "rls") && typeof resolution.connection === "string"
@@ -167,6 +173,7 @@ export class ConnectionManager {
             }
             connection = new Connection(config, { schema });
             this.connections.set(resolution.name, connection);
+            ownsConnection = true;
         }
         else if (schema && schemaMode === "qualify") {
             connection = connection.withSchema(schema);
@@ -176,6 +183,10 @@ export class ConnectionManager {
             connection,
             connectionName: resolution.name,
             strategy: resolution.strategy,
+            resolvedAt,
+            expiresAt: policy.ttl ? resolvedAt + policy.ttl : undefined,
+            closeOnPurge: policy.closeOnPurge ?? ownsConnection,
+            ownsConnection,
             schema,
             schemaMode,
             rlsTenantId: resolution.strategy === "rls" ? resolution.tenantId || tenantId : undefined,
@@ -185,19 +196,53 @@ export class ConnectionManager {
         return context;
     }
     static getResolvedTenant(tenantId) {
-        return this.tenantCache.get(tenantId);
+        const context = this.tenantCache.get(tenantId);
+        if (!context || !context.expiresAt || context.expiresAt > Date.now())
+            return context;
+        this.tenantCache.delete(tenantId);
+        return undefined;
     }
     static purgeTenant(tenantId) {
         this.tenantCache.delete(tenantId);
     }
+    static async purgeExpiredTenants(options = {}) {
+        const now = Date.now();
+        const purged = [];
+        for (const [tenantId, context] of [...this.tenantCache.entries()]) {
+            if (!context.expiresAt || context.expiresAt > now)
+                continue;
+            purged.push(tenantId);
+            if (options.close ?? context.closeOnPurge) {
+                await this.closeTenant(tenantId);
+            }
+            else {
+                this.tenantCache.delete(tenantId);
+            }
+        }
+        return purged;
+    }
     static async closeTenant(tenantId) {
         const context = this.tenantCache.get(tenantId);
         if (!context)
             return;
         this.tenantCache.delete(tenantId);
+        if (!context.closeOnPurge)
+            return;
         const connection = this.connections.get(context.connectionName);
-        this.connections.delete(context.connectionName);
-        await connection?.close();
+        if (connection === context.connection) {
+            this.connections.delete(context.connectionName);
+            await connection.close();
+        }
+        else if (context.ownsConnection) {
+            await context.connection.close();
+        }
+        const pool = this.pools.get(context.connectionName);
+        if (pool) {
+            this.pools.delete(context.connectionName);
+            for (const { connection } of pool) {
+                await connection.close().catch(() => null);
+            }
+        }
     }
     static async closeAll() {
         const connections = new Set(this.connections.values());

package/dist/src/connection/TenantContext.d.ts

@@ -4,6 +4,10 @@ export interface ActiveTenantContext {
     connection: Connection;
     connectionName: string;
     strategy: "database" | "schema" | "rls";
+    resolvedAt: number;
+    expiresAt?: number;
+    closeOnPurge: boolean;
+    ownsConnection: boolean;
     schema?: string;
     schemaMode?: "qualify" | "search_path";
     rlsTenantId?: string;

package/dist/src/index.d.ts

@@ -1,6 +1,6 @@
 export { Connection } from "./connection/Connection.js";
 export { ConnectionManager } from "./connection/ConnectionManager.js";
-export type { TenantResolution, TenantResolver } from "./connection/ConnectionManager.js";
+export type { TenantCachePolicy, TenantResolution, TenantResolver } from "./connection/ConnectionManager.js";
 export { TenantContext } from "./connection/TenantContext.js";
 export type { ActiveTenantContext } from "./connection/TenantContext.js";
 export { configureBunny } from "./config/BunnyConfig.js";
@@ -23,7 +23,10 @@ export { BelongsToMany } from "./model/BelongsToMany.js";
 export { IdentityMap } from "./model/IdentityMap.js";
 export { Migration } from "./migration/Migration.js";
 export { Migrator } from "./migration/Migrator.js";
-export type { MigrationEvent, MigrationEventListener, MigrationEventPayload } from "./migration/Migrator.js";
+export type { MigrationEvent, MigrationEventListener, MigrationEventPayload, MigrationStatusRow, MigratorOptions } from "./migration/Migrator.js";
 export { MigrationCreator } from "./migration/MigrationCreator.js";
 export { TypeGenerator } from "./typegen/TypeGenerator.js";
 export { TypeMapper } from "./typegen/TypeMapper.js";
+export { Seeder, SeederRunner } from "./seeding/Seeder.js";
+export { Factory, factory } from "./seeding/Factory.js";
+export type { FactoryDefinition, FactoryState } from "./seeding/Factory.js";

package/dist/src/index.js

@@ -21,3 +21,5 @@ export { Migrator } from "./migration/Migrator.js";
 export { MigrationCreator } from "./migration/MigrationCreator.js";
 export { TypeGenerator } from "./typegen/TypeGenerator.js";
 export { TypeMapper } from "./typegen/TypeMapper.js";
+export { Seeder, SeederRunner } from "./seeding/Seeder.js";
+export { Factory, factory } from "./seeding/Factory.js";

package/dist/src/migration/Migrator.d.ts

@@ -1,5 +1,17 @@
 import { Connection } from "../connection/Connection.js";
 import type { TypeGeneratorOptions } from "../typegen/TypeGenerator.js";
+export interface MigrationStatusRow {
+    migration: string;
+    status: string;
+    tenant: string | null;
+    checksum?: string;
+    storedChecksum?: string | null;
+}
+export interface MigratorOptions {
+    tenantId?: string | null;
+    lock?: boolean;
+    lockTimeoutMs?: number;
+}
 export type MigrationEvent = "migrating" | "migrated" | "rollingBack" | "rolledBack" | "schemaDumped" | "schemaSquashed";
 export interface MigrationEventPayload {
     migration?: string;
@@ -12,25 +24,37 @@ export declare class Migrator {
     private path;
     private typesOutDir?;
     private typeGeneratorOptions;
+    private options;
     private static listeners;
-    constructor(connection: Connection, path: string | string[], typesOutDir?: string | undefined, typeGeneratorOptions?: Omit<TypeGeneratorOptions, "outDir">);
+    constructor(connection: Connection, path: string | string[], typesOutDir?: string | undefined, typeGeneratorOptions?: Omit<TypeGeneratorOptions, "outDir">, options?: MigratorOptions);
     private getPaths;
     private ensureMigrationsTable;
+    private getTenantId;
+    private scopedMigrations;
+    private ensureMigrationLocksTable;
+    private getLockName;
+    private shouldLock;
+    private acquireLock;
+    private releaseLock;
     static on(event: MigrationEvent, listener: MigrationEventListener): () => void;
     static clearListeners(event?: MigrationEvent): void;
     private emit;
     private getLastBatchNumber;
     private getMigrationFiles;
+    private checksumFile;
     run(): Promise<void>;
-    rollback(): Promise<void>;
+    rollback(steps?: number): Promise<void>;
+    private getRollbackBatches;
+    reset(): Promise<void>;
+    refresh(): Promise<void>;
+    fresh(): Promise<void>;
     private generateTypesIfNeeded;
-    status(): Promise<{
-        migration: string;
-        status: string;
-    }[]>;
+    status(): Promise<MigrationStatusRow[]>;
     dumpSchema(path: string): Promise<string>;
     squash(path: string): Promise<string>;
     private getSchemaDumpSql;
+    private dropAllTables;
     private resolve;
     private getRan;
+    private getRanRecords;
 }