0
# Core Storage Operations
1

2
Primary key-value storage functionality including get, set, delete operations with TTL support and type safety for all JavaScript data types including Buffer.
3

4
## Capabilities
5

6
### Constructor
7

8
Creates a new Keyv instance with optional storage adapter and configuration options.
9

10
```typescript { .api }
11
/**
12
 * Create a Keyv instance
13
 * @param options - Configuration options for the instance
14
 */
15
constructor(options?: KeyvOptions);
16

17
/**
18
 * Create a Keyv instance with storage adapter and options
19
 * @param store - Storage adapter instance or options object  
20
 * @param options - Additional options (merged with store options)
21
 */
22
constructor(store?: KeyvStoreAdapter | KeyvOptions | Map<any, any>, options?: Omit<KeyvOptions, 'store'>);
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import Keyv from "keyv";
29
import KeyvRedis from "@keyv/redis";
30

31
// In-memory storage (default)
32
const keyv = new Keyv();
33

34
// With options
35
const keyvWithTTL = new Keyv({ ttl: 60000, namespace: 'my-cache' });
36

37
// With storage adapter
38
const keyvRedis = new Keyv(new KeyvRedis('redis://localhost:6379'));
39

40
// Storage adapter with options
41
const keyvWithStore = new Keyv(new KeyvRedis('redis://localhost:6379'), { 
42
  ttl: 30000, 
43
  namespace: 'sessions' 
44
});
45

46
// Type-safe instance
47
const keyvTyped = new Keyv<{ name: string; age: number }>();
48
```
49

50
### Get Operation
51

52
Retrieves values by key with support for single keys, arrays, and raw data access.
53

54
```typescript { .api }
55
/**
56
 * Get value by key
57
 * @param key - Key to retrieve
58
 * @param options - Options including raw data access
59
 * @returns Promise resolving to stored value or undefined
60
 */
61
async get<Value = GenericValue>(key: string, options?: {raw?: false}): Promise<StoredDataNoRaw<Value>>;
62
async get<Value = GenericValue>(key: string, options?: {raw?: true}): Promise<StoredDataRaw<Value>>;
63

64
/**
65
 * Get multiple values by keys array
66
 * @param key - Array of keys to retrieve
67
 * @param options - Options including raw data access
68
 * @returns Promise resolving to array of stored values
69
 */
70
async get<Value = GenericValue>(key: string[], options?: {raw?: false}): Promise<Array<StoredDataNoRaw<Value>>>;
71
async get<Value = GenericValue>(key: string[], options?: {raw?: true}): Promise<Array<StoredDataRaw<Value>>>;
72
```
73

74
**Usage Examples:**
75

76
```typescript
77
const keyv = new Keyv();
78

79
// Basic get
80
await keyv.set('user', { name: 'Alice', age: 30 });
81
const user = await keyv.get('user'); // { name: 'Alice', age: 30 }
82

83
// Get with type
84
const message = await keyv.get<string>('message'); // string | undefined
85

86
// Get raw data (includes TTL info)
87
const raw = await keyv.get('user', { raw: true }); 
88
// { value: { name: 'Alice', age: 30 }, expires: 1625097600000 }
89

90
// Get multiple keys
91
const users = await keyv.get(['user:1', 'user:2', 'user:3']); 
92
// [{ name: 'Alice' }, { name: 'Bob' }, undefined]
93

94
// Expired keys return undefined
95
await keyv.set('temp', 'data', 1000); // expires in 1 second
96
// ... wait 2 seconds
97
const expired = await keyv.get('temp'); // undefined
98
```
99

100
### Set Operation
101

102
Stores values by key with optional TTL (time-to-live) expiration.
103

104
```typescript { .api }
105
/**
106
 * Set value for key with optional TTL
107
 * @param key - Key to store value under
108
 * @param value - Value to store (any JSON-serializable type plus Buffer)
109
 * @param ttl - Time to live in milliseconds (optional)
110
 * @returns Promise resolving to true if successful, false if failed
111
 */
112
async set<Value = GenericValue>(key: string, value: Value, ttl?: number): Promise<boolean>;
113
```
114

115
**Usage Examples:**
116

117
```typescript
118
const keyv = new Keyv();
119

120
// Basic set
121
await keyv.set('user', { name: 'Alice', age: 30 }); // true
122

123
// Set with TTL (expires in 5 minutes)
124
await keyv.set('session', 'abc123', 5 * 60 * 1000); // true
125

126
// Set with type
127
await keyv.set<string>('message', 'hello world'); // true
128

129
// Overwrite existing key
130
await keyv.set('counter', 1); // true
131
await keyv.set('counter', 2); // true (overwrites)
132

133
// Different data types
134
await keyv.set('buffer', Buffer.from('data')); // true
135
await keyv.set('date', new Date()); // true  
136
await keyv.set('array', [1, 2, 3]); // true
137
await keyv.set('null', null); // true
138

139
// TTL of 0 means no expiration
140
await keyv.set('permanent', 'never expires', 0); // true
141
```
142

143
### Delete Operation
144

145
Removes keys from storage with support for single keys and arrays.
146

