accio-orm 0.1.0

package/dist/query/QueryBuilder.d.ts

@@ -0,0 +1,64 @@
+import type { Connection } from '../connection/Connection';
+import type { EntityMetadata } from '../metadata/types';
+import type { Repository } from '../repository/Repository';
+export declare class QueryBuilder<T> {
+    private repository;
+    private connection;
+    private metadata;
+    private conditions;
+    private limitValue?;
+    private offsetValue?;
+    private orderByColumn?;
+    private orderDirection;
+    constructor(repository: Repository<T>, connection: Connection, metadata: EntityMetadata, initialConditions?: Partial<T>);
+    /**
+     * Map a database row to an entity instance
+     * @private
+     */
+    private mapRowToEntity;
+    /**
+     * Add WHERE conditions (can be chained multiple times)
+     * Multiple calls to where() are combined with AND
+     */
+    where(conditions: Partial<T>): this;
+    /**
+     * Set the maximum number of results to return
+     */
+    limit(value: number): this;
+    /**
+     * Set the number of results to skip
+     */
+    offset(value: number): this;
+    /**
+     * Order results by a column
+     */
+    orderBy(column: string, direction?: 'ASC' | 'DESC'): this;
+    /**
+     * Execute the query and return all matching results
+     */
+    find(): Promise<T[]>;
+    /**
+     * Execute the query and return the first result (or null)
+     */
+    findOne(): Promise<T | null>;
+    /**
+     * Count the number of results that match the query
+     */
+    count(): Promise<number>;
+    /**
+     * Check if any results exist matching the query
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Build the SQL query and parameters
+     * @private
+     */
+    private buildSQL;
+    /**
+     * Get the SQL query that would be executed (for debugging)
+     */
+    toSQL(): {
+        sql: string;
+        params: unknown[];
+    };
+}

