@zintrust/core 0.1.12 → 0.1.14

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

@@ -7,14 +7,33 @@
 
 import { Env } from './env';
 import {
+  BroadcastConfigInput,
+  BroadcastDrivers,
+  InMemoryBroadcastDriverConfig,
   KnownBroadcastDriverConfig,
   PusherBroadcastDriverConfig,
   RedisBroadcastDriverConfig,
   RedisHttpsBroadcastDriverConfig,
 } from './type';
+import { ErrorFactory } from '@zintrust/core';
 
 const normalizeDriverName = (value: string): string => value.trim().toLowerCase();
 
+const hasOwn = (obj: Record<string, unknown>, key: string): boolean => {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+};
+
+const getDefaultBroadcaster = (drivers: BroadcastDrivers): string => {
+  const value = normalizeDriverName(Env.get('BROADCAST_DRIVER', 'inmemory'));
+
+  if (value.length > 0 && hasOwn(drivers, value)) {
+    return value;
+  }
+
+  // Backwards-compatible default.
+  return hasOwn(drivers, 'inmemory') ? 'inmemory' : (Object.keys(drivers)[0] ?? 'inmemory');
+};
+
 const getPusherConfig = (): PusherBroadcastDriverConfig => ({
   driver: 'pusher',
   appId: Env.get('PUSHER_APP_ID', ''),
@@ -39,28 +58,77 @@ const getRedisHttpsConfig = (): RedisHttpsBroadcastDriverConfig => ({
   channelPrefix: Env.get('BROADCAST_CHANNEL_PREFIX', 'broadcast:'),
 });
 
+const getBroadcastDriver = (
+  config: BroadcastConfigInput,
+  name?: string
+): KnownBroadcastDriverConfig => {
+  const selected = normalizeDriverName(String(name ?? config.default));
+  const broadcasterName = selected === 'default' ? normalizeDriverName(config.default) : selected;
+
+  const isExplicitSelection =
+    name !== undefined &&
+    String(name).trim().length > 0 &&
+    normalizeDriverName(String(name)) !== 'default';
+
+  if (broadcasterName.length > 0 && hasOwn(config.drivers, broadcasterName)) {
+    const resolved = (config.drivers as Record<string, KnownBroadcastDriverConfig>)[
+      broadcasterName
+    ];
+    if (resolved !== undefined) return resolved;
+  }
+
+  if (isExplicitSelection) {
+    throw ErrorFactory.createConfigError(`Broadcast driver not configured: ${broadcasterName}`);
+  }
+
+  const fallback = config.drivers['inmemory'] ?? Object.values(config.drivers)[0];
+  if (fallback !== undefined) return fallback;
+
+  throw ErrorFactory.createConfigError('No broadcast drivers are configured');
+};
+
 const broadcastConfigObj = {
   /**
-   * Normalized broadcast driver name.
+   * Default broadcaster name (normalized).
+   */
+  get default(): string {
+    return getDefaultBroadcaster(this.drivers);
+  },
+
+  /**
+   * Broadcast drivers.
    *
-   * NOTE: Allows custom driver names (project-specific drivers), so returns string.
+   * You may add custom named broadcasters (e.g. `ops`, `billing`) that point to any
+   * known driver config.
+   */
+  drivers: {
+    get inmemory(): InMemoryBroadcastDriverConfig {
+      return { driver: 'inmemory' };
+    },
+    get pusher() {
+      return getPusherConfig();
+    },
+    get redis() {
+      return getRedisConfig();
+    },
+    get redishttps() {
+      return getRedisHttpsConfig();
+    },
+  } satisfies BroadcastDrivers,
+
+  /**
+   * Normalized broadcast driver name for the default broadcaster.
    */
   getDriverName(): string {
-    return normalizeDriverName(Env.get('BROADCAST_DRIVER', 'inmemory'));
+    return normalizeDriverName(this.default);
   },
 
   /**
    * Get a config object for the currently selected driver.
    * Defaults to inmemory for unknown/unsupported names.
    */
-  getDriverConfig(): KnownBroadcastDriverConfig {
-    const driver = this.getDriverName();
-
-    if (driver === 'pusher') return getPusherConfig();
-    if (driver === 'redis') return getRedisConfig();
-    if (driver === 'redishttps') return getRedisHttpsConfig();
-
-    return { driver: 'inmemory' };
+  getDriverConfig(name?: string): KnownBroadcastDriverConfig {
+    return getBroadcastDriver(this, name);
   },
 } as const;
 

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

@@ -5,17 +5,29 @@
  */
 
 import { Env } from './env';
-import { CacheConfigInput, CacheDriverConfig, CacheDrivers } from './type';
+import { CacheConfigInput, CacheDriverConfig } from './type';
+import { ErrorFactory } from '@zintrust/core';
 
-const getCacheDriver = (config: CacheConfigInput): CacheDriverConfig => {
-  const defaultDriver = config.default;
+const getCacheDriver = (config: CacheConfigInput, name?: string): CacheDriverConfig => {
+  const selected = String(name ?? config.default).trim();
+  const storeName = selected === 'default' ? String(config.default).trim() : selected;
+  const isExplicitSelection =
+    name !== undefined && String(name).trim().length > 0 && String(name).trim() !== 'default';
 
-  if (Object.hasOwn(config.drivers, defaultDriver)) {
-    const driverName = defaultDriver as keyof CacheDrivers;
-    return config.drivers[driverName];
+  if (storeName.length > 0 && Object.hasOwn(config.drivers, storeName)) {
+    const resolved = (config.drivers as Record<string, CacheDriverConfig>)[storeName];
+    if (resolved !== undefined) return resolved;
   }
 
-  return config.drivers.memory;
+  if (isExplicitSelection) {
+    throw ErrorFactory.createConfigError(`Cache store not configured: ${storeName}`);
+  }
+
+  // Backwards-compatible fallback.
+  const fallback = config.drivers['memory'] ?? Object.values(config.drivers)[0];
+  if (fallback !== undefined) return fallback;
+
+  throw ErrorFactory.createConfigError('No cache stores are configured');
 };
 
 const cacheConfigObj = {
@@ -57,8 +69,8 @@ const cacheConfigObj = {
   /**
    * Get cache driver config
    */
-  getDriver(): CacheDriverConfig {
-    return getCacheDriver(this);
+  getDriver(name?: string): CacheDriverConfig {
+    return getCacheDriver(this, name);
   },
 
   /**

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
    */