lba 1.0.0

package/README.md

@@ -0,0 +1,52 @@
+# LBA (Log-structured Binary Archive)
+
+A lightweight, high-performance, file-based key-value store for Node.js.
+It supports sharding, compression (zlib), and atomic updates.
+
+## Installation
+
+```bash
+npm install lba
+```
+
+## Usage
+
+```js
+const LBA = require("@your-username/lba");
+
+// Initialize DB (creates 'lba_storage' folder by default)
+const db = new LBA("./my-data");
+
+(async () => {
+  // 1. Set Data
+  await db.set("user:1001", {
+    name: "Alice",
+    age: 30,
+    items: ["sword", "shield"],
+  });
+
+  // 2. Get Data
+  const user = await db.get("user:1001");
+  console.log(user);
+  // Output: { name: 'Alice', age: 30, items: ['sword', 'shield'] }
+
+  // 3. Atomic Update (Thread-safe)
+  await db.update("user:1001", (data) => {
+    data.age += 1;
+    return data; // Return modified data
+  });
+
+  // 4. Delete
+  await db.delete("user:1001");
+})();
+```
+
+## Features
+
+- Sharding: Distributes data across multiple files to reduce lock contention.
+
+- Compression: Automatically compresses data using zlib.
+
+- Atomic Updates: Prevents race conditions during read-modify-write operations.
+
+- LRU Cache: Built-in memory caching for fast reads.

package/index.js

