pixl-server-storage

4.1.0 verified Mon Apr 27 auth: no javascript

A key/value/list storage component for the pixl-server framework, providing multiple back-end engines including local filesystem, Amazon S3, Redis, SQLite, and hybrid. Version 4.1.0 is current, with regular updates. It introduces chunked linked lists for fast list operations, hash tables with key iteration, transaction system for atomic commits/rollbacks, advisory locking, and full-text search indexing. Designed for simplicity and low memory usage, it stands out by supporting multiple storage back-ends with consistent API and built-in maintenance features like auto-expiration and compaction.

Common errors

error Error: ENOENT: no such file or directory, open '/path/to/file' ↓

cause The filesystem engine cannot find or create the specified path. Path must be writable and exist (or engine_path directory must exist).

fix

Ensure 'engine_path' directory exists and is writable. Use an absolute path.

error TypeError: storage.put is not a function ↓

cause Used CommonJS require or incorrect import. The module is ESM-only.

fix

Use ESM import syntax: import { StorageComponent } from 'pixl-server-storage'.

error Error: Invalid engine type: 'mysql' ↓

cause Unsupported engine type provided in configuration. Engines: 'filesystem', 's3', 'redis', 'sqlite', 'hybrid'.

fix

Set 'engine' to one of the valid options or implement a custom engine plugin.

error Error: Redis connection error: connect ECONNREFUSED 127.0.0.1:6379 ↓

cause Redis server is not running or not accessible at the configured host/port.

fix

Start Redis server or configure 'engine_opts' with correct host/port.

Warnings

breaking Version 4.x drops support for Node.js < 12. Ensure you are on Node.js 12 or later. ↓

fix Upgrade Node.js to 12+ or stay on pixl-server-storage@3.x.

deprecated The 'lower_case_keys' configuration option is deprecated and will be removed in version 5.0. ↓

fix Manually normalize keys before passing to API.

gotcha Default engine is 'filesystem', which requires an absolute path for 'engine_path'. Relative paths may cause data loss. ↓

fix Always provide an absolute path for 'engine_path' when using filesystem engine.

breaking Redis engine used to support 'redis' package v2, but version 4.x requires 'redis' v4 or above. ↓

fix Update 'redis' dependency to ^4.0.0 and adjust connection options accordingly.

gotcha When using Amazon S3 engine, the 'aws-sdk' v3 is not supported; only v2 is compatible. ↓

fix Install 'aws-sdk' v2 (e.g., 'npm install aws-sdk@2') and configure region/credentials.

Install

npm install pixl-server-storage

yarn add pixl-server-storage

pnpm add pixl-server-storage

Imports

StorageComponent

wrong

const StorageComponent = require('pixl-server-storage')

correct

import { StorageComponent } from 'pixl-server-storage'

ESM module; CommonJS require is not supported.

pixl-server-storage

wrong

import * as pixlServerStorage from 'pixl-server-storage'

correct

import pixlServerStorage from 'pixl-server-storage'

Default export is the StorageComponent class.

StorageComponent type
```
import { StorageComponent } from 'pixl-server-storage'
```
For TypeScript, use named import for type.

Quickstart

Initializes the storage component with filesystem engine, stores and fetches a JSON record asynchronously.

import { StorageComponent } from 'pixl-server-storage';

const storage = new StorageComponent({
  engine: 'filesystem',
  engine_path: '/tmp/storage',
  debug: true
}, (err) => {
  if (err) throw err;
  console.log('Storage initialized');
});

// Store a record
storage.put('user:123', { name: 'Alice', email: 'alice@example.com' }, (err) => {
  if (err) throw err;
  console.log('Record stored');
});

// Fetch a record
storage.get('user:123', (err, data) => {
  if (err) throw err;
  console.log('Fetched:', data);
});