@fjell/cache 4.6.14 → 4.6.16

package/examples/aggregator-example.ts

@@ -1,329 +0,0 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
-/**
- * Aggregator Example
- *
- * This example demonstrates advanced fjell-cache functionality using the Aggregator
- * for managing related entities with automatic population of references.
- *
- * Shows how to:
- * - Create aggregated caches with references between entities
- * - Populate items with their related data automatically
- * - Handle optional vs required aggregates
- * - Manage complex business relationships through caching
- */
-
-import { createAggregator } from '../src/Aggregator';
-import { createCache } from '../src/Cache';
-import { createInstance } from '../src/Instance';
-import { createRegistry } from '../src/Registry';
-import { ClientApi } from '@fjell/client-api';
-import { Item, PriKey } from '@fjell/core';
-import { createCoordinate } from '@fjell/registry';
-
-// Define our business models with relationships
-interface Customer extends Item<'customer'> {
-  id: string;
-  name: string;
-  email: string;
-  company: string;
-  tier: 'bronze' | 'silver' | 'gold' | 'platinum';
-}
-
-interface Order extends Item<'order'> {
-  id: string;
-  customerId: string;
-  total: number;
-  status: 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled';
-  items: string[]; // Array of product IDs
-  orderDate: Date;
-}
-
-interface Product extends Item<'product'> {
-  id: string;
-  name: string;
-  price: number;
-  category: string;
-  inStock: boolean;
-}
-
-interface SupportTicket extends Item<'ticket'> {
-  id: string;
-  customerId: string;
-  orderId?: string; // Optional reference to order
-  subject: string;
-  priority: 'low' | 'medium' | 'high' | 'urgent';
-  status: 'open' | 'in-progress' | 'resolved' | 'closed';
-  description: string;
-}
-
-// Mock storage
-const mockCustomers = new Map<string, Customer>();
-const mockOrders = new Map<string, Order>();
-const mockProducts = new Map<string, Product>();
-const mockTickets = new Map<string, SupportTicket>();
-
-// Helper to create mock APIs
-const createMockApi = <T extends Item<any>>(storage: Map<string, T>) => {
-  return {
-    async all(_query = {}) {
-      console.log(`📦 Fetching all items from ${storage.constructor.name}...`);
-      return Array.from(storage.values());
-    },
-    async one(query = {}) {
-      const items = await this.all!(query);
-      return items[0] || null;
-    },
-    async get(key: PriKey<any>) {
-      const item = storage.get(String(key.pk));
-      if (!item) {
-        throw new Error(`Item not found: ${key.pk}`);
-      }
-      return item;
-    },
-    async find(_finder = 'all') {
-      return await this.all!({});
-    }
-  } as Partial<ClientApi<T, any>>;
-};
-
-// Test data creation helpers
-const createCustomer = (id: string, name: string, email: string, company: string, tier: 'bronze' | 'silver' | 'gold' | 'platinum'): Customer => {
-  const customer: Customer = {
-    id, name, email, company, tier,
-    key: { kt: 'customer', pk: id },
-    events: { created: { at: new Date() }, updated: { at: new Date() }, deleted: { at: null } }
-  };
-  mockCustomers.set(id, customer);
-  return customer;
-};
-
-const createProduct = (id: string, name: string, price: number, category: string, inStock: boolean): Product => {
-  const product: Product = {
-    id, name, price, category, inStock,
-    key: { kt: 'product', pk: id },
-    events: { created: { at: new Date() }, updated: { at: new Date() }, deleted: { at: null } }
-  };
-  mockProducts.set(id, product);
-  return product;
-};
-
-const createOrder = (id: string, customerId: string, total: number, status: 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled', items: string[]): Order => {
-  const order: Order = {
-    id, customerId, total, status, items, orderDate: new Date(),
-    key: { kt: 'order', pk: id },
-    events: { created: { at: new Date() }, updated: { at: new Date() }, deleted: { at: null } },
-    // Add references for aggregation
-    refs: {
-      customer: { kt: 'customer', pk: customerId }
-    }
-  };
-  mockOrders.set(id, order);
-  return order;
-};
-
-const createSupportTicket = (
-  id: string,
-  customerId: string,
-  subject: string,
-  priority: 'low' | 'medium' | 'high' | 'urgent',
-  status: 'open' | 'in-progress' | 'resolved' | 'closed',
-  description: string,
-  // eslint-disable-next-line max-params
-  orderId?: string): SupportTicket => {
-  const ticket: SupportTicket = {
-    id, customerId, subject, priority, status, description, orderId,
-    key: { kt: 'ticket', pk: id },
-    events: { created: { at: new Date() }, updated: { at: new Date() }, deleted: { at: null } },
-    // Add references for aggregation
-    refs: {
-      customer: { kt: 'customer', pk: customerId },
-      ...(orderId && { order: { kt: 'order', pk: orderId } })
-    }
-  };
-  mockTickets.set(id, ticket);
-  return ticket;
-};
-
-export const runAggregatorExample = async (): Promise<void> => {
-  console.log('\n🚀 Fjell-Cache Aggregator Example');
-  console.log('=================================\n');
-
-  console.log('This example demonstrates advanced caching with entity relationships and aggregation.\n');
-
-  // Step 1: Create test data
-  console.log('Step 1: Creating business entities');
-  console.log('----------------------------------');
-
-  const customer1 = createCustomer('cust-1', 'Acme Corp', 'contact@acme.com', 'Acme Corporation', 'gold');
-  const customer2 = createCustomer('cust-2', 'TechStart Inc', 'hello@techstart.io', 'TechStart Inc', 'silver');
-
-  const product1 = createProduct('prod-1', 'Premium Widget', 299.99, 'widgets', true);
-  const product2 = createProduct('prod-2', 'Standard Widget', 199.99, 'widgets', true);
-  const product3 = createProduct('prod-3', 'Budget Widget', 99.99, 'widgets', false);
-
-  const order1 = createOrder('order-1', customer1.id, 499.98, 'shipped', [product1.id, product2.id]);
-  const order2 = createOrder('order-2', customer2.id, 199.99, 'pending', [product2.id]);
-
-  const ticket1 = createSupportTicket('ticket-1', customer1.id, 'Widget not working', 'high', 'open', 'The premium widget stopped working after 2 days', order1.id);
-  const ticket2 = createSupportTicket('ticket-2', customer2.id, 'General inquiry', 'low', 'resolved', 'Question about widget compatibility');
-
-  console.log(`✅ Created ${mockCustomers.size} customers, ${mockProducts.size} products, ${mockOrders.size} orders, ${mockTickets.size} tickets\n`);
-
-  // Step 2: Set up cache infrastructure
-  console.log('Step 2: Setting up cache infrastructure');
-  console.log('--------------------------------------');
-
-  const registry = createRegistry();
-  console.log('✅ Created registry');
-
-  // Create individual caches for each entity type
-  const customerApi = createMockApi(mockCustomers) as ClientApi<Customer, 'customer'>;
-  const orderApi = createMockApi(mockOrders) as ClientApi<Order, 'order'>;
-  const productApi = createMockApi(mockProducts) as ClientApi<Product, 'product'>;
-  const ticketApi = createMockApi(mockTickets) as ClientApi<SupportTicket, 'ticket'>;
-
-  const customerCache = await createCache(customerApi, createCoordinate('customer'), registry);
-  const orderCache = await createCache(orderApi, createCoordinate('order'), registry);
-  const productCache = await createCache(productApi, createCoordinate('product'), registry);
-  const ticketCache = await createCache(ticketApi, createCoordinate('ticket'), registry);
-
-  console.log('✅ Created individual caches for each entity type');
-
-  // Step 3: Create aggregated caches
-  console.log('\nStep 3: Creating aggregated caches');
-  console.log('----------------------------------');
-
-  // Create order aggregator that automatically populates customer data
-  const orderAggregator = await createAggregator(orderCache, {
-    aggregates: {
-      customer: { cache: customerCache, optional: false }, // Required reference
-    },
-    events: {}
-  });
-
-  // Create support ticket aggregator with both customer and order references
-  const ticketAggregator = await createAggregator(ticketCache, {
-    aggregates: {
-      customer: { cache: customerCache, optional: false }, // Required reference
-      order: { cache: orderCache, optional: true }, // Optional reference (not all tickets relate to orders)
-    },
-    events: {}
-  });
-
-  console.log('✅ Created aggregated caches with relationship mappings (aggregators are now instances)\n');
-
-  // Step 4: Basic aggregation - Fetch orders with customer data
-  console.log('Step 4: Order aggregation with customer data');
-  console.log('--------------------------------------------');
-
-  const [, orders] = await orderAggregator.all();
-  console.log(`📋 Fetched ${orders.length} orders`);
-
-  for (const order of orders) {
-    console.log(`\n📦 Order ${order.id}:`);
-    console.log(`   Amount: $${order.total}`);
-    console.log(`   Status: ${order.status}`);
-    console.log(`   Items: ${order.items.join(', ')}`);
-
-    // Populate the order with customer data
-    const populatedOrder = await orderAggregator.populate(order);
-    if (populatedOrder.aggs?.customer?.item) {
-      const customer = populatedOrder.aggs.customer.item;
-      console.log(`   👤 Customer: ${customer.name} (${customer.email})`);
-      console.log(`   🏢 Company: ${customer.company} - ${customer.tier} tier`);
-    }
-  }
-
-  // Step 5: Complex aggregation - Support tickets with multiple references
-  console.log('\n\nStep 5: Support ticket aggregation with multiple references');
-  console.log('----------------------------------------------------------');
-
-  const [, tickets] = await ticketAggregator.all();
-  console.log(`🎫 Fetched ${tickets.length} support tickets`);
-
-  for (const ticket of tickets) {
-    console.log(`\n🎫 Ticket ${ticket.id}:`);
-    console.log(`   Subject: ${ticket.subject}`);
-    console.log(`   Priority: ${ticket.priority}`);
-    console.log(`   Status: ${ticket.status}`);
-    console.log(`   Description: ${ticket.description}`);
-
-    // Populate the ticket with all related data
-    const populatedTicket = await ticketAggregator.populate(ticket);
-
-    // Customer data (required reference)
-    if (populatedTicket.aggs?.customer?.item) {
-      const customer = populatedTicket.aggs.customer.item;
-      console.log(`   👤 Customer: ${customer.name} (${customer.email}) - ${customer.tier} tier`);
-    }
-
-    // Order data (optional reference)
-    if (populatedTicket.aggs?.order?.item) {
-      const order = populatedTicket.aggs.order.item;
-      console.log(`   📦 Related Order: ${order.id} - $${order.total} (${order.status})`);
-    } else {
-      console.log(`   📦 No related order`);
-    }
-  }
-
-  // Step 6: Individual item retrieval with aggregation
-  console.log('\n\nStep 6: Individual item retrieval with aggregation');
-  console.log('-------------------------------------------------');
-
-  const [, specificOrder] = await orderAggregator.get(order1.key);
-  if (specificOrder) {
-    console.log(`🔍 Retrieved specific order: ${specificOrder.id}`);
-
-    const populatedSpecificOrder = await orderAggregator.populate(specificOrder);
-    if (populatedSpecificOrder.aggs?.customer?.item) {
-      const customer = populatedSpecificOrder.aggs.customer.item;
-      console.log(`   Automatically populated customer: ${customer.name}`);
-    }
-  }
-
-  // Step 7: Demonstrating cache efficiency with aggregation
-  console.log('\n\nStep 7: Cache efficiency demonstration');
-  console.log('-------------------------------------');
-
-  console.log('🎯 First population (will fetch from storage):');
-  const startTime1 = Date.now();
-  const populated1 = await orderAggregator.populate(order1);
-  const time1 = Date.now() - startTime1;
-  console.log(`   Populated order with customer data in ${time1}ms`);
-
-  console.log('🎯 Second population (should use cached data):');
-  const startTime2 = Date.now();
-  const populated2 = await orderAggregator.populate(order1);
-  const time2 = Date.now() - startTime2;
-  console.log(`   Populated same order in ${time2}ms (cached)`);
-
-  console.log(`   📊 Cache efficiency: ${Math.round(((time1 - time2) / time1) * 100)}% faster on second call`);
-
-  // Step 8: Aggregate management and statistics
-  console.log('\n\nStep 8: Aggregate management and statistics');
-  console.log('------------------------------------------');
-
-  console.log('📊 Cache Statistics:');
-  console.log(`   👥 Customers cached: ${mockCustomers.size}`);
-  console.log(`   📦 Orders cached: ${mockOrders.size}`);
-  console.log(`   📦 Products cached: ${mockProducts.size}`);
-  console.log(`   🎫 Tickets cached: ${mockTickets.size}`);
-  console.log(`   🔗 Order aggregator references: customer (required)`);
-  console.log(`   🔗 Ticket aggregator references: customer (required), order (optional)`);
-
-  console.log('\n🎉 Aggregator Example Complete!');
-  console.log('===============================\n');
-
-  console.log('Key concepts demonstrated:');
-  console.log('• Creating aggregated caches with entity relationships');
-  console.log('• Automatic population of referenced entities');
-  console.log('• Required vs optional aggregate references');
-  console.log('• Cache efficiency through aggregation');
-  console.log('• Complex business model relationships');
-  console.log('• Performance benefits of cached aggregates\n');
-};
-
-// Run the example if this file is executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
-  runAggregatorExample().catch(console.error);
-}