package/dist/query/QueryBuilder.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryBuilder = void 0;
+const entityMapper_1 = require("../utils/entityMapper");
+class QueryBuilder {
+    constructor(repository, connection, metadata, initialConditions) {
+        this.conditions = [];
+        this.orderDirection = 'ASC';
+        this.repository = repository;
+        this.connection = connection;
+        this.metadata = metadata;
+        if (initialConditions) {
+            this.conditions.push(initialConditions);
+        }
+    }
+    /**
+     * Map a database row to an entity instance
+     * @private
+     */
+    mapRowToEntity(row) {
+        // Get the entity class from the repository
+        const entityClass = this.repository.getEntityClass();
+        const entity = new entityClass();
+        // Map each column from the database row to the entity property
+        this.metadata.columns.forEach((col) => {
+            const value = row[col.columnName];
+            entity[col.propertyKey] = value;
+        });
+        return entity;
+    }
+    /**
+     * Add WHERE conditions (can be chained multiple times)
+     * Multiple calls to where() are combined with AND
+     */
+    where(conditions) {
+        this.conditions.push(conditions);
+        return this;
+    }
+    /**
+     * Set the maximum number of results to return
+     */
+    limit(value) {
+        if (value < 0) {
+            throw new Error('Limit must be a positive number');
+        }
+        this.limitValue = value;
+        return this;
+    }
+    /**
+     * Set the number of results to skip
+     */
+    offset(value) {
+        if (value < 0) {
+            throw new Error('Offset must be a positive number');
+        }
+        this.offsetValue = value;
+        return this;
+    }
+    /**
+     * Order results by a column
+     */
+    orderBy(column, direction = 'ASC') {
+        // Validate that the column exists
+        const columnMeta = this.metadata.columns.find((col) => col.propertyKey === column);
+        if (!columnMeta) {
+            throw new Error(`Column '${column}' does not exist on entity. ` +
+                `Available columns: ${this.metadata.columns.map((c) => c.propertyKey).join(', ')}`);
+        }
+        this.orderByColumn = columnMeta.columnName;
+        this.orderDirection = direction;
+        return this;
+    }
+    /**
+     * Execute the query and return all matching results
+     */
+    async find() {
+        const { sql, params } = this.buildSQL();
+        const result = await this.connection.query(sql, params);
+        // Get entity class from repository
+        const entityClass = this.repository.getEntityClass();
+        return (0, entityMapper_1.mapRowsToEntities)(result.rows, entityClass, this.metadata);
+    }
+    /**
+     * Execute the query and return the first result (or null)
+     */
+    async findOne() {
+        // Automatically add LIMIT 1 for performance
+        this.limit(1);
+        const results = await this.find();
+        return results[0] || null;
+    }
+    /**
+     * Count the number of results that match the query
+     */
+    async count() {
+        const { sql: baseSQL, params } = this.buildSQL(true); // true = count mode
+        // Replace SELECT * with SELECT COUNT(*)
+        const sql = baseSQL.replace(`SELECT * FROM ${this.metadata.tableName}`, `SELECT COUNT(*) as count FROM ${this.metadata.tableName}`);
+        const result = await this.connection.query(sql, params);
+        const row = result.rows[0];
+        return parseInt(String(row.count), 10);
+    }
+    /**
+     * Check if any results exist matching the query
+     */
+    async exists() {
+        const count = await this.count();
+        return count > 0;
+    }
+    /**
+     * Build the SQL query and parameters
+     * @private
+     */
+    buildSQL(skipLimitOffset = false) {
+        let sql = `SELECT * FROM ${this.metadata.tableName}`;
+        const params = [];
+        // build where clause;
+        if (this.conditions.length > 0) {
+            const whereClauses = [];
+            this.conditions.forEach((condition) => {
+                Object.entries(condition).forEach(([key, value]) => {
+                    // find column metadata for this property
+                    const column = this.metadata.columns.find((col) => col.propertyKey === key);
+                    if (!column) {
+                        throw new Error(`Property '${key}' does not exist on entity ${this.metadata.tableName}. ` +
+                            `Available properties: ${this.metadata.columns.map((c) => c.propertyKey).join(', ')}`);
+                    }
+                    // Hanfle different value types
+                    if (value === null) {
+                        whereClauses.push(`${column.columnName} IS NULL`);
+                    }
+                    else if (Array.isArray(value)) {
+                        // IN clause: WHERE column IN ($1, $2, $3)
+                        if (value.length === 0) {
+                            whereClauses.push('1 = 0');
+                        }
+                        else {
+                            const placeholders = value
+                                .map((v) => {
+                                params.push(v);
+                                return `$${params.length}`;
+                            })
+                                .join(', ');
+                            whereClauses.push(`${column.columnName} IN (${placeholders})`);
+                        }
+                    }
+                    else {
+                        // regular equality: WHERE column = $1
+                        params.push(value);
+                        whereClauses.push(`${column.columnName} = $${params.length}`);
+                    }
+                });
+            });
+            if (whereClauses.length > 0) {
+                sql += ` WHERE ${whereClauses.join(' AND ')}`;
+            }
+            // Add ORDER BY
+            if (this.orderByColumn) {
+                sql += ` ORDER BY ${this.orderByColumn} ${this.orderDirection}`;
+            }
+            // Add LIMIT and OFFSET (skip for count queries)
+            if (!skipLimitOffset) {
+                if (this.limitValue !== undefined) {
+                    sql += ` LIMIT ${this.limitValue}`;
+                }
+                if (this.offsetValue !== undefined) {
+                    sql += ` OFFSET ${this.offsetValue}`;
+                }
+            }
+        }
+        return { sql, params };
+    }
+    /**
+     * Get the SQL query that would be executed (for debugging)
+     */
+    toSQL() {
+        return this.buildSQL();
+    }
+}
+exports.QueryBuilder = QueryBuilder;

package/dist/repository/Repository.d.ts

@@ -0,0 +1,43 @@
+import type { Connection } from '@/connection/Connection';
+import type { EntityConstructor, EntityMetadata } from '@/metadata/types';
+import { QueryBuilder } from '@/query/QueryBuilder';
+export declare class Repository<T> {
+    private entityClass;
+    private connection;
+    private metadata;
+    constructor(entityClass: EntityConstructor, connection: Connection);
+    getConnection(): Connection;
+    getMetadata(): EntityMetadata;
+    getEntityClass(): EntityConstructor;
+    where(conditions: Partial<T>): QueryBuilder<T>;
+    findById(id: unknown): Promise<T | null>;
+    /**
+     * Find all entities
+     */
+    findAll(): Promise<T[]>;
+    save(entity: T): Promise<T>;
+    /**
+     * Insert a new entity
+     */
+    insert(entity: T): Promise<T>;
+    /**
+     * Update an existing entity
+     */
+    update(entity: T): Promise<T>;
+    /**
+     * Delete an entity
+     */
+    delete(entity: T): Promise<void>;
+    /**
+     * Delete by primary key
+     */
+    deleteById(id: unknown): Promise<void>;
+    /**
+     * Count all entities
+     */
+    count(): Promise<number>;
+    /**
+     * Check if entity exists by primary key
+     */
+    exists(id: unknown): Promise<boolean>;
+}

