@zintrust/core 0.1.27 → 0.1.28

package/src/config/workers.ts

@@ -0,0 +1,257 @@
+/**
+ * Workers Configuration
+ * Background worker management settings
+ * Sealed namespace for immutability
+ */
+
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+import type {
+  RedisConfig,
+  WorkerConfig,
+  WorkerObservabilityConfig,
+  WorkersConfigOverrides,
+  WorkersGlobalConfig,
+} from '@config/type';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { createRequire } from '@node-singletons/module';
+import { StartupConfigFile, StartupConfigFileRegistry } from '@runtime/StartupConfigFileRegistry';
+import type IORedis from 'ioredis';
+
+let redisModule: typeof import('ioredis') | null | undefined;
+
+const resolveIORedis = (): typeof import('ioredis') => {
+  const injected = (globalThis as unknown as { __zintrustIoredisModule?: unknown })
+    .__zintrustIoredisModule;
+  if (injected !== undefined && injected !== null) {
+    redisModule = injected as typeof import('ioredis');
+  }
+
+  if (redisModule !== undefined) {
+    if (redisModule === null) {
+      throw ErrorFactory.createConfigError(
+        "Workers Redis driver requires the 'ioredis' package. Install it with `npm i ioredis` to enable Redis workers."
+      );
+    }
+    return redisModule;
+  }
+
+  try {
+    const require = createRequire(import.meta.url);
+    const requiredModule: unknown = require('ioredis');
+
+    // For test environments, be more permissive - if it's an object with Redis or is a function, accept it
+    if (
+      requiredModule !== null &&
+      requiredModule !== undefined &&
+      (typeof requiredModule === 'object' || typeof requiredModule === 'function')
+    ) {
+      const moduleAsRecord = requiredModule as Record<string, unknown>;
+
+      // Check if it has Redis property or if it's directly the Redis constructor
+      if (typeof moduleAsRecord['Redis'] === 'function' || typeof requiredModule === 'function') {
+        redisModule = requiredModule as typeof import('ioredis');
+      } else {
+        redisModule = null;
+      }
+    } else {
+      redisModule = null;
+    }
+  } catch {
+    redisModule = null;
+  }
+
+  if (!redisModule) {
+    throw ErrorFactory.createConfigError(
+      "Workers Redis driver requires the 'ioredis' package. Install it with `npm i ioredis' to enable Redis workers."
+    );
+  }
+
+  return redisModule;
+};
+
+export const createRedisConnection = (config: RedisConfig, maxRetries = 3): IORedis => {
+  const { Redis } = resolveIORedis();
+  const client = new Redis({
+    host: config.host,
+    port: config.port,
+    password: config.password,
+    db: config.db,
+    maxRetriesPerRequest: null, // Required by BullMQ
+    retryStrategy: (times: number): number | null => {
+      if (times > maxRetries) return null;
+      return Math.min(times * 50, 2000);
+    },
+  });
+
+  if (typeof client.on === 'function') {
+    client.on('error', (err: Error) => {
+      try {
+        if (err?.message?.includes('NOAUTH')) {
+          Logger.error(
+            '[workers][redis] NOAUTH: Redis requires authentication. Provide `password` in the workers Redis config.'
+          );
+        }
+        // eslint-disable-next-line no-console
+        console.error('[workers][redis] Redis error:', err.message || err);
+      } catch (error_) {
+        Logger.error('Redis error handler failed', error_ as Error);
+      }
+    });
+  }
+
+  return client;
+};
+
+/**
+ * Helper: Create default worker configuration from environment
+ */
+const createDefaultWorkerConfig = (): Partial<WorkerConfig> => ({
+  enabled: Env.getBool('WORKER_ENABLED', true),
+  concurrency: Env.getInt('WORKER_CONCURRENCY', 5),
+  timeout: Env.getInt('WORKER_TIMEOUT', 60),
+  retries: Env.getInt('WORKER_RETRIES', 3),
+  autoStart: Env.getBool('WORKER_AUTO_START', false),
+  priority: Env.getInt('WORKER_PRIORITY', 1),
+  healthCheckInterval: Env.getInt('WORKER_HEALTH_CHECK_INTERVAL', 60),
+  clusterMode: Env.getBool('WORKER_CLUSTER_MODE', true),
+  region: Env.get('WORKER_REGION', 'us-east-1'),
+});
+
+/**
+ * Helper: Create auto-scaling configuration from environment
+ */
+const createAutoScalingConfig = (): WorkersGlobalConfig['autoScaling'] => ({
+  enabled: Env.getBool('WORKER_AUTO_SCALING_ENABLED', false),
+  interval: Env.getInt('WORKER_AUTO_SCALING_INTERVAL', 30),
+  offPeakSchedule: Env.get('WORKER_OFF_PEAK_SCHEDULE', '22:00-06:00'),
+  offPeakReduction: Env.getFloat('WORKER_OFF_PEAK_REDUCTION', 0.7),
+});
+
+/**
+ * Helper: Create cost optimization configuration from environment
+ */
+const createCostOptimizationConfig = (): WorkersGlobalConfig['costOptimization'] => ({
+  enabled: Env.getBool('WORKER_COST_OPTIMIZATION_ENABLED', false),
+  spotInstances: Env.getBool('WORKER_SPOT_INSTANCES', false),
+  offPeakScaling: Env.getBool('WORKER_OFF_PEAK_SCALING', false),
+});
+
+/**
+ * Helper: Create compliance configuration from environment
+ */
+const createComplianceConfig = (): WorkersGlobalConfig['compliance'] => ({
+  auditLog: Env.getBool('WORKER_AUDIT_LOG', true),
+  encryption: Env.getBool('WORKER_ENCRYPTION', true),
+  dataRetention: Env.getInt('WORKER_DATA_RETENTION', 90),
+  gdpr: Env.getBool('WORKER_GDPR', false),
+  hipaa: Env.getBool('WORKER_HIPAA', false),
+  soc2: Env.getBool('WORKER_SOC2', true),
+});
+
+/**
+ * Helper: Create observability configuration from environment
+ */
+const createObservabilityConfig = (): WorkerObservabilityConfig => ({
+  prometheus: {
+    enabled: Env.getBool('WORKER_PROMETHEUS_ENABLED', false),
+    port: Env.getInt('WORKER_PROMETHEUS_PORT', 9090),
+  },
+  opentelemetry: {
+    enabled: Env.getBool('WORKER_OPENTELEMETRY_ENABLED', false),
+    endpoint: Env.get('WORKER_OPENTELEMETRY_ENDPOINT', 'http://localhost:4318'),
+  },
+  datadog: {
+    enabled: Env.getBool('WORKER_DATADOG_ENABLED', false),
+    apiKey: Env.get('WORKER_DATADOG_API_KEY', ''),
+  },
+});
+
+const createWorkersConfig = (): WorkersGlobalConfig => {
+  const overrides: WorkersConfigOverrides =
+    StartupConfigFileRegistry.get<WorkersConfigOverrides>(StartupConfigFile.Workers) ?? {};
+
+  const baseConfig: WorkersGlobalConfig = {
+    enabled: Env.getBool('WORKERS_ENABLED', true),
+    healthCheckInterval: Env.getInt('WORKERS_HEALTH_CHECK_INTERVAL', 60),
+    clusterMode: Env.getBool('WORKERS_CLUSTER_MODE', false),
+    autoScaling: createAutoScalingConfig(),
+    costOptimization: createCostOptimizationConfig(),
+    compliance: createComplianceConfig(),
+    observability: createObservabilityConfig(),
+    defaultWorker: createDefaultWorkerConfig(),
+  };
+
+  const workersConfigObj: WorkersGlobalConfig = {
+    enabled: overrides.enabled ?? baseConfig.enabled,
+    healthCheckInterval: overrides.healthCheckInterval ?? baseConfig.healthCheckInterval,
+    clusterMode: overrides.clusterMode ?? baseConfig.clusterMode,
+    autoScaling: {
+      ...baseConfig.autoScaling,
+      ...overrides.autoScaling,
+    },
+    costOptimization: {
+      ...baseConfig.costOptimization,
+      ...overrides.costOptimization,
+    },
+    compliance: {
+      ...baseConfig.compliance,
+      ...overrides.compliance,
+    },
+    observability: {
+      prometheus: {
+        ...baseConfig.observability.prometheus,
+        ...overrides.observability?.prometheus,
+      },
+      opentelemetry: {
+        ...baseConfig.observability.opentelemetry,
+        ...overrides.observability?.opentelemetry,
+      },
+      datadog: {
+        ...baseConfig.observability.datadog,
+        ...overrides.observability?.datadog,
+      },
+    },
+    defaultWorker: {
+      ...baseConfig.defaultWorker,
+      ...overrides.defaultWorker,
+    },
+  };
+
+  return Object.freeze(workersConfigObj);
+};
+
+export type WorkersConfig = ReturnType<typeof createWorkersConfig>;
+
+let cached: WorkersConfig | null = null;
+const proxyTarget: WorkersConfig = {} as WorkersConfig;
+
+const ensureWorkersConfig = (): WorkersConfig => {
+  if (cached) return cached;
+  cached = createWorkersConfig();
+
+  try {
+    Object.defineProperties(
+      proxyTarget as unknown as object,
+      Object.getOwnPropertyDescriptors(cached)
+    );
+  } catch {
+    // best-effort
+  }
+
+  return cached;
+};
+
+export const workersConfig: WorkersConfig = new Proxy(proxyTarget, {
+  get(_target, prop: keyof WorkersConfig) {
+    return ensureWorkersConfig()[prop];
+  },
+  ownKeys() {
+    ensureWorkersConfig();
+    return Reflect.ownKeys(proxyTarget as unknown as object);
+  },
+  getOwnPropertyDescriptor(_target, prop) {
+    ensureWorkersConfig();
+    return Object.getOwnPropertyDescriptor(proxyTarget as unknown as object, prop);
+  },
+});

