@open-core/framework 0.1.0-alpha.1

package/dist/server/templates/repository/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Repository Pattern Module
+ *
+ * Provides an abstract Repository base class for implementing
+ * the Repository Pattern with type-safe CRUD operations.
+ *
+ * @example
+ * ```typescript
+ * import { Repository, FindOptions } from '@open-core/framework/server'
+ * import type { DatabaseContract } from '@open-core/framework/server'
+ *
+ * interface User {
+ *   id: number
+ *   name: string
+ *   email: string
+ *   active: boolean
+ * }
+ *
+ * class UserRepository extends Repository<User> {
+ *   protected tableName = 'users'
+ *
+ *   constructor(db: DatabaseContract) {
+ *     super(db)
+ *   }
+ *
+ *   protected toEntity(row: any): User {
+ *     return {
+ *       id: row.id,
+ *       name: row.name,
+ *       email: row.email,
+ *       active: Boolean(row.active)
+ *     }
+ *   }
+ *
+ *   protected toRow(entity: User): Record<string, any> {
+ *     return {
+ *       id: entity.id,
+ *       name: entity.name,
+ *       email: entity.email,
+ *       active: entity.active ? 1 : 0
+ *     }
+ *   }
+ *
+ *   // Custom methods
+ *   async findByEmail(email: string): Promise<User | null> {
+ *     return this.findOne({ email })
+ *   }
+ *
+ *   async findActive(options?: FindOptions<User>): Promise<User[]> {
+ *     const { data } = await this.findMany({ active: true }, options)
+ *     return data
+ *   }
+ * }
+ * ```
+ */
+export type { OrderDirection, FindOptions, FindManyResult, WhereCondition, } from './repository.types';
+export { Repository } from './repository.contract';

