@fjell/cache 4.6.10 → 4.6.11

package/dist/ops/one.es.js

@@ -0,0 +1,29 @@
+import { validatePK } from '@fjell/core';
+import { NotFoundError } from '@fjell/http-api';
+import LibLogger from '../logger.es.js';
+
+const logger = LibLogger.get('one');
+const one = async (api, cacheMap, pkType, query = {}, locations = [])=>{
+    logger.default('one', {
+        query,
+        locations
+    });
+    let retItem = null;
+    try {
+        retItem = await api.one(query, locations);
+        if (retItem) {
+            cacheMap.set(retItem.key, retItem);
+        }
+    } catch (e) {
+        if (e instanceof NotFoundError) ; else {
+            throw e;
+        }
+    }
+    return [
+        cacheMap,
+        retItem ? validatePK(retItem, pkType) : null
+    ];
+};
+
+export { one };
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoib25lLmVzLmpzIiwic291cmNlcyI6W10sInNvdXJjZXNDb250ZW50IjpbXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7In0=

package/dist/ops/remove.cjs.js

@@ -0,0 +1,30 @@
+'use strict';
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const core = require('@fjell/core');
+const logger$1 = require('../logger.cjs.js');
+
+const logger = logger$1.default.get('remove');
+const remove = async (api, cacheMap, key)=>{
+    logger.default('remove', {
+        key
+    });
+    if (!core.isValidItemKey(key)) {
+        logger.error('Key for Remove is not a valid ItemKey: %j', key);
+        throw new Error('Key for Remove is not a valid ItemKey');
+    }
+    try {
+        await api.remove(key);
+        cacheMap.delete(key);
+    } catch (e) {
+        logger.error("Error deleting item", {
+            error: e
+        });
+        throw e;
+    }
+    return cacheMap;
+};
+
+exports.remove = remove;
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVtb3ZlLmNqcy5qcyIsInNvdXJjZXMiOltdLCJzb3VyY2VzQ29udGVudCI6W10sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OzsifQ==

package/dist/ops/remove.d.ts

@@ -0,0 +1,4 @@
+import { ComKey, Item, PriKey } from '@fjell/core';
+import { ClientApi } from '@fjell/client-api';
+import { CacheMap } from '../CacheMap';
+export declare const remove: <V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(api: ClientApi<V, S, L1, L2, L3, L4, L5>, cacheMap: CacheMap<V, S, L1, L2, L3, L4, L5>, key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>) => Promise<CacheMap<V, S, L1, L2, L3, L4, L5>>;

package/dist/ops/remove.es.js

@@ -0,0 +1,26 @@
+import { isValidItemKey } from '@fjell/core';
+import LibLogger from '../logger.es.js';
+
+const logger = LibLogger.get('remove');
+const remove = async (api, cacheMap, key)=>{
+    logger.default('remove', {
+        key
+    });
+    if (!isValidItemKey(key)) {
+        logger.error('Key for Remove is not a valid ItemKey: %j', key);
+        throw new Error('Key for Remove is not a valid ItemKey');
+    }
+    try {
+        await api.remove(key);
+        cacheMap.delete(key);
+    } catch (e) {
+        logger.error("Error deleting item", {
+            error: e
+        });
+        throw e;
+    }
+    return cacheMap;
+};
+
+export { remove };
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVtb3ZlLmVzLmpzIiwic291cmNlcyI6W10sInNvdXJjZXNDb250ZW50IjpbXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7In0=

package/dist/ops/reset.cjs.js

@@ -0,0 +1,15 @@
+'use strict';
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const CacheMap = require('../CacheMap.cjs.js');
+
+const reset = async (coordinate)=>{
+    const cacheMap = new CacheMap.CacheMap(coordinate.kta);
+    return [
+        cacheMap
+    ];
+};
+
+exports.reset = reset;
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVzZXQuY2pzLmpzIiwic291cmNlcyI6W10sInNvdXJjZXNDb250ZW50IjpbXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7OyJ9

