@zintrust/core 0.4.15 → 0.4.17

package/src/tools/notification/templates/markdown/registry.ts

@@ -0,0 +1,45 @@
+import { readdirSync, statSync } from '@node-singletons/fs';
+import { join, relative } from '@node-singletons/path';
+import { loadTemplate } from '@notification/templates/markdown';
+import { MarkdownRenderer } from '@tools/templates';
+
+const BASE = join(process.cwd(), 'src', 'tools', 'notification', 'templates', 'markdown');
+
+const walkDir = (dir: string, base = dir): string[] => {
+  const entries = readdirSync(dir);
+  let files: string[] = [];
+  for (const e of entries) {
+    const p = join(dir, e);
+    const s = statSync(p);
+    if (s.isDirectory()) {
+      files = files.concat(walkDir(p, base));
+      continue;
+    }
+    if (e.endsWith('.md')) {
+      const rel = relative(base, p).replaceAll('\\', '/');
+      const withoutExt = rel.toLowerCase().endsWith('.md') ? rel.slice(0, -3) : rel;
+      files.push(withoutExt);
+    }
+  }
+  return files;
+};
+
+export const listTemplates = (): string[] => {
+  return walkDir(BASE);
+};
+
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+export const renderTemplate = (
+  name: string,
+  vars: Record<string, unknown> = {}
+): { html: string; meta: ReturnType<typeof loadTemplate> } => {
+  const tpl = loadTemplate(name);
+  // Basic validation: subject required
+  if (tpl.subject === null || tpl.subject === undefined || tpl.subject.trim() === '')
+    throw ErrorFactory.createValidationError('Notification template missing subject', { name });
+  const html = MarkdownRenderer.render(tpl.content, vars);
+  return { html, meta: tpl };
+};
+
+export default { listTemplates, renderTemplate };

package/src/tools/notification/testing.ts

@@ -0,0 +1,50 @@
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+type SentRecord = {
+  provider: string;
+  payload: unknown;
+  config: unknown;
+};
+
+export const NotificationFake = Object.freeze({
+  _sent: [] as Array<SentRecord>,
+
+  async send(provider: string, config: unknown, payload: unknown): Promise<{ ok: boolean }> {
+    this._sent.push({ provider, config, payload });
+    await Promise.resolve();
+    return { ok: true };
+  },
+
+  assertSent(predicate: (r: SentRecord) => boolean) {
+    if (!this._sent.some(predicate))
+      throw ErrorFactory.createValidationError('Expected notification to be sent');
+  },
+
+  assertNotSent(predicate: (r: SentRecord) => boolean) {
+    if (this._sent.some(predicate))
+      throw ErrorFactory.createValidationError('Expected notification to NOT be sent');
+  },
+
+  assertSentCount(expected: number) {
+    if (this._sent.length !== expected) {
+      throw ErrorFactory.createValidationError('Unexpected notification send count', {
+        expected,
+        actual: this._sent.length,
+      });
+    }
+  },
+
+  getSent(): Array<SentRecord> {
+    return [...this._sent];
+  },
+
+  lastSent(): SentRecord | undefined {
+    return this._sent.length > 0 ? this._sent.at(-1) : undefined;
+  },
+
+  reset() {
+    this._sent.length = 0;
+  },
+});
+
+export default NotificationFake;

package/src/tools/notification/testingHelpers.ts

