@zintrust/core 0.1.27 → 0.1.28

package/src/collections/Collection.ts

@@ -0,0 +1,241 @@
+export type PrimitiveKey = string | number | boolean | null | undefined;
+
+export type ICollection<T> = Readonly<{
+  all: () => T[];
+  toArray: () => T[];
+  count: () => number;
+  isEmpty: () => boolean;
+  map: <U>(fn: (item: T, index: number) => U) => ICollection<U>;
+  filter: (fn: (item: T, index: number) => boolean) => ICollection<T>;
+  reduce: <U>(fn: (acc: U, item: T, index: number) => U, initial: U) => U;
+  first: (fn?: (item: T, index: number) => boolean) => T | undefined;
+  last: (fn?: (item: T, index: number) => boolean) => T | undefined;
+  pluck: <K extends keyof T>(key: K) => ICollection<T[K]>;
+  where: <K extends keyof T>(key: K, value: T[K]) => ICollection<T>;
+  unique: (keySelector?: (item: T) => PrimitiveKey) => ICollection<T>;
+  sortBy: (keySelector: (item: T) => PrimitiveKey) => ICollection<T>;
+  chunk: (size: number) => ICollection<T[]>;
+  take: (n: number) => ICollection<T>;
+  skip: (n: number) => ICollection<T>;
+  keyBy: <K extends PropertyKey>(keySelector: (item: T) => K) => ReadonlyMap<K, T>;
+  groupBy: <K extends PropertyKey>(keySelector: (item: T) => K) => ReadonlyMap<K, ICollection<T>>;
+  tap: (fn: (items: T[]) => void) => ICollection<T>;
+  [Symbol.iterator]: () => Iterator<T>;
+}>;
+
+type CollectionSource<T> = Iterable<T> | ArrayLike<T> | null | undefined;
+
+function normalizeToArray<T>(items: CollectionSource<T>): T[] {
+  if (items === null || items === undefined) return [];
+
+  if (typeof (items as Iterable<T>)[Symbol.iterator] === 'function') {
+    return Array.from(items as Iterable<T>);
+  }
+
+  return Array.from(items as ArrayLike<T>);
+}
+
+function stableArray<T>(items: readonly T[]): T[] {
+  return items.slice();
+}
+
+function firstMatch<T>(
+  snapshot: readonly T[],
+  fn?: (item: T, index: number) => boolean
+): T | undefined {
+  if (!fn) return snapshot[0];
+  for (let i = 0; i < snapshot.length; i += 1) {
+    if (fn(snapshot[i], i)) return snapshot[i];
+  }
+  return undefined;
+}
+
+function lastMatch<T>(
+  snapshot: readonly T[],
+  fn?: (item: T, index: number) => boolean
+): T | undefined {
+  if (!fn) return snapshot.at(-1);
+  for (let i = snapshot.length - 1; i >= 0; i -= 1) {
+    if (fn(snapshot[i], i)) return snapshot[i];
+  }
+  return undefined;
+}
+
+function uniqueItems<T>(snapshot: readonly T[], keySelector?: (item: T) => PrimitiveKey): T[] {
+  const seen = new Set<PrimitiveKey>();
+  const out: T[] = [];
+  for (const item of snapshot) {
+    const key = keySelector ? keySelector(item) : (item as unknown as PrimitiveKey);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(item);
+  }
+  return out;
+}
+
+function sortByKey<T>(snapshot: readonly T[], keySelector: (item: T) => PrimitiveKey): T[] {
+  const out = snapshot.slice();
+  out.sort((a, b) => {
+    const ka = keySelector(a);
+    const kb = keySelector(b);
+
+    const aNil = ka === null || ka === undefined;
+    const bNil = kb === null || kb === undefined;
+    if (aNil && bNil) return 0;
+    if (aNil) return 1;
+    if (bNil) return -1;
+
+    if (typeof ka === 'number' && typeof kb === 'number') return ka - kb;
+    return String(ka).localeCompare(String(kb));
+  });
+  return out;
+}
+
+function chunkItems<T>(snapshot: readonly T[], size: number): T[][] {
+  const n = Math.floor(size);
+  if (!Number.isFinite(n) || n <= 0) return [];
+
+  const out: T[][] = [];
+  for (let i = 0; i < snapshot.length; i += n) {
+    out.push(snapshot.slice(i, i + n));
+  }
+  return out;
+}
+
+function keyByItems<T, K extends PropertyKey>(
+  snapshot: readonly T[],
+  keySelector: (item: T) => K
+): ReadonlyMap<K, T> {
+  const out = new Map<K, T>();
+  for (const item of snapshot) {
+    out.set(keySelector(item), item);
+  }
+  return out;
+}
+
+function groupByItems<T, K extends PropertyKey>(
+  snapshot: readonly T[],
+  keySelector: (item: T) => K
+): ReadonlyMap<K, ICollection<T>> {
+  const groups = new Map<K, T[]>();
+  for (const item of snapshot) {
+    const key = keySelector(item);
+    const bucket = groups.get(key);
+    if (bucket) bucket.push(item);
+    else groups.set(key, [item]);
+  }
+
+  const out = new Map<K, ICollection<T>>();
+  for (const [k, bucket] of groups.entries()) {
+    out.set(k, makeCollection(bucket));
+  }
+  return out;
+}
+
+function makeCollection<T>(items: readonly T[]): ICollection<T> {
+  const snapshot = stableArray(items);
+
+  const api: ICollection<T> = Object.freeze({
+    all: () => snapshot.slice(),
+    toArray: () => snapshot.slice(),
+    count: () => snapshot.length,
+    isEmpty: () => snapshot.length === 0,
+
+    map: (fn) => {
+      if (typeof fn !== 'function') {
+        throw new TypeError('Map callback must be a function');
+      }
+      return makeCollection(snapshot.map((item, index) => fn(item, index)));
+    },
+    filter: (fn) => {
+      if (typeof fn !== 'function') {
+        throw new TypeError('Filter callback must be a function');
+      }
+      return makeCollection(snapshot.filter((item, index) => fn(item, index)));
+    },
+    reduce: (fn, initial) => {
+      if (typeof fn !== 'function') {
+        throw new TypeError('Reduce callback must be a function');
+      }
+      return snapshot.reduce(
+        (accumulator, element, index) => fn(accumulator, element, index),
+        initial
+      );
+    },
+
+    first: (fn) => {
+      if (fn && typeof fn !== 'function') {
+        throw new TypeError('First callback must be a function');
+      }
+      return firstMatch(snapshot, fn);
+    },
+    last: (fn) => {
+      if (fn && typeof fn !== 'function') {
+        throw new TypeError('Last callback must be a function');
+      }
+      return lastMatch(snapshot, fn);
+    },
+
+    pluck: (key) => makeCollection(snapshot.map((item) => item[key])),
+    where: (key, value) => makeCollection(snapshot.filter((item) => item[key] === value)),
+
+    unique: (keySelector) => {
+      if (keySelector && typeof keySelector !== 'function') {
+        throw new TypeError('Unique key selector must be a function');
+      }
+      return makeCollection(uniqueItems(snapshot, keySelector));
+    },
+    sortBy: (keySelector) => {
+      if (typeof keySelector !== 'function') {
+        throw new TypeError('Sort key selector must be a function');
+      }
+      return makeCollection(sortByKey(snapshot, keySelector));
+    },
+    chunk: (size) => makeCollection(chunkItems(snapshot, size)),
+
+    take: (n) => {
+      const count = Math.max(0, Math.floor(n));
+      return makeCollection(snapshot.slice(0, count));
+    },
+
+    skip: (n) => {
+      const count = Math.max(0, Math.floor(n));
+      return makeCollection(snapshot.slice(count));
+    },
+
+    keyBy: (keySelector) => keyByItems(snapshot, keySelector),
+    groupBy: (keySelector) => groupByItems(snapshot, keySelector),
+
+    tap: (fn) => {
+      fn(snapshot.slice());
+      return makeCollection(snapshot);
+    },
+
+    [Symbol.iterator]: function* () {
+      for (const item of snapshot) yield item;
+    },
+  });
+
+  return api;
+}
+
+export const Collection = Object.freeze({
+  from: <T>(items: Iterable<T> | ArrayLike<T> | null | undefined): ICollection<T> =>
+    makeCollection(normalizeToArray(items)),
+
+  of: <T>(...items: T[]): ICollection<T> => makeCollection(items),
+
+  isCollection: (value: unknown): value is ICollection<unknown> => {
+    if (value === null || value === undefined) return false;
+    return (
+      typeof value === 'object' &&
+      typeof (value as { all?: unknown }).all === 'function' &&
+      typeof (value as { map?: unknown }).map === 'function' &&
+      typeof (value as { [Symbol.iterator]?: unknown })[Symbol.iterator] === 'function'
+    );
+  },
+});
+
+export function collect<T>(items: Iterable<T> | ArrayLike<T> | null | undefined): ICollection<T> {
+  return Collection.from(items);
+}

