0
# Configuration and Properties
1

2
Configuration options and runtime property management for customizing serialization, compression, namespacing, and error handling behavior.
3

4
## Capabilities
5

6
### KeyvOptions Interface
7

8
Complete configuration options for Keyv instances.
9

10
```typescript { .api }
11
interface KeyvOptions {
12
  /** Whether to emit error events (default: true) */
13
  emitErrors?: boolean;
14
  /** Namespace for key prefixing (default: 'keyv') */
15
  namespace?: string;
16
  /** Custom serialization function (default: JSON.stringify) */
17
  serialize?: Serialize;
18
  /** Custom deserialization function (default: JSON.parse) */
19
  deserialize?: Deserialize;
20
  /** Storage adapter instance (default: new Map()) */
21
  store?: KeyvStoreAdapter | Map<any, any> | any;
22
  /** Default TTL in milliseconds (default: undefined - no expiration) */
23
  ttl?: number;
24
  /** Compression adapter instance (default: undefined - no compression) */
25
  compression?: CompressionAdapter | any;
26
  /** Enable statistics tracking (default: false) */
27
  stats?: boolean;
28
  /** Enable key prefixing with namespace (default: true) */
29
  useKeyPrefix?: boolean;
30
  /** Throw errors in addition to emitting them (default: false) */
31
  throwOnErrors?: boolean;
32
}
33

34
type Serialize = <Value>(data: DeserializedData<Value>) => Promise<string> | string;
35
type Deserialize = <Value>(data: string) => Promise<DeserializedData<Value> | undefined> | DeserializedData<Value> | undefined;
36
```
37

38
**Usage Examples:**
39

40
```typescript
41
import Keyv from "keyv";
42
import KeyvRedis from "@keyv/redis";
43
import KeyvGzip from "@keyv/compress-gzip";
44

45
// Complete configuration example
46
const keyv = new Keyv({
47
  emitErrors: true,
48
  namespace: 'my-app',
49
  ttl: 3600000, // 1 hour default
50
  store: new KeyvRedis('redis://localhost:6379'),
51
  compression: new KeyvGzip(),
52
  stats: true,
53
  useKeyPrefix: true,
54
  throwOnErrors: false,
55
  serialize: JSON.stringify,
56
  deserialize: JSON.parse
57
});
58

59
// Minimal configuration
60
const simple = new Keyv({
61
  namespace: 'cache',
62
  ttl: 300000 // 5 minutes
63
});
64
```
65

66
### Namespace Configuration
67

68
Key prefixing and namespace management for isolation and collision avoidance.
69

70
```typescript { .api }
71
class Keyv {
72
  /** Get current namespace */
73
  get namespace(): string | undefined;
74
  
75
  /** Set namespace (updates storage adapter too) */
76
  set namespace(namespace: string | undefined);
77
}
78

79
interface KeyvOptions {
80
  /** Namespace for key prefixing */
81
  namespace?: string;
82
  /** Enable/disable key prefixing */
83
  useKeyPrefix?: boolean;
84
}
85
```
86

87
**Usage Examples:**
88

89
```typescript
90
const keyv = new Keyv({ namespace: 'user-sessions' });
91

92
// Keys are automatically prefixed
93
await keyv.set('abc123', { userId: 456 }); 
94
// Actually stored as 'user-sessions:abc123'
95

96
// Change namespace at runtime
97
keyv.namespace = 'admin-sessions';
98
await keyv.set('xyz789', { userId: 789 }); 
99
// Stored as 'admin-sessions:xyz789'
100

101
// Disable key prefixing
102
keyv.useKeyPrefix = false;
103
await keyv.set('raw-key', 'value'); 
104
// Stored as 'raw-key' (no prefix)
105

106
// Remove namespace entirely
107
keyv.namespace = undefined;
108
console.log(keyv.namespace); // undefined
109

110
// Multiple instances with different namespaces
111
const userCache = new Keyv({ namespace: 'users' });
112
const productCache = new Keyv({ namespace: 'products' });
113

114
await userCache.set('123', { name: 'Alice' }); // users:123
115
await productCache.set('123', { name: 'Widget' }); // products:123
116
// No collision between user ID 123 and product ID 123
117
```
118

119
### TTL Configuration
120

121
Time-to-live settings for automatic expiration.
122

123
```typescript { .api }
124
class Keyv {
125
  /** Get current default TTL */
126
  get ttl(): number | undefined;
127
  
128
  /** Set default TTL for new keys */
129
  set ttl(ttl: number | undefined);
130
}
131

132
interface KeyvOptions {
133
  /** Default TTL in milliseconds */
134
  ttl?: number;
135
}
136
```
137

138
**Usage Examples:**
139