package/examples/basic-cache-example.ts

@@ -1,270 +0,0 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
-/**
- * Basic Cache Example
- *
- * This example demonstrates the fundamental usage of fjell-cache for caching data models.
- * It shows how to create caches, perform basic operations like get/set/all, and manage
- * cached data with mock storage operations.
- *
- * Perfect for understanding the basics of fjell-cache before moving to advanced features.
- */
-
-import { createCache } from '../src/Cache';
-import { createInstance } from '../src/Instance';
-import { createRegistry } from '../src/Registry';
-import { ClientApi } from '@fjell/client-api';
-import { Item, PriKey } from '@fjell/core';
-import { createCoordinate } from '@fjell/registry';
-
-// Define our data models
-interface User extends Item<'user'> {
-  id: string;
-  name: string;
-  email: string;
-  role: 'admin' | 'user' | 'guest';
-}
-
-interface Task extends Item<'task'> {
-  id: string;
-  title: string;
-  description: string;
-  assignedTo?: string;
-  status: 'pending' | 'in-progress' | 'completed';
-  priority: 'low' | 'medium' | 'high';
-}
-
-// Mock storage for demonstration (in real apps, this would be your database/API)
-const mockUserStorage = new Map<string, User>();
-const mockTaskStorage = new Map<string, Task>();
-
-// Simple mock API for Users (simplified to avoid type issues)
-const createUserApi = (): Partial<ClientApi<User, 'user'>> => ({
-  async all(query = {}) {
-    console.log('📦 Fetching all users from storage...');
-    return Array.from(mockUserStorage.values());
-  },
-
-  async one(query = {}) {
-    const users = await this.all!(query);
-    return users[0] || null;
-  },
-
-  async get(key: PriKey<'user'>) {
-    console.log(`🔍 Getting user with key: ${key.pk}`);
-    const user = mockUserStorage.get(String(key.pk));
-    if (!user) {
-      throw new Error(`User not found: ${key.pk}`);
-    }
-    return user;
-  },
-
-  async find(finder = 'all') {
-    return await this.all!({});
-  }
-});
-
-// Simple mock API for Tasks
-const createTaskApi = (): Partial<ClientApi<Task, 'task'>> => ({
-  async all(query = {}) {
-    console.log('📦 Fetching all tasks from storage...');
-    return Array.from(mockTaskStorage.values());
-  },
-
-  async one(query = {}) {
-    const tasks = await this.all!(query);
-    return tasks[0] || null;
-  },
-
-  async get(key: PriKey<'task'>) {
-    console.log(`🔍 Getting task with key: ${key.pk}`);
-    const task = mockTaskStorage.get(String(key.pk));
-    if (!task) {
-      throw new Error(`Task not found: ${key.pk}`);
-    }
-    return task;
-  },
-
-  async find(finder = 'all') {
-    return await this.all!({});
-  }
-});
-
-// Helper function to create test data
-const createTestUser = (id: string, name: string, email: string, role: 'admin' | 'user' | 'guest'): User => {
-  const user: User = {
-    id,
-    name,
-    email,
-    role,
-    key: { kt: 'user', pk: id },
-    events: {
-      created: { at: new Date() },
-      updated: { at: new Date() },
-      deleted: { at: null }
-    }
-  };
-  mockUserStorage.set(id, user);
-  console.log(`✅ Created user: ${user.name} (${user.email})`);
-  return user;
-};
-
-const createTestTask = (id: string, title: string, description: string, assignedTo: string, status: 'pending' | 'in-progress' | 'completed', priority: 'low' | 'medium' | 'high'): Task => {
-  const task: Task = {
-    id,
-    title,
-    description,
-    assignedTo,
-    status,
-    priority,
-    key: { kt: 'task', pk: id },
-    events: {
-      created: { at: new Date() },
-      updated: { at: new Date() },
-      deleted: { at: null }
-    }
-  };
-  mockTaskStorage.set(id, task);
-  console.log(`✅ Created task: ${task.title}`);
-  return task;
-};
-
-// Main example function
-export const runBasicCacheExample = async (): Promise<void> => {
-  console.log('\n🚀 Fjell-Cache Basic Example');
-  console.log('============================\n');
-
-  console.log('This example demonstrates basic cache operations with User and Task models.\n');
-
-  // Step 1: Create registry and cache instances
-  console.log('Step 1: Setting up cache infrastructure');
-  console.log('--------------------------------------');
-
-  const registry = createRegistry();
-  console.log('✅ Created cache registry');
-
-  const userApi = createUserApi() as ClientApi<User, 'user'>;
-  const taskApi = createTaskApi() as ClientApi<Task, 'task'>;
-  console.log('✅ Created mock APIs for users and tasks');
-
-  const userCache = await createCache(userApi, createCoordinate('user'), registry);
-  const taskCache = await createCache(taskApi, createCoordinate('task'), registry);
-  console.log('✅ Created cache instances (which are now also instances)');
-  console.log('✅ Created cache model instances\n');
-
-  // Step 2: Create some test data
-  console.log('Step 2: Creating test data');
-  console.log('-------------------------');
-
-  const user1 = createTestUser('user-1', 'Alice Johnson', 'alice@example.com', 'admin');
-  const user2 = createTestUser('user-2', 'Bob Smith', 'bob@example.com', 'user');
-
-  const task1 = createTestTask('task-1', 'Setup project repository', 'Initialize Git repo and create basic structure', user1.id, 'completed', 'high');
-  const task2 = createTestTask('task-2', 'Implement user authentication', 'Add login and registration functionality', user2.id, 'in-progress', 'medium');
-
-  console.log('✅ Created test users and tasks\n');
-
-  // Step 3: Cache operations - Fetch and cache all items
-  console.log('Step 3: Cache operations - Fetching all items');
-  console.log('----------------------------------------------');
-
-  const [, allUsers] = await userCache.operations.all();
-  console.log(`📋 Cached ${allUsers.length} users:`, allUsers.map((u: User) => u.name));
-
-  const [, allTasks] = await taskCache.operations.all();
-  console.log(`📋 Cached ${allTasks.length} tasks:`, allTasks.map((t: Task) => t.title));
-  console.log('');
-
-  // Step 4: Individual item retrieval from cache
-  console.log('Step 4: Individual item retrieval');
-  console.log('---------------------------------');
-
-  const [, cachedUser1] = await userCache.operations.get(user1.key);
-  console.log(`👤 Retrieved from cache: ${cachedUser1?.name} (${cachedUser1?.email})`);
-
-  const [, cachedTask1] = await taskCache.operations.get(task1.key);
-  console.log(`📝 Retrieved from cache: ${cachedTask1?.title} - Status: ${cachedTask1?.status}`);
-  console.log('');
-
-  // Step 5: Cache hit vs miss demonstration
-  console.log('Step 5: Cache behavior demonstration');
-  console.log('-----------------------------------');
-
-  // This should hit the cache (no API call)
-  console.log('🎯 Second retrieval (should hit cache):');
-  const [, cachedUser1Again] = await userCache.operations.retrieve(user1.key);
-  console.log(`👤 Retrieved: ${cachedUser1Again?.name} (cache hit)`);
-
-  // Create a new user and demonstrate cache miss
-  const user3 = createTestUser('user-3', 'Charlie Brown', 'charlie@example.com', 'guest');
-
-  console.log('🎯 New item retrieval (cache miss, will fetch from API):');
-  const [, cachedUser3] = await userCache.operations.get(user3.key);
-  console.log(`👤 Retrieved: ${cachedUser3?.name} (fetched from API and cached)`);
-  console.log('');
-
-  // Step 6: Cache updates
-  console.log('Step 6: Cache updates');
-  console.log('--------------------');
-
-  const updatedTask2 = { ...task2, status: 'completed' as const, description: 'Add login and registration functionality - COMPLETED!' };
-  mockTaskStorage.set(task2.id, updatedTask2);
-
-  // Update cache with new version
-  await taskCache.operations.set(updatedTask2.key, updatedTask2);
-  console.log(`🔄 Updated task in cache: ${updatedTask2.title} - New status: ${updatedTask2.status}`);
-  console.log('');
-
-  // Step 7: Query operations
-  console.log('Step 7: Query operations');
-  console.log('-----------------------');
-
-  const [, foundTasks] = await taskCache.operations.find('all');
-  console.log(`🔍 Found ${foundTasks.length} tasks through cache query`);
-
-  const [, oneTask] = await taskCache.operations.one();
-  console.log(`📝 Retrieved one task: ${oneTask?.title}`);
-  console.log('');
-
-  // Step 8: Cache statistics and management
-  console.log('Step 8: Cache management');
-  console.log('-----------------------');
-
-  console.log('📊 Cache Statistics:');
-  console.log(`   👥 Users in cache: ${allUsers.length}`);
-  console.log(`   📝 Tasks in cache: ${allTasks.length}`);
-  console.log(`   🎯 User cache coordinate: ${userCache.coordinate.kta[0]}`);
-  console.log(`   🎯 Task cache coordinate: ${taskCache.coordinate.kta[0]}`);
-  console.log('');
-
-  // Step 9: Cleanup demonstration
-  console.log('Step 9: Cleanup demonstration');
-  console.log('-----------------------------');
-
-  mockUserStorage.delete('user-3');
-  console.log('🗑️ Removed user from storage');
-
-  // Cache still has the old data until next fetch
-  const [, stillCachedUser3] = await userCache.operations.retrieve(user3.key);
-  console.log(`🎯 Cache still contains removed user: ${stillCachedUser3?.name || 'null'}`);
-
-  // Fresh fetch will update cache
-  const [, freshAllUsers] = await userCache.operations.all();
-  console.log(`📋 Fresh fetch shows ${freshAllUsers.length} users (cache updated)`);
-  console.log('');
-
-  console.log('🎉 Basic Cache Example Complete!');
-  console.log('================================\n');
-
-  console.log('Key concepts demonstrated:');
-  console.log('• Cache creation with registry and instances');
-  console.log('• Basic cache operations (get, set, all, find, one)');
-  console.log('• Cache hits vs misses');
-  console.log('• Cache updates and management');
-  console.log('• Integration with mock storage APIs');
-  console.log('• Cache lifecycle and data consistency\n');
-};
-
-// Run the example if this file is executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
-  runBasicCacheExample().catch(console.error);
-}