@neupgroup/mapper 1.2.3 → 1.2.4

package/dist/adapters/mysql-adapter.js

@@ -0,0 +1,166 @@
+/**
+ * MySQL Database Adapter
+ * Requires: npm install mysql2
+ */
+export class MySQLAdapter {
+    constructor(config) {
+        try {
+            // Dynamically import mysql2 to avoid bundling if not used
+            this.mysql = require('mysql2/promise');
+            this.pool = this.mysql.createPool({
+                host: config.host,
+                port: config.port || 3306,
+                user: config.user,
+                password: config.password,
+                database: config.database,
+                waitForConnections: true,
+                connectionLimit: config.connectionLimit || 10,
+                queueLimit: 0,
+                ssl: config.ssl,
+            });
+        }
+        catch (error) {
+            throw new Error(`Failed to initialize MySQL adapter: ${error.message}\n` +
+                `Make sure to install mysql2: npm install mysql2`);
+        }
+    }
+    buildWhereClause(options) {
+        const values = [];
+        const conditions = [];
+        // Handle raw WHERE clause
+        if (options.rawWhere) {
+            return { sql: options.rawWhere, values: [] };
+        }
+        // Build WHERE conditions from filters
+        for (const filter of options.filters) {
+            const { field, operator, value } = filter;
+            switch (operator) {
+                case '=':
+                case '>':
+                case '<':
+                case '>=':
+                case '<=':
+                case '!=':
+                    conditions.push(`\`${field}\` ${operator} ?`);
+                    values.push(value);
+                    break;
+                case 'LIKE':
+                    conditions.push(`\`${field}\` LIKE ?`);
+                    values.push(value);
+                    break;
+                case 'IN':
+                    conditions.push(`\`${field}\` IN (?)`);
+                    values.push(value);
+                    break;
+                default:
+                    conditions.push(`\`${field}\` = ?`);
+                    values.push(value);
+            }
+        }
+        const sql = conditions.length > 0 ? conditions.join(' AND ') : '';
+        return { sql, values };
+    }
+    async get(options) {
+        const connection = await this.pool.getConnection();
+        try {
+            const fields = options.fields.length > 0
+                ? options.fields.map(f => `\`${f}\``).join(', ')
+                : '*';
+            let sql = `SELECT ${fields} FROM \`${options.collectionName}\``;
+            const values = [];
+            // Add WHERE clause
+            const { sql: whereSql, values: whereValues } = this.buildWhereClause(options);
+            if (whereSql) {
+                sql += ` WHERE ${whereSql}`;
+                values.push(...whereValues);
+            }
+            // Add ORDER BY
+            if (options.sortBy) {
+                sql += ` ORDER BY \`${options.sortBy.field}\` ${options.sortBy.direction.toUpperCase()}`;
+            }
+            // Add LIMIT and OFFSET
+            if (options.limit !== null) {
+                sql += ` LIMIT ?`;
+                values.push(options.limit);
+            }
+            if (options.offset !== null) {
+                sql += ` OFFSET ?`;
+                values.push(options.offset);
+            }
+            const [rows] = await connection.execute(sql, values);
+            return rows;
+        }
+        finally {
+            connection.release();
+        }
+    }
+    async getOne(options) {
+        const results = await this.get({ ...options, limit: 1 });
+        return results[0] || null;
+    }
+    async getDocuments(options) {
+        return this.get(options);
+    }
+    async addDocument(collectionName, data) {
+        const connection = await this.pool.getConnection();
+        try {
+            const fields = Object.keys(data);
+            const placeholders = fields.map(() => '?').join(', ');
+            const values = Object.values(data);
+            const sql = `INSERT INTO \`${collectionName}\` (${fields.map(f => `\`${f}\``).join(', ')}) VALUES (${placeholders})`;
+            const [result] = await connection.execute(sql, values);
+            return String(result.insertId);
+        }
+        finally {
+            connection.release();
+        }
+    }
+    async updateDocument(collectionName, docId, data) {
+        const connection = await this.pool.getConnection();
+        try {
+            const fields = Object.keys(data);
+            const setClause = fields.map(f => `\`${f}\` = ?`).join(', ');
+            const values = [...Object.values(data), docId];
+            const sql = `UPDATE \`${collectionName}\` SET ${setClause} WHERE id = ?`;
+            await connection.execute(sql, values);
+        }
+        finally {
+            connection.release();
+        }
+    }
+    async deleteDocument(collectionName, docId) {
+        const connection = await this.pool.getConnection();
+        try {
+            const sql = `DELETE FROM \`${collectionName}\` WHERE id = ?`;
+            await connection.execute(sql, [docId]);
+        }
+        finally {
+            connection.release();
+        }
+    }
+    /**
+     * Close all connections in the pool
+     */
+    async close() {
+        await this.pool.end();
+    }
+    /**
+     * Execute a raw SQL query
+     */
+    async raw(sql, values) {
+        const connection = await this.pool.getConnection();
+        try {
+            const [results] = await connection.execute(sql, values || []);
+            return results;
+        }
+        finally {
+            connection.release();
+        }
+    }
+}
+/**
+ * Factory function to create MySQL adapter
+ */
+export function createMySQLAdapter(config) {
+    return new MySQLAdapter(config);
+}

