@zintrust/core 0.1.19 → 0.1.21

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

@@ -1,21 +1,8 @@
 /**
- * Configuration Exports
+ * Configuration Exports (template)
  * Central export point for all configuration
  */
 
-import {
-  appConfig,
-  broadcastConfig,
-  cacheConfig,
-  databaseConfig,
-  microservicesConfig,
-  middlewareConfig,
-  notificationConfig,
-  queueConfig,
-  securityConfig,
-  storageConfig,
-} from '@zintrust/core';
-
 export {
   appConfig,
   broadcastConfig,
@@ -31,23 +18,21 @@ export {
 
 export type {
   AppConfig,
+  BroadcastConfig,
   CacheConfig,
+  DatabaseConfig,
   MicroservicesConfig,
+  MiddlewareConfig,
+  NotificationConfig,
   QueueConfig,
+  SecurityConfig,
   StorageConfig,
 } from '@zintrust/core';
 
-// Core exports this as `DatabaseRuntimeConfig`; keep template API stable.
-export type { DatabaseRuntimeConfig as DatabaseConfig } from '@zintrust/core';
-
-export type BroadcastConfig = typeof broadcastConfig;
-export type NotificationConfig = typeof notificationConfig;
-
 /**
  * Combined configuration object
- * Sealed namespace for immutability
  */
-export const config = Object.freeze({
+export const config = {
   app: appConfig,
   broadcast: broadcastConfig,
   database: databaseConfig,
@@ -58,6 +43,6 @@ export const config = Object.freeze({
   microservices: microservicesConfig,
   cache: cacheConfig,
   queue: queueConfig,
-} as const);
+} as const;
 
 export type Config = typeof config;

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

@@ -1,121 +1,14 @@
 /**
- * HTTP Endpoint Logger
- * Sends logs to an external HTTP logging service.
+ * HTTP Logger (starter override)
  *
- * Enabled via env:
- *  - HTTP_LOG_ENABLED (default: false)
- *  - HTTP_LOG_ENDPOINT_URL
- *  - HTTP_LOG_BATCH_SIZE (default: 50)
- *  - HTTP_LOG_AUTH_TOKEN (optional)
+ * Starter projects should import the framework's HttpLogger from `@zintrust/core`.
+ * This keeps templates free of deep/internal imports.
  */
 
-import { delay } from '@zintrust/core';
-import { Env } from '@zintrust/core';
-import { ErrorFactory } from '@zintrust/core';
-import { HttpClient } from '@zintrust/core';
+import { HttpLogger } from '@zintrust/core';
+import type { HttpLogEvent } from '@zintrust/core';
 
-export type HttpLogEvent = {
-  timestamp: string;
-  level: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
-  message: string;
-  category?: string;
-  data?: unknown;
-  error?: string;
-};
-
-const isEnabled = (): boolean => Env.getBool('HTTP_LOG_ENABLED', false);
-
-let buffer: HttpLogEvent[] = [];
-let flushPromise: Promise<void> | undefined;
-
-const postBatch = async (events: HttpLogEvent[]): Promise<void> => {
-  const endpoint = Env.get('HTTP_LOG_ENDPOINT_URL').trim();
-  if (endpoint.length === 0) {
-    throw ErrorFactory.createConfigError(
-      'HTTP_LOG_ENDPOINT_URL is required when HTTP logging is enabled'
-    );
-  }
-
-  const token = Env.get('HTTP_LOG_AUTH_TOKEN').trim();
-
-  const builder = HttpClient.post(endpoint, {
-    sentAt: new Date().toISOString(),
-    count: events.length,
-    events,
-  });
-
-  if (token.length > 0) {
-    builder.withAuth(token, 'Bearer');
-  }
-
-  await builder.send();
-};
-
-const flushNow = async (): Promise<void> => {
-  const toSend = buffer;
-  buffer = [];
-
-  if (!isEnabled()) return;
-  if (toSend.length === 0) return;
-
-  const maxRetries = 3;
-
-  const attemptPost = async (attempt: number): Promise<void> => {
-    try {
-      await postBatch(toSend);
-    } catch {
-      if (attempt >= maxRetries) return;
-      const backoffMs = 100 * 2 ** attempt;
-      await delay(backoffMs);
-      await attemptPost(attempt + 1);
-    }
-  };
-
-  await attemptPost(0);
-};
-
-const scheduleFlush = async (): Promise<void> => {
-  if (flushPromise !== undefined) return flushPromise;
-
-  const promise = new Promise<void>((resolve) => {
-    const run = async (): Promise<void> => {
-      try {
-        await flushNow();
-      } finally {
-        resolve(undefined);
-      }
-    };
-
-    if (typeof globalThis.setTimeout !== 'function') {
-      void run();
-      return;
-    }
-
-    globalThis.setTimeout(() => {
-      void run();
-    }, 0);
-  });
-
-  flushPromise = promise.finally(() => {
-    flushPromise = undefined;
-  });
-
-  return flushPromise;
-};
-
-export const HttpLogger = Object.freeze({
-  async enqueue(event: HttpLogEvent): Promise<void> {
-    if (!isEnabled()) return Promise.resolve(); // NOSONAR
-
-    buffer.push(event);
-
-    const batchSize = Math.max(1, Env.getInt('HTTP_LOG_BATCH_SIZE', 50));
-    if (buffer.length >= batchSize) {
-      return scheduleFlush();
-    }
-
-    return scheduleFlush();
-  },
-});
+export { HttpLogger };
+export type { HttpLogEvent };
 
 export default HttpLogger;

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

@@ -1,62 +1,19 @@
+import { Env, type MailConfigOverrides } from '@zintrust/core';
+
 /**
- * Mail Configuration
- * Runtime mail drivers and settings
- * Sealed namespace for immutability
+ * Mail Configuration (default override)
+ *
+ * Keep this file declarative:
+ * - Core owns env parsing/default logic.
+ * - Projects can override config by editing values below.
  */
 
-import type { MailConfigInput, MailDriverConfig } from '@zintrust/core';
-import { ErrorFactory, Env } from '@zintrust/core';
-
-const isMailDriverConfig = (value: unknown): value is MailDriverConfig => {
-  if (typeof value !== 'object' || value === null) return false;
-  if (!('driver' in value)) return false;
-
-  const driver = (value as { driver?: unknown }).driver;
-  return typeof driver === 'string' && driver.trim().length > 0;
-};
-
-const getMailDriver = (config: MailConfigInput, name?: string): MailDriverConfig => {
-  const drivers = config.drivers as Record<string, unknown>;
-  const envSelectedRaw = Env.get('MAIL_CONNECTION', Env.get('MAIL_DRIVER', '')).trim();
-  const selected = (
-    name ??
-    (envSelectedRaw.length > 0 ? envSelectedRaw : undefined) ??
-    config.default
-  )
-    .toString()
-    .trim();
-
-  if (selected.length === 0) {
-    const disabled = drivers['disabled'];
-    if (isMailDriverConfig(disabled)) return disabled;
-    throw ErrorFactory.createConfigError('Mail driver not configured: disabled');
-  }
-
-  if (Object.hasOwn(drivers, selected)) {
-    const resolved = drivers[selected];
-    if (isMailDriverConfig(resolved)) return resolved;
-  }
-
-  throw ErrorFactory.createConfigError(`Mail driver not configured: ${selected}`);
-};
-
-const mailConfigObj = {
-  /**
-   * Default mail driver
-   */
+export default {
   default: Env.get('MAIL_CONNECTION', Env.get('MAIL_DRIVER', 'disabled')).trim().toLowerCase(),
-
-  /**
-   * Default "From" identity
-   */
   from: {
     address: Env.get('MAIL_FROM_ADDRESS', ''),
     name: Env.get('MAIL_FROM_NAME', ''),
   },
-
-  /**
-   * Driver configs
-   */
   drivers: {
     disabled: {
       driver: 'disabled' as const,
@@ -109,14 +66,4 @@ const mailConfigObj = {
       region: Env.get('AWS_REGION', 'us-east-1'),
     },
   },
-
-  /**
-   * Get selected driver config
-   */
-  getDriver(name?: string): MailDriverConfig {
-    return getMailDriver(this, name);
-  },
-} as const;
-
-export const mailConfig = Object.freeze(mailConfigObj);
-export type MailConfig = typeof mailConfig;
+} satisfies MailConfigOverrides;

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

@@ -1,104 +1,18 @@
 /**
- * Microservices Configuration
- * Microservices architecture and service discovery settings
- * Sealed namespace for immutability
+ * Microservices Configuration (template)
+ *
+ * Keep this file declarative:
+ * - Core owns env parsing/default logic.
+ * - Projects can override values by editing `microservicesConfigObj`.
  */
 
-import { Env } from '@zintrust/core';
+import { microservicesConfig as coreMicroservicesConfig } from '@zintrust/core';
 
-const microservicesConfigObj = {
-  /**
-   * Enable microservices mode
-   */
-  enabled: Env.getBool('MICROSERVICES', false),
+type MicroservicesConfigShape = typeof coreMicroservicesConfig;
 
-  /**
-   * Enabled services (comma-separated)
-   */
-  services: Env.get('SERVICES', '')
-    .split(',')
-    .filter((s) => s.trim()),
-
-  /**
-   * Service discovery
-   */
-  discovery: {
-    type: Env.get('SERVICE_DISCOVERY_TYPE', 'filesystem') as 'filesystem' | 'consul' | 'etcd',
-    servicesPath: Env.get('SERVICES_PATH', 'services'),
-    refreshInterval: Env.getInt('SERVICE_DISCOVERY_REFRESH_INTERVAL', 30000),
-  },
-
-  /**
-   * Service Registry
-   */
-  registry: {
-    host: Env.get('SERVICE_REGISTRY_HOST', 'localhost'),
-    port: Env.getInt('SERVICE_REGISTRY_PORT', 8500),
-    deregisterCriticalServiceAfter: Env.get('SERVICE_DEREGISTER_CRITICAL_AFTER', '30s'),
-  },
-
-  /**
-   * Service Authentication
-   */
-  auth: {
-    strategy: Env.get('SERVICE_AUTH_STRATEGY', 'none') as 'api-key' | 'jwt' | 'none' | 'custom',
-    apiKey: Env.get('SERVICE_API_KEY'),
-    jwtSecret: Env.get('SERVICE_JWT_SECRET'),
-  },
-
-  /**
-   * Request Tracing
-   */
-  tracing: {
-    enabled: Env.getBool('MICROSERVICES_TRACING', false),
-    samplingRate: Env.getInt('MICROSERVICES_TRACING_RATE', 100) / 100,
-    exportInterval: Env.getInt('TRACING_EXPORT_INTERVAL', 10000),
-    jaegerEndpoint: Env.get('JAEGER_AGENT_HOST', 'localhost'),
-  },
-
-  /**
-   * Database Isolation
-   */
-  database: {
-    isolation: Env.get('DATABASE_ISOLATION', 'shared') as 'shared' | 'isolated',
-    schema: Env.get('DATABASE_SCHEMA_PREFIX', 'microservice'),
-  },
-
-  /**
-   * Service Health Check
-   */
-  healthCheck: {
-    enabled: Env.getBool('SERVICE_HEALTH_CHECK_ENABLED', true),
-    interval: Env.getInt('SERVICE_HEALTH_CHECK_INTERVAL', 30000),
-    timeout: Env.getInt('SERVICE_HEALTH_CHECK_TIMEOUT', 5000),
-    unhealthyThreshold: Env.getInt('SERVICE_UNHEALTHY_THRESHOLD', 3),
-    healthyThreshold: Env.getInt('SERVICE_HEALTHY_THRESHOLD', 2),
-  },
-
-  /**
-   * Service Communication
-   */
-  communication: {
-    timeout: Env.getInt('SERVICE_CALL_TIMEOUT', 30000),
-    retries: Env.getInt('SERVICE_CALL_RETRIES', 3),
-    retryDelay: Env.getInt('SERVICE_CALL_RETRY_DELAY', 1000),
-    circuitBreaker: {
-      enabled: Env.getBool('CIRCUIT_BREAKER_ENABLED', true),
-      threshold: Env.getInt('CIRCUIT_BREAKER_THRESHOLD', 5),
-      timeout: Env.getInt('CIRCUIT_BREAKER_TIMEOUT', 60000),
-    },
-  },
-
-  /**
-   * Service Mesh (Istio/Linkerd support)
-   */
-  mesh: {
-    enabled: Env.getBool('SERVICE_MESH_ENABLED', false),
-    type: Env.get('SERVICE_MESH_TYPE', 'istio') as 'istio' | 'linkerd',
-    namespace: Env.get('SERVICE_MESH_NAMESPACE', 'default'),
-  },
-} as const;
-
-export const microservicesConfig = Object.freeze(microservicesConfigObj);
+export const microservicesConfigObj = {
+  ...coreMicroservicesConfig,
+} satisfies MicroservicesConfigShape;
 
+export const microservicesConfig = microservicesConfigObj;
 export type MicroservicesConfig = typeof microservicesConfig;

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

@@ -1,50 +1,32 @@
-import type { MiddlewareConfigType } from '@zintrust/core';
+/**
+ * Middleware Configuration (template)
+ *
+ * Keep this file declarative:
+ * - Core owns middleware construction / any runtime behavior.
+ * - Projects can override by editing `middlewareConfigObj`.
+ */
+
+import { middlewareConfig as coreMiddlewareConfig } from '@zintrust/core';
 import { CsrfMiddleware } from '@zintrust/core';
-import { ErrorHandlerMiddleware } from '@zintrust/core';
-import { LoggingMiddleware } from '@zintrust/core';
-import type { Middleware } from '@zintrust/core';
-import { RateLimiter } from '@zintrust/core';
-import { SecurityMiddleware } from '@zintrust/core';
 
-function createSharedMiddlewares() {
-  return Object.freeze({
-    log: LoggingMiddleware.create(),
-    error: ErrorHandlerMiddleware.create(),
-    security: SecurityMiddleware.create(),
-    rateLimit: RateLimiter.create(),
-    csrf: CsrfMiddleware.create(),
-  });
-}
+type MiddlewareConfigShape = typeof coreMiddlewareConfig;
 
-export function createMiddlewareConfig(): MiddlewareConfigType {
-  const shared = createSharedMiddlewares();
-
-  const middlewareConfigObj: MiddlewareConfigType = {
-    global: [shared.log, shared.error, shared.security, shared.rateLimit, shared.csrf],
-    route: shared,
-  };
-
-  return Object.freeze(middlewareConfigObj);
-}
-
-let cached: MiddlewareConfigType | null = null;
-
-function ensureMiddlewareConfig(): MiddlewareConfigType {
-  if (cached) return cached;
-  cached = createMiddlewareConfig();
-  return cached;
-}
+// Optional: if you're building a pure Bearer-token API (no cookie auth),
+// you can bypass CSRF for API routes.
+// Example: ['\/api\/*'] skips CSRF for all API endpoints.
+const csrf = CsrfMiddleware.create({
+  skipPaths: [],
+});
 
-export const middlewareConfig: MiddlewareConfigType = new Proxy({} as MiddlewareConfigType, {
-  get(_target, prop: keyof MiddlewareConfigType) {
-    return ensureMiddlewareConfig()[prop];
-  },
-  ownKeys() {
-    return Reflect.ownKeys(ensureMiddlewareConfig());
+export const middlewareConfigObj = {
+  ...coreMiddlewareConfig,
+  route: {
+    ...coreMiddlewareConfig.route,
+    csrf,
   },
-  getOwnPropertyDescriptor(_target, prop) {
-    return Object.getOwnPropertyDescriptor(ensureMiddlewareConfig(), prop);
-  },
-});
+  // Keep global middleware order but swap in the overridden CSRF middleware.
+  global: coreMiddlewareConfig.global.map((mw) => (mw === coreMiddlewareConfig.route.csrf ? csrf : mw)),
+} satisfies MiddlewareConfigShape;
 
+export const middlewareConfig = middlewareConfigObj;
 export default middlewareConfig;

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

@@ -1,72 +1,19 @@
+import { Env, type NotificationConfigOverrides } from '@zintrust/core';
+
 /**
- * Notification Configuration
+ * Notification Configuration (default override)
  *
- * Config-first mapping of notification providers/channels.
- * Driver selection must be dynamic (tests may mutate process.env).
+ * Keep this file declarative:
+ * - Core owns env parsing/default logic.
+ * - Projects can override config by editing values below.
  */
 
-import type {
-  KnownNotificationDriverConfig,
-  NotificationConfigInput,
-  NotificationDrivers,
-  NotificationProviders,
-} from '@zintrust/core';
-import { ErrorFactory ,Env} from '@zintrust/core';
-
-const normalizeName = (value: string): string => value.trim().toLowerCase();
-
-const hasOwn = (obj: Record<string, unknown>, key: string): boolean => {
-  return Object.hasOwn(obj, key);
-};
-
-const getDefaultChannel = (drivers: NotificationDrivers): string => {
-  const envSelectedRaw = Env.get(
-    'NOTIFICATION_CONNECTION',
-    Env.get('NOTIFICATION_DRIVER', 'console')
-  );
-  const value = normalizeName(envSelectedRaw ?? 'console');
-
-  if (value.length > 0 && hasOwn(drivers, value)) return value;
-
-  if (envSelectedRaw.trim().length > 0) {
-    throw ErrorFactory.createConfigError(`Notification channel not configured: ${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 (Object.keys(config.drivers ?? {}).length === 0) {
-    throw ErrorFactory.createConfigError('No notification channels are configured');
-  }
-
-  if (isExplicitSelection) {
-    throw ErrorFactory.createConfigError(`Notification channel not configured: ${channelName}`);
-  }
-
-  // Default selection is strict: if `default` points at an unconfigured channel, throw.
-  throw ErrorFactory.createConfigError(`Notification channel not configured: ${channelName}`);
-};
-
-const getBaseProviders = (): NotificationProviders => {
-  return {
-    console: { driver: 'console' as const },
+export default {
+  default: Env.get('NOTIFICATION_CONNECTION', Env.get('NOTIFICATION_DRIVER', 'console')),
+  drivers: {
+    console: {
+      driver: 'console' as const,
+    },
     termii: {
       driver: 'termii' as const,
       apiKey: Env.get('TERMII_API_KEY', ''),
@@ -83,53 +30,5 @@ const getBaseProviders = (): NotificationProviders => {
       driver: 'slack' as const,
       webhookUrl: Env.get('SLACK_WEBHOOK_URL', ''),
     },
-  };
-};
-
-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 const notificationConfig = Object.freeze(notificationConfigObj);
-export type NotificationConfig = typeof notificationConfig;
-
-export default notificationConfig;
+} satisfies NotificationConfigOverrides;

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

@@ -1,27 +1,15 @@
+import { Env, type QueueConfigOverrides, type QueueDriverName } from '@zintrust/core';
+
 /**
- * Queue Configuration
- * Background job and message queue settings
- * Sealed namespace for immutability
+ * Queue Configuration (default override)
+ *
+ * Keep this file declarative:
+ * - Core owns env parsing/default logic.
+ * - Projects can override config by editing values below.
  */
 
-import { Env } from '@zintrust/core';
-
-import type { QueueConfigWithDrivers, QueueDriverName, QueueDriversConfig } from '@zintrust/core';
-
-const getQueueDriver = (config: QueueConfigWithDrivers): QueueDriversConfig[QueueDriverName] => {
-  const driverName = config.default;
-  return config.drivers[driverName];
-};
-
-const queueConfigObj = {
-  /**
-   * Default queue driver
-   */
+export default {
   default: Env.get('QUEUE_DRIVER', 'sync') as QueueDriverName,
-
-  /**
-   * Queue drivers
-   */
   drivers: {
     sync: {
       driver: 'sync' as const,
@@ -53,34 +41,15 @@ const queueConfigObj = {
       region: Env.AWS_REGION,
       queueUrl: Env.get('AWS_SQS_QUEUE_URL'),
     },
-  } satisfies QueueDriversConfig,
-
-  /**
-   * Get queue driver config
-   */
-  getDriver(): QueueDriversConfig[QueueDriverName] {
-    return getQueueDriver(this);
   },
-
-  /**
-   * Failed jobs table
-   */
   failed: {
     database: Env.get('FAILED_JOBS_DB_CONNECTION', 'default'),
     table: Env.get('FAILED_JOBS_TABLE', 'failed_jobs'),
   },
-
-  /**
-   * Job processing
-   */
   processing: {
     timeout: Env.getInt('QUEUE_JOB_TIMEOUT', 60),
     retries: Env.getInt('QUEUE_JOB_RETRIES', 3),
     backoff: Env.getInt('QUEUE_JOB_BACKOFF', 0),
     workers: Env.getInt('QUEUE_WORKERS', 1),
   },
-};
-
-export const queueConfig = Object.freeze(queueConfigObj);
-
-export type QueueConfig = typeof queueConfig;
+} satisfies QueueConfigOverrides;