147
```typescript { .api }
148
/**
149
 * Delete key(s) from storage
150
 * @param key - Key or array of keys to delete
151
 * @returns Promise resolving to true if key existed and was deleted
152
 */
153
async delete(key: string | string[]): Promise<boolean>;
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
const keyv = new Keyv();
160

161
// Delete single key
162
await keyv.set('user', { name: 'Alice' });
163
await keyv.delete('user'); // true (existed and deleted)
164
await keyv.delete('nonexistent'); // false (didn't exist)
165

166
// Delete multiple keys
167
await keyv.set('a', 1);
168
await keyv.set('b', 2);
169
await keyv.delete(['a', 'b', 'c']); // true (at least one existed)
170
```
171

172
### Clear Operation
173

174
Removes all entries in the current namespace.
175

176
```typescript { .api }
177
/**
178
 * Clear all entries in current namespace
179
 * @returns Promise that resolves when entries are cleared
180
 */
181
async clear(): Promise<void>;
182
```
183

184
**Usage Examples:**
185

186
```typescript
187
const keyv = new Keyv({ namespace: 'cache' });
188

189
await keyv.set('key1', 'value1');
190
await keyv.set('key2', 'value2');
191
await keyv.clear(); // Removes all entries in 'cache' namespace
192

193
const key1 = await keyv.get('key1'); // undefined
194
const key2 = await keyv.get('key2'); // undefined
195
```
196

197
### Has Operation
198

199
Checks if keys exist and are not expired.
200

201
```typescript { .api }
202
/**
203
 * Check if key exists and is not expired
204
 * @param key - Key or array of keys to check
205
 * @returns Promise resolving to boolean or array of booleans
206
 */
207
async has(key: string): Promise<boolean>;
208
async has(key: string[]): Promise<boolean[]>;
209
```
210

211
**Usage Examples:**
212

213
```typescript
214
const keyv = new Keyv();
215

216
await keyv.set('existing', 'value');
217
await keyv.has('existing'); // true
218
await keyv.has('nonexistent'); // false
219

220
// Multiple keys
221
await keyv.has(['existing', 'nonexistent', 'another']); // [true, false, false]
222

223
// Expired keys return false
224
await keyv.set('temp', 'value', 1000); // expires in 1 second
225
// ... wait 2 seconds
226
await keyv.has('temp'); // false (expired)
227
```
228

229
### Disconnect Operation
230

231
Cleanly disconnects from the storage adapter if supported.
232

233
```typescript { .api }
234
/**
235
 * Disconnect from storage adapter
236
 * @returns Promise that resolves when disconnected
237
 */
238
async disconnect(): Promise<void>;
239
```
240

241
**Usage Examples:**
242

243
```typescript
244
import Keyv from "keyv";
245
import KeyvRedis from "@keyv/redis";
246

247
const keyv = new Keyv(new KeyvRedis('redis://localhost:6379'));
248

249
// Perform operations
250
await keyv.set('key', 'value');
251

252
// Clean disconnect
253
await keyv.disconnect(); // Closes Redis connection
254
```
255

256
### Iterator Operation
257

258
Iterate over all entries in the current namespace using async iteration.
259

260
```typescript { .api }
261
/**
262
 * Async iterator for all entries in the current namespace
263
 * Available when storage adapter supports iteration
264
 */
265
iterator?: IteratorFunction;
266

267
type IteratorFunction = (argument: any) => AsyncGenerator<any, void>;
268
```
269

270
**Usage Examples:**
271

272
```typescript
273
import Keyv from "keyv";
274
import KeyvSqlite from "@keyv/sqlite";
275

276
const keyv = new Keyv(new KeyvSqlite('sqlite://data.db'));
277

278
// Add some data
279
await keyv.set('user:1', { name: 'Alice', age: 30 });
280
await keyv.set('user:2', { name: 'Bob', age: 25 });
281
await keyv.set('product:1', { name: 'Widget', price: 9.99 });
282

283
// Iterate over all entries
284
if (keyv.iterator) {
285
  for await (const [key, value] of keyv.iterator()) {
286
    console.log(`${key}: ${JSON.stringify(value)}`);
287
  }
288
  // Output:
289
  // user:1: {"name":"Alice","age":30}
290
  // user:2: {"name":"Bob","age":25}  
291
  // product:1: {"name":"Widget","price":9.99}
292
}
293

294
// Iterator with namespace filtering
295
const userKeyv = new Keyv(new KeyvSqlite('sqlite://data.db'), { namespace: 'users' });
296
await userKeyv.set('1', { name: 'Alice' });
297
await userKeyv.set('2', { name: 'Bob' });
298

299
if (userKeyv.iterator) {
300
  for await (const [key, value] of userKeyv.iterator()) {
301
    console.log(`User ${key}: ${value.name}`);
302
  }
303
  // Output:
304
  // User 1: Alice
305
  // User 2: Bob
306
}
307

308
// Check if iterator is available
309
const memoryKeyv = new Keyv(); // Uses Map storage
310
if (memoryKeyv.iterator) {
311
  // Iterator is available for Map storage
312
  for await (const [key, value] of memoryKeyv.iterator()) {
313
    console.log(key, value);
314
  }
315
} else {
316
  console.log('Iterator not available for this storage adapter');
317
}
318
```
319

320
**Notes:**
321
- Iterator availability depends on the storage adapter
322
- Available for Map storage (default) and most database adapters (SQLite, PostgreSQL, MySQL, MongoDB, Redis, etc.)
323
- Automatically filters by namespace when set
324
- Expired keys are automatically removed during iteration
325
- Iterator respects the `useKeyPrefix` setting