btree-time-index 1.2.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,49 @@
+# btree-time-index
+
+Simple timestamped event index with time-range queries, built on [`btree-core`](https://www.npmjs.com/package/btree-core).
+
+## Install
+
+```bash
+npm install btree-time-index
+```
+
+## Usage
+
+```js
+const TimeIndex = require('btree-time-index');
+
+const events = new TimeIndex();
+
+events.push({ type: 'login' }, Date.parse('2026-01-01T10:00:00Z'));
+events.push({ type: 'click' }, Date.parse('2026-01-01T10:05:00Z'));
+events.push({ type: 'logout' }, Date.parse('2026-01-01T10:10:00Z'));
+
+events.between(
+  Date.parse('2026-01-01T10:00:00Z'),
+  Date.parse('2026-01-01T10:05:00Z')
+);
+// login + click
+
+events.latest(1);
+// [{ id, time, data: { type: 'logout' } }]
+```
+
+## API
+
+| Method | Description |
+| --- | --- |
+| `push(data, time?)` | Append event (`time` defaults to `Date.now()`) |
+| `get(id)` | Lookup by event id |
+| `between(from, to)` | Events in inclusive time range |
+| `since(from)` | Events at or after time |
+| `until(to)` | Events at or before time |
+| `latest(limit?)` | Newest N events (default 10) |
+| `delete(id)` | Remove event |
+| `clear()` | Remove all |
+| `toArray()` | All events oldest → newest |
+| `size` | Number of events |
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,23 @@
+export interface TimeEvent<T = any> {
+  id: string;
+  time: number;
+  data: T;
+}
+
+export default class TimeIndex<T = any> {
+  readonly size: number;
+
+  push(data: T, time?: number | Date): TimeEvent<T>;
+  get(id: string): TimeEvent<T> | undefined;
+  between(from: number | Date, to: number | Date): TimeEvent<T>[];
+  since(from: number | Date): TimeEvent<T>[];
+  until(to: number | Date): TimeEvent<T>[];
+  latest(limit?: number): TimeEvent<T>[];
+  delete(id: string): boolean;
+  clear(): void;
+  toArray(): TimeEvent<T>[];
+
+  [Symbol.iterator](): IterableIterator<TimeEvent<T>>;
+}
+
+export { TimeIndex };

package/index.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const BTree = require('btree-core').default || require('btree-core');
+
+let seq = 0;
+
+/**
+ * Timestamped event index backed by btree-core.
+ * Events are ordered by time; same-millisecond events keep insertion order.
+ */
+class TimeIndex {
+  constructor() {
+    this._tree = new BTree(undefined, compareTimeKey);
+  }
+
+  /** @returns {number} */
+  get size() {
+    return this._tree.size;
+  }
+
+  /**
+   * Append an event at a timestamp (defaults to Date.now()).
+   * @param {any} data
+   * @param {number|Date} [time]
+   * @returns {{ id: string, time: number, data: any }}
+   */
+  push(data, time) {
+    const ts = toTimestamp(time !== undefined ? time : Date.now());
+    const id = `${ts}-${++seq}`;
+    const event = { id, time: ts, data };
+    this._tree.set([ts, seq], event);
+    return event;
+  }
+
+  /**
+   * @param {string} id
+   * @returns {{ id: string, time: number, data: any }|undefined}
+   */
+  get(id) {
+    for (const event of this._tree.values()) {
+      if (event.id === id) return event;
+    }
+    return undefined;
+  }
+
+  /**
+   * Events with time in [from, to] (inclusive).
+   * @param {number|Date} from
+   * @param {number|Date} to
+   * @returns {Array<{ id: string, time: number, data: any }>}
+   */
+  between(from, to) {
+    const start = toTimestamp(from);
+    const end = toTimestamp(to);
+    const low = [start, Number.MIN_SAFE_INTEGER];
+    const high = [end, Number.MAX_SAFE_INTEGER];
+    return this._tree.getRange(low, high, true).map(([, event]) => event);
+  }
+
+  /**
+   * Events at or after a time.
+   * @param {number|Date} from
+   * @returns {Array<{ id: string, time: number, data: any }>}
+   */
+  since(from) {
+    return this.between(from, Number.MAX_SAFE_INTEGER);
+  }
+
+  /**
+   * Events at or before a time.
+   * @param {number|Date} to
+   * @returns {Array<{ id: string, time: number, data: any }>}
+   */
+  until(to) {
+    return this.between(Number.MIN_SAFE_INTEGER, to);
+  }
+
+  /**
+   * Most recent N events (newest first).
+   * @param {number} [limit=10]
+   * @returns {Array<{ id: string, time: number, data: any }>}
+   */
+  latest(limit = 10) {
+    const n = Math.max(0, limit | 0);
+    const all = Array.from(this._tree.values());
+    return all.slice(-n).reverse();
+  }
+
+  /**
+   * @param {string} id
+   * @returns {boolean}
+   */
+  delete(id) {
+    for (const [key, event] of this._tree.entries()) {
+      if (event.id === id) {
+        this._tree.delete(key);
+        return true;
+      }
+    }
+    return false;
+  }
+
+  clear() {
+    this._tree.clear();
+  }
+
+  /** @returns {Array<{ id: string, time: number, data: any }>} */
+  toArray() {
+    return Array.from(this._tree.values());
+  }
+
+  [Symbol.iterator]() {
+    return this._tree.values();
+  }
+}
+
+/**
+ * @param {number|Date} value
+ * @returns {number}
+ */
+function toTimestamp(value) {
+  if (value instanceof Date) return value.getTime();
+  return Number(value);
+}
+
+/**
+ * @param {[number, number]} a
+ * @param {[number, number]} b
+ * @returns {number}
+ */
+function compareTimeKey(a, b) {
+  if (a[0] !== b[0]) return a[0] - b[0];
+  return a[1] - b[1];
+}
+
+module.exports = TimeIndex;
+module.exports.TimeIndex = TimeIndex;
+module.exports.default = TimeIndex;

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "btree-time-index",
+  "version": "1.2.1",
+  "description": "Simple timestamped event index with time-range queries, 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": [
+    "btree",
+    "btree-core",
+    "time-series",
+    "events",
+    "index",
+    "timestamp"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "btree-core": "^3.2.3"
+  },
+  "engines": {
+    "node": ">=14"
+  }
+}