logosdb 0.7.1

package/README.md

@@ -0,0 +1,143 @@
+# LogosDB - Node.js Bindings
+
+Fast semantic vector database (HNSW + mmap) for Node.js. Zero-copy memory-mapped storage with local-only deployment.
+
+## Features
+
+- **Memory-efficient**: Uses mmap() — RAM scales with queries, not data size
+- **Fast**: HNSW approximate nearest neighbor (O(log n) queries)
+- **Local-only**: No cloud dependencies, data never leaves your machine
+- **TypeScript support**: Full type definitions included
+- **Cross-platform**: Linux, macOS, Windows (x64, arm64)
+
+## Installation
+
+```bash
+npm install logosdb
+```
+
+Prebuilt binaries are provided for common platforms. If a prebuilt binary is not available, npm will compile from source (requires Python, C++ compiler, and CMake).
+
+## Quick Start
+
+```javascript
+const { DB, DIST_COSINE } = require('logosdb');
+
+// Create database
+const db = new DB('/tmp/mydb', {
+  dim: 384,              // Vector dimension
+  distance: DIST_COSINE  // Auto-normalizes vectors
+});
+
+// Insert documents with embeddings
+const embedding = [0.1, 0.2, /* ... 384 floats ... */];
+const id = db.put(embedding, 'My document text', '2025-01-01T00:00:00Z');
+
+// Search
+const query = [0.15, 0.25, /* ... */];
+const hits = db.search(query, 5);
+
+for (const hit of hits) {
+  console.log(`${hit.score.toFixed(4)}  ${hit.text}`);
+}
+
+// Close
+db.close();
+```
+
+## API
+
+### `new DB(path, options)`
+
+Create a new database instance.
+
+**Options:**
+- `dim` (number): Vector dimension (default: 128)
+- `maxElements` (number): Maximum capacity (default: 1,000,000)
+- `efConstruction` (number): HNSW build quality (default: 200)
+- `M` (number): HNSW graph degree (default: 16)
+- `efSearch` (number): HNSW search width (default: 50)
+- `distance` (number): Distance metric (`DIST_IP`, `DIST_COSINE`, `DIST_L2`)
+
+### `db.put(embedding, text?, timestamp?)`
+
+Insert a vector. Returns the assigned row ID.
+
+### `db.search(queryEmbedding, topK?)`
+
+Search for similar vectors. Returns array of `SearchHit` objects.
+
+### `db.searchTsRange(queryEmbedding, options)`
+
+Search with timestamp filter.
+
+**Options:**
+- `topK` (number): Number of results
+- `tsFrom` (string): Start timestamp (ISO 8601)
+- `tsTo` (string): End timestamp (ISO 8601)
+- `candidateK` (number): Internal multiplier for filtering
+
+### `db.update(id, embedding, text?, timestamp?)`
+
+Update a row (marks old as deleted, creates new). Returns new ID.
+
+### `db.delete(id)`
+
+Delete a row by ID.
+
+### `db.count()` / `db.countLive()`
+
+Get total/live row counts.
+
+### `db.close()`
+
+Close the database.
+
+## Distance Metrics
+
+- `DIST_IP` (0): Inner product (default, requires L2-normalized vectors)
+- `DIST_COSINE` (1): Cosine similarity (auto-normalizes)
+- `DIST_L2` (2): Euclidean distance
+
+## Memory Model
+
+LogosDB uses memory-mapped files:
+
+| Dataset | Disk | Typical Query RAM |
+|---------|------|-------------------|
+| 100K × 384-dim | 153 MB | <20 MB |
+| 1M × 384-dim | 1.5 GB | <100 MB |
+| 10M × 384-dim | 15 GB | <200 MB |
+
+RAM scales with query patterns, not dataset size.
+
+## TypeScript
+
+```typescript
+import { DB, SearchHit, DIST_COSINE } from 'logosdb';
+
+const db = new DB('/tmp/mydb', { dim: 384, distance: DIST_COSINE });
+const hits: SearchHit[] = db.search(embedding, 5);
+```
+
+## Building from Source
+
+```bash
+npm install --build-from-source
+```
+
+Requirements:
+- Python 3.x
+- C++17 compiler (GCC, Clang, MSVC)
+- CMake 3.15+
+- Node.js 16+
+
+## License
+
+MIT — see [LICENSE](../LICENSE)
+
+## Links
+
+- GitHub: https://github.com/jose-compu/logosdb
+- Issues: https://github.com/jose-compu/logosdb/issues
+- Python bindings: `pip install logosdb`

package/binding.gyp