package/src/collections/index.ts

@@ -0,0 +1,2 @@
+export { collect, Collection } from '@/collections/Collection';
+export type { ICollection, PrimitiveKey } from '@/collections/Collection';

package/src/common/AwsSigV4.ts

@@ -0,0 +1,116 @@
+import { createHash, createHmac } from '@node-singletons/crypto';
+
+export type AwsSigV4Credentials = {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+};
+
+type CanonicalizedHeaders = {
+  canonicalHeaders: string;
+  signedHeaders: string;
+};
+
+export const AwsSigV4 = Object.freeze({
+  sha256Hex(data: string | Uint8Array): string {
+    return createHash('sha256').update(data).digest('hex');
+  },
+
+  hmacSha256(key: Uint8Array | string, data: string): Uint8Array {
+    return createHmac('sha256', key).update(data).digest();
+  },
+
+  toAmzDate(date: Date): { amzDate: string; dateStamp: string } {
+    const yyyy = String(date.getUTCFullYear());
+    const mm = String(date.getUTCMonth() + 1).padStart(2, '0');
+    const dd = String(date.getUTCDate()).padStart(2, '0');
+    const hh = String(date.getUTCHours()).padStart(2, '0');
+    const mi = String(date.getUTCMinutes()).padStart(2, '0');
+    const ss = String(date.getUTCSeconds()).padStart(2, '0');
+
+    const dateStamp = `${yyyy}${mm}${dd}`;
+    const amzDate = `${dateStamp}T${hh}${mi}${ss}Z`;
+    return { amzDate, dateStamp };
+  },
+
+  deriveSigningKey(params: {
+    secretAccessKey: string;
+    dateStamp: string;
+    region: string;
+    service: string;
+  }): Uint8Array {
+    const kDate = this.hmacSha256(`AWS4${params.secretAccessKey}`, params.dateStamp);
+    const kRegion = this.hmacSha256(kDate, params.region);
+    const kService = this.hmacSha256(kRegion, params.service);
+    return this.hmacSha256(kService, 'aws4_request');
+  },
+
+  canonicalizeHeaders(headers: Record<string, string>): CanonicalizedHeaders {
+    const sortedHeaderKeys = Object.keys(headers).sort((a, b) => a.localeCompare(b));
+
+    const canonicalHeaders = sortedHeaderKeys
+      .map((k) => `${k}:${String(headers[k]).trim().replaceAll(/\s+/g, ' ')}`)
+      .join('\n');
+
+    const signedHeaders = sortedHeaderKeys.join(';');
+
+    return { canonicalHeaders, signedHeaders };
+  },
+
+  buildAuthorization(params: {
+    method: string;
+    canonicalUri: string;
+    canonicalQueryString: string;
+    headers: Record<string, string>;
+    payloadHash: string;
+    region: string;
+    service: string;
+    amzDate: string;
+    dateStamp: string;
+    credentials: AwsSigV4Credentials;
+  }): { authorization: string; signedHeaders: string } {
+    const sessionToken = params.credentials.sessionToken;
+    if (
+      typeof sessionToken === 'string' &&
+      sessionToken.trim() !== '' &&
+      params.headers['x-amz-security-token'] === undefined
+    ) {
+      params.headers['x-amz-security-token'] = sessionToken;
+    }
+
+    const { canonicalHeaders, signedHeaders } = this.canonicalizeHeaders(params.headers);
+
+    const canonicalRequest = [
+      params.method,
+      params.canonicalUri,
+      params.canonicalQueryString,
+      `${canonicalHeaders}\n`,
+      signedHeaders,
+      params.payloadHash,
+    ].join('\n');
+
+    const algorithm = 'AWS4-HMAC-SHA256';
+    const credentialScope = `${params.dateStamp}/${params.region}/${params.service}/aws4_request`;
+    const stringToSign = [
+      algorithm,
+      params.amzDate,
+      credentialScope,
+      this.sha256Hex(canonicalRequest),
+    ].join('\n');
+
+    const signingKey = this.deriveSigningKey({
+      secretAccessKey: params.credentials.secretAccessKey,
+      dateStamp: params.dateStamp,
+      region: params.region,
+      service: params.service,
+    });
+
+    const signature = createHmac('sha256', signingKey).update(stringToSign).digest('hex');
+
+    const authorization =
+      `${algorithm} Credential=${params.credentials.accessKeyId}/${credentialScope}, ` +
+      `SignedHeaders=${signedHeaders}, Signature=${signature}`;
+
+    return { authorization, signedHeaders };
+  },
+});

