Static Code Generator

.commitlintrc

@@ -0,0 +1,5 @@
+{
+  "extends": [
+    "@commitlint/config-conventional"
+  ]
+}

.editorconfig

@@ -0,0 +1,6 @@
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+indent_style = space
+indent_size = 2

.github/workflows/ci.yml

@@ -41,3 +41,11 @@ jobs:
       - name: Run tests no check
         run: |
           make run_test_nochecks
+
+      - name: Run Node.js e2e Tests
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+      - run: npm ci
+      - run: npm run build --if-present
+      - run: npm run test:e2e:runner

.gitignore

@@ -3,6 +3,8 @@
 test/result
 .env
 .envrc
+.eslintcache
 test/remote_expected
 test/remote_sql
 test/remote_result
+node_modules

.nvmrc

@@ -0,0 +1 @@
+lts/*

.prettierrc

@@ -0,0 +1,6 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "arrowParens": "avoid",
+  "trailingComma": "none"
+}

.vscode/launch.json

@@ -0,0 +1,24 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Test File w/ ts-node",
+      "protocol": "inspector",
+      "runtimeArgs": ["--loader", "ts-node/esm/transpile-only", "--test"],
+      "args": ["${relativeFile}"],
+      "outputCapture": "std",
+      "internalConsoleOptions": "openOnSessionStart",
+      "envFile": "${workspaceRoot}/.env",
+      "skipFiles": [
+        "${workspaceRoot}/../../node_modules/**/*",
+        "<node_internals>/**/*"
+      ],
+      "windows": {
+        "skipFiles": ["C:\\**\\node_modules\\**\\*", "<node_internals>/**/*"]
+      },
+      "disableOptimisticBPs": true
+    }
+  ]
+}

README.md

