@argos-js/cache 0.0.0-stage → 0.1.0

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.
@@ -0,0 +1,168 @@
1
+ /**
2
+ * Options provided when setting a cache entry.
3
+ */
4
+ export interface SetOptions {
5
+ /**
6
+ * Time to live in seconds. If omitted, uses defaultTtl from CacheConfig.
7
+ */
8
+ ttl?: number;
9
+ /**
10
+ * Tags associated with this entry for batch invalidation (e.g. ['users', 'tenant_123']).
11
+ */
12
+ tags?: string[];
13
+ }
14
+ /**
15
+ * Common interface that all Argos cache drivers must satisfy.
16
+ */
17
+ export interface CacheDriver {
18
+ readonly name: string;
19
+ /**
20
+ * Retrieves a cached value by key. Returns null if expired or not found.
21
+ */
22
+ get<T = unknown>(key: string): Promise<T | null>;
23
+ /**
24
+ * Sets a value in the cache with optional TTL and tags.
25
+ */
26
+ set<T = unknown>(key: string, value: T, options?: SetOptions): Promise<void>;
27
+ /**
28
+ * Deletes a cache entry by key. Returns true if removed, false otherwise.
29
+ */
30
+ delete(key: string): Promise<boolean>;
31
+ /**
32
+ * Deletes multiple cache entries by keys. Returns the count of deleted entries.
33
+ */
34
+ deleteMany?(keys: string[]): Promise<number>;
35
+ /**
36
+ * Checks whether a non-expired entry exists for the given key.
37
+ */
38
+ has(key: string): Promise<boolean>;
39
+ /**
40
+ * Clears all cache entries managed by this driver.
41
+ */
42
+ clear(): Promise<void>;
43
+ /**
44
+ * Invalidates all cache entries associated with the specified tag.
45
+ */
46
+ invalidateByTag?(tag: string): Promise<void>;
47
+ /**
48
+ * Gracefully closes any active client connections, sockets, or listeners.
49
+ */
50
+ disconnect?(): Promise<void>;
51
+ }
52
+ export type SupportedCacheDriver = 'pulse' | 'redis' | 'argosdb' | 'memory';
53
+ export interface PulseNearCacheConfig {
54
+ /**
55
+ * Whether to actively subscribe to CDC mutation events on argosdb-pulse.
56
+ * Default: true.
57
+ */
58
+ listenCdc?: boolean;
59
+ /**
60
+ * List of database tables to watch for mutations (e.g. ['auth_users', 'products']).
61
+ * If omitted or empty, listens to all CDC events ('cdc.*').
62
+ */
63
+ watchedTables?: string[];
64
+ /**
65
+ * Optional custom EventsManager instance. If omitted, uses global `events` from @argos-js/events.
66
+ */
67
+ events?: any;
68
+ /**
69
+ * Optional custom function mapping a CDC mutation to cache keys to invalidate.
70
+ */
71
+ keyResolver?: (tableName: string, primaryKey: string, op: number) => string[];
72
+ /**
73
+ * Maximum number of items in L1 memory cache before LRU eviction kicks in.
74
+ */
75
+ maxItems?: number;
76
+ /**
77
+ * Default TTL for L1 cache entries in seconds.
78
+ */
79
+ defaultTtl?: number;
80
+ /**
81
+ * Consumer group name for CDC subscription.
82
+ */
83
+ groupName?: string;
84
+ /**
85
+ * Worker ID for the consumer group.
86
+ */
87
+ workerId?: string;
88
+ }
89
+ export interface RedisCacheConfig {
90
+ /**
91
+ * Redis connection URL (e.g. 'redis://localhost:6379').
92
+ */
93
+ url?: string;
94
+ host?: string;
95
+ port?: number;
96
+ password?: string;
97
+ db?: number;
98
+ /**
99
+ * Optional pre-instantiated Redis client (ioredis instance or duck-typed).
100
+ */
101
+ client?: any;
102
+ }
103
+ export interface ArgosDbTableCacheConfig {
104
+ /**
105
+ * Database client instance (@argos-js/data DatabaseClient or query function).
106
+ */
107
+ db?: any;
108
+ /**
109
+ * Database table name used for storing cache entries. Default: 'app_cache'.
110
+ */
111
+ tableName?: string;
112
+ /**
113
+ * Whether to automatically create the cache table if it does not exist. Default: true.
114
+ */
115
+ autoCreateTable?: boolean;
116
+ }
117
+ export interface MemoryCacheConfig {
118
+ /**
119
+ * Maximum number of items to keep in memory before LRU eviction.
120
+ * Default: 10000.
121
+ */
122
+ maxItems?: number;
123
+ /**
124
+ * Default TTL in seconds.
125
+ */
126
+ defaultTtl?: number;
127
+ }
128
+ export interface CacheConfig {
129
+ /**
130
+ * Active driver name ('pulse', 'redis', 'argosdb', 'memory').
131
+ */
132
+ driver?: SupportedCacheDriver | string;
133
+ /**
134
+ * Global key prefix applied to all cache keys (e.g. 'argos_api:').
135
+ */
136
+ prefix?: string;
137
+ /**
138
+ * Default time-to-live in seconds when not specified in `set()`. Default: 300 (5 minutes).
139
+ */
140
+ defaultTtl?: number;
141
+ /**
142
+ * Configuration for Pulse Near-Cache driver.
143
+ */
144
+ pulse?: PulseNearCacheConfig;
145
+ /**
146
+ * Configuration for Redis driver.
147
+ */
148
+ redis?: RedisCacheConfig;
149
+ /**
150
+ * Configuration for ArgosDB Table driver.
151
+ */
152
+ argosdb?: ArgosDbTableCacheConfig;
153
+ /**
154
+ * Configuration for In-Memory driver.
155
+ */
156
+ memory?: MemoryCacheConfig;
157
+ /**
158
+ * Driver map for additional custom or named configurations.
159
+ */
160
+ drivers?: {
161
+ pulse?: PulseNearCacheConfig;
162
+ redis?: RedisCacheConfig;
163
+ argosdb?: ArgosDbTableCacheConfig;
164
+ memory?: MemoryCacheConfig;
165
+ [key: string]: unknown;
166
+ };
167
+ }
168
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
package/dist/types.js ADDED
@@ -0,0 +1,3 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}
package/package.json CHANGED
@@ -1,6 +1,38 @@
1
1
  {
2
2
  "name": "@argos-js/cache",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0",
4
+ "description": "Modular, runtime-agnostic caching suite for Argos-JS with Pulse CDC Near-Cache, Redis, ArgosDB Table and In-Memory drivers",
5
+ "main": "./dist/index.js",
6
+ "types": "./dist/index.d.ts",
7
+ "exports": {
8
+ ".": {
9
+ "import": "./dist/index.js",
10
+ "require": "./dist/index.js",
11
+ "types": "./dist/index.d.ts"
12
+ }
13
+ },
14
+ "publishConfig": {
15
+ "access": "public"
16
+ },
17
+ "dependencies": {
18
+ "@argos-js/core": "0.1.0",
19
+ "@argos-js/events": "0.1.0"
20
+ },
21
+ "devDependencies": {
22
+ "@types/node": "^20.11.0",
23
+ "typescript": "^5.4.0",
24
+ "vitest": "^5.0.3",
25
+ "@argos-js/data": "0.1.0"
26
+ },
27
+ "license": "MIT",
28
+ "files": [
29
+ "dist",
30
+ "README.md",
31
+ "LICENSE"
32
+ ],
33
+ "scripts": {
34
+ "build": "tsc",
35
+ "dev": "tsc --watch",
36
+ "test": "vitest run"
37
+ }
6
38
  }