0
# File System Caching
1

2
High-performance file system caching system with namespace support, TTL, and both synchronous and asynchronous operations. Built specifically for development workflow optimization and build performance.
3

4
## Capabilities
5

6
### FileSystemCache Class
7

8
Full-featured file system caching implementation with flexible configuration options.
9

10
```typescript { .api }
11
/**
12
 * High-performance file system cache with TTL and namespace support
13
 */
14
class FileSystemCache {
15
  /**
16
   * Create a new file system cache instance
17
   * @param options - Cache configuration options
18
   */
19
  constructor(options?: {
20
    /** Cache namespace for isolation */
21
    ns?: string;
22
    /** Key prefix for all cache entries */
23
    prefix?: string;
24
    /** Hash algorithm for key generation */
25
    hash_alg?: string;
26
    /** Base path for cache storage */
27
    basePath?: string;
28
    /** Time-to-live in milliseconds */
29
    ttl?: number;
30
  });
31

32
  /**
33
   * Get cached value asynchronously
34
   * @param key - Cache key
35
   * @returns Promise resolving to cached value or undefined if not found/expired
36
   */
37
  get<T>(key: string): Promise<T | undefined>;
38

39
  /**
40
   * Get cached value synchronously
41
   * @param key - Cache key
42
   * @returns Cached value or undefined if not found/expired
43
   */
44
  getSync<T>(key: string): T | undefined;
45

46
  /**
47
   * Set cached value asynchronously
48
   * @param key - Cache key
49
   * @param value - Value to cache
50
   * @returns Promise resolving when value is cached
51
   */
52
  set<T>(key: string, value: T): Promise<void>;
53

54
  /**
55
   * Set cached value synchronously
56
   * @param key - Cache key
57
   * @param value - Value to cache
58
   */
59
  setSync<T>(key: string, value: T): void;
60

61
  /**
62
   * Set multiple cached values asynchronously
63
   * @param entries - Array of key-value pairs to cache
64
   * @returns Promise resolving when all values are cached
65
   */
66
  setMany<T>(entries: Array<[string, T]>): Promise<void>;
67

68
  /**
69
   * Set multiple cached values synchronously
70
   * @param entries - Array of key-value pairs to cache
71
   */
72
  setManySync<T>(entries: Array<[string, T]>): void;
73

74
  /**
75
   * Remove cached value asynchronously
76
   * @param key - Cache key to remove
77
   * @returns Promise resolving when value is removed
78
   */
79
  remove(key: string): Promise<void>;
80

81
  /**
82
   * Remove cached value synchronously
83
   * @param key - Cache key to remove
84
   */
85
  removeSync(key: string): void;
86

87
  /**
88
   * Clear all cached values asynchronously
89
   * @returns Promise resolving when cache is cleared
90
   */
91
  clear(): Promise<void>;
92

93
  /**
94
   * Clear all cached values synchronously
95
   */
96
  clearSync(): void;
97

98
  /**
99
   * Get all cached values asynchronously
100
   * @returns Promise resolving to array of key-value pairs
101
   */
102
  getAll<T>(): Promise<Array<[string, T]>>;
103

104
  /**
105
   * Load cache from disk
106
   * @returns Promise resolving when cache is loaded
107
   */
108
  load(): Promise<void>;
109
}
110
```
111

112
**Usage Examples:**
113

114
```typescript
115
import { FileSystemCache } from "@storybook/core-common";
116

117
// Create cache with default settings
118
const cache = new FileSystemCache();
119

120
// Cache with custom configuration
121
const customCache = new FileSystemCache({
122
  ns: 'storybook-dev',
123
  prefix: 'build-',
124
  ttl: 60 * 60 * 1000, // 1 hour TTL
125
  basePath: './node_modules/.cache/storybook'
126
});
127

128
// Basic async operations
129
await cache.set('webpack-config', compiledConfig);
130
const config = await cache.get('webpack-config');
131

132
// Sync operations for performance-critical paths
133
cache.setSync('fast-lookup', data);
134
const result = cache.getSync('fast-lookup');
135

136
// Batch operations
137
await cache.setMany([
138
  ['stories', storyEntries],
139
  ['metadata', projectMeta],
140
  ['dependencies', deps]
141
]);
142

143
// Cleanup
144
await cache.remove('outdated-key');
145
await cache.clear();
146
```
147

148
### Cache Factory Function
149

150
Factory function for creating FileSystemCache instances with predefined configurations.
151

152
```typescript { .api }
153
/**
154
 * Create a FileSystemCache instance with specified options
155
 * @param options - Cache configuration options
156
 * @returns Configured FileSystemCache instance
157
 */
158
function createFileSystemCache(options?: {
159
  ns?: string;
160
  prefix?: string;
161
  hash_alg?: string;
162
  basePath?: string;
163
  ttl?: number;
164
}): FileSystemCache;
165
```
166

167
**Usage Example:**
168

