ztechno_core 0.0.105 → 0.0.108

package/lib/core/orm/orm.js

@@ -0,0 +1,67 @@
+'use strict';
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.ZOrm =
+  exports.toDatetimeFromDateOnly =
+  exports.formatDatetime =
+  exports.toDatetime =
+  exports.toJsonColumn =
+    void 0;
+/**
+ * Safely converts a value to a JSON string for storage in a JSON column.
+ * Prevents the mysql driver from expanding plain objects into `key`=value pairs.
+ */
+function toJsonColumn(value) {
+  if (value == null) return null;
+  return typeof value === 'string' ? value : JSON.stringify(value);
+}
+exports.toJsonColumn = toJsonColumn;
+/**
+ * Converts an ISO 8601 date string (e.g. from Mollie API) to MySQL DATETIME format.
+ * Accepts `2026-02-26T00:47:04+00:00` → `2026-02-26 00:47:04`
+ */
+function toDatetime(value) {
+  if (value == null) return null;
+  const d = new Date(value);
+  if (isNaN(d.getTime())) return null;
+  return d.toISOString().slice(0, 19).replace('T', ' ');
+}
+exports.toDatetime = toDatetime;
+/**
+ * Converts a Date object to MySQL DATETIME format.
+ */
+function formatDatetime(value) {
+  return value.toISOString().slice(0, 19).replace('T', ' ');
+}
+exports.formatDatetime = formatDatetime;
+/**
+ * Converts a date-only string (e.g. `2026-02-26`) to MySQL DATETIME format.
+ */
+function toDatetimeFromDateOnly(value) {
+  if (value == null) return null;
+  return toDatetime(`${value}T00:00:00Z`);
+}
+exports.toDatetimeFromDateOnly = toDatetimeFromDateOnly;
+class ZOrm {
+  constructor(opt) {
+    this.alias = opt.alias;
+    this.sqlService = opt.sqlService;
+  }
+  async ensureTableExists() {
+    const exists = await this.checkTableExists();
+    if (!exists) {
+      await this.createTable();
+    }
+  }
+  async checkTableExists() {
+    const res = await this.sqlService.query(`
+      SELECT ENGINE, VERSION, CREATE_TIME FROM information_schema.tables
+      WHERE table_schema = '${this.sqlService.database}' AND table_name = '${this.alias}'
+      LIMIT 1
+    `);
+    return res.length > 0;
+  }
+  async createTable() {
+    throw new Error(`${this.alias} Create Table Statement Not Implemented!`);
+  }
+}
+exports.ZOrm = ZOrm;

package/lib/core/sql_service.d.ts

