diff --git a/npmextra.json b/npmextra.json index 488270d..b97cda6 100644 --- a/npmextra.json +++ b/npmextra.json @@ -5,17 +5,30 @@ "githost": "code.foss.global", "gitscope": "push.rocks", "gitrepo": "levelcache", - "description": "a cache that uses memory/disk/s3 as backup", + "description": "A cache that utilizes memory, disk, and S3 for data storage and backup.", "npmPackagename": "@push.rocks/levelcache", "license": "MIT", - "projectDomain": "push.rocks" + "projectDomain": "push.rocks", + "keywords": [ + "caching", + "memory cache", + "disk cache", + "S3 cache", + "data backup", + "multilevel caching", + "performance optimization", + "persistent storage", + "data retrieval", + "node.js", + "typescript" + ] } }, "npmci": { "npmGlobalTools": [], "npmAccessLevel": "public" }, - "tsdocs": { + "tsdoc": { "legal": "\n## License and Legal Information\n\nThis 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. \n\n**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.\n\n### Trademarks\n\nThis 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.\n\n### Company Information\n\nTask Venture Capital GmbH \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy 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.\n" } } \ No newline at end of file diff --git a/package.json b/package.json index d7af32a..6670c29 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "@push.rocks/levelcache", "version": "3.0.8", "private": false, - "description": "a cache that uses memory/disk/s3 as backup", + "description": "A cache that utilizes memory, disk, and S3 for data storage and backup.", "main": "dist_ts/index.js", "typings": "dist_ts/index.d.ts", "type": "module", @@ -50,5 +50,18 @@ ], "browserslist": [ "last 1 chrome versions" + ], + "keywords": [ + "caching", + "memory cache", + "disk cache", + "S3 cache", + "data backup", + "multilevel caching", + "performance optimization", + "persistent storage", + "data retrieval", + "node.js", + "typescript" ] -} +} \ No newline at end of file diff --git a/readme.hints.md b/readme.hints.md new file mode 100644 index 0000000..0519ecb --- /dev/null +++ b/readme.hints.md @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/readme.md b/readme.md index 122e2a9..6c65acd 100644 --- a/readme.md +++ b/readme.md @@ -1,40 +1,126 @@ # @push.rocks/levelcache a cache that uses memory/disk/s3 as backup -## Availabililty and Links -* [npmjs.org (npm package)](https://www.npmjs.com/package/@push.rocks/levelcache) -* [gitlab.com (source)](https://gitlab.com/push.rocks/levelcache) -* [github.com (source mirror)](https://github.com/push.rocks/levelcache) -* [docs (typedoc)](https://push.rocks.gitlab.io/levelcache/) +## Install +To install `@push.rocks/levelcache`, you can use npm or yarn as follows: -## Status for master +```bash +npm install @push.rocks/levelcache --save +``` +or +```bash +yarn add @push.rocks/levelcache +``` -Status Category | Status Badge --- | -- -GitLab Pipelines | [![pipeline status](https://gitlab.com/push.rocks/levelcache/badges/master/pipeline.svg)](https://lossless.cloud) -GitLab Pipline Test Coverage | [![coverage report](https://gitlab.com/push.rocks/levelcache/badges/master/coverage.svg)](https://lossless.cloud) -npm | [![npm downloads per month](https://badgen.net/npm/dy/@push.rocks/levelcache)](https://lossless.cloud) -Snyk | [![Known Vulnerabilities](https://badgen.net/snyk/push.rocks/levelcache)](https://lossless.cloud) -TypeScript Support | [![TypeScript](https://badgen.net/badge/TypeScript/>=%203.x/blue?icon=typescript)](https://lossless.cloud) -node Support | [![node](https://img.shields.io/badge/node->=%2010.x.x-blue.svg)](https://nodejs.org/dist/latest-v10.x/docs/api/) -Code Style | [![Code Style](https://badgen.net/badge/style/prettier/purple)](https://lossless.cloud) -PackagePhobia (total standalone install weight) | [![PackagePhobia](https://badgen.net/packagephobia/install/@push.rocks/levelcache)](https://lossless.cloud) -PackagePhobia (package size on registry) | [![PackagePhobia](https://badgen.net/packagephobia/publish/@push.rocks/levelcache)](https://lossless.cloud) -BundlePhobia (total size when bundled) | [![BundlePhobia](https://badgen.net/bundlephobia/minzip/@push.rocks/levelcache)](https://lossless.cloud) +This will add `@push.rocks/levelcache` to your project's dependencies. ## Usage -@pushrocks/levelcache implements an efficient way to cache larger amounts of data ind a multilevel approach. -smaller and prioritized data is safed in memory. +`@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. -Use TypeScript for best in class intellisense. +### Getting Started -## Contribution +First, you need to import `LevelCache` and `CacheEntry` from the package: -We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :) +```typescript +import { LevelCache, CacheEntry } from '@push.rocks/levelcache'; +``` -For further information read the linked docs at the top of this readme. +### Initializing a Cache -## Legal -> MIT licensed | **©** [Task Venture Capital GmbH](https://task.vc) -| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy) +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.