File Lockdown

File Lockdown is a library designed to handle file locking and asynchronous file operations.
It is built for use with fs-broker and allows communication with background processes via the net-fn module.
The library ensures thread safety and provides a robust API for managing file operations without blocking the event loop.

This manual is also available in HTML5 format.

---

Installation

Install the library using npm:

npm install file-lockdown

---

Basic Usage

Here’s a simple example of how to use the library:
``javascript
var file_lock = require("file-lockdown");
setTimeout(function () {
file_lock.lockAppendFile("./test.txt", "1 test\r\n", function (err) {
if (err) { console.error(err); }
});
}, 100);
`

---

How It Works

The library uses a locking mechanism to ensure that file operations are serialized for the same file. This prevents race conditions and ensures thread safety.

1. A lockFiles object tracks the state of locked files.
2. If a file is already locked, the callback is queued.
3. If the file is not locked, it is locked, and queued callbacks are processed sequentially using the next function.
4. A fnUnlock function is provided to release the lock after the operation is complete.

---

Key Features

- Thread Safety: Ensures that file operations are serialized for the same file.
- Asynchronous Operations: All operations are non-blocking and use callbacks.
- IPC Support: Allows communication with background processes via the net module.
- Configurable Behavior: Options like enableSyncWrites provide flexibility for synchronous or asynchronous writes.

---

Config Sets

- enableSyncWrites: Enable synchronous writing. This is safer than asynchronous writing. (added with version 1.2)
- ipc_port: Port number. See more about net-fn connection.
- ipc_host: Hostname.See more about net-fn connection.

`json
{
"production": {
"file_lockdown": {
"enableSyncWrites": false,
"ipc_port": 8021,
"ipc_host": "localhost"
}
}
}
`

Reference

Below is a list of the available functions and their usage:

$3

Locks a file for exclusive access.
`javascript
/**
* @param {string} filePath
* @param {(err:any,callback:(err:any,fnUnlock:()void)void)void} callback function(err,fnUnlock()=>void){...}
*/
function lockFile(filePath, callback)
`

$3

Reads a file while ensuring it is locked during the operation.
`javascript
/**
* @param {string} filePath
* @param {(err:any,data:Buffer)void} callback function(err,data)
* @param {string} encoding Default: "utf8"
*/
function lockReadFile(filePath, callback, encoding = "utf8")
`

$3

Writes data to a file, optionally truncating it first.
`javascript
/**
* @param {string} filePath
* @param {Buffer} bufferdata
* @param {(err:any)void} callback function(err)
* @param {string} encoding Default: "utf8"
*/
function lockWriteFile(filePath, buffer, callback, encoding = "utf8")
`

$3

Combines reading and writing operations on a file.
`javascript
/**
* @param {string} filePath
* @param {(err:any,buf:Buffer,fnWriteClose:(buf:Buffer,isTruncated:boolean, callback:(err:any)void)void)void} fnRead function(err,data,fnWriteClose(buffer))'buffer'dataforwritingandclose|nullforclose
* @param {string} encoding Default: "utf8"
*/
function lockReadWriteFile(filePath, callback, encoding = "utf8",)
`

$3

Appends data to a file, creating it if it doesn't exist.
`javascript
/**
* @param {string} filePath
* @param {Buffer} buffer
* @param {(err:any)void} callback function(err)
* @param {string} encoding Default: "utf8"
*/
function lockAppendFile(filePath, buffer, callback, encoding = "utf8")
`

$3

Deletes a file.
`javascript
/**
* @param {string} filePath
* @param {(err:any)void} callback function(err)
*/
function lockDeleteFile(filePath, callback)
`

$3

Renames a file.
`javascript
/**
* @param {string} filePath
* @param {string} newPath
* @param {(err:any)void} callback
*/
function lockRename(filePath, newPath, callback)
`

$3

Creates a directory recursively.
`javascript
/**
* @param {string} dirPath
* @param {(err:any)void} callback
*/
function lockCreateDir(dirPath, callback)
`

$3

Deletes a directory recursively.
`javascript
/**
* @param {string} dirPath
* @param {(err:any)void} callback
*/
function lockDeleteDir(dirPath, callback)
`

$3

Checks if a file or directory exists.
`javascript
/**
* @param {string} path
* @param {(err:any)void} callback
* @param {number} timeout
*/
function lockAccess(path, callback, timeout)
``

License

This project is licensed under the MIT License.

Copyright © Manuel Lõhmus