@fjell/cache 4.6.10 → 4.6.13

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/docs/docs.config.ts

@@ -0,0 +1,75 @@
+interface DocsConfig {
+  projectName: string;
+  basePath: string;
+  port: number;
+  branding: {
+    theme: string;
+    tagline: string;
+    logo?: string;
+    backgroundImage?: string;
+    primaryColor?: string;
+    accentColor?: string;
+    github?: string;
+    npm?: string;
+  };
+  sections: Array<{
+    id: string;
+    title: string;
+    subtitle: string;
+    file: string;
+  }>;
+  filesToCopy: Array<{
+    source: string;
+    destination: string;
+  }>;
+  plugins?: any[];
+  version: {
+    source: string;
+  };
+  customContent?: {
+    [key: string]: (content: string) => string;
+  };
+}
+
+const config: DocsConfig = {
+  projectName: 'Fjell Cache',
+  basePath: '/fjell-cache/',
+  port: 3005,
+  branding: {
+    theme: 'cache',
+    tagline: 'Cache for Fjell',
+    backgroundImage: '/pano.png',
+    github: 'https://github.com/getfjell/fjell-cache',
+    npm: 'https://www.npmjs.com/package/@fjell/cache'
+  },
+  sections: [
+    {
+      id: 'overview',
+      title: 'Getting Started',
+      subtitle: 'Installation, setup & core concepts',
+      file: '/README.md'
+    },
+    {
+      id: 'examples',
+      title: 'Examples',
+      subtitle: 'Code examples & usage patterns',
+      file: '/examples-README.md'
+    }
+  ],
+  filesToCopy: [
+    {
+      source: '../README.md',
+      destination: 'public/README.md'
+    },
+    {
+      source: '../examples/README.md',
+      destination: 'public/examples-README.md'
+    }
+  ],
+  plugins: [],
+  version: {
+    source: 'package.json'
+  }
+}
+
+export default config

package/docs/index.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+  <link rel="icon" type="image/svg+xml" href="/fjell-icon.svg" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Fjell Cache - Cache for Fjell</title>
+  <meta name="description"
+    content="Cache for Fjell - A powerful caching framework for TypeScript applications with intelligent caching and business relationships">
+</head>
+
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/main.tsx"></script>
+</body>
+
+</html>

package/docs/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "fjell-cache-docs",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "copy-docs": "node node_modules/@fjell/docs-template/scripts/copy-docs.js",
+    "dev": "pnpm run copy-docs && vite",
+    "build": "pnpm run copy-docs && vite build",
+    "preview": "vite preview",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest --watch"
+  },
+  "dependencies": {
+    "@fjell/docs-template": "1.0.5",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
+    "@types/react-syntax-highlighter": "^15.5.13",
+    "@vitejs/plugin-react": "^4.6.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "jsdom": "^26.1.0",
+    "typescript": "^5.8.3",
+    "vite": "^7.0.0",
+    "vitest": "^3.2.4"
+  }
+}

package/docs/public/README.md

@@ -0,0 +1,96 @@
+# Fjell Cache
+
+Cache for Fjell - A powerful caching framework for TypeScript applications
+
+## Overview
+
+Fjell Cache provides intelligent caching capabilities for complex data models and business relationships. Built on the Fjell framework architecture, it offers high-performance caching with automatic relationship management and business logic integration.
+
+## Features
+
+- **Smart Caching**: Intelligent cache operations with automatic cache hits/misses
+- **Business Relationships**: Automatic population of related entities through aggregation
+- **Performance Optimized**: High-performance cache operations with bulk processing
+- **Location-Based**: Support for contained items with location hierarchies
+- **Framework Integration**: Seamless integration with Fjell Core, Registry, and Client API
+- **TypeScript First**: Full TypeScript support with comprehensive type safety
+
+## Installation
+
+```bash
+npm install @fjell/cache
+# or
+pnpm add @fjell/cache
+# or
+yarn add @fjell/cache
+```
+
+## Quick Start
+
+```typescript
+import { createCache } from '@fjell/cache';
+import { createCoordinate, createRegistry } from '@fjell/registry';
+import { ClientApi } from '@fjell/client-api';
+
+// Create a registry for cache management
+const registry = createRegistry();
+
+// Create a cache instance with API integration
+const userApi = createUserApi(); // Your API implementation
+const userCache = await createCache(userApi, createCoordinate('user'), registry);
+
+// Perform cache operations
+const [cacheMap, allUsers] = await userCache.operations.all();
+const [, cachedUser] = await userCache.operations.get(userKey);
+const [, retrievedUser] = await userCache.operations.retrieve(userKey); // Cache hit!
+
+await userCache.operations.set(userKey, updatedUser);
+```
+
+## Core Components
+
+### Basic Caching
+- **Cache Operations**: Get, set, retrieve, and manage cached data
+- **Cache-as-Instance**: Caches extend Instance from fjell-registry
+- **Performance Monitoring**: Track cache hits, misses, and efficiency
+
+### Advanced Aggregation
+- **Entity Relationships**: Automatic population of related entities
+- **Required vs Optional**: Flexible relationship management
+- **Business Logic**: Complex business scenarios with interconnected data
+
+### Direct Cache Management
+- **CacheMap**: Low-level cache operations and management
+- **Location Filtering**: Filter contained items by location hierarchy
+- **Bulk Operations**: Efficient processing of multiple cache operations
+
+## Examples
+
+Comprehensive examples are available in the [examples directory](./examples/):
+
+- **[Basic Cache Example](./examples/basic-cache-example.ts)** - Start here! Fundamental caching operations
+- **[Aggregator Example](./examples/aggregator-example.ts)** - Advanced business relationships
+- **[Cache Map Example](./examples/cache-map-example.ts)** - Low-level cache operations
+
+## Documentation
+
+For detailed documentation, examples, and API reference, visit our [documentation site](https://getfjell.github.io/fjell-cache/).
+
+## Dependencies
+
+Fjell Cache builds on the Fjell ecosystem:
+- `@fjell/core` - Core framework functionality
+- `@fjell/registry` - Registry and coordinate management
+- `@fjell/client-api` - API integration layer
+- `@fjell/http-api` - HTTP API capabilities
+- `@fjell/logging` - Structured logging
+
+## License
+
+Apache-2.0
+
+## Contributing
+
+We welcome contributions! Please see our contributing guidelines for more information.
+
+Built with love by the Fjell team.