fs-key-value 0.1.2 → 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,46 +1,336 @@
-var fs = require('fs-ext')
-var path = require('path')
+'use strict';
 
-function FsKeyValue (directory) {
-  this.directory = directory
-  if (!fs.existsSync(this.directory)) {
-    fs.mkdirSync(this.directory)
+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);
   }
-  var filename = path.join(this.directory, '.lock')
-  this.lock = fs.openSync(filename, 'a')
 }
 
-FsKeyValue.prototype.get = function (key) {
-  fs.flockSync(this.lock, 'sh')
-  var filename = path.join(this.directory, key)
-  if (!fs.existsSync(filename)) {
-    return
-  }
-  var fd = fs.openSync(filename, 'a+')
-  fs.flockSync(fd, 'sh')
-  var data = fs.readFileSync(filename, {'encoding': 'utf8'})
-  fs.flockSync(fd, 'un')
-  fs.flockSync(this.lock, 'un')
-  return JSON.parse(data)
-}
+/**
+ * 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) {
+  if (typeof callback !== 'function') {
+    callback = function (err) {
+      if (err) {
+        throw 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;
+      }
+    };
+  }
 
-FsKeyValue.prototype.put = function (key, value) {
-  fs.flockSync(this.lock, 'sh')
-  var filename = path.join(this.directory, key)
-  var fd = fs.openSync(filename, 'a')
-  fs.flockSync(fd, 'ex')
-  fs.writeFileSync(filename, JSON.stringify(value), {'encoding': 'utf8'})
-  fs.flockSync(fd, 'un')
-  fs.flockSync(this.lock, 'un')
+  this.getAsync(key)
+    .then((value) => {
+      if (value === undefined) {
+        // Preserve original behavior: callback() with no args for missing keys
+        callback();
+      } else {
+        callback(null, value);
+      }
+    })
+    .catch((err) => callback(err));
 };
 
-FsKeyValue.prototype.del = function (key) {
-  fs.flockSync(this.lock, 'ex')
-  var filename = path.join(this.directory, key)
-  if (fs.existsSync(filename)) {
-    fs.unlinkSync(filename)
+/**
+ * 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 */
+      }
+      try {
+        fs.closeSync(keyfile);
+      } catch {
+        /* ignore */
+      }
+    }
+    if (dirlock !== null) {
+      try {
+        await flock(dirlock, 'un');
+      } catch {
+        /* ignore */
+      }
+      try {
+        fs.closeSync(dirlock);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+};
+
+/**
+ * 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) {
+  if (typeof callback !== 'function') {
+    callback = function (err) {
+      if (err) {
+        throw err;
+      }
+    };
+  }
+
+  this.putAsync(key, value)
+    .then(() => callback(null))
+    .catch((err) => 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 */
+      }
+      try {
+        fs.closeSync(keyfile);
+      } catch {
+        /* ignore */
+      }
+    }
+    if (dirlock !== null) {
+      try {
+        await flock(dirlock, 'un');
+      } catch {
+        /* ignore */
+      }
+      try {
+        fs.closeSync(dirlock);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+};
+
+/**
+ * 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) {
+  if (typeof callback !== 'function') {
+    callback = function (err) {
+      if (err) {
+        throw err;
+      }
+    };
+  }
+
+  this.deleteAsync(key)
+    .then(() => callback(null))
+    .catch((err) => 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 */
+      }
+      try {
+        fs.closeSync(dirlock);
+      } catch {
+        /* ignore */
+      }
+    }
   }
-  fs.flockSync(this.lock, 'un')
 };
 
-module.exports = FsKeyValue
+module.exports = FsKeyValue;

package/package.json

@@ -1,21 +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": "0.1.2",
-  "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"
+  "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 +0,0 @@
-.DS_Store

package/Readme.md

@@ -1,40 +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 FsKeyValue = new require('fs-key-value')
-
-var db = new FsKeyValue('./mydb')
-
-var cluster = require('cluster')
-
-if (cluster.isMaster) {
-  for (var i = 0; i < 8; i++) {
-    cluster.fork()
-  }
-} else {
-  var id = cluster.worker.id % 2
-
-  db.put('hoopla' + id, {'msg': 'ballyhoo ' + cluster.worker.id})
-
-  var data = db.get('hoopla' + id)
-  if (data != undefined) {
-    console.log(data.msg)
-  }
-
-  db.del('hoopla' + id)
-
-  cluster.worker.kill()
-}
-```