@zintrust/core 0.1.0

package/src/templates/adapters/MySQLAdapter.ts.tpl

@@ -0,0 +1,97 @@
+// TEMPLATE_START
+/* eslint-disable @typescript-eslint/require-await */
+/**
+ * MySQL Database Adapter
+ */
+
+import { FeatureFlags } from '@config/features';
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { DatabaseConfig, IDatabaseAdapter, QueryResult } from '@orm/DatabaseAdapter';
+
+/**
+ * MySQL adapter implementation
+ * Sealed namespace for immutability
+ */
+export const MySQLAdapter = Object.freeze({
+  /**
+   * Create a new MySQL adapter instance
+   */
+  create(config: DatabaseConfig): IDatabaseAdapter {
+    let connected = false;
+
+    return {
+      async connect(): Promise<void> {
+        if (config.host === 'error') {
+          throw ErrorFactory.createConnectionError(
+            'Failed to connect to MySQL: Error: Connection failed'
+          );
+        }
+        connected = true;
+        Logger.info(`✓ MySQL connected (${config.host}:${config.port})`);
+      },
+
+      async disconnect(): Promise<void> {
+        connected = false;
+        Logger.info('✓ MySQL disconnected');
+      },
+
+      async query(_sql: string, _parameters: unknown[]): Promise<QueryResult> {
+        if (!connected) throw ErrorFactory.createConnectionError('Database not connected');
+        // Mock implementation
+        return { rows: [], rowCount: 0 };
+      },
+
+      async queryOne(sql: string, parameters: unknown[]): Promise<Record<string, unknown> | null> {
+        const result = await this.query(sql, parameters);
+        return result.rows[0] ?? null;
+      },
+
+      async transaction<T>(callback: (adapter: IDatabaseAdapter) => Promise<T>): Promise<T> {
+        if (!connected) throw ErrorFactory.createConnectionError('Database not connected');
+        try {
+          await this.query('START TRANSACTION', []);
+          const result = await callback(this);
+          await this.query('COMMIT', []);
+          return result;
+        } catch (error) {
+          await this.query('ROLLBACK', []);
+          throw ErrorFactory.createTryCatchError('MySQL transaction failed', error);
+        }
+      },
+
+      getType(): string {
+        return 'mysql';
+      },
+      isConnected(): boolean {
+        return connected;
+      },
+      async rawQuery<T = unknown>(sql: string, parameters?: unknown[]): Promise<T[]> {
+        if (!FeatureFlags.isRawQueryEnabled()) {
+          throw ErrorFactory.createConfigError('Raw SQL queries are disabled');
+        }
+
+        if (!connected) {
+          throw ErrorFactory.createConnectionError('Database not connected');
+        }
+
+        try {
+          Logger.warn(`Raw SQL Query executed: ${sql}`, { parameters });
+          // Mock implementation for tests
+          if (sql.includes('INVALID')) {
+            throw ErrorFactory.createDatabaseError('Invalid SQL syntax');
+          }
+          return [] as T[];
+        } catch (error) {
+          throw ErrorFactory.createTryCatchError(`Raw SQL query failed: ${sql}`, error);
+        }
+      },
+      getPlaceholder(_index: number): string {
+        return '?';
+      },
+    };
+  },
+});
+
+export default MySQLAdapter;
+// TEMPLATE_END

package/src/templates/adapters/PostgreSQLAdapter.ts.tpl