package/dist/ops/reset.d.ts

@@ -0,0 +1,4 @@
+import { Item } from '@fjell/core';
+import { CacheMap } from '../CacheMap';
+import { Coordinate } from '@fjell/registry';
+export declare const reset: <V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(coordinate: Coordinate<S, L1, L2, L3, L4, L5>) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>]>;

package/dist/ops/reset.es.js

@@ -0,0 +1,11 @@
+import { CacheMap } from '../CacheMap.es.js';
+
+const reset = async (coordinate)=>{
+    const cacheMap = new CacheMap(coordinate.kta);
+    return [
+        cacheMap
+    ];
+};
+
+export { reset };
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVzZXQuZXMuanMiLCJzb3VyY2VzIjpbXSwic291cmNlc0NvbnRlbnQiOltdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7Ozs7OzsifQ==

package/dist/ops/retrieve.cjs.js

@@ -0,0 +1,37 @@
+'use strict';
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const core = require('@fjell/core');
+const logger$1 = require('../logger.cjs.js');
+const get = require('./get.cjs.js');
+
+const logger = logger$1.default.get('retrieve');
+const retrieve = async (api, cacheMap, pkType, key)=>{
+    logger.default('retrieve', {
+        key
+    });
+    if (!core.isValidItemKey(key)) {
+        logger.error('Key for Retrieve is not a valid ItemKey: %j', key);
+        throw new Error('Key for Retrieve is not a valid ItemKey');
+    }
+    const containsItemKey = cacheMap.includesKey(key);
+    let retrieved;
+    if (containsItemKey) {
+        logger.default('Looking for Object in Cache', key);
+        retrieved = cacheMap.get(key);
+    } else {
+        logger.default('Object Not Found in Cache, Retrieving from Server API', {
+            key
+        });
+        [, retrieved] = await get.get(api, cacheMap, pkType, key);
+    }
+    const retValue = [
+        containsItemKey ? null : cacheMap,
+        retrieved ? core.validatePK(retrieved, pkType) : null
+    ];
+    return retValue;
+};
+
+exports.retrieve = retrieve;
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmV0cmlldmUuY2pzLmpzIiwic291cmNlcyI6W10sInNvdXJjZXNDb250ZW50IjpbXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OzsifQ==

package/dist/ops/retrieve.d.ts

@@ -0,0 +1,4 @@
+import { ComKey, Item, PriKey } from '@fjell/core';
+import { CacheMap } from '../CacheMap';
+import { ClientApi } from '@fjell/client-api';
+export declare const retrieve: <V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(api: ClientApi<V, S, L1, L2, L3, L4, L5>, cacheMap: CacheMap<V, S, L1, L2, L3, L4, L5>, pkType: S, key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5> | null, V | null]>;

package/dist/ops/retrieve.es.js

@@ -0,0 +1,33 @@
+import { isValidItemKey, validatePK } from '@fjell/core';
+import LibLogger from '../logger.es.js';
+import { get } from './get.es.js';
+
+const logger = LibLogger.get('retrieve');
+const retrieve = async (api, cacheMap, pkType, key)=>{
+    logger.default('retrieve', {
+        key
+    });
+    if (!isValidItemKey(key)) {
+        logger.error('Key for Retrieve is not a valid ItemKey: %j', key);
+        throw new Error('Key for Retrieve is not a valid ItemKey');
+    }
+    const containsItemKey = cacheMap.includesKey(key);
+    let retrieved;
+    if (containsItemKey) {
+        logger.default('Looking for Object in Cache', key);
+        retrieved = cacheMap.get(key);
+    } else {
+        logger.default('Object Not Found in Cache, Retrieving from Server API', {
+            key
+        });
+        [, retrieved] = await get(api, cacheMap, pkType, key);
+    }
+    const retValue = [
+        containsItemKey ? null : cacheMap,
+        retrieved ? validatePK(retrieved, pkType) : null
+    ];
+    return retValue;
+};
+
+export { retrieve };
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmV0cmlldmUuZXMuanMiLCJzb3VyY2VzIjpbXSwic291cmNlc0NvbnRlbnQiOltdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7In0=

