@lp-labs/temporal-state 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/temporal-state
 
-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.
+Keep bounded, append-only JSON events per key and query the latest value at any retained timestamp.
+Explicit compaction advances a history watermark while preserving a baseline value at the cutoff.
+
+- Zero runtime and peer dependencies; ESM, CommonJS, and TypeScript declarations.
+- Per-key timestamps are nondecreasing; same-time events use append order.
+- In-memory only; no clock, persistence, distributed ordering, or automatic retention timer.
+- [MIT](./LICENSE). Node.js 18+.
+
+## Installation
+
+```sh
+npm install @lp-labs/temporal-state
+```
+
+## Quickstart
+
+```js
+import { createTemporalState } from '@lp-labs/temporal-state';
+
+const state = createTemporalState({ maxEvents: 1000, maxKeys: 100 });
+state.set('cart/42', 1_800_000_000_000, { items: 2 });
+state.set('cart/42', 1_800_000_000_500, { items: 3 });
+console.log(state.getAt('cart/42', 1_800_000_000_200)); // { items: 2 }
+console.log(state.snapshotAt(1_800_000_000_500)); // { 'cart/42': { items: 3 } }
+```
+
+CommonJS: `const { createTemporalState } = require('@lp-labs/temporal-state')`.
+
+## API and retention
+
+`createTemporalState({ maxEvents?, maxKeys?, maxDepth? })` defaults to 10,000 events, 1,000 keys,
+and 64 nesting levels. `set(key, timestampMs, json)` and `delete(key, timestampMs)` append events.
+Keys contain 1..256 characters and timestamps are non-negative safe integer milliseconds. Capacity
+overflow throws `TemporalStateError` with code `capacity`; records are never silently dropped.
+Appending an earlier event for an existing key throws `out-of-order`.
+
+`getAt(key, timestampMs)` returns the cloned value or `undefined` if the key was not present.
+`snapshotAt(timestampMs)` returns a frozen plain record excluding deleted/absent keys.
+`compact(beforeMs)` removes superseded history through the cutoff and returns the number of events
+removed. It preserves the state as of the cutoff (including deletion) as a baseline. Queries strictly
+before the watermark and appends before it throw `pruned`; moving the watermark backward throws
+`conflict`. `snapshot()` reports retained event/key counts, `oldestAvailableAt` and latest event time.
+
+## Customization and limitations
+
+Choose timestamp units consistently and persist/rebuild events in your application if needed. Values
+are cloned JSON, not arbitrary objects. Storage is process-local and bounded; no automatic expiry,
+global ordering across keys, clock-skew correction, event sourcing integration, or historical query
+before compaction is provided. A caller must decide a safe retention cutoff.
+
+## 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,26 @@
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export interface TemporalOptions {
+    readonly maxEvents?: number;
+    readonly maxKeys?: number;
+    readonly maxDepth?: number;
+}
+export interface TemporalSnapshot {
+    readonly events: number;
+    readonly keys: number;
+    readonly oldestAvailableAt: number;
+    readonly latestAt?: number;
+}
+export declare class TemporalStateError extends Error {
+    readonly code: 'invalid' | 'capacity' | 'out-of-order' | 'pruned' | 'conflict';
+    constructor(code: 'invalid' | 'capacity' | 'out-of-order' | 'pruned' | 'conflict', message: string);
+}
+export declare function createTemporalState(options?: TemporalOptions): Readonly<{
+    set(key: string, at: number, value: unknown): void;
+    delete(key: string, at: number): void;
+    getAt(key: string, atInput: number): Json | undefined;
+    snapshotAt(atInput: number): Readonly<Record<string, Json>>;
+    compact(beforeInput: number): number;
+    snapshot(): TemporalSnapshot;
+}>;

