wip library to store cold objects in s3, warm objects on disk, and hot objects in memory
nekomimi.pet
nodejs
typescript
1import { gzip, gunzip } from 'node:zlib';
2import { promisify } from 'node:util';
3
4const gzipAsync = promisify(gzip);
5const gunzipAsync = promisify(gunzip);
6
7/**
8 * Compress data using gzip.
9 *
10 * @param data - Data to compress
11 * @returns Compressed data as Uint8Array
12 *
13 * @remarks
14 * Uses Node.js zlib with default compression level (6).
15 * Compression is transparent to the user - data is automatically decompressed on retrieval.
16 *
17 * @example
18 * ```typescript
19 * const original = new TextEncoder().encode('Hello, world!');
20 * const compressed = await compress(original);
21 * console.log(`Compressed from ${original.length} to ${compressed.length} bytes`);
22 * ```
23 */
24export async function compress(data: Uint8Array): Promise<Uint8Array> {
25 const buffer = Buffer.from(data);
26 const compressed = await gzipAsync(buffer);
27 return new Uint8Array(compressed);
28}
29
30/**
31 * Decompress gzip-compressed data.
32 *
33 * @param data - Compressed data
34 * @returns Decompressed data as Uint8Array
35 * @throws Error if data is not valid gzip format
36 *
37 * @remarks
38 * Automatically validates gzip magic bytes (0x1f 0x8b) before decompression.
39 *
40 * @example
41 * ```typescript
42 * const decompressed = await decompress(compressedData);
43 * const text = new TextDecoder().decode(decompressed);
44 * ```
45 */
46export async function decompress(data: Uint8Array): Promise<Uint8Array> {
47 // Validate gzip magic bytes
48 if (data.length < 2 || data[0] !== 0x1f || data[1] !== 0x8b) {
49 throw new Error('Invalid gzip data: missing magic bytes');
50 }
51
52 const buffer = Buffer.from(data);
53 const decompressed = await gunzipAsync(buffer);
54 return new Uint8Array(decompressed);
55}
56
57/**
58 * Check if data appears to be gzip-compressed by inspecting magic bytes.
59 *
60 * @param data - Data to check
61 * @returns true if data starts with gzip magic bytes (0x1f 0x8b)
62 *
63 * @remarks
64 * This is a quick check that doesn't decompress the data.
65 * Useful for detecting already-compressed data to avoid double compression.
66 *
67 * @example
68 * ```typescript
69 * if (isGzipped(data)) {
70 * console.log('Already compressed, skipping compression');
71 * } else {
72 * data = await compress(data);
73 * }
74 * ```
75 */
76export function isGzipped(data: Uint8Array): boolean {
77 return data.length >= 2 && data[0] === 0x1f && data[1] === 0x8b;
78}