or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

batch-operations.mdcache-configuration.mdcache-management.mddata-operations.mdindex.md
tile.json

tessl/npm-file-system-cache

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/file-system-cache@3.0.x

To install, run

npx @tessl/cli install tessl/npm-file-system-cache@3.0.0

index.mddocs/

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"