@zintrust/core 0.1.8 → 0.1.9

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

@@ -4,13 +4,64 @@
  * 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 { QueryBuilder } from '@orm/QueryBuilder';
-import Database from 'better-sqlite3';
+import { performance } from 'node:perf_hooks';
+
+import {
+  ErrorFactory,
+  FeatureFlags,
+  Logger,
+  QueryBuilder,
+  type DatabaseConfig,
+  type IDatabaseAdapter,
+  type QueryResult,
+} from '@zintrust/core';
+
+type SqliteRunInfo = { changes: number };
+type SqliteStatement = {
+  all: (params?: readonly unknown[]) => unknown[];
+  run: (params?: readonly unknown[]) => SqliteRunInfo;
+};
+type SqliteDatabase = {
+  prepare: (sql: string) => SqliteStatement;
+  pragma: (value: string) => void;
+  close: () => void;
+};
+
+function isMissingEsmPackage(error: unknown, packageName: string): boolean {
+  if (typeof error !== 'object' || error === null) return false;
+  const maybe = error as { code?: unknown; message?: unknown };
+  const code = typeof maybe.code === 'string' ? maybe.code : '';
+  const message = typeof maybe.message === 'string' ? maybe.message : '';
+  // Some runners/wrappers preserve `code` but sanitize/omit the message.
+  if (code === 'ERR_MODULE_NOT_FOUND' && message.length === 0) return true;
+  if (code === 'ERR_MODULE_NOT_FOUND' && message.includes(`'${packageName}'`)) return true;
+  if (message.includes(`Cannot find package '${packageName}'`)) return true;
+  return false;
+}
+
+async function importSqliteDatabaseConstructor(): Promise<
+  new (filename: string) => SqliteDatabase
+> {
+  try {
+    const mod = (await import('better-sqlite3')) as unknown as {
+      default?: new (filename: string) => SqliteDatabase;
+    };
+
+    const ctor = (mod as unknown as { default?: unknown }).default;
+    if (typeof ctor === 'function') return ctor as new (filename: string) => SqliteDatabase;
+
+    // Some CJS packages may not present a `default` export under certain loaders.
+    return mod as unknown as new (filename: string) => SqliteDatabase;
+  } catch (error) {
+    if (isMissingEsmPackage(error, 'better-sqlite3')) {
+      throw ErrorFactory.createConfigError(
+        "SQLite adapter requires the 'better-sqlite3' package (run `zin add db:sqlite` or `zin plugin install db:sqlite`)."
+      );
+    }
+
+    throw ErrorFactory.createTryCatchError('Failed to load SQLite driver', { cause: error });
+  }
+}
 
 function normalizeFilename(database: string | null | undefined): string {
   const value = (database ?? '').trim();
@@ -21,13 +72,13 @@ function isSelectQuery(sql: string): boolean {
   return sql.trimStart().toLowerCase().startsWith('select');
 }
 
-function requireDb(db: Database.Database | null): Database.Database {
+function requireDb(db: SqliteDatabase | null): SqliteDatabase {
   if (db === null) throw ErrorFactory.createConnectionError('Database not connected');
   return db;
 }
 
 function executeQuery(
-  db: Database.Database,
+  db: SqliteDatabase,
   sql: string,
   parameters: readonly unknown[]
 ): QueryResult {
@@ -45,11 +96,7 @@ function executeQuery(
   return { rows: [], rowCount: info.changes };
 }
 
-function executeRawQuery<T>(
-  db: Database.Database,
-  sql: string,
-  parameters: readonly unknown[]
-): T[] {
+function executeRawQuery<T>(db: SqliteDatabase, sql: string, parameters: readonly unknown[]): T[] {
   const stmt = db.prepare(sql);
   if (isSelectQuery(sql)) return stmt.all(parameters) as T[];
   stmt.run(parameters);
@@ -57,7 +104,7 @@ function executeRawQuery<T>(
 }
 
 type SQLiteAdapterState = {
-  db: Database.Database | null;
+  db: SqliteDatabase | null;
   config: DatabaseConfig;
 };
 
@@ -65,7 +112,9 @@ async function connectSQLite(state: SQLiteAdapterState): Promise<void> {
   if (state.db !== null) return;
 
   const filename = normalizeFilename(state.config.database);
-  state.db = new Database(filename);
+
+  const SqliteDatabaseCtor = await importSqliteDatabaseConstructor();
+  state.db = new SqliteDatabaseCtor(filename);
 
   // Enable WAL mode for better concurrency
   state.db.pragma('journal_mode = WAL');
@@ -118,7 +167,7 @@ async function rawQuerySQLite<T>(
 async function transactionSQLite<T>(
   state: SQLiteAdapterState,
   adapter: IDatabaseAdapter,
-  callback: (adapter: IDatabaseAdapter, db: Database.Database) => Promise<T>
+  callback: (adapter: IDatabaseAdapter, db: SqliteDatabase) => Promise<T>
 ): Promise<T> {
   const currentDb = requireDb(state.db);
 
@@ -162,7 +211,7 @@ function createSQLiteAdapter(config: DatabaseConfig): IDatabaseAdapter {
     },
 
     async transaction<T>(
-      callback: (adapter: IDatabaseAdapter, db: Database.Database) => Promise<T>
+      callback: (adapter: IDatabaseAdapter, db: SqliteDatabase) => Promise<T>
     ): Promise<T> {
       return transactionSQLite(state, adapter, callback);
     },

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

@@ -1,7 +1,6 @@
 // TEMPLATE_START
 
-import { generateSecureJobId } from '@common/uuid';
-import { Logger } from '@config/logger';
+import { generateSecureJobId, Logger } from '@zintrust/core';
 
 export interface QueueJob {
   id: string;
@@ -44,4 +43,4 @@ export const Queue = Object.freeze({
   },
 });
 
-// TEMPLATE_END
+// TEMPLATE_END

package/src/templates/project/basic/README.md.tpl

@@ -6,6 +6,10 @@ Starter Task API built with Zintrust.
 
 ```bash
 npm install
+
+# Install optional runtime drivers on-demand (example: SQLite)
+zin add db:sqlite
+
 zin s
 ```
 

package/src/templates/project/basic/app/Controllers/UserController.ts.tpl

@@ -3,7 +3,7 @@
  * Example controller demonstrating request handling
  */
 
-import { User } from '@app/Models/User';
+import { User } from '../Models/User';
 import { Logger } from '@zintrust/core';
 import { IRequest } from '@zintrust/core';
 import { IResponse } from '@zintrust/core';

package/src/templates/project/basic/app/Models/Post.ts.tpl

@@ -3,7 +3,7 @@
  */
 
 import { IRelationship } from '@zintrust/core';
-import { User } from '@app/Models/User';
+import { User } from './User';
 import { IModel, Model, ModelConfig } from '@zintrust/core';
 
 export const PostConfig: ModelConfig = {

package/src/templates/project/basic/app/Models/User.ts.tpl

@@ -2,7 +2,7 @@
  * User Model
  */
 
-import { Post } from '@app/Models/Post';
+import { Post } from './Post';
 import { IModel, Model } from '@zintrust/core';
 
 /**

package/src/templates/project/basic/config/FileLogWriter.ts.tpl

@@ -4,9 +4,10 @@
  */
 
 import { ensureDirSafe } from '@zintrust/core';
-import { Env } from '@zintrust/core';
-import * as fs from '@node-singletons/fs';
-import * as path from '@node-singletons/path';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { Env } from './env';
 
 const getCwdSafe = (): string => {
   try {

package/src/templates/project/basic/config/SecretsManager.ts.tpl

@@ -4,13 +4,13 @@
  * Supports: AWS Secrets Manager, Parameter Store, Cloudflare KV, Deno env
  */
 
-import { Logger } from '@config/logger';
+import { Logger } from '@zintrust/core';
 import type {
   GetSecretOptions,
   SecretConfig,
   SecretsManagerInstance,
   SetSecretOptions,
-} from '@config/type';
+} from './type';
 import { ErrorFactory } from '@zintrust/core';
 
 let instance: SecretsManagerInstance | undefined;

package/src/templates/project/basic/config/StartupConfigValidator.ts.tpl

@@ -1,5 +1,5 @@
-import { appConfig } from '@config/app';
-import type { StartupConfigValidationError, StartupConfigValidationResult } from '@config/type';
+import { appConfig } from './app';
+import type { StartupConfigValidationError, StartupConfigValidationResult } from './type';
 import { ErrorFactory } from '@zintrust/core';
 
 const isSensitiveKey = (key: string): boolean => {

package/src/templates/project/basic/config/app.ts.tpl

@@ -4,8 +4,8 @@
  * Sealed namespace for immutability
  */
 
-import { Env } from '@config/env';
-import type { Environment, ProcessLike, StartMode } from '@config/type';
+import { Env } from './env';
+import type { Environment, ProcessLike, StartMode } from './type';
 
 const getProcessLike = (): ProcessLike | undefined => {
   return typeof process === 'undefined' ? undefined : (process as unknown as ProcessLike);

package/src/templates/project/basic/config/broadcast.ts.tpl

@@ -5,13 +5,13 @@
  * Driver selection must be dynamic (tests may mutate process.env).
  */
 
-import { Env } from '@config/env';
+import { Env } from './env';
 import {
   KnownBroadcastDriverConfig,
   PusherBroadcastDriverConfig,
   RedisBroadcastDriverConfig,
   RedisHttpsBroadcastDriverConfig,
-} from '@config/type';
+} from './type';
 
 const normalizeDriverName = (value: string): string => value.trim().toLowerCase();
 

package/src/templates/project/basic/config/cache.ts.tpl

@@ -4,8 +4,8 @@
  * Sealed namespace for immutability
  */
 
-import { Env } from '@config/env';
-import { CacheConfigInput, CacheDriverConfig, CacheDrivers } from '@config/type';
+import { Env } from './env';
+import { CacheConfigInput, CacheDriverConfig, CacheDrivers } from './type';
 
 const getCacheDriver = (config: CacheConfigInput): CacheDriverConfig => {
   const defaultDriver = config.default;
@@ -22,7 +22,7 @@ const cacheConfigObj = {
   /**
    * Default cache driver
    */
-  default: Env.get('CACHE_DRIVER', 'memory'),
+  default: Env.CACHE_DRIVER,
 
   /**
    * Cache drivers

package/src/templates/project/basic/config/cloudflare.ts.tpl

@@ -5,7 +5,7 @@
  * This keeps runtime-specific globals out of adapters/drivers.
  */
 
-import { KVNamespace, WorkersEnv } from '@config/type';
+import { KVNamespace, WorkersEnv } from './type';
 import type { DatabaseConfig, ID1Database } from '@zintrust/core';
 
 const getWorkersEnv = (): WorkersEnv | null => {

package/src/templates/project/basic/config/database.ts.tpl

@@ -4,12 +4,12 @@
  * Sealed namespace for immutability
  */
 
-import { Env } from '@config/env';
+import { Env } from './env';
 import {
   DatabaseConfigShape,
   DatabaseConnectionConfig,
   DatabaseConnectionName,
-} from '@config/type';
+} from './type';
 
 const isDatabaseConnectionName = (value: string): value is DatabaseConnectionName => {
   return value === 'sqlite' || value === 'postgresql' || value === 'mysql';

package/src/templates/project/basic/config/env.ts.tpl

@@ -6,7 +6,7 @@
  * Safe for both Node.js and serverless runtimes (Cloudflare Workers, Deno, Lambda)
  */
 
-import { ProcessLike } from '@config/type';
+import { ProcessLike } from './type';
 
 const getProcessLike = (): ProcessLike | undefined => {
   return typeof process === 'undefined' ? undefined : (process as unknown as ProcessLike);

package/src/templates/project/basic/config/features.ts.tpl

@@ -1,5 +1,5 @@
 import { Env } from '@zintrust/core';
-import { Logger } from '@config/logger';
+import { Logger } from '@zintrust/core';
 
 /**
  * Feature Flags State

package/src/templates/project/basic/config/index.ts.tpl

@@ -3,23 +3,23 @@
  * Central export point for all configuration
  */
 
-import { appConfig } from '@config/app';
-import { cacheConfig } from '@config/cache';
-import { databaseConfig } from '@config/database';
-import { microservicesConfig } from '@config/microservices';
-import { middlewareConfig } from '@config/middleware';
-import { queueConfig } from '@config/queue';
-import { securityConfig } from '@config/security';
-import { storageConfig } from '@config/storage';
+import { appConfig } from './app';
+import { cacheConfig } from './cache';
+import { databaseConfig } from './database';
+import { microservicesConfig } from './microservices';
+import { middlewareConfig } from './middleware';
+import { queueConfig } from './queue';
+import { securityConfig } from './security';
+import { storageConfig } from './storage';
 
-export { appConfig, type AppConfig } from '@config/app';
-export { cacheConfig, type CacheConfig } from '@config/cache';
-export { databaseConfig, type DatabaseConfig } from '@config/database';
-export { microservicesConfig, type MicroservicesConfig } from '@config/microservices';
-export { middlewareConfig } from '@config/middleware';
-export { queueConfig, type QueueConfig } from '@config/queue';
-export { securityConfig } from '@config/security';
-export { storageConfig, type StorageConfig } from '@config/storage';
+export { appConfig, type AppConfig } from './app';
+export { cacheConfig, type CacheConfig } from './cache';
+export { databaseConfig, type DatabaseConfig } from './database';
+export { microservicesConfig, type MicroservicesConfig } from './microservices';
+export { middlewareConfig } from './middleware';
+export { queueConfig, type QueueConfig } from './queue';
+export { securityConfig } from './security';
+export { storageConfig, type StorageConfig } from './storage';
 
 /**
  * Combined configuration object

package/src/templates/project/basic/config/logger.ts.tpl

@@ -3,8 +3,10 @@
  * Sealed namespace pattern - all exports through Logger namespace
  * Replaces console.* calls throughout the codebase
  */
-import { appConfig } from '@config/app';
-import { Env } from '@config/env';
+import { Logger } from '@zintrust/core';
+
+import { appConfig } from './app';
+import { Env } from './env';
 
 interface ILogger {
   debug(message: string, data?: unknown, category?: string): void;
@@ -87,7 +89,7 @@ let fileWriter: FileWriterModule['FileLogWriter'] | undefined;
 const getFileWriter = (): void => {
   if (fileWriter !== undefined) return;
   if (fileWriterPromise !== undefined) return;
-  fileWriterPromise = import('@config/FileLogWriter')
+  fileWriterPromise = import('./FileLogWriter')
     .then((mod) => {
       fileWriter = mod.FileLogWriter;
       return mod;
@@ -195,7 +197,7 @@ const emitCloudLogs = (event: CloudLogEvent): void => {
   void (async (): Promise<void> => {
     try {
       if (event.level === 'error' || event.level === 'fatal') {
-        const mod = await import('@config/logging/KvLogger');
+        const mod = await import('./logging/KvLogger');
         void mod.KvLogger.enqueue(event);
       }
     } catch {
@@ -204,7 +206,7 @@ const emitCloudLogs = (event: CloudLogEvent): void => {
 
     try {
       if (event.level === 'warn' || event.level === 'error' || event.level === 'fatal') {
-        const mod = await import('@config/logging/SlackLogger');
+        const mod = await import('./logging/SlackLogger');
         void mod.SlackLogger.enqueue(event);
       }
     } catch {
@@ -212,7 +214,7 @@ const emitCloudLogs = (event: CloudLogEvent): void => {
     }
 
     try {
-      const mod = await import('@config/logging/HttpLogger');
+      const mod = await import('./logging/HttpLogger');
       void mod.HttpLogger.enqueue(event);
     } catch {
       // best-effort
@@ -364,7 +366,7 @@ export const cleanLogsOnce = async (): Promise<string[]> => {
   if (!shouldLogToFile()) return [];
 
   try {
-    const mod = await import('@config/FileLogWriter');
+    const mod = await import('./FileLogWriter');
     const deleted = mod.cleanOnce();
     logInfo('Log cleanup executed', { deletedCount: deleted.length });
     return deleted;

package/src/templates/project/basic/config/logging/KvLogger.ts.tpl

@@ -8,8 +8,8 @@
  *  - KV_LOG_RETENTION_DAYS (default: 30)
  */
 
-import { Cloudflare } from '@config/cloudflare';
-import { Env } from '@zintrust/core';
+import { Cloudflare } from '../cloudflare';
+import { Env } from '../env';
 
 export type KvLogEvent = {
   timestamp: string;

package/src/templates/project/basic/config/mail.ts.tpl

@@ -4,8 +4,8 @@
  * Sealed namespace for immutability
  */
 
-import { Env } from '@config/env';
-import type { MailConfigInput, MailDriverConfig, MailDriverName, MailDrivers } from '@config/type';
+import { Env } from './env';
+import type { MailConfigInput, MailDriverConfig, MailDriverName, MailDrivers } from './type';
 
 const getMailDriver = (config: MailConfigInput): MailDriverConfig => {
   const defaultDriver = config.default;
@@ -67,6 +67,21 @@ const mailConfigObj = {
       })(),
     },
 
+    nodemailer: {
+      driver: 'nodemailer' as const,
+      host: Env.get('MAIL_HOST', ''),
+      port: Env.getInt('MAIL_PORT', 587),
+      username: Env.get('MAIL_USERNAME', ''),
+      password: Env.get('MAIL_PASSWORD', ''),
+      secure: (() => {
+        const raw = Env.get('MAIL_SECURE', '').trim().toLowerCase();
+        if (raw === 'starttls') return 'starttls' as const;
+        if (raw === 'tls' || raw === 'ssl' || raw === 'smtps' || raw === 'implicit') return true;
+        if (raw === 'none' || raw === 'off' || raw === 'false' || raw === '0') return false;
+        return Env.getBool('MAIL_SECURE', false);
+      })(),
+    },
+
     ses: {
       driver: 'ses' as const,
       region: Env.get('AWS_REGION', 'us-east-1'),

package/src/templates/project/basic/config/middleware.ts.tpl

@@ -1,10 +1,13 @@
-import { MiddlewareConfigType } from '@config/type';
-import { CsrfMiddleware } from '@middleware/CsrfMiddleware';
-import { ErrorHandlerMiddleware } from '@middleware/ErrorHandlerMiddleware';
-import { LoggingMiddleware } from '@middleware/LoggingMiddleware';
-import type { Middleware } from '@middleware/MiddlewareStack';
-import { RateLimiter } from '@middleware/RateLimiter';
-import { SecurityMiddleware } from '@middleware/SecurityMiddleware';
+import {
+  CsrfMiddleware,
+  ErrorHandlerMiddleware,
+  LoggingMiddleware,
+  RateLimiter,
+  SecurityMiddleware,
+  type Middleware,
+} from '@zintrust/core';
+
+import { MiddlewareConfigType } from './type';
 
 const shared = Object.freeze({
   log: LoggingMiddleware.create(),

package/src/templates/project/basic/config/notification.ts.tpl

@@ -5,8 +5,8 @@
  * Keeps runtime driver selection in one place and uses Env for safe access.
  */
 
-import { Env } from '@config/env';
-import type { NotificationProviders } from '@config/type';
+import { Env } from './env';
+import type { NotificationProviders } from './type';
 
 const notificationConfigObj = {
   /**

package/src/templates/project/basic/config/queue.ts.tpl

@@ -4,9 +4,9 @@
  * Sealed namespace for immutability
  */
 
-import { Env } from '@config/env';
+import { Env } from './env';
 
-import type { QueueConfigWithDrivers, QueueDriverName, QueueDriversConfig } from '@config/type';
+import type { QueueConfigWithDrivers, QueueDriverName, QueueDriversConfig } from './type';
 
 const getQueueDriver = (config: QueueConfigWithDrivers): QueueDriversConfig[QueueDriverName] => {
   const driverName = config.default;

package/src/templates/project/basic/config/security.ts.tpl

@@ -16,9 +16,10 @@
  * security domains (e.g., different keys for different microservices).
  */
 
-import { appConfig } from '@config/app';
-import { Env } from '@config/env';
-import { Logger } from '@config/logger';
+import { Logger } from '@zintrust/core';
+
+import { appConfig } from './app';
+import { Env } from './env';
 import { ErrorFactory } from '@zintrust/core';
 
 /**

package/src/templates/project/basic/config/startup.ts.tpl

@@ -4,7 +4,7 @@
  * Startup-only controls (evaluated during Application.boot()).
  */
 
-import { Env } from '@config/env';
+import { Env } from './env';
 
 export type StartupConfig = {
   healthChecksEnabled: boolean;

package/src/templates/project/basic/config/storage.ts.tpl

@@ -4,13 +4,13 @@
  * Sealed namespace for immutability
  */
 
-import { Env } from '@config/env';
+import { Env } from './env';
 import type {
   StorageConfigRuntime,
   StorageDriverConfig,
   StorageDriverName,
   StorageDrivers,
-} from '@config/type';
+} from './type';
 
 const isStorageDriverName = (
   value: string,

package/src/templates/project/basic/config/type.ts.tpl

@@ -1,5 +1,6 @@
-import { Env } from '@config/env';
-import type { Middleware as MiddlewareFn } from '@middleware/MiddlewareStack';
+import type { Middleware } from '@zintrust/core';
+
+import { Env } from './env';
 
 export type Environment =
   | 'development'
@@ -202,11 +203,11 @@ export type NotificationProviders = {
 };
 
 export type MiddlewareConfigType = {
-  global: MiddlewareFn[];
-  route: Record<string, MiddlewareFn>;
+  global: Middleware[];
+  route: Record<string, Middleware>;
 };
 
-export type MailDriverName = 'disabled' | 'sendgrid' | 'smtp' | 'ses' | 'mailgun';
+export type MailDriverName = 'disabled' | 'sendgrid' | 'smtp' | 'ses' | 'mailgun' | 'nodemailer';
 
 export type DisabledMailDriverConfig = {
   driver: 'disabled';
@@ -234,6 +235,15 @@ export type SmtpMailDriverConfig = {
   secure: boolean | 'starttls';
 };
 
+export type NodemailerMailDriverConfig = {
+  driver: 'nodemailer';
+  host: string;
+  port: number;
+  username: string;
+  password: string;
+  secure: boolean | 'starttls';
+};
+
 export type SesMailDriverConfig = {
   driver: 'ses';
   region: string;
@@ -244,6 +254,7 @@ export type MailDriverConfig =
   | SendGridMailDriverConfig
   | MailgunMailDriverConfig
   | SmtpMailDriverConfig
+  | NodemailerMailDriverConfig
   | SesMailDriverConfig;
 
 export type MailDrivers = {
@@ -251,6 +262,7 @@ export type MailDrivers = {
   sendgrid: SendGridMailDriverConfig;
   mailgun: MailgunMailDriverConfig;
   smtp: SmtpMailDriverConfig;
+  nodemailer: NodemailerMailDriverConfig;
   ses: SesMailDriverConfig;
 };
 

package/src/templates/project/basic/routes/api.ts.tpl

@@ -3,12 +3,12 @@
  * Demonstrates routing patterns
  */
 
-import { UserController } from '@app/Controllers/UserController';
-import { Env } from '@zintrust/core';
-import { registerBroadcastRoutes } from '@routes/broadcast';
-import { registerHealthRoutes } from '@routes/health';
-import { registerStorageRoutes } from '@routes/storage';
-import { type IRouter, Router } from '@zintrust/core';
+import { Env, type IRouter, Router } from '@zintrust/core';
+
+import { UserController } from '../app/Controllers/UserController';
+import { registerBroadcastRoutes } from './broadcast';
+import { registerHealthRoutes } from './health';
+import { registerStorageRoutes } from './storage';
 
 export function registerRoutes(router: IRouter): void {
   const userController = UserController.create();