@@ -12,9 +12,19 @@ Over time, new features have been introduced while maintaining backward compatib
 
 - [Ignore updates with no actual changes](#ignore-unchanged-values)
 - [Include the current version in history](#include-current-version-in-history)
+- [Static trigger code generation](#static-trigger-code-generation)
+- [Automatic trigger re-rendering](#event-trigger-for-automatic-re-rendering)
+- [Versioning tables metadata management](#versioning-tables-metadata)
+- [Update conflict mitigation](#mitigate-update-conflicts)
+- [Migration mode support](#migration-mode)
 
 <a name="usage"></a>
 
+## PostgreSQL Version Requirements
+
+- **Legacy functionality** (basic versioning): Works with any PostgreSQL version
+- **Modern functionality** (static triggers, metadata management): Requires PostgreSQL 13.21 or higher
+
 ## Usage
 
 Create a database and the versioning function:
@@ -234,6 +244,40 @@ FOR EACH ROW EXECUTE PROCEDURE versioning(
 );
 ```
 
+<a name="mitigate-update-conflicts"></a>
+
+### Mitigate Update Conflicts
+
+By default, when multiple transactions try to update the same row simultaneously, PostgreSQL's versioning system can detect conflicts where the system period start time would be greater than or equal to the current transaction time. This can cause errors in high-concurrency scenarios.
+
+The `mitigate_update_conflicts` parameter (sixth parameter) automatically adjusts timestamps by adding 1 microsecond when conflicts are detected, allowing operations to proceed smoothly:
+
+```sql
+CREATE TRIGGER versioning_trigger
+BEFORE INSERT OR UPDATE OR DELETE ON subscriptions
+FOR EACH ROW EXECUTE PROCEDURE versioning(
+  'sys_period', 'subscriptions_history', true, false, false, true
+);
+```
+
+**Note:** This feature slightly modifies timestamps to resolve conflicts, which may affect temporal queries that rely on exact timing.
+
+<a name="migration-mode"></a>
+
+### Migration Mode
+
+Migration mode (seventh parameter) enables gradual adoption of the `include_current_version_in_history` feature for existing tables without requiring a maintenance window:
+
+```sql
+CREATE TRIGGER versioning_trigger
+BEFORE INSERT OR UPDATE OR DELETE ON subscriptions
+FOR EACH ROW EXECUTE PROCEDURE versioning(
+  'sys_period', 'subscriptions_history', true, false, true, false, true
+);
+```
+
+When enabled, the trigger automatically populates missing current versions in the history table during UPDATE or DELETE operations.
+
 <a name="migration-to-include-current-version-in-history"></a>
 
 ### Migrating to include_current_version_in_history
@@ -339,13 +383,13 @@ WHERE UPPER(sys_period) IS NULL;
 
 When adopting the `include_current_version_in_history` feature for existing tables, you can use the automatic gradual migration mode to seamlessly populate the history table with current records.
 
-The migration mode is enabled by adding a sixth parameter to the versioning trigger:
+The migration mode is enabled by adding a seventh parameter to the versioning trigger:
 
 ```sql
 CREATE TRIGGER versioning_trigger
 BEFORE INSERT OR UPDATE OR DELETE ON your_table
 FOR EACH ROW EXECUTE PROCEDURE versioning(
-  'sys_period', 'your_table_history', true, false, true, true
+  'sys_period', 'your_table_history', true, false, true, false, true
 );
 ```
 
@@ -385,6 +429,174 @@ When migration mode is enabled:
 
 **Note:** The automatic migration happens gradually, filling in missing history only when existing records are updated or deleted. As a result, records that rarely change will still require manual migration using the [method described above](#migration-to-include-current-version-in-history). However, since the most active records will be automatically migrated, the risk of missing important data is greatly reduced, eliminating the need for a dedicated maintenance window.
 
+<a name="versioning-tables-metadata"></a>
+
+## Versioning Tables Metadata
+
+The modern functionality includes a metadata table to track all versioned tables and their configuration. This enables automatic trigger re-rendering when table schemas change.
+
+### Setup
+
+1. **Install the metadata table:**
+   ```sh
+   psql temporal_test < versioning_tables_metadata.sql
+   ```
+
+2. **Register versioned tables:**
+   ```sql
+   INSERT INTO versioning_tables_metadata (
+     table_name, 
+     table_schema, 
+     history_table, 
+     history_table_schema,
+     sys_period,
+     ignore_unchanged_values,
+     include_current_version_in_history,
+     mitigate_update_conflicts,
+     enable_migration_mode
+   ) VALUES (
+     'subscriptions', 
+     'public', 
+     'subscriptions_history',
+     'public',
+     'sys_period',
+     false,
+     false,
+     false,
+     false
+   );
+   ```
+
+### Benefits
+
+- **Automatic trigger re-rendering** when table schemas change
+- **Centralized configuration** for all versioned tables
+- **Audit trail** with created_at and updated_at timestamps
+- **Schema flexibility** with separate schemas for tables and history tables
+
+<a name="static-trigger-code-generation"></a>
+
+## Static Trigger Code Generation (PostgreSQL 13+)
+
+The modern static trigger generator creates optimized, table-specific trigger functions with no runtime schema lookups, providing better performance and reliability.
+
+### Basic Usage
+
+1. **Install the generator:**
+   ```sh
+   psql temporal_test < generate_static_versioning_trigger.sql
+   psql temporal_test < render_versioning_trigger.sql
+   ```
+
+2. **Generate static trigger:**
+   ```sql
+   -- Using the generator function directly
+   SELECT generate_static_versioning_trigger(
+     p_table_name => 'subscriptions',
+     p_history_table => 'subscriptions_history',
+     p_sys_period => 'sys_period',
+     p_ignore_unchanged_values => false,
+     p_include_current_version_in_history => false,
+     p_mitigate_update_conflicts => false,
+     p_enable_migration_mode => false
+   );
+   ```
+
+3. **Using the render procedure (recommended):**
+   ```sql
+   CALL render_versioning_trigger(
+     p_table_name => 'subscriptions',
+     p_history_table => 'subscriptions_history',
+     p_sys_period => 'sys_period',
+     p_ignore_unchanged_values => false,
+     p_include_current_version_in_history => false,
+     p_mitigate_update_conflicts => false,
+     p_enable_migration_mode => false
+   );
+   ```
+
+### Advanced Features
+
+The static generator supports all modern features:
+
+```sql
+-- Generate trigger with all advanced features enabled
+CALL render_versioning_trigger(
+  p_table_name => 'subscriptions',
+  p_history_table => 'subscriptions_history',
+  p_sys_period => 'sys_period',
+  p_ignore_unchanged_values => true,
+  p_include_current_version_in_history => true,
+  p_mitigate_update_conflicts => true,
+  p_enable_migration_mode => true
+);
+```
+
+### Benefits of Static Triggers
+
+- **Better Performance**: No runtime schema lookups
+- **Compile-time Validation**: Errors detected when trigger is created
+- **Explicit Dependencies**: Clear relationship between table structure and trigger code
+- **Optimized Code**: Generated specifically for your table's current schema
+
+<a name="event-trigger-for-automatic-re-rendering"></a>
+
+## Event Trigger for Automatic Re-rendering (PostgreSQL 13+)
+
+Event triggers automatically re-render static versioning triggers when table schemas change, ensuring triggers stay synchronized with table structures.
+
+### Setup
+
+1. **Install event trigger:**
+   ```sh
+   psql temporal_test < event_trigger_versioning.sql
+   ```
+
+2. **Ensure metadata is populated:**
+   The event trigger uses the `versioning_tables_metadata` table to determine which tables need trigger re-rendering.
+
+### How It Works
+
+- **Automatic Detection**: Event trigger fires on `ALTER TABLE` commands
+- **Metadata Lookup**: Checks if the altered table is registered in `versioning_tables_metadata`
+- **Trigger Re-rendering**: Automatically calls `render_versioning_trigger` with stored configuration
+- **Schema Synchronization**: Ensures triggers always match current table structure
+
+### Example Workflow
+
+```sql
+-- 1. Register table in metadata
+INSERT INTO versioning_tables_metadata (
+  table_name, table_schema, history_table, history_table_schema,
+  sys_period, ignore_unchanged_values, include_current_version_in_history
+) VALUES (
+  'subscriptions', 'public', 'subscriptions_history', 'public',
+  'sys_period', true, true
+);
+
+-- 2. Generate initial trigger
+CALL render_versioning_trigger(
+  p_table_name => 'subscriptions',
+  p_history_table => 'subscriptions_history',
+  p_sys_period => 'sys_period',
+  p_ignore_unchanged_values => true,
+  p_include_current_version_in_history => true
+);
+
+-- 3. Modify table schema - trigger is automatically re-rendered
+ALTER TABLE subscriptions ADD COLUMN plan text;
+ALTER TABLE subscriptions_history ADD COLUMN plan text;
+
+-- The event trigger automatically regenerates the versioning trigger!
+```
+
+### Benefits
+
+- **Zero Maintenance**: Triggers stay synchronized automatically
+- **Schema Evolution**: Safe to modify table structures
+- **Error Prevention**: Eliminates manual trigger update requirements
+- **Development Friendly**: Works seamlessly with migration scripts
+
 <a name="migrations"></a>
 
 ## Migrations
@@ -411,6 +623,75 @@ If the column doesn't accept null values you'll need to modify it to allow for n
 
 ## Test
 
+### End-to-End Tests (Enhanced)
+
+We've enhanced our comprehensive end-to-end tests written in modern TypeScript using Node.js built-in test runner and node-postgres. These tests provide extensive coverage of all temporal table features with improved reliability:
+
+#### Test Coverage
+- **Static Generator Tests**: Full coverage of the static trigger generator functionality
+- **Legacy Function Tests**: Backward compatibility testing with the original versioning function  
+- **Event Trigger Tests**: Automatic trigger re-rendering on schema changes
+- **Integration Tests**: Real-world scenarios including e-commerce workflows, schema evolution, and performance testing
+- **Error Handling**: Edge cases, transaction rollbacks, and concurrent modifications
+- **Version-aware Testing**: Automatically adapts tests based on PostgreSQL version
+
+#### Test Reliability Improvements
+- **Enhanced timestamp handling**: Eliminates flaky tests due to timing issues
+- **Robust database state management**: Proper cleanup and isolation between tests
+- **Version-specific loading**: Only loads SQL files appropriate for the PostgreSQL version
+- **Better error reporting**: Detailed failure messages with timing context
+
+#### Running E2E Tests
+
+1. **Prerequisites**: Ensure you have PostgreSQL running (Docker or local installation)
+
+2. **Install dependencies**:
+   ```bash
+   npm install
+   ```
+
+3. **Start database** (if using Docker):
+   ```bash
+   npm run db:start
+   ```
+
+4. **Run all E2E tests**:
+   ```bash
+   npm run test:e2e
+   ```
+
+5. **Run specific test suites**:
+   ```bash
+   # Static generator tests
+   npm run test:e2e:static
+
+   # Legacy function tests  
+   npm run test:e2e:legacy
+
+   # Integration tests
+   npm run test:e2e:integration
+
+   # Event trigger tests
+   npm run test:e2e:event
+
+   # Custom test runner (TypeScript)
+   npm run test:e2e:runner
+   ```
+
+#### Features of Enhanced E2E Tests
+- **Type-safe**: Written in TypeScript with proper type definitions
+- **Modern**: Uses Node.js built-in test runner (no external dependencies like Jest)
+- **Comprehensive**: Tests all features including advanced options and edge cases
+- **Isolated**: Each test starts with a clean database state
+- **Real-world scenarios**: Includes practical examples like e-commerce order processing
+- **Performance testing**: Bulk operations and concurrent access patterns
+- **Version-aware**: Automatically skips tests not supported by current PostgreSQL version
+- **Reliable timing**: Enhanced timestamp checking eliminates flaky test failures
+
+See [test/e2e/README.md](test/e2e/README.md) for detailed documentation.
+
+### Traditional Tests
+
 Ensure you have a postgres database available. A database container can be started by running:
 
 ```sh