@zintrust/core 0.1.26 → 0.1.28

package/src/config/app.ts

@@ -0,0 +1,229 @@
+/**
+ * Application Configuration
+ * Core application settings
+ * Sealed namespace for immutability
+ */
+
+import { Env } from '@config/env';
+import type { Environment, StartMode } from '@config/type';
+
+// Cache getSafeEnv result at module load time to avoid repeated object creation
+const anyEnv = Env as {
+  get?: (key: string, defaultValue?: string) => string;
+  getInt?: (key: string, defaultValue?: number) => number;
+  getBool?: (key: string, defaultValue?: boolean) => boolean;
+};
+
+const readEnvString = (key: string, defaultValue: string = ''): string => {
+  if (typeof anyEnv.get === 'function') {
+    return anyEnv.get(key, defaultValue) ?? '';
+  }
+
+  if (typeof process !== 'undefined') {
+    const raw = process.env?.[key];
+    if (typeof raw === 'string' && raw !== '') return raw;
+  }
+
+  return defaultValue;
+};
+
+const readEnvInt = (key: string, defaultValue: number = 0): number => {
+  if (typeof anyEnv.getInt === 'function') {
+    return anyEnv.getInt(key, defaultValue);
+  }
+
+  const raw = readEnvString(key, String(defaultValue));
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : defaultValue;
+};
+
+const readEnvBool = (key: string, defaultValue: boolean = false): boolean => {
+  if (typeof anyEnv.getBool === 'function') {
+    return anyEnv.getBool(key, defaultValue);
+  }
+
+  const raw = readEnvString(key, '');
+  if (raw === '') return defaultValue;
+  return raw.toLowerCase() === 'true' || raw === '1';
+};
+
+const readAppPort = (): number => {
+  if (typeof anyEnv.getInt === 'function') {
+    return anyEnv.getInt('PORT', anyEnv.getInt('APP_PORT', 3000));
+  }
+
+  if (typeof Env.PORT === 'number' && Number.isFinite(Env.PORT) && Env.PORT > 0) {
+    return Env.PORT;
+  }
+
+  const portRaw = readEnvString('PORT', readEnvString('APP_PORT', '3000'));
+  const parsed = Number.parseInt(portRaw, 10);
+  return Number.isFinite(parsed) ? parsed : 3000;
+};
+
+/**
+ * Check if running on AWS Lambda
+ */
+function isLambda(): boolean {
+  return (
+    Env.getBool('LAMBDA_TASK_ROOT') === true ||
+    Env.getBool('AWS_LAMBDA_FUNCTION_NAME') === true ||
+    Env.getBool('AWS_EXECUTION_ENV') === true
+  );
+}
+
+/**
+ * Check if running on Cloudflare Workers
+ */
+function isCloudflare(): boolean {
+  return (globalThis as unknown as { CF: unknown }).CF !== undefined;
+}
+
+/**
+ * Check if running on Deno
+ */
+function isDeno(): boolean {
+  return (globalThis as unknown as { Deno: unknown }).Deno !== undefined;
+}
+
+/**
+ * Detect current runtime environment
+ */
+const detectRuntime = (): string => {
+  const explicit = Env.get('RUNTIME').trim();
+
+  if (explicit !== '' && explicit !== 'auto') return explicit;
+
+  // Auto-detection logic
+  if (isLambda() === true) {
+    return 'lambda';
+  }
+
+  if (isCloudflare() === true) {
+    return 'cloudflare';
+  }
+
+  if (isDeno() === true) {
+    return 'deno';
+  }
+
+  // Default to nodejs for containers (Fargate, Docker, Cloud Run)
+  return 'nodejs';
+};
+
+const resolvedNodeEnv = readEnvString('NODE_ENV', 'development') as NodeJS.ProcessEnv['NODE_ENV'];
+
+// Cache getSafeEnv result at module load time to avoid repeated object creation
+const cachedSafeEnv: NodeJS.ProcessEnv = {
+  ...(typeof process === 'undefined' ? {} : process.env),
+  NODE_ENV: resolvedNodeEnv,
+  MODE: resolvedNodeEnv,
+  npm_config_scripts_prepend_node_path: 'true',
+};
+
+const useRawQry = readEnvString('USE_RAW_QRY');
+if (useRawQry !== '') cachedSafeEnv.USE_RAW_QRY = useRawQry;
+
+const serviceApiKey = readEnvString('SERVICE_API_KEY');
+if (serviceApiKey !== '') cachedSafeEnv.SERVICE_API_KEY = serviceApiKey;
+
+const serviceJwtSecret = readEnvString('SERVICE_JWT_SECRET') || readEnvString('APP_KEY');
+if (serviceJwtSecret !== '') cachedSafeEnv.SERVICE_JWT_SECRET = serviceJwtSecret;
+
+const baseUrl = readEnvString('BASE_URL');
+if (baseUrl !== '') cachedSafeEnv['BASE_URL'] = baseUrl;
+
+if (typeof Env.SAFE_PATH === 'string' && Env.SAFE_PATH !== '') {
+  cachedSafeEnv['PATH'] = Env.SAFE_PATH;
+}
+
+const getSafeEnv = (): NodeJS.ProcessEnv => cachedSafeEnv;
+
+const normalizeMode = (): StartMode => {
+  const value = readEnvString('NODE_ENV', Env.NODE_ENV ?? 'development') as Environment;
+  if (value === 'production' || value === 'pro' || value === 'prod') return 'production';
+  if (value === 'testing' || value === 'test') return 'testing';
+  return 'development';
+};
+
+const Prefix = (): string => {
+  const app_name = (Env.APP_NAME || 'zintrust').toLowerCase().replaceAll(/\s/g, '_');
+  const env = Env.NODE_ENV;
+  return `${app_name}_zintrust_${env}`;
+};
+
+const appConfigObj = {
+  /**
+   * Application name
+   */
+  name: readEnvString('APP_NAME', Env.APP_NAME),
+
+  /**
+   * Application prefix
+   */
+  prefix: Prefix(),
+
+  /**
+   * Application environment
+   */
+  environment: normalizeMode(),
+
+  /**
+   * Application port
+   */
+  port: readAppPort(),
+
+  /**
+   * Application host
+   */
+  host: readEnvString('HOST', Env.HOST),
+
+  /**
+   * Is development environment
+   */
+  isDevelopment(): boolean {
+    return this.environment === 'development';
+  },
+
+  /**
+   * Is production environment
+   */
+  isProduction(): boolean {
+    return this.environment === 'production';
+  },
+
+  /**
+   * Is testing environment
+   */
+  isTesting(): boolean {
+    return this.environment === 'testing';
+  },
+
+  /**
+   * Application debug mode
+   */
+  debug: readEnvBool('DEBUG', Env.DEBUG),
+
+  /**
+   * Application timezone
+   */
+  timezone: readEnvString('APP_TIMEZONE', Env.APP_TIMEZONE),
+
+  /**
+   * Request timeout (milliseconds)
+   */
+  requestTimeout: readEnvInt('REQUEST_TIMEOUT', Env.REQUEST_TIMEOUT),
+
+  /**
+   * Max request body size
+   */
+  maxBodySize: readEnvInt('MAX_BODY_SIZE', Env.MAX_BODY_SIZE),
+
+  getSafeEnv,
+  detectRuntime,
+} as const;
+
+export const appConfig = Object.freeze(appConfigObj);
+export { getSafeEnv };
+
+export type AppConfig = typeof appConfig;

