stabilize-orm 1.2.0 → 1.3.2

package/model.ts

@@ -0,0 +1,177 @@
+/**
+ * @file model.ts
+ * @description Provides a programmatic API for defining models and a metadata storage system.
+ * @author ElectronSz
+ */
+
+import type { QueryBuilder } from './query-builder';
+import { DataTypes, RelationType, DBType } from './types';
+
+// Interface for column configuration
+export interface ColumnConfig {
+    name?: string;
+    type: DataTypes;
+    length?: number;
+    precision?: number;
+    scale?: number;
+    required?: boolean;
+    unique?: boolean;
+    defaultValue?: any;
+    index?: string; // Optional index name
+    softDelete?: boolean; // Marks column as soft delete field
+}
+
+// Interface for relationship configuration
+export interface RelationConfig {
+    type: RelationType;
+    target: () => any; // Reference to another model
+    property: string; // Property name in the model
+    foreignKey?: string;
+    inverseKey?: string;
+    joinTable?: string;
+}
+
+// Interface for model configuration
+export interface ModelConfig {
+    tableName: string;
+    versioned?: boolean;
+    softDelete?: boolean;
+    columns: Record<string, ColumnConfig>;
+    relations?: RelationConfig[];
+    scopes?: Record<string, (qb: QueryBuilder<any>, ...args: any[]) => QueryBuilder<any>>; // Custom query scopes
+}
+
+/**
+ * Metadata storage for models.
+ * Stores and retrieves model configuration such as columns, relations, scopes, etc.
+ */
+export class MetadataStorage {
+    private static models: Map<Function, ModelConfig> = new Map();
+
+    /**
+     * Associates model metadata with a class constructor.
+     * @param model - The class constructor for the model.
+     * @param config - The model configuration object.
+     */
+    static setModelMetadata(model: Function, config: ModelConfig) {
+        this.models.set(model, config);
+    }
+
+    /**
+     * Retrieves the model configuration for a given model class.
+     * @param model - The class constructor for the model.
+     * @returns The model configuration or undefined if not found.
+     */
+    static getModelMetadata(model: Function): ModelConfig | undefined {
+        return this.models.get(model);
+    }
+
+    /**
+     * Gets the table name for a given model class.
+     * @param model - The class constructor for the model.
+     * @returns The table name or an empty string if not found.
+     */
+    static getTableName(model: Function): string {
+        return this.getModelMetadata(model)?.tableName || '';
+    }
+
+    /**
+     * Gets the column configuration for a given model class.
+     * @param model - The class constructor for the model.
+     * @returns Record of column names to their configuration.
+     */
+    static getColumns(model: Function): Record<string, ColumnConfig> {
+        return this.getModelMetadata(model)?.columns || {};
+    }
+
+    /**
+     * Collects validation rules for each column of a given model.
+     * @param model - The class constructor for the model.
+     * @returns An object mapping column names to an array of validation rule names.
+     */
+    static getValidators(model: Function): Record<string, string[]> {
+        const columns = this.getModelMetadata(model)?.columns || {};
+        const validators: Record<string, string[]> = {};
+        for (const [key, col] of Object.entries(columns)) {
+            const rules: string[] = [];
+            if (col.required) rules.push('required');
+            if (col.unique) rules.push('unique');
+            validators[key] = rules;
+        }
+        return validators;
+    }
+
+    /**
+     * Gets the relationship configuration for a given model class.
+     * @param model - The class constructor for the model.
+     * @returns Record of property names to their relation configuration.
+     */
+    static getRelations(model: Function): Record<string, RelationConfig> {
+        const relations = this.getModelMetadata(model)?.relations || [];
+        const result: Record<string, RelationConfig> = {};
+        for (const rel of relations) {
+            result[rel.property] = rel;
+        }
+        return result;
+    }
+
+    /**
+     * Finds the soft delete field, if any, for a given model class.
+     * @param model - The class constructor for the model.
+     * @returns The key of the soft delete field, or null if not found.
+     */
+    static getSoftDeleteField(model: Function): string | null {
+        const columns = this.getModelMetadata(model)?.columns || {};
+        for (const [key, col] of Object.entries(columns)) {
+            if (col.softDelete) return key;
+        }
+        return null;
+    }
+
+    /**
+     * Checks if the model is versioned.
+     * @param model - The class constructor for the model.
+     * @returns True if versioned, false otherwise.
+     */
+    static isVersioned(model: Function): boolean {
+        return !!this.getModelMetadata(model)?.versioned;
+    }
+
+    /**
+     * Gets custom query scopes for a given model class.
+     * @param model - The class constructor for the model.
+     * @returns Record of scope names to scope functions.
+     */
+    static getScopes(model: Function): Record<string, (qb: QueryBuilder<any>, ...args: any[]) => QueryBuilder<any>> {
+        return this.getModelMetadata(model)?.scopes || {};
+    }
+}
+
+/**
+ * Programmatically defines a model and stores its metadata.
+ * @param config - The model configuration object.
+ * @returns The dynamically created model class.
+ */
+export function defineModel(config: ModelConfig) {
+    class Model {
+        /**
+         * Constructs a model instance from plain data.
+         * @param data - The plain object to assign properties from.
+         */
+        constructor(data: any) {
+            Object.assign(this, data);
+        }
+    }
+
+    // Store metadata
+    MetadataStorage.setModelMetadata(Model, {
+        tableName: config.tableName,
+        versioned: config.versioned || false,
+        softDelete: config.softDelete || false,
+        columns: config.columns,
+        relations: config.relations || [],
+        scopes: config.scopes || {},
+    });
+
+    return Model;
+}