@@ -0,0 +1,101 @@
+// TEMPLATE_START
+/* eslint-disable @typescript-eslint/require-await */
+/**
+ * PostgreSQL Database Adapter
+ */
+
+import { FeatureFlags } from '@config/features';
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { DatabaseConfig, IDatabaseAdapter, QueryResult } from '@orm/DatabaseAdapter';
+
+/**
+ * PostgreSQL adapter implementation
+ * Sealed namespace for immutability
+ */
+export const PostgreSQLAdapter = Object.freeze({
+  /**
+   * Create a new PostgreSQL adapter instance
+   */
+  create(config: DatabaseConfig): IDatabaseAdapter {
+    let connected = false;
+
+    return {
+      async connect(): Promise<void> {
+        if (config.host === 'error') {
+          throw ErrorFactory.createConnectionError(
+            'Failed to connect to PostgreSQL: Connection failed'
+          );
+        }
+        connected = true;
+        Logger.info(`✓ PostgreSQL connected (${config.host}:${config.port})`);
+      },
+
+      async disconnect(): Promise<void> {
+        connected = false;
+        Logger.info('✓ PostgreSQL disconnected');
+      },
+
+      async query(_sql: string, _parameters: unknown[]): Promise<QueryResult> {
+        if (!connected) throw ErrorFactory.createConnectionError('Database not connected');
+        // Mock implementation
+        return { rows: [], rowCount: 0 };
+      },
+
+      async queryOne(sql: string, parameters: unknown[]): Promise<Record<string, unknown> | null> {
+        const result = await this.query(sql, parameters);
+        return result.rows[0] ?? null;
+      },
+
+      async transaction<T>(callback: (adapter: IDatabaseAdapter) => Promise<T>): Promise<T> {
+        if (!connected) throw ErrorFactory.createConnectionError('Database not connected');
+        try {
+          await this.query('BEGIN', []);
+          const result = await callback(this);
+          await this.query('COMMIT', []);
+          return result;
+        } catch (error) {
+          await this.query('ROLLBACK', []);
+          throw ErrorFactory.createTryCatchError('PostgreSQL transaction failed', error);
+        }
+      },
+
+      getType(): string {
+        return 'postgresql';
+      },
+      isConnected(): boolean {
+        return connected;
+      },
+      async rawQuery<T = unknown>(sql: string, parameters?: unknown[]): Promise<T[]> {
+        if (!FeatureFlags.isRawQueryEnabled()) {
+          throw ErrorFactory.createConfigError(
+            'Raw SQL queries are disabled. Set USE_RAW_QRY=true environment variable to enable.'
+          );
+        }
+
+        if (!connected) {
+          throw ErrorFactory.createConnectionError('Database not connected');
+        }
+
+        Logger.warn(`Raw SQL Query executed: ${sql}`, { parameters });
+
+        try {
+          if (sql.toUpperCase().includes('INVALID')) {
+            throw ErrorFactory.createDatabaseError('Invalid SQL syntax');
+          }
+          // Mock implementation
+          return [] as T[];
+        } catch (error) {
+          throw ErrorFactory.createTryCatchError('Raw SQL Query failed', error);
+        }
+      },
+      getPlaceholder(index: number): string {
+        return `$${index}`;
+      },
+    };
+  },
+});
+
+export default PostgreSQLAdapter;
+
+// TEMPLATE_END

package/src/templates/adapters/SQLServerAdapter.ts.tpl

