@goatlab/node-backend 0.2.5 → 0.4.0

package/README.md

@@ -62,38 +62,88 @@ const result = await cache.remember('expensive-op', 300000, async () => {
 
 ## Secret Management
 
-The `SecretService` provides secure secret management with support for multiple backends:
+The `SecretService` provides secure secret management with support for multiple backends and preloading:
 
 ```typescript
 import { SecretService } from '@goatlab/node-backend'
 
-// File-based encrypted secrets
-const fileSecrets = new SecretService('FILE', '/path/to/secrets.json')
+// File-based encrypted secrets with TTL caching
+const fileSecrets = new SecretService({
+  provider: 'FILE',
+  location: '/path/to/secrets.json',
+  encryptionKey: process.env.ENCRYPTION_KEY,
+  cacheTTL: 300000 // 5 minutes (optional, default: 5 minutes)
+})
 
 // HashiCorp Vault integration
-const vaultSecrets = new SecretService('VAULT', 'my-app/secrets')
+const vaultSecrets = new SecretService({
+  provider: 'VAULT',
+  location: 'my-app/secrets',
+  encryptionKey: process.env.ENCRYPTION_KEY
+})
 
-// Environment variables (new!)
-const envSecrets = new SecretService('ENV', 'APP') // Loads APP_* env vars
-const allEnvSecrets = new SecretService('ENV', '') // Loads all env vars
+// Environment variables
+const envSecrets = new SecretService({
+  provider: 'ENV',
+  location: 'APP', // Loads APP_* env vars
+  encryptionKey: process.env.ENCRYPTION_KEY // Now supports encryption for all providers
+})
 
-// Usage
-await fileSecrets.loadSecrets()
-const apiKey = await fileSecrets.getSecret('API_KEY')
-const config = await fileSecrets.getSecretJson('CONFIG')
+// Preload secrets for synchronous access (new!)
+await fileSecrets.preload()
+const apiKey = fileSecrets.getSecretSync('API_KEY') // Synchronous!
+const config = fileSecrets.getSecretJsonSync('CONFIG') // Synchronous!
+
+// Async operations still available
+const apiKeyAsync = await fileSecrets.getSecret('API_KEY')
+const configAsync = await fileSecrets.getSecretJson('CONFIG')
 
 // Store secrets (FILE and VAULT providers)
 await fileSecrets.storeSecrets({ API_KEY: 'secret-value' })
+
+// Manual cache cleanup
+SecretService.cleanupExpiredCache()
+
+// Dispose when done (stops file watching)
+fileSecrets.dispose()
 ```
 
 ### Secret Provider Features
 
-- **FILE**: Encrypted local file storage using AES encryption
+- **FILE**: Encrypted local file storage using AES encryption with file watching
 - **VAULT**: HashiCorp Vault integration with automatic token management  
-- **ENV**: Runtime environment variable access with optional prefix filtering
-- **Caching**: Automatic in-memory caching for improved performance
+- **ENV**: Runtime environment variable access with encryption support
+- **Preloading**: Load secrets once async, access synchronously afterward
+- **Per-Tenant Encryption**: Each tenant can have its own encryption key
+- **Automatic Invalidation**: File changes trigger automatic reload (FILE provider)
+- **TTL Caching**: Configurable time-to-live caching with automatic expiration
 - **Type Safety**: Generic type support for JSON secrets
 
+### Preloading Pattern with Container
+
+```typescript
+const container = new Container(factories, async (preload, meta) => {
+  // Create and preload secret service
+  const secretService = preload.secrets(meta.tenantId, {
+    provider: 'FILE',
+    location: meta.secretsLocation,
+    encryptionKey: meta.encryptionKey
+  })
+  
+  await secretService.preload() // Load once async
+  
+  // Use sync methods for instant access
+  const dbUrl = secretService.getSecretSync('DATABASE_URL')
+  const apiKey = secretService.getSecretSync('API_KEY')
+  
+  // Create other services with preloaded secrets
+  const database = preload.database(meta.tenantId, { url: dbUrl })
+  const api = preload.api(meta.tenantId, { apiKey })
+  
+  return { secrets: secretService, database, api }
+})
+```
+
 ## Express + tRPC Integration
 
 Helper for creating Express applications with tRPC integration:
@@ -117,6 +167,88 @@ const app = getExpressTrpcApp({
 })
 ```
 
+### Performance Features (New!)
+
+- **Optimized Compression**: Automatically skips compression for small responses (<1KB), SSE, WebSocket upgrades, and pre-compressed content
+- **Memory Monitoring**: Built-in middleware tracks heap usage and triggers garbage collection when needed
+- **Smart Rate Limiting**: Different limits for auth endpoints, API endpoints, and general routes
+
+## Container - Dependency Injection
+
+Multi-tenant dependency injection container with performance optimizations:
+
+```typescript
+import { Container } from '@goatlab/node-backend'
+
+// Define your service factories
+const factories = {
+  database: DatabaseService,
+  api: ApiService,
+  cache: CacheService
+}
+
+// Create container with initializer
+const container = new Container(factories, async (preload, tenantMeta) => {
+  const db = preload.database(tenantMeta.id, tenantMeta.dbConfig)
+  const cache = preload.cache(tenantMeta.id)
+  
+  return {
+    database: db,
+    api: preload.api(tenantMeta.id, db),
+    cache
+  }
+})
+
+// Bootstrap for a tenant
+await container.bootstrap(tenantMeta, async () => {
+  const { database, api } = container.context
+  // Use services...
+})
+
+// Batch operations (new!)
+const results = await container.bootstrapBatch([
+  { metadata: tenant1, fn: processTenant1 },
+  { metadata: tenant2, fn: processTenant2 }
+], {
+  concurrency: 10,
+  continueOnError: true,
+  onProgress: (completed, total) => console.log(`${completed}/${total}`)
+})
+
+// Batch cache invalidation (new!)
+await container.invalidateTenantBatch(['tenant1', 'tenant2', 'tenant3'])
+```
+
+### Container Features
+
+- **Multi-tenancy**: Isolated service instances per tenant
+- **Batch Operations**: Process multiple tenants in parallel with concurrency control
+- **Performance Metrics**: Built-in performance tracking and statistics
+- **Cache Management**: Efficient caching with batch invalidation support
+- **Type Safety**: Full TypeScript support with inference
+
+## Translation Service
+
+High-performance translation service with template caching:
+
+```typescript
+import { translationService } from '@goatlab/node-backend'
+
+// Translations are automatically loaded and cached
+const greeting = translationService.translate('welcome', { language: 'es' })
+
+// With template parameters
+const message = translationService.translate('user.greeting', 
+  { language: 'en' }, 
+  { name: 'John' }
+)
+
+// Performance optimized with:
+// - Compiled template caching
+// - Locale preloading at startup
+// - In-memory locale storage
+```
+
 ## Testing Utilities
 
 Comprehensive testing setup with testcontainers support:

package/dist/container/Container.d.ts

@@ -1,4 +1,4 @@
-import { ContainerOptions, InstancesStructure, PreloadStructure } from './types';
+import { ContainerOptions, InstancesStructure, PreloadStructure, BatchBootstrapOptions, BatchBootstrapResult, BatchInvalidationResult } from './types';
 /**
  * ═══════════════════════════════════════════════════════════════════════════════
  * 🏗️ MULTI-TENANT DEPENDENCY INJECTION CONTAINER
@@ -83,6 +83,7 @@ export declare class Container<Defs extends Record<string, unknown>, TenantMetad
     /**
      * Service instance cache managers - one per service type
      * Each manager handles LRU caching for that specific service
+     * Lazy-allocated to save memory for unused services
      */
     private readonly managers;
     /**
@@ -109,11 +110,6 @@ export declare class Container<Defs extends Record<string, unknown>, TenantMetad
      * Prevents concurrent bootstrap for same tenant from running initializer twice
      */
     private readonly initializerPromises;
-    /**
-     * Path string cache: converts ['user', 'repo'] -> "user.repo"
-     * Optimized to avoid repeated string joins and array operations
-     */
-    private readonly pathCache;
     /**
      * Proxy object cache: reuses proxy objects for the same paths
      * Reduces memory allocation and improves performance
@@ -132,14 +128,14 @@ export declare class Container<Defs extends Record<string, unknown>, TenantMetad
     private readonly initializerCache;
     /**
      * High-performance metrics using Uint32Array for better JIT optimization
-     * Indices: [hits, misses, creates, ctx, paths, proxy, initHits, resets]
+     * Indices: [hits, misses, creates, ctx, proxy, initHits, resets, batchOps, batchErrors]
      * Auto-wraps at 2^32 without overflow checks for maximum performance
      */
     private readonly metrics;
     /**
      * Metric indices for Uint32Array
      */
-    private static readonly METRIC_INDICES;
+    private static readonly METRIC;
     /**
      * Legacy overflow threshold for test compatibility
      * Note: With Uint32Array, overflow is handled automatically, but tests may mock this
@@ -166,25 +162,16 @@ export declare class Container<Defs extends Record<string, unknown>, TenantMetad
      */
     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
+     * Get or create a cache manager for a service - lazy allocation
+     * Saves memory by only creating caches for services that are actually used
+     * Note: Type safety is enforced at compile time through generics, not runtime
      */
-    private createManagers;
-    /**
-     * Optimized path caching that maintains flat key strings to avoid repeated joins
-     * Uses closure to keep pre-computed cache and final keys for maximum performance
-     */
-    private getOrCachePath;
+    private getManager;
     /**
      * Pre-populate the factory cache by walking the entire factory tree
      * This eliminates the need for recursive object traversal during runtime
      */
     private preloadFactoryCache;
-    /**
-     * Pre-warm proxy cache with static builders for common paths
-     * This reduces proxy creation overhead during runtime access patterns
-     */
-    private prewarmProxyCache;
     /**
      * Recursive factory tree walker that builds the flat factory cache
      * Converts nested object structure to flat dot-notation keys
@@ -252,8 +239,15 @@ export declare class Container<Defs extends Record<string, unknown>, TenantMetad
      */
     private createContextProxy;
     /**
-     * Create a stable cache key from tenant metadata using crypto-strong hashing
-     * Uses SHA-1 for better collision resistance than simple hash (~1:2^16 -> negligible)
+     * Simple string hash function for fallback tenant keys
+     * Uses djb2 algorithm - fast and good enough for cache keys
+     * Note: For very large metadata objects, consider upgrading to FNV-1a or crypto.createHash
+     * if collision resistance is critical. Current implementation is optimized for speed.
+     */
+    private simpleHash;
+    /**
+     * Create a stable cache key from tenant metadata
+     * Uses common tenant properties or hashed JSON as fallback
      */
     private createTenantCacheKey;
     /**
@@ -291,6 +285,85 @@ export declare class Container<Defs extends Record<string, unknown>, TenantMetad
         instances: InstancesStructure<Defs>;
         result?: T;
     }>;
+    /**
+     * Bootstrap multiple tenants in parallel with controlled concurrency
+     *
+     * This method enables efficient initialization of multiple tenants while:
+     * - Controlling concurrency to avoid overwhelming the system
+     * - Isolating errors so one failure doesn't affect others
+     * - Providing progress tracking for long-running operations
+     * - Collecting performance metrics for each operation
+     *
+     * @param tenantBatch - Array of tenant metadata and optional functions to execute
+     * @param options - Options for controlling the batch operation
+     * @returns Array of results for each tenant, including successes and failures
+     *
+     * ```typescript
+     * const results = await container.bootstrapBatch([
+     *   { metadata: tenant1Meta, fn: async () => processТenant1() },
+     *   { metadata: tenant2Meta, fn: async () => processTenant2() },
+     *   { metadata: tenant3Meta } // No function, just bootstrap
+     * ], {
+     *   concurrency: 5,
+     *   continueOnError: true,
+     *   onProgress: (completed, total) => console.log(`${completed}/${total}`)
+     * })
+     *
+     * // Process results
+     * for (const result of results) {
+     *   if (result.status === 'success') {
+     *     console.log(`Tenant ${result.metadata.id} initialized in ${result.metrics.duration}ms`)
+     *   } else {
+     *     console.error(`Tenant ${result.metadata.id} failed:`, result.error)
+     *   }
+     * }
+     * ```
+     */
+    bootstrapBatch<TMetadata = unknown, T = unknown>(tenantBatch: Array<{
+        metadata: TMetadata;
+        fn?: () => Promise<T>;
+    }>, options?: BatchBootstrapOptions<TMetadata>): Promise<Array<BatchBootstrapResult<Defs, TMetadata, T>>>;
+    /**
+     * Invalidate multiple tenant caches in batch
+     *
+     * Efficiently invalidates caches for multiple tenants with proper disposal
+     * and error handling. Useful for bulk updates or maintenance operations.
+     *
+     * @param tenantIds - Array of tenant IDs to invalidate
+     * @param reason - Optional reason for invalidation (for logging)
+     * @param distributed - Whether to propagate invalidation to other instances
+     * @returns Summary of the batch invalidation operation
+     *
+     * ```typescript
+     * const result = await container.invalidateTenantBatch(
+     *   ['tenant1', 'tenant2', 'tenant3'],
+     *   'Bulk configuration update',
+     *   true // Distribute to other instances
+     * )
+     *
+     * console.log(`Invalidated ${result.succeeded}/${result.total} tenants`)
+     * if (result.failed > 0) {
+     *   console.error('Failed invalidations:', result.errors)
+     * }
+     * ```
+     */
+    invalidateTenantBatch(tenantIds: string[], reason?: string, distributed?: boolean): Promise<BatchInvalidationResult>;
+    /**
+     * Invalidate multiple service caches in batch
+     *
+     * @param serviceTypes - Array of service types to invalidate
+     * @param reason - Optional reason for invalidation
+     * @param distributed - Whether to propagate invalidation
+     * @returns Summary of the batch invalidation operation
+     *
+     * ```typescript
+     * const result = await container.invalidateServiceBatch(
+     *   ['database', 'api.users', 'api.auth'],
+     *   'Service configuration update'
+     * )
+     * ```
+     */
+    invalidateServiceBatch(serviceTypes: string[], reason?: string, distributed?: boolean): Promise<BatchInvalidationResult>;
     /**
      * Get current performance metrics
      * Converts Uint32Array back to object format for compatibility
@@ -300,9 +373,10 @@ export declare class Container<Defs extends Record<string, unknown>, TenantMetad
         cacheMisses: number;
         instanceCreations: number;
         contextAccesses: number;
-        pathCacheHits: number;
         proxyCacheHits: number;
         initializerCacheHits: number;
+        batchOperations: number;
+        batchErrors: number;
     };
     /**
      * Reset all performance metrics to zero
@@ -314,6 +388,12 @@ export declare class Container<Defs extends Record<string, unknown>, TenantMetad
      * Calls optional dispose() hooks to prevent memory leaks (sockets, db handles, etc.)
      */
     clearCaches(): void;
+    /**
+     * Async version of clearCaches that properly awaits all disposal operations
+     * Use this method when you need to ensure all resources are fully disposed
+     * before continuing (e.g., during graceful shutdown)
+     */
+    clearCachesAsync(): Promise<void>;
     /**
      * Setup distributed cache invalidation system
      * Connects to Redis pub/sub for coordinating cache invalidation across instances
@@ -345,6 +425,12 @@ export declare class Container<Defs extends Record<string, unknown>, TenantMetad
      * Invalidate all cached data (local only)
      */
     private invalidateAllLocally;
+    /**
+     * Dispose all service instances across all tenants and clear caches
+     * Useful for graceful shutdown and testing cleanup
+     * Note: This also clears all caches to prevent resurrection of disposed services
+     */
+    disposeAll(): Promise<void>;
     /**
      * Get detailed cache statistics for each service
      * Shows how many instances are cached and the cache limits
@@ -369,13 +455,15 @@ export declare class Container<Defs extends Record<string, unknown>, TenantMetad
         initializerCacheSize: number;
         initializerPromisesSize: number;
         cacheHitRatio: number;
+        batchSuccessRatio: number;
         cacheHits: number;
         cacheMisses: number;
         instanceCreations: number;
         contextAccesses: number;
-        pathCacheHits: number;
         proxyCacheHits: number;
         initializerCacheHits: number;
+        batchOperations: number;
+        batchErrors: number;
     };
     /**
      * Check if there's an active tenant context