@pgpm/stamps 0.4.0 → 0.6.0

package/Makefile

@@ -1,5 +1,5 @@
 EXTENSION = launchql-stamps
-DATA = sql/launchql-stamps--0.4.6.sql
+DATA = sql/launchql-stamps--0.5.0.sql
 
 PG_CONFIG = pg_config
 PGXS := $(shell $(PG_CONFIG) --pgxs)

package/README.md

@@ -2,4 +2,273 @@
 
 Timestamp utilities and audit trail functions for PostgreSQL.
 
-Provides created_at, updated_at, and other timestamp management functions for tracking data changes and audit trails.
+## Overview
+
+`@pgpm/stamps` provides PostgreSQL trigger functions for automatically managing timestamp and user tracking columns in your tables. This package simplifies audit trail implementation by automatically setting `created_at`, `updated_at`, `created_by`, and `updated_by` fields.
+
+## Features
+
+- **timestamps()**: Trigger function that automatically manages `created_at` and `updated_at` columns
+- **peoplestamps()**: Trigger function that automatically manages `created_by` and `updated_by` columns using JWT claims
+- Automatic preservation of creation timestamps and users on updates
+- Integration with `@pgpm/jwt-claims` for user context
+
+## Installation
+
+If you have `pgpm` installed:
+
+```bash
+pgpm install @pgpm/stamps
+pgpm deploy
+```
+
+This is a quick way to get started. The sections below provide more detailed installation options.
+
+### Prerequisites
+
+```bash
+# Install pgpm globally
+npm install -g pgpm
+
+# Start PostgreSQL
+pgpm docker start
+
+# Set environment variables
+eval "$(pgpm env)"
+```
+
+### Deploy
+
+#### Option 1: Deploy by installing with pgpm
+
+```bash
+pgpm install @pgpm/stamps
+pgpm deploy
+```
+
+#### Option 2: Deploy from Package Directory
+
+```bash
+cd packages/data-types/stamps
+pgpm deploy --createdb
+```
+
+#### Option 3: Deploy from Workspace Root
+
+```bash
+# Install workspace dependencies
+pnpm install
+
+# Deploy with dependencies
+pgpm deploy mydb1 --yes --createdb
+```
+
+## Usage
+
+### Setting Up Timestamp Tracking
+
+```sql
+-- Create a table with timestamp columns
+CREATE TABLE public.posts (
+  id serial PRIMARY KEY,
+  title text,
+  content text,
+  created_at timestamptz,
+  updated_at timestamptz
+);
+
+-- Add trigger to automatically manage timestamps
+CREATE TRIGGER set_timestamps
+BEFORE INSERT OR UPDATE ON public.posts
+FOR EACH ROW
+EXECUTE FUNCTION stamps.timestamps();
+```
+
+### Setting Up User Tracking
+
+```sql
+-- Create a table with user tracking columns
+CREATE TABLE public.posts (
+  id serial PRIMARY KEY,
+  title text,
+  content text,
+  created_at timestamptz,
+  updated_at timestamptz,
+  created_by uuid,
+  updated_by uuid
+);
+
+-- Add triggers for automatic timestamp and user tracking
+CREATE TRIGGER set_timestamps
+BEFORE INSERT OR UPDATE ON public.posts
+FOR EACH ROW
+EXECUTE FUNCTION stamps.timestamps();
+
+CREATE TRIGGER set_peoplestamps
+BEFORE INSERT OR UPDATE ON public.posts
+FOR EACH ROW
+EXECUTE FUNCTION stamps.peoplestamps();
+```
+
+### How It Works
+
+When you insert a new row:
+- `created_at` and `updated_at` are set to the current timestamp
+- `created_by` and `updated_by` are set to the current user ID from JWT claims
+
+When you update an existing row:
+- `created_at` and `created_by` are preserved (set to their original values)
+- `updated_at` is set to the current timestamp
+- `updated_by` is set to the current user ID from JWT claims
+
+### Example Usage
+
+```sql
+-- Set the user context (typically done by your application)
+SET jwt.claims.user_id = '00000000-0000-0000-0000-000000000001';
+
+-- Insert a new post
+INSERT INTO public.posts (title, content)
+VALUES ('My First Post', 'Hello World!');
+-- created_at, updated_at, created_by, and updated_by are automatically set
+
+-- Update the post
+UPDATE public.posts
+SET content = 'Updated content'
+WHERE id = 1;
+-- updated_at and updated_by are automatically updated
+-- created_at and created_by remain unchanged
+```
+
+## Trigger Functions
+
+### stamps.timestamps()
+
+Automatically manages timestamp columns on INSERT and UPDATE operations.
+
+**Behavior:**
+- **INSERT**: Sets both `created_at` and `updated_at` to `NOW()`
+- **UPDATE**: Preserves `created_at`, updates `updated_at` to `NOW()`
+
+**Required Columns:**
+- `created_at timestamptz`
+- `updated_at timestamptz`
+
+### stamps.peoplestamps()
+
+Automatically manages user tracking columns on INSERT and UPDATE operations using JWT claims.
+
+**Behavior:**
+- **INSERT**: Sets both `created_by` and `updated_by` to `jwt_public.current_user_id()`
+- **UPDATE**: Preserves `created_by`, updates `updated_by` to `jwt_public.current_user_id()`
+
+**Required Columns:**
+- `created_by uuid`
+- `updated_by uuid`
+
+**Dependencies:**
+- Requires `@pgpm/jwt-claims` for `jwt_public.current_user_id()` function
+- User context must be set via `jwt.claims.user_id` session variable
+
+## Dependencies
+
+- `@pgpm/jwt-claims`: JWT claim handling for user context
+- `@pgpm/verify`: Verification utilities for database objects
+
+## Testing
+
+```bash
+pnpm test
+```
+
+The test suite validates:
+- Automatic timestamp setting on insert and update
+- Automatic user tracking on insert and update
+- Preservation of creation timestamps and users on updates
+- Integration with JWT claims for user context
+
+## Development
+
+See the [Development](#development) section below for information on working with this package.
+
+---
+
+## Development
+
+### **Before You Begin**
+
+```bash
+# 1. Install pgpm
+npm install -g pgpm
+
+# 2. Start Postgres (Docker or local)
+pgpm docker start
+
+# 3. Load PG* environment variables (PGHOST, PGUSER, ...)
+eval "$(pgpm env)"
+```
+
+---
+
+### **Starting a New Project**
+
+```bash
+# 1. Create a workspace
+pgpm init --workspace
+cd my-app
+
+# 2. Create your first module
+pgpm init
+
+# 3. Add a migration
+pgpm add some_change
+
+# 4. Deploy (auto-creates database)
+pgpm deploy --createdb
+```
+
+---
+
+### **Working With an Existing Project**
+
+```bash
+# 1. Clone and enter the project
+git clone <repo> && cd <project>
+
+# 2. Install dependencies
+pnpm install
+
+# 3. Deploy locally
+pgpm deploy --createdb
+```
+
+---
+
+### **Testing a Module Inside a Workspace**
+
+```bash
+# 1. Install workspace deps
+pnpm install
+
+# 2. Enter the module directory
+cd packages/<some-module>
+
+# 3. Run tests in watch mode
+pnpm test:watch
+```
+
+## Related Tooling
+
+* [pgpm](https://github.com/launchql/launchql/tree/main/packages/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+* [pgsql-test](https://github.com/launchql/launchql/tree/main/packages/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [supabase-test](https://github.com/launchql/launchql/tree/main/packages/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/launchql/launchql/tree/main/packages/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pgsql-parser](https://github.com/launchql/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://github.com/launchql/libpg-query-node): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://github.com/launchql/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+
+## 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/launchql-stamps.control

@@ -1,6 +1,6 @@
 # launchql-stamps extension
 comment = 'launchql-stamps extension'
-default_version = '0.4.6'
+default_version = '0.5.0'
 module_pathname = '$libdir/launchql-stamps'
 requires = 'plpgsql,launchql-jwt-claims,launchql-verify'
 relocatable = false

package/package.json

@@ -1,29 +1,29 @@
 {
   "name": "@pgpm/stamps",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Timestamp utilities and audit trail functions for PostgreSQL",
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "bundle": "lql package",
+    "bundle": "pgpm package",
     "test": "jest",
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@pgpm/jwt-claims": "0.4.0",
-    "@pgpm/verify": "0.4.0"
+    "@pgpm/jwt-claims": "0.6.0",
+    "@pgpm/verify": "0.6.0"
   },
   "devDependencies": {
-    "@launchql/cli": "^4.9.0"
+    "pgpm": "^0.2.0"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/launchql/extensions"
+    "url": "https://github.com/launchql/pgpm-modules"
   },
-  "homepage": "https://github.com/launchql/extensions",
+  "homepage": "https://github.com/launchql/pgpm-modules",
   "bugs": {
-    "url": "https://github.com/launchql/extensions/issues"
+    "url": "https://github.com/launchql/pgpm-modules/issues"
   },
-  "gitHead": "cc9f52a335caa6e21ee7751b04b77c84ce6cb809"
+  "gitHead": "c7d0eae588d7a764b382a330c8b853b341b13fb2"
 }