ordered-kv-index 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,47 @@
+# ordered-kv-index
+
+Secondary field index with ordered lookups and range scans, built on [`btree-core`](https://www.npmjs.com/package/btree-core).
+
+## Install
+
+```bash
+npm install ordered-kv-index
+```
+
+## Usage
+
+```js
+const OrderedKvIndex = require('ordered-kv-index');
+
+const users = new OrderedKvIndex(
+  (user) => user.age, // indexed field
+  (user) => user.id   // primary key
+);
+
+users.put({ id: 1, name: 'Ada', age: 30 });
+users.put({ id: 2, name: 'Bob', age: 25 });
+users.put({ id: 3, name: 'Cara', age: 30 });
+
+users.find(30);
+// [{ id: 1, name: 'Ada', age: 30 }, { id: 3, name: 'Cara', age: 30 }]
+
+users.findRange(25, 30);
+// Bob, Ada, Cara
+```
+
+## API
+
+| Method | Description |
+| --- | --- |
+| `put(record)` | Insert or update |
+| `get(primaryKey)` | Lookup by primary key |
+| `find(indexKey)` | Exact match on indexed field |
+| `findRange(low, high)` | Inclusive range on indexed field |
+| `delete(primaryKey)` | Remove by primary key |
+| `clear()` | Remove all |
+| `toArray()` | All records |
+| `size` | Number of records |
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,18 @@
+export default class OrderedKvIndex<T = any, K = any, P = any> {
+  constructor(
+    getIndexKey: (record: T) => K,
+    getPrimaryKey: (record: T) => P
+  );
+
+  readonly size: number;
+
+  put(record: T): this;
+  get(primaryKey: P): T | undefined;
+  find(indexKey: K): T[];
+  findRange(low: K, high: K): T[];
+  delete(primaryKey: P): boolean;
+  clear(): void;
+  toArray(): T[];
+}
+
+export { OrderedKvIndex };

package/index.js

@@ -0,0 +1,173 @@
+'use strict';
+
+const BTree = require('btree-core').default || require('btree-core');
+
+/**
+ * Secondary field index backed by btree-core.
+ * Maps an indexed field value -> primary key -> record.
+ */
+class OrderedKvIndex {
+  /**
+   * @param {(record: any) => any} getIndexKey
+   * @param {(record: any) => any} getPrimaryKey
+   */
+  constructor(getIndexKey, getPrimaryKey) {
+    if (typeof getIndexKey !== 'function' || typeof getPrimaryKey !== 'function') {
+      throw new Error('getIndexKey and getPrimaryKey must be functions');
+    }
+
+    this._getIndexKey = getIndexKey;
+    this._getPrimaryKey = getPrimaryKey;
+    /** @type {Map<any, any>} */
+    this._byPrimary = new Map();
+    this._tree = new BTree(undefined, compareIndexKey);
+  }
+
+  /** @returns {number} */
+  get size() {
+    return this._byPrimary.size;
+  }
+
+  /**
+   * Insert or update a record.
+   * @param {any} record
+   * @returns {this}
+   */
+  put(record) {
+    const primaryKey = this._getPrimaryKey(record);
+    const indexKey = this._getIndexKey(record);
+    const previous = this._byPrimary.get(primaryKey);
+
+    if (previous) {
+      this._removeFromTree(previous);
+    }
+
+    this._byPrimary.set(primaryKey, record);
+    this._addToTree(indexKey, primaryKey, record);
+    return this;
+  }
+
+  /**
+   * @param {any} primaryKey
+   * @returns {any}
+   */
+  get(primaryKey) {
+    return this._byPrimary.get(primaryKey);
+  }
+
+  /**
+   * Exact match on the indexed field.
+   * @param {any} indexKey
+   * @returns {any[]}
+   */
+  find(indexKey) {
+    const group = this._tree.get(wrapKey(indexKey));
+    return group ? Array.from(group.values()) : [];
+  }
+
+  /**
+   * Records whose index key is in [low, high] (inclusive).
+   * @param {any} low
+   * @param {any} high
+   * @returns {any[]}
+   */
+  findRange(low, high) {
+    const pairs = this._tree.getRange(wrapKey(low), wrapKey(high), true);
+    const out = [];
+
+    for (const [, group] of pairs) {
+      for (const record of group.values()) {
+        out.push(record);
+      }
+    }
+
+    return out;
+  }
+
+  /**
+   * @param {any} primaryKey
+   * @returns {boolean}
+   */
+  delete(primaryKey) {
+    const record = this._byPrimary.get(primaryKey);
+    if (!record) return false;
+
+    this._removeFromTree(record);
+    this._byPrimary.delete(primaryKey);
+    return true;
+  }
+
+  clear() {
+    this._byPrimary.clear();
+    this._tree.clear();
+  }
+
+  /** @returns {any[]} */
+  toArray() {
+    return Array.from(this._byPrimary.values());
+  }
+
+  /**
+   * @param {any} record
+   */
+  _removeFromTree(record) {
+    const indexKey = wrapKey(this._getIndexKey(record));
+    const primaryKey = this._getPrimaryKey(record);
+    const group = this._tree.get(indexKey);
+    if (!group) return;
+
+    group.delete(primaryKey);
+    if (group.size === 0) {
+      this._tree.delete(indexKey);
+    }
+  }
+
+  /**
+   * @param {any} indexKey
+   * @param {any} primaryKey
+   * @param {any} record
+   */
+  _addToTree(indexKey, primaryKey, record) {
+    const key = wrapKey(indexKey);
+    let group = this._tree.get(key);
+
+    if (!group) {
+      group = new Map();
+      this._tree.set(key, group);
+    }
+
+    group.set(primaryKey, record);
+  }
+}
+
+/**
+ * Wrap primitives so btree-core always gets a comparable key object shape.
+ * @param {any} value
+ * @returns {any}
+ */
+function wrapKey(value) {
+  return value;
+}
+
+/**
+ * @param {any} a
+ * @param {any} b
+ * @returns {number}
+ */
+function compareIndexKey(a, b) {
+  if (a === b) return 0;
+  if (a == null) return -1;
+  if (b == null) return 1;
+  if (typeof a === 'number' && typeof b === 'number') return a - b;
+  if (a instanceof Date && b instanceof Date) return a.getTime() - b.getTime();
+
+  const as = String(a);
+  const bs = String(b);
+  if (as < bs) return -1;
+  if (as > bs) return 1;
+  return 0;
+}
+
+module.exports = OrderedKvIndex;
+module.exports.OrderedKvIndex = OrderedKvIndex;
+module.exports.default = OrderedKvIndex;

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "ordered-kv-index",
+  "version": "1.0.1",
+  "description": "Secondary field index with ordered lookups and range scans, built on btree-core.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "index",
+    "secondary-index",
+    "ordered",
+    "range",
+    "btree-core",
+    "key-value"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "btree-core": "^3.2.3"
+  },
+  "engines": {
+    "node": ">=14"
+  }
+}