random-access-layered-storage - npm Package Compare versions

Comparing version 1.0.0 to 1.0.1

lib/random-access-layered-storage.js

@@ -22,2 +22,3 @@ import RAS from 'random-access-storage';
         this._flushOnClose = opts.flushOnClose !== undefined ? opts.flushOnClose : true;
+        this._autoFlushOnEvict = opts.autoFlushOnEvict !== undefined ? opts.autoFlushOnEvict : true;
         this._opts = opts;
@@ -789,3 +790,3 @@
 
-        if (page.modified && this._opts.autoFlushOnEvict) {
+        if (page.modified && this._autoFlushOnEvict) {
             // Flush page before eviction if it was modified and autoFlushOnEvict is set
@@ -792,0 +793,0 @@ this.flush(pageIndex * this.pageSize, this.pageSize, (err) => {

package.json

 {
   "name": "random-access-layered-storage",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A flexible, layered storage solution building on the random-access-storage interface. Provides an in-memory overlay with configurable eviction, paging, and strict size enforcement options, designed for complex data management scenarios.",
@@ -5,0 +5,0 @@ "type": "module",

readme.md

@@ -56,2 +56,96 @@ # RandomAccessLayeredStorage
 
+---
+
+## Constructor: `RandomAccessLayeredStorage`
+
+The `RandomAccessLayeredStorage` class provides an in-memory overlay for random-access storage (such as `RAM`, `RAF`, etc.), allowing for efficient caching, eviction, and flushing of data to underlying storage.
+
+### Usage
+
+```js
+const RAS = require('random-access-storage');
+const RandomAccessLayeredStorage = require('./path-to-your-layered-storage');
+
+const underlyingStorage = new RAM(); // or RAF, IndexedDB, etc.
+const layeredStorage = new RandomAccessLayeredStorage(underlyingStorage, {
+    pageSize: 1024 * 1024,   // 1MB page size
+    maxPages: 100,           // Max pages in memory
+    createIfMissing: true,   // Create file if it does not exist
+    strictSizeEnforcement: 1024 * 1024 * 10, // 10MB strict size limit
+    flushOnClose: true,      // Automatically flush on close
+    autoFlushOnEvict: true   // Automatically flush evicted pages
+});
+```
+
+### Constructor Parameters
+
+#### `underlyingStorage`
+- **Type:** `RandomAccessStorage` interface (e.g., `RAM`, `RAF`)
+- **Description:** The underlying storage to be used by the `RandomAccessLayeredStorage` instance.
+
+#### `opts`
+- **Type:** `Object`
+- **Description:** Configuration options for the layered storage.
+
+### Available Options
+
+#### `pageSize`
+- **Type:** `number`
+- **Default:** `1024 * 1024` (1MB)
+- **Description:** The size (in bytes) of each page in memory. The storage works by loading and storing data in pages, where each page is cached in memory.
+
+#### `maxPages`
+- **Type:** `number`
+- **Default:** `100`
+- **Description:** The maximum number of pages to store in memory. Once this limit is reached, the least recently used (LRU) pages are evicted. If `autoFlushOnEvict` is enabled, modified pages will be flushed to the underlying storage before being evicted.
+
+#### `createIfMissing`
+- **Type:** `boolean`
+- **Default:** `true`
+- **Description:** If set to `true`, the underlying storage will be created if it doesn’t already exist. This is useful when dealing with new storage files.
+
+#### `strictSizeEnforcement`
+- **Type:** `number`
+- **Default:** `undefined`
+- **Description:** If provided, this enforces a maximum size limit (in bytes) for the storage. Any attempts to read or write beyond this size will result in an error.
+
+#### `flushOnClose`
+- **Type:** `boolean`
+- **Default:** `true`
+- **Description:** If set to `true`, the storage will automatically flush all modified pages to the underlying storage when it is closed.
+
+#### `autoFlushOnEvict`
+- **Type:** `boolean`
+- **Default:** `true`
+- **Description:** If set to `true`, pages evicted from memory due to LRU constraints will be automatically flushed to the underlying storage if they were modified.
+
+---
+
+### Example
+
+```js
+const ram = new RAM();
+const layeredStorage = new RandomAccessLayeredStorage(ram, {
+    pageSize: 1024,          // 1KB page size
+    maxPages: 50,            // Store up to 50 pages in memory
+    createIfMissing: true,   // Create if missing
+    strictSizeEnforcement: 1024 * 1024 * 5, // Enforce 5MB size limit
+    flushOnClose: true,      // Flush data when storage is closed
+    autoFlushOnEvict: true   // Flush pages when evicted from memory
+});
+
+layeredStorage.write(0, Buffer.from('Hello, world!'), err => {
+    if (err) throw err;
+    
+    layeredStorage.flush(0, 13, err => {
+        if (err) throw err;
+        console.log('Data flushed to underlying storage.');
+    });
+});
+```
+
+### Notes
+- The `RandomAccessLayeredStorage` class extends the `random-access-storage` interface, so it supports the standard methods like `write`, `read`, `del`, `truncate`, `flush`, and `close`.
+- Evictions are handled via the internal Least Recently Used (LRU) cache mechanism. Pages can be manually pinned or evicted as needed.
+
 ## Public Methods
@@ -58,0 +152,0 @@

No alert changes

Improved metrics

Total package byte prevSize

74476

increased by5.46%

Lines of code

1377

increased by0.07%

Number of lines in readme file

285

increased by49.21%

No dependency changes