graphile-history 1.1.1

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+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,140 @@
+# graphile-history
+
+PostGraphile v5 plugin for per-row **version history**, **point-in-time reads**, and **restore mutations**.
+
+It discovers tables tagged with the `@history` smart tag — the companion
+`<table>_history` tables produced by the constructive-db `DataHistory` module —
+and augments the GraphQL schema with:
+
+- a `history` field on each source row type: the row's full version stream,
+  newest first (`recorded_at DESC`);
+- a `versionAt(at: Datetime!)` field: the version that was current at a given
+  instant;
+- a `versionsBetween(from: Datetime!, to: Datetime!)` field: every version
+  recorded within an inclusive time window, newest first;
+- a `restore<Table>Version(input: { <pk>, recordedAt, reinsert })` root
+  mutation that rewrites the live row from a historical version (optionally
+  re-inserting a deleted row).
+
+All reads and writes flow through the request's `withPgClient` + `pgSettings`,
+so row-level security and mutation policies are enforced exactly as for any
+other operation. Because a restore writes through the source table, the source
+`DataHistory` trigger records the restore itself as a new version.
+
+## Usage
+
+```typescript
+import { HistoryPreset } from 'graphile-history';
+
+const preset = {
+  extends: [
+    HistoryPreset(),
+  ],
+};
+```
+
+### Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `historySuffix` | `'_history'` | Suffix used to derive the history table name when the `@history` tag has no explicit name. |
+| `recordedAtColumn` | `'recorded_at'` | Version timestamp column on the history table. |
+| `operationColumn` | `'history_op'` | Operation marker column (INSERT/UPDATE/DELETE). |
+| `immutableColumns` | `['created_at', 'updated_at']` | Source columns never written by a restore (primary keys are always excluded). |
+
+## Example
+
+```graphql
+query {
+  postByRowId(rowId: 1) {
+    title
+    history { title historyOp recordedAt }
+    versionAt(at: "2024-02-15T00:00:00Z") { title }
+    versionsBetween(from: "2024-01-01T00:00:00Z", to: "2024-03-01T00:00:00Z") {
+      title
+      recordedAt
+    }
+  }
+}
+
+mutation {
+  restorePostVersion(input: { id: 1, recordedAt: "2024-02-15T00:00:00Z" }) {
+    version { title }
+    restored { title body }
+  }
+}
+```
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pglite-test](https://github.com/constructive-io/constructive/tree/main/postgres/pglite-test): **🪶 Drop-in pgsql-test replacement backed by PGlite** — in-process Postgres, no server required, instance-per-suite isolation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+### 📚 Documentation & Skills
+
+* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
+
+Install skills for AI coding agents:
+
+```bash
+# All platform skills (security, blueprints, codegen, billing, etc.)
+npx skills add constructive-io/constructive-skills
+
+# Individual repo skills (pgpm, testing, CLI, search, etc.)
+npx skills add https://github.com/constructive-io/constructive --skill pgpm
+npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
+```
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/esm/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * graphile-history — PostGraphile v5 History Plugin
+ *
+ * Per-row version history, point-in-time reads, and restore mutations for
+ * tables tagged with `@history` (the constructive-db `DataHistory` module).
+ *
+ * @example
+ * ```typescript
+ * import { HistoryPreset } from 'graphile-history';
+ *
+ * const preset = {
+ *   extends: [
+ *     HistoryPreset(),
+ *   ],
+ * };
+ * ```
+ */
+export { createHistoryPlugin, HistoryPlugin } from './plugin';
+export { HistoryPreset } from './preset';
+export type { HistoryColumn, HistoryPluginOptions, HistoryTableInfo } from './types';

package/esm/index.js

@@ -0,0 +1,21 @@
+/**
+ * graphile-history — PostGraphile v5 History Plugin
+ *
+ * Per-row version history, point-in-time reads, and restore mutations for
+ * tables tagged with `@history` (the constructive-db `DataHistory` module).
+ *
+ * @example
+ * ```typescript
+ * import { HistoryPreset } from 'graphile-history';
+ *
+ * const preset = {
+ *   extends: [
+ *     HistoryPreset(),
+ *   ],
+ * };
+ * ```
+ */
+// Plugin
+export { createHistoryPlugin, HistoryPlugin } from './plugin';
+// Preset
+export { HistoryPreset } from './preset';

package/esm/plugin.d.ts

@@ -0,0 +1,36 @@
+/**
+ * PostGraphile v5 History Plugin
+ *
+ * Discovers tables tagged with `@history` (companion `<table>_history` tables
+ * produced by the constructive-db `DataHistory` module) and augments the schema
+ * with:
+ *   - a `history` connection field on each source row type — the row's full
+ *     version stream ordered by `recorded_at DESC`;
+ *   - a `versionAt(at: Datetime!)` field returning the version that was current
+ *     at a given point in time;
+ *   - a `restore<Table>Version` root mutation that rewrites the live row from a
+ *     historical version (optionally re-inserting a deleted row).
+ *
+ * All reads and writes go through the request's `withPgClient` + `pgSettings`,
+ * so row-level security and mutation policies are enforced exactly as they are
+ * for any other operation. Because restores write through the source table, the
+ * source `DataHistory` trigger records the restore itself as a new version.
+ *
+ * Smart tag format (stamped by `metaschema_generators.data_history`):
+ *   @history { "history_table": "posts_history", ... }
+ * The tag value may also be a bare string naming the history table, or simply a
+ * truthy marker (in which case the history table is derived by suffix).
+ */
+import 'graphile-build';
+import 'graphile-build-pg';
+import type { GraphileConfig } from 'graphile-config';
+import type { HistoryPluginOptions } from './types';
+declare global {
+    namespace GraphileConfig {
+        interface Plugins {
+            HistoryPlugin: true;
+        }
+    }
+}
+export declare function createHistoryPlugin(options?: HistoryPluginOptions): GraphileConfig.Plugin;
+export declare const HistoryPlugin: GraphileConfig.Plugin;