@@ -0,0 +1,195 @@
+import * as mysql from 'mysql';
+type ZOnErrorCallback = (err: mysql.MysqlError) => any;
+type ZOnLogCallback = (log: string) => any;
+export type ZSQLOptions = mysql.PoolConfig & {
+  dateStringTimezone?: string;
+  parseBooleans?: boolean;
+};
+/**
+ * A scoped transaction handle passed to the `transaction()` callback.
+ * All queries executed through this handle run on the same connection
+ * inside a single BEGIN / COMMIT / ROLLBACK block.
+ */
+export interface ZTransaction {
+  /** Run a raw query inside the transaction (no type conversions). */
+  query<T = any>(
+    sql: string,
+    params?:
+      | any[]
+      | {
+          [key: string]: any;
+        },
+  ): Promise<T[]>;
+  query(
+    sql: string,
+    params?:
+      | any[]
+      | {
+          [key: string]: any;
+        },
+  ): Promise<{
+    insertId: number;
+    affectedRows: number;
+  }>;
+  /** Run a query with automatic date/boolean conversions inside the transaction. */
+  exec<T = any>(opt: {
+    query: string;
+    params?:
+      | any[]
+      | {
+          [key: string]: any;
+        };
+  }): Promise<T[]>;
+  exec(opt: {
+    query: string;
+    params?:
+      | any[]
+      | {
+          [key: string]: any;
+        };
+  }): Promise<{
+    insertId: number;
+    affectedRows: number;
+  }>;
+}
+export declare class ZSQLService {
+  private options;
+  private pool;
+  private defaultPoolconfig;
+  private listeners;
+  private databaseName;
+  get database(): string;
+  /**
+   * Creates a new ZSQLService instance with a MySQL connection pool.
+   * @param options - MySQL pool configuration options including custom dateStringTimezone and parseBooleans settings
+   */
+  constructor(options: ZSQLOptions);
+  /**
+   * Registers an event listener for database errors or logs.
+   * @param eventName - The event type to listen for ('err' or 'log')
+   * @param listener - The callback function to execute when the event occurs
+   * @throws Error if the event name is not supported
+   */
+  on(eventName: 'err', listener: ZOnErrorCallback): void;
+  on(eventName: 'log', listener: ZOnLogCallback): void;
+  private triggerEvent;
+  private getPoolConnection;
+  /**
+   * Executes a SQL query with automatic type conversion for dates and booleans.
+   * Converts TINYINT(1) columns to booleans if parseBooleans option is enabled.
+   * Converts date strings to Date objects if dateStringTimezone option is set.
+   * @template T - The expected result type
+   * @param opt - Query options containing the SQL query string and optional parameters
+   * @param opt.query - The SQL query string to execute
+   * @param opt.params - Optional query parameters (array for positional, object for named parameters)
+   * @returns Promise resolving to query results with type conversions applied
+   */
+  exec(opt: {
+    query: string;
+    params?:
+      | any[]
+      | {
+          [key: string]: any;
+        };
+  }): Promise<{
+    insertId: number;
+    affectedRows: number;
+  }>;
+  exec<T = any>(opt: {
+    query: string;
+    params?:
+      | any[]
+      | {
+          [key: string]: any;
+        };
+  }): Promise<T[]>;
+  /**
+   * Legacy method to execute a SQL query. Uses uppercase property names for backwards compatibility.
+   * Applies date and boolean conversions if configured. Consider using exec() directly for new code.
+   * @template T - The expected result type
+   * @param opt - Query options
+   * @param opt.Query - The SQL query string to execute
+   * @param opt.Params - Named parameters for the query
+   * @returns Promise resolving to query results
+   */
+  fetch<T = any>(opt: {
+    Query: string;
+    Params:
+      | {
+          [key: string]: any;
+        }
+      | any[];
+  }): Promise<T[]>;
+  fetch<T = any>(
+    query: string,
+    params:
+      | {
+          [key: string]: any;
+        }
+      | any[],
+  ): Promise<T[]>;
+  /**
+   * Executes a SQL query without type conversions.
+   * Supports both positional (array) and named (object) parameters.
+   * @template T - The expected result type
+   * @param sql - The SQL query string to execute
+   * @param params - Optional query parameters (array for positional with ?, object for named with :key)
+   * @returns Promise resolving to query results or insert/update metadata
+   */
+  query(
+    sql: string,
+    params?:
+      | any[]
+      | {
+          [key: string]: any;
+        },
+  ): Promise<{
+    insertId: number;
+    affectedRows: number;
+  }>;
+  query<T = any>(
+    sql: string,
+    params?:
+      | any[]
+      | {
+          [key: string]: any;
+        },
+  ): Promise<T[]>;
+  private queryWithFields;
+  private formatQueryParams;
+  private isSqlDate;
+  private beginTransaction;
+  private commitTransaction;
+  private rollbackTransaction;
+  private queryOnConnection;
+  private queryOnConnectionWithFields;
+  private buildExecOnConnection;
+  /**
+   * Executes a callback inside a database transaction.
+   * Automatically calls BEGIN before and COMMIT after the callback.
+   * If the callback throws, the transaction is rolled back and the error is re-thrown.
+   *
+   * @template T - The return type of the callback
+   * @param fn - An async function that receives a {@link ZTransaction} handle
+   * @returns The value returned by `fn`
+   *
+   * @example
+   * ```ts
+   * const result = await sqlService.transaction(async (trx) => {
+   *   await trx.query('INSERT INTO orders (customer_id) VALUES (:id)', { id: 42 })
+   *   await trx.query('UPDATE inventory SET stock = stock - 1 WHERE product_id = :pid', { pid: 7 })
+   *   return 'done'
+   * })
+   * ```
+   */
+  transaction<T = void>(fn: (trx: ZTransaction) => Promise<T>): Promise<T>;
+  /**
+   * Changes the active database by closing the current connection pool and creating a new one.
+   * All active connections will be gracefully closed before switching.
+   * @param newDatabase - The name of the database to switch to
+   * @returns Promise that resolves when the database has been changed successfully
+   * @throws Error if the pool cannot be closed or new pool cannot be created
+   */
+  changeDatabase(newDatabase: string): Promise<void>;
+}
+export {};

