@fjell/cache 4.7.65 → 4.7.66

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.
Files changed (4) hide show
  1. package/guide/index.md +30 -0
  2. package/guide/integration.md +32 -0
  3. package/guide/usage.md +43 -0
  4. package/package.json +8 -8
package/guide/index.md ADDED
@@ -0,0 +1,30 @@
1
+ # @fjell/cache - Agentic Guide
2
+
3
+ ## Purpose
4
+
5
+ Caching primitives and cache-map implementations for Fjell data workflows.
6
+
7
+ This guide is optimized for AI-assisted code generation and integration workflows.
8
+
9
+ ## Documentation
10
+
11
+ - **[Usage Guide](./usage.md)** - API-oriented usage patterns and model-safe examples
12
+ - **[Integration Guide](./integration.md)** - Architecture placement, composition rules, and implementation guidance
13
+
14
+ ## Key Capabilities
15
+
16
+ - Provides memory, localStorage, sessionStorage, and IndexedDB cache maps
17
+ - Supports TTL management, cache stats, events, and operation wrappers
18
+ - Includes registry/aggregator helpers for composing cache behavior
19
+
20
+ ## Installation
21
+
22
+ ```bash
23
+ npm install @fjell/cache
24
+ ```
25
+
26
+ ## Public API Highlights
27
+
28
+ - `createCache`, `CacheMap`, and cache-map implementations
29
+ - `TTLManager`, cache event exports, and stats managers
30
+ - `createOperations`, `createAggregator`, and registry utilities
package/guide/integration.md ADDED
@@ -0,0 +1,32 @@
1
+ # Integration Guide
2
+
3
+ Guide for integrating `@fjell/cache` into larger Fjell-based systems.
4
+
5
+ ## Where It Fits
6
+
7
+ Caching primitives and cache-map implementations for Fjell data workflows.
8
+
9
+ ## Recommended Integration Pattern
10
+
11
+ - Use cache in front of provider/client-api calls for hot query paths
12
+ - Emit cache events to logging/metrics systems for observability
13
+ - Define TTL strategy per entity class rather than one global timeout
14
+
15
+ ## System Composition Checklist
16
+
17
+ - Define package boundaries: schema/types, transport, operations, adapters, and UI.
18
+ - Keep contracts stable by sharing @fjell/types interfaces where applicable.
19
+ - Centralize retries/timeouts/logging around infrastructure-facing operations.
20
+ - Validate inputs at API boundaries before invoking persistence or provider layers.
21
+ - Add contract and integration tests for every generated workflow.
22
+
23
+ ## Cross-Library Pairings
24
+
25
+ - Pair with @fjell/types for shared contracts.
26
+ - Pair with @fjell/validation for input and schema checks.
27
+ - Pair with @fjell/logging for observability in integration flows.
28
+ - Pair with storage/router/provider packages based on your runtime architecture.
29
+
30
+ ## Integration Example Shape
31
+
32
+ Use this package behind an application service layer that exposes stable domain methods. Generated code should call those service methods, not raw infrastructure primitives, unless your architecture intentionally keeps infrastructure at the edge.
package/guide/usage.md ADDED
@@ -0,0 +1,43 @@
1
+ # Usage Guide
2
+
3
+ Comprehensive usage guidance for `@fjell/cache`.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @fjell/cache
9
+ ```
10
+
11
+ ## API Highlights
12
+
13
+ - `createCache`, `CacheMap`, and cache-map implementations
14
+ - `TTLManager`, cache event exports, and stats managers
15
+ - `createOperations`, `createAggregator`, and registry utilities
16
+
17
+ ## Quick Example
18
+
19
+ ```ts
20
+ import { createCache, EnhancedMemoryCacheMap } from "@fjell/cache";
21
+
22
+ const cache = createCache({
23
+ cacheMap: new EnhancedMemoryCacheMap(),
24
+ ttl: { defaultTTL: 60_000 },
25
+ });
26
+
27
+ await cache.set("widget#1", { id: "widget#1", name: "Widget One" });
28
+ const widget = await cache.get("widget#1");
29
+ ```
30
+
31
+ ## Model Consumption Rules
32
+
33
+ 1. Import from the package root (`@fjell/cache`) instead of deep-internal paths unless explicitly documented.
34
+ 2. Keep usage aligned with exported public symbols listed in this guide.
35
+ 3. Prefer explicit typing at package boundaries so generated code remains robust during upgrades.
36
+ 4. Keep error handling deterministic and map infrastructure failures into domain-level errors.
37
+ 5. Co-locate integration wrappers in your app so model-generated code has one canonical entry point.
38
+
39
+ ## Best Practices
40
+
41
+ - Keep examples and abstractions consistent with existing Fjell package conventions.
42
+ - Favor composable wrappers over one-off inline integration logic.
43
+ - Add targeted tests around generated integration code paths.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@fjell/cache",
3
3
  "description": "Cache for Fjell",
4
- "version": "4.7.65",
4
+ "version": "4.7.66",
5
5
  "keywords": [
6
6
  "cache",
7
7
  "fjell"
@@ -37,12 +37,12 @@
37
37
  "docs:test": "cd docs && npm run test"
38
38
  },
39
39
  "dependencies": {
40
- "@fjell/client-api": "^4.4.72",
41
- "@fjell/core": "^4.4.78",
42
- "@fjell/http-api": "^4.4.68",
43
- "@fjell/logging": "^4.4.71",
44
- "@fjell/registry": "^4.4.85",
45
- "@fjell/types": "^4.4.8",
40
+ "@fjell/client-api": "^4.4.73",
41
+ "@fjell/core": "^4.4.79",
42
+ "@fjell/http-api": "^4.4.69",
43
+ "@fjell/logging": "^4.4.72",
44
+ "@fjell/registry": "^4.4.86",
45
+ "@fjell/types": "^4.4.9",
46
46
  "fast-safe-stringify": "^2.1.1",
47
47
  "flatted": "^3.3.3",
48
48
  "yocto-queue": "^1.2.1"
@@ -66,7 +66,7 @@
66
66
  "ts-node": "^10.9.2",
67
67
  "tsc-alias": "^1.8.16",
68
68
  "typescript": "^5.9.3",
69
- "@fjell/validation": "^4.4.5",
69
+ "@fjell/validation": "^4.4.6",
70
70
  "vitest": "^4.0.1"
71
71
  },
72
72
  "repository": {