0
# Raw Data Access
1

2
Direct access to internal data structures including TTL metadata, useful for debugging and advanced use cases where expiry information is needed.
3

4
## Capabilities
5

6
### Get Raw
7

8
Retrieves the raw stored data including internal metadata like expiry timestamps.
9

10
```typescript { .api }
11
/**
12
 * Get raw stored data for a key including TTL metadata
13
 * @param key - Key to retrieve raw data for
14
 * @returns Promise resolving to raw data object or undefined if key doesn't exist or is expired
15
 */
16
async getRaw<Value = GenericValue>(key: string): Promise<StoredDataRaw<Value> | undefined>;
17

18
type DeserializedData<Value> = {
19
  /** The stored value */
20
  value?: Value;
21
  /** Unix timestamp when the key expires (undefined means no expiration) */
22
  expires?: number | undefined;
23
};
24

25
type StoredDataRaw<Value> = DeserializedData<Value> | undefined;
26
```
27

28
**Usage Examples:**
29

30
```typescript
31
const keyv = new Keyv();
32

33
// Set data with TTL
34
await keyv.set('session', 'abc123', 60000); // expires in 1 minute
35

36
// Get raw data
37
const raw = await keyv.getRaw('session');
38
console.log(raw);
39
// {
40
//   value: 'abc123',
41
//   expires: 1625097660000  // Unix timestamp
42
// }
43

44
// Set data without TTL
45
await keyv.set('permanent', 'forever');
46
const rawPermanent = await keyv.getRaw('permanent');
47
console.log(rawPermanent);
48
// {
49
//   value: 'forever',
50
//   expires: undefined  // No expiration
51
// }
52

53
// Check if key will expire soon
54
const userData = await keyv.getRaw('user:session');
55
if (userData && userData.expires) {
56
  const timeLeft = userData.expires - Date.now();
57
  if (timeLeft < 5000) { // Less than 5 seconds
58
    console.log('Session expires soon!');
59
  }
60
}
61

62
// Nonexistent key
63
const missing = await keyv.getRaw('nonexistent'); // undefined
64

65
// Expired key (returns undefined, key is also deleted)
66
await keyv.set('temp', 'data', 1000); // 1 second TTL
67
// ... wait 2 seconds
68
const expired = await keyv.getRaw('temp'); // undefined
69
```
70

71
### Get Many Raw
72

73
Retrieves raw stored data for multiple keys simultaneously.
74

75
```typescript { .api }
76
/**
77
 * Get raw stored data for multiple keys including TTL metadata
78
 * @param keys - Array of keys to retrieve raw data for
79
 * @returns Promise resolving to array of raw data objects in same order as keys
80
 */
81
async getManyRaw<Value = GenericValue>(keys: string[]): Promise<Array<StoredDataRaw<Value>>>;
82
```
83

84
**Usage Examples:**
85

86
```typescript
87
const keyv = new Keyv();
88

89
// Setup test data with different TTL values
90
await keyv.set('user:1', { name: 'Alice' }, 60000); // 1 minute
91
await keyv.set('user:2', { name: 'Bob' }, 120000); // 2 minutes  
92
await keyv.set('user:3', { name: 'Charlie' }); // permanent
93

94
// Get raw data for multiple keys
95
const rawUsers = await keyv.getManyRaw(['user:1', 'user:2', 'user:3', 'user:4']);
96
console.log(rawUsers);
97
// [
98
//   { value: { name: 'Alice' }, expires: 1625097720000 },
99
//   { value: { name: 'Bob' }, expires: 1625097780000 },
100
//   { value: { name: 'Charlie' }, expires: undefined },
101
//   undefined  // user:4 doesn't exist
102
// ]
103

104
// Process results with expiry checking
105
const results = await keyv.getManyRaw(['session:1', 'session:2', 'session:3']);
106
const now = Date.now();
107

108
results.forEach((raw, index) => {
109
  const key = `session:${index + 1}`;
110
  if (!raw) {
111
    console.log(`${key}: Not found`);
112
  } else if (raw.expires && raw.expires < now) {
113
    console.log(`${key}: Expired`);
114
  } else if (raw.expires) {
115
    const timeLeft = Math.round((raw.expires - now) / 1000);
116
    console.log(`${key}: Expires in ${timeLeft} seconds`);
117
  } else {
118
    console.log(`${key}: Permanent`);
119
  }
120
});
121

122
// Type safety with generics
123
interface Session { userId: string; token: string; }
124
const rawSessions = await keyv.getManyRaw<Session>(['session:1', 'session:2']);
125
// Array<DeserializedData<Session> | undefined>
126

127
// Empty array handling  
128
const empty = await keyv.getManyRaw([]); // []
129
```
130

131
## Use Cases
132

133
Raw data access is particularly useful for:
134

135
### TTL Monitoring
136

137
```typescript
138
const keyv = new Keyv();
139

140
// Function to check TTL status
141
async function checkTTL(key: string) {
142
  const raw = await keyv.getRaw(key);
143
  if (!raw) {
144
    return 'Key does not exist';
145
  }
146
  
147
  if (!raw.expires) {
148
    return 'Key never expires';
149
  }
150
  
151
  const timeLeft = raw.expires - Date.now();
152
  if (timeLeft <= 0) {
153
    return 'Key has expired';
154
  }
155
  
156
  return `Key expires in ${Math.round(timeLeft / 1000)} seconds`;
157
}
158

159
await keyv.set('temp-data', 'value', 30000); // 30 seconds
160
console.log(await checkTTL('temp-data')); // "Key expires in 30 seconds"
161
```
162

163
### Cache Warming
164

165
```typescript
166
const keyv = new Keyv();
167

168
// Pre-emptively refresh keys that are about to expire
169
async function refreshExpiringSoon(keys: string[], thresholdMs: number = 5000) {
170
  const rawData = await keyv.getManyRaw(keys);
171
  const now = Date.now();
172
  
173
  const expiringSoon = rawData
174
    .map((raw, index) => ({ key: keys[index], raw }))
175
    .filter(({ raw }) => 
176
      raw && raw.expires && (raw.expires - now) < thresholdMs
177
    );
178
    
179
  for (const { key, raw } of expiringSoon) {
180
    console.log(`Refreshing ${key} (expires in ${raw!.expires! - now}ms)`);
181
    // Refresh logic here
182
    await refreshKey(key);
183
  }
184
}
185

186
async function refreshKey(key: string) {
187
  // Your refresh logic
188
  const newValue = await fetchFreshData(key);
189
  await keyv.set(key, newValue, 60000);
190
}
191
```
192

193
### Debugging and Monitoring
194

195
```typescript
196
const keyv = new Keyv();
197

198
// Debug function to inspect storage state
199
async function debugKeys(keys: string[]) {
200
  const rawData = await keyv.getManyRaw(keys);
201
  
202
  keys.forEach((key, index) => {
203
    const raw = rawData[index];
204
    if (!raw) {
205
      console.log(`${key}: [MISSING]`);
206
    } else {
207
      const expires = raw.expires ? new Date(raw.expires).toISOString() : 'never';
208
      console.log(`${key}: value=${JSON.stringify(raw.value)}, expires=${expires}`);
209
    }
210
  });
211
}
212

213
await keyv.set('debug:1', { test: true }, 30000);
214
await keyv.set('debug:2', 'permanent data');
215
await debugKeys(['debug:1', 'debug:2', 'debug:3']);
216
// debug:1: value={"test":true}, expires=2021-07-01T12:30:00.000Z  
217
// debug:2: value="permanent data", expires=never
218
// debug:3: [MISSING]
219
```