@@ -0,0 +1,65 @@
+{
+  "variables": {
+    "openssl_fips%": ""
+  },
+  "targets": [
+    {
+      "target_name": "logosdb",
+      "sources": [
+        "src/node_logosdb.cpp",
+        "../src/logosdb.cpp",
+        "../src/storage.cpp",
+        "../src/metadata.cpp",
+        "../src/hnsw_index.cpp",
+        "../src/wal.cpp",
+        "../src/platform.cpp"
+      ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")",
+        "../include",
+        "../src",
+        "../third_party"
+      ],
+      "cflags!": ["-fno-exceptions"],
+      "cflags_cc!": ["-fno-exceptions"],
+      "cflags_cc": [
+        "-std=c++17",
+        "-fexceptions"
+      ],
+      "conditions": [
+        ["OS=='mac'", {
+          "xcode_settings": {
+            "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
+            "CLANG_CXX_LIBRARY": "libc++",
+            "MACOSX_DEPLOYMENT_TARGET": "11.0",
+            "OTHER_CPLUSPLUSFLAGS": [
+              "-std=c++17",
+              "-fexceptions"
+            ]
+          }
+        }],
+        ["OS=='linux'", {
+          "cflags_cc": [
+            "-std=c++17",
+            "-fexceptions"
+          ],
+          "ldflags": [
+            "-Wl,--gc-sections"
+          ]
+        }],
+        ["OS=='win'", {
+          "msvs_settings": {
+            "VCCLCompilerTool": {
+              "ExceptionHandling": 1,
+              "AdditionalOptions": ["/std:c++17"]
+            }
+          }
+        }]
+      ],
+      "defines": [
+        "NAPI_CPP_EXCEPTIONS",
+        "NAPI_VERSION=8"
+      ]
+    }
+  ]
+}

package/lib/index.js

@@ -0,0 +1,184 @@
+/**
+ * LogosDB - Fast semantic vector database (HNSW + mmap)
+ * Node.js bindings
+ */
+
+'use strict';
+
+const bindings = require('bindings')('logosdb');
+
+/**
+ * Search result hit
+ * @typedef {Object} SearchHit
+ * @property {number} id - Row ID
+ * @property {number} score - Similarity score (0-1)
+ * @property {string|null} text - Associated text
+ * @property {string|null} timestamp - ISO 8601 timestamp
+ */
+
+/**
+ * LogosDB database instance
+ *
+ * @example
+ * const { DB } = require('logosdb');
+ *
+ * const db = new DB('/tmp/mydb', { dim: 128 });
+ *
+ * // Insert with embedding
+ * const id = db.put(embedding, 'My text', '2025-01-01T00:00:00Z');
+ *
+ * // Search
+ * const hits = db.search(queryEmbedding, 5);
+ * console.log(hits[0].text, hits[0].score);
+ */
+class DB {
+  /**
+   * Create a new LogosDB instance
+   * @param {string} path - Database directory path
+   * @param {Object} [options] - Database options
+   * @param {number} [options.dim=128] - Vector dimension
+   * @param {number} [options.maxElements=1000000] - Maximum capacity
+   * @param {number} [options.efConstruction=200] - HNSW construction parameter
+   * @param {number} [options.M=16] - HNSW M parameter
+   * @param {number} [options.efSearch=50] - HNSW search parameter
+   * @param {number} [options.distance=DIST_IP] - Distance metric (DIST_IP, DIST_COSINE, DIST_L2)
+   */
+  constructor(path, options = {}) {
+    this._db = new bindings.DB(path, options);
+    this._closed = false;
+  }
+
+  /**
+   * Insert a vector with optional text and timestamp
+   * @param {number[]} embedding - Float vector
+   * @param {string} [text] - Optional text metadata
+   * @param {string} [timestamp] - Optional ISO 8601 timestamp
+   * @returns {number} Assigned row ID
+   */
+  put(embedding, text, timestamp) {
+    this._checkClosed();
+    return this._db.put(embedding, text, timestamp);
+  }
+
+  /**
+   * Search for similar vectors
+   * @param {number[]} queryEmbedding - Query vector
+   * @param {number} [topK=10] - Number of results
+   * @returns {SearchHit[]} Search results
+   */
+  search(queryEmbedding, topK = 10) {
+    this._checkClosed();
+    return this._db.search(queryEmbedding, topK);
+  }
+
+  /**
+   * Search with timestamp range filter
+   * @param {number[]} queryEmbedding - Query vector
+   * @param {Object} options - Search options
+   * @param {number} [options.topK=10] - Number of results
+   * @param {string} [options.tsFrom] - Start timestamp (inclusive)
+   * @param {string} [options.tsTo] - End timestamp (inclusive)
+   * @param {number} [options.candidateK] - Internal candidate multiplier
+   * @returns {SearchHit[]} Search results
+   */
+  searchTsRange(queryEmbedding, options = {}) {
+    this._checkClosed();
+    return this._db.searchTsRange(queryEmbedding, options);
+  }
+
+  /**
+   * Update an existing row (marks old as deleted, creates new)
+   * @param {number} id - Row ID to update
+   * @param {number[]} embedding - New embedding
+   * @param {string} [text] - New text
+   * @param {string} [timestamp] - New timestamp
+   * @returns {number} New row ID
+   */
+  update(id, embedding, text, timestamp) {
+    this._checkClosed();
+    return this._db.update(id, embedding, text, timestamp);
+  }
+
+  /**
+   * Delete a row by ID
+   * @param {number} id - Row ID to delete
+   */
+  delete(id) {
+    this._checkClosed();
+    this._db.delete(id);
+  }
+
+  /**
+   * Get total row count (including deleted)
+   * @returns {number}
+   */
+  count() {
+    this._checkClosed();
+    return this._db.count();
+  }
+
+  /**
+   * Get live row count (excluding deleted)
+   * @returns {number}
+   */
+  countLive() {
+    this._checkClosed();
+    return this._db.countLive();
+  }
+
+  /**
+   * Get vector dimension
+   * @returns {number}
+   */
+  dim() {
+    return this._db.dim();
+  }
+
+  /**
+   * Close the database
+   */
+  close() {
+    if (!this._closed) {
+      this._db.close();
+      this._closed = true;
+    }
+  }
+
+  _checkClosed() {
+    if (this._closed) {
+      throw new Error('Database is closed');
+    }
+  }
+}
+
+/**
+ * Inner product distance (default, requires L2-normalized vectors)
+ * @constant {number}
+ */
+const DIST_IP = bindings.DIST_IP;
+
+/**
+ * Cosine similarity (auto-normalizes vectors)
+ * @constant {number}
+ */
+const DIST_COSINE = bindings.DIST_COSINE;
+
+/**
+ * Euclidean distance (L2 space)
+ * @constant {number}
+ */
+const DIST_L2 = bindings.DIST_L2;
+
+/**
+ * Library version string
+ * @constant {string}
+ */
+const VERSION = bindings.VERSION;
+
+module.exports = {
+  DB,
+  DIST_IP,
+  DIST_COSINE,
+  DIST_L2,
+  VERSION,
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "logosdb",
+  "version": "0.7.1",
+  "description": "Fast semantic vector database (HNSW + mmap) - Node.js bindings",
+  "main": "lib/index.js",
+  "types": "types/index.d.ts",
+  "scripts": {
+    "install": "prebuild-install || node-gyp rebuild",
+    "build": "node-gyp rebuild",
+    "test": "mocha test/test.js",
+    "prebuild": "prebuild --runtime napi --all --strip",
+    "prebuild-upload": "prebuild --runtime napi --all --strip --upload-all"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jose-compu/logosdb.git"
+  },
+  "keywords": [
+    "vector-database",
+    "hnsw",
+    "embeddings",
+    "semantic-search",
+    "nearest-neighbor",
+    "native-addon"
+  ],
+  "author": "Jose",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/jose-compu/logosdb/issues"
+  },
+  "homepage": "https://github.com/jose-compu/logosdb#readme",
+  "dependencies": {
+    "bindings": "^1.5.0",
+    "node-addon-api": "^7.0.0",
+    "prebuild-install": "^7.1.1"
+  },
+  "devDependencies": {
+    "mocha": "^10.2.0",
+    "prebuild": "^12.1.0"
+  },
+  "binary": {
+    "napi_versions": [
+      8
+    ]
+  },
+  "gypfile": true,
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}

