levelcache/readme.md

# @push.rocks/levelcache
a cache that uses memory/disk/s3 as backup

## Install
To install `@push.rocks/levelcache`, you can use npm or yarn as follows:

```bash
npm install @push.rocks/levelcache --save
```
or
```bash
yarn add @push.rocks/levelcache
```

This will add `@push.rocks/levelcache` to your project's dependencies.

## Usage

`@push.rocks/levelcache` provides a versatile caching solution that leverages memory, disk, and Amazon S3 for data storage, ensuring both speed and durability. By prioritizing data storage based on the size and storage limits you define, it efficiently manages where to store your cache entries.

### Getting Started

First, you need to import `LevelCache` and `CacheEntry` from the package:

```typescript
import { LevelCache, CacheEntry } from '@push.rocks/levelcache';
```

### Initializing a Cache

You initialize a new cache by creating an instance of `LevelCache`. You can specify options such as memory and disk size limits, S3 configurations, and more.

```typescript
const myCache = new LevelCache({
  cacheId: 'myUniqueCacheId', // A unique ID for your cache
  maxMemoryStorageInMB: 10, // Optional - default is 0.5 MB
  maxDiskStorageInMB: 100, // Optional - default is 10 MB
  diskStoragePath: './myCache', // Optional - default uses a '.nogit' directory
  // Specify S3 configurations if you want to use S3 as a storage level
  s3Config: {
    accessKeyId: 'yourAccessKeyId', // Your S3 access key
    secretAccessKey: 'yourSecretAccessKey', // Your S3 secret key
    region: 'us-west-2' // The region your S3 bucket is in
  },
  s3BucketName: 'myBucketName', // The name of your S3 bucket
  immutableCache: true, // Optional - if cache entries should be immutable
  persistentCache: true, // Optional - if cache should persist between restarts
});
```

### Storing and Retrieving Cached Data

To store data, you create a `CacheEntry` and use `storeCacheEntryByKey` method. Retrieving data is done using the `retrieveCacheEntryByKey` method.

```typescript
async function cacheOperations() {
  // Ensure the cache is ready
  await myCache.ready;

  // Create a cache entry
  const myCacheEntry = new CacheEntry({
    ttl: 3600000, // Time-to-live in milliseconds
    contents: Buffer.from('This is some data to cache'), // The data to cache
  });

  // Store the cache entry
  await myCache.storeCacheEntryByKey('myDataKey', myCacheEntry);

  // Retrieve the cache entry
  const retrievedEntry = await myCache.retrieveCacheEntryByKey('myDataKey');
  if(retrievedEntry) {
    console.log(retrievedEntry.contents.toString()); // Logs: This is some data to cache
  }
}

cacheOperations();
```

### Deleting Cache Entries

You can delete entries from the cache using `deleteCacheEntryByKey` method:

```typescript
await myCache.deleteCacheEntryByKey('myDataKey');
```

### Cache Cleanup

The library provides mechanisms to clean outdated entries or flush the entire cache.

```typescript
// Clean outdated cache entries
await myCache.cleanOutdated();

// Clean all cache entries
await myCache.cleanAll();
```

### Advanced Use Cases

For more complex caching requirements, such as custom cache routing or handling larger datasets with varying priorities, you can dive deeper into the library's API to customize your caching strategy. This includes configuring thresholds for when to use each storage level and managing cache immutability and persistence.

For further information and more in-depth examples, you're encouraged to explore the source code and experiment with configuring `LevelCache` to best suit your application's needs.

`@push.rocks/levelcache` blends the speed of in-memory caching with the durability and scalability of disk and S3-based caching, making it a comprehensive solution for your caching needs.

By carefully considering your application's data access patterns, size constraints, and persistence requirements, you can leverage `@push.rocks/levelcache` to significantly improve performance and efficiency.

## License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.