@zintrust/core 0.4.17 → 0.4.19

package/src/node-singletons/index.ts

@@ -1,38 +0,0 @@
-/**
- * Node.js Singleton Modules
- * Centralized exports for all node:* imports
- * This allows conditional loading and runtime-aware imports
- *
- * Safe for all runtimes (API, CLI, Serverless):
- * - http
- * - crypto
- * - events
- * - perf-hooks
- *
- * CLI-only (Node.js):
- * - fs
- * - path
- * - child-process
- * - url
- * - os
- * - readline
- */
-
-// Safe for all runtimes
-export * from '@node-singletons/async_hooks';
-export * from '@node-singletons/crypto';
-export * from '@node-singletons/events';
-export * from '@node-singletons/http';
-export * from '@node-singletons/perf-hooks';
-export * as process from '@node-singletons/process';
-
-// CLI-only (should not be imported in API code)
-export * as childProcess from '@node-singletons/child-process';
-export * as fs from '@node-singletons/fs';
-export * as module from '@node-singletons/module';
-export * as net from '@node-singletons/net';
-export * as os from '@node-singletons/os';
-export * as path from '@node-singletons/path';
-export * as readline from '@node-singletons/readline';
-export * as tls from '@node-singletons/tls';
-export * as url from '@node-singletons/url';

package/src/node-singletons/module.ts

@@ -1,12 +0,0 @@
-/**
- * Node.js Module Singleton
- * Wrapper for node:module imports
- * CLI-only - should not be imported in API code
- */
-
-import * as module from 'node:module';
-
-export { createRequire } from 'node:module';
-
-// Default export for compatibility
-export default module;

package/src/node-singletons/net.ts

@@ -1,10 +0,0 @@
-/**
- * node-singletons/net
- * Centralized export for Node's net module.
- * NOTE: Node-only.
- */
-
-import * as net from 'node:net';
-
-export default net;
-export * from 'node:net';

package/src/node-singletons/os.ts

@@ -1,20 +0,0 @@
-/**
- * Node.js OS Module Singleton
- * CLI-only: Should not be imported in API/serverless code
- * Exported from node:os built-in
- */
-
-import * as os from 'node:os';
-
-export const arch = os.arch;
-export const cpus = os.cpus;
-export const freemem = os.freemem;
-export const hostname = os.hostname;
-export const loadavg = os.loadavg;
-export const platform = os.platform;
-export const tmpdir = os.tmpdir;
-export const totalmem = os.totalmem;
-export const type = os.type;
-export const uptime = os.uptime;
-
-export default os;

package/src/node-singletons/path.ts

@@ -1,12 +0,0 @@
-/**
- * Node.js Path Module Singleton
- * CLI-only: Should not be imported in API/serverless code
- * Exported from node:path built-in
- */
-
-import * as path from 'node:path';
-
-export const { basename, delimiter, dirname, extname, join, relative, resolve, sep, posix, win32 } =
-  path;
-
-export default path;

package/src/node-singletons/perf-hooks.ts

@@ -1,11 +0,0 @@
-/**
- * Node.js Performance Hooks Module Singleton
- * Safe to import in both API and CLI code
- * Exported from node:perf_hooks built-in
- */
-
-import * as perf_hooks from 'node:perf_hooks';
-
-export const { performance } = perf_hooks;
-
-export default perf_hooks;

package/src/node-singletons/process.ts

