@zintrust/core 0.1.27 → 0.1.28

package/src/cache/CacheDriverRegistry.ts

@@ -0,0 +1,29 @@
+import type { CacheDriver } from '@cache/CacheDriver';
+import type { CacheDriverConfig } from '@config/type';
+
+export type CacheDriverFactory = (config: CacheDriverConfig) => CacheDriver;
+
+const registry = new Map<CacheDriverConfig['driver'], CacheDriverFactory>();
+
+function register(driver: CacheDriverConfig['driver'], factory: CacheDriverFactory): void {
+  registry.set(driver, factory);
+}
+
+function get(driver: CacheDriverConfig['driver']): CacheDriverFactory | undefined {
+  return registry.get(driver);
+}
+
+function has(driver: CacheDriverConfig['driver']): boolean {
+  return registry.has(driver);
+}
+
+function list(): Array<CacheDriverConfig['driver']> {
+  return Array.from(registry.keys());
+}
+
+export const CacheDriverRegistry = Object.freeze({
+  register,
+  get,
+  has,
+  list,
+});

package/src/cache/CacheRuntimeRegistration.ts

@@ -0,0 +1,24 @@
+import type { CacheConfig } from '@config/cache';
+
+import { CacheDriverRegistry } from '@cache/CacheDriverRegistry';
+import { KVDriver } from '@cache/drivers/KVDriver';
+import { KVRemoteDriver } from '@cache/drivers/KVRemoteDriver';
+import { MemoryDriver } from '@cache/drivers/MemoryDriver';
+import { MongoDriver } from '@cache/drivers/MongoDriver';
+import { RedisDriver } from '@cache/drivers/RedisDriver';
+
+/**
+ * Register cache drivers from runtime config.
+ *
+ * This follows the framework's config-driven availability pattern:
+ * - Built-in driver factories are registered so config entries can reference them.
+ * - Named cache stores are still resolved from `cacheConfig.drivers[storeName]`.
+ * - Unknown store names throw when explicitly selected via `cacheConfig.getDriver(name)`.
+ */
+export function registerCachesFromRuntimeConfig(_config: CacheConfig): void {
+  CacheDriverRegistry.register('memory', () => MemoryDriver.create());
+  CacheDriverRegistry.register('redis', () => RedisDriver.create());
+  CacheDriverRegistry.register('mongodb', () => MongoDriver.create());
+  CacheDriverRegistry.register('kv', () => KVDriver.create());
+  CacheDriverRegistry.register('kv-remote', () => KVRemoteDriver.create());
+}

package/src/cache/drivers/KVDriver.ts

@@ -0,0 +1,63 @@
+/**
+ * Cloudflare KV Cache Driver
+ * Interfaces with the native KV binding in Cloudflare Workers
+ */
+
+import type { CacheDriver } from '@cache/CacheDriver';
+import { Cloudflare } from '@config/cloudflare';
+import { Logger } from '@config/logger';
+
+/**
+ * Create a new KV driver instance
+ */
+const create = (): CacheDriver => {
+  // In Cloudflare Workers, the KV namespace is usually bound to a variable in the environment
+  const kv = Cloudflare.getKVBinding('CACHE');
+
+  return {
+    async get<T>(key: string): Promise<T | null> {
+      if (kv === null) return null;
+      const value = await kv.get(key, { type: 'json' });
+      return (value as T | null) ?? null;
+    },
+
+    async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+      if (kv === null) {
+        Logger.warn('KV binding "CACHE" not found. Cache set ignored.');
+        return;
+      }
+
+      const options: { expirationTtl?: number } = {};
+      if (ttl !== undefined) {
+        // KV expirationTtl must be at least 60 seconds
+        options.expirationTtl = Math.max(60, ttl);
+      }
+
+      await kv.put(key, JSON.stringify(value), options);
+    },
+
+    async delete(key: string): Promise<void> {
+      if (kv === null) return;
+      await kv.delete(key);
+    },
+
+    async clear(): Promise<void> {
+      // KV doesn't support clearing all keys easily without listing and deleting
+      Logger.warn('KV clear() is not implemented due to Cloudflare KV limitations.');
+      await Promise.resolve();
+    },
+
+    async has(key: string): Promise<boolean> {
+      if (kv === null) return false;
+      const value = await kv.get(key);
+      return value !== null;
+    },
+  };
+};
+
+/**
+ * KVDriver namespace - sealed for immutability
+ */
+export const KVDriver = Object.freeze({
+  create,
+});

package/src/cache/drivers/KVRemoteDriver.ts