package/src/container/ServiceContainer.ts

@@ -0,0 +1,108 @@
+/**
+ * ServiceContainer - Dependency Injection Container
+ * Manages service registration and resolution with proven dependency injection patterns
+ */
+
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+type ServiceFactory<T = unknown> = () => T;
+
+interface ServiceBinding<T = unknown> {
+  factory: ServiceFactory<T>;
+  singleton: boolean;
+  instance?: T;
+}
+
+export interface IServiceContainer {
+  bind<T>(key: string, factory: ServiceFactory<T>): void;
+  singleton<T>(key: string, factoryOrInstance: ServiceFactory<T> | T): void;
+  resolve<T = unknown>(key: string): T;
+  has(key: string): boolean;
+  get<T = unknown>(key: string): T;
+  flush(): void;
+}
+
+/**
+ * ServiceContainer - Dependency Injection Container
+ * Refactored to Functional Object pattern
+ */
+export const ServiceContainer = Object.freeze({
+  /**
+   * Create a new service container instance
+   */
+  create(): IServiceContainer {
+    const bindings = new Map<string, ServiceBinding>();
+    const singletons = new Map<string, unknown>();
+
+    return {
+      /**
+       * Register a service binding
+       */
+      bind<T>(key: string, factory: ServiceFactory<T>): void {
+        bindings.set(key, {
+          factory: factory as ServiceFactory,
+          singleton: false,
+        });
+      },
+
+      /**
+       * Register a singleton service (instantiated once)
+       */
+      singleton<T>(key: string, factoryOrInstance: ServiceFactory<T> | T): void {
+        const isFactory = typeof factoryOrInstance === 'function';
+
+        bindings.set(key, {
+          factory: isFactory ? (factoryOrInstance as ServiceFactory) : (): T => factoryOrInstance,
+          singleton: true,
+        });
+      },
+
+      /**
+       * Resolve a service from the container
+       */
+      resolve<T = unknown>(key: string): T {
+        const binding = bindings.get(key);
+
+        if (binding === undefined) {
+          throw ErrorFactory.createNotFoundError(
+            `Service "${key}" is not registered in the container`,
+            { key }
+          );
+        }
+
+        if (binding.singleton === true) {
+          if (singletons.has(key) === false) {
+            singletons.set(key, binding.factory());
+          }
+          return singletons.get(key) as T;
+        }
+
+        return binding.factory() as T;
+      },
+
+      /**
+       * Check if a service is registered
+       */
+      has(key: string): boolean {
+        return bindings.has(key);
+      },
+
+      /**
+       * Get a service (alias for resolve)
+       */
+      get<T = unknown>(key: string): T {
+        return this.resolve<T>(key);
+      },
+
+      /**
+       * Clear all bindings and singletons
+       */
+      flush(): void {
+        bindings.clear();
+        singletons.clear();
+      },
+    };
+  },
+});
+
+export default ServiceContainer;