package/dist/repository/Repository.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Repository = void 0;
+const MetadataStorage_1 = require("@/metadata/MetadataStorage");
+const QueryBuilder_1 = require("@/query/QueryBuilder");
+const entityMapper_1 = require("../utils/entityMapper");
+class Repository {
+    constructor(entityClass, connection) {
+        this.entityClass = entityClass;
+        this.connection = connection;
+        // extract and cache metadata on construction
+        this.metadata = MetadataStorage_1.MetadataStorage.getEntityMetadata(entityClass);
+    }
+    getConnection() {
+        return this.connection;
+    }
+    getMetadata() {
+        return this.metadata;
+    }
+    getEntityClass() {
+        return this.entityClass;
+    }
+    where(conditions) {
+        return new QueryBuilder_1.QueryBuilder(this, this.connection, this.metadata, conditions);
+    }
+    async findById(id) {
+        if (!this.metadata.primaryColumn) {
+            throw new Error(`Entity ${this.entityClass.name} has no primary key`);
+        }
+        const primaryKey = this.metadata.primaryColumn.columnName;
+        const sql = `SELECT * FROM ${this.metadata.tableName} WHERE ${primaryKey} = $1`;
+        const result = await this.connection.query(sql, [id]);
+        if (result.rows.length === 0) {
+            return null;
+        }
+        return (0, entityMapper_1.mapRowToEntity)(result.rows[0], this.entityClass, this.metadata);
+    }
+    /**
+     * Find all entities
+     */
+    async findAll() {
+        const sql = `SELECT * FROM ${this.metadata.tableName}`;
+        const result = await this.connection.query(sql);
+        return (0, entityMapper_1.mapRowsToEntities)(result.rows, this.entityClass, this.metadata);
+    }
+    save(entity) {
+        if (!this.metadata.primaryColumn) {
+            throw new Error(`Entity ${this.entityClass.name} has no primary key`);
+        }
+        const primaryKey = this.metadata.primaryColumn.columnName;
+        const id = entity[primaryKey];
+        if (id !== undefined && id !== null) {
+            return this.update(entity);
+        }
+        else {
+            return this.insert(entity);
+        }
+    }
+    /**
+     * Insert a new entity
+     */
+    async insert(entity) {
+        const columns = this.metadata.columns.filter((col) => !col.isPrimary);
+        if (columns.length === 0) {
+            throw new Error(`Entity ${this.entityClass.name} has no columns to insert (only primary key)`);
+        }
+        const columnNames = columns.map((col) => col.columnName).join(', ');
+        const placeholders = columns.map((_, i) => `$${i + 1}`).join(', ');
+        const values = columns.map((col) => entity[col.propertyKey]);
+        const sql = `
+      INSERT INTO ${this.metadata.tableName} (${columnNames})
+      VALUES (${placeholders})
+      RETURNING *
+    `;
+        const result = await this.connection.query(sql, values);
+        return (0, entityMapper_1.mapRowToEntity)(result.rows[0], this.entityClass, this.metadata);
+    }
+    /**
+     * Update an existing entity
+     */
+    async update(entity) {
+        if (!this.metadata.primaryColumn) {
+            throw new Error(`Entity ${this.entityClass.name} has no primary key`);
+        }
+        const columns = this.metadata.columns.filter((col) => !col.isPrimary);
+        if (columns.length === 0) {
+            throw new Error(`Entity ${this.entityClass.name} has no columns to update (only primary key)`);
+        }
+        const primaryKey = this.metadata.primaryColumn.columnName;
+        const primaryValue = entity[this.metadata.primaryColumn.propertyKey];
+        // Build SET clause: column1 = $1, column2 = $2, ...
+        const setClause = columns
+            .map((col, i) => `${col.columnName} = $${i + 1}`)
+            .join(', ');
+        const values = columns.map((col) => entity[col.propertyKey]);
+        const sql = `
+      UPDATE ${this.metadata.tableName}
+      SET ${setClause}
+      WHERE ${primaryKey} = $${columns.length + 1}
+      RETURNING *
+    `;
+        const result = await this.connection.query(sql, [...values, primaryValue]);
+        if (result.rows.length === 0) {
+            throw new Error(`Update failed: Entity with ${primaryKey} = ${String(primaryValue)} not found`);
+        }
+        return (0, entityMapper_1.mapRowToEntity)(result.rows[0], this.entityClass, this.metadata);
+    }
+    /**
+     * Delete an entity
+     */
+    async delete(entity) {
+        if (!this.metadata.primaryColumn) {
+            throw new Error(`Entity ${this.entityClass.name} has no primary key`);
+        }
+        const primaryKey = this.metadata.primaryColumn.columnName;
+        const primaryValue = entity[this.metadata.primaryColumn.propertyKey];
+        if (primaryValue === undefined || primaryValue === null) {
+            throw new Error(`Cannot delete entity: primary key ${primaryKey} is ${primaryValue}`);
+        }
+        const sql = `DELETE FROM ${this.metadata.tableName} WHERE ${primaryKey} = $1`;
+        await this.connection.query(sql, [primaryValue]);
+    }
+    /**
+     * Delete by primary key
+     */
+    async deleteById(id) {
+        if (!this.metadata.primaryColumn) {
+            throw new Error(`Entity ${this.entityClass.name} has no primary key`);
+        }
+        const primaryKey = this.metadata.primaryColumn.columnName;
+        const sql = `DELETE FROM ${this.metadata.tableName} WHERE ${primaryKey} = $1`;
+        await this.connection.query(sql, [id]);
+    }
+    /**
+     * Count all entities
+     */
+    async count() {
+        const sql = `SELECT COUNT(*) as count FROM ${this.metadata.tableName}`;
+        const result = await this.connection.query(sql);
+        const row = result.rows[0];
+        return parseInt(String(row.count), 10);
+    }
+    /**
+     * Check if entity exists by primary key
+     */
+    async exists(id) {
+        if (!this.metadata.primaryColumn) {
+            throw new Error(`Entity ${this.entityClass.name} has no primary key`);
+        }
+        const primaryKey = this.metadata.primaryColumn.columnName;
+        const sql = `SELECT 1 FROM ${this.metadata.tableName} WHERE ${primaryKey} = $1 LIMIT 1`;
+        const result = await this.connection.query(sql, [id]);
+        return result.rows.length > 0;
+    }
+}
+exports.Repository = Repository;

