accio-orm 0.1.0 → 0.1.1

package/README.md

@@ -4,6 +4,7 @@
 
 Accio is a lightweight, type-safe TypeScript ORM for PostgreSQL, built from first principles with a focus on simplicity and developer experience.
 
+[![npm version](https://badge.fury.io/js/accio-orm.svg)](https://www.npmjs.com/package/accio-orm)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 

package/dist/connection/Connection.d.ts

@@ -1,8 +1,10 @@
 import { type QueryResult } from 'pg';
+import { Logger } from '@/logger/Logger';
 import { Repository } from '../repository/Repository';
 import type { ConnectionConfig } from './types';
 export declare class Connection {
     private pool;
+    private logger;
     constructor(config: ConnectionConfig);
     /**
      * Get a repository for an entity class
@@ -22,6 +24,10 @@ export declare class Connection {
      * Test the connection
      */
     testConnection(): Promise<boolean>;
+    /**
+     * Get the logger instance
+     */
+    getLogger(): Logger;
 }
 /**
  * Factory function to create a connection

package/dist/connection/Connection.js

@@ -3,16 +3,41 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Connection = void 0;
 exports.connect = connect;
 const pg_1 = require("pg");
+const errors_1 = require("@/errors");
+const Logger_1 = require("@/logger/Logger");
+const validation_1 = require("@/validation");
 const Repository_1 = require("../repository/Repository");
 class Connection {
     constructor(config) {
-        this.pool = new pg_1.Pool({
-            host: config.host,
-            port: config.port ?? 5432,
-            database: config.database,
-            user: config.user,
-            password: config.password
-        });
+        // validate connection configuration
+        validation_1.ConnectionValidator.validate(config);
+        // initialize logger
+        this.logger = new Logger_1.Logger(config.logger);
+        try {
+            this.pool = new pg_1.Pool({
+                host: config.host,
+                port: config.port ?? 5432,
+                database: config.database,
+                user: config.user,
+                password: config.password
+            });
+            this.logger.info('Database connection pool created', {
+                host: config.host,
+                database: config.database,
+                port: config.database ?? 5432
+            });
+        }
+        catch (error) {
+            this.logger.error('Failed to create connection pool', error, {
+                host: config.host,
+                database: config.database
+            });
+            throw new errors_1.ConnectionError('Failed to create database connection pool', {
+                host: config.host,
+                database: config.database,
+                port: config.database ?? 5432
+            }, error);
+        }
     }
     /**
      * Get a repository for an entity class
@@ -26,19 +51,35 @@ class Connection {
      * Execute a raw SQL query
      */
     async query(sql, params) {
+        const startTime = Date.now();
         try {
-            return await this.pool.query(sql, params);
+            const result = await this.pool.query(sql, params);
+            const duration = Date.now() - startTime;
+            this.logger.query(sql, params, duration);
+            return result;
         }
         catch (error) {
-            // re-throw with context
-            throw new Error(`Query failed: ${sql}\nError: ${error instanceof Error ? error.message : String(error)}`);
+            const duration = Date.now() - startTime;
+            this.logger.error('Query execution failed', error, {
+                sql,
+                params,
+                duration
+            });
+            throw new errors_1.QueryError('Query Execution failed', sql, params, error);
         }
     }
     /**
      * Close all connections in the pool
      */
     async close() {
-        await this.pool.end();
+        try {
+            await this.pool.end();
+            this.logger.info('Database connection pool closed');
+        }
+        catch (error) {
+            this.logger.error('Failed to close connection pool', error);
+            throw new errors_1.ConnectionError('Failed to close database connection pool', undefined, error);
+        }
     }
     /**
      * Test the connection
@@ -46,13 +87,21 @@ class Connection {
     async testConnection() {
         try {
             await this.pool.query('SELECT 1');
+            this.logger.info('Connection test successful');
             return true;
         }
         catch (error) {
             console.log('Connection test failed:', error);
+            this.logger.error('Connection test failed', error);
             return false;
         }
     }
+    /**
+     * Get the logger instance
+     */
+    getLogger() {
+        return this.logger;
+    }
 }
 exports.Connection = Connection;
 /**

package/dist/connection/types.d.ts

@@ -1,7 +1,9 @@
+import type { LoggerConfig } from '@/logger';
 export interface ConnectionConfig {
     host: string;
     port?: number;
     database: string;
     user: string;
     password: string;
+    logger?: Partial<LoggerConfig>;
 }

package/dist/decorators/Column.d.ts

@@ -1,14 +1,15 @@
 import 'reflect-metadata';
+import type { PostgresType } from '@/types';
 export declare const COLUMNS_KEY: unique symbol;
 export interface ColumnOptions {
     name?: string;
-    type?: string;
+    type?: PostgresType | string;
     nullable?: boolean;
 }
 export interface ColumnMetadata {
     propertyKey: string;
     columnName: string;
-    type?: string;
+    type?: PostgresType | string;
     isNullable?: boolean;
     isPrimary: boolean;
 }

package/dist/decorators/PrimaryColumn.d.ts

@@ -6,4 +6,4 @@ import 'reflect-metadata';
  * @PrimaryColumn
  * id: number
  */
-export declare function PrimaryColumn(): (target: object, propertyKey: string | symbol) => void;
+export declare function PrimaryColumn(): (target: object | undefined, propertyKey: string | symbol) => void;

package/dist/decorators/PrimaryColumn.js

@@ -12,6 +12,9 @@ const Column_1 = require("./Column");
  */
 function PrimaryColumn() {
     return function (target, propertyKey) {
+        if (!target) {
+            throw new Error('PrimaryColumn decorator must be used on an instance property');
+        }
         const constructor = target.constructor;
         const columns = Reflect.getMetadata(Column_1.COLUMNS_KEY, constructor) ?? [];
         const key = typeof propertyKey === 'symbol' ? propertyKey.toString() : propertyKey;

package/dist/errors/AccioError.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Base error class for all Accio ORM errors
+ *
+ * Provides  context tracking, error chaining, and structured error information
+ * All Accio-specific errors extend from this class
+ *
+ * @example
+ * ```typescript
+ * throw new AccioError(
+ *   'Operation failed',
+ *   'OPERATION_ERROR',
+ *   { operation: 'INSERT', table: 'users' }
+ * )
+ * ```
+ */
+export declare class AccioError extends Error {
+    /**
+     * Error code for programmatic error handling
+     */
+    readonly code: string;
+    /**
+     * Additional context about the error
+     */
+    readonly context?: Record<string, unknown>;
+    /**
+     * Original error that caused this error (for error chaining)
+     */
+    readonly cause?: Error;
+    /**
+     * Causes a new AccioError
+     *
+     * @param message - Human-readable error message
+     * @param code - Machine-readable error code
+     * @param context - Additional structured context about the error
+     * @param cause - Original error that caused this error
+     */
+    constructor(message: string, code: string, context?: Record<string, unknown>, cause?: Error);
+    /**
+     * Serialize error to JSON for logging or transmission
+     *
+     * @param Structured error object
+     */
+    toJSON(): Record<string, unknown>;
+}

package/dist/errors/AccioError.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccioError = void 0;
+/**
+ * Base error class for all Accio ORM errors
+ *
+ * Provides  context tracking, error chaining, and structured error information
+ * All Accio-specific errors extend from this class
+ *
+ * @example
+ * ```typescript
+ * throw new AccioError(
+ *   'Operation failed',
+ *   'OPERATION_ERROR',
+ *   { operation: 'INSERT', table: 'users' }
+ * )
+ * ```
+ */
+class AccioError extends Error {
+    /**
+     * Causes a new AccioError
+     *
+     * @param message - Human-readable error message
+     * @param code - Machine-readable error code
+     * @param context - Additional structured context about the error
+     * @param cause - Original error that caused this error
+     */
+    constructor(message, code, context, cause) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.context = context;
+        this.cause = cause;
+        if ('captureStackTrace' in Error &&
+            typeof Error.captureStackTrace === 'function') {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Serialize error to JSON for logging or transmission
+     *
+     * @param Structured error object
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            context: this.context,
+            cause: this.cause?.message,
+            stack: this.stack
+        };
+    }
+}
+exports.AccioError = AccioError;

package/dist/errors/ConnectionError.d.ts

@@ -0,0 +1,27 @@
+import { AccioError } from './AccioError';
+/**
+ * Thrown when database connection operation fail
+ *
+ * This includes connection establishment failures, connection pool exhaustion,
+ * connection timeouts, and connection closing errors.
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof ConnectionError) {
+ *     console.error('Failed to connect to database:', error.context)
+ *   }
+ * }
+ * ```
+ */
+export declare class ConnectionError extends AccioError {
+    /**
+     * Creates a new QueryError
+     *
+     * @param message - Human-readable error message
+     * @param sql - The SQL query that failed (optional)
+     * @param params - The parameter bound to the query (optional)
+     * @param cause - Original error from the database driver
+     */
+    constructor(message: string, context?: Record<string, unknown>, cause?: Error);
+}

package/dist/errors/ConnectionError.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionError = void 0;
+const AccioError_1 = require("./AccioError");
+/**
+ * Thrown when database connection operation fail
+ *
+ * This includes connection establishment failures, connection pool exhaustion,
+ * connection timeouts, and connection closing errors.
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof ConnectionError) {
+ *     console.error('Failed to connect to database:', error.context)
+ *   }
+ * }
+ * ```
+ */
+class ConnectionError extends AccioError_1.AccioError {
+    /**
+     * Creates a new QueryError
+     *
+     * @param message - Human-readable error message
+     * @param sql - The SQL query that failed (optional)
+     * @param params - The parameter bound to the query (optional)
+     * @param cause - Original error from the database driver
+     */
+    constructor(message, context, cause) {
+        super(message, 'CONNECTION_ERROR', context, cause);
+    }
+}
+exports.ConnectionError = ConnectionError;

package/dist/errors/DatabaseError.d.ts

@@ -0,0 +1,35 @@
+import { AccioError } from './AccioError';
+/**
+ * Thrown for database-level errors
+ *
+ * This includes constraint violations, permission errors, database-specific
+ * errors, and other database-level failures that are not query syntax errors
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof DatabaseError) {
+ *     console.error('Database error:' error.constrait, error.detail)
+ *   }
+ * }
+ * ```
+ */
+export declare class DatabaseError extends AccioError {
+    /**
+     * The database constraint that was violated (if applicable)
+     */
+    readonly constraint?: string;
+    /**
+     * Detailed information from the database about the error
+     */
+    readonly detail?: string;
+    /**
+     * Creates a new DatabaseError
+     *
+     * @param message - Human-readable error message
+     * @param constraint - The constraint that was violated (optional)
+     * @param detail - Detailed information from the database (optional)
+     * @param cause - Original error from the database driver
+     */
+    constructor(message: string, constraint?: string, detail?: string, cause?: Error);
+}

package/dist/errors/DatabaseError.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatabaseError = void 0;
+const AccioError_1 = require("./AccioError");
+/**
+ * Thrown for database-level errors
+ *
+ * This includes constraint violations, permission errors, database-specific
+ * errors, and other database-level failures that are not query syntax errors
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof DatabaseError) {
+ *     console.error('Database error:' error.constrait, error.detail)
+ *   }
+ * }
+ * ```
+ */
+class DatabaseError extends AccioError_1.AccioError {
+    /**
+     * Creates a new DatabaseError
+     *
+     * @param message - Human-readable error message
+     * @param constraint - The constraint that was violated (optional)
+     * @param detail - Detailed information from the database (optional)
+     * @param cause - Original error from the database driver
+     */
+    constructor(message, constraint, detail, cause) {
+        super(message, 'DATABASE_ERROR', { constraint, detail }, cause);
+        this.constraint = constraint;
+        this.detail = detail;
+    }
+}
+exports.DatabaseError = DatabaseError;

package/dist/errors/QueryError.d.ts

@@ -0,0 +1,36 @@
+import { AccioError } from './AccioError';
+/**
+ * Thrown when validation fails
+ *
+ * This includes configuration validation, metadata validation, input validation,
+ * and SQL identifier validation. Used to prevent invalid operations before they
+ * reach the database.
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.error('Validation failed for ${error.field}:', error.value)
+ *   }
+ * }
+ * ```
+ */
+export declare class QueryError extends AccioError {
+    /**
+     * The SQL query that failed
+     */
+    readonly sql?: string;
+    /**
+     * The parameter that are bound to the query
+     */
+    readonly params?: unknown[];
+    /**
+     * Creates a new QueryError
+     *
+     * @param message - Human-readable error message
+     * @param sql - The SQL query that failed (optional)
+     * @param params - The parameter bound to the query (optional)
+     * @param cause - Original error from the database driver
+     */
+    constructor(message: string, sql?: string, params?: unknown[], cause?: Error);
+}

package/dist/errors/QueryError.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryError = void 0;
+const AccioError_1 = require("./AccioError");
+/**
+ * Thrown when validation fails
+ *
+ * This includes configuration validation, metadata validation, input validation,
+ * and SQL identifier validation. Used to prevent invalid operations before they
+ * reach the database.
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.error('Validation failed for ${error.field}:', error.value)
+ *   }
+ * }
+ * ```
+ */
+class QueryError extends AccioError_1.AccioError {
+    /**
+     * Creates a new QueryError
+     *
+     * @param message - Human-readable error message
+     * @param sql - The SQL query that failed (optional)
+     * @param params - The parameter bound to the query (optional)
+     * @param cause - Original error from the database driver
+     */
+    constructor(message, sql, params, cause) {
+        super(message, 'QUERY_ERROR', { sql, params }, cause);
+        this.sql = sql;
+        this.params = params;
+    }
+}
+exports.QueryError = QueryError;

package/dist/errors/ValidationError.d.ts

@@ -0,0 +1,35 @@
+import { AccioError } from './AccioError';
+/**
+ * Thrown when validation fails
+ *
+ * This includes configuration validation, metadata validation, input validation,
+ * and SQL identifier validation. Used to prevent invalid operations before they
+ * reach the database.
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.error('Validation failed for ${error.field}:', error.value)
+ *   }
+ * }
+ */
+export declare class ValidationError extends AccioError {
+    /**
+     * The field or property that failed validation
+     */
+    readonly field?: string;
+    /**
+     * The imvalid value that caused the validation error
+     */
+    readonly value?: unknown;
+    /**
+     * Creates a new ValidationError
+     *
+     * @param message - Human-readable error message describing the validation failure
+     * @param field - The field or property that failed validation (optional)
+     * @param value - The invalid value (optional, may be redacted for sensitive data)
+     * @param context - Additional context about the validation failure (optional)
+     */
+    constructor(message: string, field?: string, value?: unknown, context?: Record<string, unknown>);
+}

package/dist/errors/ValidationError.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = void 0;
+const AccioError_1 = require("./AccioError");
+/**
+ * Thrown when validation fails
+ *
+ * This includes configuration validation, metadata validation, input validation,
+ * and SQL identifier validation. Used to prevent invalid operations before they
+ * reach the database.
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.error('Validation failed for ${error.field}:', error.value)
+ *   }
+ * }
+ */
+class ValidationError extends AccioError_1.AccioError {
+    /**
+     * Creates a new ValidationError
+     *
+     * @param message - Human-readable error message describing the validation failure
+     * @param field - The field or property that failed validation (optional)
+     * @param value - The invalid value (optional, may be redacted for sensitive data)
+     * @param context - Additional context about the validation failure (optional)
+     */
+    constructor(message, field, value, context) {
+        super(message, 'VALIDATION_ERROR', { field, value, ...context });
+        this.field = field;
+        this.value = value;
+    }
+}
+exports.ValidationError = ValidationError;

package/dist/errors/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Error classes for Accio ORM
+ *
+ * All errors extend from AccioError, which provides error chaining,
+ * context tracking, and structured error information
+ */
+export { AccioError } from './AccioError';
+export { ConnectionError } from './ConnectionError';
+export { DatabaseError } from './DatabaseError';
+export { QueryError } from './QueryError';
+export { ValidationError } from './ValidationError';

package/dist/errors/index.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Error classes for Accio ORM
+ *
+ * All errors extend from AccioError, which provides error chaining,
+ * context tracking, and structured error information
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = exports.QueryError = exports.DatabaseError = exports.ConnectionError = exports.AccioError = void 0;
+var AccioError_1 = require("./AccioError");
+Object.defineProperty(exports, "AccioError", { enumerable: true, get: function () { return AccioError_1.AccioError; } });
+var ConnectionError_1 = require("./ConnectionError");
+Object.defineProperty(exports, "ConnectionError", { enumerable: true, get: function () { return ConnectionError_1.ConnectionError; } });
+var DatabaseError_1 = require("./DatabaseError");
+Object.defineProperty(exports, "DatabaseError", { enumerable: true, get: function () { return DatabaseError_1.DatabaseError; } });
+var QueryError_1 = require("./QueryError");
+Object.defineProperty(exports, "QueryError", { enumerable: true, get: function () { return QueryError_1.QueryError; } });
+var ValidationError_1 = require("./ValidationError");
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return ValidationError_1.ValidationError; } });

