tessl/npm-file-system-cache

A super-fast, promise-based cache that reads and writes to the file-system

—

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

Cache Configuration

Name: tessl/npm-file-system-cache
Author: tessl

Comprehensive configuration options for creating and customizing file system cache instances.

Capabilities

Default Factory Function

Creates a new FileSystemCache instance with optional configuration.

/**
 * Default entry function that creates a FileSystemCache instance
 * @param options - Optional configuration for the cache instance
 * @returns New FileSystemCache instance
 */
export default function(options?: FileSystemCacheOptions): FileSystemCache;

Usage Examples:

import Cache from "file-system-cache";

// Default configuration
const cache = Cache();

// Custom configuration
const cache = Cache({
  basePath: "./my-cache",
  ns: "user-data",
  ttl: 3600,
  hash: "sha256",
  extension: "cache"
});

FileSystemCache Constructor

Direct class constructor for creating cache instances.

/**
 * Creates a new FileSystemCache instance
 * @param options - Configuration options
 */
constructor(options?: FileSystemCacheOptions);

Usage Examples:

import { FileSystemCache } from "file-system-cache";

const cache = new FileSystemCache({
  basePath: "/tmp/cache",
  ns: ["app", "v1", "users"],
  ttl: 1800
});

Configuration Options

Complete configuration interface for cache instances.

interface FileSystemCacheOptions {
  /** 
   * Base directory path for storing cache files
   * @default "./.cache"
   */
  basePath?: string;
  
  /** 
   * Namespace for cache isolation - can be any value or array
   * Used to prevent key collisions between different cache instances
   */
  ns?: any;
  
  /** 
   * Default time-to-live for cached items in seconds
   * @default 0 (never expires)
   */
  ttl?: number;
  
  /** 
   * Hashing algorithm for generating cache keys
   * @default "sha1"
   */
  hash?: HashAlgorithm;
  
  /** 
   * File extension for cache files (without leading dot)
   * @default undefined (no extension)
   */
  extension?: string;
}

Hash Algorithms

All supported hashing algorithms for cache key generation.

type HashAlgorithm =
  | "RSA-MD5"
  | "RSA-RIPEMD160"
  | "RSA-SHA1"
  | "RSA-SHA1-2"
  | "RSA-SHA224"
  | "RSA-SHA256"
  | "RSA-SHA3-224"
  | "RSA-SHA3-256"
  | "RSA-SHA3-384"
  | "RSA-SHA3-512"
  | "RSA-SHA384"
  | "RSA-SHA512"
  | "RSA-SHA512/224"
  | "RSA-SHA512/256"
  | "RSA-SM3"
  | "blake2b512"
  | "blake2s256"
  | "id-rsassa-pkcs1-v1_5-with-sha3-224"
  | "id-rsassa-pkcs1-v1_5-with-sha3-256"
  | "id-rsassa-pkcs1-v1_5-with-sha3-384"
  | "id-rsassa-pkcs1-v1_5-with-sha3-512"
  | "md5"
  | "md5-sha1"
  | "md5WithRSAEncryption"
  | "ripemd"
  | "ripemd160"
  | "ripemd160WithRSA"
  | "rmd160"
  | "sha1"
  | "sha1WithRSAEncryption"
  | "sha224"
  | "sha224WithRSAEncryption"
  | "sha256"
  | "sha256WithRSAEncryption"
  | "sha3-224"
  | "sha3-256"
  | "sha3-384"
  | "sha3-512"
  | "sha384"
  | "sha384WithRSAEncryption"
  | "sha512"
  | "sha512-224"
  | "sha512-224WithRSAEncryption"
  | "sha512-256"
  | "sha512-256WithRSAEncryption"
  | "sha512WithRSAEncryption"
  | "shake128"
  | "shake256"
  | "sm3"
  | "sm3WithRSAEncryption"
  | "ssl3-md5"
  | "ssl3-sha1";

Static Hash Algorithms List

Access to all available hash algorithms at runtime.

/**
 * Static property containing all supported hash algorithms
 */
static hashAlgorithms: HashAlgorithm[];

Usage Example:

import { FileSystemCache } from "file-system-cache";

// Get all available algorithms
const availableAlgorithms = FileSystemCache.hashAlgorithms;
console.log(`${availableAlgorithms.length} algorithms available`);

// Check if algorithm is supported
const isSupported = FileSystemCache.hashAlgorithms.includes("sha256");

Configuration Examples

Basic Configuration

// Minimal setup
const cache = Cache();

// With custom directory
const cache = Cache({ basePath: "./cache" });

Namespace Configuration

// String namespace
const userCache = Cache({ ns: "users" });
const productCache = Cache({ ns: "products" });

// Array namespace for hierarchical organization
const cache = Cache({ ns: ["api", "v2", "responses"] });

// Object namespace
const cache = Cache({ ns: { app: "myapp", env: "prod" } });

TTL Configuration

// 1 hour TTL
const cache = Cache({ ttl: 3600 });

// 30 minutes TTL
const cache = Cache({ ttl: 1800 });

// Per-operation TTL override
await cache.set("temp-data", value, 300); // 5 minutes

Security Configuration

// High-security hashing
const cache = Cache({ hash: "sha512" });

// Fast hashing for performance
const cache = Cache({ hash: "md5" });

docs

batch-operations.md

cache-configuration.md

tessl/npm-file-system-cache