tessl/npm-metro-cache

Cache layers for Metro bundler with multi-layered caching system supporting local file storage and remote HTTP caching

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Utilities

Name: tessl/npm-metro-cache
Author: tessl

Utility functions for cache key generation and error classes for handling cache-specific exceptions. Provides essential support functionality for cache operations.

Capabilities

Hash Generation

Stable hash function for generating consistent cache keys from JavaScript values.

/**
 * Generate stable MD5 hash for cache keys from any JavaScript value
 * Ensures consistent hashing across runs by using canonical JSON serialization
 * @param value - Any JavaScript value to hash (objects, arrays, primitives)
 * @returns MD5 hash as Buffer suitable for use as cache key
 */
function stableHash(value: mixed): Buffer;

Usage Examples:

const { stableHash } = require("metro-cache");

// Hash simple values
const stringKey = stableHash("my-cache-key");
const numberKey = stableHash(42);

// Hash complex objects (order-independent)
const objectKey = stableHash({
  file: "app.js",
  transforms: ["babel", "minify"],
  options: { target: "es5" }
});

// Same object, different property order = same hash
const sameObjectKey = stableHash({
  transforms: ["babel", "minify"],
  options: { target: "es5" },
  file: "app.js"
});

console.log(objectKey.equals(sameObjectKey)); // true

// Hash arrays (order-dependent)
const arrayKey = stableHash(["transform1", "transform2"]);

// Use with Cache
const cache = new Cache([fileStore]);
const key = stableHash({ source: sourceCode, config: babelConfig });
const result = await cache.get(key);

Error Classes

Specialized error classes for different types of cache failures.

HttpError

HTTP-specific error with status code information.

/**
 * HTTP-specific error with status code
 * Thrown by HttpStore for HTTP protocol errors
 */
class HttpError extends Error {
  /**
   * Create HTTP error with message and status code
   * @param message - Error description
   * @param code - HTTP status code (e.g., 404, 500)
   */
  constructor(message: string, code: number);
  
  /**
   * HTTP status code associated with this error
   */
  code: number;
}

Usage Examples:

const { HttpStore } = require("metro-cache");

const httpStore = new HttpStore({ endpoint: "https://cache.example.com" });

try {
  await httpStore.get(key);
} catch (error) {
  if (error instanceof HttpStore.HttpError) {
    switch (error.code) {
      case 404:
        console.log("Cache miss");
        break;
      case 401:
        console.error("Authentication failed");
        break;
      case 500:
        console.error("Server error:", error.message);
        break;
      default:
        console.error(`HTTP ${error.code}: ${error.message}`);
    }
  }
}

NetworkError

Network connectivity error with error code information.

/**
 * Network connectivity error
 * Thrown by HttpStore for network-level issues
 */
class NetworkError extends Error {
  /**
   * Create network error with message and error code
   * @param message - Error description
   * @param code - Network error code (e.g., "ECONNREFUSED", "TIMEOUT")
   */
  constructor(message: string, code: string);
  
  /**
   * Network error code associated with this error
   */
  code: string;
}

Usage Examples:

const { HttpStore } = require("metro-cache");

const httpStore = new HttpStore({ 
  endpoint: "https://cache.example.com",
  timeout: 5000
});

try {
  await httpStore.set(key, value);
} catch (error) {
  if (error instanceof HttpStore.NetworkError) {
    switch (error.code) {
      case "ECONNREFUSED":
        console.error("Cache server is not running");
        break;
      case "ENOTFOUND":
        console.error("Cache server hostname not found");
        break;
      case "TIMEOUT":
        console.error("Request timed out");
        break;
      default:
        console.error(`Network error ${error.code}: ${error.message}`);
    }
  }
}

Hash Algorithm Details

The stableHash function provides deterministic hashing by:

Canonical Serialization: Uses metro-core's canonicalize function to ensure consistent JSON serialization regardless of object property order
MD5 Hashing: Applies MD5 hash algorithm to the canonical JSON string
Buffer Output: Returns hash as Buffer for direct use as cache keys

Error Hierarchy

Error
├── HttpError (HTTP protocol errors)
└── NetworkError (Network connectivity errors)

Both error classes extend the standard JavaScript Error class and add specific error code information for more precise error handling in caching scenarios.

Integration Notes

These utilities integrate seamlessly with the rest of the metro-cache system:

stableHash: Used throughout Metro bundler for generating consistent cache keys
Error Classes: Referenced as static properties on HttpStore for convenient access
Logging: All operations are automatically logged via Metro's Logger system