package/dist/ops/set.cjs.js

@@ -0,0 +1,71 @@
+'use strict';
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const core = require('@fjell/core');
+const logger$1 = require('../logger.cjs.js');
+
+const logger = logger$1.default.get('set');
+// Normalize a key value to string for consistent comparison
+const normalizeKeyValue = (value)=>{
+    return String(value);
+};
+// Normalized key comparison function that handles string/number differences
+const isItemKeyEqualNormalized = (a, b)=>{
+    // For now, just normalize the keys to strings and use the original comparison
+    const normalizedA = normalizeKey(a);
+    const normalizedB = normalizeKey(b);
+    return core.isItemKeyEqual(normalizedA, normalizedB);
+};
+// Helper function to normalize a key
+const normalizeKey = (key)=>{
+    if (typeof key === 'object' && key !== null) {
+        const normalizedKey = JSON.parse(JSON.stringify(key));
+        // Normalize pk values
+        if ('pk' in normalizedKey && normalizedKey.pk !== null) {
+            normalizedKey.pk = normalizeKeyValue(normalizedKey.pk);
+        }
+        // Normalize lk values
+        if ('lk' in normalizedKey && normalizedKey.lk !== null) {
+            normalizedKey.lk = normalizeKeyValue(normalizedKey.lk);
+        }
+        // Normalize loc array lk values
+        if ('loc' in normalizedKey && Array.isArray(normalizedKey.loc)) {
+            normalizedKey.loc = normalizedKey.loc.map((locItem)=>{
+                if (locItem && 'lk' in locItem && locItem.lk !== null) {
+                    return {
+                        ...locItem,
+                        lk: normalizeKeyValue(locItem.lk)
+                    };
+                }
+                return locItem;
+            });
+        }
+        return normalizedKey;
+    }
+    return key;
+};
+const set = async (cacheMap, pkType, key, v)=>{
+    logger.default('set', {
+        key,
+        v
+    });
+    if (!core.isValidItemKey(key)) {
+        logger.error('Key for Set is not a valid ItemKey: %j', key);
+        throw new Error('Key for Set is not a valid ItemKey');
+    }
+    // Validate the item's primary key
+    core.validatePK(v, pkType);
+    if (!isItemKeyEqualNormalized(key, v.key)) {
+        logger.error('Key does not match item key: %j != %j', key, v.key);
+        throw new Error('Key does not match item key');
+    }
+    cacheMap.set(key, v);
+    return [
+        cacheMap,
+        core.validatePK(v, pkType)
+    ];
+};
+
+exports.set = set;
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2V0LmNqcy5qcyIsInNvdXJjZXMiOltdLCJzb3VyY2VzQ29udGVudCI6W10sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OyJ9

package/dist/ops/set.d.ts

@@ -0,0 +1,3 @@
+import { ComKey, Item, PriKey } from '@fjell/core';
+import { CacheMap } from '../CacheMap';
+export declare const set: <V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(cacheMap: CacheMap<V, S, L1, L2, L3, L4, L5>, pkType: S, key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, v: Item<S, L1, L2, L3, L4, L5>) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V]>;

package/dist/ops/set.es.js

