@wxn0brp/db-lock 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 wxn0brP
+
+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,55 @@
+# @wxn0brp/db-lock
+
+Designed to safely handle multiple processes accessing the same ValtheraDB instance simultaneously
+
+## Overview
+
+This package provides a locking mechanism that ensures thread-safe database operations by using file-based locks. It's designed to work with the ValtheraDB ecosystem and prevents concurrent write operations that could lead to data corruption or inconsistencies.
+
+## Installation
+
+```bash
+yarn add github:wxn0brP/ValtheraDB-lock#dist
+```
+
+## Features
+
+- **File-based locks**: Uses filesystem operations to coordinate locks
+- **Stale lock detection**: Automatically removes lock files that have exceeded the stale threshold
+- **Retry mechanism**: Configurable retry count and timing for lock acquisition
+- **Proxy-based**: Transparently wraps database operations without changing your code
+- **Lightweight**: Minimal overhead with efficient lock management
+
+## Usage
+
+```typescript
+import { createLock } from "@wxn0brp/db-lock";
+import { ValtheraClass } from "@wxn0brp/db-core";
+
+const db = new ValtheraClass();
+const lockedDb = createLock(db);
+
+// Now use lockedDb as you would use your original database instance
+// Locks will be automatically acquired for write operations and released afterwards
+```
+
+## Configuration Options
+
+| Option      | Type    | Default    | Description |
+|-------------|---------|------------|-------------|
+| `file`      | string  | "valthera.lock" | Path to the lock file |
+| `stale`     | number  | 5000       | Time in milliseconds after which a lock is considered stale and can be removed |
+| `retryTime` | number  | 50         | Time in milliseconds to wait between lock acquisition attempts |
+| `retryCount`| number  | 50         | Number of retry attempts before throwing an error |
+
+## How It Works
+
+The locking mechanism works by creating a lock file when a database operation begins and removing it when the operation completes. Operations that try to access the database while a lock exists will wait until the lock is released.
+
+The library automatically detects and removes stale locks that have been held longer than the configured stale threshold, preventing indefinite blocking (e.g., if a lock process is crashed).
+
+The proxy only intercepts operations that contain "add", "find", "remove", or "update" in their method names, allowing other database methods to pass through unaffected.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { ValtheraCompatible } from "@wxn0brp/db-core";
+export interface LockOpts {
+    file?: string;
+    stale?: number;
+    retryTime?: number;
+    retryCount?: number;
+}
+export declare function createLock<T extends ValtheraCompatible>(db: T, opts?: LockOpts): T;

package/dist/index.js

@@ -0,0 +1,57 @@
+import { unlink, open, stat } from "fs/promises";
+const lockOp = ["add", "find", "remove", "update", "toggle"];
+const hasOp = (op) => lockOp.some(v => op.includes(v));
+async function unlock(lockFile) {
+    try {
+        await unlink(lockFile);
+    }
+    catch { }
+}
+async function waitLock(opts) {
+    let i = 0;
+    while (true) {
+        if (opts.retryCount && i++ > opts.retryCount) {
+            throw new Error("Failed to acquire lock");
+        }
+        try {
+            const fd = await open(opts.file, "wx");
+            await fd.close();
+            break;
+        }
+        catch {
+            try {
+                const s = await stat(opts.file);
+                if (Date.now() - s.mtimeMs > opts.stale) {
+                    await unlink(opts.file);
+                }
+            }
+            catch { }
+            await new Promise(r => setTimeout(r, opts.retryTime || 50));
+        }
+    }
+}
+export function createLock(db, opts = {}) {
+    opts = {
+        file: "valthera.lock",
+        stale: 5000,
+        retryTime: 50,
+        retryCount: 50,
+        ...opts
+    };
+    return new Proxy(db, {
+        get: (target, prop) => {
+            if (!hasOp(prop.toString()))
+                return target[prop];
+            const origMethod = target[prop];
+            return async (...args) => {
+                await waitLock(opts);
+                try {
+                    return await origMethod.bind(target)(...args);
+                }
+                finally {
+                    await unlock(opts.file);
+                }
+            };
+        }
+    });
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "@wxn0brp/db-lock",
+    "version": "0.0.1",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "description": "Provides file-based locking for thread-safe ValtheraDB operations.",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/wxn0brP/ValtheraDB-lock.git"
+    },
+    "homepage": "https://github.com/wxn0brP/ValtheraDB-lock",
+    "author": "wxn0brP",
+    "license": "MIT",
+    "type": "module",
+    "scripts": {
+        "build": "tsc && tsc-alias"
+    },
+    "devDependencies": {
+        "@types/bun": "*",
+        "@wxn0brp/db-core": "^0.3.0",
+        "@wxn0brp/db-storage-dir": "^0.1.4",
+        "tsc-alias": "*",
+        "typescript": "*"
+    },
+    "peerDependencies": {
+        "@wxn0brp/db-core": ">=0.3.0",
+        "@wxn0brp/db-storage-dir": ">=0.1.4"
+    },
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        },
+        "./*": {
+            "types": "./dist/*.d.ts",
+            "import": "./dist/*.js",
+            "default": "./dist/*.js"
+        }
+    }
+}