package/src/config/broadcast.ts

@@ -0,0 +1,194 @@
+/**
+ * Broadcast Configuration
+ *
+ * Centralizes broadcast driver selection and provider env mappings.
+ * Driver selection must be dynamic (tests may mutate process.env).
+ */
+
+import { Env } from '@config/env';
+import type {
+  BroadcastConfigInput,
+  BroadcastDrivers,
+  InMemoryBroadcastDriverConfig,
+  KnownBroadcastDriverConfig,
+  PusherBroadcastDriverConfig,
+  RedisBroadcastDriverConfig,
+  RedisHttpsBroadcastDriverConfig,
+} from '@config/type';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { StartupConfigFile, StartupConfigFileRegistry } from '@runtime/StartupConfigFileRegistry';
+
+export type BroadcastConfigOverrides = Partial<{
+  default: string;
+  drivers: Record<string, KnownBroadcastDriverConfig>;
+}>;
+
+type BroadcastRuntimeConfig = {
+  default: string;
+  drivers: BroadcastDrivers;
+  getDriverName: () => string;
+  getDriverConfig: (name?: string) => KnownBroadcastDriverConfig;
+};
+
+const normalizeDriverName = (value: string): string => value.trim().toLowerCase();
+
+const hasOwn = (obj: Record<string, unknown>, key: string): boolean => {
+  return Object.hasOwn(obj, key);
+};
+
+const getDefaultBroadcaster = (drivers: BroadcastDrivers): string => {
+  const envSelectedRaw = Env.get('BROADCAST_CONNECTION', Env.get('BROADCAST_DRIVER', 'inmemory'));
+  const value = normalizeDriverName(envSelectedRaw ?? 'inmemory');
+
+  if (value.length > 0 && hasOwn(drivers, value)) return value;
+
+  if (envSelectedRaw.trim().length > 0) {
+    throw ErrorFactory.createConfigError(`Broadcast driver not configured: ${value}`);
+  }
+
+  return hasOwn(drivers, 'inmemory') ? 'inmemory' : (Object.keys(drivers)[0] ?? 'inmemory');
+};
+
+const getPusherConfig = (): PusherBroadcastDriverConfig => ({
+  driver: 'pusher',
+  appId: Env.get('PUSHER_APP_ID', ''),
+  key: Env.get('PUSHER_APP_KEY', ''),
+  secret: Env.get('PUSHER_APP_SECRET', ''),
+  cluster: Env.get('PUSHER_APP_CLUSTER', ''),
+  useTLS: Env.getBool('PUSHER_USE_TLS', true),
+});
+
+const getRedisConfig = (): RedisBroadcastDriverConfig => ({
+  driver: 'redis',
+  host: Env.get('BROADCAST_REDIS_HOST', Env.get('REDIS_HOST', 'localhost')),
+  port: Env.getInt('BROADCAST_REDIS_PORT', Env.getInt('REDIS_PORT', 6379)),
+  password: Env.get('BROADCAST_REDIS_PASSWORD', Env.get('REDIS_PASSWORD', '')),
+  channelPrefix: Env.get('BROADCAST_CHANNEL_PREFIX', 'broadcast:'),
+});
+
+const getRedisHttpsConfig = (): RedisHttpsBroadcastDriverConfig => ({
+  driver: 'redishttps',
+  endpoint: Env.get('REDIS_HTTPS_ENDPOINT', ''),
+  token: Env.get('REDIS_HTTPS_TOKEN', ''),
+  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 createBroadcastConfig = (): BroadcastRuntimeConfig => {
+  const overrides: BroadcastConfigOverrides =
+    StartupConfigFileRegistry.get<BroadcastConfigOverrides>(StartupConfigFile.Broadcast) ?? {};
+
+  const broadcastConfigObj: BroadcastRuntimeConfig = {
+    /**
+     * Default broadcaster name (normalized).
+     */
+    get default(): string {
+      const overrideDefault = overrides.default;
+      if (typeof overrideDefault === 'string' && overrideDefault.trim().length > 0) {
+        const value = normalizeDriverName(overrideDefault);
+        if (value.length > 0 && hasOwn(this.drivers, value)) return value;
+        throw ErrorFactory.createConfigError(`Broadcast driver not configured: ${value}`);
+      }
+
+      return getDefaultBroadcaster(this.drivers);
+    },
+
+    /**
+     * Broadcast drivers.
+     *
+     * You may add custom named broadcasters (e.g. `ops`, `billing`) that point to any
+     * known driver config.
+     */
+    get drivers(): BroadcastDrivers {
+      return {
+        inmemory: { driver: 'inmemory' } satisfies InMemoryBroadcastDriverConfig,
+        pusher: getPusherConfig(),
+        redis: getRedisConfig(),
+        redishttps: getRedisHttpsConfig(),
+        ...overrides.drivers,
+      } as BroadcastDrivers;
+    },
+
+    /**
+     * Normalized broadcast driver name for the default broadcaster.
+     */
+    getDriverName(): string {
+      return normalizeDriverName(this.default);
+    },
+
+    /**
+     * Get a config object for the currently selected driver.
+     * Defaults to inmemory for unknown/unsupported names.
+     */
+    getDriverConfig(name?: string): KnownBroadcastDriverConfig {
+      return getBroadcastDriver(this, name);
+    },
+  } as const;
+
+  return Object.freeze(broadcastConfigObj);
+};
+
+export type BroadcastConfig = ReturnType<typeof createBroadcastConfig>;
+
+let cached: BroadcastConfig | null = null;
+const proxyTarget: BroadcastConfig = {} as BroadcastConfig;
+
+const ensureBroadcastConfig = (): BroadcastConfig => {
+  if (cached) return cached;
+  cached = createBroadcastConfig();
+
+  try {
+    Object.defineProperties(
+      proxyTarget as unknown as object,
+      Object.getOwnPropertyDescriptors(cached)
+    );
+  } catch {
+    // best-effort
+  }
+
+  return cached;
+};
+
+const broadcastConfig: BroadcastConfig = new Proxy(proxyTarget, {
+  get(_target, prop: keyof BroadcastConfig) {
+    return ensureBroadcastConfig()[prop];
+  },
+  ownKeys() {
+    ensureBroadcastConfig();
+    return Reflect.ownKeys(proxyTarget as unknown as object);
+  },
+  getOwnPropertyDescriptor(_target, prop) {
+    ensureBroadcastConfig();
+    return Object.getOwnPropertyDescriptor(proxyTarget as unknown as object, prop);
+  },
+});
+
+export default broadcastConfig;

package/src/config/cache.ts

@@ -0,0 +1,175 @@
+/**
+ * Cache Configuration
+ * Caching drivers and settings
+ * Sealed namespace for immutability
+ */
+
+import { Env } from '@config/env';
+import type { CacheConfigInput, CacheDriverConfig } from '@config/type';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { StartupConfigFile, StartupConfigFileRegistry } from '@runtime/StartupConfigFileRegistry';
+
+export type CacheConfigOverrides = Partial<{
+  default: string;
+  drivers: CacheConfigInput['drivers'];
+  keyPrefix: string;
+  ttl: number;
+}>;
+
+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 (storeName.length > 0 && Object.hasOwn(config.drivers, storeName)) {
+    const resolved = (config.drivers as Record<string, CacheDriverConfig>)[storeName];
+    if (resolved !== undefined) return resolved;
+  }
+
+  if (isExplicitSelection) {
+    throw ErrorFactory.createConfigError(`Cache store not configured: ${storeName}`);
+  }
+
+  if (Object.keys(config.drivers ?? {}).length === 0) {
+    throw ErrorFactory.createConfigError('No cache stores are configured');
+  }
+
+  throw ErrorFactory.createConfigError(
+    `Cache default store not configured: ${storeName || '<empty>'}`
+  );
+};
+
+const createCacheConfig = (): {
+  default: string;
+  drivers: CacheConfigInput['drivers'];
+  getDriver: (name?: string) => CacheDriverConfig;
+  keyPrefix: string;
+  ttl: number;
+} => {
+  const baseDefault = (() => {
+    const envConnection = Env.get('CACHE_CONNECTION', '').trim();
+
+    const envDriver =
+      typeof (Env as unknown as { CACHE_DRIVER?: unknown }).CACHE_DRIVER === 'string'
+        ? String((Env as unknown as { CACHE_DRIVER?: unknown }).CACHE_DRIVER)
+        : Env.get('CACHE_DRIVER', 'memory');
+
+    const selected = envConnection.length > 0 ? envConnection : String(envDriver ?? 'memory');
+    return selected.trim().toLowerCase();
+  })();
+
+  const baseDrivers = {
+    memory: {
+      driver: 'memory' as const,
+      ttl: Env.getInt('CACHE_MEMORY_TTL', 3600),
+    },
+    redis: {
+      driver: 'redis' as const,
+      host: Env.get('REDIS_HOST', 'localhost'),
+      port: Env.getInt('REDIS_PORT', 6379),
+      ttl: Env.getInt('CACHE_REDIS_TTL', 3600),
+    },
+    mongodb: {
+      driver: 'mongodb' as const,
+      uri: Env.get('MONGO_URI'),
+      db: Env.get('MONGO_DB', 'zintrust_cache'),
+      ttl: Env.getInt('CACHE_MONGO_TTL', 3600),
+    },
+    kv: {
+      driver: 'kv' as const,
+      ttl: Env.getInt('CACHE_KV_TTL', 3600),
+    },
+    'kv-remote': {
+      driver: 'kv-remote' as const,
+      ttl: Env.getInt('CACHE_KV_TTL', 3600),
+    },
+  } satisfies CacheConfigInput['drivers'];
+
+  const overrides: CacheConfigOverrides =
+    StartupConfigFileRegistry.get<CacheConfigOverrides>(StartupConfigFile.Cache) ?? {};
+
+  const mergedDrivers = {
+    ...baseDrivers,
+    ...overrides.drivers,
+  } satisfies CacheConfigInput['drivers'];
+
+  const mergedDefault =
+    typeof overrides.default === 'string' && overrides.default.trim() !== ''
+      ? overrides.default.trim().toLowerCase()
+      : baseDefault;
+
+  const mergedKeyPrefix =
+    typeof overrides.keyPrefix === 'string' && overrides.keyPrefix.length > 0
+      ? overrides.keyPrefix
+      : Env.get('CACHE_KEY_PREFIX', 'zintrust:');
+
+  const mergedTtl =
+    typeof overrides.ttl === 'number' && Number.isFinite(overrides.ttl) ? overrides.ttl : 3600;
+
+  const cacheConfigObj = {
+    /**
+     * Default cache driver
+     */
+    default: mergedDefault,
+
+    /**
+     * Cache drivers
+     */
+    drivers: mergedDrivers,
+
+    /**
+     * Get cache driver config
+     */
+    getDriver(name?: string): CacheDriverConfig {
+      return getCacheDriver(this, name);
+    },
+
+    /**
+     * Key prefix for all cache keys
+     */
+    keyPrefix: mergedKeyPrefix,
+
+    /**
+     * Default cache TTL (seconds)
+     */
+    ttl: mergedTtl,
+  };
+
+  return Object.freeze(cacheConfigObj);
+};
+
+export type CacheConfig = ReturnType<typeof createCacheConfig>;
+
+let cached: CacheConfig | null = null;
+const proxyTarget: CacheConfig = {} as CacheConfig;
+
+const ensureCacheConfig = (): CacheConfig => {
+  if (cached) return cached;
+  cached = createCacheConfig();
+
+  try {
+    Object.defineProperties(
+      proxyTarget as unknown as object,
+      Object.getOwnPropertyDescriptors(cached)
+    );
+  } catch {
+    // best-effort
+  }
+
+  return cached;
+};
+
+export const cacheConfig: CacheConfig = new Proxy(proxyTarget, {
+  get(_target, prop: keyof CacheConfig) {
+    return ensureCacheConfig()[prop];
+  },
+  ownKeys() {
+    ensureCacheConfig();
+    return Reflect.ownKeys(proxyTarget as unknown as object);
+  },
+  getOwnPropertyDescriptor(_target, prop) {
+    ensureCacheConfig();
+    return Object.getOwnPropertyDescriptor(proxyTarget as unknown as object, prop);
+  },
+});

package/src/config/cloudflare.ts

@@ -0,0 +1,43 @@
+/**
+ * Cloudflare Workers Environment Access
+ *
+ * Centralizes access to Workers bindings via globalThis.env.
+ * This keeps runtime-specific globals out of adapters/drivers.
+ */
+
+import type { KVNamespace, WorkersEnv } from '@config/type';
+import type { DatabaseConfig, ID1Database } from '@orm/DatabaseAdapter';
+
+const getWorkersEnv = (): WorkersEnv | null => {
+  const env = (globalThis as unknown as { env?: unknown }).env;
+  if (env === undefined || env === null) return null;
+  if (typeof env !== 'object') return null;
+  return env as WorkersEnv;
+};
+
+const getD1Binding = (config: DatabaseConfig): ID1Database | null => {
+  if (config.d1 !== undefined && config.d1 !== null) return config.d1;
+
+  const env = getWorkersEnv();
+  const envDb = env === null ? undefined : (env['DB'] as ID1Database | undefined);
+  if (envDb !== undefined) return envDb;
+
+  const globalDb = (globalThis as unknown as { DB?: ID1Database }).DB;
+  if (globalDb !== undefined) return globalDb;
+
+  return null;
+};
+
+const getKVBinding = (bindingName = 'CACHE'): KVNamespace | null => {
+  const env = getWorkersEnv();
+  if (env === null) return null;
+
+  const kv = env[bindingName] as KVNamespace | undefined;
+  return kv ?? null;
+};
+
+export const Cloudflare = Object.freeze({
+  getWorkersEnv,
+  getD1Binding,
+  getKVBinding,
+});