package/dist/adapters/postgres-adapter.d.ts

@@ -0,0 +1,52 @@
+import type { DbAdapter, QueryOptions, DocumentData } from '../orm/types';
+export interface PostgreSQLConfig {
+    host: string;
+    port?: number;
+    user: string;
+    password: string;
+    database: string;
+    max?: number;
+    ssl?: boolean | {
+        rejectUnauthorized?: boolean;
+    };
+}
+/**
+ * PostgreSQL Database Adapter
+ * Requires: npm install pg
+ */
+export declare class PostgreSQLAdapter implements DbAdapter {
+    private pool;
+    private pg;
+    constructor(config: PostgreSQLConfig);
+    private buildWhereClause;
+    get(options: QueryOptions): Promise<DocumentData[]>;
+    getOne(options: QueryOptions): Promise<DocumentData | null>;
+    getDocuments(options: QueryOptions): Promise<DocumentData[]>;
+    addDocument(collectionName: string, data: DocumentData): Promise<string>;
+    updateDocument(collectionName: string, docId: string, data: DocumentData): Promise<void>;
+    deleteDocument(collectionName: string, docId: string): Promise<void>;
+    /**
+     * Close all connections in the pool
+     */
+    close(): Promise<void>;
+    /**
+     * Execute a raw SQL query
+     */
+    raw(sql: string, values?: any[]): Promise<any>;
+    /**
+     * Begin a transaction
+     */
+    beginTransaction(): Promise<any>;
+    /**
+     * Commit a transaction
+     */
+    commitTransaction(client: any): Promise<void>;
+    /**
+     * Rollback a transaction
+     */
+    rollbackTransaction(client: any): Promise<void>;
+}
+/**
+ * Factory function to create PostgreSQL adapter
+ */
+export declare function createPostgreSQLAdapter(config: PostgreSQLConfig): PostgreSQLAdapter;

package/dist/adapters/postgres-adapter.js