package/dist/cjs/index.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TemporalStateError = void 0;
+exports.createTemporalState = createTemporalState;
+class TemporalStateError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'TemporalStateError';
+    }
+}
+exports.TemporalStateError = TemporalStateError;
+function cloneJson(value, maxDepth, depth = 0) {
+    if (depth > maxDepth)
+        throw new TemporalStateError('capacity', 'Value exceeds maxDepth.');
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (Array.isArray(value)) {
+        if (value.length > 100_000)
+            throw new TemporalStateError('capacity', 'Array is too large.');
+        for (const key of Reflect.ownKeys(value)) {
+            if (key === 'length')
+                continue;
+            if (typeof key !== 'string' || !/^(0|[1-9]\d*)$/.test(key) || Number(key) >= value.length)
+                throw new TemporalStateError('invalid', 'JSON arrays cannot have extra properties.');
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor?.enumerable || !('value' in descriptor))
+                throw new TemporalStateError('invalid', 'JSON arrays must be dense data properties.');
+        }
+        const copy = [];
+        for (let index = 0; index < value.length; index++) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+            if (!descriptor?.enumerable || !('value' in descriptor))
+                throw new TemporalStateError('invalid', 'JSON arrays must be dense data properties.');
+            copy.push(cloneJson(descriptor.value, maxDepth, depth + 1));
+        }
+        return copy;
+    }
+    if (typeof value === 'object' &&
+        (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)) {
+        const copy = {};
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key !== 'string')
+                throw new TemporalStateError('invalid', 'JSON records cannot contain symbol keys.');
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor?.enumerable || !('value' in descriptor))
+                throw new TemporalStateError('invalid', 'Values must use enumerable data properties.');
+            Object.defineProperty(copy, key, {
+                value: cloneJson(descriptor.value, maxDepth, depth + 1),
+                enumerable: true,
+                configurable: true,
+                writable: true,
+            });
+        }
+        return copy;
+    }
+    throw new TemporalStateError('invalid', 'Values must be finite JSON data.');
+}
+function timestamp(at) {
+    if (!Number.isSafeInteger(at) || at < 0)
+        throw new TemporalStateError('invalid', 'Timestamp must be a non-negative safe integer.');
+    return at;
+}
+function createTemporalState(options = {}) {
+    const maxEvents = options.maxEvents ?? 10_000;
+    const maxKeys = options.maxKeys ?? 1000;
+    const maxDepth = options.maxDepth ?? 64;
+    if (!Number.isSafeInteger(maxEvents) || maxEvents < 1 || maxEvents > 1_000_000)
+        throw new RangeError('maxEvents must be an integer from 1 through 1000000.');
+    if (!Number.isSafeInteger(maxKeys) || maxKeys < 1 || maxKeys > 100_000)
+        throw new RangeError('maxKeys must be an integer from 1 through 100000.');
+    if (!Number.isSafeInteger(maxDepth) || maxDepth < 0 || maxDepth > 256)
+        throw new RangeError('maxDepth must be an integer from 0 through 256.');
+    const history = new Map();
+    let eventCount = 0;
+    let watermark = 0;
+    let latestAt;
+    const assertKey = (key) => {
+        if (typeof key !== 'string' || key.length < 1 || key.length > 256)
+            throw new TemporalStateError('invalid', 'Key must contain 1..256 characters.');
+    };
+    const append = (key, atInput, event) => {
+        assertKey(key);
+        const at = timestamp(atInput);
+        if (at < watermark)
+            throw new TemporalStateError('pruned', 'Cannot append before the compaction watermark.');
+        const events = history.get(key);
+        if (events && at < events[events.length - 1].at)
+            throw new TemporalStateError('out-of-order', 'Events for each key must be nondecreasing in time.');
+        if (!events && history.size >= maxKeys)
+            throw new TemporalStateError('capacity', `Key capacity of ${maxKeys} is full.`);
+        if (eventCount >= maxEvents)
+            throw new TemporalStateError('capacity', `Event capacity of ${maxEvents} is full.`);
+        const next = events ?? [];
+        next.push(Object.freeze({ at, ...event }));
+        history.set(key, next);
+        eventCount++;
+        latestAt = Math.max(latestAt ?? at, at);
+    };
+    const stateAt = (key, at) => {
+        const events = history.get(key);
+        if (!events)
+            return undefined;
+        let low = 0;
+        let high = events.length - 1;
+        let found = -1;
+        while (low <= high) {
+            const middle = (low + high) >>> 1;
+            if (events[middle].at <= at) {
+                found = middle;
+                low = middle + 1;
+            }
+            else
+                high = middle - 1;
+        }
+        if (found < 0 || events[found].deleted)
+            return undefined;
+        return cloneJson(events[found].value, maxDepth);
+    };
+    return Object.freeze({
+        set(key, at, value) {
+            append(key, at, { deleted: false, value: cloneJson(value, maxDepth) });
+        },
+        delete(key, at) {
+            append(key, at, { deleted: true });
+        },
+        getAt(key, atInput) {
+            assertKey(key);
+            const at = timestamp(atInput);
+            if (at < watermark)
+                throw new TemporalStateError('pruned', `History before ${watermark} was compacted.`);
+            return stateAt(key, at);
+        },
+        snapshotAt(atInput) {
+            const at = timestamp(atInput);
+            if (at < watermark)
+                throw new TemporalStateError('pruned', `History before ${watermark} was compacted.`);
+            const result = {};
+            for (const key of history.keys()) {
+                const value = stateAt(key, at);
+                if (value !== undefined)
+                    Object.defineProperty(result, key, {
+                        value,
+                        enumerable: true,
+                        configurable: true,
+                        writable: true,
+                    });
+            }
+            return Object.freeze(result);
+        },
+        compact(beforeInput) {
+            const before = timestamp(beforeInput);
+            if (before < watermark)
+                throw new TemporalStateError('conflict', 'Compaction watermark cannot move backward.');
+            let removed = 0;
+            for (const [key, events] of history) {
+                let last = -1;
+                while (last + 1 < events.length && events[last + 1].at <= before)
+                    last++;
+                if (last > 0) {
+                    const baseline = events[last];
+                    const kept = [Object.freeze({ ...baseline, at: before }), ...events.slice(last + 1)];
+                    removed += events.length - kept.length;
+                    history.set(key, kept);
+                }
+                else if (last === 0 && events[0].at < before) {
+                    events[0] = Object.freeze({ ...events[0], at: before });
+                }
+            }
+            eventCount -= removed;
+            watermark = before;
+            return removed;
+        },
+        snapshot() {
+            return Object.freeze({
+                events: eventCount,
+                keys: history.size,
+                oldestAvailableAt: watermark,
+                ...(latestAt === undefined ? {} : { latestAt }),
+            });
+        },
+    });
+}