package/lib/core/sql_service.js

@@ -0,0 +1,333 @@
+'use strict';
+var __createBinding =
+  (this && this.__createBinding) ||
+  (Object.create
+    ? function (o, m, k, k2) {
+        if (k2 === undefined) k2 = k;
+        var desc = Object.getOwnPropertyDescriptor(m, k);
+        if (!desc || ('get' in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+          desc = {
+            enumerable: true,
+            get: function () {
+              return m[k];
+            },
+          };
+        }
+        Object.defineProperty(o, k2, desc);
+      }
+    : function (o, m, k, k2) {
+        if (k2 === undefined) k2 = k;
+        o[k2] = m[k];
+      });
+var __setModuleDefault =
+  (this && this.__setModuleDefault) ||
+  (Object.create
+    ? function (o, v) {
+        Object.defineProperty(o, 'default', { enumerable: true, value: v });
+      }
+    : function (o, v) {
+        o['default'] = v;
+      });
+var __importStar =
+  (this && this.__importStar) ||
+  function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null)
+      for (var k in mod)
+        if (k !== 'default' && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+  };
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.ZSQLService = void 0;
+const mysql = __importStar(require('mysql'));
+class ZSQLService {
+  get database() {
+    return this.databaseName;
+  }
+  /**
+   * Creates a new ZSQLService instance with a MySQL connection pool.
+   * @param options - MySQL pool configuration options including custom dateStringTimezone and parseBooleans settings
+   */
+  constructor(options) {
+    this.options = options;
+    this.defaultPoolconfig = {
+      connectionLimit: 10,
+      timeout: 20000,
+      connectTimeout: 20000,
+      acquireTimeout: 20000,
+    };
+    this.listeners = { err: [], log: [] };
+    this.databaseName = options.database;
+    this.pool = mysql.createPool(Object.assign({}, this.defaultPoolconfig, options));
+    this.pool.on('connection', (connection) => {
+      // connection.config.queryFormat = function (query, values) {
+      // }
+      connection.on('error', (err) => {
+        this.triggerEvent('err', err);
+      });
+      connection.on('close', (err) => {
+        this.triggerEvent('err', err);
+      });
+    });
+  }
+  on(eventName, listener) {
+    if (!this.listeners.hasOwnProperty(eventName))
+      throw new Error(`EventName not supported for ZSqlService.on(${eventName}, ...)`);
+    this.listeners[eventName].push(listener);
+  }
+  triggerEvent(eventName, args) {
+    this.listeners[eventName].map((listener) => {
+      listener.apply(undefined, args);
+    });
+  }
+  getPoolConnection() {
+    return new Promise((resolve, reject) => {
+      this.pool.getConnection((err, con) => (err ? reject(err) : resolve(con)));
+    });
+  }
+  async exec(opt) {
+    const { results, fields } = await this.queryWithFields(opt.query, opt.params);
+    if (!Array.isArray(results)) {
+      return results;
+    }
+    if (!this.options.dateStringTimezone && !this.options.parseBooleans) {
+      return results;
+    }
+    // Build a set of column names that are TINYINT(1) for boolean conversion
+    const booleanColumns = new Set();
+    if (this.options.parseBooleans && fields) {
+      fields.forEach((field) => {
+        // Check if column is TINYINT(1) - type 1 is TINY, length 1 means TINYINT(1)
+        if (field.type === 1 && field.length === 1) {
+          booleanColumns.add(field.name);
+        }
+      });
+    }
+    return results.map((row) => {
+      Object.keys(row).map((key) => {
+        if (this.options.dateStringTimezone && this.isSqlDate(row[key])) {
+          row[key] = new Date(row[key] + this.options.dateStringTimezone);
+        }
+        if (this.options.parseBooleans && booleanColumns.has(key) && (row[key] === 0 || row[key] === 1)) {
+          row[key] = row[key] === 1;
+        }
+      });
+      return row;
+    });
+  }
+  async fetch(opt, params) {
+    if (typeof opt === 'string') {
+      return await this.exec({ query: opt, params });
+    }
+    return await this.exec({ query: opt.Query, params: opt.Params });
+  }
+  async query(sql, params) {
+    try {
+      const con = await this.getPoolConnection();
+      try {
+        const output = await new Promise((resolve, reject) => {
+          if (Array.isArray(params)) {
+            con.query(sql, params, (err, result) => (err ? reject(err) : resolve(result)));
+          } else {
+            sql = this.formatQueryParams(con, sql, params);
+            con.query(sql, (err, result) => (err ? reject(err) : resolve(result)));
+          }
+        });
+        con.release();
+        return output;
+      } catch (err) {
+        con.release();
+        throw err;
+      }
+    } catch (err) {
+      throw err;
+    }
+  }
+  async queryWithFields(sql, params) {
+    try {
+      const con = await this.getPoolConnection();
+      try {
+        const output = await new Promise((resolve, reject) => {
+          if (Array.isArray(params)) {
+            con.query(sql, params, (err, results, fields) => {
+              if (err) {
+                reject(err);
+              } else {
+                resolve({ results, fields });
+              }
+            });
+          } else {
+            sql = this.formatQueryParams(con, sql, params);
+            con.query(sql, (err, results, fields) => {
+              if (err) {
+                reject(err);
+              } else {
+                resolve({ results, fields });
+              }
+            });
+          }
+        });
+        con.release();
+        return output;
+      } catch (err) {
+        con.release();
+        throw err;
+      }
+    } catch (err) {
+      throw err;
+    }
+  }
+  formatQueryParams(con, query, values) {
+    if (!values) {
+      return query;
+    }
+    return query.replace(/\:(\w+)/g, (txt, key) => {
+      return values.hasOwnProperty(key) ? con.escape(values[key]) : txt;
+    });
+  }
+  isSqlDate(str) {
+    if (
+      str &&
+      typeof str === 'string' &&
+      str[4] === '-' &&
+      str[7] === '-' &&
+      str[10] === ' ' &&
+      str[13] === ':' &&
+      str[16] === ':'
+    ) {
+      return true;
+    }
+    return false;
+  }
+  // ── Transaction helpers ────────────────────────────────────────────
+  beginTransaction(con) {
+    return new Promise((resolve, reject) => {
+      con.beginTransaction((err) => (err ? reject(err) : resolve()));
+    });
+  }
+  commitTransaction(con) {
+    return new Promise((resolve, reject) => {
+      con.commit((err) => (err ? reject(err) : resolve()));
+    });
+  }
+  rollbackTransaction(con) {
+    return new Promise((resolve, reject) => {
+      con.rollback(() => resolve()); // rollback should not throw
+    });
+  }
+  queryOnConnection(con, sql, params) {
+    return new Promise((resolve, reject) => {
+      if (Array.isArray(params)) {
+        con.query(sql, params, (err, result) => (err ? reject(err) : resolve(result)));
+      } else {
+        sql = this.formatQueryParams(con, sql, params);
+        con.query(sql, (err, result) => (err ? reject(err) : resolve(result)));
+      }
+    });
+  }
+  queryOnConnectionWithFields(con, sql, params) {
+    return new Promise((resolve, reject) => {
+      if (Array.isArray(params)) {
+        con.query(sql, params, (err, results, fields) => (err ? reject(err) : resolve({ results, fields })));
+      } else {
+        sql = this.formatQueryParams(con, sql, params);
+        con.query(sql, (err, results, fields) => (err ? reject(err) : resolve({ results, fields })));
+      }
+    });
+  }
+  buildExecOnConnection(con) {
+    const self = this;
+    return async function execOnConnection(opt) {
+      const { results, fields } = await self.queryOnConnectionWithFields(con, opt.query, opt.params);
+      if (!Array.isArray(results)) return results;
+      if (!self.options.dateStringTimezone && !self.options.parseBooleans) return results;
+      const booleanColumns = new Set();
+      if (self.options.parseBooleans && fields) {
+        fields.forEach((field) => {
+          if (field.type === 1 && field.length === 1) booleanColumns.add(field.name);
+        });
+      }
+      return results.map((row) => {
+        Object.keys(row).map((key) => {
+          if (self.options.dateStringTimezone && self.isSqlDate(row[key])) {
+            row[key] = new Date(row[key] + self.options.dateStringTimezone);
+          }
+          if (self.options.parseBooleans && booleanColumns.has(key) && (row[key] === 0 || row[key] === 1)) {
+            row[key] = row[key] === 1;
+          }
+        });
+        return row;
+      });
+    };
+  }
+  /**
+   * Executes a callback inside a database transaction.
+   * Automatically calls BEGIN before and COMMIT after the callback.
+   * If the callback throws, the transaction is rolled back and the error is re-thrown.
+   *
+   * @template T - The return type of the callback
+   * @param fn - An async function that receives a {@link ZTransaction} handle
+   * @returns The value returned by `fn`
+   *
+   * @example
+   * ```ts
+   * const result = await sqlService.transaction(async (trx) => {
+   *   await trx.query('INSERT INTO orders (customer_id) VALUES (:id)', { id: 42 })
+   *   await trx.query('UPDATE inventory SET stock = stock - 1 WHERE product_id = :pid', { pid: 7 })
+   *   return 'done'
+   * })
+   * ```
+   */
+  async transaction(fn) {
+    const con = await this.getPoolConnection();
+    await this.beginTransaction(con);
+    const trx = {
+      query: (sql, params) => {
+        return this.queryOnConnection(con, sql, params);
+      },
+      exec: this.buildExecOnConnection(con),
+    };
+    try {
+      const result = await fn(trx);
+      await this.commitTransaction(con);
+      con.release();
+      return result;
+    } catch (err) {
+      await this.rollbackTransaction(con);
+      con.release();
+      throw err;
+    }
+  }
+  /**
+   * Changes the active database by closing the current connection pool and creating a new one.
+   * All active connections will be gracefully closed before switching.
+   * @param newDatabase - The name of the database to switch to
+   * @returns Promise that resolves when the database has been changed successfully
+   * @throws Error if the pool cannot be closed or new pool cannot be created
+   */
+  async changeDatabase(newDatabase) {
+    return new Promise((resolve, reject) => {
+      this.pool.end((err) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+        this.databaseName = newDatabase;
+        const newOptions = { ...this.options, database: newDatabase };
+        this.pool = mysql.createPool(Object.assign({}, this.defaultPoolconfig, newOptions));
+        this.pool.on('connection', (connection) => {
+          connection.on('error', (err) => {
+            this.triggerEvent('err', err);
+          });
+          connection.on('close', (err) => {
+            this.triggerEvent('err', err);
+          });
+        });
+        resolve();
+      });
+    });
+  }
+}
+exports.ZSQLService = ZSQLService;