package/dist/index.d.ts

@@ -1,9 +1,12 @@
 export { connect, Connection } from './connection/Connection';
-export { ConnectionConfig } from './connection/types';
-export { Column, ColumnMetadata, ColumnOptions } from './decorators/Column';
+export type { ConnectionConfig } from './connection/types';
+export { Column, type ColumnMetadata, type ColumnOptions } from './decorators/Column';
 export { PrimaryColumn } from './decorators/PrimaryColumn';
 export { Table } from './decorators/Table';
 export { Repository } from './repository/Repository';
 export { QueryBuilder } from './query/QueryBuilder';
 export { MetadataStorage } from './metadata/MetadataStorage';
-export { EntityMetadata } from './metadata/types';
+export type { EntityMetadata } from './metadata/types';
+export { AccioError, ConnectionError, DatabaseError, QueryError, ValidationError } from './errors';
+export { Logger, type LoggerConfig, LogLevel } from './logger';
+export { getPostgresTypeForTS, isValidPostgresType, PostgresType } from './types';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MetadataStorage = exports.QueryBuilder = exports.Repository = exports.Table = exports.PrimaryColumn = exports.Column = exports.Connection = exports.connect = void 0;
+exports.PostgresType = exports.isValidPostgresType = exports.getPostgresTypeForTS = exports.LogLevel = exports.Logger = exports.ValidationError = exports.QueryError = exports.DatabaseError = exports.ConnectionError = exports.AccioError = exports.MetadataStorage = exports.QueryBuilder = exports.Repository = exports.Table = exports.PrimaryColumn = exports.Column = exports.Connection = exports.connect = void 0;
 // Connection
 var Connection_1 = require("./connection/Connection");
 Object.defineProperty(exports, "connect", { enumerable: true, get: function () { return Connection_1.connect; } });
