@lp-labs/time-series-index 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Libin Prasanth
+
+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

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @lp-labs/time-series-index
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A bounded in-memory index for numeric time series with sorted range retrieval and fixed-width
+aggregates. Timestamps are safe integer epoch units chosen consistently by the caller.
+
+## Install
+
+```bash
+npm install @lp-labs/time-series-index
+```
+
+Includes ES2022 ESM and CommonJS builds with TypeScript declarations. CommonJS:
+`const { createTimeSeriesIndex } = require('@lp-labs/time-series-index')`.
+
+## Quickstart
+
+```js
+import { createTimeSeriesIndex } from '@lp-labs/time-series-index';
+
+const index = createTimeSeriesIndex();
+index.upsert('temperature', { timestamp: 1000, value: 18.5 });
+index.upsert('temperature', { timestamp: 2000, value: 19 });
+console.log(index.query('temperature', { from: 1000, to: 1500 }));
+console.log(index.aggregate('temperature', 1000));
+```
+
+## API
+
+- `createTimeSeriesIndex({ maxSeries?, maxPoints? })` defaults to 1,000 series and 1,000,000
+  total points. `maxSeries` is capped at 100,000; `maxPoints` at 10,000,000.
+- `upsert(series, { timestamp, value })` inserts in timestamp order. Re-inserting a timestamp
+  replaces its value without consuming capacity. Timestamps are safe integers; values must be
+  finite numbers.
+- `query(series, { from?, to?, limit? })` returns detached, ascending points in the inclusive
+  range. The default limit is the total point capacity.
+- `aggregate(series, width, { from?, to? })` returns occupied, epoch-aligned buckets containing
+  `[start, end)` boundaries, count, sum, min, max and average. `width` is a positive safe integer.
+- `removeSeries`, `clear`, `seriesCount`, and `pointCount` manage and report state.
+
+Unknown series throw `TimeSeriesIndexError` with code `unknown-series`; capacity failures use
+code `capacity`. Validate timestamps and units at your application boundary (milliseconds,
+seconds and other epochs are not inferred).
+
+## Customization and limitations
+
+The index is process-local, single-threaded, and stores raw points in JavaScript arrays. Insert
+and query are O(log n) lookup plus O(n) array movement/copying for a series; queries and bucket
+aggregation are linear in returned/scanned points. There is no retention policy, persistence,
+interpolation, gap filling, timezone/calendar bucketing, counter-rate logic, distributed
+replication, or arbitrary dimensional metrics. Aggregation uses ordinary floating-point sums and
+includes only observed buckets.
+
+## Support
+
+If this library is useful to you, consider supporting its maintenance with a [donation via PayPal](https://www.paypal.me/LibinPrasanth).
+
+## Author
+
+Created by [Libin Prasanth](https://www.linkedin.com/in/libinprasanth/). Connect on LinkedIn for updates and discussion.

package/dist/cjs/index.d.ts

@@ -0,0 +1,36 @@
+export interface DataPoint {
+    timestamp: number;
+    value: number;
+}
+export interface TimeSeriesOptions {
+    maxSeries?: number;
+    maxPoints?: number;
+}
+export interface QueryRange {
+    from?: number;
+    to?: number;
+    limit?: number;
+}
+export interface Bucket {
+    start: number;
+    end: number;
+    count: number;
+    sum: number;
+    min: number;
+    max: number;
+    average: number;
+}
+export interface TimeSeriesIndex {
+    readonly seriesCount: number;
+    readonly pointCount: number;
+    upsert(series: string, point: DataPoint): void;
+    removeSeries(series: string): boolean;
+    query(series: string, range?: QueryRange): DataPoint[];
+    aggregate(series: string, width: number, range?: QueryRange): Bucket[];
+    clear(): void;
+}
+export declare class TimeSeriesIndexError extends Error {
+    readonly code: 'capacity' | 'unknown-series';
+    constructor(code: 'capacity' | 'unknown-series', message: string);
+}
+export declare function createTimeSeriesIndex(options?: TimeSeriesOptions): TimeSeriesIndex;

package/dist/cjs/index.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeSeriesIndexError = void 0;
+exports.createTimeSeriesIndex = createTimeSeriesIndex;
+class TimeSeriesIndexError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'TimeSeriesIndexError';
+    }
+}
+exports.TimeSeriesIndexError = TimeSeriesIndexError;
+const isRecord = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+function assertPlainObject(value, name) {
+    if (!isRecord(value))
+        throw new TypeError(`${name} must be a plain object.`);
+}
+function bounded(value, name, minimum, maximum) {
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw new RangeError(`${name} must be an integer from ${minimum} through ${maximum}.`);
+    }
+    return value;
+}
+function validateSeries(value) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > 256) {
+        throw new TypeError('Series name must be a non-empty string of at most 256 characters.');
+    }
+}
+function validateTime(value, name) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+        throw new TypeError(`${name} must be a safe integer timestamp.`);
+    }
+}
+function createTimeSeriesIndex(options = {}) {
+    assertPlainObject(options, 'Options');
+    const maxSeries = bounded(options.maxSeries ?? 1000, 'maxSeries', 1, 100_000);
+    const maxPoints = bounded(options.maxPoints ?? 1_000_000, 'maxPoints', 1, 10_000_000);
+    const seriesMap = new Map();
+    let pointCount = 0;
+    const requireSeries = (name) => {
+        validateSeries(name);
+        const points = seriesMap.get(name);
+        if (!points)
+            throw new TimeSeriesIndexError('unknown-series', `Unknown series: ${name}`);
+        return points;
+    };
+    const rangeValues = (range = {}) => {
+        assertPlainObject(range, 'Range');
+        const from = range.from;
+        const to = range.to;
+        if (from !== undefined)
+            validateTime(from, 'from');
+        if (to !== undefined)
+            validateTime(to, 'to');
+        if (from !== undefined && to !== undefined && from > to)
+            throw new RangeError('from must not exceed to.');
+        const limit = bounded(range.limit ?? maxPoints, 'limit', 0, maxPoints);
+        return { from: from ?? Number.MIN_SAFE_INTEGER, to: to ?? Number.MAX_SAFE_INTEGER, limit };
+    };
+    return {
+        get seriesCount() {
+            return seriesMap.size;
+        },
+        get pointCount() {
+            return pointCount;
+        },
+        upsert(name, input) {
+            validateSeries(name);
+            if (!isRecord(input))
+                throw new TypeError('Point must be a plain object.');
+            validateTime(input.timestamp, 'timestamp');
+            if (typeof input.value !== 'number' || !Number.isFinite(input.value)) {
+                throw new TypeError('Point value must be finite.');
+            }
+            let points = seriesMap.get(name);
+            if (!points) {
+                if (seriesMap.size >= maxSeries)
+                    throw new TimeSeriesIndexError('capacity', 'Series capacity reached.');
+                points = [];
+                seriesMap.set(name, points);
+            }
+            let low = 0;
+            let high = points.length;
+            while (low < high) {
+                const middle = (low + high) >>> 1;
+                if (points[middle].timestamp < input.timestamp)
+                    low = middle + 1;
+                else
+                    high = middle;
+            }
+            const replacing = points[low]?.timestamp === input.timestamp;
+            if (!replacing && pointCount >= maxPoints)
+                throw new TimeSeriesIndexError('capacity', 'Point capacity reached.');
+            const point = Object.freeze({ timestamp: input.timestamp, value: input.value });
+            if (replacing)
+                points[low] = point;
+            else {
+                points.splice(low, 0, point);
+                pointCount++;
+            }
+        },
+        removeSeries(name) {
+            validateSeries(name);
+            const points = seriesMap.get(name);
+            if (!points)
+                return false;
+            pointCount -= points.length;
+            return seriesMap.delete(name);
+        },
+        query(name, range = {}) {
+            const points = requireSeries(name);
+            const { from, to, limit } = rangeValues(range);
+            let low = 0;
+            let high = points.length;
+            while (low < high) {
+                const middle = (low + high) >>> 1;
+                if (points[middle].timestamp < from)
+                    low = middle + 1;
+                else
+                    high = middle;
+            }
+            const output = [];
+            for (let index = low; index < points.length && output.length < limit; index++) {
+                if (points[index].timestamp > to)
+                    break;
+                output.push({ ...points[index] });
+            }
+            return output;
+        },
+        aggregate(name, width, range = {}) {
+            const points = requireSeries(name);
+            if (!Number.isSafeInteger(width) || width <= 0)
+                throw new RangeError('width must be a positive safe integer.');
+            const { from, to, limit } = rangeValues(range);
+            const buckets = new Map();
+            let considered = 0;
+            for (const point of points) {
+                if (point.timestamp < from)
+                    continue;
+                if (point.timestamp > to)
+                    break;
+                if (considered >= limit)
+                    break;
+                considered++;
+                const start = Math.floor(point.timestamp / width) * width;
+                if (!Number.isSafeInteger(start) || !Number.isSafeInteger(start + width)) {
+                    throw new RangeError('Bucket boundaries exceed the safe integer timestamp range.');
+                }
+                let bucket = buckets.get(start);
+                if (!bucket)
+                    buckets.set(start, (bucket = { count: 0, sum: 0, min: Infinity, max: -Infinity }));
+                bucket.count++;
+                bucket.sum += point.value;
+                if (!Number.isFinite(bucket.sum))
+                    throw new RangeError('Bucket sum exceeds finite number range.');
+                bucket.min = Math.min(bucket.min, point.value);
+                bucket.max = Math.max(bucket.max, point.value);
+            }
+            return [...buckets]
+                .sort(([a], [b]) => a - b)
+                .map(([start, bucket]) => ({
+                start,
+                end: start + width,
+                count: bucket.count,
+                sum: bucket.sum,
+                min: bucket.min,
+                max: bucket.max,
+                average: bucket.sum / bucket.count,
+            }));
+        },
+        clear() {
+            seriesMap.clear();
+            pointCount = 0;
+        },
+    };
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,36 @@
+export interface DataPoint {
+    timestamp: number;
+    value: number;
+}
+export interface TimeSeriesOptions {
+    maxSeries?: number;
+    maxPoints?: number;
+}
+export interface QueryRange {
+    from?: number;
+    to?: number;
+    limit?: number;
+}
+export interface Bucket {
+    start: number;
+    end: number;
+    count: number;
+    sum: number;
+    min: number;
+    max: number;
+    average: number;
+}
+export interface TimeSeriesIndex {
+    readonly seriesCount: number;
+    readonly pointCount: number;
+    upsert(series: string, point: DataPoint): void;
+    removeSeries(series: string): boolean;
+    query(series: string, range?: QueryRange): DataPoint[];
+    aggregate(series: string, width: number, range?: QueryRange): Bucket[];
+    clear(): void;
+}
+export declare class TimeSeriesIndexError extends Error {
+    readonly code: 'capacity' | 'unknown-series';
+    constructor(code: 'capacity' | 'unknown-series', message: string);
+}
+export declare function createTimeSeriesIndex(options?: TimeSeriesOptions): TimeSeriesIndex;

package/dist/esm/index.js

@@ -0,0 +1,177 @@
+export class TimeSeriesIndexError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'TimeSeriesIndexError';
+    }
+}
+const isRecord = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+function assertPlainObject(value, name) {
+    if (!isRecord(value))
+        throw new TypeError(`${name} must be a plain object.`);
+}
+function bounded(value, name, minimum, maximum) {
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw new RangeError(`${name} must be an integer from ${minimum} through ${maximum}.`);
+    }
+    return value;
+}
+function validateSeries(value) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > 256) {
+        throw new TypeError('Series name must be a non-empty string of at most 256 characters.');
+    }
+}
+function validateTime(value, name) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+        throw new TypeError(`${name} must be a safe integer timestamp.`);
+    }
+}
+export function createTimeSeriesIndex(options = {}) {
+    assertPlainObject(options, 'Options');
+    const maxSeries = bounded(options.maxSeries ?? 1000, 'maxSeries', 1, 100_000);
+    const maxPoints = bounded(options.maxPoints ?? 1_000_000, 'maxPoints', 1, 10_000_000);
+    const seriesMap = new Map();
+    let pointCount = 0;
+    const requireSeries = (name) => {
+        validateSeries(name);
+        const points = seriesMap.get(name);
+        if (!points)
+            throw new TimeSeriesIndexError('unknown-series', `Unknown series: ${name}`);
+        return points;
+    };
+    const rangeValues = (range = {}) => {
+        assertPlainObject(range, 'Range');
+        const from = range.from;
+        const to = range.to;
+        if (from !== undefined)
+            validateTime(from, 'from');
+        if (to !== undefined)
+            validateTime(to, 'to');
+        if (from !== undefined && to !== undefined && from > to)
+            throw new RangeError('from must not exceed to.');
+        const limit = bounded(range.limit ?? maxPoints, 'limit', 0, maxPoints);
+        return { from: from ?? Number.MIN_SAFE_INTEGER, to: to ?? Number.MAX_SAFE_INTEGER, limit };
+    };
+    return {
+        get seriesCount() {
+            return seriesMap.size;
+        },
+        get pointCount() {
+            return pointCount;
+        },
+        upsert(name, input) {
+            validateSeries(name);
+            if (!isRecord(input))
+                throw new TypeError('Point must be a plain object.');
+            validateTime(input.timestamp, 'timestamp');
+            if (typeof input.value !== 'number' || !Number.isFinite(input.value)) {
+                throw new TypeError('Point value must be finite.');
+            }
+            let points = seriesMap.get(name);
+            if (!points) {
+                if (seriesMap.size >= maxSeries)
+                    throw new TimeSeriesIndexError('capacity', 'Series capacity reached.');
+                points = [];
+                seriesMap.set(name, points);
+            }
+            let low = 0;
+            let high = points.length;
+            while (low < high) {
+                const middle = (low + high) >>> 1;
+                if (points[middle].timestamp < input.timestamp)
+                    low = middle + 1;
+                else
+                    high = middle;
+            }
+            const replacing = points[low]?.timestamp === input.timestamp;
+            if (!replacing && pointCount >= maxPoints)
+                throw new TimeSeriesIndexError('capacity', 'Point capacity reached.');
+            const point = Object.freeze({ timestamp: input.timestamp, value: input.value });
+            if (replacing)
+                points[low] = point;
+            else {
+                points.splice(low, 0, point);
+                pointCount++;
+            }
+        },
+        removeSeries(name) {
+            validateSeries(name);
+            const points = seriesMap.get(name);
+            if (!points)
+                return false;
+            pointCount -= points.length;
+            return seriesMap.delete(name);
+        },
+        query(name, range = {}) {
+            const points = requireSeries(name);
+            const { from, to, limit } = rangeValues(range);
+            let low = 0;
+            let high = points.length;
+            while (low < high) {
+                const middle = (low + high) >>> 1;
+                if (points[middle].timestamp < from)
+                    low = middle + 1;
+                else
+                    high = middle;
+            }
+            const output = [];
+            for (let index = low; index < points.length && output.length < limit; index++) {
+                if (points[index].timestamp > to)
+                    break;
+                output.push({ ...points[index] });
+            }
+            return output;
+        },
+        aggregate(name, width, range = {}) {
+            const points = requireSeries(name);
+            if (!Number.isSafeInteger(width) || width <= 0)
+                throw new RangeError('width must be a positive safe integer.');
+            const { from, to, limit } = rangeValues(range);
+            const buckets = new Map();
+            let considered = 0;
+            for (const point of points) {
+                if (point.timestamp < from)
+                    continue;
+                if (point.timestamp > to)
+                    break;
+                if (considered >= limit)
+                    break;
+                considered++;
+                const start = Math.floor(point.timestamp / width) * width;
+                if (!Number.isSafeInteger(start) || !Number.isSafeInteger(start + width)) {
+                    throw new RangeError('Bucket boundaries exceed the safe integer timestamp range.');
+                }
+                let bucket = buckets.get(start);
+                if (!bucket)
+                    buckets.set(start, (bucket = { count: 0, sum: 0, min: Infinity, max: -Infinity }));
+                bucket.count++;
+                bucket.sum += point.value;
+                if (!Number.isFinite(bucket.sum))
+                    throw new RangeError('Bucket sum exceeds finite number range.');
+                bucket.min = Math.min(bucket.min, point.value);
+                bucket.max = Math.max(bucket.max, point.value);
+            }
+            return [...buckets]
+                .sort(([a], [b]) => a - b)
+                .map(([start, bucket]) => ({
+                start,
+                end: start + width,
+                count: bucket.count,
+                sum: bucket.sum,
+                min: bucket.min,
+                max: bucket.max,
+                average: bucket.sum / bucket.count,
+            }));
+        },
+        clear() {
+            seriesMap.clear();
+            pointCount = 0;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@lp-labs/time-series-index",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A bounded in-memory sorted index for timestamped numeric series.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "npm run build && node scripts/check-types.mjs",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "format": "prettier --write src scripts tests *.json README.md",
+    "format:check": "prettier --check src scripts tests *.json README.md",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "prettier": "^3.6.2"
+  },
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "all",
+    "printWidth": 100,
+    "endOfLine": "lf"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": {
+    "name": "Libin Prasanth",
+    "url": "https://www.linkedin.com/in/libinprasanth/"
+  },
+  "funding": {
+    "type": "paypal",
+    "url": "https://www.paypal.me/LibinPrasanth"
+  }
+}