@@ -0,0 +1,204 @@
+/**
+ * PostgreSQL Database Adapter
+ * Requires: npm install pg
+ */
+export class PostgreSQLAdapter {
+    constructor(config) {
+        try {
+            // Dynamically import pg to avoid bundling if not used
+            this.pg = require('pg');
+            this.pool = new this.pg.Pool({
+                host: config.host,
+                port: config.port || 5432,
+                user: config.user,
+                password: config.password,
+                database: config.database,
+                max: config.max || 10,
+                ssl: config.ssl,
+            });
+        }
+        catch (error) {
+            throw new Error(`Failed to initialize PostgreSQL adapter: ${error.message}\n` +
+                `Make sure to install pg: npm install pg`);
+        }
+    }
+    buildWhereClause(options) {
+        const values = [];
+        const conditions = [];
+        let paramIndex = 1;
+        // Handle raw WHERE clause
+        if (options.rawWhere) {
+            return { sql: options.rawWhere, values: [] };
+        }
+        // Build WHERE conditions from filters
+        for (const filter of options.filters) {
+            const { field, operator, value } = filter;
+            switch (operator) {
+                case '=':
+                case '>':
+                case '<':
+                case '>=':
+                case '<=':
+                case '!=':
+                    conditions.push(`"${field}" ${operator} $${paramIndex}`);
+                    values.push(value);
+                    paramIndex++;
+                    break;
+                case 'LIKE':
+                case 'ILIKE':
+                    conditions.push(`"${field}" ${operator} $${paramIndex}`);
+                    values.push(value);
+                    paramIndex++;
+                    break;
+                case 'IN':
+                    conditions.push(`"${field}" = ANY($${paramIndex})`);
+                    values.push(Array.isArray(value) ? value : [value]);
+                    paramIndex++;
+                    break;
+                default:
+                    conditions.push(`"${field}" = $${paramIndex}`);
+                    values.push(value);
+                    paramIndex++;
+            }
+        }
+        const sql = conditions.length > 0 ? conditions.join(' AND ') : '';
+        return { sql, values };
+    }
+    async get(options) {
+        const client = await this.pool.connect();
+        try {
+            const fields = options.fields.length > 0
+                ? options.fields.map(f => `"${f}"`).join(', ')
+                : '*';
+            let sql = `SELECT ${fields} FROM "${options.collectionName}"`;
+            const values = [];
+            // Add WHERE clause
+            const { sql: whereSql, values: whereValues } = this.buildWhereClause(options);
+            if (whereSql) {
+                sql += ` WHERE ${whereSql}`;
+                values.push(...whereValues);
+            }
+            let paramIndex = values.length + 1;
+            // Add ORDER BY
+            if (options.sortBy) {
+                sql += ` ORDER BY "${options.sortBy.field}" ${options.sortBy.direction.toUpperCase()}`;
+            }
+            // Add LIMIT and OFFSET
+            if (options.limit !== null) {
+                sql += ` LIMIT $${paramIndex}`;
+                values.push(options.limit);
+                paramIndex++;
+            }
+            if (options.offset !== null) {
+                sql += ` OFFSET $${paramIndex}`;
+                values.push(options.offset);
+                paramIndex++;
+            }
+            const result = await client.query(sql, values);
+            return result.rows;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async getOne(options) {
+        const results = await this.get({ ...options, limit: 1 });
+        return results[0] || null;
+    }
+    async getDocuments(options) {
+        return this.get(options);
+    }
+    async addDocument(collectionName, data) {
+        var _a;
+        const client = await this.pool.connect();
+        try {
+            const fields = Object.keys(data);
+            const values = Object.values(data);
+            const placeholders = fields.map((_, i) => `$${i + 1}`).join(', ');
+            const sql = `INSERT INTO "${collectionName}" (${fields.map(f => `"${f}"`).join(', ')}) VALUES (${placeholders}) RETURNING id`;
+            const result = await client.query(sql, values);
+            return String(((_a = result.rows[0]) === null || _a === void 0 ? void 0 : _a.id) || '');
+        }
+        finally {
+            client.release();
+        }
+    }
+    async updateDocument(collectionName, docId, data) {
+        const client = await this.pool.connect();
+        try {
+            const fields = Object.keys(data);
+            const values = Object.values(data);
+            const setClause = fields.map((f, i) => `"${f}" = $${i + 1}`).join(', ');
+            const sql = `UPDATE "${collectionName}" SET ${setClause} WHERE id = $${fields.length + 1}`;
+            await client.query(sql, [...values, docId]);
+        }
+        finally {
+            client.release();
+        }
+    }
+    async deleteDocument(collectionName, docId) {
+        const client = await this.pool.connect();
+        try {
+            const sql = `DELETE FROM "${collectionName}" WHERE id = $1`;
+            await client.query(sql, [docId]);
+        }
+        finally {
+            client.release();
+        }
+    }
+    /**
+     * Close all connections in the pool
+     */
+    async close() {
+        await this.pool.end();
+    }
+    /**
+     * Execute a raw SQL query
+     */
+    async raw(sql, values) {
+        const client = await this.pool.connect();
+        try {
+            const result = await client.query(sql, values || []);
+            return result.rows;
+        }
+        finally {
+            client.release();
+        }
+    }
+    /**
+     * Begin a transaction
+     */
+    async beginTransaction() {
+        const client = await this.pool.connect();
+        await client.query('BEGIN');
+        return client;
+    }
+    /**
+     * Commit a transaction
+     */
+    async commitTransaction(client) {
+        try {
+            await client.query('COMMIT');
+        }
+        finally {
+            client.release();
+        }
+    }
+    /**
+     * Rollback a transaction
+     */
+    async rollbackTransaction(client) {
+        try {
+            await client.query('ROLLBACK');
+        }
+        finally {
+            client.release();
+        }
+    }
+}
+/**
+ * Factory function to create PostgreSQL adapter
+ */
+export function createPostgreSQLAdapter(config) {
+    return new PostgreSQLAdapter(config);
+}

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-import { Connections, SchemaManager } from './index';
+import { Connections, SchemaManager } from './index.js';
 export interface DatabaseConnectionConfig {
     name: string;
     type: 'mysql' | 'sql' | 'firestore' | 'mongodb';
@@ -55,7 +55,7 @@ export declare class ConfigBasedMapper {
     getSchemaManager(): SchemaManager;
     use(schemaName: string): any;
     schema(name: string): any;
-    connect(name: string, type: 'mysql' | 'sql' | 'firestore' | 'mongodb' | 'api', config: Record<string, any>): import("./mapper").Mapper;
+    connect(name: string, type: 'mysql' | 'sql' | 'firestore' | 'mongodb' | 'api', config: Record<string, any>): import("./mapper.js").Mapper;
     get(schemaName: string, filters?: Record<string, any>): Promise<Record<string, any>[]>;
     getOne(schemaName: string, filters?: Record<string, any>): Promise<Record<string, any> | null>;
     add(schemaName: string, data: Record<string, any>): Promise<any>;

package/dist/config.js

@@ -1,4 +1,4 @@
-import { createMapper } from './mapper';
+import { createMapper } from './mapper.js';
 export class ConfigLoader {
     static getInstance() {
         if (!ConfigLoader.instance) {

package/dist/connector.d.ts

@@ -0,0 +1,57 @@
+import { ConnectionType } from './index.js';
+/**
+ * A fluent builder for dynamic connections and ad-hoc queries.
+ * This allows defining connections with runtime values (variables, env, etc.)
+ * rather than relying solely on static configuration.
+ */
+export declare class Connector {
+    private _name;
+    private _type;
+    private _config;
+    private _collection;
+    /**
+     * Start a new connection definition.
+     * Usage: new Connector().name('myDb')...
+     */
+    constructor(name?: string);
+    /**
+     * Set the connection name.
+     */
+    name(n: string): this;
+    /**
+     * Set the connection type.
+     * Supported types: 'mysql', 'sql' (postgres/sqlite), 'mongodb', 'api'.
+     */
+    type(t: ConnectionType | string): this;
+    /**
+     * Generic configuration setup.
+     * Pass any key-value pairs required by the adapter.
+     */
+    config(c: Record<string, any>): this;
+    /**
+     * Set the Base URL (for API connections).
+     */
+    basePath(url: string): this;
+    /**
+     * Set the Connection URL/String (for DB connections).
+     */
+    url(url: string): this;
+    /**
+     * Define the table or collection to operate on.
+     * This registers the connection (if not already) and prepares a query.
+     */
+    table(tableName: string): import("./fluent-mapper.js").FluentQueryBuilder;
+    /**
+     * Alias for table() for API endpoints (subpath).
+     */
+    subpath(path: string): import("./fluent-mapper.js").FluentQueryBuilder;
+    /**
+     * Finalizes the connection registration and returns a query object.
+     */
+    private finalize;
+}
+/**
+ * Factory function for cleaner syntax:
+ * mapper('db').type('mysql')...
+ */
+export declare function mapper(name?: string): Connector;

package/dist/connector.js

@@ -0,0 +1,114 @@
+import { StaticMapper } from './fluent-mapper.js';
+/**
+ * A fluent builder for dynamic connections and ad-hoc queries.
+ * This allows defining connections with runtime values (variables, env, etc.)
+ * rather than relying solely on static configuration.
+ */
+export class Connector {
+    /**
+     * Start a new connection definition.
+     * Usage: new Connector().name('myDb')...
+     */
+    constructor(name) {
+        this._name = '';
+        this._type = 'api';
+        this._config = {};
+        this._collection = '';
+        if (name)
+            this._name = name;
+    }
+    /**
+     * Set the connection name.
+     */
+    name(n) {
+        this._name = n;
+        return this;
+    }
+    /**
+     * Set the connection type.
+     * Supported types: 'mysql', 'sql' (postgres/sqlite), 'mongodb', 'api'.
+     */
+    type(t) {
+        // Map 'database_sqlite' or others to supported types if necessary
+        if (t === 'database_sqlite')
+            t = 'sql';
+        this._type = t;
+        return this;
+    }
+    /**
+     * Generic configuration setup.
+     * Pass any key-value pairs required by the adapter.
+     */
+    config(c) {
+        this._config = { ...this._config, ...c };
+        return this;
+    }
+    /**
+     * Set the Base URL (for API connections).
+     */
+    basePath(url) {
+        this._config.baseUrl = url;
+        return this;
+    }
+    /**
+     * Set the Connection URL/String (for DB connections).
+     */
+    url(url) {
+        this._config.url = url;
+        return this;
+    }
+    /**
+     * Define the table or collection to operate on.
+     * This registers the connection (if not already) and prepares a query.
+     */
+    table(tableName) {
+        this._collection = tableName;
+        return this.finalize();
+    }
+    /**
+     * Alias for table() for API endpoints (subpath).
+     */
+    subpath(path) {
+        return this.table(path);
+    }
+    /**
+     * Finalizes the connection registration and returns a query object.
+     */
+    finalize() {
+        if (!this._name)
+            throw new Error('Connection name is required');
+        // Try to register connection, or use existing
+        let connInterface;
+        try {
+            connInterface = StaticMapper.makeConnection(this._name, this._type, this._config);
+        }
+        catch (e) {
+            if (e.message && (e.message.includes('already exists') || e.message.includes('ConnectionExistingError'))) {
+                connInterface = StaticMapper.connection(this._name);
+            }
+            else {
+                connInterface = StaticMapper.connection(this._name);
+            }
+        }
+        // Auto-define a schema for this table/collection if we are using one
+        const schemaName = `${this._name}_${this._collection}`;
+        try {
+            // Using the fluent interface to define schema if not exists
+            connInterface.schema(schemaName)
+                .collection(this._collection)
+                .structure({ '?field': 'any' });
+        }
+        catch (e) {
+            // Ignore if schema already exists
+        }
+        // Return the query builder
+        return StaticMapper.query(schemaName);
+    }
+}
+/**
+ * Factory function for cleaner syntax:
+ * mapper('db').type('mysql')...
+ */
+export function mapper(name) {
+    return new Connector(name);
+}

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+export declare class MapperError extends Error {
+    readonly code: string;
+    readonly hint?: string | undefined;
+    constructor(message: string, code: string, hint?: string | undefined);
+}
+export declare class AdapterMissingError extends MapperError {
+    constructor(connectionName: string);
+}
+export declare class UpdatePayloadMissingError extends MapperError {
+    constructor();
+}
+export declare class DocumentMissingIdError extends MapperError {
+    constructor(operation: string);
+}
+export declare class ConnectionExistingError extends MapperError {
+    constructor(name: string);
+}
+export declare class ConnectionUnknownError extends MapperError {
+    constructor(method: string, name: string);
+}
+export declare class SchemaExistingError extends MapperError {
+    constructor(name: string);
+}
+export declare class SchemaMissingError extends MapperError {
+    constructor(name: string);
+}
+export declare class SchemaConfigurationError extends MapperError {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,50 @@
+export class MapperError extends Error {
+    constructor(message, code, hint) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.name = this.constructor.name;
+        // Restore prototype chain for instanceof checks (TS workaround)
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class AdapterMissingError extends MapperError {
+    constructor(connectionName) {
+        super(`No adapter attached for connection '${connectionName}'.`, 'ADAPTER_MISSING', `Ensure you have registered an adapter for '${connectionName}'. You can use 'Mapper.connection().attachAdapter(...)'`);
+    }
+}
+export class UpdatePayloadMissingError extends MapperError {
+    constructor() {
+        super(`No update payload set for the query.`, 'UPDATE_PAYLOAD_MISSING', `You must call '.to({ ... })' with the data you want to update before executing '.update()' or '.updateOne()'.`);
+    }
+}
+export class DocumentMissingIdError extends MapperError {
+    constructor(operation) {
+        super(`Document is missing its 'id' field, which is required for '${operation}'.`, 'DOCUMENT_MISSING_ID', `Ensure that the documents you are trying to ${operation} have an 'id' property. If you fetched them, make sure 'id' was included in the fields.`);
+    }
+}
+export class ConnectionExistingError extends MapperError {
+    constructor(name) {
+        super(`Connection with name '${name}' already exists.`, 'CONNECTION_EXISTS', `Use a unique name for each connection or check if you are registering the same connection twice.`);
+    }
+}
+export class ConnectionUnknownError extends MapperError {
+    constructor(method, name) {
+        super(`Cannot ${method}: unknown connection '${name}'.`, 'CONNECTION_UNKNOWN', `Check if the connection '${name}' has been created using 'Mapper.connection().create(...)' or registered.`);
+    }
+}
+export class SchemaExistingError extends MapperError {
+    constructor(name) {
+        super(`Schema with name '${name}' already exists.`, 'SCHEMA_EXISTS', `Use a unique name for each schema.`);
+    }
+}
+export class SchemaMissingError extends MapperError {
+    constructor(name) {
+        super(`Unknown schema '${name}'.`, 'SCHEMA_UNKNOWN', `Ensure you have defined the schema '${name}' using 'Mapper.schema().create("${name}")...'`);
+    }
+}
+export class SchemaConfigurationError extends MapperError {
+    constructor(message) {
+        super(message, 'SCHEMA_CONFIG_ERROR', 'Ensure "connection" and "collection" are properly set using ".use({ connection, collection })" before defining structure.');
+    }
+}