@@ -0,0 +1,67 @@
+import { isValidItemKey, validatePK, isItemKeyEqual } from '@fjell/core';
+import LibLogger from '../logger.es.js';
+
+const logger = LibLogger.get('set');
+// Normalize a key value to string for consistent comparison
+const normalizeKeyValue = (value)=>{
+    return String(value);
+};
+// Normalized key comparison function that handles string/number differences
+const isItemKeyEqualNormalized = (a, b)=>{
+    // For now, just normalize the keys to strings and use the original comparison
+    const normalizedA = normalizeKey(a);
+    const normalizedB = normalizeKey(b);
+    return isItemKeyEqual(normalizedA, normalizedB);
+};
+// Helper function to normalize a key
+const normalizeKey = (key)=>{
+    if (typeof key === 'object' && key !== null) {
+        const normalizedKey = JSON.parse(JSON.stringify(key));
+        // Normalize pk values
+        if ('pk' in normalizedKey && normalizedKey.pk !== null) {
+            normalizedKey.pk = normalizeKeyValue(normalizedKey.pk);
+        }
+        // Normalize lk values
+        if ('lk' in normalizedKey && normalizedKey.lk !== null) {
+            normalizedKey.lk = normalizeKeyValue(normalizedKey.lk);
+        }
+        // Normalize loc array lk values
+        if ('loc' in normalizedKey && Array.isArray(normalizedKey.loc)) {
+            normalizedKey.loc = normalizedKey.loc.map((locItem)=>{
+                if (locItem && 'lk' in locItem && locItem.lk !== null) {
+                    return {
+                        ...locItem,
+                        lk: normalizeKeyValue(locItem.lk)
+                    };
+                }
+                return locItem;
+            });
+        }
+        return normalizedKey;
+    }
+    return key;
+};
+const set = async (cacheMap, pkType, key, v)=>{
+    logger.default('set', {
+        key,
+        v
+    });
+    if (!isValidItemKey(key)) {
+        logger.error('Key for Set is not a valid ItemKey: %j', key);
+        throw new Error('Key for Set is not a valid ItemKey');
+    }
+    // Validate the item's primary key
+    validatePK(v, pkType);
+    if (!isItemKeyEqualNormalized(key, v.key)) {
+        logger.error('Key does not match item key: %j != %j', key, v.key);
+        throw new Error('Key does not match item key');
+    }
+    cacheMap.set(key, v);
+    return [
+        cacheMap,
+        validatePK(v, pkType)
+    ];
+};
+
+export { set };
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2V0LmVzLmpzIiwic291cmNlcyI6W10sInNvdXJjZXNDb250ZW50IjpbXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OzsifQ==

package/dist/ops/update.cjs.js

@@ -0,0 +1,34 @@
+'use strict';
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const core = require('@fjell/core');
+const logger$1 = require('../logger.cjs.js');
+
+const logger = logger$1.default.get('update');
+const update = async (api, cacheMap, pkType, key, v)=>{
+    logger.default('update', {
+        key,
+        v
+    });
+    if (!core.isValidItemKey(key)) {
+        logger.error('Key for Update is not a valid ItemKey: %j', key);
+        throw new Error('Key for Update is not a valid ItemKey');
+    }
+    try {
+        const updated = await api.update(key, v);
+        cacheMap.set(updated.key, updated);
+        return [
+            cacheMap,
+            core.validatePK(updated, pkType)
+        ];
+    } catch (e) {
+        logger.error("Error updating item", {
+            error: e
+        });
+        throw e;
+    }
+};
+
+exports.update = update;
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidXBkYXRlLmNqcy5qcyIsInNvdXJjZXMiOltdLCJzb3VyY2VzQ29udGVudCI6W10sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7In0=

package/dist/ops/update.d.ts

@@ -0,0 +1,4 @@
+import { ComKey, Item, PriKey } from '@fjell/core';
+import { ClientApi } from '@fjell/client-api';
+import { CacheMap } from '../CacheMap';
+export declare const update: <V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(api: ClientApi<V, S, L1, L2, L3, L4, L5>, cacheMap: CacheMap<V, S, L1, L2, L3, L4, L5>, pkType: S, key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, v: Partial<Item<S, L1, L2, L3, L4, L5>>) => Promise<[CacheMap<V, S, L1, L2, L3, L4, L5>, V]>;

package/dist/ops/update.es.js