package/lib/core/translate_service.d.ts

@@ -0,0 +1,48 @@
+import { TranslateData, dbTranslationRow, ATranslateLang, TranslateServiceOptions } from './types/translate_types';
+export declare class ZTranslateService {
+  private opt;
+  private localCache;
+  private get sql();
+  surpressErrors: boolean;
+  private maxRetries;
+  private retryDelay;
+  private fallbackText;
+  getLanguages(): ATranslateLang[];
+  getSourceLang(): string;
+  getDefaultLang(): string;
+  constructor(opt: TranslateServiceOptions);
+  private codes;
+  getLang(cookies: { [key: string]: string }): string;
+  private sleep;
+  private logError;
+  private retryOperation;
+  translateText(langOrReq: string | any, text: string): Promise<string>;
+  private processHtmlEntities;
+  translateHtml(
+    html: string,
+    cookies: {
+      lang: string;
+    } & {
+      [key: string]: string;
+    },
+  ): Promise<string>;
+  private translateHtmlRec;
+  update(
+    key: string,
+    lang: string,
+    data: TranslateData,
+  ): Promise<{
+    insertId: number;
+    affectedRows: number;
+  }>;
+  private checkLocalCache;
+  private insertLocalCache;
+  private clearLocalCache;
+  private fetch;
+  private insert;
+  private fetchLang;
+  fetchAllGrouped(): Promise<{
+    [key: string]: dbTranslationRow[];
+  }>;
+  private fetchAll;
+}