169
```typescript
170
import { createFileSystemCache } from "@storybook/core-common";
171

172
// Create specialized caches for different purposes
173
const buildCache = createFileSystemCache({
174
  ns: 'build',
175
  ttl: 24 * 60 * 60 * 1000 // 24 hours
176
});
177

178
const devCache = createFileSystemCache({
179
  ns: 'dev-server',
180
  ttl: 60 * 60 * 1000 // 1 hour
181
});
182

183
// Use for different data types
184
await buildCache.set('webpack-stats', stats);
185
await devCache.set('hot-reload-state', hmrState);
186
```
187

188
### Default Cache Instance
189

190
Pre-configured cache instance for immediate use in development workflows.
191

192
```typescript { .api }
193
/**
194
 * Default file system cache instance configured for Storybook dev-server
195
 */
196
declare const cache: FileSystemCache;
197
```
198

199
**Usage Example:**
200

201
```typescript
202
import { cache } from "@storybook/core-common";
203

204
// Use default cache directly
205
const cachedStories = await cache.get('normalized-stories');
206
if (!cachedStories) {
207
  const stories = await processStories();
208
  await cache.set('normalized-stories', stories);
209
}
210

211
// Cache build artifacts
212
await cache.set('babel-config', babelConfig);
213
await cache.set('webpack-config', webpackConfig);
214
```
215

216
### Cache Path Resolution
217

218
Utility for resolving paths within the Storybook cache directory.
219

220
```typescript { .api }
221
/**
222
 * Resolve path within Storybook cache directory
223
 * @param name - Cache entry name
224
 * @param sub - Optional subdirectory
225
 * @returns Resolved cache path
226
 */
227
function resolvePathInStorybookCache(name: string, sub?: string): string;
228
```
229

230
**Usage Example:**
231

232
```typescript
233
import { resolvePathInStorybookCache } from "@storybook/core-common";
234

235
// Get cache paths for manual file operations
236
const buildCachePath = resolvePathInStorybookCache('build-artifacts');
237
const metaCachePath = resolvePathInStorybookCache('metadata', 'stories');
238

239
// Use with other file operations
240
const fs = require('fs');
241
const configPath = resolvePathInStorybookCache('webpack.config.js');
242
fs.writeFileSync(configPath, configContent);
243
```
244

245
## Advanced Caching Patterns
246

247
### Conditional Caching
248

249
```typescript
250
import { cache } from "@storybook/core-common";
251

252
async function getProcessedStories(configDir: string, isDev: boolean) {
253
  const cacheKey = `stories-${configDir}-${isDev ? 'dev' : 'prod'}`;
254
  
255
  // Try cache first
256
  let stories = await cache.get(cacheKey);
257
  
258
  if (!stories) {
259
    // Process stories if not cached
260
    stories = await processStoryEntries(configDir, isDev);
261
    
262
    // Cache with appropriate TTL
263
    await cache.set(cacheKey, stories);
264
  }
265
  
266
  return stories;
267
}
268
```
269

270
### Cache Invalidation
271

272
```typescript
273
import { cache } from "@storybook/core-common";
274

275
async function invalidateRelatedCache(pattern: string) {
276
  const allEntries = await cache.getAll();
277
  
278
  // Remove entries matching pattern
279
  const keysToRemove = allEntries
280
    .map(([key]) => key)
281
    .filter(key => key.includes(pattern));
282
    
283
  for (const key of keysToRemove) {
284
    await cache.remove(key);
285
  }
286
}
287

288
// Usage
289
await invalidateRelatedCache('webpack-'); // Remove all webpack-related cache
290
```
291

292
### Performance Monitoring
293

294
```typescript
295
import { cache } from "@storybook/core-common";
296

297
async function cachedOperation<T>(
298
  key: string, 
299
  operation: () => Promise<T>
300
): Promise<T> {
301
  const start = performance.now();
302
  
303
  // Try cache first
304
  let result = await cache.get<T>(key);
305
  
306
  if (result) {
307
    console.log(`Cache hit for ${key}: ${performance.now() - start}ms`);
308
    return result;
309
  }
310
  
311
  // Execute operation and cache result
312
  result = await operation();
313
  await cache.set(key, result);
314
  
315
  console.log(`Cache miss for ${key}: ${performance.now() - start}ms`);
316
  return result;
317
}
318
```
319

320
## Configuration Options
321

322
```typescript { .api }
323
interface CacheOptions {
324
  /** Namespace for cache isolation between different tools/contexts */
325
  ns?: string;
326
  
327
  /** Prefix added to all cache keys */
328
  prefix?: string;
329
  
330
  /** Hash algorithm used for key generation (default: 'md5') */
331
  hash_alg?: string;
332
  
333
  /** Base directory for cache storage */
334
  basePath?: string;
335
  
336
  /** Time-to-live in milliseconds (0 = no expiration) */
337
  ttl?: number;
338
}
339
```