@hiliosai/sdk 0.1.0 → 0.1.1

package/src/examples/cache-usage.example.ts

@@ -1,293 +0,0 @@
-/**
- * Example of how to use the cache middleware in a Moleculer service
- * This file demonstrates various caching patterns and best practices
- */
-
-import type {AppContext} from '../types';
-import {CacheMiddleware} from '../middlewares/cache.middleware';
-import {REDIS_URL} from '../env';
-
-// Initialize cache on application start
-export function initializeCache() {
-  CacheMiddleware.init({
-    redisUrl: REDIS_URL, // Falls back to in-memory if not set
-    ttl: 10 * 60 * 1000, // 10 minutes default TTL
-    namespace: 'app', // Namespace for cache keys
-  });
-}
-
-/**
- * Example 1: Simple get/set pattern
- */
-export async function getUserWithCache(ctx: AppContext, userId: string) {
-  const cacheKey = `user:${userId}`;
-
-  // Try to get from cache
-  const cached = await ctx.cache.get(cacheKey);
-  if (cached) {
-    return cached;
-  }
-
-  // Cache miss - fetch from database
-  const user = await fetchUserFromDatabase(userId);
-
-  // Store in cache for 5 minutes
-  await ctx.cache.set(cacheKey, user, 5 * 60 * 1000);
-
-  return user;
-}
-
-/**
- * Example 2: Using the wrap pattern (recommended)
- * Automatically handles get/set logic
- */
-export async function getUserWithWrap(ctx: AppContext, userId: string) {
-  return ctx.cache.wrap(
-    `user:${userId}`,
-    async () => {
-      // This function only runs if cache miss
-      return fetchUserFromDatabase(userId);
-    },
-    5 * 60 * 1000 // TTL
-  );
-}
-
-/**
- * Example 3: Caching complex calculations
- */
-export async function getUserPermissions(ctx: AppContext, userId: string) {
-  return ctx.cache.wrap(
-    `permissions:${userId}`,
-    async () => {
-      // Complex permission calculation
-      const user = await fetchUserFromDatabase(userId);
-      const roles = await fetchUserRoles(userId);
-      const permissions = calculatePermissions(user, roles);
-      return permissions;
-    },
-    10 * 60 * 1000 // Cache for 10 minutes
-  );
-}
-
-/**
- * Example 4: Batch operations
- */
-export async function getUsersBatch(ctx: AppContext, userIds: string[]) {
-  // Generate cache keys
-  const cacheKeys = userIds.map((id) => `user:${id}`);
-
-  // Get all from cache at once
-  const cachedUsers = await ctx.cache.mget(...cacheKeys);
-
-  // Find missing users
-  const result: Array<Record<string, unknown>> = [];
-  const missingIds: string[] = [];
-
-  cachedUsers.forEach((user, index) => {
-    if (user !== undefined && user !== null) {
-      result[index] = user as Record<string, unknown>;
-    } else {
-      const userId = userIds[index];
-      if (userId !== undefined) {
-        missingIds.push(userId);
-      }
-    }
-  });
-
-  // Fetch missing users from database
-  if (missingIds.length > 0) {
-    const missingUsers = await fetchUsersFromDatabase(missingIds);
-
-    // Prepare batch cache update
-    const cacheEntries: Record<string, unknown> = {};
-    missingUsers.forEach((user) => {
-      cacheEntries[`user:${user.id}`] = user;
-      // Add to result
-      const index = userIds.indexOf(user.id);
-      if (index !== -1) {
-        result[index] = user;
-      }
-    });
-
-    // Set all at once
-    await ctx.cache.mset(cacheEntries, 5 * 60 * 1000);
-  }
-
-  return result;
-}
-
-/**
- * Example 5: Cache invalidation after update
- */
-export async function updateUser(
-  ctx: AppContext,
-  userId: string,
-  updates: Record<string, unknown>
-) {
-  // Update in database
-  const updatedUser = await updateUserInDatabase(userId, updates);
-
-  // Invalidate all related caches
-  await ctx.cache.mdel(
-    `user:${userId}`,
-    `permissions:${userId}`,
-    `profile:${userId}`
-  );
-
-  // Optionally, pre-populate cache with new data
-  await ctx.cache.set(`user:${userId}`, updatedUser, 5 * 60 * 1000);
-
-  return updatedUser;
-}
-
-/**
- * Example 6: Check if key exists
- */
-export async function isUserCached(ctx: AppContext, userId: string) {
-  return ctx.cache.has(`user:${userId}`);
-}
-
-/**
- * Example 7: Clear entire cache namespace
- */
-export async function clearAllCache(ctx: AppContext) {
-  await ctx.cache.clear();
-}
-
-/**
- * Example 8: Cache with dynamic TTL based on data
- */
-interface CacheableData {
-  type: 'static' | 'volatile' | 'normal';
-  [key: string]: unknown;
-}
-
-export async function cacheWithDynamicTTL(
-  ctx: AppContext,
-  key: string,
-  data: CacheableData
-) {
-  // Determine TTL based on data characteristics
-  let ttl = 5 * 60 * 1000; // 5 minutes default
-
-  if (data.type === 'static') {
-    ttl = 60 * 60 * 1000; // 1 hour for static data
-  } else if (data.type === 'volatile') {
-    ttl = 60 * 1000; // 1 minute for volatile data
-  }
-
-  await ctx.cache.set(key, data, ttl);
-}
-
-/**
- * Example 9: Cache status check
- */
-export async function checkCacheHealth(ctx: AppContext) {
-  const testKey = 'health:check';
-  const testValue = {timestamp: Date.now(), random: Math.random()};
-
-  try {
-    // Test set
-    const setResult = await ctx.cache.set(testKey, testValue, 1000);
-
-    // Test get
-    const getResult = await ctx.cache.get(testKey);
-
-    // Test has
-    const hasResult = await ctx.cache.has(testKey);
-
-    // Test delete
-    const deleteResult = await ctx.cache.delete(testKey);
-
-    return {
-      healthy: true,
-      type: REDIS_URL ? 'Redis' : 'In-Memory',
-      operations: {
-        set: setResult,
-        get: JSON.stringify(getResult) === JSON.stringify(testValue),
-        has: hasResult,
-        delete: deleteResult,
-      },
-    };
-  } catch (error) {
-    return {
-      healthy: false,
-      error: error instanceof Error ? error.message : 'Unknown error',
-    };
-  }
-}
-
-// Mock database functions for example purposes
-async function fetchUserFromDatabase(userId: string) {
-  return {
-    id: userId,
-    name: `User ${userId}`,
-    email: `user${userId}@example.com`,
-    createdAt: new Date(),
-  };
-}
-
-async function fetchUsersFromDatabase(userIds: string[]) {
-  return userIds.map((id) => ({
-    id,
-    name: `User ${id}`,
-    email: `user${id}@example.com`,
-    createdAt: new Date(),
-  }));
-}
-
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-async function fetchUserRoles(_userId: string) {
-  return ['user', 'member'];
-}
-
-interface User {
-  id: string;
-  name: string;
-  email: string;
-  createdAt: Date;
-}
-
-function calculatePermissions(_user: User, roles: string[]) {
-  return {
-    canRead: true,
-    canWrite: roles.includes('admin'),
-    canDelete: roles.includes('admin'),
-  };
-}
-
-async function updateUserInDatabase(
-  userId: string,
-  updates: Record<string, unknown>
-) {
-  return {
-    id: userId,
-    ...updates,
-    updatedAt: new Date(),
-  };
-}
-
-/**
- * Usage in a Moleculer service:
- *
- * export default {
- *   name: 'users',
- *   middlewares: [CacheMiddleware],
- *
- *   started() {
- *     initializeCache();
- *   },
- *
- *   stopped() {
- *     return CacheMiddleware.stopped();
- *   },
- *
- *   actions: {
- *     get: {
- *       async handler(ctx) {
- *         return getUserWithWrap(ctx, ctx.params.id);
- *       }
- *     }
- *   }
- * }
- */

