https://github.com/knfs-library/bamimi-cache
A lightweight, file-based caching library designed for Node.js applications. It provides flexible caching with optional compression, expiration handling, and keyword search capabilities. The library is easy to use and integrates seamlessly into modern applications
https://github.com/knfs-library/bamimi-cache
bamimi cache cache-control cache-storage framework nodejs
Last synced: 8 months ago
JSON representation
A lightweight, file-based caching library designed for Node.js applications. It provides flexible caching with optional compression, expiration handling, and keyword search capabilities. The library is easy to use and integrates seamlessly into modern applications
- Host: GitHub
- URL: https://github.com/knfs-library/bamimi-cache
- Owner: knfs-library
- License: mit
- Created: 2025-01-13T07:04:36.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-04-17T18:41:24.000Z (11 months ago)
- Last Synced: 2025-06-19T00:51:48.073Z (8 months ago)
- Topics: bamimi, cache, cache-control, cache-storage, framework, nodejs
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/@knfs-tech/bamimi-cache
- Size: 103 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# About **BAMIMI Cache**
**BAMIMI Cache** is a lightweight, file-based caching library designed for Node.js applications. It provides flexible caching with optional compression, expiration handling, and keyword search capabilities. The library is easy to use and integrates seamlessly into modern applications.
---
## Installation
Install BAMIMI Cache via **npm** or **yarn**:
```bash
npm i @knfs-tech/bamimi-cache
# OR
yarn add @knfs-tech/bamimi-cache
```
---
## Features
- **File-based Caching**: Store data directly on the file system for fast and efficient access.
- **Compression**: Reduce file sizes with Snappy compression.
- **Expiration Handling**: Automatically delete cached entries after a specified duration.
- **Keyword Search**: Search through cached entries using keywords with `AND`/`OR` logic.
- **Logging**: Enable optional logging for debugging and monitoring.
- **Flexible Configuration**: Set up default settings for expiration, compression, and cache directory.
---
## Basic Usage
### Example
```javascript
const CacheFile = require('@knfs-tech/bamimi-cache');
// Initialize the cache system
const cache = new CacheFile({
folder: './my-cache', // Custom cache folder
autoCompress: true, // Automatically compress data
log: true, // Enable logging
});
cache.setup()
// Store data in the cache
await cache.set('user:123', JSON.stringify({ name: 'John Doe' }), { expire: 60000 });
// Retrieve data from the cache
const userData = await cache.get('user:123');
console.log(JSON.parse(userData));
// Check if a key exists
const exists = await cache.exist('user:123');
console.log(exists ? 'Key exists' : 'Key does not exist');
// Delete a cache entry
await cache.del('user:123');
```
---
## API Reference
### **Constructor**
#### `new CacheFile(config)`
Creates a new instance of BAMIMI Cache.
| Parameter | Type | Default | Description | Support Version |
| --------------------- | ------- | ------------------------ | ------------------------------------------- |-------------|
| `config.folder` | String | `projectPath + /cache` | Directory to store cached files. | >= 1.0.2
| `config.expire` | Number | `0` | Default expiration time in milliseconds, (0 is not expire) | >= 1.0.2 |
| `config.autoCompress` | Boolean | `false` | Enable auto-compression for cached content. | >= 1.0.2 |
| `config.log` | Boolean | `false` | Enable or disable logging. | >= 1.0.2 |
| `config.peakDuration` | Number | `3000` | Allows peak time to use cache to store the results returned when getting, to increase query speed. If peakDuration is 0, it means it is not used. | >= 1.1.3 |
| `config.maxSize` | Number | `0` | Default max size of cache content in bytes, (0 is not verify). | >= 1.2.9 |
| `config.logHandle` | Number | use `console.log` | Function handle log | >= 1.3.0 (Latest) |
| `config.errorHandle` | Number | use `throw new Error` | Function handle error. | >= 1.3.0 |
---
### **Methods**
#### **`setup()`**
Initialize configuration files
#### **`set(key, content, options)`**
Stores data in the cache.
| Parameter | Type | Description |
| ------------------ | ------------- | ----------------------------------------- |
| `key` | String | Unique identifier for the cache entry. |
| `content` | String | Content to cache. |
| `options.compress` | Boolean | Enable compression for this entry. |
| `options.expire` | Number | Expiration time in milliseconds. |
| `options.search` | Array | Keywords to enable search for this entry. |
---
#### **`get(key)`**
Retrieves cached content by its key.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| `key` | String | Unique identifier for the cache. |
**Returns:** `Promise` - Cached content.
---
#### **`exist(key)`**
Checks if a key exists in the cache.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| `key` | String | Unique identifier for the cache. |
**Returns:** `Boolean` - `true` if the key exists, otherwise `false`.
---
#### **`del(key)`**
Deletes a cached entry by its key.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| `key` | String | Unique identifier for the cache. |
---
#### **`search(keywords, logic)`**
Searches for cached entries based on keywords.
| Parameter | Type | Default | Description |
| ---------- | ------------------- | ------- | --------------------------------- |
| `keywords` | Array | `[]` | Keywords to search for. |
| `logic` | String (`AND`/`OR`) | `AND` | Logic to apply during the search. |
**Returns:** `Array` - Matching cache keys.
---
#### **`publish(key, message)`** (>= 1.5.1)
Publish event
| Parameter | Type | Default | Description |
| ---------- | ------------------- | ------- | --------------------------------- |
| `key` | String | | Key or event. |
| `message` | any | | Message publish to event. |
---
#### **`subscribe(key, listener)`** (>= 1.5.1)
Subscribe event
| Parameter | Type | Default | Description |
| ---------- | ------------------- | ------- | --------------------------------- |
| `key` | String | | Key or event. |
| `logic` | function(message) | | Listen event publish. |
*Ex:*
```javascript
const storage = new CacheFile(configDefault)
storage.setup()
storage.subscribe("event-1", async (message) => {
console.log("listener 1", message)
})
storage.publish("event-1", contentNumber)
```
---
### Configuration Example
To customize the cache configuration:
```javascript
const cache = new CacheFile({
folder: './cache-directory',
expire: 60000, // Default expiration time: 60 seconds
autoCompress: true, // Enable automatic compression
log: true, // Enable logging
});
```
---
## Advanced Features
### **Compression**
Uses [Snappy](https://github.com/google/snappy) for fast and lightweight compression. To enable compression:
```javascript
await cache.set('key', 'content', { compress: true });
```
### **Expiration Handling**
Automatically removes expired entries:
```javascript
await cache.set('tempKey', 'tempData', { expire: 5000 }); // Expires in 5 seconds
```
---
## Contributions
We welcome contributions! Please create a pull request or submit issues on GitHub.
---
## License
**BAMIMI Cache** is open-source software licensed under the [MIT License](LICENSE).