@varity-labs/sdk 2.0.0-alpha.1

package/dist/modules/cache/CacheModule.js

@@ -0,0 +1,493 @@
+/**
+ * CacheModule - Universal caching and performance optimization
+ *
+ * Provides high-performance caching with TTL, namespacing, and invalidation
+ * patterns. Works across all templates to optimize query performance.
+ */
+export class CacheModule {
+    constructor(sdk) {
+        this.sdk = sdk;
+    }
+    /**
+     * Get value from cache
+     *
+     * Universal method - retrieves cached value by key.
+     *
+     * @example
+     * ```typescript
+     * const kpis = await sdk.cache.get('dashboard:kpis:current_month')
+     * if (!kpis) {
+     *   // Cache miss - fetch from source
+     *   kpis = await sdk.analytics.getKPIs({ period: 'current_month' })
+     *   await sdk.cache.set('dashboard:kpis:current_month', kpis, { ttl: 300 })
+     * }
+     * ```
+     */
+    async get(key, namespace) {
+        const apiEndpoint = this.sdk.getAPIEndpoint();
+        const apiKey = this.sdk.getAPIKey();
+        const fullKey = namespace ? `${namespace}:${key}` : key;
+        const response = await fetch(`${apiEndpoint}/api/v1/cache/${encodeURIComponent(fullKey)}`, {
+            method: 'GET',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` })
+            }
+        });
+        if (response.status === 404) {
+            return null; // Cache miss
+        }
+        if (!response.ok) {
+            throw new Error(`Failed to get cache value: ${response.statusText}`);
+        }
+        const result = await response.json();
+        return result.value;
+    }
+    /**
+     * Set value in cache with optional TTL
+     *
+     * Universal method - stores value in cache with expiration.
+     *
+     * @example
+     * ```typescript
+     * await sdk.cache.set('user:123:profile', userProfile, { ttl: 3600, tags: ['user'] })
+     * ```
+     */
+    async set(key, value, options = {}) {
+        const apiEndpoint = this.sdk.getAPIEndpoint();
+        const apiKey = this.sdk.getAPIKey();
+        const fullKey = options.namespace ? `${options.namespace}:${key}` : key;
+        const response = await fetch(`${apiEndpoint}/api/v1/cache/${encodeURIComponent(fullKey)}`, {
+            method: 'PUT',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` })
+            },
+            body: JSON.stringify({
+                value,
+                ttl: options.ttl,
+                tags: options.tags,
+                compress: options.compress
+            })
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to set cache value: ${response.statusText}`);
+        }
+    }
+    /**
+     * Delete value from cache
+     *
+     * Universal method - removes cached value by key.
+     */
+    async delete(key, namespace) {
+        const apiEndpoint = this.sdk.getAPIEndpoint();
+        const apiKey = this.sdk.getAPIKey();
+        const fullKey = namespace ? `${namespace}:${key}` : key;
+        const response = await fetch(`${apiEndpoint}/api/v1/cache/${encodeURIComponent(fullKey)}`, {
+            method: 'DELETE',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` })
+            }
+        });
+        if (response.status === 404) {
+            return false; // Key didn't exist
+        }
+        if (!response.ok) {
+            throw new Error(`Failed to delete cache value: ${response.statusText}`);
+        }
+        return true;
+    }
+    /**
+     * Check if key exists in cache
+     *
+     * Universal method - checks cache key existence without retrieving value.
+     */
+    async has(key, namespace) {
+        const apiEndpoint = this.sdk.getAPIEndpoint();
+        const apiKey = this.sdk.getAPIKey();
+        const fullKey = namespace ? `${namespace}:${key}` : key;
+        const response = await fetch(`${apiEndpoint}/api/v1/cache/${encodeURIComponent(fullKey)}/exists`, {
+            method: 'GET',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` })
+            }
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to check cache key: ${response.statusText}`);
+        }
+        const result = await response.json();
+        return result.exists;
+    }
+    /**
+     * Remember pattern - get from cache or execute function and cache result
+     *
+     * Universal method - simplifies cache-aside pattern.
+     *
+     * @example
+     * ```typescript
+     * const kpis = await sdk.cache.remember(
+     *   'dashboard:kpis',
+     *   async () => await sdk.analytics.getKPIs(),
+     *   { ttl: 300 }
+     * )
+     * ```
+     */
+    async remember(key, fn, options = {}) {
+        // Try to get from cache first
+        const cached = await this.get(key, options.namespace);
+        if (cached !== null) {
+            return cached;
+        }
+        // Cache miss - execute function
+        const result = await fn();
+        // Store in cache
+        await this.set(key, result, options);
+        return result;
+    }
+    /**
+     * Invalidate cache by pattern
+     *
+     * Universal method - removes all keys matching pattern.
+     *
+     * @example
+     * ```typescript
+     * // Invalidate all user-related cache
+     * await sdk.cache.invalidate('user:*')
+     *
+     * // Invalidate specific namespace
+     * await sdk.cache.invalidate('*', 'analytics')
+     * ```
+     */
+    async invalidate(pattern, namespace) {
+        const apiEndpoint = this.sdk.getAPIEndpoint();
+        const apiKey = this.sdk.getAPIKey();
+        const fullPattern = namespace ? `${namespace}:${pattern}` : pattern;
+        const response = await fetch(`${apiEndpoint}/api/v1/cache/invalidate`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` })
+            },
+            body: JSON.stringify({ pattern: fullPattern })
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to invalidate cache: ${response.statusText}`);
+        }
+        const result = await response.json();
+        return result.deletedCount;
+    }
+    /**
+     * Invalidate cache by tags
+     *
+     * Universal method - removes all keys with specific tags.
+     *
+     * @example
+     * ```typescript
+     * // Set cache with tags
+     * await sdk.cache.set('merchant:123', data, { tags: ['merchant', 'iso'] })
+     *
+     * // Invalidate all entries with 'merchant' tag
+     * await sdk.cache.invalidateByTags(['merchant'])
+     * ```
+     */
+    async invalidateByTags(tags) {
+        const apiEndpoint = this.sdk.getAPIEndpoint();
+        const apiKey = this.sdk.getAPIKey();
+        const response = await fetch(`${apiEndpoint}/api/v1/cache/invalidate-by-tags`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` })
+            },
+            body: JSON.stringify({ tags })
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to invalidate by tags: ${response.statusText}`);
+        }
+        const result = await response.json();
+        return result.deletedCount;
+    }
+    /**
+     * Clear entire cache or namespace
+     *
+     * Universal method - removes all cached entries.
+     *
+     * @example
+     * ```typescript
+     * // Clear entire cache
+     * await sdk.cache.clear()
+     *
+     * // Clear specific namespace
+     * await sdk.cache.clear('analytics')
+     * ```
+     */
+    async clear(namespace) {
+        const apiEndpoint = this.sdk.getAPIEndpoint();
+        const apiKey = this.sdk.getAPIKey();
+        const queryParams = namespace ? `?namespace=${namespace}` : '';
+        const response = await fetch(`${apiEndpoint}/api/v1/cache/clear${queryParams}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` })
+            }
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to clear cache: ${response.statusText}`);
+        }
+        const result = await response.json();
+        return result.deletedCount;
+    }
+    /**
+     * Get cache statistics
+     *
+     * Universal method - retrieves cache performance metrics.
+     *
+     * @example
+     * ```typescript
+     * const stats = await sdk.cache.getStats()
+     * console.log(`Cache hit rate: ${stats.hitRate}%`)
+     * ```
+     */
+    async getStats(namespace) {
+        const apiEndpoint = this.sdk.getAPIEndpoint();
+        const apiKey = this.sdk.getAPIKey();
+        const queryParams = namespace ? `?namespace=${namespace}` : '';
+        const response = await fetch(`${apiEndpoint}/api/v1/cache/stats${queryParams}`, {
+            method: 'GET',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` })
+            }
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to get cache stats: ${response.statusText}`);
+        }
+        return await response.json();
+    }
+    /**
+     * Batch operations on cache
+     *
+     * Universal method - performs multiple cache operations efficiently.
+     *
+     * @example
+     * ```typescript
+     * const results = await sdk.cache.batch([
+     *   { key: 'user:123', operation: 'get' },
+     *   { key: 'user:456', operation: 'get' },
+     *   { key: 'session:abc', operation: 'delete' }
+     * ])
+     * ```
+     */
+    async batch(operations) {
+        const apiEndpoint = this.sdk.getAPIEndpoint();
+        const apiKey = this.sdk.getAPIKey();
+        const response = await fetch(`${apiEndpoint}/api/v1/cache/batch`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` })
+            },
+            body: JSON.stringify({ operations })
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to perform batch operations: ${response.statusText}`);
+        }
+        return await response.json();
+    }
+    /**
+     * Get multiple values from cache
+     *
+     * Universal method - retrieves multiple cached values efficiently.
+     *
+     * @example
+     * ```typescript
+     * const values = await sdk.cache.getMany(['user:123', 'user:456', 'user:789'])
+     * ```
+     */
+    async getMany(keys, namespace) {
+        const operations = keys.map(key => ({
+            key: namespace ? `${namespace}:${key}` : key,
+            operation: 'get'
+        }));
+        const results = await this.batch(operations);
+        const map = new Map();
+        results.forEach((result, index) => {
+            if (result.success && result.value !== null) {
+                map.set(keys[index], result.value);
+            }
+        });
+        return map;
+    }
+    /**
+     * Set multiple values in cache
+     *
+     * Universal method - stores multiple values efficiently.
+     */
+    async setMany(entries) {
+        const operations = entries.map(entry => ({
+            key: entry.options?.namespace ? `${entry.options.namespace}:${entry.key}` : entry.key,
+            value: entry.value,
+            operation: 'set',
+            options: entry.options
+        }));
+        await this.batch(operations);
+    }
+    /**
+     * Delete multiple keys from cache
+     *
+     * Universal method - removes multiple cached values efficiently.
+     */
+    async deleteMany(keys, namespace) {
+        const operations = keys.map(key => ({
+            key: namespace ? `${namespace}:${key}` : key,
+            operation: 'delete'
+        }));
+        const results = await this.batch(operations);
+        return results.filter(r => r.success).length;
+    }
+    /**
+     * List keys matching pattern
+     *
+     * Universal method - finds all keys matching a pattern.
+     *
+     * @example
+     * ```typescript
+     * const keys = await sdk.cache.keys('user:*')
+     * ```
+     */
+    async keys(pattern, namespace) {
+        const apiEndpoint = this.sdk.getAPIEndpoint();
+        const apiKey = this.sdk.getAPIKey();
+        const fullPattern = namespace ? `${namespace}:${pattern}` : pattern;
+        const response = await fetch(`${apiEndpoint}/api/v1/cache/keys?pattern=${encodeURIComponent(fullPattern)}`, {
+            method: 'GET',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` })
+            }
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to list cache keys: ${response.statusText}`);
+        }
+        const result = await response.json();
+        return result.keys;
+    }
+    /**
+     * Get TTL (time to live) for a key
+     *
+     * Universal method - returns remaining TTL in seconds.
+     */
+    async ttl(key, namespace) {
+        const apiEndpoint = this.sdk.getAPIEndpoint();
+        const apiKey = this.sdk.getAPIKey();
+        const fullKey = namespace ? `${namespace}:${key}` : key;
+        const response = await fetch(`${apiEndpoint}/api/v1/cache/${encodeURIComponent(fullKey)}/ttl`, {
+            method: 'GET',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` })
+            }
+        });
+        if (response.status === 404) {
+            return null; // Key doesn't exist
+        }
+        if (!response.ok) {
+            throw new Error(`Failed to get TTL: ${response.statusText}`);
+        }
+        const result = await response.json();
+        return result.ttl;
+    }
+    /**
+     * Extend TTL for a key
+     *
+     * Universal method - extends expiration time for cached value.
+     *
+     * @example
+     * ```typescript
+     * // Extend TTL by 1 hour
+     * await sdk.cache.extend('session:abc', 3600)
+     * ```
+     */
+    async extend(key, additionalTTL, namespace) {
+        const apiEndpoint = this.sdk.getAPIEndpoint();
+        const apiKey = this.sdk.getAPIKey();
+        const fullKey = namespace ? `${namespace}:${key}` : key;
+        const response = await fetch(`${apiEndpoint}/api/v1/cache/${encodeURIComponent(fullKey)}/extend`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` })
+            },
+            body: JSON.stringify({ ttl: additionalTTL })
+        });
+        if (response.status === 404) {
+            return false; // Key doesn't exist
+        }
+        if (!response.ok) {
+            throw new Error(`Failed to extend TTL: ${response.statusText}`);
+        }
+        return true;
+    }
+    /**
+     * Increment numeric value in cache
+     *
+     * Universal method - atomically increments cached number.
+     *
+     * @example
+     * ```typescript
+     * // Increment page view counter
+     * const views = await sdk.cache.increment('page:views:home', 1)
+     * ```
+     */
+    async increment(key, amount = 1, namespace) {
+        const apiEndpoint = this.sdk.getAPIEndpoint();
+        const apiKey = this.sdk.getAPIKey();
+        const fullKey = namespace ? `${namespace}:${key}` : key;
+        const response = await fetch(`${apiEndpoint}/api/v1/cache/${encodeURIComponent(fullKey)}/increment`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(apiKey && { 'Authorization': `Bearer ${apiKey}` })
+            },
+            body: JSON.stringify({ amount })
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to increment: ${response.statusText}`);
+        }
+        const result = await response.json();
+        return result.value;
+    }
+    /**
+     * Decrement numeric value in cache
+     *
+     * Universal method - atomically decrements cached number.
+     */
+    async decrement(key, amount = 1, namespace) {
+        return await this.increment(key, -amount, namespace);
+    }
+    /**
+     * Warm cache with data
+     *
+     * Universal method - preloads cache with frequently accessed data.
+     *
+     * @example
+     * ```typescript
+     * await sdk.cache.warm([
+     *   { key: 'dashboard:kpis', fn: () => sdk.analytics.getKPIs(), ttl: 300 },
+     *   { key: 'dashboard:trends', fn: () => sdk.analytics.getTrends(...), ttl: 300 }
+     * ])
+     * ```
+     */
+    async warm(entries) {
+        await Promise.all(entries.map(async (entry) => {
+            const exists = await this.has(entry.key, entry.options?.namespace);
+            if (!exists) {
+                const value = await entry.fn();
+                await this.set(entry.key, value, entry.options);
+            }
+        }));
+    }
+}

package/dist/modules/cache/index.d.ts

@@ -0,0 +1,3 @@
+export { CacheModule } from './CacheModule';
+export type { CacheOptions, CacheEntry, CacheStats, CacheBatchOperation, CacheBatchResult, CachePattern } from './CacheModule';
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,YAAY,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACb,MAAM,eAAe,CAAA"}

package/dist/modules/cache/index.js

@@ -0,0 +1 @@
+export { CacheModule } from './CacheModule';