package/src/node_logosdb.cpp

@@ -0,0 +1,405 @@
+/**
+ * Node.js N-API bindings for LogosDB
+ *
+ * Provides JavaScript bindings for the LogosDB C++ API.
+ */
+
+#include <napi.h>
+#include <logosdb/logosdb.h>
+#include <cstring>
+#include <string>
+#include <vector>
+
+// Helper to convert JS array to float vector
+static std::vector<float> JsArrayToFloatVector(const Napi::Array& arr) {
+    std::vector<float> vec;
+    vec.reserve(arr.Length());
+    for (size_t i = 0; i < arr.Length(); i++) {
+        vec.push_back(arr.Get(i).As<Napi::Number>().FloatValue());
+    }
+    return vec;
+}
+
+// Helper to convert SearchHit to JS object
+static Napi::Object SearchHitToJsObject(Napi::Env env, const logosdb_search_result_t* result, int index) {
+    Napi::Object obj = Napi::Object::New(env);
+
+    uint64_t id = logosdb_result_id(result, index);
+    float score = logosdb_result_score(result, index);
+    const char* text = logosdb_result_text(result, index);
+    const char* timestamp = logosdb_result_timestamp(result, index);
+
+    obj.Set("id", Napi::Number::New(env, static_cast<double>(id)));
+    obj.Set("score", Napi::Number::New(env, score));
+    if (text) {
+        obj.Set("text", Napi::String::New(env, text));
+    } else {
+        obj.Set("text", env.Null());
+    }
+    if (timestamp) {
+        obj.Set("timestamp", Napi::String::New(env, timestamp));
+    } else {
+        obj.Set("timestamp", env.Null());
+    }
+
+    return obj;
+}
+
+// DB wrapper class
+class DBWrapper : public Napi::ObjectWrap<DBWrapper> {
+public:
+    static Napi::Object Init(Napi::Env env, Napi::Object exports) {
+        Napi::Function func = DefineClass(env, "DB", {
+            InstanceMethod("put", &DBWrapper::Put),
+            InstanceMethod("search", &DBWrapper::Search),
+            InstanceMethod("searchTsRange", &DBWrapper::SearchTsRange),
+            InstanceMethod("update", &DBWrapper::Update),
+            InstanceMethod("delete", &DBWrapper::Delete),
+            InstanceMethod("count", &DBWrapper::Count),
+            InstanceMethod("countLive", &DBWrapper::CountLive),
+            InstanceMethod("dim", &DBWrapper::Dim),
+            InstanceMethod("close", &DBWrapper::Close),
+        });
+
+        exports.Set("DB", func);
+        return exports;
+    }
+
+    DBWrapper(const Napi::CallbackInfo& info) : Napi::ObjectWrap<DBWrapper>(info) {
+        Napi::Env env = info.Env();
+
+        if (info.Length() < 1 || !info[0].IsString()) {
+            throw Napi::TypeError::New(env, "Path (string) expected as first argument");
+        }
+
+        std::string path = info[0].As<Napi::String>().Utf8Value();
+        int dim = 128;  // default
+        size_t max_elements = 1000000;
+        int ef_construction = 200;
+        int M = 16;
+        int ef_search = 50;
+        int distance = 0;  // LOGOSDB_DIST_IP
+
+        // Parse options object if provided
+        if (info.Length() > 1 && info[1].IsObject()) {
+            Napi::Object options = info[1].As<Napi::Object>();
+
+            if (options.Has("dim")) {
+                dim = options.Get("dim").As<Napi::Number>().Int32Value();
+            }
+            if (options.Has("maxElements")) {
+                max_elements = static_cast<size_t>(
+                    options.Get("maxElements").As<Napi::Number>().Int64Value()
+                );
+            }
+            if (options.Has("efConstruction")) {
+                ef_construction = options.Get("efConstruction").As<Napi::Number>().Int32Value();
+            }
+            if (options.Has("M")) {
+                M = options.Get("M").As<Napi::Number>().Int32Value();
+            }
+            if (options.Has("efSearch")) {
+                ef_search = options.Get("efSearch").As<Napi::Number>().Int32Value();
+            }
+            if (options.Has("distance")) {
+                distance = options.Get("distance").As<Napi::Number>().Int32Value();
+            }
+        }
+
+        // Create options
+        logosdb_options_t* opts = logosdb_options_create();
+        logosdb_options_set_dim(opts, dim);
+        logosdb_options_set_max_elements(opts, max_elements);
+        logosdb_options_set_ef_construction(opts, ef_construction);
+        logosdb_options_set_M(opts, M);
+        logosdb_options_set_ef_search(opts, ef_search);
+        logosdb_options_set_distance(opts, distance);
+
+        char* err = nullptr;
+        db_ = logosdb_open(path.c_str(), opts, &err);
+        logosdb_options_destroy(opts);
+
+        if (!db_) {
+            std::string error_msg = err ? err : "Unknown error opening database";
+            if (err) free(err);
+            throw Napi::Error::New(env, error_msg);
+        }
+
+        dim_ = dim;
+    }
+
+    ~DBWrapper() {
+        if (db_) {
+            logosdb_close(db_);
+            db_ = nullptr;
+        }
+    }
+
+private:
+    logosdb_t* db_ = nullptr;
+    int dim_ = 0;
+
+    Napi::Value Put(const Napi::CallbackInfo& info) {
+        Napi::Env env = info.Env();
+
+        if (info.Length() < 1 || !info[0].IsArray()) {
+            throw Napi::TypeError::New(env, "Embedding (array) expected as first argument");
+        }
+
+        Napi::Array embeddingArr = info[0].As<Napi::Array>();
+        std::vector<float> embedding = JsArrayToFloatVector(embeddingArr);
+
+        if ((int)embedding.size() != dim_) {
+            throw Napi::Error::New(env, "Embedding dimension mismatch");
+        }
+
+        const char* text = nullptr;
+        const char* timestamp = nullptr;
+
+        if (info.Length() > 1 && info[1].IsString()) {
+            text_str_ = info[1].As<Napi::String>().Utf8Value();
+            text = text_str_.c_str();
+        }
+
+        if (info.Length() > 2 && info[2].IsString()) {
+            ts_str_ = info[2].As<Napi::String>().Utf8Value();
+            timestamp = ts_str_.c_str();
+        }
+
+        char* err = nullptr;
+        uint64_t id = logosdb_put(db_, embedding.data(), dim_, text, timestamp, &err);
+
+        if (id == UINT64_MAX) {
+            std::string error_msg = err ? err : "Failed to insert";
+            if (err) free(err);
+            throw Napi::Error::New(env, error_msg);
+        }
+
+        if (err) free(err);
+
+        return Napi::Number::New(env, static_cast<double>(id));
+    }
+
+    // Storage for string references during put calls
+    std::string text_str_;
+    std::string ts_str_;
+
+    Napi::Value Search(const Napi::CallbackInfo& info) {
+        Napi::Env env = info.Env();
+
+        if (info.Length() < 1 || !info[0].IsArray()) {
+            throw Napi::TypeError::New(env, "Query embedding (array) expected as first argument");
+        }
+
+        Napi::Array queryArr = info[0].As<Napi::Array>();
+        std::vector<float> query = JsArrayToFloatVector(queryArr);
+
+        if ((int)query.size() != dim_) {
+            throw Napi::Error::New(env, "Query dimension mismatch");
+        }
+
+        int top_k = 10;
+        if (info.Length() > 1 && info[1].IsNumber()) {
+            top_k = info[1].As<Napi::Number>().Int32Value();
+        }
+
+        char* err = nullptr;
+        logosdb_search_result_t* result = logosdb_search(db_, query.data(), dim_, top_k, &err);
+
+        if (!result) {
+            std::string error_msg = err ? err : "Search failed";
+            if (err) free(err);
+            throw Napi::Error::New(env, error_msg);
+        }
+
+        if (err) free(err);
+
+        int count = logosdb_result_count(result);
+        Napi::Array results = Napi::Array::New(env, count);
+
+        for (int i = 0; i < count; i++) {
+            results.Set(i, SearchHitToJsObject(env, result, i));
+        }
+
+        logosdb_result_free(result);
+
+        return results;
+    }
+
+    Napi::Value SearchTsRange(const Napi::CallbackInfo& info) {
+        Napi::Env env = info.Env();
+
+        if (info.Length() < 1 || !info[0].IsArray()) {
+            throw Napi::TypeError::New(env, "Query embedding (array) expected");
+        }
+
+        Napi::Array queryArr = info[0].As<Napi::Array>();
+        std::vector<float> query = JsArrayToFloatVector(queryArr);
+
+        if ((int)query.size() != dim_) {
+            throw Napi::Error::New(env, "Query dimension mismatch");
+        }
+
+        int top_k = 10;
+        std::string ts_from;
+        std::string ts_to;
+        int candidate_k = 0;
+
+        if (info.Length() > 1 && info[1].IsObject()) {
+            Napi::Object options = info[1].As<Napi::Object>();
+
+            if (options.Has("topK")) {
+                top_k = options.Get("topK").As<Napi::Number>().Int32Value();
+            }
+            if (options.Has("tsFrom")) {
+                ts_from = options.Get("tsFrom").As<Napi::String>().Utf8Value();
+            }
+            if (options.Has("tsTo")) {
+                ts_to = options.Get("tsTo").As<Napi::String>().Utf8Value();
+            }
+            if (options.Has("candidateK")) {
+                candidate_k = options.Get("candidateK").As<Napi::Number>().Int32Value();
+            }
+        }
+
+        if (candidate_k < top_k) {
+            candidate_k = top_k * 10;  // Default 10x
+        }
+
+        char* err = nullptr;
+        logosdb_search_result_t* result = logosdb_search_ts_range(
+            db_, query.data(), dim_, top_k,
+            ts_from.empty() ? nullptr : ts_from.c_str(),
+            ts_to.empty() ? nullptr : ts_to.c_str(),
+            candidate_k,
+            &err
+        );
+
+        if (!result) {
+            std::string error_msg = err ? err : "Search failed";
+            if (err) free(err);
+            throw Napi::Error::New(env, error_msg);
+        }
+
+        if (err) free(err);
+
+        int count = logosdb_result_count(result);
+        Napi::Array results = Napi::Array::New(env, count);
+
+        for (int i = 0; i < count; i++) {
+            results.Set(i, SearchHitToJsObject(env, result, i));
+        }
+
+        logosdb_result_free(result);
+
+        return results;
+    }
+
+    Napi::Value Update(const Napi::CallbackInfo& info) {
+        Napi::Env env = info.Env();
+
+        if (info.Length() < 2 || !info[0].IsNumber() || !info[1].IsArray()) {
+            throw Napi::TypeError::New(env, "Expected (id, embedding, [text], [timestamp])");
+        }
+
+        uint64_t id = static_cast<uint64_t>(info[0].As<Napi::Number>().Int64Value());
+
+        Napi::Array embeddingArr = info[1].As<Napi::Array>();
+        std::vector<float> embedding = JsArrayToFloatVector(embeddingArr);
+
+        if ((int)embedding.size() != dim_) {
+            throw Napi::Error::New(env, "Embedding dimension mismatch");
+        }
+
+        const char* text = nullptr;
+        const char* timestamp = nullptr;
+
+        if (info.Length() > 2 && info[2].IsString()) {
+            text_str_ = info[2].As<Napi::String>().Utf8Value();
+            text = text_str_.c_str();
+        }
+
+        if (info.Length() > 3 && info[3].IsString()) {
+            ts_str_ = info[3].As<Napi::String>().Utf8Value();
+            timestamp = ts_str_.c_str();
+        }
+
+        char* err = nullptr;
+        uint64_t new_id = logosdb_update(db_, id, embedding.data(), dim_, text, timestamp, &err);
+
+        if (new_id == UINT64_MAX) {
+            std::string error_msg = err ? err : "Update failed";
+            if (err) free(err);
+            throw Napi::Error::New(env, error_msg);
+        }
+
+        if (err) free(err);
+
+        return Napi::Number::New(env, static_cast<double>(new_id));
+    }
+
+    Napi::Value Delete(const Napi::CallbackInfo& info) {
+        Napi::Env env = info.Env();
+
+        if (info.Length() < 1 || !info[0].IsNumber()) {
+            throw Napi::TypeError::New(env, "ID (number) expected");
+        }
+
+        uint64_t id = static_cast<uint64_t>(info[0].As<Napi::Number>().Int64Value());
+
+        char* err = nullptr;
+        int rc = logosdb_delete(db_, id, &err);
+
+        if (rc != 0) {
+            std::string error_msg = err ? err : "Delete failed";
+            if (err) free(err);
+            throw Napi::Error::New(env, error_msg);
+        }
+
+        if (err) free(err);
+        return env.Undefined();
+    }
+
+    Napi::Value Count(const Napi::CallbackInfo& info) {
+        Napi::Env env = info.Env();
+        size_t count = logosdb_count(db_);
+        return Napi::Number::New(env, static_cast<double>(count));
+    }
+
+    Napi::Value CountLive(const Napi::CallbackInfo& info) {
+        Napi::Env env = info.Env();
+        size_t count = logosdb_count_live(db_);
+        return Napi::Number::New(env, static_cast<double>(count));
+    }
+
+    Napi::Value Dim(const Napi::CallbackInfo& info) {
+        Napi::Env env = info.Env();
+        return Napi::Number::New(env, dim_);
+    }
+
+    Napi::Value Close(const Napi::CallbackInfo& info) {
+        Napi::Env env = info.Env();
+        if (db_) {
+            logosdb_close(db_);
+            db_ = nullptr;
+        }
+        return env.Undefined();
+    }
+};
+
+// Constants
+static void DefineConstants(Napi::Env env, Napi::Object exports) {
+    exports.Set("DIST_IP", Napi::Number::New(env, LOGOSDB_DIST_IP));
+    exports.Set("DIST_COSINE", Napi::Number::New(env, LOGOSDB_DIST_COSINE));
+    exports.Set("DIST_L2", Napi::Number::New(env, LOGOSDB_DIST_L2));
+    exports.Set("VERSION", Napi::String::New(env, LOGOSDB_VERSION_STRING));
+}
+
+// Module initialization
+static Napi::Object Init(Napi::Env env, Napi::Object exports) {
+    DBWrapper::Init(env, exports);
+    DefineConstants(env, exports);
+    return exports;
+}
+
+NODE_API_MODULE(logosdb, Init)