@@ -0,0 +1,30 @@
+import { isValidItemKey, validatePK } from '@fjell/core';
+import LibLogger from '../logger.es.js';
+
+const logger = LibLogger.get('update');
+const update = async (api, cacheMap, pkType, key, v)=>{
+    logger.default('update', {
+        key,
+        v
+    });
+    if (!isValidItemKey(key)) {
+        logger.error('Key for Update is not a valid ItemKey: %j', key);
+        throw new Error('Key for Update is not a valid ItemKey');
+    }
+    try {
+        const updated = await api.update(key, v);
+        cacheMap.set(updated.key, updated);
+        return [
+            cacheMap,
+            validatePK(updated, pkType)
+        ];
+    } catch (e) {
+        logger.error("Error updating item", {
+            error: e
+        });
+        throw e;
+    }
+};
+
+export { update };
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidXBkYXRlLmVzLmpzIiwic291cmNlcyI6W10sInNvdXJjZXNDb250ZW50IjpbXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OyJ9

package/examples/README.md

@@ -6,11 +6,11 @@ This directory contains examples demonstrating how to use fjell-cache for cachin
 
 ### 1. `basic-cache-example.ts` ⭐ **Start Here!**
 **Perfect for beginners!** Demonstrates the fundamental way to use fjell-cache for data caching:
-- **Basic cache operations** - Create caches, get/set items, manage cache lifecycle
+- **Basic cache operations** - Create caches with coordinates and registries, use operations API
 - **Simple data models** - User and Task entities with mock storage
-- **Registry and Instance creation** - Set up cache model instances
+- **Cache-as-Instance architecture** - Caches extend Instance from fjell-registry
 - **Cache hits vs misses** - Understand cache behavior and performance benefits
-- **Cache management** - Updates, deletions, and data consistency
+- **Cache management** - Updates, deletions, and data consistency through operations
 
 Great for understanding the fundamentals of fjell-cache data management.
 
@@ -39,7 +39,8 @@ Perfect for understanding the underlying cache mechanisms and advanced use cases
 ### Basic Caching Operations (basic-cache-example.ts)
 ```typescript
 // Import fjell-cache functionality
-import { createCache, createRegistry, createInstance } from '@fjell/cache';
+import { createCache } from '@fjell/cache';
+import { createCoordinate, createRegistry } from '@fjell/registry';
 import { ClientApi } from '@fjell/client-api';
 
 // Create a registry for cache management
@@ -47,17 +48,15 @@ const registry = createRegistry();
 
 // Create a cache instance with API integration
 const userApi = createUserApi(); // Your API implementation
-const userCache = await createCache(userApi, 'user');
-
-// Create cache model instance
-const userInstance = createInstance(registry, createCoordinate('user'), userCache);
+const userCache = await createCache(userApi, createCoordinate('user'), registry);
 
-// Perform cache operations
-const [cacheMap, allUsers] = await userInstance.cache.all();
-const [, cachedUser] = await userInstance.cache.get(userKey);
-const [, retrievedUser] = await userInstance.cache.retrieve(userKey); // Cache hit!
+// Cache is now an instance - no need for separate createInstance call
+// Perform cache operations through the operations API
+const [cacheMap, allUsers] = await userCache.operations.all();
+const [, cachedUser] = await userCache.operations.get(userKey);
+const [, retrievedUser] = await userCache.operations.retrieve(userKey); // Cache hit!
 
-await userInstance.cache.set(userKey, updatedUser);
+await userCache.operations.set(userKey, updatedUser);
 ```
 
 ### Advanced Aggregation (aggregator-example.ts)
@@ -78,8 +77,8 @@ if (populatedOrder.aggs?.customer?.item) {
   console.log(`Order for: ${customer.name} (${customer.email})`);
 }
 
-// Create aggregated cache instance
-const orderInstance = createInstance(registry, createCoordinate('order'), orderAggregator);
+// Aggregator is now itself an instance - access operations directly
+const [, orders] = await orderAggregator.all();
 ```
 
 ### Direct Cache Management (cache-map-example.ts)
@@ -262,18 +261,16 @@ const populatedTicket = await ticketAggregator.populate(ticket);
 
 ### Performance Optimization
 ```typescript
