🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
Sign In

fs-key-value

Package Overview
Dependencies
Maintainers
1
Versions
5
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

fs-key-value - npm Package Compare versions

Comparing version
1.0.0
 to
1.2.0
+21
LICENSE
MIT License
Copyright (c) 2013-present Andrew Shell
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
+181
README.md
# fs-key-value
[![npm version](https://img.shields.io/npm/v/fs-key-value.svg)](https://www.npmjs.com/package/fs-key-value)
[![CI](https://github.com/andrewshell/node-fs-key-value/actions/workflows/ci.yml/badge.svg)](https://github.com/andrewshell/node-fs-key-value/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
A simple key-value data store using only the filesystem. Uses POSIX file locking for safe operation in multi-process environments without the overhead of a separate database server.
## Features
- Simple key-value API (`get`, `put`, `delete`)
- Both callback and async/await interfaces
- File-based storage (values stored as JSON)
- POSIX file locking for safe concurrent access
- Works across multiple processes (via cluster, child_process, etc.)
- No external database required
## Requirements
- Node.js >= 18.0.0
- POSIX-compliant filesystem (Linux, macOS, etc.)
## Installation
```bash
npm install fs-key-value
```
## Quick Start
### Using async/await
```js
const FsKeyValue = require('fs-key-value');
const db = new FsKeyValue();
await db.openAsync('./mydb');
// Store a value
await db.putAsync('user:1', { name: 'Alice', age: 30 });
// Retrieve the value
const data = await db.getAsync('user:1');
console.log(data); // { name: 'Alice', age: 30 }
// Delete the value
await db.deleteAsync('user:1');
```
### Using callbacks
```js
var FsKeyValue = require('fs-key-value');
var db = new FsKeyValue('./mydb', function (err, db) {
if (err) throw err;
// Store a value
db.put('user:1', { name: 'Alice', age: 30 }, function (err) {
if (err) throw err;
// Retrieve the value
db.get('user:1', function (err, data) {
if (err) throw err;
console.log(data); // { name: 'Alice', age: 30 }
// Delete the value
db.delete('user:1', function (err) {
if (err) throw err;
console.log('Deleted!');
});
});
});
});
```
## API
### `new FsKeyValue([directory], [callback])`
Creates a new key-value store instance.
- `directory` (string, optional): Path to the storage directory
- `callback` (function, optional): Called with `(err, db)` when initialization completes
### `db.open(directory, callback)`
Initialize or reinitialize the store with a directory. Creates the directory if it doesn't exist.
- `directory` (string): Path to the storage directory
- `callback` (function): Called with `(err, db)` when complete
### `db.get(key, callback)`
Retrieve a value by key.
- `key` (string): The key to retrieve
- `callback` (function): Called with `(err, value)`. Value is `undefined` if key doesn't exist.
### `db.put(key, value, callback)`
Store a value. The value is serialized to JSON.
- `key` (string): The key to store
- `value` (any): Any JSON-serializable value
- `callback` (function): Called with `(err)` when complete
### `db.delete(key, callback)`
Delete a key from the store.
- `key` (string): The key to delete
- `callback` (function): Called with `(err)` when complete
### Async Methods
All methods are also available as async/Promise versions:
- `db.openAsync(directory)` → `Promise<void>`
- `db.getAsync(key)` → `Promise<value | undefined>`
- `db.putAsync(key, value)` → `Promise<void>`
- `db.deleteAsync(key)` → `Promise<void>`
## Multi-Process Example
This example demonstrates safe concurrent access from multiple worker processes:
```js
var cluster = require('cluster');
var FsKeyValue = require('fs-key-value');
if (cluster.isMaster) {
// Fork 8 worker processes
for (var i = 0; i < 8; i++) {
cluster.fork();
}
} else {
var id = cluster.worker.id % 2;
var mydb = new FsKeyValue('./mydb', function (err, db) {
if (err) {
return console.log(err);
}
db.put(
'hoopla' + id,
{ msg: 'ballyhoo ' + cluster.worker.id },
function (err) {
if (err) {
return console.log(cluster.worker.id + ' err ' + err);
}
db.get('hoopla' + id, function (err, data) {
if (err) {
return console.log(cluster.worker.id + ' err ' + err);
}
if (data != undefined) {
console.log(data.msg);
}
db.delete('hoopla' + id);
cluster.worker.kill();
});
}
);
});
}
```
## How It Works
- Each key is stored as a separate file in the specified directory
- Values are serialized as JSON
- Uses `fs-ext` for POSIX file locking (`flock`)
- Shared locks for reads, exclusive locks for writes
- Directory-level lock file (`.lock`) coordinates operations
## License
MIT
+292
-182
fs-key-value.js

@@ -1,226 +0,336 @@

var fs = require('fs-ext'),
path = require('path'),
util = require('util'),
Step = require('step')
'use strict';
function FsKeyValue (directory, callback) {
this.open(directory, callback)
const fs = require('fs');
const fsp = require('fs/promises');
const fsExt = require('fs-ext');
const path = require('path');
const { promisify } = require('util');
const flock = promisify(fsExt.flock);
/**
* @callback ErrorCallback
* @param {Error|null} err - Error if one occurred
*/
/**
* @callback GetCallback
* @param {Error|null} err - Error if one occurred
* @param {*} [value] - The retrieved value, or undefined if key doesn't exist
*/
/**
* @callback OpenCallback
* @param {Error|null} err - Error if one occurred
* @param {FsKeyValue} [instance] - The initialized FsKeyValue instance
*/
/**
* Filesystem-based key-value store with file locking.
*
* Stores values as JSON files in a directory, using POSIX file locks
* for safe concurrent access.
*
* @constructor
* @param {string} [directory] - Path to storage directory
* @param {OpenCallback} [callback] - Called when initialization completes
*
* @example
* var FsKeyValue = require('fs-key-value');
* var store = new FsKeyValue('/tmp/mydb', function(err, db) {
* if (err) throw err;
* db.put('mykey', { foo: 'bar' }, function(err) {
* if (err) throw err;
* console.log('Value stored');
* });
* });
*/
function FsKeyValue(directory, callback) {
if (directory) {
this.open(directory, callback);
}
}
/**
* The storage directory path.
* @type {string}
*/
FsKeyValue.prototype.directory = undefined;
/**
* Path to the directory lock file.
* @type {string}
*/
FsKeyValue.prototype.directoryLock = undefined;
/**
* Initialize the store with a directory.
*
* Creates the directory if it doesn't exist.
*
* @param {string} directory - Path to storage directory
* @param {OpenCallback} [callback] - Called when initialization completes
*/
FsKeyValue.prototype.open = function (directory, callback) {
var self = this
if (typeof callback !== 'function') {
callback = function (err) {
if (err) {
throw err;
}
};
}
if (typeof callback != 'function') {
var callback = function (err) {
this.openAsync(directory)
.then(() => callback(null, this))
.catch((err) => callback(err));
};
/**
* Initialize the store with a directory (async version).
*
* Creates the directory if it doesn't exist.
*
* @param {string} directory - Path to storage directory
* @returns {Promise<void>}
*/
FsKeyValue.prototype.openAsync = async function (directory) {
const exists = fs.existsSync(directory);
if (!exists) {
await fsp.mkdir(directory, { mode: 0o777 });
}
this.directory = directory;
this.directoryLock = path.join(directory, '.lock');
};
/**
* Retrieve a value by key.
*
* Uses a shared lock on the key file for safe concurrent reads.
*
* @param {string} key - The key to retrieve
* @param {GetCallback} [callback] - Called with the value or undefined if not found
*/
FsKeyValue.prototype.get = function (key, callback) {
if (typeof callback !== 'function') {
callback = function (err) {
if (err) {
throw err
throw err;
}
}
};
}
Step(
function initialize () {
fs.exists(directory, this)
},
function makeDirectoryIfNotExists (exists) {
if (exists) {
return this()
this.getAsync(key)
.then((value) => {
if (value === undefined) {
// Preserve original behavior: callback() with no args for missing keys
callback();
} else {
fs.mkdir(directory, 0777, this)
callback(null, value);
}
},
function openDirectoryLockFile (err) {
if (err) {
return callback(err)
}
var filename = path.join(directory, '.lock')
fs.open(filename, 'a', 0666, this)
},
function assignDirectoryLockFile (err, fd) {
if (err) {
return callback(err)
}
self.lock = fd
this()
},
function finishInitialization() {
self.directory = directory
callback(null, self)
}
)
}
})
.catch((err) => callback(err));
};
FsKeyValue.prototype.get = function (key, callback) {
var self = this
/**
* Retrieve a value by key (async version).
*
* Uses a shared lock on the key file for safe concurrent reads.
*
* @param {string} key - The key to retrieve
* @returns {Promise<*>} The value, or undefined if key doesn't exist
*/
FsKeyValue.prototype.getAsync = async function (key) {
const filename = path.join(this.directory, key);
let dirlock = null;
let keyfile = null;
if (typeof callback != 'function') {
var callback = function (err) {
if (err) {
throw err
}
try {
// Open and lock directory
dirlock = fs.openSync(this.directoryLock, 'a', 0o666);
await flock(dirlock, 'sh');
// Check if key exists
const exists = fs.existsSync(filename);
if (!exists) {
return undefined;
}
}
var filename
var keyfile
var value
// Open and lock key file
keyfile = fs.openSync(filename, 'a+', 0o666);
await flock(keyfile, 'sh');
Step(
function getDirectorySharedLock () {
fs.flock(self.lock, 'sh', this)
},
function doesKeyFileExist (err) {
if (err) {
return callback(err)
// Read value
const data = await fsp.readFile(filename, { encoding: 'utf8' });
return JSON.parse(data);
} finally {
// Release locks and close files
if (keyfile !== null) {
try {
await flock(keyfile, 'un');
} catch {
/* ignore */
}
filename = path.join(self.directory, key)
fs.exists(filename, this)
},
function openKeyFile (exists) {
if (exists) {
fs.open(filename, 'a+', 0666, this)
} else {
callback()
try {
fs.closeSync(keyfile);
} catch {
/* ignore */
}
},
function getKeyFileSharedLock (err, fd) {
if (err) {
return callback(err)
}
if (dirlock !== null) {
try {
await flock(dirlock, 'un');
} catch {
/* ignore */
}
keyfile = fd
fs.flock(keyfile, 'sh', this)
},
function readKeyFile (err) {
if (err) {
return callback(err)
try {
fs.closeSync(dirlock);
} catch {
/* ignore */
}
fs.readFile(filename, {'encoding': 'utf8'}, this)
},
function recordKeyValue (err, data) {
if (err) {
return callback(err)
}
value = data
this()
},
function releaseKeyFileSharedLock () {
fs.flock(keyfile, 'un', this)
},
function releaseDirectorySharedLock (err) {
if (err) {
return callback(err)
}
fs.flock(self.lock, 'un', this)
},
function finishGettingKey (err) {
if (err) {
return callback(err)
}
callback(err, JSON.parse(value))
}
)
}
}
};
/**
* Store a value by key.
*
* Uses an exclusive lock on the key file for safe writes.
* The value is serialized to JSON.
*
* @param {string} key - The key to store
* @param {*} value - The value to store (must be JSON-serializable)
* @param {ErrorCallback} [callback] - Called when write completes
*/
FsKeyValue.prototype.put = function (key, value, callback) {
var self = this
if (typeof callback != 'function') {
var callback = function (err) {
if (typeof callback !== 'function') {
callback = function (err) {
if (err) {
throw err
throw err;
}
}
};
}
var filename;
var keyfile;
var value;
this.putAsync(key, value)
.then(() => callback(null))
.catch((err) => callback(err));
};
Step(
function getDirectorySharedLock () {
fs.flock(self.lock, 'sh', this)
},
function openKeyFile (err) {
if (err) {
return callback(err)
/**
* Store a value by key (async version).
*
* Uses an exclusive lock on the key file for safe writes.
* The value is serialized to JSON.
*
* @param {string} key - The key to store
* @param {*} value - The value to store (must be JSON-serializable)
* @returns {Promise<void>}
*/
FsKeyValue.prototype.putAsync = async function (key, value) {
const filename = path.join(this.directory, key);
let dirlock = null;
let keyfile = null;
try {
// Open and lock directory (shared lock for puts)
dirlock = fs.openSync(this.directoryLock, 'a', 0o666);
await flock(dirlock, 'sh');
// Open and lock key file (exclusive lock for write)
keyfile = fs.openSync(filename, 'a', 0o666);
await flock(keyfile, 'ex');
// Write value
await fsp.writeFile(filename, JSON.stringify(value), { encoding: 'utf8' });
} finally {
// Release locks and close files
if (keyfile !== null) {
try {
await flock(keyfile, 'un');
} catch {
/* ignore */
}
filename = path.join(self.directory, key)
fs.open(filename, 'a', 0666, this)
},
function getKeyFileExclusiveLock (err, fd) {
if (err) {
return callback(err)
try {
fs.closeSync(keyfile);
} catch {
/* ignore */
}
keyfile = fd
fs.flock(keyfile, 'ex', this)
},
function writeKeyFile (err) {
if (err) {
return callback(err)
}
if (dirlock !== null) {
try {
await flock(dirlock, 'un');
} catch {
/* ignore */
}
fs.writeFile(filename, JSON.stringify(value), {'encoding': 'utf8'}, this)
},
function releaseKeyFileSharedLock (err) {
if (err) {
return callback(err)
try {
fs.closeSync(dirlock);
} catch {
/* ignore */
}
fs.flock(keyfile, 'un', this)
},
function releaseDirectorySharedLock (err) {
if (err) {
return callback(err)
}
fs.flock(self.lock, 'un', this)
},
function finishPuttingKey (err) {
return callback(err)
}
)
}
}
};
/**
* Delete a key from the store.
*
* Uses an exclusive lock on the directory for safe deletion.
* Does nothing if the key doesn't exist.
*
* @param {string} key - The key to delete
* @param {ErrorCallback} [callback] - Called when deletion completes
*/
FsKeyValue.prototype.delete = function (key, callback) {
var self = this
if (typeof callback != 'function') {
var callback = function (err) {
if (typeof callback !== 'function') {
callback = function (err) {
if (err) {
throw err
throw err;
}
}
};
}
var filename;
var keyfile;
var value;
this.deleteAsync(key)
.then(() => callback(null))
.catch((err) => callback(err));
};
Step(
function getDirectoryExclusiveLock () {
fs.flock(self.lock, 'ex', this)
},
function doesKeyFileExist (err) {
if (err) {
return callback(err)
/**
* Delete a key from the store (async version).
*
* Uses an exclusive lock on the directory for safe deletion.
* Does nothing if the key doesn't exist.
*
* @param {string} key - The key to delete
* @returns {Promise<void>}
*/
FsKeyValue.prototype.deleteAsync = async function (key) {
const filename = path.join(this.directory, key);
let dirlock = null;
try {
// Open and lock directory (exclusive lock for delete)
dirlock = fs.openSync(this.directoryLock, 'a', 0o666);
await flock(dirlock, 'ex');
// Delete if exists
const exists = fs.existsSync(filename);
if (exists) {
await fsp.unlink(filename);
}
} finally {
// Release lock and close file
if (dirlock !== null) {
try {
await flock(dirlock, 'un');
} catch {
/* ignore */
}
filename = path.join(self.directory, key)
fs.exists(filename, this)
},
function deleteKeyFile (exists) {
if (exists) {
fs.unlink(filename, this)
} else {
return callback()
try {
fs.closeSync(dirlock);
} catch {
/* ignore */
}
},
function releaseDirectorySharedLock (err) {
if (err) {
return callback(err)
}
fs.flock(self.lock, 'un', this)
},
function finishDeletingKey (err) {
return callback(err)
}
)
}
}
};
module.exports = FsKeyValue
module.exports = FsKeyValue;
+30
-15
package.json
{
"name": "fs-key-value",
"version": "1.2.0",
"description": "Key value data store using the filesystem",
"keywords": ["key", "value", "fs", "fs-ext", "flock", "db"],
"version": "1.0.0",
"homepage": "http://andrewshell.github.com/node-fs-key-value",
"repository": "git://github.com/andrewshell/node-fs-key-value.git",
"author": "Andrew Shell <andrew@andrewshell.org> (http://blog.andrewshell.org/)",
"homepage": "https://github.com/andrewshell/node-fs-key-value",
"repository": {
"type": "git",
"url": "git+https://github.com/andrewshell/node-fs-key-value.git"
},
"bugs": {
"url": "https://github.com/andrewshell/node-fs-key-value/issues"
},
"author": "Andrew Shell <andrew@andrewshell.org> (https://blog.andrewshell.org/)",
"license": "MIT",
"main": "./fs-key-value.js",
"files": [
"fs-key-value.js",
"README.md",
"LICENSE"
],
"engines": {
"node": ">=18.0.0"
},
"scripts": {
"test": "node --test 'test/**/*.test.js'",
"lint": "eslint .",
"format": "prettier --write .",
"format:check": "prettier --check ."
},
"dependencies": {
"fs-ext": ">= 0.3.x",
"path": ">= 0.4.x",
"step": "*"
"fs-ext": "^2.0.0"
},
"engines": {
"node": ">= v0.8.0"
},
"bugs": {
"mail" : "andrew@andrewshell.org",
"web" : "https://github.com/andrewshell/node-fs-key-value/issues"
"devDependencies": {
"eslint": "^9.17.0",
"prettier": "^3.4.2"
}
}
}
.npmignore

Sorry, the diff of this file is not supported yet

-52
Readme.md
# fs-key-value
This module provides a simple key value data store using only the file system. It makes use of file locking to allow safe operation in a multiple process environment without the overhead of a separate database server.
[![NPM](https://nodei.co/npm/fs-key-value.png)](https://nodei.co/npm/fs-key-value/)
## Installation
```bash
$ npm install fs-key-value
```
## Example
```js
var cluster = require('cluster'),
FsKeyValue = require('fs-key-value')
if (cluster.isMaster) {
for (var i = 0; i < 8; i++) {
cluster.fork()
}
} else {
var id = cluster.worker.id % 2
var mydb = new FsKeyValue('./mydb', function (err, db) {
if (err) {
return console.log(err)
}
db.put('hoopla' + id, {'msg': 'ballyhoo ' + cluster.worker.id}, function (err) {
if (err) {
return console.log(cluster.worker.id + ' err ' + err)
}
db.get('hoopla' + id, function (err, data) {
if (err) {
return console.log(cluster.worker.id + ' err ' + err)
}
if (data != undefined) {
console.log(data.msg)
}
db.delete('hoopla' + id)
cluster.worker.kill()
})
})
})
}
```