package/dist/server/templates/repository/index.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Repository Pattern Module
+ *
+ * Provides an abstract Repository base class for implementing
+ * the Repository Pattern with type-safe CRUD operations.
+ *
+ * @example
+ * ```typescript
+ * import { Repository, FindOptions } from '@open-core/framework/server'
+ * import type { DatabaseContract } from '@open-core/framework/server'
+ *
+ * interface User {
+ *   id: number
+ *   name: string
+ *   email: string
+ *   active: boolean
+ * }
+ *
+ * class UserRepository extends Repository<User> {
+ *   protected tableName = 'users'
+ *
+ *   constructor(db: DatabaseContract) {
+ *     super(db)
+ *   }
+ *
+ *   protected toEntity(row: any): User {
+ *     return {
+ *       id: row.id,
+ *       name: row.name,
+ *       email: row.email,
+ *       active: Boolean(row.active)
+ *     }
+ *   }
+ *
+ *   protected toRow(entity: User): Record<string, any> {
+ *     return {
+ *       id: entity.id,
+ *       name: entity.name,
+ *       email: entity.email,
+ *       active: entity.active ? 1 : 0
+ *     }
+ *   }
+ *
+ *   // Custom methods
+ *   async findByEmail(email: string): Promise<User | null> {
+ *     return this.findOne({ email })
+ *   }
+ *
+ *   async findActive(options?: FindOptions<User>): Promise<User[]> {
+ *     const { data } = await this.findMany({ active: true }, options)
+ *     return data
+ *   }
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Repository = void 0;
+// Contract
+var repository_contract_1 = require("./repository.contract");
+Object.defineProperty(exports, "Repository", { enumerable: true, get: function () { return repository_contract_1.Repository; } });

package/dist/server/templates/repository/repository.contract.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Repository Contract
+ *
+ * Abstract base class for implementing the Repository Pattern.
+ * Provides common CRUD operations with support for pagination, ordering, and field selection.
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: number
+ *   name: string
+ *   email: string
+ *   createdAt: Date
+ * }
+ *
+ * class UserRepository extends Repository<User> {
+ *   protected tableName = 'users'
+ *
+ *   constructor(db: DatabaseContract) {
+ *     super(db)
+ *   }
+ *
+ *   protected toEntity(row: any): User {
+ *     return {
+ *       id: row.id,
+ *       name: row.name,
+ *       email: row.email,
+ *       createdAt: new Date(row.created_at)
+ *     }
+ *   }
+ *
+ *   protected toRow(entity: User): Record<string, any> {
+ *     return {
+ *       id: entity.id,
+ *       name: entity.name,
+ *       email: entity.email,
+ *       created_at: entity.createdAt.toISOString()
+ *     }
+ *   }
+ * }
+ *
+ * // Usage
+ * const userRepo = new UserRepository(db)
+ * const user = await userRepo.findById(1)
+ * const users = await userRepo.findMany({ active: true }, { limit: 10, orderBy: { createdAt: 'DESC' } })
+ * ```
+ */
+import type { DatabaseContract } from '../../database/database.contract';
+import type { FindOptions, FindManyResult, WhereCondition, OrderDirection } from './repository.types';
+/**
+ * Abstract Repository base class
+ *
+ * Extend this class to create type-safe repositories for your entities.
+ *
+ * @typeParam TEntity - The entity type this repository manages
+ * @typeParam TId - The type of the primary key (defaults to number)
+ */
+export declare abstract class Repository<TEntity, TId = number> {
+    protected readonly db: DatabaseContract;
+    /**
+     * The database table name for this entity
+     */
+    protected abstract tableName: string;
+    /**
+     * The primary key column name (defaults to 'id')
+     */
+    protected primaryKey: string;
+    /**
+     * Creates a new repository instance
+     *
+     * @param db - The database contract/service to use for queries
+     */
+    constructor(db: DatabaseContract);
+    /**
+     * Maps a database row to an entity instance
+     *
+     * @param row - Raw database row
+     * @returns The mapped entity
+     */
+    protected abstract toEntity(row: any): TEntity;
+    /**
+     * Maps an entity to a database row
+     *
+     * @param entity - The entity to map
+     * @returns Object suitable for database operations
+     */
+    protected abstract toRow(entity: TEntity): Record<string, any>;
+    /**
+     * Find an entity by its primary key
+     *
+     * @param id - The primary key value
+     * @returns The entity or null if not found
+     *
+     * @example
+     * ```typescript
+     * const user = await userRepo.findById(1)
+     * if (user) {
+     *   console.log(user.name)
+     * }
+     * ```
+     */
+    findById(id: TId): Promise<TEntity | null>;
+    /**
+     * Find a single entity matching the given conditions
+     *
+     * @param where - Conditions to match (equality only)
+     * @returns The first matching entity or null
+     *
+     * @example
+     * ```typescript
+     * const user = await userRepo.findOne({ email: 'john@example.com' })
+     * ```
+     */
+    findOne(where: WhereCondition<TEntity>): Promise<TEntity | null>;
+    /**
+     * Find multiple entities with optional filtering, pagination, and ordering
+     *
+     * @param where - Optional conditions to filter by
+     * @param options - Query options (select, orderBy, limit, offset)
+     * @returns Result containing data array and optional total count
+     *
+     * @example
+     * ```typescript
+     * // Simple query
+     * const { data: users } = await userRepo.findMany({ active: true })
+     *
+     * // With pagination and ordering
+     * const result = await userRepo.findMany(
+     *   { role: 'admin' },
+     *   { limit: 10, offset: 20, orderBy: { createdAt: 'DESC' } }
+     * )
+     * console.log(`Page of ${result.data.length} admins`)
+     * ```
+     */
+    findMany(where?: WhereCondition<TEntity>, options?: FindOptions<TEntity>): Promise<FindManyResult<TEntity>>;
+    /**
+     * Count entities matching the given conditions
+     *
+     * @param where - Optional conditions to filter by
+     * @returns The count of matching entities
+     *
+     * @example
+     * ```typescript
+     * const activeCount = await userRepo.count({ active: true })
+     * ```
+     */
+    count(where?: WhereCondition<TEntity>): Promise<number>;
+    /**
+     * Save an entity (insert if new, update if exists)
+     *
+     * If the entity has a primary key value, it will be updated.
+     * Otherwise, a new record will be inserted.
+     *
+     * @param entity - The entity to save
+     * @returns The saved entity with updated ID (for inserts)
+     *
+     * @example
+     * ```typescript
+     * // Insert new user
+     * const newUser = await userRepo.save({ name: 'John', email: 'john@example.com' })
+     * console.log(newUser.id) // Generated ID
+     *
+     * // Update existing user
+     * user.name = 'John Doe'
+     * await userRepo.save(user)
+     * ```
+     */
+    save(entity: TEntity): Promise<TEntity>;
+    /**
+     * Delete an entity by its primary key
+     *
+     * @param id - The primary key of the entity to delete
+     * @returns true if deleted, false if not found
+     *
+     * @example
+     * ```typescript
+     * const deleted = await userRepo.delete(1)
+     * if (deleted) {
+     *   console.log('User deleted')
+     * }
+     * ```
+     */
+    delete(id: TId): Promise<boolean>;
+    /**
+     * Delete entities matching the given conditions
+     *
+     * @param where - Conditions to match for deletion
+     * @returns Number of deleted entities
+     *
+     * @example
+     * ```typescript
+     * const count = await userRepo.deleteWhere({ active: false })
+     * console.log(`Deleted ${count} inactive users`)
+     * ```
+     */
+    deleteWhere(where: WhereCondition<TEntity>): Promise<number>;
+    /**
+     * Update an entity by ID
+     */
+    protected update(id: TId, row: Record<string, any>): Promise<void>;
+    /**
+     * Insert a new row and return the inserted ID
+     */
+    protected insertRow(row: Record<string, any>): Promise<TId>;
+    /**
+     * Build SELECT clause from field selection
+     */
+    protected buildSelectClause(select?: (keyof TEntity)[]): string;
+    /**
+     * Build WHERE clause from conditions
+     */
+    protected buildWhereClause(where?: WhereCondition<TEntity>): {
+        clause: string;
+        params: any[];
+    };
+    /**
+     * Build ORDER BY clause from orderBy options
+     */
+    protected buildOrderClause(orderBy?: Partial<Record<keyof TEntity, OrderDirection>>): string;
+    /**
+     * Build LIMIT/OFFSET clause
+     */
+    protected buildLimitClause(limit?: number, offset?: number): string;
+}