package/dist/utils/entityMapper.d.ts

@@ -0,0 +1,9 @@
+import type { EntityConstructor, EntityMetadata } from '../metadata/types';
+/**
+ * Maps a database row to an entity instance
+ */
+export declare function mapRowToEntity<T>(row: Record<string, unknown>, entityClass: EntityConstructor, metadata: EntityMetadata): T;
+/**
+ * Maps multiple database rows to entity instances
+ */
+export declare function mapRowsToEntities<T>(rows: Record<string, unknown>[], entityClass: EntityConstructor, metadata: EntityMetadata): T[];

package/dist/utils/entityMapper.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapRowToEntity = mapRowToEntity;
+exports.mapRowsToEntities = mapRowsToEntities;
+/**
+ * Maps a database row to an entity instance
+ */
+function mapRowToEntity(row, entityClass, metadata) {
+    const entity = new entityClass();
+    // Map each column from the database row to the entity property
+    metadata.columns.forEach((col) => {
+        const value = row[col.columnName];
+        entity[col.propertyKey] = value;
+    });
+    return entity;
+}
+/**
+ * Maps multiple database rows to entity instances
+ */
+function mapRowsToEntities(rows, entityClass, metadata) {
+    return rows.map((row) => mapRowToEntity(row, entityClass, metadata));
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "accio-orm",
+  "version": "0.1.0",
+  "description": "The summoning charm for Postgres - A lightweight TypeScript ORM",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node examples/basic-usage.ts",
+    "lint": "eslint src/",
+    "lint:fix": "eslint . --fix",
+    "type-check": "tsc --noEmit",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:run": "vitest run",
+    "coverage": "vitest run --coverage",
+    "prepublishOnly": "pnpm run build && pnpm run test:run"
+  },
+  "keywords": [
+    "orm",
+    "postgres",
+    "postgresql",
+    "typescript",
+    "database",
+    "sql",
+    "data-mapper"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jidemusty/accio.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jidemusty/accio/issues"
+  },
+  "homepage": "https://github.com/jidemusty/accio#readme",
+  "author": "Mustapha Adubiagbe",
+  "license": "MIT",
+  "packageManager": "pnpm@10.27.0",
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^25.0.3",
+    "@types/pg": "^8.16.0",
+    "@typescript-eslint/eslint-plugin": "^8.51.0",
+    "@typescript-eslint/parser": "^8.51.0",
+    "@vitest/coverage-v8": "4.0.16",
+    "@vitest/ui": "^4.0.16",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "globals": "^17.0.0",
+    "pg": "^8.16.3",
+    "prettier": "^3.7.4",
+    "reflect-metadata": "^0.2.2",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.52.0",
+    "vitest": "^4.0.16"
+  },
+  "peerDependencies": {
+    "pg": "^8.0.0",
+    "reflect-metadata": "^0.2.2"
+  }
+}