package/test/test.js

@@ -0,0 +1,320 @@
+/**
+ * LogosDB Node.js bindings tests
+ */
+
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { DB, DIST_IP, DIST_COSINE, DIST_L2, VERSION } = require('../lib');
+
+// Helper to generate random unit vector
+function randomUnitVector(dim, seed = 0) {
+  const vec = new Array(dim);
+  let sum = 0;
+
+  // Simple pseudo-random for deterministic tests
+  let state = seed;
+  for (let i = 0; i < dim; i++) {
+    state = (state * 9301 + 49297) % 233280;
+    const rnd = state / 233280;
+    vec[i] = rnd * 2 - 1;  // -1 to 1
+    sum += vec[i] * vec[i];
+  }
+
+  // Normalize
+  const norm = Math.sqrt(sum);
+  return vec.map(v => v / norm);
+}
+
+// Helper to create temp directory
+function createTempDir(prefix = 'logosdb-test-') {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+// Helper to cleanup
+function cleanup(dir) {
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+  } catch (e) {
+    // Ignore cleanup errors
+  }
+}
+
+describe('LogosDB Node.js', function() {
+  this.timeout(10000);  // 10 second timeout for tests
+
+  describe('Constants', () => {
+    it('should export distance constants', () => {
+      assert.strictEqual(typeof DIST_IP, 'number');
+      assert.strictEqual(typeof DIST_COSINE, 'number');
+      assert.strictEqual(typeof DIST_L2, 'number');
+    });
+
+    it('should export version', () => {
+      assert.strictEqual(typeof VERSION, 'string');
+      assert.ok(VERSION.match(/^\d+\.\d+\.\d+/));
+    });
+  });
+
+  describe('DB Creation', () => {
+    let dbPath;
+
+    afterEach(() => {
+      if (dbPath) cleanup(dbPath);
+    });
+
+    it('should create a new database', () => {
+      dbPath = createTempDir();
+      const db = new DB(dbPath, { dim: 128 });
+      assert.ok(db);
+      assert.strictEqual(db.dim(), 128);
+      db.close();
+    });
+
+    it('should use default options', () => {
+      dbPath = createTempDir();
+      const db = new DB(dbPath);
+      assert.strictEqual(db.dim(), 128);  // default
+      db.close();
+    });
+
+    it('should support custom options', () => {
+      dbPath = createTempDir();
+      const db = new DB(dbPath, {
+        dim: 256,
+        maxElements: 10000,
+        efConstruction: 100,
+        M: 8,
+        efSearch: 30,
+        distance: DIST_COSINE
+      });
+      assert.strictEqual(db.dim(), 256);
+      db.close();
+    });
+  });
+
+  describe('Basic Operations', () => {
+    let db, dbPath;
+
+    beforeEach(() => {
+      dbPath = createTempDir();
+      db = new DB(dbPath, { dim: 64 });
+    });
+
+    afterEach(() => {
+      if (db) db.close();
+      cleanup(dbPath);
+    });
+
+    it('should put and return an id', () => {
+      const vec = randomUnitVector(64, 1);
+      const id = db.put(vec, 'test text', '2025-01-01T00:00:00Z');
+      assert.strictEqual(typeof id, 'number');
+      assert.ok(id >= 0);
+    });
+
+    it('should put without text and timestamp', () => {
+      const vec = randomUnitVector(64, 2);
+      const id = db.put(vec);
+      assert.strictEqual(typeof id, 'number');
+    });
+
+    it('should count documents', () => {
+      assert.strictEqual(db.count(), 0);
+      assert.strictEqual(db.countLive(), 0);
+
+      db.put(randomUnitVector(64, 3));
+      assert.strictEqual(db.count(), 1);
+      assert.strictEqual(db.countLive(), 1);
+    });
+  });
+
+  describe('Search', () => {
+    let db, dbPath;
+
+    beforeEach(() => {
+      dbPath = createTempDir();
+      db = new DB(dbPath, { dim: 64, distance: DIST_COSINE });
+    });
+
+    afterEach(() => {
+      if (db) db.close();
+      cleanup(dbPath);
+    });
+
+    it('should search and return hits', () => {
+      const vec1 = randomUnitVector(64, 10);
+      const vec2 = randomUnitVector(64, 11);
+      const vec3 = randomUnitVector(64, 12);
+
+      db.put(vec1, 'first');
+      db.put(vec2, 'second');
+      db.put(vec3, 'third');
+
+      const hits = db.search(vec1, 3);
+      assert.ok(Array.isArray(hits));
+      assert.ok(hits.length <= 3);
+
+      if (hits.length > 0) {
+        assert.ok(hits[0].id >= 0);
+        assert.ok(hits[0].score > 0);
+        assert.ok(typeof hits[0].text === 'string' || hits[0].text === null);
+      }
+    });
+
+    it('should find similar vectors', () => {
+      // Use same seed to get identical vectors
+      const vec = randomUnitVector(64, 20);
+
+      db.put(vec, 'original');
+
+      // Search with same vector
+      const hits = db.search(vec, 1);
+      assert.strictEqual(hits.length, 1);
+      assert.strictEqual(hits[0].text, 'original');
+      assert.ok(hits[0].score > 0.99, 'Self-similarity should be ~1.0');
+    });
+  });
+
+  describe('Timestamp Range Search', () => {
+    let db, dbPath;
+
+    beforeEach(() => {
+      dbPath = createTempDir();
+      db = new DB(dbPath, { dim: 32, distance: DIST_COSINE });
+    });
+
+    afterEach(() => {
+      if (db) db.close();
+      cleanup(dbPath);
+    });
+
+    it('should search with timestamp filter', () => {
+      const vec = randomUnitVector(32, 30);
+
+      db.put(vec, 'early', '2025-01-01T00:00:00Z');
+      db.put(vec, 'mid', '2025-01-15T00:00:00Z');
+      db.put(vec, 'late', '2025-02-01T00:00:00Z');
+
+      const hits = db.searchTsRange(vec, {
+        topK: 10,
+        tsFrom: '2025-01-01T00:00:00Z',
+        tsTo: '2025-01-31T23:59:59Z'
+      });
+
+      assert.ok(hits.length >= 2);
+      // Should find early and mid, but not late
+      const texts = hits.map(h => h.text);
+      assert.ok(texts.includes('early'));
+      assert.ok(texts.includes('mid'));
+    });
+  });
+
+  describe('Update and Delete', () => {
+    let db, dbPath;
+
+    beforeEach(() => {
+      dbPath = createTempDir();
+      db = new DB(dbPath, { dim: 32, distance: DIST_COSINE });
+    });
+
+    afterEach(() => {
+      if (db) db.close();
+      cleanup(dbPath);
+    });
+
+    it('should update a row', () => {
+      const vec = randomUnitVector(32, 40);
+      const id = db.put(vec, 'original');
+
+      const newVec = randomUnitVector(32, 41);
+      const newId = db.update(id, newVec, 'updated');
+
+      assert.strictEqual(typeof newId, 'number');
+      assert.ok(newId > id);
+      assert.strictEqual(db.countLive(), 1);  // Old marked deleted, new added
+      assert.strictEqual(db.count(), 2);  // Total includes both
+    });
+
+    it('should delete a row', () => {
+      const vec = randomUnitVector(32, 50);
+      const id = db.put(vec, 'to delete');
+
+      assert.strictEqual(db.countLive(), 1);
+
+      db.delete(id);
+
+      assert.strictEqual(db.countLive(), 0);
+      assert.strictEqual(db.count(), 1);  // Still counted but marked deleted
+    });
+  });
+
+  describe('Error Handling', () => {
+    let dbPath;
+
+    afterEach(() => {
+      cleanup(dbPath);
+    });
+
+    it('should throw on dimension mismatch', () => {
+      dbPath = createTempDir();
+      const db = new DB(dbPath, { dim: 64 });
+
+      assert.throws(() => {
+        db.put(randomUnitVector(32));  // Wrong dimension
+      }, /dimension/);
+
+      db.close();
+    });
+
+    it('should throw on closed database access', () => {
+      dbPath = createTempDir();
+      const db = new DB(dbPath, { dim: 64 });
+      db.close();
+
+      assert.throws(() => {
+        db.put(randomUnitVector(64));
+      }, /closed/);
+    });
+  });
+
+  describe('Persistence', () => {
+    let dbPath;
+
+    afterEach(() => {
+      cleanup(dbPath);
+    });
+
+    it('should persist data across reopen', () => {
+      dbPath = createTempDir();
+
+      // First session: insert
+      let db1 = new DB(dbPath, { dim: 32, distance: DIST_COSINE });
+      const vec = randomUnitVector(32, 60);
+      const id = db1.put(vec, 'persistent');
+      db1.close();
+
+      // Second session: verify
+      let db2 = new DB(dbPath, { dim: 32, distance: DIST_COSINE });
+      assert.strictEqual(db2.countLive(), 1);
+
+      const hits = db2.search(vec, 1);
+      assert.strictEqual(hits.length, 1);
+      assert.strictEqual(hits[0].text, 'persistent');
+      db2.close();
+    });
+  });
+});
+
+// Run tests if executed directly
+if (require.main === module) {
+  const Mocha = require('mocha');
+  const mocha = new Mocha();
+  mocha.suite.emit('pre-require', global, 'test.js', mocha);
+
+  // Simple test runner for standalone execution
+  console.log('Running LogosDB Node.js tests...\n');
+}