@@ -1,58 +0,0 @@
-/**
- * Node.js Process Module Singleton
- * Safe to import in both API and CLI code
- * Exported from node:process built-in
- */
-
-import * as processModule from 'node:process';
-
-export const {
-  arch,
-  argv,
-  argv0,
-  chdir,
-  config,
-  connected,
-  cpuUsage,
-  cwd,
-  debugPort,
-  disconnect,
-  emitWarning,
-  env,
-  execArgv,
-  execPath,
-  exit,
-  exitCode,
-  getegid,
-  geteuid,
-  getgid,
-  getgroups,
-  getuid,
-  hasUncaughtExceptionCaptureCallback,
-  hrtime,
-  kill,
-  memoryUsage,
-  nextTick,
-  pid,
-  platform,
-  ppid,
-  release,
-  report,
-  resourceUsage,
-  setegid,
-  seteuid,
-  setgid,
-  setgroups,
-  setuid,
-  setUncaughtExceptionCaptureCallback,
-  stderr,
-  stdin,
-  stdout,
-  title,
-  umask,
-  uptime,
-  version,
-  versions,
-} = processModule;
-
-export default processModule;

package/src/node-singletons/readline.ts

@@ -1,12 +0,0 @@
-/**
- * Node.js Readline Module Singleton
- * CLI-only: Should not be imported in API/serverless code
- * Exported from node:readline built-in
- */
-
-import * as readline from 'node:readline';
-
-export const { createInterface, cursorTo } = readline;
-export type { Interface } from 'node:readline';
-
-export default readline;

package/src/node-singletons/stream.ts

@@ -1,19 +0,0 @@
-/**
- * Node.js Stream Module Singleton
- * CLI-only: Should not be imported in API/serverless code
- * Exported from node:stream built-in
- */
-
-import * as stream from 'node:stream';
-
-export const { Readable, Writable, Duplex, Transform, PassThrough, pipeline, finished } = stream;
-
-export type {
-  DuplexOptions,
-  ReadableOptions,
-  TransformOptions,
-  WritableOptions,
-} from 'node:stream';
-export type { ReadableStream, WritableStream } from 'node:stream/web';
-
-export default stream;

package/src/node-singletons/tls.ts

@@ -1,10 +0,0 @@
-/**
- * node-singletons/tls
- Centralized export for Node's tls module.
- * NOTE: Node-only.
- */
-
-import * as tls from 'node:tls';
-
-export default tls;
-export * from 'node:tls';

package/src/node-singletons/url.ts

@@ -1,11 +0,0 @@
-/**
- * Node.js URL Module Singleton
- * CLI-only: Should not be imported in API/serverless code
- * Exported from node:url built-in
- */
-
-import * as url from 'node:url';
-
-export const { fileURLToPath, pathToFileURL } = url;
-
-export default url;

package/src/node-singletons/util.ts

@@ -1,6 +0,0 @@
-/**
- * Node built-in util singleton
- * Avoids issues with stubbing in tests
- */
-
-export * from 'node:util';

package/src/node.ts

@@ -1,37 +0,0 @@
-import { Logger } from '@config/logger';
-// Runtime marker to make this re-export-only module coverable in V8 coverage.
-const __coverageMarker = true;
-if (__coverageMarker !== true) {
-  throw Logger.error('Unreachable');
-}
-
-export * as crypto from '@node-singletons/crypto';
-export * as fs from '@node-singletons/fs';
-export * as path from '@node-singletons/path';
-export { performance } from '@node-singletons/perf-hooks';
-export { default, default as process } from '@node-singletons/process';
-export * as url from '@node-singletons/url';
-
-export { cleanOnce, FileLogWriter } from '@config/FileLogWriter';
-
-export { listTemplates, loadTemplate, renderTemplate } from '@mail/templates';
-export { MailFake } from '@mail/testing';
-
-export { FakeStorage } from '@tools/storage/testing';
-
-export { TestEnvironment, TestHttp } from '@/testing/index';
-export type {
-  ITestEnvironment,
-  TestEnvironmentOptions,
-  TestHeaders,
-  TestHttpRequestInput,
-  TestHttpResponseRecorder,
-  TestRequestInput,
-  TestResponse,
-} from '@/testing/index';
-
-export {
-  listTemplates as listNotificationTemplates,
-  loadTemplate as loadNotificationTemplate,
-  renderTemplate as renderNotificationTemplate,
-} from '@notification/templates/markdown';

