@polymer-labs/crystal-cache

Global package caching system with Crystal Cache architecture for Gel package manager.

Installation

npm install @polymer-labs/crystal-cache

Usage

const CrystalCache = require('@polymer-labs/crystal-cache');

// Initialize cache
const cache = new CrystalCache();

// Store a package
await cache.store('react', '18.2.0', '/path/to/react-18.2.0.tar.gz');

// Check if package exists
const exists = cache.has('react', '18.2.0');

// Get package path
const pkgPath = cache.get('react', '18.2.0');

// Link package to project
await cache.link('react', '18.2.0', '/project/node_modules/react');

// Get cache statistics
const stats = cache.getStats();
console.log(`Packages: ${stats.totalPackages}`);
console.log(`Size: ${stats.totalSize}`);
console.log(`Saved: ${stats.spaceSaved}`);

Features

• 🔮 Global Deduplication - Store packages once, use everywhere
• 🔗 Symlink Management - Efficient package linking
• 💾 Space Efficient - Reduces disk usage significantly
• ⚡ Fast Access - Quick package retrieval
• 🔒 Integrity Checks - Hash-based verification
• 📊 Usage Statistics - Track cache efficiency

Architecture

The Crystal Cache uses a centralized storage model:

~/.gel/crystal-cache/
├── packages/
│   ├── [email protected]/
│   ├── [email protected]/
│   └── [email protected]/
└── metadata.json

How It Works

1. Storage: Packages are extracted once to global cache
2. Linking: Projects receive symlinks to cached packages
3. Deduplication: Same package version shared across projects
4. Integrity: SHA-256 hashing ensures package authenticity

API

Constructor

const cache = new CrystalCache(options);

Options:

• cacheDir (string) - Custom cache directory (default: ~/.gel/crystal-cache)

Methods

store(name, version, tarballPath)

Store a package tarball in cache.

has(name, version)

Check if package exists in cache.

get(name, version)

Get path to cached package.

link(name, version, targetPath)

Create symlink from cache to project.

remove(name, version)

Remove package from cache.

clear()

Clear entire cache.

getStats()

Get cache statistics.

list()

List all cached packages.

Performance

Typical performance improvements:

• Installation Speed: 3-5x faster on repeated installs
• Disk Space: 60-80% reduction across multiple projects
• Network Usage: Eliminates redundant package downloads

Cache Location

Default: ~/.gel/crystal-cache

Override with environment variable:

export GEL_CACHE_DIR=/custom/path

Maintenance

// Clean old versions
cache.prune({ keepLatest: 2 });

// Verify integrity
const results = await cache.verify();

// Rebuild metadata
await cache.rebuild();

License

MIT © Polymer Labs