package/src/middlewares/cache.middleware.ts

@@ -1,278 +0,0 @@
-import KeyvRedis from '@keyv/redis';
-import Keyv from 'keyv';
-import {REDIS_URL} from '../env';
-import type {AppContext} from '../types';
-
-export interface CacheOptions {
-  redisUrl?: string;
-  ttl?: number; // Default TTL in milliseconds
-  namespace?: string;
-  serialize?: (value: unknown) => string;
-  deserialize?: (value: string) => unknown;
-}
-
-export interface CacheHelpers {
-  get<T = unknown>(key: string): Promise<T | undefined>;
-  set<T = unknown>(key: string, value: T, ttl?: number): Promise<boolean>;
-  delete(key: string): Promise<boolean>;
-  clear(): Promise<void>;
-  has(key: string): Promise<boolean>;
-  mget<T = unknown>(...keys: string[]): Promise<Array<T | undefined>>;
-  mset(entries: Record<string, unknown>, ttl?: number): Promise<boolean>;
-  mdel(...keys: string[]): Promise<boolean>;
-  wrap<T = unknown>(
-    key: string,
-    factory: () => Promise<T> | T,
-    ttl?: number
-  ): Promise<T>;
-}
-
-export class CacheService {
-  private keyv: Keyv;
-  private defaultTtl: number;
-
-  constructor(options: CacheOptions = {}) {
-    const {
-      redisUrl = REDIS_URL,
-      ttl = 5 * 60 * 1000, // 5 minutes default
-      namespace = 'cache',
-    } = options;
-
-    this.defaultTtl = ttl;
-
-    // Configure store based on Redis availability
-    const store = redisUrl ? new KeyvRedis(redisUrl) : new Map(); // In-memory fallback
-
-    this.keyv = new Keyv({
-      store,
-      namespace,
-      ttl,
-    });
-
-    // Error handling
-    this.keyv.on('error', () => {
-      // Silently handle errors - could be logged to a logger if available
-    });
-  }
-
-  /**
-   * Get a value from cache
-   */
-  async get<T = unknown>(key: string): Promise<T | undefined> {
-    try {
-      return await this.keyv.get<T>(key);
-    } catch {
-      return undefined;
-    }
-  }
-
-  /**
-   * Set a value in cache
-   */
-  async set<T = unknown>(
-    key: string,
-    value: T,
-    ttl?: number
-  ): Promise<boolean> {
-    try {
-      return await this.keyv.set(key, value, ttl);
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Delete a key from cache
-   */
-  async delete(key: string): Promise<boolean> {
-    try {
-      return await this.keyv.delete(key);
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Clear all keys with the namespace
-   */
-  async clear(): Promise<void> {
-    try {
-      await this.keyv.clear();
-    } catch {
-      // Silently handle errors
-    }
-  }
-
-  /**
-   * Check if a key exists
-   */
-  async has(key: string): Promise<boolean> {
-    try {
-      return await this.keyv.has(key);
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Get multiple values at once
-   */
-  async mget<T = unknown>(...keys: string[]): Promise<Array<T | undefined>> {
-    try {
-      const promises = keys.map((key) => this.get<T>(key));
-      return await Promise.all(promises);
-    } catch {
-      return keys.map(() => undefined);
-    }
-  }
-
-  /**
-   * Set multiple values at once
-   */
-  async mset(entries: Record<string, unknown>, ttl?: number): Promise<boolean> {
-    try {
-      const promises = Object.entries(entries).map(([key, value]) =>
-        this.set(key, value, ttl)
-      );
-      const results = await Promise.all(promises);
-      return results.every(Boolean);
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Delete multiple keys at once
-   */
-  async mdel(...keys: string[]): Promise<boolean> {
-    try {
-      const promises = keys.map((key) => this.delete(key));
-      const results = await Promise.all(promises);
-      return results.every(Boolean);
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Wrap pattern: Get from cache or calculate and cache
-   */
-  async wrap<T = unknown>(
-    key: string,
-    factory: () => Promise<T> | T,
-    ttl?: number
-  ): Promise<T> {
-    try {
-      // Try to get from cache
-      const cached = await this.get<T>(key);
-      if (cached !== undefined) {
-        return cached;
-      }
-
-      // Calculate value
-      const value = await factory();
-
-      // Cache the value
-      await this.set(key, value, ttl ?? this.defaultTtl);
-
-      return value;
-    } catch {
-      // In case of error, still try to return the factory value
-      return await factory();
-    }
-  }
-
-  /**
-   * Disconnect the cache (for cleanup)
-   */
-  async disconnect(): Promise<void> {
-    try {
-      await this.keyv.disconnect();
-    } catch {
-      // Silently handle errors
-    }
-  }
-}
-
-/**
- * Create cache middleware with specific options for a service
- */
-export function createCacheMiddleware(options: CacheOptions = {}) {
-  let cacheInstance: CacheService | null = null;
-
-  return {
-    /**
-     * Initialize cache on service start
-     */
-    started() {
-      cacheInstance = new CacheService(options);
-    },
-
-    /**
-     * Add cache helpers to context
-     */
-    localAction(handler: (...args: unknown[]) => unknown) {
-      return function CacheMiddlewareWrapper(this: unknown, ctx: AppContext) {
-        cacheInstance ??= new CacheService(options);
-
-        const instance = cacheInstance;
-
-        // Create scoped cache helpers
-        const cache: CacheHelpers = {
-          get: <T = unknown>(key: string) => instance.get<T>(key),
-
-          set: <T = unknown>(key: string, value: T, ttl?: number) =>
-            instance.set(key, value, ttl),
-
-          delete: (key: string) => instance.delete(key),
-
-          clear: () => instance.clear(),
-
-          has: (key: string) => instance.has(key),
-
-          mget: <T = unknown>(...keys: string[]) => instance.mget<T>(...keys),
-
-          mset: (entries: Record<string, unknown>, ttl?: number) =>
-            instance.mset(entries, ttl),
-
-          mdel: (...keys: string[]) => instance.mdel(...keys),
-
-          wrap: <T = unknown>(
-            key: string,
-            factory: () => Promise<T> | T,
-            ttl?: number
-          ) => instance.wrap<T>(key, factory, ttl),
-        };
-
-        // Add cache to context
-        ctx.cache = cache;
-
-        // Call the original handler
-        return handler.call(this, ctx);
-      };
-    },
-
-    /**
-     * Cleanup on service stop
-     */
-    stopped() {
-      if (cacheInstance) {
-        return cacheInstance.disconnect();
-      }
-    },
-  };
-}
-
-// Default cache middleware (backwards compatibility)
-export const CacheMiddleware = createCacheMiddleware();
-
-// Singleton instance for direct usage
-let globalCacheInstance: CacheService | null = null;
-
-export const getCacheInstance = (options?: CacheOptions) => {
-  if (options) {
-    return new CacheService(options);
-  }
-  globalCacheInstance ??= new CacheService();
-  return globalCacheInstance;
-};