package/package.json

@@ -1,19 +1,13 @@
 {
   "name": "stabilize-orm",
-  "version": "1.2.0",
+  "version": "1.3.2",
   "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/query-builder.ts

@@ -6,6 +6,8 @@
 
 import { DBClient } from "./client";
 import { Cache } from "./cache";
+import { MetadataStorage } from "./model";
+import { StabilizeError } from "./types";
 
 /**
  * A fluent interface for building SQL SELECT queries.
@@ -125,7 +127,7 @@ export class QueryBuilder<T> {
    */
   build(): { query: string; params: any[] } {
     let query = `SELECT ${this.selectFields.join(", ")} FROM ${this.table}`;
-    
+
     if (this.joins.length > 0) {
       query += " " + this.joins.join(" ");
     }
@@ -166,7 +168,7 @@ export class QueryBuilder<T> {
     cacheKey?: string,
   ): Promise<T[]> {
     const { query, params } = this.build();
-    
+
     // Attempt to retrieve from cache first (cache-aside read)
     if (cache && cacheKey) {
       const cached = await cache.get<T[]>(cacheKey);
@@ -178,9 +180,30 @@ export class QueryBuilder<T> {
 
     // Store the database results in the cache for future requests
     if (cache && cacheKey && results.length > 0) {
-      await cache.set(cacheKey, results, 60); 
+      await cache.set(cacheKey, results, 60);
     }
-    
+
     return results;
   }
+
+  /**
+   * Applies a named scope to the current query builder.
+   *
+   * This method looks up a scope function by name for the current model (based on the table name),
+   * then invokes the scope function with the query builder and any additional arguments.
+   *
+   * @param {string} name - The name of the scope to apply.
+   * @param {...any} args - Additional arguments to pass to the scope function.
+   * @throws {StabilizeError} If no model is found for the current table, or if the specified scope does not exist.
+   * @returns {QueryBuilder<T>} The query builder instance after applying the scope.
+   */
+  scope(name: string, ...args: any[]): QueryBuilder<T> {
+    const model = Object.values(MetadataStorage['models']).find(m => m.tableName === this.table)?.constructor;
+    if (!model) throw new StabilizeError(`Model for table ${this.table} not found`, "SCOPE_ERROR");
+    const scopes = MetadataStorage.getScopes(model);
+    const scopeFn = scopes[name];
+    if (!scopeFn) throw new StabilizeError(`Scope ${name} not found`, "SCOPE_ERROR");
+    return scopeFn(this, ...args);
+  }
+  
 }

package/repository.ts

@@ -9,24 +9,17 @@ 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,
-  VersionedKey,
-} 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`.
  * This class abstracts the database interactions for a specific model,
@@ -57,7 +50,7 @@ export class Repository<T> {
   /**
    * 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.
    */
@@ -69,14 +62,30 @@ 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 = !!Reflect.getMetadata(VersionedKey, model);
+    this.versioned = MetadataStorage.isVersioned(model);
     this.historyTable = `${this.table}_history`;
   }
 
@@ -93,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>) {
@@ -112,13 +121,13 @@ 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').
-  */
+   * 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();
+      await hook.callback(entity);
     }
   }
 
@@ -139,6 +148,21 @@ export class Repository<T> {
     return qb;
   }
 
+    /**
+   * Applies a custom scope to the query for the repository's table.
+   * @param name The name of the scope to apply.
+   * @param args Optional arguments to pass to the scope function.
+   * @returns A `QueryBuilder` instance with the scope applied.
+   * @example
+   * ```
+   * const activeUsers = await userRepository.scope('active').execute(client);
+   * ```
+   */
+  scope(name: string, ...args: any[]): QueryBuilder<T> {
+    this.logger.logDebug(`Applying scope ${name} to ${this.table}`);
+    return this.find().scope(name, ...args);
+  }
+
   /**
    * Finds a single record by its primary key (id).
    * @param id The ID of the record to find.
@@ -173,8 +197,8 @@ export class Repository<T> {
   }
 
   /**
- * Snapshot query: get record as it was at a point in time.
- */
+   * Snapshot query: get record as it was at a point in time.
+   */
   async asOf(
     id: number | string,
     asOfDate: Date,
@@ -190,8 +214,8 @@ export class Repository<T> {
   }
 
   /**
- * Get all history for a record.
- */
+   * Get all history for a record.
+   */
   async history(
     id: number | string,
     _client?: DBClient
@@ -204,8 +228,6 @@ export class Repository<T> {
     );
   }
 
-
-
   /**
    * Rollback a record to a previous version.
    */
@@ -237,21 +259,12 @@ export class Repository<T> {
     });
   }
 
-
   /**
    * Writes a versioned history row for the entity to the history table.
-   *
-   * This method maps entity property keys to their corresponding SQL column names
-   * (as defined in metadata) to ensure that inserts match the schema for all supported
-   * databases (Postgres, MySQL, SQLite).
-   *
-   * This function works for Postgres, MySQL, and SQLite, and uses positional parameters
-   * (properly formatted for the target database) for safety and compatibility.
-   *
-   * @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")
+   * @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,
@@ -261,11 +274,9 @@ export class Repository<T> {
   ) {
     if (!this.versioned) return;
 
-    // Get property keys and corresponding SQL column names
     const propertyKeys = Object.keys(this.columns);
     const sqlColumnNames = propertyKeys.map((k) => this.columns[k]!.name);
 
-    // Build historyColumns using SQL column names
     const historyColumns = [
       ...sqlColumnNames,
       "operation",
@@ -276,9 +287,7 @@ export class Repository<T> {
       "modified_at"
     ];
 
-    // Map values from entity using property keys
     const values = propertyKeys.map((k) => entity[k]);
-
     const params = [
       ...values,
       operation,
@@ -288,7 +297,7 @@ export class Repository<T> {
       user || "system",
       new Date()
     ];
-    // Database-agnostic placeholder formatting
+
     let placeholders: string;
     if (client.config.type === DBType.Postgres) {
       placeholders = params.map((_, i) => `$${i + 1}`).join(", ");
@@ -332,6 +341,7 @@ export class Repository<T> {
       return result;
     });
   }
+
   /**
    * @internal
    * The private implementation for creating a record, executed within a transaction.
@@ -407,7 +417,6 @@ export class Repository<T> {
     options: { relations?: string[]; batchSize?: number } = {},
   ): Promise<T[]> {
     return this.client.transaction(async (txClient) => {
-      // Prepare entity instances for hooks
       const preparedEntities = entities.map(data => {
         const instance = new (this as any).model();
         Object.assign(instance, data);
@@ -464,7 +473,6 @@ export class Repository<T> {
       );
 
       if (dbType === DBType.Postgres) {
-        // PostgreSQL: numbered placeholders ($1, $2, ...)
         let paramIdx = 1;
         const valuePlaceholders = batch
           .map(
@@ -476,7 +484,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(
@@ -493,7 +500,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);
@@ -642,17 +648,14 @@ 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) {
-        // Find all IDs matching the where clause
         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) {
-          // Fetch record before update for versioning
           const before = await this.findOne(id, {}, client);
           if (!before) continue;
 
-          // Prepare instance for hooks
           const instance = new ((this as any).model || Object)();
           Object.assign(instance, before, update.set);
 
@@ -693,6 +696,7 @@ export class Repository<T> {
       `Bulk updated ${updates.length} ${this.table} entities in ${(performance.now() - start).toFixed(2)}ms`,
     );
   }
+
   /**
    * Performs an "update or insert" operation based on a set of unique keys.
    * @param entity The entity to upsert.
@@ -728,6 +732,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(", ");
@@ -737,7 +742,6 @@ export class Repository<T> {
     const insertParams = columns.map((k) => (entity as any)[k]);
     let params = [...insertParams, ...updateParams];
 
-    // Try to find the record before upsert
     let before: T | null = null;
     let isUpdate = false;
     if (this.versioned && keys.length > 0) {
@@ -751,7 +755,6 @@ export class Repository<T> {
       isUpdate = !!before;
     }
 
-    // Prepare instance for hooks
     const instance = new ((this as any).model || Object)();
     Object.assign(instance, before || {}, entity);
 
@@ -767,7 +770,7 @@ export class Repository<T> {
       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(", ");
@@ -799,13 +802,6 @@ export class Repository<T> {
       await this.runHooks(result, "afterSave");
     }
 
-    if (this.cache) {
-      await this.cache.invalidatePattern(`find:${this.table}:*`);
-      if (this.cache.getStrategy() === "write-through") {
-        await this.cache.set(`findOne:${this.table}:${id}`, [result], 60);
-      }
-    }
-
     if (this.versioned) {
       await this.writeHistory(
         { ...result, version: before ? ((before as any).version ? (before as any).version + 1 : 1) : 1 },
@@ -814,11 +810,19 @@ export class Repository<T> {
       );
     }
 
+    if (this.cache) {
+      await this.cache.invalidatePattern(`find:${this.table}:*`);
+      if (this.cache.getStrategy() === "write-through") {
+        await this.cache.set(`findOne:${this.table}:${id}`, [result], 60);
+      }
+    }
+
     this.logger.logDebug(
       `Upserted ${this.table} with ID ${id} in ${(performance.now() - start).toFixed(2)}ms`,
     );
     return result;
   }
+
   /**
    * Deletes a record by its ID. Performs a soft delete if enabled on the model.
    * @param id The ID of the record to delete.
@@ -929,6 +933,7 @@ export class Repository<T> {
       `Bulk deleted ${ids.length} ${this.table} entities in ${(performance.now() - start).toFixed(2)}ms`,
     );
   }
+
   /**
    * Recovers a soft-deleted record by its ID.
    * Throws an error if soft delete is not enabled on the model.
@@ -1014,7 +1019,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
@@ -1040,4 +1045,4 @@ export class Repository<T> {
         );
     }
   }
-}
+}

package/types.ts

@@ -42,6 +42,7 @@ export enum DataTypes {
   JSON,      // Maps to JSON, JSONB, or TEXT
   UUID,      // Maps to UUID or VARCHAR(36)
   BLOB,      // Maps to BYTEA or BLOB
+  
 }
 
 export interface DBConfig {