@@ -0,0 +1,263 @@
+const fs = require("fs");
+const path = require("path");
+const zlib = require("zlib");
+const util = require("util");
+
+const inflateAsync = util.promisify(zlib.inflateRaw);
+const deflateAsync = util.promisify(zlib.deflateRaw);
+
+class LBA {
+  constructor(dbDir = "lba_storage", options = {}) {
+    this.dbDir = path.resolve(dbDir);
+    this.shardCount = options.shardCount || 32;
+    this.cacheLimit = options.cacheLimit || 10000;
+    this.compressionLevel = options.fastMode ? 1 : 6;
+
+    this.indices = Array.from({ length: this.shardCount }, () => new Map());
+    this.cache = new Map();
+
+    this.queues = Array.from({ length: this.shardCount }, () =>
+      Promise.resolve(),
+    );
+
+    this.fileHandles = new Array(this.shardCount).fill(null);
+    this.isLoaded = new Array(this.shardCount).fill(false);
+
+    if (!fs.existsSync(this.dbDir))
+      fs.mkdirSync(this.dbDir, { recursive: true });
+  }
+
+  _getShard(key) {
+    let hash = 2166136261;
+    const sKey = String(key);
+    for (let i = 0; i < sKey.length; i++) {
+      hash ^= sKey.charCodeAt(i);
+      hash = Math.imul(hash, 16777619);
+    }
+    return Math.abs(hash) % this.shardCount;
+  }
+
+  async _ensureShardLoaded(sIdx) {
+    if (this.isLoaded[sIdx]) return;
+
+    const fPath = path.join(this.dbDir, `shard_${sIdx}.lba`);
+    this.fileHandles[sIdx] = await fs.promises.open(fPath, "a+");
+
+    const stat = await this.fileHandles[sIdx].stat();
+    const size = stat.size;
+    let offset = 0;
+    const headerSize = 11;
+    const headerBuf = Buffer.alloc(headerSize);
+
+    while (offset + headerSize <= size) {
+      const { bytesRead } = await this.fileHandles[sIdx].read(
+        headerBuf,
+        0,
+        headerSize,
+        offset,
+      );
+      if (bytesRead < headerSize) break;
+
+      if (headerBuf[0] !== 0x4c || headerBuf[1] !== 0x42) {
+        console.warn(
+          `Shard ${sIdx}: 데이터 손상 감지 (Offset: ${offset}). 복구를 위해 이후 데이터를 무시합니다.`,
+        );
+        break;
+      }
+
+      const vLen = headerBuf.readUInt32BE(6);
+      const kLen = headerBuf[10];
+      const recordTotalSize = headerSize + kLen + vLen;
+
+      if (offset + recordTotalSize > size) {
+        console.warn(
+          `Shard ${sIdx}: 불완전한 기록 발견 (Offset: ${offset}). 마지막 데이터를 폐기합니다.`,
+        );
+        break;
+      }
+
+      const kBuf = Buffer.alloc(kLen);
+      await this.fileHandles[sIdx].read(kBuf, 0, kLen, offset + headerSize);
+      const key = kBuf.toString();
+
+      if (vLen > 0) {
+        this.indices[sIdx].set(key, {
+          offset: offset + headerSize + kLen,
+          length: vLen,
+        });
+      } else {
+        this.indices[sIdx].delete(key);
+      }
+
+      offset += recordTotalSize;
+    }
+
+    this.isLoaded[sIdx] = true;
+  }
+
+  async _readImpl(sIdx, key) {
+    if (this.cache.has(key)) {
+      const val = this.cache.get(key);
+      this.cache.delete(key);
+      this.cache.set(key, val);
+      return val;
+    }
+
+    const meta = this.indices[sIdx].get(String(key));
+    if (!meta) return null;
+
+    const buf = Buffer.alloc(meta.length);
+    await this.fileHandles[sIdx].read(buf, 0, meta.length, meta.offset);
+
+    try {
+      const decompressed = await inflateAsync(buf);
+      const data = JSON.parse(decompressed.toString());
+
+      if (this.cache.size >= this.cacheLimit) {
+        const firstKey = this.cache.keys().next().value;
+        this.cache.delete(firstKey);
+      }
+      this.cache.set(String(key), data);
+
+      return data;
+    } catch (err) {
+      console.error(`Read error for key ${key}:`, err);
+      return null;
+    }
+  }
+
+  async _writeImpl(sIdx, key, value) {
+    const kStr = String(key);
+    const kBuf = Buffer.from(kStr);
+
+    let vBuf;
+    let vLen = 0;
+
+    if (value !== null && value !== undefined) {
+      const jsonStr = JSON.stringify(value);
+      vBuf = await deflateAsync(jsonStr, { level: this.compressionLevel });
+      vLen = vBuf.length;
+    }
+
+    const head = Buffer.alloc(11);
+    head[0] = 0x4c;
+    head[1] = 0x42;
+    head.writeUInt32BE(0, 2);
+    head.writeUInt32BE(vLen, 6);
+    head[10] = kBuf.length;
+
+    const parts = [head, kBuf];
+    if (vLen > 0) parts.push(vBuf);
+    const block = Buffer.concat(parts);
+
+    const stat = await this.fileHandles[sIdx].stat();
+    const pos = stat.size;
+
+    await this.fileHandles[sIdx].write(block, 0, block.length, pos);
+
+    if (vLen > 0) {
+      this.indices[sIdx].set(kStr, {
+        offset: pos + 11 + kBuf.length,
+        length: vLen,
+      });
+
+      this.cache.delete(kStr);
+      this.cache.set(kStr, value);
+    } else {
+      this.indices[sIdx].delete(kStr);
+      this.cache.delete(kStr);
+    }
+  }
+
+  _enqueue(sIdx, task) {
+    const next = this.queues[sIdx]
+      .then(() => this._ensureShardLoaded(sIdx))
+      .then(task)
+      .catch((err) => console.error(`LBA Error (Shard ${sIdx}):`, err));
+
+    this.queues[sIdx] = next;
+    return next;
+  }
+
+  async get(key) {
+    const sIdx = this._getShard(key);
+    return this._enqueue(sIdx, () => this._readImpl(sIdx, key));
+  }
+
+  async set(key, value) {
+    const sIdx = this._getShard(key);
+    return this._enqueue(sIdx, () => this._writeImpl(sIdx, key, value));
+  }
+
+  async delete(key) {
+    return this.set(key, null);
+  }
+
+  async update(key, fn) {
+    const sIdx = this._getShard(key);
+    return this._enqueue(sIdx, async () => {
+      const current = await this._readImpl(sIdx, key);
+      const next = await fn(current);
+      if (next !== undefined) {
+        await this._writeImpl(sIdx, key, next);
+      }
+    });
+  }
+
+  async vacuum() {
+    const tasks = [];
+    for (let i = 0; i < this.shardCount; i++) {
+      tasks.push(
+        this._enqueue(i, async () => {
+          if (!this.isLoaded[i] || this.indices[i].size === 0) return;
+
+          const tmpPath = path.join(this.dbDir, `vacuum_${i}.tmp`);
+          const oldPath = path.join(this.dbDir, `shard_${i}.lba`);
+
+          const tmpHandle = await fs.promises.open(tmpPath, "w");
+          let newPos = 0;
+
+          for (const [key, meta] of this.indices[i]) {
+            const vBuf = Buffer.alloc(meta.length);
+            await this.fileHandles[i].read(vBuf, 0, meta.length, meta.offset);
+
+            const kBuf = Buffer.from(key);
+
+            const head = Buffer.alloc(11);
+            head[0] = 0x4c;
+            head[1] = 0x42;
+            head.writeUInt32BE(0, 2);
+            head.writeUInt32BE(vBuf.length, 6);
+            head[10] = kBuf.length;
+
+            const block = Buffer.concat([head, kBuf, vBuf]);
+
+            await tmpHandle.write(block);
+
+            meta.offset = newPos + 11 + kBuf.length;
+            newPos += block.length;
+          }
+
+          await tmpHandle.close();
+          await this.fileHandles[i].close();
+
+          await fs.promises.rename(tmpPath, oldPath);
+
+          this.fileHandles[i] = await fs.promises.open(oldPath, "a+");
+        }),
+      );
+    }
+    await Promise.all(tasks);
+    this.cache.clear();
+  }
+
+  async close() {
+    await Promise.all(this.queues);
+    for (const handle of this.fileHandles) {
+      if (handle) await handle.close();
+    }
+    this.isLoaded.fill(false);
+  }
+}
+
+module.exports = LBA;

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "lba",
+  "version": "1.0.0",
+  "description": "A lightweight, log-structured binary key-value store.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "database",
+    "key-value",
+    "lba",
+    "storage"
+  ],
+  "author": "kyoomin",
+  "license": "MIT"
+}