# nlocks

A Node.js library providing asynchronous locking mechanisms including in-memory locks and file-based locks for coordinating access to resources across concurrent processes.

## Features

- **AsyncLock**: In-memory asynchronous lock for coordinating access to resources within a single process
- **FileLock**: File-based lock for coordinating access to resources across multiple processes
- **TCPLock**: TCP-based distributed lock for coordinating access to resources across multiple machines
- Lightweight and easy to use
- Promise-based API
- Comprehensive test coverage

## Installation

```bash
npm install nlocks
```

## Usage

### Via index.js (recommended)

```javascript
const { AsyncLock, FileLock } = require('nlocks');

const asyncLock = new AsyncLock();
const fileLock = new FileLock();
```

### AsyncLock

An in-memory lock for synchronizing async operations within a single Node.js process:

```javascript
const AsyncLock = require('nlocks/async-lock');

const lock = new AsyncLock();

async function protectedOperation() {
  await lock.acquire();
  try {
    // Your critical section code here
    console.log('Performing protected operation');
    await someAsyncWork();
  } finally {
    lock.release();
  }
}
```

### FileLock

A file-based lock for synchronizing operations across multiple Node.js processes:

```javascript
const FileLock = require('nlocks/file-lock');

const lock = new FileLock();

async function fileProtectedOperation() {
  await lock.acquire('/path/to/your/file.txt');
  try {
    // Your file operation code here
    console.log('Performing file operation');
    await someFileAsyncWork();
  } finally {
    lock.release('/path/to/your/file.txt');
  }
}
```

### TCPLock

A TCP-based distributed lock for synchronizing operations across multiple machines:

#### Server side

```javascript
const TCPLockServer = require('nlocks/lock.tcp');

// Create and start a TCP lock server
const server = new TCPLockServer({
  host: '0.0.0.0',  // Listen host
  port: 7301        // Listen port
});

server.start();
```

#### Client side

```javascript
const TcpRwLock = require('nlocks/lock-client.tcp');

// Create a TCP lock client
const lock = new TcpRwLock('resource-name', {
  connect: {
    host: 'localhost',  // Server host
    port: 7301          // Server port
  }
});

async function tcpProtectedOperation() {
  await lock.connect();  // Connect to the lock server
  try {
    await lock.readLock();   // Acquire a read lock
    // Or use await lock.writeLock(); for a write lock
    
    // Your critical section code here
    console.log('Performing protected operation');
    await someAsyncWork();
  } finally {
    await lock.unlock();     // Release the lock
    await lock.close(); // Disconnect from server
  }
}
```

## API

### AsyncLock

- `new AsyncLock()` - Creates a new AsyncLock instance
- `acquire(): Promise<void>` - Acquires the lock
- `release(): void` - Releases the lock

### FileLock

- `new FileLock()` - Creates a new FileLock instance
- `acquire(filePath): Promise<void>` - Acquires a lock for the specified file path
- `release(filePath): void` - Releases the lock for the specified file path

### TCPLock

#### Server

- `new TCPLockServer(options)` - Creates a new TCP lock server instance
  - `options.host`: Host to listen on (default: '0.0.0.0')
  - `options.port`: Port to listen on (default: 7301)
- `start(): void` - Starts the lock server
- `stop(): void` - Stops the lock server

#### Client

- `new TcpRwLock(resource, options)` - Creates a new TCP lock client instance
  - `resource`: Name of the resource to lock
  - `options.connect.host`: Server hostname to connect to (default: 'localhost')
  - `options.connect.port`: Server port to connect to (default: 7301)
- `connect(): Promise<void>` - Connects to the lock server
- `readLock(): Promise<void>` - Acquires a read lock
- `writeLock(): Promise<void>` - Acquires a write lock
- `unlock(): Promise<void>` - Releases the currently held lock

## Testing

Run the test suite with:

```bash
npm test
```

## License

[MIT](LICENSE)