140
```typescript
141
// Set default TTL at creation
142
const keyv = new Keyv({ ttl: 300000 }); // 5 minutes default
143

144
// All sets use default TTL unless overridden
145
await keyv.set('key1', 'value1'); // expires in 5 minutes
146
await keyv.set('key2', 'value2', 600000); // expires in 10 minutes (override)
147
await keyv.set('key3', 'value3', 0); // never expires (override)
148

149
// Change default TTL at runtime
150
keyv.ttl = 60000; // 1 minute
151
await keyv.set('key4', 'value4'); // expires in 1 minute
152

153
// Remove default TTL
154
keyv.ttl = undefined;
155
await keyv.set('key5', 'value5'); // never expires
156

157
// Check current TTL setting
158
console.log(keyv.ttl); // undefined
159
```
160

161
### Serialization Configuration
162

163
Custom serialization and deserialization functions.
164

165
```typescript { .api }
166
class Keyv {
167
  /** Get current serialization function */
168
  get serialize(): Serialize | undefined;
169
  
170
  /** Set serialization function */
171
  set serialize(serialize: Serialize | undefined);
172
  
173
  /** Get current deserialization function */
174
  get deserialize(): Deserialize | undefined;
175
  
176
  /** Set deserialization function */
177
  set deserialize(deserialize: Deserialize | undefined);
178
}
179
```
180

181
**Usage Examples:**
182

183
```typescript
184
const keyv = new Keyv();
185

186
// Custom serialization for special data types
187
keyv.serialize = (data) => {
188
  // Handle Date objects specially
189
  if (data.value instanceof Date) {
190
    return JSON.stringify({
191
      ...data,
192
      value: { __type: 'Date', __value: data.value.toISOString() }
193
    });
194
  }
195
  return JSON.stringify(data);
196
};
197

198
keyv.deserialize = (str) => {
199
  const data = JSON.parse(str);
200
  // Restore Date objects
201
  if (data.value && data.value.__type === 'Date') {
202
    data.value = new Date(data.value.__value);
203
  }
204
  return data;
205
};
206

207
// Now Date objects are preserved
208
await keyv.set('now', new Date());
209
const date = await keyv.get('now'); // Returns actual Date object
210

211
// Disable serialization entirely (for raw storage)
212
keyv.serialize = undefined;
213
keyv.deserialize = undefined;
214
// Now values are stored as-is (useful with generic stores)
215

216
// MessagePack serialization example
217
import msgpack from 'msgpack-lite';
218

219
keyv.serialize = (data) => msgpack.encode(data);
220
keyv.deserialize = (buffer) => msgpack.decode(buffer);
221
```
222

223
### Compression Configuration
224

225
Compression adapter integration for reducing storage space.
226

227
```typescript { .api }
228
interface CompressionAdapter {
229
  /** Compress value with optional options */
230
  compress(value: any, options?: any): Promise<any>;
231
  /** Decompress value with optional options */
232
  decompress(value: any, options?: any): Promise<any>;
233
  /** Serialize data with compression */
234
  serialize<Value>(data: DeserializedData<Value>): Promise<string> | string;
235
  /** Deserialize data with decompression */
236
  deserialize<Value>(data: string): Promise<DeserializedData<Value> | undefined> | DeserializedData<Value> | undefined;
237
}
238

239
class Keyv {
240
  /** Get current compression adapter */
241
  get compression(): CompressionAdapter | undefined;
242
  
243
  /** Set compression adapter */
244
  set compression(compress: CompressionAdapter | undefined);
245
}
246
```
247

248
**Usage Examples:**
249

250
```typescript
251
import Keyv from "keyv";
252
import KeyvGzip from "@keyv/compress-gzip";
253
import KeyvBrotli from "@keyv/compress-brotli";
254
import KeyvLz4 from "@keyv/compress-lz4";
255

256
// Gzip compression
257
const keyvGzip = new Keyv({
258
  compression: new KeyvGzip()
259
});
260

261
await keyvGzip.set('large-data', 'x'.repeat(10000)); // Compressed automatically
262

263
// Brotli compression (better compression ratio)
264
const keyvBrotli = new Keyv({
265
  compression: new KeyvBrotli()
266
});
267

268
// LZ4 compression (faster compression/decompression)
269
const keyvLz4 = new Keyv({
270
  compression: new KeyvLz4()
271
});
272

273
// Change compression at runtime
274
const keyv = new Keyv();
275
keyv.compression = new KeyvGzip();
276
await keyv.set('key1', 'large value'); // Compressed with gzip
277

278
keyv.compression = new KeyvBrotli();
279
await keyv.set('key2', 'another large value'); // Compressed with brotli
280

281
// Disable compression
282
keyv.compression = undefined;
283
await keyv.set('key3', 'uncompressed value'); // No compression
284

285
// Custom compression adapter
286
class CustomCompression {
287
  async compress(value) {
288
    // Your compression logic
289
    return compressData(value);
290
  }
291
  
292
  async decompress(value) {
293
    // Your decompression logic
294
    return decompressData(value);
295
  }
296
  
297
  serialize(data) {
298
    return JSON.stringify({
299
      value: this.compress(data.value),
300
      expires: data.expires
301
    });
302
  }
303
  
304
  deserialize(str) {
305
    const data = JSON.parse(str);
306
    return {
307
      value: this.decompress(data.value),
308
      expires: data.expires
309
    };
310
  }
311
}
312

313
keyv.compression = new CustomCompression();
314
```
315