package/src/observability/OpenTelemetry.ts

@@ -1,362 +0,0 @@
-/**
- * Optional OpenTelemetry integration.
- *
- * Design goals:
- * - No hard dependency on SDKs/exporters (apps bring their own).
- * - Safe to import in runtimes without tracing configured (no-op behavior).
- * - Best-effort: never breaks request handling.
- *
- * Tiny Node enablement snippet (exporter is app-owned):
- *
- *   npm i @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node \
- *     @opentelemetry/exporter-trace-otlp-http
- *
- *   // in your app entrypoint (before creating the server)
- *   import { NodeSDK } from '@opentelemetry/sdk-node';
- *   import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
- *   import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
- *
- *   const sdk = new NodeSDK({
- *     traceExporter: new OTLPTraceExporter({ url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT }),
- *     instrumentations: [getNodeAutoInstrumentations()],
- *   });
- *   await sdk.start();
- *   process.env.OTEL_ENABLED = 'true';
- */
-
-import { Env } from '@config/env';
-import { createRequire } from '@node-singletons/module';
-import type { Context, Span } from '@opentelemetry/api';
-
-type OpenTelemetryApi = typeof import('@opentelemetry/api');
-
-let cachedApi: OpenTelemetryApi | null | undefined;
-
-const resolveOpenTelemetryApi = (): OpenTelemetryApi | null => {
-  if (cachedApi !== undefined) return cachedApi;
-
-  // Check for injected API (used for testing)
-  const injected = (globalThis as unknown as { __zintrustOpenTelemetryApi?: unknown })
-    .__zintrustOpenTelemetryApi;
-  if (injected !== undefined && injected !== null) {
-    cachedApi = injected as OpenTelemetryApi;
-    return cachedApi;
-  }
-
-  try {
-    const require = createRequire(import.meta.url);
-
-    cachedApi = require('@opentelemetry/api') as OpenTelemetryApi;
-    return cachedApi;
-  } catch {
-    cachedApi = null;
-    return null;
-  }
-};
-
-const noopSpan: Span = {
-  setAttribute: () => undefined,
-  updateName: () => undefined,
-  setStatus: () => undefined,
-  end: () => undefined,
-} as unknown as Span;
-
-const fallbackContext = {
-  active: () => ({}) as Context,
-  with: <A extends unknown[], F extends (...args: A) => ReturnType<F>>(
-    _ctx: Context,
-    fn: F,
-    _thisArg?: ThisParameterType<F>,
-    ...args: A
-  ): ReturnType<F> => fn(...args),
-};
-
-const fallbackPropagation = {
-  extract: (_ctx: Context) => _ctx,
-  inject: () => undefined,
-};
-
-const fallbackTrace = {
-  getTracer: () => ({
-    startSpan: (_name?: string, _options?: unknown, _context?: Context): Span => noopSpan,
-  }),
-  getSpan: (_ctx?: Context) => undefined,
-  setSpan: (ctx: Context) => ctx,
-};
-
-const fallbackSpanKind = {
-  SERVER: 1,
-  CLIENT: 2,
-} as const;
-
-const fallbackSpanStatusCode = {
-  OK: 1,
-  ERROR: 2,
-} as const;
-
-const resolveSpanStatusCode = (): typeof fallbackSpanStatusCode => {
-  return otel()?.SpanStatusCode ?? fallbackSpanStatusCode;
-};
-
-const resolveTracingContext = (): {
-  traceApi: OpenTelemetryApi['trace'] | typeof fallbackTrace;
-  activeContext: Context;
-  spanKind: typeof fallbackSpanKind;
-} => {
-  const api = otel();
-  return {
-    traceApi: api?.trace ?? fallbackTrace,
-    activeContext: api?.context?.active() ?? fallbackContext.active(),
-    spanKind: api?.SpanKind ?? fallbackSpanKind,
-  };
-};
-
-const otel = (): OpenTelemetryApi | null => resolveOpenTelemetryApi();
-
-export interface StartHttpServerSpanInput {
-  method: string;
-  path: string;
-  requestId?: string;
-  serviceName?: string;
-  userId?: string;
-  tenantId?: string;
-  userAgent?: string;
-}
-
-export interface EndHttpServerSpanInput {
-  route?: string;
-  status?: number;
-  error?: unknown;
-}
-
-export interface StartedSpan {
-  span: Span;
-  context: Context;
-}
-
-export interface RecordDbQuerySpanInput {
-  driver: string;
-  durationMs: number;
-}
-
-export interface RecordQueueOperationSpanInput {
-  queueName: string;
-  operation: 'enqueue' | 'dequeue' | 'ack' | 'length' | 'drain';
-  durationMs: number;
-  status: 'ok' | 'error';
-}
-
-type HeaderGetter = {
-  getHeader(name: string): unknown;
-};
-
-const isEnabled = (): boolean => {
-  return Env.getBool('OTEL_ENABLED', false);
-};
-
-const extractContextFromHeaders = (req: HeaderGetter): Context => {
-  const active = otel()?.context?.active() ?? fallbackContext.active();
-
-  try {
-    const extractor = otel()?.propagation?.extract ?? fallbackPropagation.extract;
-    return extractor(active, req, {
-      get(carrier: HeaderGetter, key: string) {
-        const value = carrier.getHeader(key);
-        if (typeof value === 'string') return value;
-        if (Array.isArray(value)) return value.join(',');
-        return undefined;
-      },
-      keys() {
-        return [];
-      },
-    });
-  } catch {
-    return active;
-  }
-};
-
-const startHttpServerSpan = (req: HeaderGetter, input: StartHttpServerSpanInput): StartedSpan => {
-  const parent = extractContextFromHeaders(req);
-  const tracer = (otel()?.trace ?? fallbackTrace).getTracer('zintrust');
-
-  const span = tracer.startSpan(
-    `${input.method} unmatched`,
-    {
-      kind: (otel()?.SpanKind ?? fallbackSpanKind).SERVER,
-      attributes: {
-        'http.method': input.method,
-        'http.target': input.path,
-        'http.user_agent': input.userAgent ?? '',
-        'service.name': input.serviceName ?? '',
-        'enduser.id': input.userId ?? '',
-        'zintrust.tenant_id': input.tenantId ?? '',
-        'zintrust.request_id': input.requestId ?? '',
-      },
-    },
-    parent
-  );
-
-  const spanContext = (otel()?.trace ?? fallbackTrace).setSpan(parent, span);
-  return { span, context: spanContext };
-};
-
-const runWithContext = async <T>(ctx: Context, fn: () => Promise<T>): Promise<T> => {
-  const runner = otel()?.context?.with ?? fallbackContext.with;
-  return runner(ctx, fn);
-};
-
-const setHttpRoute = (span: Span, method: string, route: string): void => {
-  try {
-    span.setAttribute('http.route', route);
-    span.updateName(`${method} ${route}`);
-  } catch {
-    // best-effort
-  }
-};
-
-const endHttpServerSpan = (span: Span, input: EndHttpServerSpanInput): void => {
-  try {
-    if (input.route !== undefined && input.route.trim() !== '') {
-      span.setAttribute('http.route', input.route);
-    }
-
-    if (typeof input.status === 'number') {
-      span.setAttribute('http.status_code', input.status);
-
-      if (input.status >= 500) {
-        span.setStatus({ code: (otel()?.SpanStatusCode ?? fallbackSpanStatusCode).ERROR });
-      } else {
-        span.setStatus({ code: (otel()?.SpanStatusCode ?? fallbackSpanStatusCode).OK });
-      }
-    }
-
-    if (input.error !== undefined) {
-      // Avoid throwing; represent as a string attribute.
-      span.setAttribute(
-        'zintrust.error',
-        input.error instanceof Error ? input.error.message : String(input.error)
-      );
-      span.setStatus({ code: (otel()?.SpanStatusCode ?? fallbackSpanStatusCode).ERROR });
-    }
-
-    span.end();
-  } catch {
-    // best-effort
-  }
-};
-
-const injectTraceHeaders = (headers: Record<string, string>): Record<string, string> => {
-  try {
-    const injector = otel()?.propagation?.inject ?? fallbackPropagation.inject;
-    injector(otel()?.context?.active() ?? fallbackContext.active(), headers);
-  } catch {
-    // best-effort
-  }
-
-  return headers;
-};
-
-const mapDbSystem = (driver: string): string => {
-  switch (driver) {
-    case 'postgresql':
-      return 'postgresql';
-    case 'mysql':
-      return 'mysql';
-    case 'sqlserver':
-      return 'mssql';
-    case 'd1':
-    case 'd1-remote':
-    case 'sqlite':
-    default:
-      return 'sqlite';
-  }
-};
-
-const recordDbQuerySpan = (input: RecordDbQuerySpanInput): void => {
-  if (isEnabled() === false) return;
-
-  try {
-    // Only create a DB span if we're already inside a request trace.
-    const traceApi = otel()?.trace ?? fallbackTrace;
-    const parentSpan = traceApi.getSpan(otel()?.context?.active() ?? fallbackContext.active());
-    if (!parentSpan) return;
-
-    const tracer = traceApi.getTracer('zintrust');
-    const now = Date.now();
-    const durationMs = Number.isFinite(input.durationMs) ? Math.max(0, input.durationMs) : 0;
-    const startTime = now - durationMs;
-
-    const span = tracer.startSpan(
-      'db.query',
-      {
-        kind: (otel()?.SpanKind ?? fallbackSpanKind).CLIENT,
-        startTime,
-        attributes: {
-          'db.system': mapDbSystem(input.driver),
-          'db.operation': 'query',
-          'zintrust.db.driver': input.driver,
-        },
-      },
-      otel()?.context?.active() ?? fallbackContext.active()
-    );
-
-    span.end(now);
-  } catch {
-    // best-effort
-  }
-};
-
-const recordQueueOperationSpan = (input: RecordQueueOperationSpanInput): void => {
-  if (isEnabled() === false) return;
-
-  try {
-    const tracing = resolveTracingContext();
-    const parentSpan = tracing.traceApi.getSpan(tracing.activeContext);
-    if (!parentSpan) return;
-
-    const tracer = tracing.traceApi.getTracer('zintrust');
-    const now = Date.now();
-    const durationMs = Number.isFinite(input.durationMs) ? Math.max(0, input.durationMs) : 0;
-    const startTime = now - durationMs;
-
-    const span = tracer.startSpan(
-      `queue.${input.operation}`,
-      {
-        kind: tracing.spanKind.CLIENT,
-        startTime,
-        attributes: {
-          'messaging.system': 'zintrust-queue',
-          'messaging.operation': input.operation,
-          'messaging.destination': input.queueName,
-          'zintrust.queue.status': input.status,
-        },
-      },
-      tracing.activeContext
-    );
-
-    const statusCode = resolveSpanStatusCode();
-
-    if (input.status === 'error') {
-      span.setStatus({ code: statusCode.ERROR });
-    } else {
-      span.setStatus({ code: statusCode.OK });
-    }
-
-    span.end(now);
-  } catch {
-    // best-effort
-  }
-};
-
-export const OpenTelemetry = Object.freeze({
-  isEnabled,
-  startHttpServerSpan,
-  runWithContext,
-  setHttpRoute,
-  endHttpServerSpan,
-  injectTraceHeaders,
-  recordDbQuerySpan,
-  recordQueueOperationSpan,
-});
-
-export default OpenTelemetry;