package/src/database/Paginator.ts

@@ -0,0 +1,141 @@
+/**
+ * Paginator helpers
+ * Creates consistent pagination metadata for list responses.
+ */
+
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+export type PaginationQueryValue = string | number | boolean | null | undefined;
+export type PaginationQuery = Record<string, PaginationQueryValue>;
+
+export type PaginationLinks = {
+  first?: string;
+  last?: string;
+  prev?: string;
+  next?: string;
+};
+
+export type Paginator<T> = {
+  items: T[];
+  total: number;
+  perPage: number;
+  currentPage: number;
+  lastPage: number;
+  from: number;
+  to: number;
+  links: PaginationLinks;
+};
+
+export type CreatePaginatorInput<T> = {
+  items: T[];
+  total: number;
+  perPage: number;
+  currentPage: number;
+  baseUrl?: string;
+  query?: PaginationQuery;
+};
+
+const normalizePositiveInt = (value: number, label: string): number => {
+  const n = Math.trunc(value);
+  if (!Number.isFinite(n) || n <= 0) {
+    throw ErrorFactory.createValidationError(`${label} must be a positive integer`);
+  }
+  return n;
+};
+
+const normalizeNonNegativeInt = (value: number): number => {
+  const n = Math.trunc(value);
+  if (!Number.isFinite(n) || n < 0) return 0;
+  return n;
+};
+
+const applyQueryParams = (url: URL, query?: PaginationQuery): void => {
+  if (query === undefined) return;
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null) continue;
+    url.searchParams.set(key, String(value));
+  }
+};
+
+const buildPageUrl = (
+  baseUrl: string,
+  page: number,
+  perPage: number,
+  query?: PaginationQuery
+): string => {
+  const url = new URL(baseUrl, 'http://localhost');
+  applyQueryParams(url, query);
+  url.searchParams.set('page', String(page));
+  url.searchParams.set('perPage', String(perPage));
+
+  if (baseUrl.startsWith('http://') || baseUrl.startsWith('https://')) {
+    return url.toString();
+  }
+
+  return `${url.pathname}${url.search}${url.hash}`;
+};
+
+const getLinks = (
+  baseUrl: string | undefined,
+  currentPage: number,
+  lastPage: number,
+  perPage: number,
+  query?: PaginationQuery
+): PaginationLinks => {
+  if (baseUrl === undefined || baseUrl.trim() === '') return {};
+
+  return {
+    first: buildPageUrl(baseUrl, 1, perPage, query),
+    last: buildPageUrl(baseUrl, lastPage, perPage, query),
+    prev: currentPage > 1 ? buildPageUrl(baseUrl, currentPage - 1, perPage, query) : undefined,
+    next:
+      currentPage < lastPage ? buildPageUrl(baseUrl, currentPage + 1, perPage, query) : undefined,
+  };
+};
+
+export const Paginator = Object.freeze({
+  create<T>(input: CreatePaginatorInput<T>): Paginator<T> {
+    const perPage = normalizePositiveInt(input.perPage, 'perPage');
+    const currentPage = normalizePositiveInt(input.currentPage, 'currentPage');
+    const total = normalizeNonNegativeInt(input.total);
+
+    const lastPage = total === 0 ? 1 : Math.max(1, Math.ceil(total / perPage));
+    const safePage = Math.min(currentPage, lastPage);
+
+    const from = total === 0 ? 0 : (safePage - 1) * perPage + 1;
+    const to = total === 0 ? 0 : Math.min(from + input.items.length - 1, total);
+
+    return {
+      items: input.items,
+      total,
+      perPage,
+      currentPage: safePage,
+      lastPage,
+      from,
+      to,
+      links: getLinks(input.baseUrl, safePage, lastPage, perPage, input.query),
+    };
+  },
+});
+
+export const createPaginator = <T>(input: CreatePaginatorInput<T>): Paginator<T> => {
+  return Paginator.create(input);
+};
+
+export const getNextPageUrl = (
+  paginator: Paginator<unknown>,
+  baseUrl: string,
+  query?: PaginationQuery
+): string | undefined => {
+  if (paginator.currentPage >= paginator.lastPage) return undefined;
+  return buildPageUrl(baseUrl, paginator.currentPage + 1, paginator.perPage, query);
+};
+
+export const getPrevPageUrl = (
+  paginator: Paginator<unknown>,
+  baseUrl: string,
+  query?: PaginationQuery
+): string | undefined => {
+  if (paginator.currentPage <= 1) return undefined;
+  return buildPageUrl(baseUrl, paginator.currentPage - 1, paginator.perPage, query);
+};