-// Cache with performance tuning
-const cache = await createCache(api, 'product', {
-  batchSize: 100,          // Batch operations
-  prefetch: true,          // Prefetch related items
-  compression: true,       // Compress cached data
-  ttl: 3600000,           // 1 hour cache lifetime
-  maxSize: 10000          // Maximum cached items
-});
+// Cache with coordinate and registry
+const cache = await createCache(api, createCoordinate('product'), registry);
 
 // Bulk operations for efficiency
-const [cacheMap, allProducts] = await cache.all();
+const [cacheMap, allProducts] = await cache.operations.all();
 const productMap = new Map(allProducts.map(p => [p.id, p]));
+
+// Access cache properties for optimization
+console.log(`Cache coordinate: ${cache.coordinate.kta.join(', ')}`);
+console.log(`Cached items: ${cache.cacheMap.size()}`);
 ```
 
 ### Storage Integration
@@ -287,21 +284,19 @@ Fjell-cache works with any storage backend through the ClientApi interface:
 
 ### Error Handling and Resilience
 ```typescript
-// Cache with error handling
-const resilientCache = await createCache(api, 'user', {
-  fallback: async (key) => {
-    // Fallback to secondary storage
-    return await secondaryStorage.get(key);
-  },
-  retryPolicy: {
-    attempts: 3,
-    backoff: 'exponential'
-  },
-  circuit: {
-    failureThreshold: 5,
-    resetTimeout: 30000
-  }
-});
+// Cache with proper error handling through the API layer
+const resilientCache = await createCache(api, createCoordinate('user'), registry);
+
+// Error handling in operations
+try {
+  const [, user] = await resilientCache.operations.get(userKey);
+  return user;
+} catch (error) {
+  // Handle cache errors gracefully
+  console.error('Cache operation failed:', error);
+  // Fallback to direct API call
+  return await api.get(userKey);
+}
 ```
 
 This provides the foundation for building scalable, maintainable applications with intelligent caching using fjell-cache.

package/examples/aggregator-example.ts

@@ -181,10 +181,10 @@ export const runAggregatorExample = async (): Promise<void> => {
   const productApi = createMockApi(mockProducts) as ClientApi<Product, 'product'>;
   const ticketApi = createMockApi(mockTickets) as ClientApi<SupportTicket, 'ticket'>;
 
-  const customerCache = await createCache(customerApi, 'customer');
-  const orderCache = await createCache(orderApi, 'order');
-  const productCache = await createCache(productApi, 'product');
-  const ticketCache = await createCache(ticketApi, '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');
 
@@ -209,19 +209,13 @@ export const runAggregatorExample = async (): Promise<void> => {
     events: {}
   });
 
-  console.log('✅ Created aggregated caches with relationship mappings');
-
-  // Create instances for easier management
-  const orderInstance = createInstance(registry, createCoordinate('order'), orderAggregator);
-  const ticketInstance = createInstance(registry, createCoordinate('ticket'), ticketAggregator);
-
-  console.log('✅ Created aggregated cache instances\n');
+  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 orderInstance.cache.all();
+  const [, orders] = await orderAggregator.all();
   console.log(`📋 Fetched ${orders.length} orders`);
 
   for (const order of orders) {
@@ -243,7 +237,7 @@ export const runAggregatorExample = async (): Promise<void> => {
   console.log('\n\nStep 5: Support ticket aggregation with multiple references');
   console.log('----------------------------------------------------------');
 
-  const [, tickets] = await ticketInstance.cache.all();
+  const [, tickets] = await ticketAggregator.all();
   console.log(`🎫 Fetched ${tickets.length} support tickets`);
 
   for (const ticket of tickets) {
@@ -275,7 +269,7 @@ export const runAggregatorExample = async (): Promise<void> => {
   console.log('\n\nStep 6: Individual item retrieval with aggregation');
   console.log('-------------------------------------------------');
 
-  const [, specificOrder] = await orderInstance.cache.get(order1.key);
+  const [, specificOrder] = await orderAggregator.get(order1.key);
   if (specificOrder) {
     console.log(`🔍 Retrieved specific order: ${specificOrder.id}`);