package/src/common/ExternalServiceUtils.ts

@@ -0,0 +1,151 @@
+/**
+ * Shared Utilities for External Service Drivers
+ * Common patterns for API calls, environment variable reading, and error handling
+ */
+
+import { Env } from '@config/env';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+/**
+ * Environment variable reader with fallback support
+ * Handles both Env.get() and process.env for maximum compatibility
+ */
+export const readEnvString = (key: string, fallback = ''): string => {
+  const anyEnv = Env as { get?: (k: string, d?: string) => string };
+  const fromEnv = typeof anyEnv.get === 'function' ? anyEnv.get(key, '') : '';
+  if (typeof fromEnv === 'string' && fromEnv.trim() !== '') return fromEnv;
+  if (typeof process !== 'undefined') {
+    const raw = process.env?.[key];
+    if (typeof raw === 'string') return raw;
+  }
+  return fromEnv ?? fallback;
+};
+
+/**
+ * Validate required parameters for external service calls
+ */
+export const validateRequiredParams = (
+  params: Record<string, unknown>,
+  required: string[]
+): void => {
+  for (const param of required) {
+    const value = params[param];
+    if (
+      value === null ||
+      value === undefined ||
+      (typeof value === 'string' && value.length === 0)
+    ) {
+      throw ErrorFactory.createValidationError(`${param} is required`);
+    }
+  }
+};
+
+/**
+ * Create standardized API error response
+ */
+export const createApiError = (message: string, service: string): Error => {
+  return ErrorFactory.createValidationError(`${service} API error: ${message}`);
+};
+
+/**
+ * Common fetch wrapper with error handling
+ */
+export const safeFetch = async (url: string, options: RequestInit): Promise<Response> => {
+  try {
+    const response = await globalThis.fetch(url, options);
+
+    if (!response.ok) {
+      throw ErrorFactory.createValidationError(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    return response;
+  } catch (error) {
+    throw ErrorFactory.createValidationError(
+      error instanceof Error ? error.message : 'Unknown fetch error'
+    );
+  }
+};
+
+/**
+ * Standard API response builder
+ */
+export const buildApiResponse = <T>(
+  success: boolean,
+  data?: T,
+  error?: string
+): { success: boolean; data?: T; error?: string } => {
+  const response: { success: boolean; data?: T; error?: string } = { success };
+
+  if (data !== undefined) {
+    response.data = data;
+  }
+
+  if (error !== undefined) {
+    response.error = error;
+  }
+
+  return response;
+};
+
+/**
+ * Health check utilities
+ */
+export const HealthUtils = {
+  /**
+   * Get process uptime safely
+   */
+  getUptime(): number {
+    return typeof process !== 'undefined' && typeof process.uptime === 'function'
+      ? process.uptime()
+      : 0;
+  },
+
+  /**
+   * Get current timestamp
+   */
+  getTimestamp(): string {
+    return new Date().toISOString();
+  },
+
+  /**
+   * Check if in production
+   */
+  isProduction(environment: string): boolean {
+    return environment === 'production';
+  },
+
+  /**
+   * Build health response
+   */
+  buildHealthResponse(
+    status: 'healthy' | 'unhealthy' | 'alive' | 'ready' | 'not_ready',
+    environment: string,
+    extra?: Record<string, unknown>
+  ) {
+    const base = {
+      status,
+      timestamp: HealthUtils.getTimestamp(),
+      environment,
+      ...extra,
+    };
+
+    return base;
+  },
+
+  /**
+   * Build error health response
+   */
+  buildErrorResponse(
+    status: 'unhealthy' | 'not_ready',
+    environment: string,
+    error: Error,
+    extra?: Record<string, unknown>
+  ) {
+    const isProd = HealthUtils.isProduction(environment);
+
+    return HealthUtils.buildHealthResponse(status, environment, {
+      error: isProd ? 'Service unavailable' : error.message,
+      ...extra,
+    });
+  },
+};

package/src/common/HealthRoutes.ts

@@ -0,0 +1,144 @@
+/**
+ * Shared Health Route Handlers
+ * Extracted to eliminate duplication between CoreRoutes.ts and routes/health.ts
+ */
+
+import { appConfig } from '@/config/app';
+import { RuntimeHealthProbes } from '@/health/RuntimeHealthProbes';
+import type { IRequest } from '@/http/Request';
+import type { IResponse } from '@/http/Response';
+import { HealthUtils } from '@common/ExternalServiceUtils';
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+import type { IRouter } from '@core-routes/Router';
+import { Router } from '@core-routes/Router';
+import { useDatabase } from '@orm/Database';
+import { QueryBuilder } from '@orm/QueryBuilder';
+
+/**
+ * Health check endpoint handler
+ */
+async function handleHealthRoute(_req: IRequest, res: IResponse): Promise<void> {
+  const environment = Env.NODE_ENV ?? 'development';
+
+  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 = HealthUtils.getUptime();
+
+    res.json(
+      HealthUtils.buildHealthResponse('healthy', environment, {
+        uptime,
+        database: 'connected',
+      })
+    );
+  } catch (error) {
+    Logger.error('Health check failed:', error);
+
+    res.setStatus(503).json(
+      HealthUtils.buildErrorResponse('unhealthy', environment, error as Error, {
+        database: 'disconnected',
+      })
+    );
+  }
+}
+
+/**
+ * Liveness probe endpoint handler
+ */
+function handleHealthLiveRoute(_req: IRequest, res: IResponse): void {
+  const uptime = HealthUtils.getUptime();
+
+  res.json(
+    HealthUtils.buildHealthResponse('alive', Env.NODE_ENV ?? 'development', {
+      uptime,
+    })
+  );
+}
+
+/**
+ * Readiness probe endpoint handler
+ */
+async function handleHealthReadyRoute(_req: IRequest, res: IResponse): Promise<void> {
+  const startTime = Date.now();
+  const environment = appConfig.environment;
+
+  let databaseResponseTime: number | null = null;
+  let cacheResponseTime: number | null = null;
+
+  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;
+
+    cacheResponseTime = await RuntimeHealthProbes.pingKvCache(2000);
+
+    res.json(
+      HealthUtils.buildHealthResponse('ready', environment, {
+        dependencies: {
+          database: {
+            status: 'ready',
+            responseTime: databaseResponseTime,
+          },
+          ...(cacheResponseTime === null
+            ? {}
+            : {
+                cache: {
+                  status: 'ready',
+                  responseTime: cacheResponseTime,
+                },
+              }),
+        },
+      })
+    );
+  } catch (error) {
+    Logger.error('Readiness check failed:', error);
+
+    const responseTime = Date.now() - startTime;
+
+    const dependencies: Record<string, unknown> = {
+      database: {
+        status: databaseResponseTime === null ? 'unavailable' : 'ready',
+        responseTime: databaseResponseTime ?? responseTime,
+      },
+    };
+
+    if (RuntimeHealthProbes.getCacheDriverName() === 'kv') {
+      dependencies['cache'] = {
+        status: 'unavailable',
+        responseTime: cacheResponseTime ?? responseTime,
+      };
+    }
+
+    res.setStatus(503).json(
+      HealthUtils.buildErrorResponse('not_ready', environment, error as Error, {
+        dependencies,
+      })
+    );
+  }
+}
+
+/**
+ * Register all health routes
+ */
+export const registerHealthRoutes = (router: IRouter): void => {
+  Router.get(router, '/health', handleHealthRoute);
+  Router.get(router, '/health/live', handleHealthLiveRoute);
+  Router.get(router, '/health/ready', handleHealthReadyRoute);
+};