package/types/index.d.ts

@@ -0,0 +1,138 @@
+/**
+ * LogosDB - Fast semantic vector database (HNSW + mmap)
+ * TypeScript definitions
+ */
+
+/**
+ * Search result hit
+ */
+export interface SearchHit {
+  /** Row ID */
+  id: number;
+  /** Similarity score (0-1) */
+  score: number;
+  /** Associated text */
+  text: string | null;
+  /** ISO 8601 timestamp */
+  timestamp: string | null;
+}
+
+/**
+ * Database options
+ */
+export interface DBOptions {
+  /** Vector dimension (default: 128) */
+  dim?: number;
+  /** Maximum capacity (default: 1,000,000) */
+  maxElements?: number;
+  /** HNSW construction parameter (default: 200) */
+  efConstruction?: number;
+  /** HNSW M parameter (default: 16) */
+  M?: number;
+  /** HNSW search parameter (default: 50) */
+  efSearch?: number;
+  /** Distance metric (default: DIST_IP) */
+  distance?: number;
+}
+
+/**
+ * Timestamp range search options
+ */
+export interface TsRangeOptions {
+  /** Number of results (default: 10) */
+  topK?: number;
+  /** Start timestamp (inclusive) */
+  tsFrom?: string;
+  /** End timestamp (inclusive) */
+  tsTo?: string;
+  /** Internal candidate multiplier */
+  candidateK?: number;
+}
+
+/**
+ * LogosDB database instance
+ */
+export class DB {
+  /**
+   * Create a new LogosDB instance
+   * @param path - Database directory path
+   * @param options - Database options
+   */
+  constructor(path: string, options?: DBOptions);
+
+  /**
+   * Insert a vector with optional text and timestamp
+   * @param embedding - Float vector
+   * @param text - Optional text metadata
+   * @param timestamp - Optional ISO 8601 timestamp
+   * @returns Assigned row ID
+   */
+  put(embedding: number[], text?: string, timestamp?: string): number;
+
+  /**
+   * Search for similar vectors
+   * @param queryEmbedding - Query vector
+   * @param topK - Number of results (default: 10)
+   * @returns Search results
+   */
+  search(queryEmbedding: number[], topK?: number): SearchHit[];
+
+  /**
+   * Search with timestamp range filter
+   * @param queryEmbedding - Query vector
+   * @param options - Search options
+   * @returns Search results
+   */
+  searchTsRange(queryEmbedding: number[], options?: TsRangeOptions): SearchHit[];
+
+  /**
+   * Update an existing row (marks old as deleted, creates new)
+   * @param id - Row ID to update
+   * @param embedding - New embedding
+   * @param text - New text
+   * @param timestamp - New timestamp
+   * @returns New row ID
+   */
+  update(id: number, embedding: number[], text?: string, timestamp?: string): number;
+
+  /**
+   * Delete a row by ID
+   * @param id - Row ID to delete
+   */
+  delete(id: number): void;
+
+  /**
+   * Get total row count (including deleted)
+   * @returns Total count
+   */
+  count(): number;
+
+  /**
+   * Get live row count (excluding deleted)
+   * @returns Live count
+   */
+  countLive(): number;
+
+  /**
+   * Get vector dimension
+   * @returns Dimension
+   */
+  dim(): number;
+
+  /**
+   * Close the database
+   */
+  close(): void;
+}
+
+/** Inner product distance (default, requires L2-normalized vectors) */
+export const DIST_IP: number;
+
+/** Cosine similarity (auto-normalizes vectors) */
+export const DIST_COSINE: number;
+
+/** Euclidean distance (L2 space) */
+export const DIST_L2: number;
+
+/** Library version string */
+export const VERSION: string;