@@ -0,0 +1,95 @@
+// TEMPLATE_START
+/* eslint-disable @typescript-eslint/require-await */
+/**
+ * SQL Server Database Adapter
+ */
+
+import { FeatureFlags } from '@config/features';
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { DatabaseConfig, IDatabaseAdapter, QueryResult } from '@orm/DatabaseAdapter';
+
+/**
+ * SQL Server adapter implementation
+ * Sealed namespace for immutability
+ */
+export const SQLServerAdapter = Object.freeze({
+  /**
+   * Create a new SQL Server adapter instance
+   */
+  create(config: DatabaseConfig): IDatabaseAdapter {
+    let connected = false;
+
+    return {
+      async connect(): Promise<void> {
+        if (config.host === 'error') {
+          throw ErrorFactory.createConnectionError(
+            'Failed to connect to SQL Server: Error: Connection failed'
+          );
+        }
+        connected = true;
+        Logger.info(`✓ SQL Server connected (${config.host}:${config.port})`);
+      },
+
+      async disconnect(): Promise<void> {
+        connected = false;
+        Logger.info('✓ SQL Server disconnected');
+      },
+
+      async query(_sql: string, _parameters: unknown[]): Promise<QueryResult> {
+        if (!connected) throw ErrorFactory.createConnectionError('Database not connected');
+        // Mock implementation
+        return { rows: [], rowCount: 0 };
+      },
+
+      async queryOne(sql: string, parameters: unknown[]): Promise<Record<string, unknown> | null> {
+        const result = await this.query(sql, parameters);
+        return result.rows[0] ?? null;
+      },
+
+      async transaction<T>(callback: (adapter: IDatabaseAdapter) => Promise<T>): Promise<T> {
+        try {
+          return await callback(this);
+        } catch (error) {
+          throw ErrorFactory.createTryCatchError('Transaction failed', error);
+        }
+      },
+
+      getType(): string {
+        return 'sqlserver';
+      },
+      isConnected(): boolean {
+        return connected;
+      },
+      async rawQuery<T = unknown>(sql: string, parameters?: unknown[]): Promise<T[]> {
+        if (!FeatureFlags.isRawQueryEnabled()) {
+          throw ErrorFactory.createConfigError(
+            'Raw SQL queries are disabled. Set USE_RAW_QRY=true environment variable to enable.'
+          );
+        }
+
+        if (!connected) {
+          throw ErrorFactory.createConnectionError('Database not connected');
+        }
+
+        Logger.warn(`Raw SQL Query executed: ${sql}`, { parameters });
+
+        try {
+          if (sql.toUpperCase().includes('INVALID')) {
+            throw ErrorFactory.createDatabaseError('Invalid SQL syntax');
+          }
+          // Mock implementation
+          return [] as T[];
+        } catch (error) {
+          throw ErrorFactory.createTryCatchError('Raw SQL Query failed', error);
+        }
+      },
+      getPlaceholder(index: number): string {
+        return `@param${index}`;
+      },
+    };
+  },
+});
+
+export default SQLServerAdapter;
+// TEMPLATE_END

package/src/templates/adapters/SQLiteAdapter.ts.tpl

