@zintrust/core 0.1.13 → 0.1.14

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

@@ -5,71 +5,88 @@
  */
 
 import { Env } from './env';
-import {
-  DatabaseConfigShape,
-  DatabaseConnectionConfig,
-  DatabaseConnectionName,
-} from './type';
-
-const isDatabaseConnectionName = (value: string): value is DatabaseConnectionName => {
-  return value === 'sqlite' || value === 'postgresql' || value === 'mysql';
+import { DatabaseConfigShape, DatabaseConnectionConfig, DatabaseConnections } from './type';
+import { ErrorFactory } from '@zintrust/core';
+
+const hasOwn = (obj: Record<string, unknown>, key: string): boolean => {
+  return Object.prototype.hasOwnProperty.call(obj, key);
 };
 
-const getDefaultConnection = (): DatabaseConnectionName => {
-  const value = Env.DB_CONNECTION;
-  return isDatabaseConnectionName(value) ? value : 'sqlite';
+const getDefaultConnection = (connections: DatabaseConnections): string => {
+  const value = String(Env.DB_CONNECTION || '').trim();
+
+  if (value.length > 0 && hasOwn(connections, value)) {
+    return value;
+  }
+
+  // Backwards-compatible default.
+  return hasOwn(connections, 'sqlite') ? 'sqlite' : (Object.keys(connections)[0] ?? 'sqlite');
 };
 
 const getDatabaseConnection = (config: DatabaseConfigShape): DatabaseConnectionConfig => {
-  const connName: DatabaseConnectionName = config.default;
-  return config.connections[connName];
+  const connName = config.default;
+  const resolved = config.connections[connName];
+  if (resolved !== undefined) return resolved;
+
+  // Backwards-compatible fallback.
+  const sqliteFallback = config.connections['sqlite'];
+  if (sqliteFallback !== undefined) return sqliteFallback;
+
+  const first = Object.values(config.connections)[0];
+  if (first !== undefined) return first;
+
+  throw ErrorFactory.createConfigError(
+    `No database connections are configured (default='${connName}').`
+  );
 };
 
+const connections = {
+  sqlite: {
+    driver: 'sqlite' as const,
+    database: Env.DB_DATABASE,
+    migrations: 'database/migrations',
+  },
+  postgresql: {
+    driver: 'postgresql' as const,
+    host: Env.DB_HOST,
+    port: Env.DB_PORT,
+    database: Env.DB_DATABASE,
+    username: Env.DB_USERNAME,
+    password: Env.DB_PASSWORD,
+    ssl: Env.getBool('DB_SSL', false),
+    pooling: {
+      enabled: Env.getBool('DB_POOLING', true),
+      min: Env.getInt('DB_POOL_MIN', 5),
+      max: Env.getInt('DB_POOL_MAX', 20),
+      idleTimeout: Env.getInt('DB_IDLE_TIMEOUT', 30000),
+      connectionTimeout: Env.getInt('DB_CONNECTION_TIMEOUT', 10000),
+    },
+  },
+  mysql: {
+    driver: 'mysql' as const,
+    host: Env.DB_HOST,
+    port: Env.DB_PORT,
+    database: Env.DB_DATABASE,
+    username: Env.DB_USERNAME,
+    password: Env.DB_PASSWORD,
+    pooling: {
+      enabled: Env.getBool('DB_POOLING', true),
+      min: Env.getInt('DB_POOL_MIN', 5),
+      max: Env.getInt('DB_POOL_MAX', 20),
+    },
+  },
+} satisfies DatabaseConnections;
+
 const databaseConfigObj = {
   /**
    * Default database connection
    */
-  default: getDefaultConnection(),
+  default: getDefaultConnection(connections),
 
   /**
    * Database connections
    */
-  connections: {
-    sqlite: {
-      driver: 'sqlite' as const,
-      database: Env.DB_DATABASE,
-      migrations: 'database/migrations',
-    },
-    postgresql: {
-      driver: 'postgresql' as const,
-      host: Env.DB_HOST,
-      port: Env.DB_PORT,
-      database: Env.DB_DATABASE,
-      username: Env.DB_USERNAME,
-      password: Env.DB_PASSWORD,
-      ssl: Env.getBool('DB_SSL', false),
-      pooling: {
-        enabled: Env.getBool('DB_POOLING', true),
-        min: Env.getInt('DB_POOL_MIN', 5),
-        max: Env.getInt('DB_POOL_MAX', 20),
-        idleTimeout: Env.getInt('DB_IDLE_TIMEOUT', 30000),
-        connectionTimeout: Env.getInt('DB_CONNECTION_TIMEOUT', 10000),
-      },
-    },
-    mysql: {
-      driver: 'mysql' as const,
-      host: Env.DB_HOST,
-      port: Env.DB_PORT,
-      database: Env.DB_DATABASE,
-      username: Env.DB_USERNAME,
-      password: Env.DB_PASSWORD,
-      pooling: {
-        enabled: Env.getBool('DB_POOLING', true),
-        min: Env.getInt('DB_POOL_MIN', 5),
-        max: Env.getInt('DB_POOL_MAX', 20),
-      },
-    },
-  },
+  connections,
 
   /**
    * Get current connection config

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

@@ -4,19 +4,23 @@
  */
 
 import { appConfig } from './app';
+import broadcastConfig from './broadcast';
 import { cacheConfig } from './cache';
 import { databaseConfig } from './database';
 import { microservicesConfig } from './microservices';
 import { middlewareConfig } from './middleware';
+import notificationConfig from './notification';
 import { queueConfig } from './queue';
 import { securityConfig } from './security';
 import { storageConfig } from './storage';
 
 export { appConfig, type AppConfig } from './app';
+export { default as broadcastConfig } from './broadcast';
 export { cacheConfig, type CacheConfig } from './cache';
 export { databaseConfig, type DatabaseConfig } from './database';
 export { microservicesConfig, type MicroservicesConfig } from './microservices';
 export { middlewareConfig } from './middleware';
+export { notificationConfig, type NotificationConfig } from './notification';
 export { queueConfig, type QueueConfig } from './queue';
 export { securityConfig } from './security';
 export { storageConfig, type StorageConfig } from './storage';
@@ -27,8 +31,10 @@ export { storageConfig, type StorageConfig } from './storage';
  */
 export const config = Object.freeze({
   app: appConfig,
+  broadcast: broadcastConfig,
   database: databaseConfig,
   storage: storageConfig,
+  notification: notificationConfig,
   security: securityConfig,
   middleware: middlewareConfig,
   microservices: microservicesConfig,

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

@@ -4,25 +4,38 @@
  * Sealed namespace for immutability
  */
 
-import { Env } from './env';
-import type { MailConfigInput, MailDriverConfig, MailDriverName, MailDrivers } from './type';
+import { Env } from '@config/env';
+import type { MailConfigInput, MailDriverConfig } from '@config/type';
+import { ErrorFactory } from '@zintrust/core';
 
-const getMailDriver = (config: MailConfigInput): MailDriverConfig => {
-  const defaultDriver = config.default;
+const getMailDriver = (config: MailConfigInput, name?: string): MailDriverConfig => {
+  const selected = (name ?? config.default).toString().trim();
+  if (selected.length === 0) {
+    const disabled = config.drivers['disabled'];
+    if (disabled !== undefined) return disabled;
+    throw ErrorFactory.createConfigError('Mail driver not configured: disabled');
+  }
+
+  if (Object.hasOwn(config.drivers, selected)) {
+    const resolved = config.drivers[selected];
+    if (resolved !== undefined) return resolved;
+  }
 
-  if (Object.hasOwn(config.drivers, defaultDriver)) {
-    const driverName = defaultDriver as keyof MailDrivers;
-    return config.drivers[driverName];
+  // Backward-compatible fallback: if the default is misconfigured, treat mail as disabled.
+  if (name === undefined) {
+    const disabled = config.drivers['disabled'];
+    if (disabled !== undefined) return disabled;
+    throw ErrorFactory.createConfigError('Mail driver not configured: disabled');
   }
 
-  return config.drivers.disabled;
+  throw ErrorFactory.createConfigError(`Mail driver not configured: ${selected}`);
 };
 
 const mailConfigObj = {
   /**
    * Default mail driver
    */
-  default: (Env.get('MAIL_DRIVER', 'disabled') as MailDriverName) ?? 'disabled',
+  default: Env.get('MAIL_DRIVER', 'disabled').trim().toLowerCase() || 'disabled',
 
   /**
    * Default "From" identity
@@ -91,8 +104,8 @@ const mailConfigObj = {
   /**
    * Get selected driver config
    */
-  getDriver(): MailDriverConfig {
-    return getMailDriver(this);
+  getDriver(name?: string): MailDriverConfig {
+    return getMailDriver(this, name);
   },
 } as const;
 

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

@@ -1,51 +1,124 @@
 /**
  * Notification Configuration
  *
- * Config-first mapping of notification providers.
- * Keeps runtime driver selection in one place and uses Env for safe access.
+ * Config-first mapping of notification providers/channels.
+ * Driver selection must be dynamic (tests may mutate process.env).
  */
 
-import { Env } from './env';
-import type { NotificationProviders } from './type';
+import { Env } from '@config/env';
+import type {
+  KnownNotificationDriverConfig,
+  NotificationConfigInput,
+  NotificationDrivers,
+  NotificationProviders,
+} from '@config/type';
+import { ErrorFactory } from '@zintrust/core';
 
-const notificationConfigObj = {
-  /**
-   * Normalized notification driver name.
-   *
-   * NOTE: This intentionally supports custom driver names (e.g. project-specific drivers),
-   * so it returns a string rather than a strict union.
-   */
-  getDriverName(): string {
-    return Env.get('NOTIFICATION_DRIVER', 'console').trim().toLowerCase();
-  },
+const normalizeName = (value: string): string => value.trim().toLowerCase();
 
-  /**
-   * Provider configs.
-   */
-  providers: {
-    console: {
-      driver: 'console' as const,
-    },
+const hasOwn = (obj: Record<string, unknown>, key: string): boolean => {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+};
+
+const getDefaultChannel = (drivers: NotificationDrivers): string => {
+  const value = normalizeName(Env.get('NOTIFICATION_DRIVER', 'console'));
+  if (value.length > 0 && hasOwn(drivers, value)) return value;
+  return hasOwn(drivers, 'console') ? 'console' : (Object.keys(drivers)[0] ?? 'console');
+};
+
+const getNotificationDriver = (
+  config: NotificationConfigInput,
+  name?: string
+): KnownNotificationDriverConfig => {
+  const selected = normalizeName(String(name ?? config.default));
+  const channelName = selected === 'default' ? normalizeName(config.default) : selected;
 
+  const isExplicitSelection =
+    name !== undefined &&
+    String(name).trim().length > 0 &&
+    normalizeName(String(name)) !== 'default';
+
+  if (channelName.length > 0 && hasOwn(config.drivers, channelName)) {
+    const resolved = config.drivers[channelName];
+    if (resolved !== undefined) return resolved;
+  }
+
+  if (isExplicitSelection) {
+    throw ErrorFactory.createConfigError(`Notification channel not configured: ${channelName}`);
+  }
+
+  const fallback = config.drivers['console'] ?? Object.values(config.drivers)[0];
+  if (fallback !== undefined) return fallback;
+
+  throw ErrorFactory.createConfigError('No notification channels are configured');
+};
+
+const getBaseProviders = (): NotificationProviders => {
+  return {
+    console: { driver: 'console' as const },
     termii: {
       driver: 'termii' as const,
       apiKey: Env.get('TERMII_API_KEY', ''),
       sender: Env.get('TERMII_SENDER', 'Zintrust'),
       endpoint: Env.get('TERMII_ENDPOINT', 'https://api.termii.com/sms/send'),
     },
-
     twilio: {
       driver: 'twilio' as const,
       accountSid: Env.get('TWILIO_ACCOUNT_SID', ''),
       authToken: Env.get('TWILIO_AUTH_TOKEN', ''),
       fromNumber: Env.get('TWILIO_FROM_NUMBER', ''),
     },
-
     slack: {
       driver: 'slack' as const,
       webhookUrl: Env.get('SLACK_WEBHOOK_URL', ''),
     },
-  } satisfies NotificationProviders,
+  };
+};
+
+const notificationConfigObj = {
+  /**
+   * Default notification channel name (normalized).
+   */
+  get default(): string {
+    return getDefaultChannel(this.drivers);
+  },
+
+  /**
+   * Notification channels.
+   *
+   * You may add custom named channels (e.g. `opsSlack`, `smsMarketing`) that
+   * point to any known driver config.
+   */
+  get drivers(): NotificationDrivers {
+    // Return a record of channels; can be extended by app-level config.
+    return getBaseProviders() as unknown as NotificationDrivers;
+  },
+
+  /**
+   * Legacy provider configs (kept for backwards compatibility with wrappers).
+   */
+  get providers(): NotificationProviders {
+    return getBaseProviders();
+  },
+
+  /**
+   * Normalized notification channel name.
+   */
+  getDriverName(): string {
+    return normalizeName(this.default);
+  },
+
+  /**
+   * Resolve a channel config.
+   * - Unknown names throw when explicitly selected.
+   * - `default` is a reserved alias of the configured default.
+   */
+  getDriverConfig(name?: string): KnownNotificationDriverConfig {
+    return getNotificationDriver(this, name);
+  },
 } as const;
 
-export default Object.freeze(notificationConfigObj);
+export const notificationConfig = Object.freeze(notificationConfigObj);
+export type NotificationConfig = typeof notificationConfig;
+
+export default notificationConfig;

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

@@ -5,28 +5,33 @@
  */
 
 import { Env } from './env';
-import type {
-  StorageConfigRuntime,
-  StorageDriverConfig,
-  StorageDriverName,
-  StorageDrivers,
-} from './type';
-
-const isStorageDriverName = (
-  value: string,
-  drivers: StorageDrivers
-): value is StorageDriverName => {
-  return value in drivers;
+import type { StorageConfigRuntime, StorageDriverConfig, StorageDrivers } from './type';
+import { ErrorFactory } from '@zintrust/core';
+
+const hasOwn = (obj: Record<string, unknown>, key: string): boolean => {
+  return Object.prototype.hasOwnProperty.call(obj, key);
 };
 
-const getStorageDriver = (config: StorageConfigRuntime): StorageDriverConfig => {
-  const driverName = config.default;
+const getStorageDriver = (config: StorageConfigRuntime, name?: string): StorageDriverConfig => {
+  const selected = String(name ?? config.default).trim();
+  const diskName = selected === 'default' ? String(config.default).trim() : selected;
+  const isExplicitSelection =
+    name !== undefined && String(name).trim().length > 0 && String(name).trim() !== 'default';
+
+  if (diskName !== '' && hasOwn(config.drivers, diskName)) {
+    const resolved = config.drivers[diskName];
+    if (resolved !== undefined) return resolved;
+  }
 
-  if (isStorageDriverName(driverName, config.drivers)) {
-    return config.drivers[driverName];
+  if (isExplicitSelection) {
+    throw ErrorFactory.createConfigError(`Storage disk not configured: ${diskName}`);
   }
 
-  return config.drivers.local;
+  // Backwards-compatible fallback.
+  const fallback = config.drivers['local'] ?? Object.values(config.drivers)[0];
+  if (fallback !== undefined) return fallback;
+
+  throw ErrorFactory.createConfigError('No storage disks are configured');
 };
 
 const getDrivers = (): StorageDrivers => ({
@@ -86,6 +91,17 @@ const storageConfigObj = {
     return getStorageDriver(this);
   },
 
+  /**
+   * Get a storage disk configuration by name.
+   *
+   * - When `name` is provided and not configured, this throws.
+   * - When `name` is omitted, it resolves the configured default with a backwards-compatible fallback.
+   * - Reserved name `default` aliases the configured default.
+   */
+  getDriverConfig(this: StorageConfigRuntime, name?: string): StorageDriverConfig {
+    return getStorageDriver(this, name);
+  },
+
   /**
    * Temporary file settings
    */

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

@@ -1,5 +1,5 @@
-import { Env } from './env';
-import type { Middleware as MiddlewareFn } from '../middleware/MiddlewareStack';
+import { Env } from '@config/env';
+import type { Middleware as MiddlewareFn } from '@middleware/MiddlewareStack';
 
 export type Environment =
   | 'development'
@@ -50,15 +50,15 @@ export type GcsStorageDriverConfig = {
   url: EnvGetValue;
 };
 
-export type StorageDrivers = {
-  local: LocalStorageDriverConfig;
-  s3: S3StorageDriverConfig;
-  r2: R2StorageDriverConfig;
-  gcs: GcsStorageDriverConfig;
-};
+export type StorageDriverConfig =
+  | LocalStorageDriverConfig
+  | S3StorageDriverConfig
+  | R2StorageDriverConfig
+  | GcsStorageDriverConfig;
+
+export type StorageDrivers = Record<string, StorageDriverConfig>;
 
 export type StorageDriverName = keyof StorageDrivers;
-export type StorageDriverConfig = StorageDrivers[StorageDriverName];
 
 export type StorageConfigRuntime = {
   readonly default: string;
@@ -194,6 +194,13 @@ export type KnownNotificationDriverConfig =
   | TwilioNotificationDriverConfig
   | SlackNotificationDriverConfig;
 
+export type NotificationDrivers = Record<string, KnownNotificationDriverConfig>;
+
+export type NotificationConfigInput = {
+  default: string;
+  drivers: NotificationDrivers;
+};
+
 export type NotificationProviders = {
   console: ConsoleNotificationDriverConfig;
   termii: TermiiNotificationDriverConfig;
@@ -256,17 +263,16 @@ export type MailDriverConfig =
   | NodemailerMailDriverConfig
   | SesMailDriverConfig;
 
-export type MailDrivers = {
-  disabled: DisabledMailDriverConfig;
-  sendgrid: SendGridMailDriverConfig;
-  mailgun: MailgunMailDriverConfig;
-  smtp: SmtpMailDriverConfig;
-  nodemailer: NodemailerMailDriverConfig;
-  ses: SesMailDriverConfig;
-};
+export type MailDrivers = Record<string, MailDriverConfig>;
 
 export type MailConfigInput = {
-  default: MailDriverName;
+  /**
+   * Default mailer key name.
+   *
+   * This is intentionally a string to support named mailers (e.g. 'transactional', 'marketing').
+   * The underlying driver is selected by the `driver` field within each mailer config.
+   */
+  default: string;
   from: {
     address: string;
     name: string;
@@ -317,17 +323,23 @@ export type MysqlConnectionConfig = {
   };
 };
 
-export type DatabaseConnections = {
-  sqlite: SqliteConnectionConfig;
-  postgresql: PostgresqlConnectionConfig;
-  mysql: MysqlConnectionConfig;
-};
+export type DatabaseConnectionConfig =
+  | SqliteConnectionConfig
+  | PostgresqlConnectionConfig
+  | MysqlConnectionConfig;
 
-export type DatabaseConnectionName = keyof DatabaseConnections;
-export type DatabaseConnectionConfig = DatabaseConnections[DatabaseConnectionName];
+/**
+ * Named database connection configs.
+ *
+ * Keys represent connection names (e.g. 'default', 'auth', 'tasks', 'db1').
+ */
+export type DatabaseConnections = Record<string, DatabaseConnectionConfig>;
 
+/**
+ * Default connection name.
+ */
 export type DatabaseConfigShape = {
-  default: DatabaseConnectionName;
+  default: string;
   connections: DatabaseConnections;
 };
 
@@ -382,13 +394,7 @@ export type CacheDriverConfig =
   | KvCacheDriverConfig
   | KvRemoteCacheDriverConfig;
 
-export type CacheDrivers = {
-  memory: MemoryCacheDriverConfig;
-  redis: RedisCacheDriverConfig;
-  mongodb: MongoCacheDriverConfig;
-  kv: KvCacheDriverConfig;
-  'kv-remote': KvRemoteCacheDriverConfig;
-};
+export type CacheDrivers = Record<string, CacheDriverConfig>;
 
 export type CacheConfigInput = {
   default: string;
@@ -430,3 +436,10 @@ export type KnownBroadcastDriverConfig =
   | PusherBroadcastDriverConfig
   | RedisBroadcastDriverConfig
   | RedisHttpsBroadcastDriverConfig;
+
+export type BroadcastDrivers = Record<string, KnownBroadcastDriverConfig>;
+
+export type BroadcastConfigInput = {
+  default: string;
+  drivers: BroadcastDrivers;
+};

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

@@ -3,17 +3,13 @@
  * Provides health, liveness, and readiness endpoints.
  */
 
-import {
-  Env,
-  Logger,
-  QueryBuilder,
-  RuntimeHealthProbes,
-  type IRouter,
-  Router,
-  useDatabase,
-} from '@zintrust/core';
-
-import { appConfig } from '../config';
+import { appConfig } from '../config/app';
+import { Env } from '../config/env';
+import { Logger } from '../config/logger';
+import { RuntimeHealthProbes } from '@zintrust/core';
+import { useDatabase } from '@zintrust/core';
+import { QueryBuilder } from '@zintrust/core';
+import { type IRouter, Router } from '@zintrust/core';
 
 export function registerHealthRoutes(router: IRouter): void {
   registerHealthRoute(router);
@@ -27,6 +23,13 @@ function registerHealthRoute(router: IRouter): void {
 
     try {
       const db = useDatabase();
+      const maybeIsConnected = (db as unknown as { isConnected?: unknown }).isConnected;
+      const maybeConnect = (db as unknown as { connect?: unknown }).connect;
+      if (typeof maybeIsConnected === 'function' && maybeIsConnected.call(db) === false) {
+        if (typeof maybeConnect === 'function') {
+          await maybeConnect.call(db);
+        }
+      }
       await QueryBuilder.ping(db);
 
       const uptime =
@@ -79,6 +82,13 @@ function registerHealthReadyRoute(router: IRouter): void {
 
     try {
       const db = useDatabase();
+      const maybeIsConnected = (db as unknown as { isConnected?: unknown }).isConnected;
+      const maybeConnect = (db as unknown as { connect?: unknown }).connect;
+      if (typeof maybeIsConnected === 'function' && maybeIsConnected.call(db) === false) {
+        if (typeof maybeConnect === 'function') {
+          await maybeConnect.call(db);
+        }
+      }
       await QueryBuilder.ping(db);
 
       databaseResponseTime = Date.now() - startTime;

package/src/tools/broadcast/Broadcast.d.ts

@@ -1,7 +1,9 @@
+type Broadcaster = Readonly<{
+    send: (channel: string, event: string, data: unknown) => Promise<unknown>;
+}>;
 export declare const Broadcast: Readonly<{
-    send(channel: string, event: string, data: unknown): Promise<{
-        ok: boolean;
-    }>;
+    send(channel: string, event: string, data: unknown): Promise<unknown>;
+    broadcaster(name?: string): Broadcaster;
 }>;
 export default Broadcast;
 //# sourceMappingURL=Broadcast.d.ts.map

package/src/tools/broadcast/Broadcast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Broadcast.d.ts","sourceRoot":"","sources":["../../../../src/tools/broadcast/Broadcast.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,SAAS;kBACA,MAAM,SAAS,MAAM,QAAQ,OAAO;;;EAmCxD,CAAC;AAEH,eAAe,SAAS,CAAC"}
+{"version":3,"file":"Broadcast.d.ts","sourceRoot":"","sources":["../../../../src/tools/broadcast/Broadcast.ts"],"names":[],"mappings":"AAQA,KAAK,WAAW,GAAG,QAAQ,CAAC;IAC1B,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3E,CAAC,CAAC;AAyDH,eAAO,MAAM,SAAS;kBACA,MAAM,SAAS,MAAM,QAAQ,OAAO;uBAKrC,MAAM,GAAG,WAAW;EAQvC,CAAC;AAEH,eAAe,SAAS,CAAC"}