package/dist/cjs/package.json

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

package/dist/esm/index.d.ts

@@ -0,0 +1,26 @@
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export interface TemporalOptions {
+    readonly maxEvents?: number;
+    readonly maxKeys?: number;
+    readonly maxDepth?: number;
+}
+export interface TemporalSnapshot {
+    readonly events: number;
+    readonly keys: number;
+    readonly oldestAvailableAt: number;
+    readonly latestAt?: number;
+}
+export declare class TemporalStateError extends Error {
+    readonly code: 'invalid' | 'capacity' | 'out-of-order' | 'pruned' | 'conflict';
+    constructor(code: 'invalid' | 'capacity' | 'out-of-order' | 'pruned' | 'conflict', message: string);
+}
+export declare function createTemporalState(options?: TemporalOptions): Readonly<{
+    set(key: string, at: number, value: unknown): void;
+    delete(key: string, at: number): void;
+    getAt(key: string, atInput: number): Json | undefined;
+    snapshotAt(atInput: number): Readonly<Record<string, Json>>;
+    compact(beforeInput: number): number;
+    snapshot(): TemporalSnapshot;
+}>;

package/dist/esm/index.js

@@ -0,0 +1,181 @@
+export class TemporalStateError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'TemporalStateError';
+    }
+}
+function cloneJson(value, maxDepth, depth = 0) {
+    if (depth > maxDepth)
+        throw new TemporalStateError('capacity', 'Value exceeds maxDepth.');
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (Array.isArray(value)) {
+        if (value.length > 100_000)
+            throw new TemporalStateError('capacity', 'Array is too large.');
+        for (const key of Reflect.ownKeys(value)) {
+            if (key === 'length')
+                continue;
+            if (typeof key !== 'string' || !/^(0|[1-9]\d*)$/.test(key) || Number(key) >= value.length)
+                throw new TemporalStateError('invalid', 'JSON arrays cannot have extra properties.');
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor?.enumerable || !('value' in descriptor))
+                throw new TemporalStateError('invalid', 'JSON arrays must be dense data properties.');
+        }
+        const copy = [];
+        for (let index = 0; index < value.length; index++) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+            if (!descriptor?.enumerable || !('value' in descriptor))
+                throw new TemporalStateError('invalid', 'JSON arrays must be dense data properties.');
+            copy.push(cloneJson(descriptor.value, maxDepth, depth + 1));
+        }
+        return copy;
+    }
+    if (typeof value === 'object' &&
+        (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)) {
+        const copy = {};
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key !== 'string')
+                throw new TemporalStateError('invalid', 'JSON records cannot contain symbol keys.');
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor?.enumerable || !('value' in descriptor))
+                throw new TemporalStateError('invalid', 'Values must use enumerable data properties.');
+            Object.defineProperty(copy, key, {
+                value: cloneJson(descriptor.value, maxDepth, depth + 1),
+                enumerable: true,
+                configurable: true,
+                writable: true,
+            });
+        }
+        return copy;
+    }
+    throw new TemporalStateError('invalid', 'Values must be finite JSON data.');
+}
+function timestamp(at) {
+    if (!Number.isSafeInteger(at) || at < 0)
+        throw new TemporalStateError('invalid', 'Timestamp must be a non-negative safe integer.');
+    return at;
+}
+export function createTemporalState(options = {}) {
+    const maxEvents = options.maxEvents ?? 10_000;
+    const maxKeys = options.maxKeys ?? 1000;
+    const maxDepth = options.maxDepth ?? 64;
+    if (!Number.isSafeInteger(maxEvents) || maxEvents < 1 || maxEvents > 1_000_000)
+        throw new RangeError('maxEvents must be an integer from 1 through 1000000.');
+    if (!Number.isSafeInteger(maxKeys) || maxKeys < 1 || maxKeys > 100_000)
+        throw new RangeError('maxKeys must be an integer from 1 through 100000.');
+    if (!Number.isSafeInteger(maxDepth) || maxDepth < 0 || maxDepth > 256)
+        throw new RangeError('maxDepth must be an integer from 0 through 256.');
+    const history = new Map();
+    let eventCount = 0;
+    let watermark = 0;
+    let latestAt;
+    const assertKey = (key) => {
+        if (typeof key !== 'string' || key.length < 1 || key.length > 256)
+            throw new TemporalStateError('invalid', 'Key must contain 1..256 characters.');
+    };
+    const append = (key, atInput, event) => {
+        assertKey(key);
+        const at = timestamp(atInput);
+        if (at < watermark)
+            throw new TemporalStateError('pruned', 'Cannot append before the compaction watermark.');
+        const events = history.get(key);
+        if (events && at < events[events.length - 1].at)
+            throw new TemporalStateError('out-of-order', 'Events for each key must be nondecreasing in time.');
+        if (!events && history.size >= maxKeys)
+            throw new TemporalStateError('capacity', `Key capacity of ${maxKeys} is full.`);
+        if (eventCount >= maxEvents)
+            throw new TemporalStateError('capacity', `Event capacity of ${maxEvents} is full.`);
+        const next = events ?? [];
+        next.push(Object.freeze({ at, ...event }));
+        history.set(key, next);
+        eventCount++;
+        latestAt = Math.max(latestAt ?? at, at);
+    };
+    const stateAt = (key, at) => {
+        const events = history.get(key);
+        if (!events)
+            return undefined;
+        let low = 0;
+        let high = events.length - 1;
+        let found = -1;
+        while (low <= high) {
+            const middle = (low + high) >>> 1;
+            if (events[middle].at <= at) {
+                found = middle;
+                low = middle + 1;
+            }
+            else
+                high = middle - 1;
+        }
+        if (found < 0 || events[found].deleted)
+            return undefined;
+        return cloneJson(events[found].value, maxDepth);
+    };
+    return Object.freeze({
+        set(key, at, value) {
+            append(key, at, { deleted: false, value: cloneJson(value, maxDepth) });
+        },
+        delete(key, at) {
+            append(key, at, { deleted: true });
+        },
+        getAt(key, atInput) {
+            assertKey(key);
+            const at = timestamp(atInput);
+            if (at < watermark)
+                throw new TemporalStateError('pruned', `History before ${watermark} was compacted.`);
+            return stateAt(key, at);
+        },
+        snapshotAt(atInput) {
+            const at = timestamp(atInput);
+            if (at < watermark)
+                throw new TemporalStateError('pruned', `History before ${watermark} was compacted.`);
+            const result = {};
+            for (const key of history.keys()) {
+                const value = stateAt(key, at);
+                if (value !== undefined)
+                    Object.defineProperty(result, key, {
+                        value,
+                        enumerable: true,
+                        configurable: true,
+                        writable: true,
+                    });
+            }
+            return Object.freeze(result);
+        },
+        compact(beforeInput) {
+            const before = timestamp(beforeInput);
+            if (before < watermark)
+                throw new TemporalStateError('conflict', 'Compaction watermark cannot move backward.');
+            let removed = 0;
+            for (const [key, events] of history) {
+                let last = -1;
+                while (last + 1 < events.length && events[last + 1].at <= before)
+                    last++;
+                if (last > 0) {
+                    const baseline = events[last];
+                    const kept = [Object.freeze({ ...baseline, at: before }), ...events.slice(last + 1)];
+                    removed += events.length - kept.length;
+                    history.set(key, kept);
+                }
+                else if (last === 0 && events[0].at < before) {
+                    events[0] = Object.freeze({ ...events[0], at: before });
+                }
+            }
+            eventCount -= removed;
+            watermark = before;
+            return removed;
+        },
+        snapshot() {
+            return Object.freeze({
+                events: eventCount,
+                keys: history.size,
+                oldestAvailableAt: watermark,
+                ...(latestAt === undefined ? {} : { latestAt }),
+            });
+        },
+    });
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@lp-labs/temporal-state",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Bounded append-only keyed history with point-in-time queries and explicit compaction.",
+  "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"
+  }
+}