@@ -0,0 +1,189 @@
+// TEMPLATE_START
+/* eslint-disable @typescript-eslint/require-await */
+/**
+ * SQLite Database Adapter
+ * Production Implementation
+ */
+
+import { FeatureFlags } from '@config/features';
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { performance } from '@node-singletons/perf-hooks';
+import { DatabaseConfig, IDatabaseAdapter, QueryResult } from '@orm/DatabaseAdapter';
+import Database from 'better-sqlite3';
+
+function normalizeFilename(database: string | null | undefined): string {
+  const value = (database ?? '').trim();
+  return value.length > 0 ? value : ':memory:';
+}
+
+function isSelectQuery(sql: string): boolean {
+  return sql.trimStart().toLowerCase().startsWith('select');
+}
+
+function requireDb(db: Database.Database | null): Database.Database {
+  if (db === null) throw ErrorFactory.createConnectionError('Database not connected');
+  return db;
+}
+
+function executeQuery(
+  db: Database.Database,
+  sql: string,
+  parameters: readonly unknown[]
+): QueryResult {
+  const start = performance.now();
+
+  const stmt = db.prepare(sql);
+  if (isSelectQuery(sql)) {
+    const rows = stmt.all(parameters) as Record<string, unknown>[];
+    Logger.debug('SQLite query executed', { durationMs: performance.now() - start, sql });
+    return { rows, rowCount: rows.length };
+  }
+
+  const info = stmt.run(parameters);
+  Logger.debug('SQLite query executed', { durationMs: performance.now() - start, sql });
+  return { rows: [], rowCount: info.changes };
+}
+
+function executeRawQuery<T>(
+  db: Database.Database,
+  sql: string,
+  parameters: readonly unknown[]
+): T[] {
+  const stmt = db.prepare(sql);
+  if (isSelectQuery(sql)) return stmt.all(parameters) as T[];
+  stmt.run(parameters);
+  return [];
+}
+
+type SQLiteAdapterState = {
+  db: Database.Database | null;
+  config: DatabaseConfig;
+};
+
+async function connectSQLite(state: SQLiteAdapterState): Promise<void> {
+  if (state.db !== null) return;
+
+  const filename = normalizeFilename(state.config.database);
+  state.db = new Database(filename);
+
+  // Enable WAL mode for better concurrency
+  state.db.pragma('journal_mode = WAL');
+
+  Logger.info(`✓ SQLite connected (${filename})`);
+}
+
+async function disconnectSQLite(state: SQLiteAdapterState): Promise<void> {
+  if (state.db === null) return;
+
+  state.db.close();
+  state.db = null;
+  Logger.info('✓ SQLite disconnected');
+}
+
+async function querySQLite(
+  state: SQLiteAdapterState,
+  sql: string,
+  parameters: readonly unknown[]
+): Promise<QueryResult> {
+  const currentDb = requireDb(state.db);
+
+  try {
+    return executeQuery(currentDb, sql, parameters);
+  } catch (error: unknown) {
+    throw ErrorFactory.createTryCatchError('Query failed', { sql, parameters, cause: error });
+  }
+}
+
+async function rawQuerySQLite<T>(
+  state: SQLiteAdapterState,
+  sql: string,
+  parameters: readonly unknown[]
+): Promise<T[]> {
+  if (!FeatureFlags.isRawQueryEnabled()) {
+    throw ErrorFactory.createConfigError('Raw SQL queries are disabled');
+  }
+
+  const currentDb = requireDb(state.db);
+
+  Logger.warn(`Raw SQL Query executed: ${sql}`);
+
+  try {
+    return executeRawQuery<T>(currentDb, sql, parameters);
+  } catch (error: unknown) {
+    throw ErrorFactory.createTryCatchError('Raw query failed', { sql, parameters, cause: error });
+  }
+}
+
+async function transactionSQLite<T>(
+  state: SQLiteAdapterState,
+  adapter: IDatabaseAdapter,
+  callback: (adapter: IDatabaseAdapter, db: Database.Database) => Promise<T>
+): Promise<T> {
+  const currentDb = requireDb(state.db);
+
+  await adapter.query('BEGIN', []);
+  try {
+    const result = await callback(adapter, currentDb);
+    await adapter.query('COMMIT', []);
+    return result;
+  } catch (error: unknown) {
+    await adapter.query('ROLLBACK', []);
+    throw ErrorFactory.createTryCatchError('Transaction failed', { cause: error });
+  }
+}
+
+function createSQLiteAdapter(config: DatabaseConfig): IDatabaseAdapter {
+  const state: SQLiteAdapterState = { db: null, config };
+
+  const adapter: IDatabaseAdapter = {
+    async connect(): Promise<void> {
+      await connectSQLite(state);
+    },
+
+    async disconnect(): Promise<void> {
+      await disconnectSQLite(state);
+    },
+
+    async query(sql: string, parameters: unknown[] = []): Promise<QueryResult> {
+      return querySQLite(state, sql, parameters);
+    },
+
+    async queryOne(
+      sql: string,
+      parameters: unknown[] = []
+    ): Promise<Record<string, unknown> | null> {
+      const result = await adapter.query(sql, parameters);
+      return result.rows[0] ?? null;
+    },
+
+    async transaction<T>(
+      callback: (adapter: IDatabaseAdapter, db: Database.Database) => Promise<T>
+    ): Promise<T> {
+      return transactionSQLite(state, adapter, callback);
+    },
+
+    async rawQuery<T = unknown>(sql: string, parameters: unknown[] = []): Promise<T[]> {
+      return rawQuerySQLite<T>(state, sql, parameters);
+    },
+
+    getType(): string {
+      return 'sqlite';
+    },
+
+    isConnected(): boolean {
+      return Boolean(state.db);
+    },
+
+    getPlaceholder(_index: number): string {
+      return '?';
+    },
+  };
+
+  return adapter;
+}
+
+export const SQLiteAdapter = Object.freeze({
+  create: createSQLiteAdapter,
+});
+// TEMPLATE_END

package/src/templates/features/Auth.ts.tpl

