@goatlab/node-backend 0.0.16 → 0.1.0

package/README.md

@@ -1,45 +1,61 @@
-<!-- PROJECT SHIELDS -->
+# @goatlab/node-backend
 
-[![Stargazers][stars-shield]][stars-url]
-[![Issues][issues-shield]][issues-url]
-[![MIT License][license-shield]][license-url]
-[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
+A flexible caching solution for Node.js applications that supports both Redis and in-memory LRU caching with multi-tenancy support.
 
-<!-- PROJECT LOGO -->
-<br />
-<p align="center">
-  <a href="https://github.com/github_username/repo">
-       <img src="https://docs.goatlab.io/logo.png" alt="Logo" width="150" height="150">
-  </a>
-
-  <h3 align="center">GOAT - QUEUE</h3>
-
-  <p align="center">
-    Fluent - Time Saving (TS) utils
-    <br />
-    <a href="https://docs.goatlab.io/#/0.7.x/fluent/fluent"><strong>Explore the docs »</strong></a>
-    <br />
-    <br />
-    ·
-    <a href="https://github.com/goat-io/fluent/issues">Report Bug</a>
-    ·
-    <a href="https://github.com/goat-io/fluent/issues">Request Feature</a>
-  </p>
-  </p>
-</p>
-
-# Goat - JS UTILS
-
-Standard queue interfaces for different providers
-
-### Installing
-
-To install this package in your project, you can use the following command within your terminal.
+## Installation
 
 ```bash
-yarn add @goatlab/queue
+npm install @goatlab/node-backend
+# or
+yarn add @goatlab/node-backend
+# or
+pnpm add @goatlab/node-backend
+```
+
+## Basic Usage
+
+```typescript
+import { Cache } from '@goatlab/node-backend'
+
+// Use Redis cache
+const redisCache = new Cache({
+  connection: 'redis://localhost:6379',
+  opts: { namespace: 'my-app' }
+})
+
+// Use in-memory LRU cache
+const memoryCache = new Cache({
+  connection: undefined,
+  opts: { namespace: 'my-app' }
+})
+
+// Cache with LRU memory layer for improved performance
+const hybridCache = new Cache({
+  connection: 'redis://localhost:6379',
+  opts: { 
+    namespace: 'my-app',
+    usesLRUMemory: true // Adds LRU memory caching layer
+  }
+})
+
+// Basic operations
+await cache.set('key', { data: 'value' }, 60000) // TTL in milliseconds
+const value = await cache.get('key')
+await cache.delete('key')
+
+// Advanced operations
+const result = await cache.remember('expensive-op', 300000, async () => {
+  // This function only runs if key doesn't exist
+  return await expensiveOperation()
+})
 ```
 
-### Documentation
+## Key Features
 
-To learn how to use this visit the [Goat Docs](https://docs.goatlab.io/#/0.7.x/fluent-helpers/overview)
+- **Dual Storage**: Supports Redis for distributed caching or in-memory LRU for single instances
+- **Multi-tenancy**: Built-in tenant isolation with namespace support
+- **Memory Layer**: Optional LRU memory caching on top of Redis for improved performance
+- **Cache Helpers**: Laravel-inspired helper methods like `remember()`, `rememberForever()`, and `pull()`
+- **Namespace Operations**: Delete or retrieve values by key prefix with `deleteWhereStartsWith()` and `getValueWhereKeyStartsWith()`
+- **Type Safety**: Full TypeScript support with generic types
+- **Automatic Validation**: Skips caching of null, undefined, empty strings, empty arrays, and empty objects

package/dist/container/Container.d.ts

@@ -0,0 +1,441 @@
+import { ContainerOptions, InstancesStructure, PreloadStructure } from './types';
+/**
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 🏗️ MULTI-TENANT DEPENDENCY INJECTION CONTAINER
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * This Container provides a   dependency injection system designed
+ * for multi-tenant applications. Each tenant gets their own isolated service
+ * instances while sharing the same factory definitions.
+ *
+ * Key Features:
+ * • 🔄 Tenant-isolated service instances using AsyncLocalStorage
+ * • ⚡ High-performance caching with LRU eviction
+ * • 🪞 Intelligent proxy system for lazy loading and error handling
+ * • 📊 Built-in performance metrics and debugging tools
+ * • 🛡️ Type-safe service resolution with full TypeScript support
+ * • 🔧 Support for both class constructors and factory functions
+ *
+ * Architecture Overview:
+ * ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+ * │   Factories     │ -> │   Container     │ -> │   Instances     │
+ * │ (Shared Defs)   │    │ (Per-tenant)    │    │ (Per-tenant)    │
+ * └─────────────────┘    └─────────────────┘    └─────────────────┘
+ *
+ * Flow:
+ * 1. Define factories once (shared across all tenants)
+ * 2. Bootstrap container with tenant metadata
+ * 3. Services are lazy-loaded and cached per tenant
+ * 4. AsyncLocalStorage provides automatic context isolation
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+/**
+ * 🏗️ Multi-Tenant Dependency Injection Container
+ *
+ * The Container is the heart of the multi-tenant service architecture. It manages
+ * service instantiation, caching, and tenant isolation using AsyncLocalStorage.
+ *
+ * @template Defs - Factory definitions record (shared across tenants)
+ * @template TenantMetadata - Type of tenant-specific metadata (DB config, secrets, etc.)
+ *
+ * Key Responsibilities:
+ * 1. 🏭 **Factory Management**: Register and cache service factories
+ * 2. 🔄 **Tenant Isolation**: Each tenant gets isolated service instances
+ * 3. ⚡ **Performance**: Multi-level caching for optimal performance
+ * 4. 🪞 **Lazy Loading**: Services instantiated only when accessed
+ * 5. 🛡️ **Error Handling**: Clear error messages for missing services
+ * 6. 📊 **Observability**: Performance metrics and debugging tools
+ *
+ * Usage Pattern:
+ * ```typescript
+ * // 1. Define your services
+ * const factories = {
+ *   database: DatabaseService,
+ *   api: {
+ *     users: UserApiService,
+ *     auth: AuthApiService
+ *   }
+ * }
+ *
+ * // 2. Create container with initializer
+ * const container = new Container(factories, async (preload, meta) => {
+ *   const db = preload.database('main', meta.connectionString)
+ *   return {
+ *     database: db,
+ *     api: {
+ *       users: preload.api.users('users', db),
+ *       auth: preload.api.auth('auth', db, meta.jwtSecret)
+ *     }
+ *   }
+ * })
+ *
+ * // 3. Bootstrap for a tenant and run code
+ * await container.bootstrap(tenantMeta, async () => {
+ *   const { database, api } = container.context
+ *   const users = await api.users.getAll()
+ *   return users
+ * })
+ * ```
+ */
+export declare class Container<Defs extends Record<string, unknown>, TenantMetadata> {
+    private readonly factories;
+    private readonly initializer;
+    /**
+     * Service instance cache managers - one per service type
+     * Each manager handles LRU caching for that specific service
+     */
+    private readonly managers;
+    /**
+     * AsyncLocalStorage provides automatic tenant context isolation
+     * Each async call tree gets its own isolated service instances
+     * Also stores tenant metadata for introspection
+     */
+    private readonly als;
+    /**
+     * Pre-resolved factory lookup cache for performance
+     * Avoids recursive object traversal on every service access
+     */
+    private readonly factoryCache;
+    /**
+     * Cached preload proxy to avoid recreating the same proxy structure
+     */
+    private preloadProxy;
+    /**
+     * Container configuration with sensible defaults
+     */
+    private readonly options;
+    /**
+     * Path string cache: converts ['user', 'repo'] -> "user.repo"
+     * Avoids repeated string joining operations
+     */
+    private readonly pathCache;
+    /**
+     * Proxy object cache: reuses proxy objects for the same paths
+     * Reduces memory allocation and improves performance
+     */
+    private readonly proxyCache;
+    /**
+     * Context proxy cache: reuses proxies for the same object instances
+     * Uses WeakMap for automatic garbage collection when objects are freed
+     */
+    private readonly contextProxyCache;
+    /**
+     * Initializer cache: stores initialized instances per tenant
+     * Avoids re-running the expensive initializer function for the same tenant
+     * Key is a serialized version of tenant metadata, value is the initialized instances
+     */
+    private readonly initializerCache;
+    /**
+     * Performance metrics for monitoring and optimization
+     * Only collected when enableMetrics is true
+     * Includes overflow protection for long-running services
+     */
+    private metrics;
+    /**
+     * Maximum safe value for metrics before overflow protection kicks in
+     * Set to 90% of MAX_SAFE_INTEGER to provide buffer
+     */
+    private readonly MAX_METRIC_VALUE;
+    /**
+     * Safely increment a metric with overflow protection
+     * When approaching MAX_SAFE_INTEGER, resets all metrics to prevent overflow
+     */
+    private safeIncrementMetric;
+    /**
+     * Create a new Container instance
+     *
+     * @param factories - Service factory definitions (shared across all tenants)
+     * @param initializer - Function that creates tenant-specific service instances
+     * @param options - Configuration options for performance and debugging
+     *
+     * The initializer function receives:
+     * - preload: Proxy object for creating service instances with parameters
+     * - meta: Tenant-specific metadata (DB config, secrets, etc.)
+     *
+     * And should return a structure matching your factory definitions but with
+     * actual service instances instead of factory functions.
+     */
+    constructor(factories: Defs, initializer: (preload: PreloadStructure<Defs>, meta: TenantMetadata) => Promise<Partial<InstancesStructure<Defs>>>, options?: ContainerOptions);
+    /**
+     * Recursively create cache managers for all services in the factory tree
+     * Each service gets its own LRU cache with the configured size limit
+     */
+    private createManagers;
+    /**
+     * Efficiently cache path string conversions
+     * Converts ['user', 'service'] to "user.service" and caches the result
+     *
+     * Uses different separators for cache key vs final path to avoid conflicts
+     */
+    private getOrCachePath;
+    /**
+     * Pre-populate the factory cache by walking the entire factory tree
+     * This eliminates the need for recursive object traversal during runtime
+     */
+    private preloadFactoryCache;
+    /**
+     * Recursive factory tree walker that builds the flat factory cache
+     * Converts nested object structure to flat dot-notation keys
+     */
+    private walkFactories;
+    /**
+     * Get the preload proxy for service instantiation
+     * The preload proxy allows you to create services with parameters:
+     *
+     * ```typescript
+     * const db = preload.database('main', connectionString)
+     * const userApi = preload.api.users('users', db, config)
+     * ```
+     *
+     * This is used during the initialization phase to wire up dependencies
+     */
+    get preload(): PreloadStructure<Defs>;
+    /**
+     * Create a proxy that intercepts property access and provides factory functions
+     *
+     * The proxy works by:
+     * 1. Intercepting property access (e.g., preload.database)
+     * 2. Looking up the factory for that path
+     * 3. Returning a function that creates and caches instances
+     * 4. For nested paths, returning another proxy
+     *
+     * This enables natural dot-notation access while maintaining lazy loading
+     */
+    private createPreloadProxy;
+    /**
+     * Run a function within a specific tenant context
+     * This is usually called internally by bootstrap, but can be used directly
+     * for testing or advanced use cases
+     */
+    runWithContext<T>(instances: Partial<InstancesStructure<Defs>>, tenantMetadata: TenantMetadata, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get the current tenant's service context
+     *
+     * This is the main way to access services within a tenant context:
+     * ```typescript
+     * const { database, api } = container.context
+     * const users = await api.users.getAll()
+     * ```
+     *
+     * Throws an error if called outside of a tenant context
+     */
+    get context(): InstancesStructure<Defs>;
+    /**
+     * Create a proxy for the runtime context that provides intelligent error handling
+     *
+     * The context proxy:
+     * 1. Provides helpful error messages when services are missing
+     * 2. Handles nested object access gracefully
+     * 3. Avoids wrapping Promises or arrays (which would break them)
+     * 4. Uses WeakMap caching for automatic memory management
+     *
+     * This ensures that accessing container.context.someService either works
+     * or gives you a clear error message about what's available
+     */
+    private createContextProxy;
+    /**
+     * Create a stable cache key from tenant metadata
+     * Uses a deterministic approach focusing on tenant identity
+     */
+    private createTenantCacheKey;
+    /**
+     * Simple hash function for cache keys
+     * Not cryptographically secure, but good enough for cache key generation
+     */
+    private simpleHash;
+    /**
+     * Get or create initialized instances for a tenant
+     * Uses caching to avoid re-running the expensive initializer function
+     */
+    private getOrCreateInstances;
+    /**
+     * Bootstrap the container for a specific tenant and execute a function
+     *
+     * This is the main entry point for tenant-specific operations:
+     *
+     * @param meta - Tenant-specific metadata (DB config, secrets, etc.)
+     * @param fn - Function to execute within the tenant context (optional)
+     * @returns Object containing the initialized instances and function result
+     *
+     * ```typescript
+     * // Example: Process a user request for tenant "acme"
+     * const result = await container.bootstrap(acmeTenantMeta, async () => {
+     *   const { api } = container.context
+     *   return await api.users.getById(userId)
+     * })
+     *
+     * console.log(result.instances) // All initialized services
+     * console.log(result.result)    // Return value from the function
+     * ```
+     *
+     * The bootstrap process:
+     * 1. Gets or creates initialized services for this tenant (with caching)
+     * 2. Sets up AsyncLocalStorage context with the service instances
+     * 3. Executes your function within that context
+     * 4. Returns both the instances and your function's result
+     */
+    bootstrap<T>(meta: TenantMetadata, fn?: () => Promise<T>): Promise<{
+        instances: InstancesStructure<Defs>;
+        result?: T;
+    }>;
+    /**
+     * Get current performance metrics
+     * Useful for monitoring cache effectiveness and performance tuning
+     */
+    getMetrics(): {
+        cacheHits: number;
+        cacheMisses: number;
+        instanceCreations: number;
+        contextAccesses: number;
+        pathCacheHits: number;
+        proxyCacheHits: number;
+        initializerCacheHits: number;
+    };
+    /**
+     * Reset all performance metrics to zero
+     * Useful for benchmarking specific operations
+     */
+    resetMetrics(): void;
+    /**
+     * Clear all service instance caches
+     * Forces fresh instantiation of all services on next access
+     * Useful for testing or when you need to ensure clean state
+     */
+    clearCaches(): void;
+    /**
+     * Setup distributed cache invalidation system
+     * Connects to Redis pub/sub for coordinating cache invalidation across instances
+     */
+    private setupDistributedInvalidation;
+    /**
+     * Invalidate all cached data for a specific tenant across all instances
+     * This sends a distributed invalidation message via Redis pub/sub
+     */
+    invalidateTenantDistributed(tenantId: string, reason?: string): Promise<void>;
+    /**
+     * Invalidate all cached data for a specific service type across all instances
+     */
+    invalidateServiceDistributed(serviceType: string, reason?: string): Promise<void>;
+    /**
+     * Invalidate all cached data across all instances
+     */
+    invalidateAllDistributed(reason?: string): Promise<void>;
+    /**
+     * Invalidate cached data for a specific tenant (local only)
+     * This only affects the current instance
+     */
+    private invalidateTenantLocally;
+    /**
+     * Invalidate cached data for a specific service type (local only)
+     */
+    private invalidateServiceLocally;
+    /**
+     * Invalidate all cached data (local only)
+     */
+    private invalidateAllLocally;
+    /**
+     * Get detailed cache statistics for each service
+     * Shows how many instances are cached and the cache limits
+     */
+    getCacheStats(): Record<string, {
+        size: number;
+        maxSize?: number;
+    }>;
+    /**
+     * Get comprehensive performance statistics
+     * Combines metrics, cache stats, and computed ratios for full observability
+     */
+    getPerformanceStats(): {
+        cacheStats: Record<string, {
+            size: number;
+            maxSize?: number;
+        }>;
+        totalCacheSize: number;
+        pathCacheSize: number;
+        proxyCacheSize: number;
+        factoryCacheSize: number;
+        initializerCacheSize: number;
+        cacheHitRatio: number;
+        cacheHits: number;
+        cacheMisses: number;
+        instanceCreations: number;
+        contextAccesses: number;
+        pathCacheHits: number;
+        proxyCacheHits: number;
+        initializerCacheHits: number;
+    };
+    /**
+     * Check if there's an active tenant context
+     *
+     * @returns true if called within a tenant context, false otherwise
+     *
+     * ```typescript
+     * if (container.hasActiveContext()) {
+     *   const services = container.context
+     *   // Safe to access services
+     * }
+     * ```
+     */
+    hasActiveContext(): boolean;
+    /**
+     * Check if a service is available in the current tenant context
+     *
+     * @param servicePath - Dot-notation path to the service (e.g., "api.users")
+     * @returns true if the service exists and is initialized, false otherwise
+     *
+     * ```typescript
+     * if (container.hasService('api.users')) {
+     *   const users = container.context.api.users
+     *   // Safe to use users service
+     * }
+     * ```
+     */
+    hasService(servicePath: string): boolean;
+    /**
+     * Get the current tenant's metadata
+     *
+     * This allows access to tenant-specific configuration, credentials, and other
+     * metadata that was passed to the bootstrap method:
+     *
+     * ```typescript
+     * await container.bootstrap(tenantMeta, async () => {
+     *   const meta = container.getCurrentTenantMetadata()
+     *   console.log('Current tenant:', meta.id)
+     *   console.log('DB URL:', meta.connectionString)
+     * })
+     * ```
+     *
+     * @returns The tenant metadata that was passed to bootstrap
+     * @throws Error if called outside of a tenant context
+     */
+    getCurrentTenantMetadata(): TenantMetadata;
+    /**
+     * Get the current tenant ID from metadata
+     *
+     * This is a convenience method that extracts the tenant ID from the metadata.
+     * It assumes the metadata has an 'id' property (common pattern).
+     *
+     * ```typescript
+     * await container.bootstrap(tenantMeta, async () => {
+     *   const tenantId = container.getCurrentTenantId()
+     *   console.log('Processing request for tenant:', tenantId)
+     * })
+     * ```
+     *
+     * @returns The tenant ID if metadata has an 'id' property, undefined otherwise
+     * @throws Error if called outside of a tenant context
+     */
+    getCurrentTenantId(): string | undefined;
+    /**
+     * Get a list of all available services in the current tenant context
+     * Useful for debugging, testing, or dynamic service discovery
+     *
+     * @returns Array of dot-notation service paths (e.g., ["database", "api.users", "api.auth"])
+     */
+    getAvailableServices(): string[];
+    /**
+     * Recursively collect all service paths from the current context
+     * Helper method for getAvailableServices()
+     */
+    private collectServices;
+}