package/src/database/migrations/index.ts

@@ -0,0 +1,2 @@
+// Placeholder for migrations
+export const migrations = Object.freeze([] as const);

package/src/events/EventDispatcher.ts

@@ -0,0 +1,141 @@
+import { Logger } from '@config/logger';
+
+export type EventMap = Record<string, unknown>;
+export type EventListener<TPayload> = (payload: TPayload) => void | Promise<void>;
+
+export interface IEventDispatcher<TEvents extends EventMap = EventMap> {
+  on<K extends keyof TEvents & string>(event: K, listener: EventListener<TEvents[K]>): () => void;
+  once<K extends keyof TEvents & string>(event: K, listener: EventListener<TEvents[K]>): () => void;
+  off<K extends keyof TEvents & string>(event: K, listener: EventListener<TEvents[K]>): void;
+  emit<K extends keyof TEvents & string>(event: K, payload: TEvents[K]): void;
+  emitAsync<K extends keyof TEvents & string>(event: K, payload: TEvents[K]): Promise<void>;
+  listenerCount<K extends keyof TEvents & string>(event: K): number;
+  clear<K extends keyof TEvents & string>(event?: K): void;
+}
+
+type AnyListener = EventListener<unknown>;
+
+type ListenerStore = Map<string, Set<AnyListener>>;
+
+function getOrCreateSet(store: ListenerStore, event: string): Set<AnyListener> {
+  const existing = store.get(event);
+  if (existing !== undefined) return existing;
+
+  const created = new Set<AnyListener>();
+  store.set(event, created);
+  return created;
+}
+
+function safeFireAndForget(listener: AnyListener, payload: unknown, event: string): void {
+  const result = listener(payload);
+  if (result instanceof Promise) {
+    void result.catch((error: unknown) => {
+      Logger.error('Unhandled async event listener error', { event, error });
+    });
+  }
+}
+
+export const EventDispatcher = Object.freeze({
+  create<TEvents extends EventMap = EventMap>(): IEventDispatcher<TEvents> {
+    const listeners: ListenerStore = new Map();
+
+    const dispatcher: IEventDispatcher<TEvents> = {
+      on<K extends keyof TEvents & string>(
+        event: K,
+        listener: EventListener<TEvents[K]>
+      ): () => void {
+        const set = getOrCreateSet(listeners, event);
+        set.add(listener as AnyListener);
+
+        // Capture dispatcher reference in closure instead of using 'this'
+        return (): void => {
+          dispatcher.off(event, listener);
+        };
+      },
+
+      once<K extends keyof TEvents & string>(
+        event: K,
+        listener: EventListener<TEvents[K]>
+      ): () => void {
+        const wrapped: AnyListener = async (payload: unknown) => {
+          dispatcher.off(event, wrapped as unknown as EventListener<TEvents[K]>);
+          return (listener as AnyListener)(payload);
+        };
+
+        const set = getOrCreateSet(listeners, event);
+        set.add(wrapped);
+
+        return (): void => {
+          dispatcher.off(event, wrapped as unknown as EventListener<TEvents[K]>);
+        };
+      },
+
+      off<K extends keyof TEvents & string>(event: K, listener: EventListener<TEvents[K]>): void {
+        const set = listeners.get(event);
+        if (set === undefined) return;
+
+        set.delete(listener as AnyListener);
+
+        if (set.size === 0) {
+          listeners.delete(event);
+        }
+      },
+
+      emit<K extends keyof TEvents & string>(event: K, payload: TEvents[K]): void {
+        const set = listeners.get(event);
+        if (set === undefined) return;
+
+        // Snapshot to avoid mutation during iteration affecting dispatch.
+        const snapshot = Array.from(set);
+        for (const listener of snapshot) {
+          safeFireAndForget(listener, payload, event);
+        }
+      },
+
+      async emitAsync<K extends keyof TEvents & string>(
+        event: K,
+        payload: TEvents[K]
+      ): Promise<void> {
+        const set = listeners.get(event);
+        if (set === undefined) return;
+
+        const snapshot = Array.from(set);
+
+        const results = await Promise.allSettled(
+          snapshot.map(async (listener) => {
+            await listener(payload);
+          })
+        );
+
+        const errors = results
+          .filter((r): r is PromiseRejectedResult => r.status === 'rejected')
+          .map((r) => r.reason as unknown);
+
+        if (errors.length === 1) {
+          throw errors[0];
+        }
+
+        if (errors.length > 1) {
+          throw new AggregateError(errors, `Multiple event listeners failed for "${event}"`);
+        }
+      },
+
+      listenerCount<K extends keyof TEvents & string>(event: K): number {
+        return listeners.get(event)?.size ?? 0;
+      },
+
+      clear<K extends keyof TEvents & string>(event?: K): void {
+        if (event !== undefined) {
+          listeners.delete(event);
+          return;
+        }
+
+        listeners.clear();
+      },
+    };
+
+    return dispatcher;
+  },
+});
+
+export default EventDispatcher;

package/src/events/index.ts

@@ -0,0 +1,2 @@
+export { EventDispatcher } from '@events/EventDispatcher';
+export type { EventListener, EventMap, IEventDispatcher } from '@events/EventDispatcher';