@@ -0,0 +1,40 @@
+// TEMPLATE_START
+import * as bcrypt from 'bcrypt';
+import { sign, verify, type Secret, type SignOptions } from 'jsonwebtoken';
+
+export const Auth = Object.freeze({
+  /**
+   * Hash a password
+   */
+  async hash(password: string): Promise<string> {
+    const salt = await bcrypt.genSalt(10);
+    return bcrypt.hash(password, salt);
+  },
+
+  /**
+   * Compare a password with a hash
+   */
+  async compare(password: string, hash: string): Promise<boolean> {
+    return bcrypt.compare(password, hash);
+  },
+
+  /**
+   * Generate a JWT token
+   */
+  generateToken(
+    payload: Record<string, unknown>,
+    secret: Secret,
+    expiresIn: NonNullable<SignOptions['expiresIn']> = '1h'
+  ): string {
+    const options: SignOptions = { expiresIn };
+    return sign(payload, secret, options);
+  },
+
+  /**
+   * Verify a JWT token
+   */
+  verifyToken<T>(token: string, secret: Secret): T {
+    return verify(token, secret) as T;
+  },
+});
+// TEMPLATE_END

package/src/templates/features/Queue.ts.tpl

@@ -0,0 +1,75 @@
+// TEMPLATE_START
+
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+export interface QueueJob {
+  id: string;
+  data: unknown;
+  timestamp: number;
+}
+
+/**
+ * Simple In-Memory Queue
+ * For production, replace with Redis or similar.
+ */
+export const Queue = Object.freeze({
+  jobs: [] as QueueJob[],
+
+  /**
+   * Add a job to the queue
+   */
+  async add<T>(data: T): Promise<string> {
+    const id = await generateSecureJobId();
+    const job: QueueJob = {
+      id,
+      data,
+      timestamp: Date.now(),
+    };
+
+    // In a real implementation, this would push to Redis/SQS
+    Queue.jobs.push(job);
+    Logger.info(`[Queue] Job added: ${id}`);
+    return id;
+  },
+
+  /**
+   * Process jobs (Placeholder)
+   */
+  async process(handler: (job: QueueJob) => Promise<void>): Promise<void> {
+    Logger.info('[Queue] Processing jobs...');
+    const jobsToProcess = [...Queue.jobs];
+    Queue.jobs.length = 0;
+    await Promise.all(jobsToProcess.map(async (job) => handler(job)));
+  },
+});
+
+async function generateSecureJobId(): Promise<string> {
+  if (typeof globalThis.crypto?.randomUUID === 'function') {
+    return globalThis.crypto.randomUUID();
+  }
+
+  if (typeof globalThis.crypto?.getRandomValues === 'function') {
+    const bytes = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(bytes);
+    return bytesToHex(bytes);
+  }
+
+  // Node fallback for environments without Web Crypto
+  try {
+    const nodeCrypto = await import('node:crypto');
+    return nodeCrypto.randomBytes(16).toString('hex');
+  } catch (error) {
+    throw ErrorFactory.createTryCatchError(
+      'Secure crypto API not available to generate a job id.',
+      error
+    );
+  }
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  let out = '';
+  for (const b of bytes) out += b.toString(16).padStart(2, '0');
+  return out;
+}
+// TEMPLATE_END

package/src/templates/project/basic/.env.example.tpl

@@ -0,0 +1,26 @@
+NODE_ENV=development
+APP_NAME={{projectName}}
+APP_PORT={{port}}
+APP_DEBUG=true
+APP_KEY=
+
+DB_CONNECTION=sqlite
+DB_DATABASE=./database.sqlite
+
+LOG_LEVEL=debug
+LOG_CHANNEL=file
+
+JWT_SECRET=
+JWT_EXPIRES_IN=1h
+
+CACHE_DRIVER=memory
+CACHE_TTL=300
+QUEUE_DRIVER=sync
+
+MAIL_DRIVER=smtp
+MAIL_HOST=
+MAIL_PORT=587
+MAIL_USERNAME=
+MAIL_PASSWORD=
+MAIL_FROM_ADDRESS=
+MAIL_FROM_NAME=