stabilize-orm 1.1.8 → 1.3.0

package/package.json

@@ -1,19 +1,13 @@
 {
   "name": "stabilize-orm",
-  "version": "1.1.8",
+  "version": "1.3.0",
   "description": "A lightweight, type-safe ORM for Bun.js with support for SQLite, MySQL, PostgreSQL, and Redis caching",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "bin": {
-    "stabilize": "dist/cli/stabilize-cli.js"
-  },
   "scripts": {
-    "build": "bun build src/index.ts --outdir dist --target bun --minify && bun build cli/stabilize-cli.ts --outdir dist/cli --target bun --minify",
+    "build": "bun build src/index.ts --outdir dist --target bun --minify",
     "prepublishOnly": "bun run build && bun run test",
-    "build:exe": "bun build cli/stabilize-cli.ts --compile --outfile dist/stabilize-cli --target bun",
-    "format": "bunx prettier --write .",
-    "lint": "eslint src tests cli examples",
-    "cli": "bun run cli/stabilize-cli.ts"
+    "format": "bunx prettier --write ."
   },
   "keywords": [
     "orm",

package/repository.ts

@@ -9,18 +9,16 @@ import { DBClient } from "./client";
 import { ConsoleLogger, type Logger } from "./logger";
 import { QueryBuilder } from "./query-builder";
 import {
+  DataTypes,
   DBType,
   RelationType,
   StabilizeError,
   type CacheConfig,
 } from "./types";
-import {
-  ModelKey,
-  ColumnKey,
-  ValidatorKey,
-  RelationKey,
-  SoftDeleteKey,
-} from "./decorators";
+import { MetadataStorage } from "./model";
+import { getHooks, type HookType } from "./hooks";
+
+type VersionOperation = "insert" | "update" | "delete";
 
 /**
  * Provides a generic repository for a model `T`.
@@ -46,11 +44,13 @@ export class Repository<T> {
   >;
   private softDeleteField: string | null;
   private logger: Logger;
+  private versioned: boolean;
+  private historyTable: string;
 
   /**
    * Creates an instance of Repository.
    * @param client The database client instance for executing queries.
-   * @param model The model class constructor, decorated with `@Model`.
+   * @param model The model class constructor, defined with `defineModel`.
    * @param cacheConfig Optional configuration for caching.
    * @param logger A logger instance for logging messages.
    */
@@ -62,13 +62,31 @@ export class Repository<T> {
   ) {
     this.client = client;
     this.cache = cacheConfig.enabled ? new Cache(cacheConfig, logger) : null;
-    this.table = Reflect.getMetadata(ModelKey, model) || "";
-    this.columns = Reflect.getMetadata(ColumnKey, model.prototype) || {};
-    this.validators = Reflect.getMetadata(ValidatorKey, model.prototype) || {};
-    this.relations = Reflect.getMetadata(RelationKey, model.prototype) || {};
-    this.softDeleteField =
-      Reflect.getMetadata(SoftDeleteKey, model.prototype) || null;
+    this.table = MetadataStorage.getTableName(model);
+    this.columns = Object.fromEntries(
+      Object.entries(MetadataStorage.getColumns(model)).map(([key, col]) => [
+        key,
+        { name: col.name ?? key, type: typeof col.type === 'string' ? col.type : DataTypes[col.type] },
+      ])
+    );
+    this.relations = Object.fromEntries(
+      Object.entries(MetadataStorage.getRelations(model)).map(([key, rel]) => [
+        key,
+        {
+          type: rel.type,
+          targetModel: rel.target,
+          foreignKey: rel.foreignKey,
+          inverseKey: rel.inverseKey,
+          joinTable: rel.joinTable,
+        },
+      ])
+    );
+    this.validators = MetadataStorage.getValidators(model);
+
+    this.softDeleteField = MetadataStorage.getSoftDeleteField(model);
     this.logger = logger;
+    this.versioned = MetadataStorage.isVersioned(model);
+    this.historyTable = `${this.table}_history`;
   }
 
   /**
@@ -84,7 +102,7 @@ export class Repository<T> {
 
   /**
    * @internal
-   * Validates an entity against the 'required' constraints defined in decorators.
+   * Validates an entity against the 'required' constraints defined in the model configuration.
    * @param entity The partial entity to validate.
    */
   private validate(entity: Partial<T>) {
@@ -102,6 +120,17 @@ export class Repository<T> {
     }
   }
 
+  /**
+   * Runs lifecycle hooks of a given type for the entity.
+   * @param entity The entity instance.
+   * @param type The hook type (e.g., 'beforeCreate').
+   */
+  private async runHooks(entity: any, type: HookType): Promise<void> {
+    for (const hook of getHooks(entity, type)) {
+      await hook.callback(entity);
+    }
+  }
+
   /**
    * Creates a new `QueryBuilder` instance for the repository's table.
    * Automatically adds a `WHERE` clause to exclude soft-deleted records if applicable.
@@ -152,6 +181,121 @@ export class Repository<T> {
     return results[0] || null;
   }
 
+  /**
+   * Snapshot query: get record as it was at a point in time.
+   */
+  async asOf(
+    id: number | string,
+    asOfDate: Date,
+    _client?: DBClient
+  ): Promise<T | null> {
+    if (!this.versioned) throw new StabilizeError("Model is not versioned", "VERSIONING_ERROR");
+    const client = _client || this.client;
+    const rows = await client.query<T>(
+      `SELECT * FROM ${this.historyTable} WHERE id = ? AND valid_from <= ? AND (valid_to IS NULL OR valid_to > ?) ORDER BY version DESC LIMIT 1`,
+      [id, asOfDate, asOfDate]
+    );
+    return rows[0] || null;
+  }
+
+  /**
+   * Get all history for a record.
+   */
+  async history(
+    id: number | string,
+    _client?: DBClient
+  ): Promise<T[]> {
+    if (!this.versioned) throw new StabilizeError("Model is not versioned", "VERSIONING_ERROR");
+    const client = _client || this.client;
+    return client.query<T>(
+      `SELECT * FROM ${this.historyTable} WHERE id = ? ORDER BY version ASC`,
+      [id]
+    );
+  }
+
+  /**
+   * Rollback a record to a previous version.
+   */
+  async rollback(
+    id: number | string,
+    version: number,
+    _client?: DBClient
+  ): Promise<T> {
+    if (!this.versioned) throw new StabilizeError("Model is not versioned", "VERSIONING_ERROR");
+    const client = _client || this.client;
+    return client.transaction(async (txClient) => {
+      const rows = await txClient.query<T>(
+        `SELECT * FROM ${this.historyTable} WHERE id = ? AND version = ? LIMIT 1`,
+        [id, version]
+      );
+      if (!rows.length) throw new StabilizeError("Version not found", "ROLLBACK_ERROR");
+
+      const entity = rows[0];
+      const columns = Object.keys(this.columns).filter((c) => c !== "id");
+      const setClause = columns.map((c) => `${this.columns[c]!.name} = ?`).join(", ");
+      const params = columns.map((c) => (entity as any)[c]);
+
+      await txClient.query(
+        `UPDATE ${this.table} SET ${setClause} WHERE id = ?`,
+        [...params, id]
+      );
+      await this.writeHistory({ ...entity, version: version + 1 }, "update", txClient);
+      return this.findOne(id, {}, txClient) as Promise<T>;
+    });
+  }
+
+  /**
+   * Writes a versioned history row for the entity to the history table.
+   * @param entity The entity object being versioned
+   * @param operation The operation performed ("insert", "update", "delete")
+   * @param client The database client to use for the insert
+   * @param user The user/system responsible for the change (default: "system")
+   */
+  private async writeHistory(
+    entity: any,
+    operation: VersionOperation,
+    client: DBClient,
+    user?: string
+  ) {
+    if (!this.versioned) return;
+
+    const propertyKeys = Object.keys(this.columns);
+    const sqlColumnNames = propertyKeys.map((k) => this.columns[k]!.name);
+
+    const historyColumns = [
+      ...sqlColumnNames,
+      "operation",
+      "version",
+      "valid_from",
+      "valid_to",
+      "modified_by",
+      "modified_at"
+    ];
+
+    const values = propertyKeys.map((k) => entity[k]);
+    const params = [
+      ...values,
+      operation,
+      entity.version || 1,
+      new Date(),
+      null,
+      user || "system",
+      new Date()
+    ];
+
+    let placeholders: string;
+    if (client.config.type === DBType.Postgres) {
+      placeholders = params.map((_, i) => `$${i + 1}`).join(", ");
+    } else {
+      placeholders = params.map(() => "?").join(", ");
+    }
+
+    await client.query(
+      `INSERT INTO ${this.historyTable} (${historyColumns.join(", ")}) VALUES (${placeholders})`,
+      params
+    );
+  }
+
   /**
    * Creates a new record in the database within a transaction.
    * @param entity The data for the new record.
@@ -166,9 +310,21 @@ export class Repository<T> {
     entity: Partial<T>,
     options: { relations?: string[] } = {},
   ): Promise<T> {
-    return this.client.transaction((txClient) =>
-      this._create(entity, options, txClient),
-    );
+    return this.client.transaction(async (txClient) => {
+      const instance = new (Object.getPrototypeOf(entity).constructor || Object)();
+      Object.assign(instance, entity);
+
+      await this.runHooks(instance, "beforeCreate");
+      await this.runHooks(instance, "beforeSave");
+
+      const result = await this._create(entity, options, txClient);
+
+      await this.runHooks(result, "afterCreate");
+      await this.runHooks(result, "afterSave");
+
+      await this.writeHistory(result, "insert", txClient);
+      return result;
+    });
   }
 
   /**
@@ -245,9 +401,29 @@ export class Repository<T> {
     entities: Partial<T>[],
     options: { relations?: string[]; batchSize?: number } = {},
   ): Promise<T[]> {
-    return this.client.transaction((txClient) =>
-      this._bulkCreate(entities, options, txClient),
-    );
+    return this.client.transaction(async (txClient) => {
+      const preparedEntities = entities.map(data => {
+        const instance = new (this as any).model();
+        Object.assign(instance, data);
+        return instance;
+      });
+
+      for (const entity of preparedEntities) {
+        await this.runHooks(entity, "beforeCreate");
+        await this.runHooks(entity, "beforeSave");
+      }
+
+      const results = await this._bulkCreate(entities, options, txClient);
+
+      for (const result of results) {
+        await this.runHooks(result, "afterCreate");
+        await this.runHooks(result, "afterSave");
+        if (this.versioned) {
+          await this.writeHistory(result, "insert", txClient);
+        }
+      }
+      return results;
+    });
   }
 
   /**
@@ -282,7 +458,6 @@ export class Repository<T> {
       );
 
       if (dbType === DBType.Postgres) {
-        // PostgreSQL: numbered placeholders ($1, $2, ...)
         let paramIdx = 1;
         const valuePlaceholders = batch
           .map(
@@ -294,7 +469,6 @@ export class Repository<T> {
         const batchResults = await client.query<T>(query, params);
         const ids = batchResults.map((r) => (r as any).id);
 
-        // Handle relation loading if needed
         let finalResults = batchResults;
         if (ids.length > 0 && batchResults.length === 0) {
           const queryBuilder = this.find().where(
@@ -311,7 +485,6 @@ export class Repository<T> {
         results.push(...finalResults);
 
       } else {
-        // SQLite/MySQL: ? placeholders
         const placeholders = `(${keys.map(() => "?").join(", ")})`;
         query = `INSERT INTO ${this.table} (${columnNames}) VALUES ${batch.map(() => placeholders).join(", ")}`;
         await client.query(query, params);
@@ -358,9 +531,27 @@ export class Repository<T> {
    * ```
    */
   async update(id: number | string, entity: Partial<T>): Promise<T> {
-    return this.client.transaction((txClient) =>
-      this._update(id, entity, txClient),
-    );
+    return this.client.transaction(async (txClient) => {
+      const before = await this.findOne(id, {}, txClient);
+      if (!before) throw new StabilizeError("Not found", "UPDATE_ERROR");
+      const instance = new (Object.getPrototypeOf(before).constructor || Object)();
+      Object.assign(instance, before, entity);
+
+      await this.runHooks(instance, "beforeUpdate");
+      await this.runHooks(instance, "beforeSave");
+
+      const result = await this._update(id, entity, txClient);
+
+      await this.runHooks(result, "afterUpdate");
+      await this.runHooks(result, "afterSave");
+
+      await this.writeHistory(
+        { ...before, ...entity, version: (before as any).version ? (before as any).version + 1 : 1 },
+        "update",
+        txClient
+      );
+      return result;
+    });
   }
 
   /**
@@ -442,14 +633,45 @@ export class Repository<T> {
     for (let i = 0; i < updates.length; i += batchSize) {
       const batch = updates.slice(i, i + batchSize);
       for (const update of batch) {
-        const keys = Object.keys(update.set).filter((k) => this.columns[k]);
-        const setClause = keys.map((k) => `${this.columns[k]?.name} = ?`).join(", ");
-        const query = `UPDATE ${this.table} SET ${setClause} WHERE ${update.where.condition}${this.softDeleteField ? ` AND ${this.softDeleteField} IS NULL` : ""}`;
-        const params = [
-          ...keys.map((k) => (update.set as any)[k]),
-          ...update.where.params,
-        ];
-        await client.query(query, params);
+        const rows = await client.query<{ id: number | string }>(
+          `SELECT id FROM ${this.table} WHERE ${update.where.condition}${this.softDeleteField ? ` AND ${this.softDeleteField} IS NULL` : ""}`,
+          update.where.params,
+        );
+        for (const { id } of rows) {
+          const before = await this.findOne(id, {}, client);
+          if (!before) continue;
+
+          const instance = new ((this as any).model || Object)();
+          Object.assign(instance, before, update.set);
+
+          await this.runHooks(instance, "beforeUpdate");
+          await this.runHooks(instance, "beforeSave");
+
+          const keys = Object.keys(update.set).filter((k) => this.columns[k]);
+          const setClause = keys.map((k) => `${this.columns[k]?.name} = ?`).join(", ");
+          const query = `UPDATE ${this.table} SET ${setClause} WHERE id = ?${this.softDeleteField ? ` AND ${this.softDeleteField} IS NULL` : ""}`;
+          const params = [
+            ...keys.map((k) => (update.set as any)[k]),
+            id,
+          ];
+          await client.query(query, params);
+
+          const after = await this.findOne(id, {}, client);
+          if (after) {
+            await this.runHooks(after, "afterUpdate");
+            await this.runHooks(after, "afterSave");
+            if (this.versioned) {
+              await this.writeHistory(
+                {
+                  ...after,
+                  version: (before as any).version ? (before as any).version + 1 : 1
+                },
+                "update",
+                client
+              );
+            }
+          }
+        }
       }
     }
 
@@ -495,6 +717,7 @@ export class Repository<T> {
     const columns = Object.keys(entity).filter((k) => this.columns[k]);
     const columnNames = columns.map((k) => this.columns[k]?.name).join(", ");
     const placeholders = columns.map(() => "?").join(", ");
+
     const updateClause = columns
       .filter((c) => !keys.includes(c))
       .map((c) => `${this.columns[c]?.name} = ?`).join(", ");
@@ -504,11 +727,35 @@ export class Repository<T> {
     const insertParams = columns.map((k) => (entity as any)[k]);
     let params = [...insertParams, ...updateParams];
 
+    let before: T | null = null;
+    let isUpdate = false;
+    if (this.versioned && keys.length > 0) {
+      const whereClause = keys.map((k) => `${this.columns[k]?.name} = ?`).join(" AND ");
+      const whereParams = keys.map((k) => (entity as any)[k]);
+      const found = await client.query<T>(
+        `SELECT * FROM ${this.table} WHERE ${whereClause} LIMIT 1`,
+        whereParams
+      );
+      before = found[0] || null;
+      isUpdate = !!before;
+    }
+
+    const instance = new ((this as any).model || Object)();
+    Object.assign(instance, before || {}, entity);
+
+    if (isUpdate) {
+      await this.runHooks(instance, "beforeUpdate");
+      await this.runHooks(instance, "beforeSave");
+    } else {
+      await this.runHooks(instance, "beforeCreate");
+      await this.runHooks(instance, "beforeSave");
+    }
+
     if (dbType === DBType.SQLite) {
       query = `INSERT INTO ${this.table} (${columnNames}) VALUES (${placeholders}) ON CONFLICT(${keys.map((k) => this.columns[k]!.name).join(", ")}) DO UPDATE SET ${updateClause}`;
     } else if (dbType === DBType.MySQL) {
       query = `INSERT INTO ${this.table} (${columnNames}) VALUES (${placeholders}) ON DUPLICATE KEY UPDATE ${updateClause}`;
-    } else { // PostgreSQL
+    } else {
       const pgUpdateClause = columns
         .filter((c) => !keys.includes(c))
         .map((c) => `${this.columns[c]?.name} = EXCLUDED.${this.columns[c]?.name}`).join(", ");
@@ -532,6 +779,22 @@ export class Repository<T> {
 
     const result = results[0] ?? ((await this.findOne(id, {}, client)) as T);
 
+    if (isUpdate) {
+      await this.runHooks(result, "afterUpdate");
+      await this.runHooks(result, "afterSave");
+    } else {
+      await this.runHooks(result, "afterCreate");
+      await this.runHooks(result, "afterSave");
+    }
+
+    if (this.versioned) {
+      await this.writeHistory(
+        { ...result, version: before ? ((before as any).version ? (before as any).version + 1 : 1) : 1 },
+        before ? "update" : "insert",
+        client
+      );
+    }
+
     if (this.cache) {
       await this.cache.invalidatePattern(`find:${this.table}:*`);
       if (this.cache.getStrategy() === "write-through") {
@@ -555,7 +818,16 @@ export class Repository<T> {
    * ```
    */
   async delete(id: number | string): Promise<void> {
-    return this.client.transaction((txClient) => this._delete(id, txClient));
+    return this.client.transaction(async (txClient) => {
+      const before = await this.findOne(id, {}, txClient);
+      if (!before) throw new StabilizeError("Not found", "DELETE_ERROR");
+      await this.runHooks(before, "beforeDelete");
+
+      await this._delete(id, txClient);
+
+      await this.runHooks(before, "afterDelete");
+      await this.writeHistory(before, "delete", txClient);
+    });
   }
 
   /**
@@ -619,14 +891,25 @@ export class Repository<T> {
     const batchSize = options.batchSize || 1000;
     for (let i = 0; i < ids.length; i += batchSize) {
       const batch = ids.slice(i, i + batchSize);
-      const placeholders = batch.map(() => "?").join(", ");
-      const query = this.softDeleteField
-        ? `UPDATE ${this.table} SET ${this.softDeleteField} = ? WHERE id IN (${placeholders})`
-        : `DELETE FROM ${this.table} WHERE id IN (${placeholders})`;
-      const params = this.softDeleteField
-        ? [new Date().toISOString(), ...batch]
-        : batch;
-      await client.query(query, params);
+      for (const id of batch) {
+        const before = await this.findOne(id, {}, client);
+        if (!before) continue;
+
+        await this.runHooks(before, "beforeDelete");
+
+        const query = this.softDeleteField
+          ? `UPDATE ${this.table} SET ${this.softDeleteField} = ? WHERE id = ?`
+          : `DELETE FROM ${this.table} WHERE id = ?`;
+        const params = this.softDeleteField ? [new Date().toISOString(), id] : [id];
+
+        await client.query(query, params);
+
+        await this.runHooks(before, "afterDelete");
+
+        if (this.versioned) {
+          await this.writeHistory(before, "delete", client);
+        }
+      }
     }
 
     if (this.cache) await this.cache.invalidatePattern(`find:${this.table}:*`);
@@ -721,7 +1004,7 @@ export class Repository<T> {
         "RELATION_ERROR",
       );
 
-    const relatedTable = Reflect.getMetadata(ModelKey, rel.targetModel());
+    const relatedTable = MetadataStorage.getTableName(rel.targetModel());
     if (
       rel.type === RelationType.OneToOne ||
       rel.type === RelationType.ManyToOne
@@ -747,4 +1030,4 @@ export class Repository<T> {
         );
     }
   }
-}
+}