@@ -0,0 +1,97 @@
+/**
+ * KV Remote Cache Driver
+ *
+ * Calls a ZinTrust Cloudflare Worker KV proxy over HTTPS.
+ */
+
+import type { CacheDriver } from '@cache/CacheDriver';
+import { RemoteSignedJson, type RemoteSignedJsonSettings } from '@common/RemoteSignedJson';
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+
+type KvValueType = 'text' | 'json' | 'arrayBuffer';
+
+type KvGetResponse = { value: unknown };
+type KvPutResponse = { ok: true };
+type KvDeleteResponse = { ok: true };
+
+type KvRemoteSettings = {
+  baseUrl: string;
+  keyId: string;
+  secret: string;
+  defaultNamespace: string;
+  timeoutMs: number;
+};
+
+const normalizeNamespace = (defaultNamespace: string): string | undefined =>
+  defaultNamespace.trim() === '' ? undefined : defaultNamespace;
+
+export const KVRemoteDriver = Object.freeze({
+  create(): CacheDriver {
+    const settings: KvRemoteSettings = {
+      baseUrl: Env.get('KV_REMOTE_URL'),
+      keyId: Env.get('KV_REMOTE_KEY_ID'),
+      secret: Env.get('KV_REMOTE_SECRET'),
+      defaultNamespace: Env.get('KV_REMOTE_NAMESPACE'),
+      timeoutMs: Env.getInt('ZT_PROXY_TIMEOUT_MS', Env.REQUEST_TIMEOUT),
+    };
+
+    const remote: RemoteSignedJsonSettings = {
+      baseUrl: settings.baseUrl,
+      keyId: settings.keyId,
+      secret: settings.secret,
+      timeoutMs: settings.timeoutMs,
+      missingUrlMessage: 'KV remote proxy URL is missing (KV_REMOTE_URL)',
+      missingCredentialsMessage:
+        'KV remote signing credentials are missing (KV_REMOTE_KEY_ID / KV_REMOTE_SECRET)',
+      messages: {
+        unauthorized: 'KV remote proxy unauthorized',
+        forbidden: 'KV remote proxy forbidden',
+        rateLimited: 'KV remote proxy rate limited',
+        rejected: 'KV remote proxy rejected request',
+        error: 'KV remote proxy error',
+        timedOut: 'KV remote proxy request timed out',
+      },
+    };
+
+    return {
+      async get<T>(key: string): Promise<T | null> {
+        const out = await RemoteSignedJson.request<KvGetResponse>(remote, '/zin/kv/get', {
+          namespace: normalizeNamespace(settings.defaultNamespace),
+          key,
+          type: 'json' satisfies KvValueType,
+        });
+        return (out.value as T | null) ?? null;
+      },
+
+      async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+        await RemoteSignedJson.request<KvPutResponse>(remote, '/zin/kv/put', {
+          namespace: normalizeNamespace(settings.defaultNamespace),
+          key,
+          value,
+          ttlSeconds: ttl,
+        });
+      },
+
+      async delete(key: string): Promise<void> {
+        await RemoteSignedJson.request<KvDeleteResponse>(remote, '/zin/kv/delete', {
+          namespace: normalizeNamespace(settings.defaultNamespace),
+          key,
+        });
+      },
+
+      async clear(): Promise<void> {
+        // KV proxy does not implement clear() (and KV itself does not support full namespace wipe efficiently).
+        Logger.warn('KV remote clear() is not implemented.');
+        await Promise.resolve();
+      },
+
+      async has(key: string): Promise<boolean> {
+        const value = await this.get(key);
+        return value !== null;
+      },
+    };
+  },
+});
+
+export default KVRemoteDriver;

package/src/cache/drivers/MemoryDriver.ts

@@ -0,0 +1,85 @@
+/**
+ * Memory Cache Driver
+ * Simple in-memory storage for local development
+ */
+
+import type { CacheDriver } from '@cache/CacheDriver';
+
+/**
+ * Memory Cache Driver
+ * Simple in-memory storage for local development
+ * Refactored to Functional Object pattern
+ */
+const create = (): CacheDriver => {
+  const storage = new Map<string, { value: unknown; expires: number | null }>();
+
+  // Background cleanup interval (runs every 60 seconds)
+  const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [key, item] of storage.entries()) {
+      if (item.expires !== null && item.expires < now) {
+        storage.delete(key);
+      }
+    }
+  }, 60_000); // 60 seconds
+
+  // Unref so it doesn't keep process alive
+  cleanupInterval.unref();
+
+  return {
+    async get<T>(key: string): Promise<T | null> {
+      await Promise.resolve();
+      const item = storage.get(key);
+      if (item === undefined) return null;
+
+      if (item.expires !== null && item.expires < Date.now()) {
+        storage.delete(key);
+        return null;
+      }
+
+      return item.value as T;
+    },
+
+    async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+      const expires = ttl === undefined ? null : Date.now() + ttl * 1000;
+      storage.set(key, { value, expires });
+      await Promise.resolve();
+    },
+
+    async delete(key: string): Promise<void> {
+      storage.delete(key);
+      await Promise.resolve();
+    },
+
+    async clear(): Promise<void> {
+      storage.clear();
+      await Promise.resolve();
+    },
+
+    async has(key: string): Promise<boolean> {
+      await Promise.resolve();
+      const item = storage.get(key);
+      if (item === undefined) return false;
+
+      if (item.expires !== null && item.expires < Date.now()) {
+        storage.delete(key);
+        return false;
+      }
+
+      return true;
+    },
+
+    async dispose(): Promise<void> {
+      clearInterval(cleanupInterval);
+      storage.clear();
+      await Promise.resolve();
+    },
+  };
+};
+
+/**
+ * MemoryDriver namespace - sealed for immutability
+ */
+export const MemoryDriver = Object.freeze({
+  create,
+});

