fs-key-value 1.0.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+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.

package/README.md

@@ -0,0 +1,181 @@
+# 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

package/fs-key-value.js

@@ -1,226 +1,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');
 
-FsKeyValue.prototype.open = function (directory, callback) {
-  var self = this
+const flock = promisify(fsExt.flock);
 
-  if (typeof callback != 'function') {
-    var callback = function (err) { 
-      if (err) {
-        throw err
-      }
-    }
-  }
+/**
+ * @callback ErrorCallback
+ * @param {Error|null} err - Error if one occurred
+ */
 
-  Step(
-    function initialize () {
-      fs.exists(directory, this)
-    },
-    function makeDirectoryIfNotExists (exists) {
-      if (exists) {
-        return this()
-      } else {
-        fs.mkdir(directory, 0777, this)
-      }
-    },
-    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)
-    }
-  )
+/**
+ * @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);
+  }
 }
 
-FsKeyValue.prototype.get = function (key, callback) {
-  var self = this
+/**
+ * The storage directory path.
+ * @type {string}
+ */
+FsKeyValue.prototype.directory = undefined;
 
-  if (typeof callback != 'function') {
-    var callback = function (err) { 
+/**
+ * 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) {
+  if (typeof callback !== 'function') {
+    callback = function (err) {
       if (err) {
-        throw err
+        throw err;
       }
-    }
+    };
   }
 
-  var filename
-  var keyfile
-  var value
+  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');
+};
 
-  Step(
-    function getDirectorySharedLock () {
-      fs.flock(self.lock, 'sh', this)
-    },
-    function doesKeyFileExist (err) {
+/**
+ * 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) {
-        return callback(err)
+        throw err;
       }
-      filename = path.join(self.directory, key)
-      fs.exists(filename, this)
-    },
-    function openKeyFile (exists) {
-      if (exists) {
-        fs.open(filename, 'a+', 0666, this)
+    };
+  }
+
+  this.getAsync(key)
+    .then((value) => {
+      if (value === undefined) {
+        // Preserve original behavior: callback() with no args for missing keys
+        callback();
       } else {
-        callback()
+        callback(null, value);
       }
-    },
-    function getKeyFileSharedLock (err, fd) {
-      if (err) {
-        return callback(err)
-      }
-      keyfile = fd
-      fs.flock(keyfile, 'sh', this)
-    },
-    function readKeyFile (err) {
-      if (err) {
-        return callback(err)
+    })
+    .catch((err) => callback(err));
+};
+
+/**
+ * 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;
+
+  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;
+    }
+
+    // Open and lock key file
+    keyfile = fs.openSync(filename, 'a+', 0o666);
+    await flock(keyfile, 'sh');
+
+    // 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 */
       }
-      fs.readFile(filename, {'encoding': 'utf8'}, this)
-    },
-    function recordKeyValue (err, data) {
-      if (err) {
-        return callback(err)
+      try {
+        fs.closeSync(keyfile);
+      } catch {
+        /* ignore */
       }
-      value = data
-      this()
-    },
-    function releaseKeyFileSharedLock () {
-      fs.flock(keyfile, 'un', this)
-    },
-    function releaseDirectorySharedLock (err) {
-      if (err) {
-        return callback(err)
+    }
+    if (dirlock !== null) {
+      try {
+        await flock(dirlock, 'un');
+      } catch {
+        /* ignore */
       }
-      fs.flock(self.lock, 'un', this)
-    },
-    function finishGettingKey (err) {
-      if (err) {
-        return callback(err)
+      try {
+        fs.closeSync(dirlock);
+      } catch {
+        /* ignore */
       }
-      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)
-      }
-      filename = path.join(self.directory, key)
-      fs.open(filename, 'a', 0666, this)
-    },
-    function getKeyFileExclusiveLock (err, fd) {
-      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 */
       }
-      keyfile = fd
-      fs.flock(keyfile, 'ex', this)
-    },
-    function writeKeyFile (err) {
-      if (err) {
-        return callback(err)
+      try {
+        fs.closeSync(keyfile);
+      } catch {
+        /* ignore */
       }
-      fs.writeFile(filename, JSON.stringify(value), {'encoding': 'utf8'}, this)
-    },
-    function releaseKeyFileSharedLock (err) {
-      if (err) {
-        return callback(err)
+    }
+    if (dirlock !== null) {
+      try {
+        await flock(dirlock, 'un');
+      } catch {
+        /* ignore */
       }
-      fs.flock(keyfile, 'un', this)
-    },
-    function releaseDirectorySharedLock (err) {
-      if (err) {
-        return callback(err)
+      try {
+        fs.closeSync(dirlock);
+      } catch {
+        /* ignore */
       }
-      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)
-      }
-      filename = path.join(self.directory, key)
-      fs.exists(filename, this)
-    },
-    function deleteKeyFile (exists) {
-      if (exists) {
-        fs.unlink(filename, this)
-      } else {
-        return callback()
+/**
+ * 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 */
       }
-    },
-    function releaseDirectorySharedLock (err) {
-      if (err) {
-        return callback(err)
+      try {
+        fs.closeSync(dirlock);
+      } catch {
+        /* ignore */
       }
-      fs.flock(self.lock, 'un', this)
-    },
-    function finishDeletingKey (err) {
-      return callback(err)
     }
-  )
-}
+  }
+};
 
-module.exports = FsKeyValue
+module.exports = FsKeyValue;

package/package.json

@@ -1,22 +1,37 @@
 {
   "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/)",
-  "main": "./fs-key-value.js",
-  "dependencies": {
-    "fs-ext": ">= 0.3.x",
-    "path": ">= 0.4.x",
-    "step": "*"
+  "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": ">= v0.8.0"
+    "node": ">=18.0.0"
   },
-  "bugs": {
-    "mail" : "andrew@andrewshell.org",
-    "web" : "https://github.com/andrewshell/node-fs-key-value/issues"
+  "scripts": {
+    "test": "node --test 'test/**/*.test.js'",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "dependencies": {
+    "fs-ext": "^2.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.17.0",
+    "prettier": "^3.4.2"
   }
-}
+}

package/.npmignore

@@ -1,2 +0,0 @@
-.DS_Store
-node_modules

package/Readme.md

@@ -1,52 +0,0 @@
-# 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()
-      })
-    })
-  })
-}
-```