Name: payload hypervalue
Author: b3nab

Overview

Summary generated from the README

Stores the history of scalar field values in TimescaleDB hypertables. Tracking is enabled per collection or per field through a custom flag in the config. History can be queried with a local API method or REST endpoints, including point-in-time and range queries. Requires the Postgres adapter and TimescaleDB 2.15 or newer.

Features

Collection-level tracking with full snapshots in one wide hypertable per collection
Field-level tracking with a narrow hypertable per field
Point-in-time and date range queries through the local API
REST endpoints for snapshots and field history
Configurable chunk interval, compression and retention policies
Optional recording of draft saves

Use cases

Record sensor readings such as temperature over time and query ranges of them
Keep a price and status history for products to review past values
Apply automatic compression and retention to long-running historical data

Installation

npm i @b3nab/payload-hypervalue

Health Score

18/100Poor

Composite score based on GitHub activity, stars, npm downloads, publish recency, dependency count, and package size.

Badge for your README

Markdown

[![Payload Directory](https://payloaddirectory.dev/badge/1175545924-payload-hypervalue.svg)](https://payloaddirectory.dev/plugins/1175545924-payload-hypervalue)

HTML

<a href="https://payloaddirectory.dev/plugins/1175545924-payload-hypervalue"><img src="https://payloaddirectory.dev/badge/1175545924-payload-hypervalue.svg" alt="Payload Directory"></a>

README

@b3nab/payload-hypervalue

Time-series history tracking for Payload CMS fields and collections, powered by TimescaleDB hypertables.

Install

pnpm add @b3nab/payload-hypervalue

Usage

import { buildConfig } from "payload";
import { payloadHypervalue } from "@b3nab/payload-hypervalue";

export default buildConfig({
  plugins: [payloadHypervalue()],
  collections: [
    {
      slug: "products",
      custom: { hypervalue: true }, // collection-level: track all scalar fields
      fields: [
        { name: "title", type: "text" },
        { name: "price", type: "number" },
        { name: "status", type: "select", options: ["draft", "published"] },
      ],
    },
    {
      slug: "sensors",
      fields: [
        {
          name: "temperature",
          type: "number",
          custom: { hypervalue: true }, // field-level: track just this field
        },
      ],
    },
  ],
});

Tracking Modes

Collection-level — Add custom: { hypervalue: true } to a collection. All scalar fields are tracked in a single wide hypertable (hv_{collection}). Every update stores a full snapshot.

Field-level — Add custom: { hypervalue: true } to individual fields. Each gets its own narrow hypertable (hv_{collection}_{field}).

Both modes can coexist on the same collection.

Querying

// Collection-level — full document snapshots
const snapshots = await payload.hypervalue({
  collection: "products",
  id: productId,
});

// Field-level — single field history
const history = await payload.hypervalue({
  collection: "sensors",
  id: sensorId,
  field: "temperature",
});

// Point-in-time
const snapshot = await payload.hypervalue({
  collection: "products",
  id: productId,
  at: new Date("2025-06-01"),
});

// Range
const range = await payload.hypervalue({
  collection: "sensors",
  id: sensorId,
  field: "temperature",
  from: new Date("2025-01-01"),
  to: new Date("2025-06-01"),
});

REST endpoints:

GET /api/hypervalue/:collection/:id            # collection-level snapshots
GET /api/hypervalue/:collection/:id/:field     # field-level history

Plugin Options

Option	Type	Default	Description
`chunkInterval`	`string`	`'3 months'`	TimescaleDB chunk time interval
`compressionAfter`	`string`	—	Compress chunks older than this interval
`retentionAfter`	`string`	—	Auto-drop chunks older than this interval
`trackDrafts`	`boolean`	`false`	Record changes on draft saves
`disabled`	`boolean`	`false`	Disable the plugin at runtime

Supported Field Types

number, text, select, checkbox, date, json, relationship

Requirements

Payload ^3.79.0 with @payloadcms/db-postgres
PostgreSQL with TimescaleDB 2.15+
Node ^18.20.2 or >=20.9.0

Docs

payload-hypervalue.abbenanti.com

License

MIT

payload hypervalue