package/src/cache/drivers/MongoDriver.ts

@@ -0,0 +1,96 @@
+/**
+ * MongoDB Cache Driver
+ * Uses MongoDB Atlas Data API (HTTPS) for zero-dependency integration
+ */
+
+import type { CacheDriver } from '@cache/CacheDriver';
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+/**
+ * MongoDB Cache Driver
+ * Uses MongoDB Atlas Data API (HTTPS) for zero-dependency integration
+ * Sealed namespace for immutability
+ */
+export const MongoDriver = Object.freeze({
+  /**
+   * Create a new MongoDB driver instance
+   */
+  create(): CacheDriver {
+    const uri = Env.MONGO_URI;
+    const db = Env.MONGO_DB;
+    const collection = 'cache';
+
+    const request = async (action: string, body: Record<string, unknown>): Promise<unknown> => {
+      if (uri === '') {
+        Logger.warn('MONGO_URI not configured. MongoDB Cache request ignored.');
+        return null;
+      }
+
+      try {
+        const response = await fetch(`${uri}/action/${action}`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Access-Control-Request-Headers': '*',
+          },
+          body: JSON.stringify({
+            dataSource: 'Cluster0',
+            database: db,
+            collection: collection,
+            ...body,
+          }),
+        });
+
+        return await response.json();
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        ErrorFactory.createTryCatchError(`MongoDB Cache Error: ${message}`);
+        return null;
+      }
+    };
+
+    return {
+      async get<T>(key: string): Promise<T | null> {
+        const result = (await request('findOne', { filter: { _id: key } })) as {
+          document?: { value: T; expires: number | null };
+        } | null;
+        if (result?.document === undefined || result.document === null) return null;
+
+        const doc = result.document;
+
+        if (doc.expires !== null && doc.expires < Date.now()) {
+          await this.delete(key);
+          return null;
+        }
+
+        return doc.value;
+      },
+
+      async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+        const expires = ttl === undefined ? null : Date.now() + ttl * 1000;
+        await request('updateOne', {
+          filter: { _id: key },
+          update: { $set: { value, expires } },
+          upsert: true,
+        });
+      },
+
+      async delete(key: string): Promise<void> {
+        await request('deleteOne', { filter: { _id: key } });
+      },
+
+      async clear(): Promise<void> {
+        await request('deleteMany', { filter: {} });
+      },
+
+      async has(key: string): Promise<boolean> {
+        const result = (await request('findOne', { filter: { _id: key } })) as {
+          document?: unknown;
+        } | null;
+        return result?.document !== undefined && result.document !== null;
+      },
+    };
+  },
+});

package/src/cache/drivers/RedisDriver.ts