@@ -21,3 +21,19 @@ Object.defineProperty(exports, "QueryBuilder", { enumerable: true, get: function
 // Metadata
 var MetadataStorage_1 = require("./metadata/MetadataStorage");
 Object.defineProperty(exports, "MetadataStorage", { enumerable: true, get: function () { return MetadataStorage_1.MetadataStorage; } });
+// Errors
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "AccioError", { enumerable: true, get: function () { return errors_1.AccioError; } });
+Object.defineProperty(exports, "ConnectionError", { enumerable: true, get: function () { return errors_1.ConnectionError; } });
+Object.defineProperty(exports, "DatabaseError", { enumerable: true, get: function () { return errors_1.DatabaseError; } });
+Object.defineProperty(exports, "QueryError", { enumerable: true, get: function () { return errors_1.QueryError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_1.ValidationError; } });
+// Logger
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return logger_1.Logger; } });
+Object.defineProperty(exports, "LogLevel", { enumerable: true, get: function () { return logger_1.LogLevel; } });
+// Types
+var types_1 = require("./types");
+Object.defineProperty(exports, "getPostgresTypeForTS", { enumerable: true, get: function () { return types_1.getPostgresTypeForTS; } });
+Object.defineProperty(exports, "isValidPostgresType", { enumerable: true, get: function () { return types_1.isValidPostgresType; } });
+Object.defineProperty(exports, "PostgresType", { enumerable: true, get: function () { return types_1.PostgresType; } });