316
### Statistics Configuration
317

318
Built-in operation statistics tracking.
319

320
```typescript { .api }
321
class StatsManager {
322
  /** Enable/disable statistics collection */
323
  enabled: boolean;
324
  /** Number of cache hits */
325
  hits: number;
326
  /** Number of cache misses */
327
  misses: number;
328
  /** Number of set operations */
329
  sets: number;
330
  /** Number of delete operations */
331
  deletes: number;
332
  /** Number of errors */
333
  errors: number;
334
  
335
  /** Record cache hit */
336
  hit(): void;
337
  /** Record cache miss */
338
  miss(): void;
339
  /** Record set operation */
340
  set(): void;
341
  /** Record delete operation */
342
  delete(): void;
343
  /** Record hits/misses from array */
344
  hitsOrMisses<T>(array: Array<T | undefined>): void;
345
  /** Reset all counters */
346
  reset(): void;
347
}
348

349
class Keyv {
350
  /** Access to statistics manager */
351
  stats: StatsManager;
352
}
353
```
354

355
**Usage Examples:**
356

357
```typescript
358
const keyv = new Keyv({ stats: true });
359

360
// Perform operations
361
await keyv.set('key1', 'value1');
362
await keyv.set('key2', 'value2');
363
await keyv.get('key1'); // hit
364
await keyv.get('nonexistent'); // miss
365
await keyv.delete('key1');
366

367
// Check statistics
368
console.log(keyv.stats.hits); // 1
369
console.log(keyv.stats.misses); // 1
370
console.log(keyv.stats.sets); // 2
371
console.log(keyv.stats.deletes); // 1
372

373
// Reset statistics
374
keyv.stats.reset();
375
console.log(keyv.stats.hits); // 0
376

377
// Enable/disable at runtime
378
keyv.stats.enabled = false;
379
await keyv.get('key2'); // Won't count as hit/miss
380
keyv.stats.enabled = true;
381

382
// Custom statistics reporting
383
setInterval(() => {
384
  const { hits, misses, sets, deletes } = keyv.stats;
385
  const hitRate = hits / (hits + misses) * 100;
386
  console.log(`Cache hit rate: ${hitRate.toFixed(2)}%`);
387
  console.log(`Operations: ${sets} sets, ${deletes} deletes`);
388
}, 60000); // Every minute
389
```
390

391
### Error Handling Configuration
392

393
Control error emission and throwing behavior.
394

395
```typescript { .api }
396
class Keyv {
397
  /** Get current throwOnErrors setting */
398
  get throwOnErrors(): boolean;
399
  
400
  /** Set throwOnErrors behavior */
401
  set throwOnErrors(value: boolean);
402
}
403

404
interface KeyvOptions {
405
  /** Emit error events (default: true) */
406
  emitErrors?: boolean;
407
  /** Throw errors in addition to emitting (default: false) */
408
  throwOnErrors?: boolean;
409
}
410
```
411

412
**Usage Examples:**
413

414
```typescript
415
// Silent operation (no error events)
416
const silent = new Keyv({ emitErrors: false });
417

418
// Throwing operation (errors cause exceptions)
419
const throwing = new Keyv({ throwOnErrors: true });
420

421
try {
422
  await throwing.set('key', 'value'); // May throw on storage error
423
} catch (error) {
424
  console.error('Operation failed:', error);
425
}
426

427
// Both emit and throw
428
const verbose = new Keyv({ 
429
  emitErrors: true, 
430
  throwOnErrors: true 
431
});
432

433
verbose.on('error', (err) => console.log('Error event:', err));
434

435
try {
436
  await verbose.get('key'); // May both emit event AND throw
437
} catch (error) {
438
  console.error('Caught exception:', error);
439
}
440

441
// Change behavior at runtime
442
const keyv = new Keyv();
443
keyv.throwOnErrors = true; // Now operations will throw
444
```
445

446
### Runtime Configuration Access
447

448
Access to the complete options object.
449

450
```typescript { .api }
451
class Keyv {
452
  /** Access to current configuration options */
453
  opts: KeyvOptions_;
454
}
455
```
456

457
**Usage Examples:**
458

459
```typescript
460
const keyv = new Keyv({
461
  namespace: 'app',
462
  ttl: 60000,
463
  stats: true
464
});
465

466
// Access current configuration
467
console.log(keyv.opts.namespace); // 'app'
468
console.log(keyv.opts.ttl); // 60000
469
console.log(keyv.opts.stats); // true
470

471
// Configuration is read-only through opts
472
// Use property setters to modify:
473
keyv.namespace = 'new-namespace';
474
keyv.ttl = 120000;
475

476
console.log(keyv.opts.namespace); // 'new-namespace'
477
console.log(keyv.opts.ttl); // 120000
478
```