package/dist/server/templates/repository/repository.contract.js

@@ -0,0 +1,342 @@
+"use strict";
+/**
+ * Repository Contract
+ *
+ * Abstract base class for implementing the Repository Pattern.
+ * Provides common CRUD operations with support for pagination, ordering, and field selection.
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: number
+ *   name: string
+ *   email: string
+ *   createdAt: Date
+ * }
+ *
+ * class UserRepository extends Repository<User> {
+ *   protected tableName = 'users'
+ *
+ *   constructor(db: DatabaseContract) {
+ *     super(db)
+ *   }
+ *
+ *   protected toEntity(row: any): User {
+ *     return {
+ *       id: row.id,
+ *       name: row.name,
+ *       email: row.email,
+ *       createdAt: new Date(row.created_at)
+ *     }
+ *   }
+ *
+ *   protected toRow(entity: User): Record<string, any> {
+ *     return {
+ *       id: entity.id,
+ *       name: entity.name,
+ *       email: entity.email,
+ *       created_at: entity.createdAt.toISOString()
+ *     }
+ *   }
+ * }
+ *
+ * // Usage
+ * const userRepo = new UserRepository(db)
+ * const user = await userRepo.findById(1)
+ * const users = await userRepo.findMany({ active: true }, { limit: 10, orderBy: { createdAt: 'DESC' } })
+ * ```
+ */
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Repository = void 0;
+/**
+ * Abstract Repository base class
+ *
+ * Extend this class to create type-safe repositories for your entities.
+ *
+ * @typeParam TEntity - The entity type this repository manages
+ * @typeParam TId - The type of the primary key (defaults to number)
+ */
+class Repository {
+    /**
+     * Creates a new repository instance
+     *
+     * @param db - The database contract/service to use for queries
+     */
+    constructor(db) {
+        this.db = db;
+        /**
+         * The primary key column name (defaults to 'id')
+         */
+        this.primaryKey = 'id';
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // CRUD Operations
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Find an entity by its primary key
+     *
+     * @param id - The primary key value
+     * @returns The entity or null if not found
+     *
+     * @example
+     * ```typescript
+     * const user = await userRepo.findById(1)
+     * if (user) {
+     *   console.log(user.name)
+     * }
+     * ```
+     */
+    async findById(id) {
+        const sql = `SELECT * FROM ${this.tableName} WHERE ${this.primaryKey} = ?`;
+        const row = await this.db.single(sql, [id]);
+        return row ? this.toEntity(row) : null;
+    }
+    /**
+     * Find a single entity matching the given conditions
+     *
+     * @param where - Conditions to match (equality only)
+     * @returns The first matching entity or null
+     *
+     * @example
+     * ```typescript
+     * const user = await userRepo.findOne({ email: 'john@example.com' })
+     * ```
+     */
+    async findOne(where) {
+        const { clause, params } = this.buildWhereClause(where);
+        const sql = `SELECT * FROM ${this.tableName}${clause} LIMIT 1`;
+        const row = await this.db.single(sql, params);
+        return row ? this.toEntity(row) : null;
+    }
+    /**
+     * Find multiple entities with optional filtering, pagination, and ordering
+     *
+     * @param where - Optional conditions to filter by
+     * @param options - Query options (select, orderBy, limit, offset)
+     * @returns Result containing data array and optional total count
+     *
+     * @example
+     * ```typescript
+     * // Simple query
+     * const { data: users } = await userRepo.findMany({ active: true })
+     *
+     * // With pagination and ordering
+     * const result = await userRepo.findMany(
+     *   { role: 'admin' },
+     *   { limit: 10, offset: 20, orderBy: { createdAt: 'DESC' } }
+     * )
+     * console.log(`Page of ${result.data.length} admins`)
+     * ```
+     */
+    async findMany(where, options) {
+        const selectClause = this.buildSelectClause(options === null || options === void 0 ? void 0 : options.select);
+        const { clause: whereClause, params } = this.buildWhereClause(where);
+        const orderClause = this.buildOrderClause(options === null || options === void 0 ? void 0 : options.orderBy);
+        const limitClause = this.buildLimitClause(options === null || options === void 0 ? void 0 : options.limit, options === null || options === void 0 ? void 0 : options.offset);
+        const sql = `SELECT ${selectClause} FROM ${this.tableName}${whereClause}${orderClause}${limitClause}`;
+        const rows = await this.db.query(sql, params);
+        const data = rows.map((row) => this.toEntity(row));
+        // If pagination is used, also get total count
+        let total;
+        if ((options === null || options === void 0 ? void 0 : options.limit) !== undefined) {
+            total = await this.count(where);
+        }
+        return { data, total };
+    }
+    /**
+     * Count entities matching the given conditions
+     *
+     * @param where - Optional conditions to filter by
+     * @returns The count of matching entities
+     *
+     * @example
+     * ```typescript
+     * const activeCount = await userRepo.count({ active: true })
+     * ```
+     */
+    async count(where) {
+        const { clause, params } = this.buildWhereClause(where);
+        const sql = `SELECT COUNT(*) as count FROM ${this.tableName}${clause}`;
+        const result = await this.db.scalar(sql, params);
+        return result !== null && result !== void 0 ? result : 0;
+    }
+    /**
+     * Save an entity (insert if new, update if exists)
+     *
+     * If the entity has a primary key value, it will be updated.
+     * Otherwise, a new record will be inserted.
+     *
+     * @param entity - The entity to save
+     * @returns The saved entity with updated ID (for inserts)
+     *
+     * @example
+     * ```typescript
+     * // Insert new user
+     * const newUser = await userRepo.save({ name: 'John', email: 'john@example.com' })
+     * console.log(newUser.id) // Generated ID
+     *
+     * // Update existing user
+     * user.name = 'John Doe'
+     * await userRepo.save(user)
+     * ```
+     */
+    async save(entity) {
+        const row = this.toRow(entity);
+        const id = row[this.primaryKey];
+        if (id !== undefined && id !== null) {
+            // Update existing entity
+            await this.update(id, row);
+            return entity;
+        }
+        else {
+            // Insert new entity
+            const insertedId = await this.insertRow(row);
+            // Return entity with the new ID
+            return this.toEntity(Object.assign(Object.assign({}, row), { [this.primaryKey]: insertedId }));
+        }
+    }
+    /**
+     * Delete an entity by its primary key
+     *
+     * @param id - The primary key of the entity to delete
+     * @returns true if deleted, false if not found
+     *
+     * @example
+     * ```typescript
+     * const deleted = await userRepo.delete(1)
+     * if (deleted) {
+     *   console.log('User deleted')
+     * }
+     * ```
+     */
+    async delete(id) {
+        const sql = `DELETE FROM ${this.tableName} WHERE ${this.primaryKey} = ?`;
+        const result = await this.db.execute(sql, [id]);
+        return result.affectedRows > 0;
+    }
+    /**
+     * Delete entities matching the given conditions
+     *
+     * @param where - Conditions to match for deletion
+     * @returns Number of deleted entities
+     *
+     * @example
+     * ```typescript
+     * const count = await userRepo.deleteWhere({ active: false })
+     * console.log(`Deleted ${count} inactive users`)
+     * ```
+     */
+    async deleteWhere(where) {
+        const { clause, params } = this.buildWhereClause(where);
+        if (!clause) {
+            throw new Error('deleteWhere requires at least one condition to prevent accidental full table deletion');
+        }
+        const sql = `DELETE FROM ${this.tableName}${clause}`;
+        const result = await this.db.execute(sql, params);
+        return result.affectedRows;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Protected Helper Methods
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Update an entity by ID
+     */
+    async update(id, row) {
+        const _a = row, _b = this.primaryKey, _ = _a[_b], updateData = __rest(_a, [typeof _b === "symbol" ? _b : _b + ""]);
+        const columns = Object.keys(updateData);
+        const setClause = columns.map((col) => `${col} = ?`).join(', ');
+        const values = columns.map((col) => updateData[col]);
+        const sql = `UPDATE ${this.tableName} SET ${setClause} WHERE ${this.primaryKey} = ?`;
+        await this.db.execute(sql, [...values, id]);
+    }
+    /**
+     * Insert a new row and return the inserted ID
+     */
+    async insertRow(row) {
+        const _a = row, _b = this.primaryKey, _ = _a[_b], insertData = __rest(_a, [typeof _b === "symbol" ? _b : _b + ""]);
+        const columns = Object.keys(insertData);
+        const placeholders = columns.map(() => '?').join(', ');
+        const values = columns.map((col) => insertData[col]);
+        const sql = `INSERT INTO ${this.tableName} (${columns.join(', ')}) VALUES (${placeholders})`;
+        const result = await this.db.insert(sql, values);
+        return result.insertId;
+    }
+    /**
+     * Build SELECT clause from field selection
+     */
+    buildSelectClause(select) {
+        if (!select || select.length === 0) {
+            return '*';
+        }
+        return select.map((field) => String(field)).join(', ');
+    }
+    /**
+     * Build WHERE clause from conditions
+     */
+    buildWhereClause(where) {
+        if (!where || Object.keys(where).length === 0) {
+            return { clause: '', params: [] };
+        }
+        const conditions = [];
+        const params = [];
+        for (const [key, value] of Object.entries(where)) {
+            if (value === null) {
+                conditions.push(`${key} IS NULL`);
+            }
+            else if (value === undefined) {
+                continue; // Skip undefined values
+            }
+            else {
+                conditions.push(`${key} = ?`);
+                params.push(value);
+            }
+        }
+        if (conditions.length === 0) {
+            return { clause: '', params: [] };
+        }
+        return {
+            clause: ` WHERE ${conditions.join(' AND ')}`,
+            params,
+        };
+    }
+    /**
+     * Build ORDER BY clause from orderBy options
+     */
+    buildOrderClause(orderBy) {
+        if (!orderBy || Object.keys(orderBy).length === 0) {
+            return '';
+        }
+        const orders = Object.entries(orderBy)
+            .filter(([_, direction]) => direction)
+            .map(([field, direction]) => `${field} ${direction}`);
+        if (orders.length === 0) {
+            return '';
+        }
+        return ` ORDER BY ${orders.join(', ')}`;
+    }
+    /**
+     * Build LIMIT/OFFSET clause
+     */
+    buildLimitClause(limit, offset) {
+        if (limit === undefined) {
+            return '';
+        }
+        let clause = ` LIMIT ${limit}`;
+        if (offset !== undefined && offset > 0) {
+            clause += ` OFFSET ${offset}`;
+        }
+        return clause;
+    }
+}
+exports.Repository = Repository;