mrepo-sql 1.0.0

package/README

@@ -0,0 +1,22 @@
+# m-sql
+
+
+## Install
+npm install m-sql
+
+## Usage
+```ts
+import { BaseRepository } from "mariadb-sp-repository";
+
+const repo = new BaseRepository({
+  host: "localhost",
+  user: "root",
+  password: "123",
+  database: "test"
+});
+
+const result = await repo.execSP("SP_Product_List", {
+  params: [1]
+});
+
+

package/dist/db/repo.d.ts

@@ -0,0 +1,44 @@
+import mariadb, { type PoolConfig } from "mariadb";
+import { ExecSPOptions } from "../interfaces/db.interface.js";
+export declare class BaseRepository {
+    private pool;
+    constructor(config: PoolConfig);
+    /**
+     * Executes a stored procedure with the given parameters and handling options.
+     * @OPTIONS {params: any[] | Record<string, any>, out: OutVariable[], plain: boolean, extract: boolean, order: string[], deleteExtra: boolean, fillWithNulls: boolean}
+     * @param spName The name of the stored procedure to call.
+     * @param options The options for the stored procedure execution.
+     * @returns The result of the stored procedure execution, typed as T.
+     */
+    execSP<T = any>(spName: string, { params, out, plain, extract, order, deleteExtra, fillWithNulls, }: ExecSPOptions): Promise<T>;
+    /**
+     * Retrieves all records from a view.
+     *
+     * @param viewName - The name of the view to query.
+     * @returns The result of the query.
+     */
+    view<T = any>(viewName: string): Promise<T[]>;
+    /**
+     * Executes a query with the given parameters.
+     *
+     * @param query - The SQL query to execute.
+     * @param params - The parameters to pass to the query.
+     * @returns The result of the query.
+     */
+    query<T = any>(query: string, params?: any[]): Promise<T[]>;
+    /**
+     * Connects to the database.
+     *
+     * @param onSuccess - Callback function to execute on success.
+     * @param onError - Callback function to execute on error.
+     */
+    connectDB(onSuccess?: () => void, onError?: (error: Error) => void): Promise<void>;
+    /**
+     * Closes the connection pool.
+     *
+     * @param onSuccess - Callback function to execute on success.
+     * @param onError - Callback function to execute on error.
+     */
+    closeDB(onSuccess?: () => void, onError?: (error: Error) => void): Promise<void>;
+    getOriginalPool(): Promise<mariadb.Pool>;
+}

package/dist/db/repo.js

@@ -0,0 +1,133 @@
+import mariadb from "mariadb";
+import { extractParams, flattenToObject, generateParams } from "../helpers/hepers.js";
+const defaultConfig = {
+    multipleStatements: true,
+};
+export class BaseRepository {
+    constructor(config) {
+        this.pool = mariadb.createPool({
+            ...defaultConfig,
+            ...config
+        });
+    }
+    /**
+     * Executes a stored procedure with the given parameters and handling options.
+     * @OPTIONS {params: any[] | Record<string, any>, out: OutVariable[], plain: boolean, extract: boolean, order: string[], deleteExtra: boolean, fillWithNulls: boolean}
+     * @param spName The name of the stored procedure to call.
+     * @param options The options for the stored procedure execution.
+     * @returns The result of the stored procedure execution, typed as T.
+     */
+    async execSP(spName, { params = [], out = [], plain = true, extract = false, order = [], deleteExtra = false, fillWithNulls = false, }) {
+        const endParams = extract && !Array.isArray(params) && params !== null
+            ? extractParams({ params: params, order, deleteExtra, fillWithNulls })
+            : (Array.isArray(params) ? params : []);
+        const placeholders = generateParams(endParams.length);
+        const callParams = [
+            ...(placeholders ? [placeholders] : []),
+            ...(out.length ? out.map(({ name }) => `@${name}`) : [])
+        ].join(',');
+        let conn;
+        try {
+            conn = await this.pool.getConnection();
+            const declareOutVars = out.length
+                ? out.map(({ name, type }) => `SET @${name} = CAST(NULL AS ${type ?? 'VARCHAR(255)'});`).join('\n')
+                : '';
+            const selectOuts = out.length
+                ? 'SELECT ' + out
+                    .map(({ name }) => `@${name}`)
+                    .join(',')
+                : '';
+            const query = `
+        ${declareOutVars}
+        CALL ${spName}(${callParams});
+        ${selectOuts}
+      `;
+            const res = await conn.query(query, endParams);
+            return (plain ? flattenToObject(res) : (res[0] ?? []));
+        }
+        catch (error) {
+            throw error;
+        }
+        finally {
+            if (conn)
+                conn.release();
+        }
+    }
+    /**
+     * Retrieves all records from a view.
+     *
+     * @param viewName - The name of the view to query.
+     * @returns The result of the query.
+     */
+    async view(viewName) {
+        let conn;
+        try {
+            conn = await this.pool.getConnection();
+            const result = await conn.query(`SELECT * FROM ${viewName}`);
+            return result;
+        }
+        catch (error) {
+            throw error;
+        }
+        finally {
+            if (conn)
+                conn.release();
+        }
+    }
+    /**
+     * Executes a query with the given parameters.
+     *
+     * @param query - The SQL query to execute.
+     * @param params - The parameters to pass to the query.
+     * @returns The result of the query.
+     */
+    async query(query, params) {
+        let conn;
+        try {
+            conn = await this.pool.getConnection();
+            const result = await conn.query(query, params);
+            return result;
+        }
+        catch (error) {
+            throw error;
+        }
+        finally {
+            if (conn)
+                conn.release();
+        }
+    }
+    /**
+     * Connects to the database.
+     *
+     * @param onSuccess - Callback function to execute on success.
+     * @param onError - Callback function to execute on error.
+     */
+    async connectDB(onSuccess, onError) {
+        try {
+            const conn = await this.pool.getConnection();
+            conn.release();
+            onSuccess?.();
+        }
+        catch (error) {
+            onError?.(error);
+            throw error;
+        }
+    }
+    /**
+     * Closes the connection pool.
+     *
+     * @param onSuccess - Callback function to execute on success.
+     * @param onError - Callback function to execute on error.
+     */
+    async closeDB(onSuccess, onError) {
+        return this.pool.end().then(() => {
+            onSuccess?.();
+        }).catch(error => {
+            onError?.(error);
+            throw error;
+        });
+    }
+    async getOriginalPool() {
+        return this.pool;
+    }
+}

package/dist/helpers/hepers.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Generates a string of comma-separated placeholders.
+ */
+export declare const generateParams: (n: number) => string;
+/**
+ * Flattens MariaDB query results into a single object.
+ */
+export declare const flattenToObject: (input: unknown) => Record<string, any>;
+interface ExtractParamsArgs {
+    params: Record<string, any>;
+    order: string[];
+    deleteExtra?: boolean;
+    fillWithNulls?: boolean;
+}
+/**
+ * Extracts and orders parameters from an object.
+ */
+export declare const extractParams: ({ params, order, deleteExtra, fillWithNulls }: ExtractParamsArgs) => any[];
+export {};

package/dist/helpers/hepers.js

@@ -0,0 +1,47 @@
+/**
+ * Generates a string of comma-separated placeholders.
+ */
+export const generateParams = (n) => Array.from({ length: n }, (_, i) => `?`).join(',');
+/**
+ * Flattens MariaDB query results into a single object.
+ */
+export const flattenToObject = (input) => {
+    const result = {};
+    function helper(item) {
+        if (Array.isArray(item)) {
+            item.forEach(inner => helper(inner));
+        }
+        else if (item !== null && typeof item === 'object') {
+            Object.entries(item).forEach(([key, value]) => {
+                result[key] = value;
+            });
+        }
+    }
+    helper(input);
+    delete result.affectedRows;
+    delete result.insertId;
+    delete result.warningStatus;
+    return result;
+};
+/**
+ * Extracts and orders parameters from an object.
+ */
+export const extractParams = ({ params, order, deleteExtra = false, fillWithNulls = false }) => {
+    const ordered = [];
+    order.forEach(key => {
+        if (params[key] === undefined) {
+            if (fillWithNulls) {
+                ordered.push(null);
+            }
+            return;
+        }
+        ordered.push(params[key]);
+    });
+    if (deleteExtra) {
+        return ordered;
+    }
+    const remaining = Object.keys(params)
+        .filter(key => !order.includes(key))
+        .map(key => params[key]);
+    return [...ordered, ...remaining];
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { BaseRepository } from "./db/repo.js";
+export { BaseRepository };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { BaseRepository } from "./db/repo.js";
+export { BaseRepository };

package/dist/interfaces/db.interface.d.ts

@@ -0,0 +1,20 @@
+export interface OutVariable {
+    name: string;
+    type?: string;
+}
+export interface ExecSPOptions {
+    /** Parameters to pass to the SP. Can be an array or an object if `extract` is true. */
+    params?: any[] | Record<string, any>;
+    /** Definition of output variables. */
+    out?: OutVariable[];
+    /** If true, flattens the result into a single object. */
+    plain?: boolean;
+    /** If true, extracts parameters from an object based on the `order` array. */
+    extract?: boolean;
+    /** The order of keys to extract from `params`. */
+    order?: string[];
+    /** If true, deletes extra parameters not specified in `order`. */
+    deleteExtra?: boolean;
+    /** If true, fills missing ordered parameters with null. */
+    fillWithNulls?: boolean;
+}

package/dist/interfaces/db.interface.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "mrepo-sql",
+  "version": "1.0.0",
+  "description": "With mrepo-sql, the ability to create repositories with features that improve code readability and project scalability is added.",
+  "license": "MIT",
+  "author": "daniel_hz",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "node src/index.ts",
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "mariadb": "^3.4.5"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3"
+  }
+}

package/src/db/repo.ts

@@ -0,0 +1,152 @@
+import mariadb, { type PoolConfig } from "mariadb";
+
+import { extractParams, flattenToObject, generateParams } from "../helpers/hepers.js";
+import { ExecSPOptions } from "../interfaces/db.interface.js";
+
+const defaultConfig = {
+    multipleStatements: true,
+}
+
+export class BaseRepository {
+    private pool: mariadb.Pool;
+    constructor(config: PoolConfig) {
+        this.pool = mariadb.createPool(
+            {
+                ...defaultConfig,
+                ...config
+            }
+        );
+    }
+
+    /**
+     * Executes a stored procedure with the given parameters and handling options.
+     * @OPTIONS {params: any[] | Record<string, any>, out: OutVariable[], plain: boolean, extract: boolean, order: string[], deleteExtra: boolean, fillWithNulls: boolean}
+     * @param spName The name of the stored procedure to call.
+     * @param options The options for the stored procedure execution.
+     * @returns The result of the stored procedure execution, typed as T.
+     */
+    async execSP<T = any>(spName: string, {
+        params = [],
+        out = [],
+        plain = true,
+        extract = false,
+        order = [],
+        deleteExtra = false,
+        fillWithNulls = false,
+    }: ExecSPOptions): Promise<T> {
+        const endParams = extract && !Array.isArray(params) && params !== null
+            ? extractParams({ params: params as Record<string, any>, order, deleteExtra, fillWithNulls })
+            : (Array.isArray(params) ? params : []);
+
+        const placeholders = generateParams(endParams.length);
+
+        const callParams = [
+            ...(placeholders ? [placeholders] : []),
+            ...(out.length ? out.map(({ name }) => `@${name}`) : [])
+        ].join(',');
+
+        let conn;
+        try {
+            conn = await this.pool.getConnection();
+
+            const declareOutVars = out.length
+                ? out.map(({ name, type }) => `SET @${name} = CAST(NULL AS ${type ?? 'VARCHAR(255)'});`).join('\n')
+                : '';
+
+            const selectOuts = out.length
+                ? 'SELECT ' + out
+                    .map(({ name }) => `@${name}`)
+                    .join(',')
+                : '';
+
+            const query = `
+        ${declareOutVars}
+        CALL ${spName}(${callParams});
+        ${selectOuts}
+      `;
+
+            const res = await conn.query(query, endParams);
+
+            return (plain ? flattenToObject(res) : (res[0] ?? [])) as T;
+        } catch (error) {
+            throw error;
+        } finally {
+            if (conn) conn.release();
+        }
+    }
+
+    /**
+     * Retrieves all records from a view.
+     * 
+     * @param viewName - The name of the view to query.
+     * @returns The result of the query.
+     */
+    async view<T = any>(viewName: string): Promise<T[]> {
+        let conn;
+        try {
+            conn = await this.pool.getConnection();
+            const result = await conn.query(`SELECT * FROM ${viewName}`);
+            return result as T[];
+        } catch (error) {
+            throw error;
+        } finally {
+            if (conn) conn.release();
+        }
+    }
+
+    /**
+     * Executes a query with the given parameters.
+     * 
+     * @param query - The SQL query to execute.
+     * @param params - The parameters to pass to the query.
+     * @returns The result of the query.
+     */
+    async query<T = any>(query: string, params?: any[]): Promise<T[]> {
+        let conn;
+        try {
+            conn = await this.pool.getConnection();
+            const result = await conn.query(query, params);
+            return result as T[];
+        } catch (error) {
+            throw error;
+        } finally {
+            if (conn) conn.release();
+        }
+    }
+
+    /**
+     * Connects to the database.
+     * 
+     * @param onSuccess - Callback function to execute on success.
+     * @param onError - Callback function to execute on error.
+     */
+    async connectDB(onSuccess?: () => void, onError?: (error: Error) => void) {
+        try {
+            const conn = await this.pool.getConnection();
+            conn.release();
+            onSuccess?.();
+        } catch (error) {
+            onError?.(error as Error);
+            throw error;
+        }
+    }
+
+    /**
+     * Closes the connection pool.
+     * 
+     * @param onSuccess - Callback function to execute on success.
+     * @param onError - Callback function to execute on error.
+     */
+    async closeDB(onSuccess?: () => void, onError?: (error: Error) => void) {
+        return this.pool.end().then(() => {
+            onSuccess?.();
+        }).catch(error => {
+            onError?.(error);
+            throw error;
+        });
+    }
+
+    async getOriginalPool() {
+        return this.pool;
+    }
+}

package/src/helpers/hepers.ts

@@ -0,0 +1,64 @@
+
+/**
+ * Generates a string of comma-separated placeholders.
+ */
+export const generateParams = (n: number): string => Array.from({ length: n }, (_, i) => `?`).join(',');
+
+/**
+ * Flattens MariaDB query results into a single object.
+ */
+export const flattenToObject = (input: unknown): Record<string, any> => {
+    const result: Record<string, any> = {};
+
+    function helper(item: unknown) {
+        if (Array.isArray(item)) {
+            item.forEach(inner => helper(inner));
+        } else if (item !== null && typeof item === 'object') {
+            Object.entries(item).forEach(([key, value]) => {
+                result[key] = value;
+            });
+        }
+    }
+
+    helper(input);
+    delete result.affectedRows;
+    delete result.insertId;
+    delete result.warningStatus;
+    return result;
+};
+
+interface ExtractParamsArgs {
+    params: Record<string, any>;
+    order: string[];
+    deleteExtra?: boolean;
+    fillWithNulls?: boolean;
+}
+
+/**
+ * Extracts and orders parameters from an object.
+ */
+export const extractParams = ({ params, order, deleteExtra = false, fillWithNulls = false }: ExtractParamsArgs): any[] => {
+    const ordered: any[] = [];
+    order.forEach(key => {
+        if (params[key] === undefined) {
+            if (fillWithNulls) {
+                ordered.push(null);
+            }
+            return;
+        }
+        ordered.push(params[key]);
+    });
+
+    if (deleteExtra) {
+        return ordered;
+    }
+
+    const remaining = Object.keys(params)
+        .filter(key => !order.includes(key))
+        .map(key => params[key]);
+
+    return [...ordered, ...remaining];
+};
+
+
+

package/src/index.ts

@@ -0,0 +1,3 @@
+import { BaseRepository } from "./db/repo.js";
+
+export { BaseRepository };

package/src/interfaces/db.interface.ts

@@ -0,0 +1,21 @@
+export interface OutVariable {
+    name: string;
+    type?: string;
+}
+
+export interface ExecSPOptions {
+    /** Parameters to pass to the SP. Can be an array or an object if `extract` is true. */
+    params?: any[] | Record<string, any>;
+    /** Definition of output variables. */
+    out?: OutVariable[];
+    /** If true, flattens the result into a single object. */
+    plain?: boolean;
+    /** If true, extracts parameters from an object based on the `order` array. */
+    extract?: boolean;
+    /** The order of keys to extract from `params`. */
+    order?: string[];
+    /** If true, deletes extra parameters not specified in `order`. */
+    deleteExtra?: boolean;
+    /** If true, fills missing ordered parameters with null. */
+    fillWithNulls?: boolean;
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+    "compilerOptions": {
+        "target": "ES2020",
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext",
+        "declaration": true,
+        "outDir": "dist",
+        "rootDir": "src",
+        "strict": true
+    },
+    "include": [
+        "src"
+    ]
+}