@@ -0,0 +1,95 @@
+/**
+ * Redis Cache Driver
+ * Zero-dependency implementation using Node.js native net module
+ */
+
+import type { CacheDriver } from '@cache/CacheDriver';
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+import * as net from '@node-singletons/net';
+import { createCacheKey } from '@tools/redis/RedisKeyManager';
+
+/**
+ * Create a new Redis driver instance
+ */
+const create = (): CacheDriver => {
+  let client: net.Socket | null = null;
+  const host = Env.REDIS_HOST;
+  const port = Env.REDIS_PORT;
+
+  const connect = async (): Promise<net.Socket> => {
+    if (client && !client.destroyed) return client;
+
+    return new Promise((resolve, reject) => {
+      const socket = net.connect(port, host, () => {
+        client = socket;
+        resolve(socket);
+      });
+
+      socket.on('error', (err) => {
+        Logger.error(`Redis Connection Error: ${err.message}`);
+        reject(err);
+      });
+    });
+  };
+
+  const sendCommand = async (command: string): Promise<string> => {
+    const socket = await connect();
+    return new Promise((resolve, _reject) => {
+      socket.once('data', (data) => {
+        resolve(data.toString());
+      });
+      socket.write(command);
+    });
+  };
+
+  return {
+    async get<T>(key: string): Promise<T | null> {
+      try {
+        const prefixedKey = createCacheKey(key);
+        const response = await sendCommand(`GET ${prefixedKey}\r\n`);
+        if (response.startsWith('$-1')) return null;
+
+        // Basic RESP parsing
+        const lines = response.split('\r\n');
+        const value = lines[1];
+        return JSON.parse(value) as T;
+      } catch (error) {
+        Logger.error('Redis GET failed', error);
+        return null;
+      }
+    },
+
+    async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+      const prefixedKey = createCacheKey(key);
+      const jsonValue = JSON.stringify(value);
+      let command = `SET ${prefixedKey} ${jsonValue}\r\n`;
+      if (ttl !== undefined) {
+        command = `SETEX ${prefixedKey} ${ttl} ${jsonValue}\r\n`;
+      }
+      await sendCommand(command);
+    },
+
+    async delete(key: string): Promise<void> {
+      const prefixedKey = createCacheKey(key);
+      await sendCommand(`DEL ${prefixedKey}\r\n`);
+    },
+
+    async clear(): Promise<void> {
+      await sendCommand(`FLUSHDB\r\n`);
+    },
+
+    async has(key: string): Promise<boolean> {
+      const prefixedKey = createCacheKey(key);
+      const response = await sendCommand(`EXISTS ${prefixedKey}\r\n`);
+      return response.includes(':1');
+    },
+  };
+};
+
+/**
+ * RedisDriver namespace - sealed for immutability
+ */
+export const RedisDriver = Object.freeze({
+  create,
+});

package/src/cli/BaseCommand.ts

@@ -0,0 +1,106 @@
+/**
+ * Base Command - Abstract Command Class
+ * All CLI commands extend this class
+ */
+
+import { ErrorHandler } from '@cli/ErrorHandler';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { Command } from 'commander';
+
+export interface CommandOptions {
+  verbose?: boolean;
+  args?: string[];
+  [key: string]: unknown;
+}
+
+export interface IBaseCommand {
+  [x: string]: unknown;
+  name: string;
+  description: string;
+  verbose?: boolean;
+  getCommand(): Command;
+  addOptions?: (command: Command) => void;
+  execute(options: CommandOptions): void | Promise<void>;
+  info(message: string): void;
+  success(message: string): void;
+  warn(message: string): void;
+  debug(message: unknown): void;
+}
+
+/**
+ * Command Factory Helper
+ * Sealed namespace for immutability
+ */
+export const BaseCommand = Object.freeze({
+  /**
+   * Create a command instance with common logic
+   */
+  create<T extends IBaseCommand = IBaseCommand>(config: {
+    name: string;
+    description: string;
+    /** Optional alias or aliases for the command (e.g. 'make:mail') */
+    aliases?: string | string[];
+    addOptions?: (command: Command) => void;
+    execute: (options: CommandOptions) => void | Promise<void>;
+  }): T {
+    const getCommand = (): Command => {
+      const command = new Command(config.name);
+      command.description(config.description);
+      command.option('--verbose', 'Enable verbose output');
+
+      if (typeof config.aliases === 'string' && config.aliases.length > 0) {
+        command.alias(config.aliases);
+      }
+
+      if (Array.isArray(config.aliases)) {
+        for (const alias of config.aliases) {
+          if (typeof alias === 'string' && alias.length > 0) {
+            command.alias(alias);
+          }
+        }
+      }
+
+      // Add custom options
+      if (config.addOptions) {
+        config.addOptions(command);
+      }
+
+      // Set action handler
+      command.action(async (...args: unknown[]) => {
+        const options = args.at(-2) as CommandOptions;
+        const commandArgs = args.slice(0, -2) as string[];
+        options.args = commandArgs;
+
+        try {
+          await config.execute(options);
+        } catch (error: unknown) {
+          if (error instanceof Error) {
+            ErrorFactory.createTryCatchError('Command execution failed', error);
+            ErrorHandler.handle(error, undefined, false);
+            return;
+          }
+
+          const wrapped = ErrorFactory.createTryCatchError('Command execution failed', error);
+          ErrorHandler.handle(wrapped, undefined, false);
+        }
+      });
+
+      return command;
+    };
+
+    const base: IBaseCommand = {
+      name: config.name,
+      description: config.description,
+      verbose: false,
+      addOptions: config.addOptions,
+      getCommand,
+      execute: config.execute,
+      info: (msg: string) => ErrorHandler.info(msg),
+      success: (msg: string) => ErrorHandler.success(msg),
+      warn: (msg: string) => ErrorHandler.warn(msg),
+      debug: (msg: string) => ErrorHandler.debug(msg, true),
+    };
+
+    return base as T;
+  },
+});