@fjell/cache 4.6.11 → 4.6.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +96 -0
- package/docs/docs.config.ts +75 -0
- package/docs/index.html +18 -0
- package/docs/package.json +34 -0
- package/docs/public/README.md +96 -0
- package/docs/public/examples-README.md +302 -0
- package/docs/public/test.txt +0 -0
- package/docs/src/index.css +3 -0
- package/docs/src/main.tsx +12 -0
- package/docs/src/test/setup.ts +1 -0
- package/docs/tsconfig.node.json +15 -0
- package/examples/aggregator-example.ts +1 -0
- package/package.json +16 -11
- package/vitest.config.ts +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# Fjell Cache
|
|
2
|
+
|
|
3
|
+
Cache for Fjell - A powerful caching framework for TypeScript applications
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
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.
|
|
8
|
+
|
|
9
|
+
## Features
|
|
10
|
+
|
|
11
|
+
- **Smart Caching**: Intelligent cache operations with automatic cache hits/misses
|
|
12
|
+
- **Business Relationships**: Automatic population of related entities through aggregation
|
|
13
|
+
- **Performance Optimized**: High-performance cache operations with bulk processing
|
|
14
|
+
- **Location-Based**: Support for contained items with location hierarchies
|
|
15
|
+
- **Framework Integration**: Seamless integration with Fjell Core, Registry, and Client API
|
|
16
|
+
- **TypeScript First**: Full TypeScript support with comprehensive type safety
|
|
17
|
+
|
|
18
|
+
## Installation
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
npm install @fjell/cache
|
|
22
|
+
# or
|
|
23
|
+
pnpm add @fjell/cache
|
|
24
|
+
# or
|
|
25
|
+
yarn add @fjell/cache
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Quick Start
|
|
29
|
+
|
|
30
|
+
```typescript
|
|
31
|
+
import { createCache } from '@fjell/cache';
|
|
32
|
+
import { createCoordinate, createRegistry } from '@fjell/registry';
|
|
33
|
+
import { ClientApi } from '@fjell/client-api';
|
|
34
|
+
|
|
35
|
+
// Create a registry for cache management
|
|
36
|
+
const registry = createRegistry();
|
|
37
|
+
|
|
38
|
+
// Create a cache instance with API integration
|
|
39
|
+
const userApi = createUserApi(); // Your API implementation
|
|
40
|
+
const userCache = await createCache(userApi, createCoordinate('user'), registry);
|
|
41
|
+
|
|
42
|
+
// Perform cache operations
|
|
43
|
+
const [cacheMap, allUsers] = await userCache.operations.all();
|
|
44
|
+
const [, cachedUser] = await userCache.operations.get(userKey);
|
|
45
|
+
const [, retrievedUser] = await userCache.operations.retrieve(userKey); // Cache hit!
|
|
46
|
+
|
|
47
|
+
await userCache.operations.set(userKey, updatedUser);
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Core Components
|
|
51
|
+
|
|
52
|
+
### Basic Caching
|
|
53
|
+
- **Cache Operations**: Get, set, retrieve, and manage cached data
|
|
54
|
+
- **Cache-as-Instance**: Caches extend Instance from fjell-registry
|
|
55
|
+
- **Performance Monitoring**: Track cache hits, misses, and efficiency
|
|
56
|
+
|
|
57
|
+
### Advanced Aggregation
|
|
58
|
+
- **Entity Relationships**: Automatic population of related entities
|
|
59
|
+
- **Required vs Optional**: Flexible relationship management
|
|
60
|
+
- **Business Logic**: Complex business scenarios with interconnected data
|
|
61
|
+
|
|
62
|
+
### Direct Cache Management
|
|
63
|
+
- **CacheMap**: Low-level cache operations and management
|
|
64
|
+
- **Location Filtering**: Filter contained items by location hierarchy
|
|
65
|
+
- **Bulk Operations**: Efficient processing of multiple cache operations
|
|
66
|
+
|
|
67
|
+
## Examples
|
|
68
|
+
|
|
69
|
+
Comprehensive examples are available in the [examples directory](./examples/):
|
|
70
|
+
|
|
71
|
+
- **[Basic Cache Example](./examples/basic-cache-example.ts)** - Start here! Fundamental caching operations
|
|
72
|
+
- **[Aggregator Example](./examples/aggregator-example.ts)** - Advanced business relationships
|
|
73
|
+
- **[Cache Map Example](./examples/cache-map-example.ts)** - Low-level cache operations
|
|
74
|
+
|
|
75
|
+
## Documentation
|
|
76
|
+
|
|
77
|
+
For detailed documentation, examples, and API reference, visit our [documentation site](https://getfjell.github.io/fjell-cache/).
|
|
78
|
+
|
|
79
|
+
## Dependencies
|
|
80
|
+
|
|
81
|
+
Fjell Cache builds on the Fjell ecosystem:
|
|
82
|
+
- `@fjell/core` - Core framework functionality
|
|
83
|
+
- `@fjell/registry` - Registry and coordinate management
|
|
84
|
+
- `@fjell/client-api` - API integration layer
|
|
85
|
+
- `@fjell/http-api` - HTTP API capabilities
|
|
86
|
+
- `@fjell/logging` - Structured logging
|
|
87
|
+
|
|
88
|
+
## License
|
|
89
|
+
|
|
90
|
+
Apache-2.0
|
|
91
|
+
|
|
92
|
+
## Contributing
|
|
93
|
+
|
|
94
|
+
We welcome contributions! Please see our contributing guidelines for more information.
|
|
95
|
+
|
|
96
|
+
Built with love by the Fjell team.
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
interface DocsConfig {
|
|
2
|
+
projectName: string;
|
|
3
|
+
basePath: string;
|
|
4
|
+
port: number;
|
|
5
|
+
branding: {
|
|
6
|
+
theme: string;
|
|
7
|
+
tagline: string;
|
|
8
|
+
logo?: string;
|
|
9
|
+
backgroundImage?: string;
|
|
10
|
+
primaryColor?: string;
|
|
11
|
+
accentColor?: string;
|
|
12
|
+
github?: string;
|
|
13
|
+
npm?: string;
|
|
14
|
+
};
|
|
15
|
+
sections: Array<{
|
|
16
|
+
id: string;
|
|
17
|
+
title: string;
|
|
18
|
+
subtitle: string;
|
|
19
|
+
file: string;
|
|
20
|
+
}>;
|
|
21
|
+
filesToCopy: Array<{
|
|
22
|
+
source: string;
|
|
23
|
+
destination: string;
|
|
24
|
+
}>;
|
|
25
|
+
plugins?: any[];
|
|
26
|
+
version: {
|
|
27
|
+
source: string;
|
|
28
|
+
};
|
|
29
|
+
customContent?: {
|
|
30
|
+
[key: string]: (content: string) => string;
|
|
31
|
+
};
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
const config: DocsConfig = {
|
|
35
|
+
projectName: 'Fjell Cache',
|
|
36
|
+
basePath: '/fjell-cache/',
|
|
37
|
+
port: 3005,
|
|
38
|
+
branding: {
|
|
39
|
+
theme: 'cache',
|
|
40
|
+
tagline: 'Cache for Fjell',
|
|
41
|
+
backgroundImage: '/pano.png',
|
|
42
|
+
github: 'https://github.com/getfjell/fjell-cache',
|
|
43
|
+
npm: 'https://www.npmjs.com/package/@fjell/cache'
|
|
44
|
+
},
|
|
45
|
+
sections: [
|
|
46
|
+
{
|
|
47
|
+
id: 'overview',
|
|
48
|
+
title: 'Getting Started',
|
|
49
|
+
subtitle: 'Installation, setup & core concepts',
|
|
50
|
+
file: '/README.md'
|
|
51
|
+
},
|
|
52
|
+
{
|
|
53
|
+
id: 'examples',
|
|
54
|
+
title: 'Examples',
|
|
55
|
+
subtitle: 'Code examples & usage patterns',
|
|
56
|
+
file: '/examples-README.md'
|
|
57
|
+
}
|
|
58
|
+
],
|
|
59
|
+
filesToCopy: [
|
|
60
|
+
{
|
|
61
|
+
source: '../README.md',
|
|
62
|
+
destination: 'public/README.md'
|
|
63
|
+
},
|
|
64
|
+
{
|
|
65
|
+
source: '../examples/README.md',
|
|
66
|
+
destination: 'public/examples-README.md'
|
|
67
|
+
}
|
|
68
|
+
],
|
|
69
|
+
plugins: [],
|
|
70
|
+
version: {
|
|
71
|
+
source: 'package.json'
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
export default config
|
package/docs/index.html
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
|
|
4
|
+
<head>
|
|
5
|
+
<meta charset="UTF-8" />
|
|
6
|
+
<link rel="icon" type="image/svg+xml" href="/fjell-icon.svg" />
|
|
7
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
8
|
+
<title>Fjell Cache - Cache for Fjell</title>
|
|
9
|
+
<meta name="description"
|
|
10
|
+
content="Cache for Fjell - A powerful caching framework for TypeScript applications with intelligent caching and business relationships">
|
|
11
|
+
</head>
|
|
12
|
+
|
|
13
|
+
<body>
|
|
14
|
+
<div id="root"></div>
|
|
15
|
+
<script type="module" src="/src/main.tsx"></script>
|
|
16
|
+
</body>
|
|
17
|
+
|
|
18
|
+
</html>
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "fjell-cache-docs",
|
|
3
|
+
"private": true,
|
|
4
|
+
"version": "0.0.0",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"scripts": {
|
|
7
|
+
"copy-docs": "node node_modules/@fjell/docs-template/scripts/copy-docs.js",
|
|
8
|
+
"dev": "pnpm run copy-docs && vite",
|
|
9
|
+
"build": "pnpm run copy-docs && vite build",
|
|
10
|
+
"preview": "vite preview",
|
|
11
|
+
"test": "vitest run --coverage",
|
|
12
|
+
"test:watch": "vitest --watch"
|
|
13
|
+
},
|
|
14
|
+
"dependencies": {
|
|
15
|
+
"@fjell/docs-template": "1.0.5",
|
|
16
|
+
"react": "^19.1.0",
|
|
17
|
+
"react-dom": "^19.1.0"
|
|
18
|
+
},
|
|
19
|
+
"devDependencies": {
|
|
20
|
+
"@testing-library/jest-dom": "^6.6.3",
|
|
21
|
+
"@testing-library/react": "^16.3.0",
|
|
22
|
+
"@testing-library/user-event": "^14.6.1",
|
|
23
|
+
"@types/react": "^19.1.8",
|
|
24
|
+
"@types/react-dom": "^19.1.6",
|
|
25
|
+
"@types/react-syntax-highlighter": "^15.5.13",
|
|
26
|
+
"@vitejs/plugin-react": "^4.6.0",
|
|
27
|
+
"@vitest/coverage-v8": "^3.2.4",
|
|
28
|
+
"@vitest/ui": "^3.2.4",
|
|
29
|
+
"jsdom": "^26.1.0",
|
|
30
|
+
"typescript": "^5.8.3",
|
|
31
|
+
"vite": "^7.0.0",
|
|
32
|
+
"vitest": "^3.2.4"
|
|
33
|
+
}
|
|
34
|
+
}
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# Fjell Cache
|
|
2
|
+
|
|
3
|
+
Cache for Fjell - A powerful caching framework for TypeScript applications
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
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.
|
|
8
|
+
|
|
9
|
+
## Features
|
|
10
|
+
|
|
11
|
+
- **Smart Caching**: Intelligent cache operations with automatic cache hits/misses
|
|
12
|
+
- **Business Relationships**: Automatic population of related entities through aggregation
|
|
13
|
+
- **Performance Optimized**: High-performance cache operations with bulk processing
|
|
14
|
+
- **Location-Based**: Support for contained items with location hierarchies
|
|
15
|
+
- **Framework Integration**: Seamless integration with Fjell Core, Registry, and Client API
|
|
16
|
+
- **TypeScript First**: Full TypeScript support with comprehensive type safety
|
|
17
|
+
|
|
18
|
+
## Installation
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
npm install @fjell/cache
|
|
22
|
+
# or
|
|
23
|
+
pnpm add @fjell/cache
|
|
24
|
+
# or
|
|
25
|
+
yarn add @fjell/cache
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Quick Start
|
|
29
|
+
|
|
30
|
+
```typescript
|
|
31
|
+
import { createCache } from '@fjell/cache';
|
|
32
|
+
import { createCoordinate, createRegistry } from '@fjell/registry';
|
|
33
|
+
import { ClientApi } from '@fjell/client-api';
|
|
34
|
+
|
|
35
|
+
// Create a registry for cache management
|
|
36
|
+
const registry = createRegistry();
|
|
37
|
+
|
|
38
|
+
// Create a cache instance with API integration
|
|
39
|
+
const userApi = createUserApi(); // Your API implementation
|
|
40
|
+
const userCache = await createCache(userApi, createCoordinate('user'), registry);
|
|
41
|
+
|
|
42
|
+
// Perform cache operations
|
|
43
|
+
const [cacheMap, allUsers] = await userCache.operations.all();
|
|
44
|
+
const [, cachedUser] = await userCache.operations.get(userKey);
|
|
45
|
+
const [, retrievedUser] = await userCache.operations.retrieve(userKey); // Cache hit!
|
|
46
|
+
|
|
47
|
+
await userCache.operations.set(userKey, updatedUser);
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Core Components
|
|
51
|
+
|
|
52
|
+
### Basic Caching
|
|
53
|
+
- **Cache Operations**: Get, set, retrieve, and manage cached data
|
|
54
|
+
- **Cache-as-Instance**: Caches extend Instance from fjell-registry
|
|
55
|
+
- **Performance Monitoring**: Track cache hits, misses, and efficiency
|
|
56
|
+
|
|
57
|
+
### Advanced Aggregation
|
|
58
|
+
- **Entity Relationships**: Automatic population of related entities
|
|
59
|
+
- **Required vs Optional**: Flexible relationship management
|
|
60
|
+
- **Business Logic**: Complex business scenarios with interconnected data
|
|
61
|
+
|
|
62
|
+
### Direct Cache Management
|
|
63
|
+
- **CacheMap**: Low-level cache operations and management
|
|
64
|
+
- **Location Filtering**: Filter contained items by location hierarchy
|
|
65
|
+
- **Bulk Operations**: Efficient processing of multiple cache operations
|
|
66
|
+
|
|
67
|
+
## Examples
|
|
68
|
+
|
|
69
|
+
Comprehensive examples are available in the [examples directory](./examples/):
|
|
70
|
+
|
|
71
|
+
- **[Basic Cache Example](./examples/basic-cache-example.ts)** - Start here! Fundamental caching operations
|
|
72
|
+
- **[Aggregator Example](./examples/aggregator-example.ts)** - Advanced business relationships
|
|
73
|
+
- **[Cache Map Example](./examples/cache-map-example.ts)** - Low-level cache operations
|
|
74
|
+
|
|
75
|
+
## Documentation
|
|
76
|
+
|
|
77
|
+
For detailed documentation, examples, and API reference, visit our [documentation site](https://getfjell.github.io/fjell-cache/).
|
|
78
|
+
|
|
79
|
+
## Dependencies
|
|
80
|
+
|
|
81
|
+
Fjell Cache builds on the Fjell ecosystem:
|
|
82
|
+
- `@fjell/core` - Core framework functionality
|
|
83
|
+
- `@fjell/registry` - Registry and coordinate management
|
|
84
|
+
- `@fjell/client-api` - API integration layer
|
|
85
|
+
- `@fjell/http-api` - HTTP API capabilities
|
|
86
|
+
- `@fjell/logging` - Structured logging
|
|
87
|
+
|
|
88
|
+
## License
|
|
89
|
+
|
|
90
|
+
Apache-2.0
|
|
91
|
+
|
|
92
|
+
## Contributing
|
|
93
|
+
|
|
94
|
+
We welcome contributions! Please see our contributing guidelines for more information.
|
|
95
|
+
|
|
96
|
+
Built with love by the Fjell team.
|
|
@@ -0,0 +1,302 @@
|
|
|
1
|
+
# Fjell-Cache Examples
|
|
2
|
+
|
|
3
|
+
This directory contains examples demonstrating how to use fjell-cache for caching data models and managing complex business relationships with different patterns and complexity levels.
|
|
4
|
+
|
|
5
|
+
## Examples
|
|
6
|
+
|
|
7
|
+
### 1. `basic-cache-example.ts` ⭐ **Start Here!**
|
|
8
|
+
**Perfect for beginners!** Demonstrates the fundamental way to use fjell-cache for data caching:
|
|
9
|
+
- **Basic cache operations** - Create caches with coordinates and registries, use operations API
|
|
10
|
+
- **Simple data models** - User and Task entities with mock storage
|
|
11
|
+
- **Cache-as-Instance architecture** - Caches extend Instance from fjell-registry
|
|
12
|
+
- **Cache hits vs misses** - Understand cache behavior and performance benefits
|
|
13
|
+
- **Cache management** - Updates, deletions, and data consistency through operations
|
|
14
|
+
|
|
15
|
+
Great for understanding the fundamentals of fjell-cache data management.
|
|
16
|
+
|
|
17
|
+
### 2. `aggregator-example.ts` 🏗️ **Advanced Business Relationships**
|
|
18
|
+
**Complete business relationship management!** Demonstrates advanced caching patterns with entity relationships:
|
|
19
|
+
- **Multiple interconnected models**: Customer, Order, Product, SupportTicket
|
|
20
|
+
- **Automatic reference population**: Orders automatically include customer data
|
|
21
|
+
- **Required vs optional aggregates**: Flexible relationship management
|
|
22
|
+
- **Complex business scenarios**: E-commerce platform with customer management
|
|
23
|
+
- **Performance optimization**: Cache efficiency through aggregated data
|
|
24
|
+
|
|
25
|
+
Shows how fjell-cache handles enterprise data relationship patterns.
|
|
26
|
+
|
|
27
|
+
### 3. `cache-map-example.ts` 🔧 **Low-Level Cache Operations**
|
|
28
|
+
**Direct cache management!** Demonstrates lower-level CacheMap functionality:
|
|
29
|
+
- **Direct CacheMap usage**: Create and manage cache maps without higher-level abstractions
|
|
30
|
+
- **Primary and composite keys**: Handle both simple and complex key structures
|
|
31
|
+
- **Location-based operations**: Filter contained items by location hierarchy
|
|
32
|
+
- **Performance characteristics**: Bulk operations and efficiency testing
|
|
33
|
+
- **Cache lifecycle**: Cloning, cleanup, and memory management
|
|
34
|
+
|
|
35
|
+
Perfect for understanding the underlying cache mechanisms and advanced use cases.
|
|
36
|
+
|
|
37
|
+
## Key Concepts Demonstrated
|
|
38
|
+
|
|
39
|
+
### Basic Caching Operations (basic-cache-example.ts)
|
|
40
|
+
```typescript
|
|
41
|
+
// Import fjell-cache functionality
|
|
42
|
+
import { createCache } from '@fjell/cache';
|
|
43
|
+
import { createCoordinate, createRegistry } from '@fjell/registry';
|
|
44
|
+
import { ClientApi } from '@fjell/client-api';
|
|
45
|
+
|
|
46
|
+
// Create a registry for cache management
|
|
47
|
+
const registry = createRegistry();
|
|
48
|
+
|
|
49
|
+
// Create a cache instance with API integration
|
|
50
|
+
const userApi = createUserApi(); // Your API implementation
|
|
51
|
+
const userCache = await createCache(userApi, createCoordinate('user'), registry);
|
|
52
|
+
|
|
53
|
+
// Cache is now an instance - no need for separate createInstance call
|
|
54
|
+
// Perform cache operations through the operations API
|
|
55
|
+
const [cacheMap, allUsers] = await userCache.operations.all();
|
|
56
|
+
const [, cachedUser] = await userCache.operations.get(userKey);
|
|
57
|
+
const [, retrievedUser] = await userCache.operations.retrieve(userKey); // Cache hit!
|
|
58
|
+
|
|
59
|
+
await userCache.operations.set(userKey, updatedUser);
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### Advanced Aggregation (aggregator-example.ts)
|
|
63
|
+
```typescript
|
|
64
|
+
// Create aggregated cache with relationships
|
|
65
|
+
const orderAggregator = await createAggregator(orderCache, {
|
|
66
|
+
aggregates: {
|
|
67
|
+
customer: { cache: customerCache, optional: false }, // Required reference
|
|
68
|
+
product: { cache: productCache, optional: true }, // Optional reference
|
|
69
|
+
},
|
|
70
|
+
events: {}
|
|
71
|
+
});
|
|
72
|
+
|
|
73
|
+
// Automatically populate related entities
|
|
74
|
+
const populatedOrder = await orderAggregator.populate(order);
|
|
75
|
+
if (populatedOrder.aggs?.customer?.item) {
|
|
76
|
+
const customer = populatedOrder.aggs.customer.item;
|
|
77
|
+
console.log(`Order for: ${customer.name} (${customer.email})`);
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
// Aggregator is now itself an instance - access operations directly
|
|
81
|
+
const [, orders] = await orderAggregator.all();
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### Direct Cache Management (cache-map-example.ts)
|
|
85
|
+
```typescript
|
|
86
|
+
// Create CacheMap instances directly
|
|
87
|
+
const documentCacheMap = new CacheMap<Document, 'document'>(['document']);
|
|
88
|
+
const commentCacheMap = new CacheMap<Comment, 'comment', 'document'>(['comment', 'document']);
|
|
89
|
+
|
|
90
|
+
// Basic operations
|
|
91
|
+
documentCacheMap.set(documentKey, document);
|
|
92
|
+
const retrievedDoc = documentCacheMap.get(documentKey);
|
|
93
|
+
const hasDoc = documentCacheMap.includesKey(documentKey);
|
|
94
|
+
|
|
95
|
+
// Bulk operations
|
|
96
|
+
const allDocuments = documentCacheMap.allIn([]);
|
|
97
|
+
const allKeys = documentCacheMap.keys();
|
|
98
|
+
const allValues = documentCacheMap.values();
|
|
99
|
+
|
|
100
|
+
// Location-based filtering for contained items
|
|
101
|
+
const commentsInDoc = commentCacheMap.allIn([{ kt: 'document', lk: documentId }]);
|
|
102
|
+
|
|
103
|
+
// Performance operations
|
|
104
|
+
const clonedCache = documentCacheMap.clone();
|
|
105
|
+
documentCacheMap.delete(documentKey);
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### Data Model Patterns
|
|
109
|
+
|
|
110
|
+
#### Primary Items
|
|
111
|
+
- Standalone entities (User, Customer, Document)
|
|
112
|
+
- No location hierarchy constraints
|
|
113
|
+
- Simple key structure: `Item<'keyType'>`
|
|
114
|
+
|
|
115
|
+
#### Contained Items
|
|
116
|
+
- Nested within other entities or locations
|
|
117
|
+
- Multi-level location keys for organization
|
|
118
|
+
- Complex key structure: `Item<'keyType', 'location1', 'location2', ...>`
|
|
119
|
+
|
|
120
|
+
#### Aggregated Items
|
|
121
|
+
- Items with automatic reference population
|
|
122
|
+
- Business relationships through cache aggregation
|
|
123
|
+
- Performance optimized through cached references
|
|
124
|
+
|
|
125
|
+
## Running Examples
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
# Start with the basic example (recommended)
|
|
129
|
+
npx tsx examples/basic-cache-example.ts
|
|
130
|
+
|
|
131
|
+
# Run the aggregator example
|
|
132
|
+
npx tsx examples/aggregator-example.ts
|
|
133
|
+
|
|
134
|
+
# Run the cache map example
|
|
135
|
+
npx tsx examples/cache-map-example.ts
|
|
136
|
+
|
|
137
|
+
# Or with Node.js
|
|
138
|
+
node -r esbuild-register examples/basic-cache-example.ts
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
## Integration with Real Applications
|
|
142
|
+
|
|
143
|
+
All examples use the actual fjell-cache functionality! In production applications:
|
|
144
|
+
|
|
145
|
+
```typescript
|
|
146
|
+
import { createCache, createRegistry, createInstance, createAggregator } from '@fjell/cache';
|
|
147
|
+
import { ClientApi } from '@fjell/client-api';
|
|
148
|
+
|
|
149
|
+
// Basic cache setup
|
|
150
|
+
const registry = createRegistry();
|
|
151
|
+
|
|
152
|
+
const userCache = await createCache(userApi, 'user');
|
|
153
|
+
const userInstance = createInstance(registry, createCoordinate('user'), userCache);
|
|
154
|
+
|
|
155
|
+
// With aggregation for business relationships
|
|
156
|
+
const orderAggregator = await createAggregator(orderCache, {
|
|
157
|
+
aggregates: {
|
|
158
|
+
customer: { cache: customerCache, optional: false },
|
|
159
|
+
items: { cache: productCache, optional: true }
|
|
160
|
+
},
|
|
161
|
+
events: {
|
|
162
|
+
orderUpdated: async (key, item) => {
|
|
163
|
+
// Custom event handling
|
|
164
|
+
await notifyCustomer(item);
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
});
|
|
168
|
+
|
|
169
|
+
// Advanced cache configuration
|
|
170
|
+
const options = {
|
|
171
|
+
cacheSize: 10000,
|
|
172
|
+
ttl: 3600000, // 1 hour
|
|
173
|
+
refreshThreshold: 0.8,
|
|
174
|
+
compression: true
|
|
175
|
+
};
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
## Cache Operation Types
|
|
179
|
+
|
|
180
|
+
### Basic Operations
|
|
181
|
+
- **all()**: Get all items and update cache
|
|
182
|
+
- **get()**: Get item by key, fetch from API if not cached
|
|
183
|
+
- **retrieve()**: Get item by key, return null if not cached
|
|
184
|
+
- **set()**: Store item in cache
|
|
185
|
+
- **one()**: Get single item
|
|
186
|
+
- **find()**: Search items with finder methods
|
|
187
|
+
|
|
188
|
+
### Aggregation Operations
|
|
189
|
+
- **populate()**: Automatically populate item with related entities
|
|
190
|
+
- **populateAggregate()**: Populate specific aggregate relationship
|
|
191
|
+
- **populateEvent()**: Handle population events
|
|
192
|
+
|
|
193
|
+
### Cache Management
|
|
194
|
+
- **allIn()**: Get items by location (for contained items)
|
|
195
|
+
- **queryIn()**: Query items by location with filtering
|
|
196
|
+
- **clone()**: Create independent cache copy
|
|
197
|
+
- **delete()**: Remove item from cache
|
|
198
|
+
- **clear()**: Clear all cache contents
|
|
199
|
+
|
|
200
|
+
### Business Operations
|
|
201
|
+
```typescript
|
|
202
|
+
// Cache with business logic integration
|
|
203
|
+
const cache = await createCache(api, 'order', {
|
|
204
|
+
hooks: {
|
|
205
|
+
beforeGet: async (key) => { /* validation */ },
|
|
206
|
+
afterSet: async (key, item) => { /* notifications */ }
|
|
207
|
+
},
|
|
208
|
+
validators: {
|
|
209
|
+
status: (status) => ['pending', 'shipped', 'delivered'].includes(status)
|
|
210
|
+
},
|
|
211
|
+
aggregates: {
|
|
212
|
+
customer: customerCache,
|
|
213
|
+
items: productCache
|
|
214
|
+
}
|
|
215
|
+
});
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
## When to Use What
|
|
219
|
+
|
|
220
|
+
**Use `basic-cache-example.ts` approach when:**
|
|
221
|
+
- Learning fjell-cache fundamentals
|
|
222
|
+
- Building simple applications with caching needs
|
|
223
|
+
- Need basic get/set cache operations
|
|
224
|
+
- Working with independent data models
|
|
225
|
+
|
|
226
|
+
**Use `aggregator-example.ts` approach when:**
|
|
227
|
+
- Managing complex business relationships
|
|
228
|
+
- Need automatic population of related entities
|
|
229
|
+
- Building enterprise applications with interconnected data
|
|
230
|
+
- Require performance optimization through aggregated caching
|
|
231
|
+
- Working with customer/order/product type relationships
|
|
232
|
+
|
|
233
|
+
**Use `cache-map-example.ts` approach when:**
|
|
234
|
+
- Need direct control over cache operations
|
|
235
|
+
- Building custom caching solutions
|
|
236
|
+
- Working with contained items and location hierarchies
|
|
237
|
+
- Require maximum performance and minimal overhead
|
|
238
|
+
- Implementing cache-based data structures
|
|
239
|
+
|
|
240
|
+
## Advanced Features
|
|
241
|
+
|
|
242
|
+
### Cache Aggregation
|
|
243
|
+
```typescript
|
|
244
|
+
// Complex aggregation with optional and required references
|
|
245
|
+
const ticketAggregator = await createAggregator(ticketCache, {
|
|
246
|
+
aggregates: {
|
|
247
|
+
customer: { cache: customerCache, optional: false }, // Always populated
|
|
248
|
+
order: { cache: orderCache, optional: true }, // Only if orderId exists
|
|
249
|
+
assignee: { cache: userCache, optional: true } // Only if assigned
|
|
250
|
+
},
|
|
251
|
+
events: {
|
|
252
|
+
ticketAssigned: async (key, ticket) => {
|
|
253
|
+
await notifyAssignee(ticket);
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
});
|
|
257
|
+
|
|
258
|
+
// Automatic population includes all available references
|
|
259
|
+
const populatedTicket = await ticketAggregator.populate(ticket);
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
### Performance Optimization
|
|
263
|
+
```typescript
|
|
264
|
+
// Cache with coordinate and registry
|
|
265
|
+
const cache = await createCache(api, createCoordinate('product'), registry);
|
|
266
|
+
|
|
267
|
+
// Bulk operations for efficiency
|
|
268
|
+
const [cacheMap, allProducts] = await cache.operations.all();
|
|
269
|
+
const productMap = new Map(allProducts.map(p => [p.id, p]));
|
|
270
|
+
|
|
271
|
+
// Access cache properties for optimization
|
|
272
|
+
console.log(`Cache coordinate: ${cache.coordinate.kta.join(', ')}`);
|
|
273
|
+
console.log(`Cached items: ${cache.cacheMap.size()}`);
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
### Storage Integration
|
|
277
|
+
Fjell-cache works with any storage backend through the ClientApi interface:
|
|
278
|
+
- SQL databases (PostgreSQL, MySQL, SQLite)
|
|
279
|
+
- NoSQL databases (MongoDB, DynamoDB, Redis)
|
|
280
|
+
- REST APIs and GraphQL endpoints
|
|
281
|
+
- In-memory stores and mock data
|
|
282
|
+
- File systems and cloud storage
|
|
283
|
+
- Custom data sources
|
|
284
|
+
|
|
285
|
+
### Error Handling and Resilience
|
|
286
|
+
```typescript
|
|
287
|
+
// Cache with proper error handling through the API layer
|
|
288
|
+
const resilientCache = await createCache(api, createCoordinate('user'), registry);
|
|
289
|
+
|
|
290
|
+
// Error handling in operations
|
|
291
|
+
try {
|
|
292
|
+
const [, user] = await resilientCache.operations.get(userKey);
|
|
293
|
+
return user;
|
|
294
|
+
} catch (error) {
|
|
295
|
+
// Handle cache errors gracefully
|
|
296
|
+
console.error('Cache operation failed:', error);
|
|
297
|
+
// Fallback to direct API call
|
|
298
|
+
return await api.get(userKey);
|
|
299
|
+
}
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
This provides the foundation for building scalable, maintainable applications with intelligent caching using fjell-cache.
|
|
File without changes
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import React from 'react'
|
|
2
|
+
import ReactDOM from 'react-dom/client'
|
|
3
|
+
import { DocsApp } from '@fjell/docs-template'
|
|
4
|
+
import '@fjell/docs-template/dist/index.css'
|
|
5
|
+
import config from '../docs.config'
|
|
6
|
+
import './index.css'
|
|
7
|
+
|
|
8
|
+
ReactDOM.createRoot(document.getElementById('root')!).render(
|
|
9
|
+
<React.StrictMode>
|
|
10
|
+
<DocsApp config={config} />
|
|
11
|
+
</React.StrictMode>
|
|
12
|
+
)
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import '@testing-library/jest-dom'
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"compilerOptions": {
|
|
3
|
+
"composite": true,
|
|
4
|
+
"skipLibCheck": true,
|
|
5
|
+
"module": "ESNext",
|
|
6
|
+
"moduleResolution": "bundler",
|
|
7
|
+
"allowSyntheticDefaultImports": true,
|
|
8
|
+
"strict": true,
|
|
9
|
+
"noEmit": true
|
|
10
|
+
},
|
|
11
|
+
"include": [
|
|
12
|
+
"vite.config.ts",
|
|
13
|
+
"docs.config.ts"
|
|
14
|
+
]
|
|
15
|
+
}
|
|
@@ -128,6 +128,7 @@ const createSupportTicket = (
|
|
|
128
128
|
priority: 'low' | 'medium' | 'high' | 'urgent',
|
|
129
129
|
status: 'open' | 'in-progress' | 'resolved' | 'closed',
|
|
130
130
|
description: string,
|
|
131
|
+
// eslint-disable-next-line max-params
|
|
131
132
|
orderId?: string): SupportTicket => {
|
|
132
133
|
const ticket: SupportTicket = {
|
|
133
134
|
id, customerId, subject, priority, status, description, orderId,
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fjell/cache",
|
|
3
3
|
"description": "Cache for Fjell",
|
|
4
|
-
"version": "4.6.
|
|
4
|
+
"version": "4.6.13",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"cache",
|
|
7
7
|
"fjell"
|
|
@@ -19,21 +19,22 @@
|
|
|
19
19
|
}
|
|
20
20
|
},
|
|
21
21
|
"dependencies": {
|
|
22
|
-
"@fjell/client-api": "^4.4.
|
|
23
|
-
"@fjell/core": "^4.4.
|
|
24
|
-
"@fjell/http-api": "^4.4.
|
|
25
|
-
"@fjell/logging": "^4.4.
|
|
26
|
-
"@fjell/registry": "^4.4.
|
|
22
|
+
"@fjell/client-api": "^4.4.13",
|
|
23
|
+
"@fjell/core": "^4.4.13",
|
|
24
|
+
"@fjell/http-api": "^4.4.16",
|
|
25
|
+
"@fjell/logging": "^4.4.17",
|
|
26
|
+
"@fjell/registry": "^4.4.16"
|
|
27
27
|
},
|
|
28
28
|
"devDependencies": {
|
|
29
29
|
"@eslint/eslintrc": "^3.3.1",
|
|
30
30
|
"@eslint/js": "^9.31.0",
|
|
31
|
-
"@
|
|
31
|
+
"@fjell/eslint-config": "^1.0.5",
|
|
32
|
+
"@swc/core": "^1.13.2",
|
|
32
33
|
"@tsconfig/recommended": "^1.0.10",
|
|
33
34
|
"@types/multer": "^2.0.0",
|
|
34
|
-
"@types/node": "^24.0
|
|
35
|
-
"@typescript-eslint/eslint-plugin": "^8.
|
|
36
|
-
"@typescript-eslint/parser": "^8.
|
|
35
|
+
"@types/node": "^24.1.0",
|
|
36
|
+
"@typescript-eslint/eslint-plugin": "^8.38.0",
|
|
37
|
+
"@typescript-eslint/parser": "^8.38.0",
|
|
37
38
|
"@vitest/coverage-v8": "^3.2.4",
|
|
38
39
|
"@vitest/ui": "^3.2.4",
|
|
39
40
|
"concurrently": "^9.2.0",
|
|
@@ -58,6 +59,10 @@
|
|
|
58
59
|
"typecheck": "tsc --noEmit",
|
|
59
60
|
"lint": "eslint . --ext .ts --fix",
|
|
60
61
|
"clean": "rimraf dist",
|
|
61
|
-
"test": "pnpm run lint && vitest run --coverage"
|
|
62
|
+
"test": "pnpm run lint && vitest run --coverage",
|
|
63
|
+
"docs:dev": "cd docs && pnpm run dev",
|
|
64
|
+
"docs:build": "cd docs && pnpm run build",
|
|
65
|
+
"docs:preview": "cd docs && pnpm run preview",
|
|
66
|
+
"docs:test": "cd docs && pnpm run test"
|
|
62
67
|
}
|
|
63
68
|
}
|