@zintrust/core 0.4.17 → 0.4.18

package/src/config/workers.js

@@ -0,0 +1,326 @@
+/**
+ * Workers Configuration
+ * Background worker management settings
+ * Sealed namespace for immutability
+ */
+import { Cloudflare } from './cloudflare.js';
+import { Env } from './env.js';
+import { Logger } from './logger.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { createRequire } from '../node-singletons/module.js';
+import { StartupConfigFile, StartupConfigFileRegistry } from '../runtime/StartupConfigFileRegistry.js';
+let redisModule;
+let warnedRedisProxyMismatch = false;
+const parseHttpProxyEndpoint = (proxyUrl) => {
+    try {
+        const url = new URL(proxyUrl);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            return null;
+        }
+        const host = url.hostname.trim();
+        const defaultPort = url.protocol === 'https:' ? 443 : 80;
+        const port = url.port ? Number.parseInt(url.port, 10) : defaultPort;
+        if (host === '' || !Number.isFinite(port)) {
+            return null;
+        }
+        return { host, port };
+    }
+    catch {
+        return null;
+    }
+};
+const resolveIORedis = () => {
+    const injected = globalThis
+        .__zintrustIoredisModule;
+    if (injected !== undefined && injected !== null) {
+        redisModule = injected;
+    }
+    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 = 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;
+            // Check if it has Redis property or if it's directly the Redis constructor
+            if (typeof moduleAsRecord['Redis'] === 'function' || typeof requiredModule === 'function') {
+                redisModule = requiredModule;
+            }
+            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;
+};
+const getProxySettings = () => {
+    const proxyUrl = (Env.get('REDIS_PROXY_URL', '') || '').trim();
+    const parsedHttpProxy = parseHttpProxyEndpoint(proxyUrl);
+    const proxyIsHttp = parsedHttpProxy !== null;
+    const proxyHost = (Env.get('REDIS_PROXY_HOST', '') || '').trim();
+    const proxyPort = Env.getInt('REDIS_PROXY_PORT', 6379);
+    return {
+        proxyUrl,
+        parsedHttpProxy,
+        proxyIsHttp,
+        proxyTargetHost: parsedHttpProxy?.host ?? proxyHost,
+        proxyTargetPort: parsedHttpProxy?.port ?? proxyPort,
+    };
+};
+const validateRedisConfig = (_config, effectiveConfig, isWorkersRuntime, proxySettings) => {
+    const { proxyIsHttp, proxyTargetHost, proxyTargetPort } = proxySettings;
+    const stillTargetsHttpProxy = proxyIsHttp &&
+        proxyTargetHost !== '' &&
+        effectiveConfig.host.trim() === proxyTargetHost &&
+        Number(effectiveConfig.port) === Number(proxyTargetPort);
+    if (!isWorkersRuntime && stillTargetsHttpProxy) {
+        throw ErrorFactory.createConfigError('Redis config points to an HTTP proxy endpoint. Set REDIS_HOST/REDIS_PORT to your TCP Redis server (redis://), not REDIS_PROXY_URL/REDIS_PROXY_PORT.');
+    }
+    const shouldUseProxy = Env.USE_REDIS_PROXY === true || (Env.get('REDIS_PROXY_URL', '') || '').trim() !== '';
+    if (!shouldUseProxy && isWorkersRuntime && Cloudflare.isCloudflareSocketsEnabled() === false) {
+        throw ErrorFactory.createConfigError('Redis connections in Cloudflare Workers require ENABLE_CLOUDFLARE_SOCKETS=true.');
+    }
+};
+const resolveRedisConstructor = () => {
+    const module = resolveIORedis();
+    const moduleDefault = module['default'];
+    const candidates = [
+        module['Redis'],
+        module['default'],
+        moduleDefault?.['Redis'],
+        moduleDefault?.['default'],
+        module,
+    ];
+    const RedisCtor = candidates.find((candidate) => typeof candidate === 'function');
+    if (typeof RedisCtor !== 'function') {
+        throw ErrorFactory.createConfigError("Workers Redis driver could not resolve a Redis constructor from 'ioredis'.");
+    }
+    return RedisCtor;
+};
+const setupRedisErrorHandler = (client) => {
+    if (typeof client.on === 'function') {
+        client.on('error', (err) => {
+            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_);
+            }
+        });
+    }
+};
+const resolveEffectiveRedisConfig = (config, isWorkersRuntime, proxySettings) => {
+    const { proxyIsHttp, proxyTargetHost, proxyTargetPort } = proxySettings;
+    const configTargetsHttpProxy = proxyIsHttp &&
+        proxyTargetHost !== '' &&
+        config.host.trim() === proxyTargetHost &&
+        Number(config.port) === Number(proxyTargetPort);
+    if (!isWorkersRuntime && configTargetsHttpProxy) {
+        if (!warnedRedisProxyMismatch) {
+            warnedRedisProxyMismatch = true;
+            Logger.warn('Detected Redis config pointing to HTTP proxy endpoint in Node runtime. Falling back to standard REDIS_HOST/REDIS_PORT settings to prevent protocol errors.');
+        }
+        return {
+            host: Env.get('REDIS_HOST', config.host),
+            port: Env.getInt('REDIS_PORT', config.port),
+            password: Env.get('REDIS_PASSWORD', config.password),
+            db: Env.getInt('REDIS_QUEUE_DB', config.db),
+        };
+    }
+    return config;
+};
+export const createRedisConnection = (config, maxRetries = 3) => {
+    const isWorkersRuntime = Cloudflare.getWorkersEnv() !== null;
+    const proxySettings = getProxySettings();
+    const effectiveConfig = resolveEffectiveRedisConfig(config, isWorkersRuntime, proxySettings);
+    validateRedisConfig(config, effectiveConfig, isWorkersRuntime, proxySettings);
+    const RedisCtor = resolveRedisConstructor();
+    const client = new RedisCtor({
+        host: effectiveConfig.host,
+        port: effectiveConfig.port,
+        password: effectiveConfig.password,
+        db: effectiveConfig.db,
+        maxRetriesPerRequest: null, // Required by BullMQ
+        retryStrategy: (times) => {
+            if (times > maxRetries)
+                return null;
+            return Math.min(times * 50, 2000);
+        },
+    });
+    setupRedisErrorHandler(client);
+    return client;
+};
+const createIntervalConfig = () => Env.SSE_SNAPSHOT_INTERVAL;
+/**
+ * Helper: Create default worker configuration from environment
+ */
+const createDefaultWorkerConfig = () => ({
+    enabled: Env.getBool('WORKER_ENABLED', Cloudflare.getWorkersEnv() === null),
+    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'),
+    intervalMs: createIntervalConfig(),
+});
+/**
+ * Helper: Create auto-scaling configuration from environment
+ */
+const createAutoScalingConfig = () => ({
+    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 = () => ({
+    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 = () => ({
+    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 = () => ({
+    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:7777'),
+    },
+    datadog: {
+        enabled: Env.getBool('WORKER_DATADOG_ENABLED', false),
+        apiKey: Env.get('WORKER_DATADOG_API_KEY', ''),
+    },
+});
+const createProcessorSpecConfig = () => ({
+    remoteAllowlist: ['wk.zintrust.com'],
+    fetchTimeoutMs: Env.getInt('PROCESSOR_FETCH_TIMEOUT', 30000),
+    fetchMaxSizeBytes: Env.getInt('PROCESSOR_FETCH_MAX_SIZE', 512 * 1024),
+    retryAttempts: Env.getInt('PROCESSOR_FETCH_RETRY_ATTEMPTS', 3),
+    retryBackoffMs: Env.getInt('PROCESSOR_FETCH_RETRY_BACKOFF_MS', 1000),
+    cacheDefaultTtlSeconds: Env.getInt('PROCESSOR_CACHE_DEFAULT_TTL', 60 * 60),
+    cacheMaxTtlSeconds: Env.getInt('PROCESSOR_CACHE_MAX_TTL', 7 * 24 * 60 * 60),
+    cacheMaxSizeBytes: Env.getInt('PROCESSOR_CACHE_MAX_SIZE', 50 * 1024 * 1024),
+});
+const createWorkersConfig = () => {
+    const overrides = StartupConfigFileRegistry.get(StartupConfigFile.Workers) ?? {};
+    const baseConfig = {
+        enabled: Env.getBool('WORKERS_ENABLED', true),
+        healthCheckInterval: Env.getInt('WORKERS_HEALTH_CHECK_INTERVAL', 60),
+        clusterMode: Env.getBool('WORKERS_CLUSTER_MODE', false),
+        processorSpec: createProcessorSpecConfig(),
+        autoScaling: createAutoScalingConfig(),
+        costOptimization: createCostOptimizationConfig(),
+        compliance: createComplianceConfig(),
+        observability: createObservabilityConfig(),
+        defaultWorker: createDefaultWorkerConfig(),
+        intervalMs: createIntervalConfig(),
+    };
+    const workersConfigObj = {
+        enabled: overrides.enabled ?? baseConfig.enabled,
+        intervalMs: createIntervalConfig(),
+        healthCheckInterval: overrides.healthCheckInterval ?? baseConfig.healthCheckInterval,
+        clusterMode: overrides.clusterMode ?? baseConfig.clusterMode,
+        processorSpec: {
+            ...baseConfig.processorSpec,
+            ...overrides.processorSpec,
+        },
+        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);
+};
+let cached = null;
+const proxyTarget = {};
+const ensureWorkersConfig = () => {
+    if (cached)
+        return cached;
+    cached = createWorkersConfig();
+    try {
+        Object.defineProperties(proxyTarget, Object.getOwnPropertyDescriptors(cached));
+    }
+    catch {
+        // best-effort
+    }
+    return cached;
+};
+export const workersConfig = new Proxy(proxyTarget, {
+    get(_target, prop) {
+        return ensureWorkersConfig()[prop];
+    },
+    ownKeys() {
+        ensureWorkersConfig();
+        return Reflect.ownKeys(proxyTarget);
+    },
+    getOwnPropertyDescriptor(_target, prop) {
+        ensureWorkersConfig();
+        return Object.getOwnPropertyDescriptor(proxyTarget, prop);
+    },
+});

package/src/container/ServiceContainer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ServiceContainer - Dependency Injection Container
+ * Manages service registration and resolution with proven dependency injection patterns
+ */
+type ServiceFactory<T = unknown> = () => 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 declare const ServiceContainer: Readonly<{
+    /**
+     * Create a new service container instance
+     */
+    create(): IServiceContainer;
+}>;
+export default ServiceContainer;
+//# sourceMappingURL=ServiceContainer.d.ts.map

package/src/container/ServiceContainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServiceContainer.d.ts","sourceRoot":"","sources":["../../../src/container/ServiceContainer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,KAAK,cAAc,CAAC,CAAC,GAAG,OAAO,IAAI,MAAM,CAAC,CAAC;AAQ3C,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACvD,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,iBAAiB,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IAC1E,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC;IACrC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC;IACjC,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;OAEG;cACO,iBAAiB;EAyE3B,CAAC;AAEH,eAAe,gBAAgB,CAAC"}

package/src/container/ServiceContainer.js

@@ -0,0 +1,75 @@
+/**
+ * ServiceContainer - Dependency Injection Container
+ * Manages service registration and resolution with proven dependency injection patterns
+ */
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+/**
+ * ServiceContainer - Dependency Injection Container
+ * Refactored to Functional Object pattern
+ */
+export const ServiceContainer = Object.freeze({
+    /**
+     * Create a new service container instance
+     */
+    create() {
+        const bindings = new Map();
+        const singletons = new Map();
+        return {
+            /**
+             * Register a service binding
+             */
+            bind(key, factory) {
+                bindings.set(key, {
+                    factory: factory,
+                    singleton: false,
+                });
+            },
+            /**
+             * Register a singleton service (instantiated once)
+             */
+            singleton(key, factoryOrInstance) {
+                const isFactory = typeof factoryOrInstance === 'function';
+                bindings.set(key, {
+                    factory: isFactory ? factoryOrInstance : () => factoryOrInstance,
+                    singleton: true,
+                });
+            },
+            /**
+             * Resolve a service from the container
+             */
+            resolve(key) {
+                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);
+                }
+                return binding.factory();
+            },
+            /**
+             * Check if a service is registered
+             */
+            has(key) {
+                return bindings.has(key);
+            },
+            /**
+             * Get a service (alias for resolve)
+             */
+            get(key) {
+                return this.resolve(key);
+            },
+            /**
+             * Clear all bindings and singletons
+             */
+            flush() {
+                bindings.clear();
+                singletons.clear();
+            },
+        };
+    },
+});
+export default ServiceContainer;

package/src/database/Paginator.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Paginator helpers
+ * Creates consistent pagination metadata for list responses.
+ */
+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;
+};
+export declare const Paginator: Readonly<{
+    create<T>(input: CreatePaginatorInput<T>): Paginator<T>;
+}>;
+export declare const createPaginator: <T>(input: CreatePaginatorInput<T>) => Paginator<T>;
+export declare const getNextPageUrl: (paginator: Paginator<unknown>, baseUrl: string, query?: PaginationQuery) => string | undefined;
+export declare const getPrevPageUrl: (paginator: Paginator<unknown>, baseUrl: string, query?: PaginationQuery) => string | undefined;
+//# sourceMappingURL=Paginator.d.ts.map

package/src/database/Paginator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Paginator.d.ts","sourceRoot":"","sources":["../../../src/database/Paginator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;AAChF,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAEnE,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,eAAe,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI;IACpC,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB,CAAC;AA4DF,eAAO,MAAM,SAAS;WACb,CAAC,SAAS,oBAAoB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC;EAsBvD,CAAC;AAEH,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,OAAO,oBAAoB,CAAC,CAAC,CAAC,KAAG,SAAS,CAAC,CAAC,CAE9E,CAAC;AAEF,eAAO,MAAM,cAAc,GACzB,WAAW,SAAS,CAAC,OAAO,CAAC,EAC7B,SAAS,MAAM,EACf,QAAQ,eAAe,KACtB,MAAM,GAAG,SAGX,CAAC;AAEF,eAAO,MAAM,cAAc,GACzB,WAAW,SAAS,CAAC,OAAO,CAAC,EAC7B,SAAS,MAAM,EACf,QAAQ,eAAe,KACtB,MAAM,GAAG,SAGX,CAAC"}

package/src/database/Paginator.js

@@ -0,0 +1,81 @@
+/**
+ * Paginator helpers
+ * Creates consistent pagination metadata for list responses.
+ */
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+const normalizePositiveInt = (value, label) => {
+    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) => {
+    const n = Math.trunc(value);
+    if (!Number.isFinite(n) || n < 0)
+        return 0;
+    return n;
+};
+const applyQueryParams = (url, query) => {
+    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, page, perPage, query) => {
+    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, currentPage, lastPage, perPage, query) => {
+    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(input) {
+        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 = (input) => {
+    return Paginator.create(input);
+};
+export const getNextPageUrl = (paginator, baseUrl, query) => {
+    if (paginator.currentPage >= paginator.lastPage)
+        return undefined;
+    return buildPageUrl(baseUrl, paginator.currentPage + 1, paginator.perPage, query);
+};
+export const getPrevPageUrl = (paginator, baseUrl, query) => {
+    if (paginator.currentPage <= 1)
+        return undefined;
+    return buildPageUrl(baseUrl, paginator.currentPage - 1, paginator.perPage, query);
+};

package/src/database/migrations/index.d.ts

@@ -0,0 +1,2 @@
+export declare const migrations: readonly [];
+//# sourceMappingURL=index.d.ts.map

package/src/database/migrations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/database/migrations/index.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,UAAU,aAA6B,CAAC"}

package/src/database/migrations/index.js

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

package/src/events/EventDispatcher.d.ts

@@ -0,0 +1,16 @@
+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;
+}
+export declare const EventDispatcher: Readonly<{
+    create<TEvents extends EventMap = EventMap>(): IEventDispatcher<TEvents>;
+}>;
+export default EventDispatcher;
+//# sourceMappingURL=EventDispatcher.d.ts.map

package/src/events/EventDispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventDispatcher.d.ts","sourceRoot":"","sources":["../../../src/events/EventDispatcher.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC/C,MAAM,MAAM,aAAa,CAAC,QAAQ,IAAI,CAAC,OAAO,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAElF,MAAM,WAAW,gBAAgB,CAAC,OAAO,SAAS,QAAQ,GAAG,QAAQ;IACnE,EAAE,CAAC,CAAC,SAAS,MAAM,OAAO,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;IAChG,IAAI,CAAC,CAAC,SAAS,MAAM,OAAO,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;IAClG,GAAG,CAAC,CAAC,SAAS,MAAM,OAAO,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC3F,IAAI,CAAC,CAAC,SAAS,MAAM,OAAO,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC5E,SAAS,CAAC,CAAC,SAAS,MAAM,OAAO,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1F,aAAa,CAAC,CAAC,SAAS,MAAM,OAAO,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC;IAClE,KAAK,CAAC,CAAC,SAAS,MAAM,OAAO,GAAG,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;CAC1D;AAwBD,eAAO,MAAM,eAAe;WACnB,OAAO,SAAS,QAAQ,gBAAgB,gBAAgB,CAAC,OAAO,CAAC;EAoGxE,CAAC;AAEH,eAAe,eAAe,CAAC"}

package/src/events/EventDispatcher.js

@@ -0,0 +1,92 @@
+import { Logger } from '../config/logger.js';
+function getOrCreateSet(store, event) {
+    const existing = store.get(event);
+    if (existing !== undefined)
+        return existing;
+    const created = new Set();
+    store.set(event, created);
+    return created;
+}
+function safeFireAndForget(listener, payload, event) {
+    const result = listener(payload);
+    if (result instanceof Promise) {
+        void result.catch((error) => {
+            Logger.error('Unhandled async event listener error', { event, error });
+        });
+    }
+}
+export const EventDispatcher = Object.freeze({
+    create() {
+        const listeners = new Map();
+        const dispatcher = {
+            on(event, listener) {
+                const set = getOrCreateSet(listeners, event);
+                set.add(listener);
+                // Capture dispatcher reference in closure instead of using 'this'
+                return () => {
+                    dispatcher.off(event, listener);
+                };
+            },
+            once(event, listener) {
+                const wrapped = async (payload) => {
+                    dispatcher.off(event, wrapped);
+                    return listener(payload);
+                };
+                const set = getOrCreateSet(listeners, event);
+                set.add(wrapped);
+                return () => {
+                    dispatcher.off(event, wrapped);
+                };
+            },
+            off(event, listener) {
+                const set = listeners.get(event);
+                if (set === undefined)
+                    return;
+                set.delete(listener);
+                if (set.size === 0) {
+                    listeners.delete(event);
+                }
+            },
+            emit(event, payload) {
+                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(event, payload) {
+                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.status === 'rejected')
+                    .map((r) => r.reason);
+                if (errors.length === 1) {
+                    throw errors[0];
+                }
+                if (errors.length > 1) {
+                    throw new AggregateError(errors, `Multiple event listeners failed for "${event}"`);
+                }
+            },
+            listenerCount(event) {
+                return listeners.get(event)?.size ?? 0;
+            },
+            clear(event) {
+                if (event !== undefined) {
+                    listeners.delete(event);
+                    return;
+                }
+                listeners.clear();
+            },
+        };
+        return dispatcher;
+    },
+});
+export default EventDispatcher;