@@ -0,0 +1,44 @@
+import { Env } from '@config/env';
+import { NotificationRegistry } from '@notification/Registry';
+import NotificationFake from '@notification/testing';
+
+// NOTE: This testing helper intentionally mutates runtime env values
+// via Env.set() to temporarily override NOTIFICATION_DRIVER for test isolation.
+
+type DriverLike = {
+  send(recipient: string, message: string, options?: Record<string, unknown>): Promise<unknown>;
+};
+
+export const useFakeDriver = (
+  name = 'notification-fake',
+  fake: unknown = NotificationFake
+): { driverName: string; restore: () => void } => {
+  let previous: DriverLike | undefined;
+  try {
+    previous = NotificationRegistry.get(name) as DriverLike;
+  } catch {
+    previous = undefined;
+  }
+
+  const fakeDriver = fake as DriverLike;
+  NotificationRegistry.register(name, fakeDriver);
+  const prevEnv = Env.get('NOTIFICATION_DRIVER', '');
+  Env.set('NOTIFICATION_DRIVER', name);
+
+  return {
+    driverName: name,
+    restore() {
+      // Restore previous driver if present, otherwise keep fake registered
+      if (previous === undefined) {
+        NotificationRegistry.register(name, NotificationFake as unknown as DriverLike);
+      } else {
+        NotificationRegistry.register(name, previous);
+      }
+
+      if (prevEnv === '') Env.unset('NOTIFICATION_DRIVER');
+      else Env.set('NOTIFICATION_DRIVER', prevEnv);
+    },
+  };
+};
+
+export default { useFakeDriver };

package/src/tools/queue/AdvancedQueue.ts

