CtrlK
BlogDocsLog inGet started
Tessl Logo

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

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

File System Cache

File System Cache is a high-performance, promise-based caching library that provides persistent data storage using the local file system. It offers both asynchronous and synchronous operations with advanced features including TTL (time-to-live) expiration, namespace-based isolation, multiple hashing algorithms, and automatic JSON serialization.

Package Information

  • Package Name: file-system-cache
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install file-system-cache

Core Imports

import Cache from "file-system-cache";

Alternative named imports:

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

Basic Usage

import Cache from "file-system-cache";

// Create cache instance with configuration
const cache = Cache({
  basePath: "./.cache",      // Cache directory
  ns: "my-app",             // Namespace for isolation
  ttl: 3600,                // 1 hour TTL in seconds
  hash: "sha1",             // Hashing algorithm
  extension: "json"         // File extension
});

// Store and retrieve data
await cache.set("user:123", { name: "Alice", age: 30 });
const user = await cache.get("user:123");

// Synchronous operations
cache.setSync("config", { theme: "dark" });
const config = cache.getSync("config");

// Batch operations  
await cache.save([
  { key: "item1", value: "data1" },
  { key: "item2", value: "data2" }
]);

const allFiles = await cache.load();

Architecture

File System Cache is built around several key components:

  • Default Factory Function: Creates cache instances with optional configuration
  • FileSystemCache Class: Main cache implementation with full async/sync API
  • Configuration System: Flexible options for paths, namespaces, TTL, and hashing
  • Path Management: Automatic file path generation with namespace support
  • JSON Serialization: Automatic handling of complex data types with metadata
  • TTL System: Time-based expiration with automatic cleanup of expired items

Capabilities

Cache Instance Creation

Factory function and class constructor for creating cache instances with flexible configuration options.

export default function(options?: FileSystemCacheOptions): FileSystemCache;

interface FileSystemCacheOptions {
  basePath?: string;    // Base directory for cache files (default: "./.cache")
  ns?: any;            // Namespace for cache isolation  
  ttl?: number;        // Default TTL in seconds (default: 0 = no expiration)
  hash?: HashAlgorithm; // Hashing algorithm (default: "sha1")
  extension?: string;   // File extension for cache files
}

Cache Configuration

Data Storage and Retrieval

Core caching operations for storing and retrieving data with both asynchronous and synchronous methods.

// Asynchronous operations
get(key: string, defaultValue?: any): Promise<any>;
set(key: string, value: any, ttl?: number): Promise<{path: string}>;
remove(key: string): Promise<void>;

// Synchronous operations  
getSync(key: string, defaultValue?: any): any;
setSync(key: string, value: any, ttl?: number): FileSystemCache;

Data Operations

Cache Management

Operations for managing cache state including clearing all items and checking file existence.

clear(): Promise<void>;
fileExists(key: string): Promise<boolean>;
path(key: string): string;
ensureBasePath(): Promise<void>;

Cache Management

Batch Operations

Efficient operations for handling multiple cache items simultaneously.

save(items: ({key: string, value: any} | null | undefined)[]): Promise<{paths: string[]}>;
load(): Promise<{files: {path: string, value: any}[]}>;

Batch Operations

Types

class FileSystemCache {
  // Static properties
  static hashAlgorithms: HashAlgorithm[];
  
  // Instance properties
  readonly basePath: string;
  readonly ns?: any;
  readonly extension?: string;
  readonly hash: HashAlgorithm;
  readonly ttl: number;
  basePathExists?: boolean;
  
  constructor(options?: FileSystemCacheOptions);
}

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"
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/file-system-cache@3.0.x
Publish Source
CLI
Badge
tessl/npm-file-system-cache badge