@@ -0,0 +1,456 @@
+/**
+ * Advanced Queue Implementation
+ * Extends ZinTrust queue functionality with deduplication and lock management
+ */
+
+import type {
+  AdvancedJobOptions,
+  DeduplicationOptions,
+  JobResult,
+  LockProvider,
+  LockProviderConfig,
+  QueueConfig,
+} from '@/types/Queue';
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+import { queueConfig } from '@config/queue';
+import type { QueueDriverName } from '@config/type';
+import { createValidationError } from '@exceptions/ZintrustError';
+import { ZintrustLang } from '@lang/lang';
+import { type DeduplicationBuilder } from '@queue/DeduplicationBuilder';
+import { createLockProvider, getLockProvider, registerLockProvider } from '@queue/LockProvider';
+import type { BullMQPayload } from '@queue/Queue';
+import { Queue, resolveLockPrefix } from '@queue/Queue';
+
+export interface AdvancedQueue {
+  enqueue(name: string, payload: BullMQPayload, options: AdvancedJobOptions): Promise<string>;
+  deduplicate(id: string, builder: DeduplicationBuilder): Promise<JobResult>;
+  releaseLock(key: string): Promise<void>;
+  extendLock(key: string, ttl: number): Promise<boolean>;
+}
+
+/**
+ * Creates an advanced queue instance with deduplication capabilities
+ * @param config - Queue configuration
+ * @returns {AdvancedQueue} Advanced queue instance
+ */
+export function createAdvancedQueue(config: QueueConfig): AdvancedQueue {
+  const lockProviderName = resolveLockProviderName(config);
+  const lockProvider = initializeLockProvider(lockProviderName, config);
+
+  return {
+    enqueue: async (name: string, payload: BullMQPayload, options: AdvancedJobOptions) =>
+      enqueueWithDeduplication(name, payload, options, lockProvider),
+    // eslint-disable-next-line @typescript-eslint/require-await
+    deduplicate: async (_id: string, _builder: DeduplicationBuilder): Promise<JobResult> => {
+      throw createValidationError(
+        'deduplicate() method should be used via enqueue() with deduplication options'
+      );
+    },
+    releaseLock: async (key: string): Promise<void> => releaseLock(key, lockProvider),
+    extendLock: async (key: string, ttl: number): Promise<boolean> =>
+      extendLock(key, ttl, lockProvider),
+  };
+}
+
+/**
+ * Initialize lock provider for the advanced queue
+ */
+function initializeLockProvider(lockProviderName: string, config: QueueConfig): LockProvider {
+  // Initialize default lock provider if not exists
+  const getLock = getLockProvider(lockProviderName);
+  if (getLock === undefined) {
+    const lockConfig: LockProviderConfig = {
+      type: lockProviderName === ZintrustLang.REDIS ? ZintrustLang.REDIS : ZintrustLang.MEMORY,
+      prefix: resolveLockPrefix(),
+      defaultTtl: resolveDefaultLockTtl(config),
+    };
+    registerLockProvider(lockProviderName, createLockProvider(lockConfig));
+  }
+
+  const provider = getLockProvider(lockProviderName);
+  if (provider === undefined) {
+    throw createValidationError(`Failed to initialize lock provider: ${lockProviderName}`);
+  }
+
+  return provider;
+}
+
+function resolveLockProviderName(config: QueueConfig): string {
+  const envProvider: QueueDriverName = queueConfig.default;
+  if (
+    config.lockProvider !== undefined &&
+    config.lockProvider !== null &&
+    config.lockProvider.length > 0
+  )
+    return config.lockProvider;
+  if (envProvider.length > 0) return envProvider;
+  return ZintrustLang.MEMORY;
+}
+
+function resolveDefaultLockTtl(config: QueueConfig): number {
+  return Env.getInt(
+    'QUEUE_DEFAULT_DEDUP_TTL',
+    config.defaultDedupTtl ?? ZintrustLang.ZINTRUST_LOCKS_TTL
+  );
+}
+
+function resolveMaxLockTtl(): number | undefined {
+  const max = Env.getInt('QUEUE_MAX_LOCK_TTL', 0);
+  if (max <= 0) return undefined;
+  return max;
+}
+
+/**
+ * Handle uniqueId validation
+ */
+function validateUniqueIdOptions(options: AdvancedJobOptions): void {
+  if (options.uniqueId !== null && options.uniqueId !== undefined && options.uniqueId !== '') {
+    const validation = validateUniqueId(options.uniqueId);
+    if (!validation.valid) {
+      throw createValidationError(`Invalid uniqueId: ${validation.reason}`);
+    }
+  }
+}
+
+function validateDeduplicationOptions(options: AdvancedJobOptions): void {
+  if (!options.deduplication) return;
+
+  const maxTtl = resolveMaxLockTtl();
+  if (maxTtl !== undefined && options.deduplication.ttl !== undefined) {
+    if (options.deduplication.ttl > maxTtl) {
+      throw createValidationError(
+        `Deduplication TTL exceeds QUEUE_MAX_LOCK_TTL (${options.deduplication.ttl} > ${maxTtl})`
+      );
+    }
+  }
+}
+
+const QUEUE_META_KEY = '__zintrustQueueMeta';
+
+type QueueMeta = {
+  deduplicationId?: string;
+  releaseAfter?: AdvancedJobOptions['deduplication'] extends { releaseAfter?: infer T }
+    ? T
+    : unknown;
+  uniqueId?: string;
+};
+
+function shouldAttachReleaseAfterMeta(options: AdvancedJobOptions): boolean {
+  if (options.deduplication?.releaseAfter === undefined) return false;
+  return typeof options.deduplication.releaseAfter !== 'number';
+}
+
+function attachQueueMeta(
+  payload: BullMQPayload,
+  options: AdvancedJobOptions
+): { payload: BullMQPayload; metaAttached: boolean } {
+  if (!shouldAttachReleaseAfterMeta(options)) {
+    return { payload, metaAttached: false };
+  }
+
+  if (payload === null || payload === undefined || typeof payload !== 'object') {
+    return { payload, metaAttached: false };
+  }
+
+  const meta: QueueMeta = {
+    deduplicationId: options.deduplication?.id,
+    releaseAfter: options.deduplication?.releaseAfter,
+    uniqueId: options.uniqueId,
+  };
+
+  return {
+    payload: {
+      ...payload,
+      [QUEUE_META_KEY]: meta,
+    },
+    metaAttached: true,
+  };
+}
+
+/**
+ * Handle deduplication logic
+ */
+async function handleDeduplicationLogic(
+  options: AdvancedJobOptions,
+  lockProvider: LockProvider,
+  name: string,
+  startTime: number
+): Promise<string | null> {
+  if (!options.deduplication) {
+    return null;
+  }
+
+  const deduplicationResult = await handleDeduplication(options.deduplication, lockProvider);
+
+  if (deduplicationResult.deduplicated) {
+    Logger.info('Job deduplicated', {
+      queueName: name,
+      deduplicationId: options.deduplication.id,
+      duration: Date.now() - startTime,
+    });
+
+    return deduplicationResult.lockId ?? ZintrustLang.DEDUPLICATED;
+  }
+
+  // Handle releaseAfter (numeric delay)
+  if (
+    options.deduplication?.releaseAfter !== undefined &&
+    typeof options.deduplication.releaseAfter === 'number' &&
+    deduplicationResult.lockId !== null &&
+    deduplicationResult.lockId !== undefined &&
+    deduplicationResult.lockId !== ''
+  ) {
+    const delay = options.deduplication.releaseAfter;
+    // lockId from handleDeduplication (via acquire) already has prefix?
+    // acquire returns lock.key which INCLUDES prefix.
+    // releaseLock() calls lockProvider.status(key) which ADDS prefix.
+    // So if we pass lockId (with prefix) to releaseLock, lockProvider.status will double prefix?
+    // Let's check LockProvider.ts.
+    // acquire: lockKey = `${prefix}${key}`. Returns lock.key = lockKey.
+    // releaseLock (AdvancedQueue): calls lockProvider.status(key).
+    // lockProvider.status: lockKey = `${prefix}${key}`.
+    // So releaseLock expects 'id' (without prefix).
+    // deduplicationResult.lockId is lock.key (WITH prefix).
+    // deduplicationResult.id is the original ID.
+    const lockId = options.deduplication.id; // Use the original ID
+
+    // Create timeout with proper cleanup tracking
+    // Using unref() to prevent blocking process exit
+    // eslint-disable-next-line no-restricted-syntax
+    const timeoutId = setTimeout(async () => {
+      try {
+        await releaseLock(lockId, lockProvider);
+        Logger.debug('Released lock after delay', { lockId, delay });
+      } catch (error) {
+        Logger.error('Failed to release lock after delay', { lockId, error });
+      }
+    }, delay);
+
+    // Prevent Node.js from keeping the event loop alive
+    timeoutId.unref();
+  }
+
+  // Store lock reference for manual release info
+  if (
+    deduplicationResult.lockId !== null &&
+    deduplicationResult.lockId !== undefined &&
+    deduplicationResult.lockId !== ''
+  ) {
+    // In real implementation, this would be stored for later reference
+    Logger.debug('Lock created for job', {
+      lockId: deduplicationResult.lockId,
+      deduplicationId: options.deduplication.id,
+    });
+  }
+
+  return null;
+}
+
+/**
+ * Enqueue a job with advanced deduplication options
+ */
+async function enqueueWithDeduplication(
+  name: string,
+  payload: BullMQPayload,
+  options: AdvancedJobOptions,
+  defaultLockProvider: LockProvider
+): Promise<string> {
+  const startTime = Date.now();
+
+  try {
+    // Handle uniqueId validation
+    validateUniqueIdOptions(options);
+    validateDeduplicationOptions(options);
+
+    // Determine lock provider (uniqueVia override)
+    let lockProvider = defaultLockProvider;
+    if (options.uniqueVia !== null && options.uniqueVia !== undefined && options.uniqueVia !== '') {
+      const customProvider = getLockProvider(options.uniqueVia);
+      if (!customProvider) {
+        throw createValidationError(`Lock provider not found: ${options.uniqueVia}`);
+      }
+      lockProvider = customProvider;
+    }
+
+    // Handle deduplication
+    const deduplicationResult = await handleDeduplicationLogic(
+      options,
+      lockProvider,
+      name,
+      startTime
+    );
+    if (deduplicationResult !== null) {
+      return deduplicationResult;
+    }
+
+    const { payload: payloadToSend, metaAttached } = attachQueueMeta(payload, options);
+
+    if (!metaAttached && shouldAttachReleaseAfterMeta(options)) {
+      Logger.warn(
+        'releaseAfter condition metadata could not be attached; payload is not an object',
+        {
+          queueName: name,
+          releaseAfter: options.deduplication?.releaseAfter,
+        }
+      );
+    }
+
+    // Enqueue the job using existing queue system
+    const jobId = await Queue.enqueue(name, payloadToSend);
+
+    Logger.info('Job enqueued successfully', {
+      queueName: name,
+      jobId,
+      uniqueId: options.uniqueId,
+      duration: Date.now() - startTime,
+    });
+
+    return jobId ?? '';
+  } catch (error) {
+    Logger.error('Failed to enqueue job', {
+      queueName: name,
+      uniqueId: options.uniqueId,
+      error,
+    });
+    throw error;
+  }
+}
+
+/**
+ * Release a lock by key
+ */
+async function releaseLock(key: string, lockProvider: LockProvider): Promise<void> {
+  try {
+    const lockStatus = await lockProvider.status(key);
+    if (!lockStatus.exists) {
+      Logger.warn('Attempted to release non-existent lock', { key });
+      return;
+    }
+
+    // Create lock object for release
+    const lock = {
+      key,
+      ttl: lockStatus.ttl ?? 0,
+      acquired: true,
+      expires: lockStatus.expires ?? new Date(),
+    };
+
+    await lockProvider.release(lock);
+    Logger.info('Lock released successfully', { key });
+  } catch (error) {
+    Logger.error('Failed to release lock', { key, error });
+    throw error;
+  }
+}
+
+/**
+ * Extend a lock's TTL
+ */
+async function extendLock(key: string, ttl: number, lockProvider: LockProvider): Promise<boolean> {
+  try {
+    const lockStatus = await lockProvider.status(key);
+    if (!lockStatus.exists) {
+      Logger.warn('Attempted to extend non-existent lock', { key });
+      return false;
+    }
+
+    // Create lock object for extension
+    const lock = {
+      key,
+      ttl: lockStatus.ttl ?? 0,
+      acquired: true,
+      expires: lockStatus.expires ?? new Date(),
+    };
+
+    const extended = await lockProvider.extend(lock, ttl);
+
+    if (extended) {
+      Logger.info('Lock extended successfully', { key, ttl });
+    } else {
+      Logger.warn('Failed to extend lock', { key, ttl });
+    }
+
+    return extended;
+  } catch (error) {
+    Logger.error('Error extending lock', { key, ttl, error });
+    return false;
+  }
+}
+
+/**
+ * Validate unique ID format and check for potential issues
+ */
+function validateUniqueId(uniqueId: string): { valid: boolean; reason?: string } {
+  if (!uniqueId || typeof uniqueId !== 'string') {
+    return { valid: false, reason: 'uniqueId must be a non-empty string' };
+  }
+
+  if (uniqueId.length > 255) {
+    return { valid: false, reason: 'uniqueId must be less than 255 characters' };
+  }
+
+  if (uniqueId.includes(' ') || uniqueId.includes('\n') || uniqueId.includes('\r')) {
+    return { valid: false, reason: 'uniqueId cannot contain whitespace characters' };
+  }
+
+  // Check for invalid characters
+  const invalidChars = /[<>:"\\|?*]/;
+  if (invalidChars.test(uniqueId)) {
+    return { valid: false, reason: 'uniqueId contains invalid characters' };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Handle deduplication logic
+ */
+async function handleDeduplication(
+  deduplicationOptions: DeduplicationOptions, // DeduplicationOptions - using any to avoid circular import
+  lockProvider: LockProvider
+): Promise<JobResult> {
+  const { id, ttl, replace } = deduplicationOptions;
+
+  try {
+    // Check if lock already exists
+    const lockStatus = await lockProvider.status(id);
+
+    if (lockStatus.exists) {
+      if (replace === true) {
+        // Replace existing lock
+        const newLock = await lockProvider.acquire(id, { ttl });
+        return {
+          id,
+          deduplicated: false,
+          lockId: newLock.key,
+          status: ZintrustLang.QUEUED,
+        };
+      } else {
+        // Job is deduplicated
+        return {
+          id,
+          deduplicated: true,
+          status: ZintrustLang.DEDUPLICATED,
+        };
+      }
+    }
+
+    // Acquire new lock
+    const lock = await lockProvider.acquire(id, { ttl });
+
+    return {
+      id,
+      deduplicated: false,
+      lockId: lock.key,
+      status: ZintrustLang.QUEUED,
+    };
+  } catch (error) {
+    Logger.error(`Deduplication handling failed`, { id, error });
+    return {
+      id,
+      deduplicated: false,
+      status: ZintrustLang.FAILED,
+    };
+  }
+}

package/src/tools/queue/DeduplicationBuilder.ts

@@ -0,0 +1,111 @@
+/**
+ * Deduplication Builder - Plain function implementation for BullMQ job deduplication
+ * Follows ZinTrust's preference for functions over classes
+ */
+
+import type { DeduplicationOptions, ReleaseCondition } from '@/types/Queue';
+import { createValidationError } from '@exceptions/ZintrustError';
+
+export type ReleaseStrategy = string | number | ReleaseCondition;
+
+export interface DeduplicationBuilder {
+  id(id: string): DeduplicationBuilder;
+  expireAfter(ms: number): DeduplicationBuilder;
+  dontRelease(): DeduplicationBuilder;
+  replace(): DeduplicationBuilder;
+  releaseAfter(strategy: ReleaseStrategy): DeduplicationBuilder;
+  build(): DeduplicationOptions;
+}
+
+interface DeduplicationBuilderState {
+  id?: string;
+  ttl?: number;
+  dontRelease?: boolean;
+  replace?: boolean;
+  releaseAfter?: ReleaseStrategy;
+}
+
+/**
+ * Creates a deduplication builder for configuring job deduplication options
+ * @returns {DeduplicationBuilder} Builder instance with fluent interface
+ */
+export function createDeduplicationBuilder(): DeduplicationBuilder {
+  const state: DeduplicationBuilderState = {};
+
+  return {
+    /**
+     * Set the unique identifier for deduplication
+     * @param id - Unique identifier string
+     */
+    id(id: string): DeduplicationBuilder {
+      state.id = id;
+      return this;
+    },
+
+    /**
+     * Set time-to-live for deduplication lock in milliseconds
+     * @param ms - TTL in milliseconds
+     */
+    expireAfter(ms: number): DeduplicationBuilder {
+      state.ttl = ms;
+      return this;
+    },
+
+    /**
+     * Prevent automatic lock release - requires manual release
+     */
+    dontRelease(): DeduplicationBuilder {
+      state.dontRelease = true;
+      return this;
+    },
+
+    /**
+     * Replace existing job with same ID instead of ignoring
+     */
+    replace(): DeduplicationBuilder {
+      state.replace = true;
+      return this;
+    },
+
+    /**
+     * Set release strategy for the deduplication lock
+     * @param strategy - Release strategy (delay, 'success', or condition object)
+     */
+    releaseAfter(strategy: string | number | ReleaseCondition): DeduplicationBuilder {
+      state.releaseAfter = strategy;
+      return this;
+    },
+
+    /**
+     * Build the final deduplication options
+     * @returns {DeduplicationOptions} Configured deduplication options
+     */
+    build(): DeduplicationOptions {
+      if (state.id === null || state.id === undefined) {
+        throw createValidationError('Deduplication ID is required. Call .id() before .build()');
+      }
+
+      const options: DeduplicationOptions = {
+        id: state.id,
+      };
+
+      if (state.ttl !== undefined) {
+        options.ttl = state.ttl;
+      }
+
+      if (state.dontRelease === true) {
+        options.dontRelease = true;
+      }
+
+      if (state.replace === true) {
+        options.replace = true;
+      }
+
+      if (state.releaseAfter !== undefined) {
+        options.releaseAfter = state.releaseAfter;
+      }
+
+      return options;
+    },
+  } as DeduplicationBuilder;
+}