@pgpmjs/types 2.12.8 → 2.14.0

package/README.md

@@ -39,9 +39,14 @@ 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.
+* [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.
@@ -55,28 +60,6 @@ Common issues and solutions for pgpm, PostgreSQL, and testing.
 * [@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.
 
-### 🚀 API & Dev Tools
-
-* [@constructive-io/graphql-server](https://github.com/constructive-io/constructive/tree/main/graphql/server): **⚡ Express-based API server** powered by PostGraphile to expose a secure, scalable GraphQL API over your Postgres database.
-* [@constructive-io/graphql-explorer](https://github.com/constructive-io/constructive/tree/main/graphql/explorer): **🔎 Visual API explorer** with GraphiQL for browsing across all databases and schemas—useful for debugging, documentation, and API prototyping.
-
-### 🔁 Streaming & Uploads
-
-* [etag-hash](https://github.com/constructive-io/constructive/tree/main/streaming/etag-hash): **🏷️ S3-compatible ETags** created by streaming and hashing file uploads in chunks.
-* [etag-stream](https://github.com/constructive-io/constructive/tree/main/streaming/etag-stream): **🔄 ETag computation** via Node stream transformer during upload or transfer.
-* [uuid-hash](https://github.com/constructive-io/constructive/tree/main/streaming/uuid-hash): **🆔 Deterministic UUIDs** generated from hashed content, great for deduplication and asset referencing.
-* [uuid-stream](https://github.com/constructive-io/constructive/tree/main/streaming/uuid-stream): **🌊 Streaming UUID generation** based on piped file content—ideal for upload pipelines.
-* [@constructive-io/s3-streamer](https://github.com/constructive-io/constructive/tree/main/streaming/s3-streamer): **📤 Direct S3 streaming** for large files with support for metadata injection and content validation.
-* [@constructive-io/upload-names](https://github.com/constructive-io/constructive/tree/main/streaming/upload-names): **📂 Collision-resistant filenames** utility for structured and unique file names for uploads.
-
-### 🧰 CLI & Codegen
-
-* [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.
-* [@constructive-io/cli](https://github.com/constructive-io/constructive/tree/main/packages/cli): **🖥️ Command-line toolkit** for managing Constructive projects—supports database scaffolding, migrations, seeding, code generation, and automation.
-* [@constructive-io/graphql-codegen](https://github.com/constructive-io/constructive/tree/main/graphql/codegen): **✨ GraphQL code generation** (types, operations, SDK) from schema/endpoint introspection.
-* [@constructive-io/query-builder](https://github.com/constructive-io/constructive/tree/main/packages/query-builder): **🏗️ SQL constructor** providing a robust TypeScript-based query builder for dynamic generation of `SELECT`, `INSERT`, `UPDATE`, `DELETE`, and stored procedure calls—supports advanced SQL features like `JOIN`, `GROUP BY`, and schema-qualified queries.
-* [@constructive-io/graphql-query](https://github.com/constructive-io/constructive/tree/main/graphql/query): **🧩 Fluent GraphQL builder** for PostGraphile schemas. ⚡ Schema-aware via introspection, 🧩 composable and ergonomic for building deeply nested queries.
-
 ## 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).**

package/esm/index.js

@@ -1,5 +1,6 @@
 export * from './error';
 export * from './error-factory';
+export * from './pg-error-format';
 export * from './pgpm';
 export * from './jobs';
 export * from './update';

package/esm/pg-error-format.js

@@ -0,0 +1,121 @@
+/**
+ * PostgreSQL Error Formatting Utilities
+ *
+ * Extracts and formats extended PostgreSQL error fields from pg library errors.
+ * These fields provide additional context for debugging database errors.
+ */
+/**
+ * Extract PostgreSQL error fields from an error object.
+ * Returns null if the error doesn't appear to be a PostgreSQL error.
+ *
+ * @param err - The error object to extract fields from
+ * @returns PgErrorFields if the error has PG fields, null otherwise
+ */
+export function extractPgErrorFields(err) {
+    if (!err || typeof err !== 'object') {
+        return null;
+    }
+    const e = err;
+    // Check if this looks like a PostgreSQL error (has code or detail)
+    if (!e.code && !e.detail && !e.where) {
+        return null;
+    }
+    const fields = {};
+    if (typeof e.code === 'string')
+        fields.code = e.code;
+    if (typeof e.detail === 'string')
+        fields.detail = e.detail;
+    if (typeof e.hint === 'string')
+        fields.hint = e.hint;
+    if (typeof e.where === 'string')
+        fields.where = e.where;
+    if (typeof e.position === 'string')
+        fields.position = e.position;
+    if (typeof e.internalPosition === 'string')
+        fields.internalPosition = e.internalPosition;
+    if (typeof e.internalQuery === 'string')
+        fields.internalQuery = e.internalQuery;
+    if (typeof e.schema === 'string')
+        fields.schema = e.schema;
+    if (typeof e.table === 'string')
+        fields.table = e.table;
+    if (typeof e.column === 'string')
+        fields.column = e.column;
+    if (typeof e.dataType === 'string')
+        fields.dataType = e.dataType;
+    if (typeof e.constraint === 'string')
+        fields.constraint = e.constraint;
+    if (typeof e.file === 'string')
+        fields.file = e.file;
+    if (typeof e.line === 'string')
+        fields.line = e.line;
+    if (typeof e.routine === 'string')
+        fields.routine = e.routine;
+    return fields;
+}
+/**
+ * Format PostgreSQL error fields into an array of human-readable lines.
+ * Only includes fields that are present and non-empty.
+ *
+ * @param fields - The PostgreSQL error fields to format
+ * @returns Array of formatted lines
+ */
+export function formatPgErrorFields(fields) {
+    const lines = [];
+    if (fields.detail)
+        lines.push(`Detail: ${fields.detail}`);
+    if (fields.hint)
+        lines.push(`Hint: ${fields.hint}`);
+    if (fields.where)
+        lines.push(`Where: ${fields.where}`);
+    if (fields.schema)
+        lines.push(`Schema: ${fields.schema}`);
+    if (fields.table)
+        lines.push(`Table: ${fields.table}`);
+    if (fields.column)
+        lines.push(`Column: ${fields.column}`);
+    if (fields.dataType)
+        lines.push(`Data Type: ${fields.dataType}`);
+    if (fields.constraint)
+        lines.push(`Constraint: ${fields.constraint}`);
+    if (fields.position)
+        lines.push(`Position: ${fields.position}`);
+    if (fields.internalQuery)
+        lines.push(`Internal Query: ${fields.internalQuery}`);
+    if (fields.internalPosition)
+        lines.push(`Internal Position: ${fields.internalPosition}`);
+    return lines;
+}
+/**
+ * Format a PostgreSQL error with full context for debugging.
+ * Combines the original error message with extended PostgreSQL fields
+ * and optional query context.
+ *
+ * @param err - The error object
+ * @param context - Optional query context (SQL and parameters)
+ * @returns Formatted error string with all available information
+ */
+export function formatPgError(err, context) {
+    if (!err || typeof err !== 'object') {
+        return String(err);
+    }
+    const e = err;
+    const message = typeof e.message === 'string' ? e.message : String(err);
+    const lines = [message];
+    // Add PostgreSQL error fields
+    const pgFields = extractPgErrorFields(err);
+    if (pgFields) {
+        const fieldLines = formatPgErrorFields(pgFields);
+        if (fieldLines.length > 0) {
+            lines.push(...fieldLines);
+        }
+    }
+    // Add query context
+    if (context?.query) {
+        lines.push(`Query: ${context.query}`);
+    }
+    if (context?.values !== undefined) {
+        lines.push(`Values: ${JSON.stringify(context.values)}`);
+    }
+    return lines.join('\n');
+}

package/esm/pgpm.js

@@ -40,6 +40,7 @@ export const pgpmDefaults = {
         strictAuth: false,
     },
     cdn: {
+        provider: 'minio',
         bucketName: 'test-bucket',
         awsRegion: 'us-east-1',
         awsAccessKey: 'minioadmin',

package/index.d.ts

@@ -1,5 +1,6 @@
 export * from './error';
 export * from './error-factory';
+export * from './pg-error-format';
 export * from './pgpm';
 export * from './jobs';
 export * from './update';

package/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./error"), exports);
 __exportStar(require("./error-factory"), exports);
+__exportStar(require("./pg-error-format"), exports);
 __exportStar(require("./pgpm"), exports);
 __exportStar(require("./jobs"), exports);
 __exportStar(require("./update"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgpmjs/types",
-  "version": "2.12.8",
+  "version": "2.14.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "PGPM types",
   "main": "index.js",
@@ -29,7 +29,7 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "pg-env": "^1.2.4"
+    "pg-env": "^1.2.5"
   },
   "keywords": [
     "types",
@@ -40,7 +40,7 @@
     "migrations"
   ],
   "devDependencies": {
-    "makage": "^0.1.9"
+    "makage": "^0.1.10"
   },
-  "gitHead": "c2e68f9808a87e3231d9b9af5e706bef5dbd2af8"
+  "gitHead": "f2f9c9851beff3214790dfca371e4ca7f6c1373f"
 }

package/pg-error-format.d.ts

@@ -0,0 +1,77 @@
+/**
+ * PostgreSQL Error Formatting Utilities
+ *
+ * Extracts and formats extended PostgreSQL error fields from pg library errors.
+ * These fields provide additional context for debugging database errors.
+ */
+/**
+ * Extended PostgreSQL error fields available from pg-protocol.
+ * These fields are populated by PostgreSQL when an error occurs.
+ */
+export interface PgErrorFields {
+    /** PostgreSQL error code (e.g., '42P01' for undefined table) */
+    code?: string;
+    /** Additional detail about the error */
+    detail?: string;
+    /** Suggestion for fixing the error */
+    hint?: string;
+    /** PL/pgSQL call stack or context */
+    where?: string;
+    /** Character position in the query where the error occurred */
+    position?: string;
+    /** Position in internal query */
+    internalPosition?: string;
+    /** Internal query that caused the error */
+    internalQuery?: string;
+    /** Schema name related to the error */
+    schema?: string;
+    /** Table name related to the error */
+    table?: string;
+    /** Column name related to the error */
+    column?: string;
+    /** Data type name related to the error */
+    dataType?: string;
+    /** Constraint name related to the error */
+    constraint?: string;
+    /** Source file in PostgreSQL where error was generated */
+    file?: string;
+    /** Line number in PostgreSQL source file */
+    line?: string;
+    /** PostgreSQL routine that generated the error */
+    routine?: string;
+}
+/**
+ * Context about the query that caused the error.
+ */
+export interface PgErrorContext {
+    /** The SQL query that was executed */
+    query?: string;
+    /** Parameter values passed to the query */
+    values?: any[];
+}
+/**
+ * Extract PostgreSQL error fields from an error object.
+ * Returns null if the error doesn't appear to be a PostgreSQL error.
+ *
+ * @param err - The error object to extract fields from
+ * @returns PgErrorFields if the error has PG fields, null otherwise
+ */
+export declare function extractPgErrorFields(err: unknown): PgErrorFields | null;
+/**
+ * Format PostgreSQL error fields into an array of human-readable lines.
+ * Only includes fields that are present and non-empty.
+ *
+ * @param fields - The PostgreSQL error fields to format
+ * @returns Array of formatted lines
+ */
+export declare function formatPgErrorFields(fields: PgErrorFields): string[];
+/**
+ * Format a PostgreSQL error with full context for debugging.
+ * Combines the original error message with extended PostgreSQL fields
+ * and optional query context.
+ *
+ * @param err - The error object
+ * @param context - Optional query context (SQL and parameters)
+ * @returns Formatted error string with all available information
+ */
+export declare function formatPgError(err: unknown, context?: PgErrorContext): string;

package/pg-error-format.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * PostgreSQL Error Formatting Utilities
+ *
+ * Extracts and formats extended PostgreSQL error fields from pg library errors.
+ * These fields provide additional context for debugging database errors.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractPgErrorFields = extractPgErrorFields;
+exports.formatPgErrorFields = formatPgErrorFields;
+exports.formatPgError = formatPgError;
+/**
+ * Extract PostgreSQL error fields from an error object.
+ * Returns null if the error doesn't appear to be a PostgreSQL error.
+ *
+ * @param err - The error object to extract fields from
+ * @returns PgErrorFields if the error has PG fields, null otherwise
+ */
+function extractPgErrorFields(err) {
+    if (!err || typeof err !== 'object') {
+        return null;
+    }
+    const e = err;
+    // Check if this looks like a PostgreSQL error (has code or detail)
+    if (!e.code && !e.detail && !e.where) {
+        return null;
+    }
+    const fields = {};
+    if (typeof e.code === 'string')
+        fields.code = e.code;
+    if (typeof e.detail === 'string')
+        fields.detail = e.detail;
+    if (typeof e.hint === 'string')
+        fields.hint = e.hint;
+    if (typeof e.where === 'string')
+        fields.where = e.where;
+    if (typeof e.position === 'string')
+        fields.position = e.position;
+    if (typeof e.internalPosition === 'string')
+        fields.internalPosition = e.internalPosition;
+    if (typeof e.internalQuery === 'string')
+        fields.internalQuery = e.internalQuery;
+    if (typeof e.schema === 'string')
+        fields.schema = e.schema;
+    if (typeof e.table === 'string')
+        fields.table = e.table;
+    if (typeof e.column === 'string')
+        fields.column = e.column;
+    if (typeof e.dataType === 'string')
+        fields.dataType = e.dataType;
+    if (typeof e.constraint === 'string')
+        fields.constraint = e.constraint;
+    if (typeof e.file === 'string')
+        fields.file = e.file;
+    if (typeof e.line === 'string')
+        fields.line = e.line;
+    if (typeof e.routine === 'string')
+        fields.routine = e.routine;
+    return fields;
+}
+/**
+ * Format PostgreSQL error fields into an array of human-readable lines.
+ * Only includes fields that are present and non-empty.
+ *
+ * @param fields - The PostgreSQL error fields to format
+ * @returns Array of formatted lines
+ */
+function formatPgErrorFields(fields) {
+    const lines = [];
+    if (fields.detail)
+        lines.push(`Detail: ${fields.detail}`);
+    if (fields.hint)
+        lines.push(`Hint: ${fields.hint}`);
+    if (fields.where)
+        lines.push(`Where: ${fields.where}`);
+    if (fields.schema)
+        lines.push(`Schema: ${fields.schema}`);
+    if (fields.table)
+        lines.push(`Table: ${fields.table}`);
+    if (fields.column)
+        lines.push(`Column: ${fields.column}`);
+    if (fields.dataType)
+        lines.push(`Data Type: ${fields.dataType}`);
+    if (fields.constraint)
+        lines.push(`Constraint: ${fields.constraint}`);
+    if (fields.position)
+        lines.push(`Position: ${fields.position}`);
+    if (fields.internalQuery)
+        lines.push(`Internal Query: ${fields.internalQuery}`);
+    if (fields.internalPosition)
+        lines.push(`Internal Position: ${fields.internalPosition}`);
+    return lines;
+}
+/**
+ * Format a PostgreSQL error with full context for debugging.
+ * Combines the original error message with extended PostgreSQL fields
+ * and optional query context.
+ *
+ * @param err - The error object
+ * @param context - Optional query context (SQL and parameters)
+ * @returns Formatted error string with all available information
+ */
+function formatPgError(err, context) {
+    if (!err || typeof err !== 'object') {
+        return String(err);
+    }
+    const e = err;
+    const message = typeof e.message === 'string' ? e.message : String(err);
+    const lines = [message];
+    // Add PostgreSQL error fields
+    const pgFields = extractPgErrorFields(err);
+    if (pgFields) {
+        const fieldLines = formatPgErrorFields(pgFields);
+        if (fieldLines.length > 0) {
+            lines.push(...fieldLines);
+        }
+    }
+    // Add query context
+    if (context?.query) {
+        lines.push(`Query: ${context.query}`);
+    }
+    if (context?.values !== undefined) {
+        lines.push(`Values: ${JSON.stringify(context.values)}`);
+    }
+    return lines.join('\n');
+}

package/pgpm.d.ts

@@ -96,10 +96,16 @@ export interface ServerOptions {
     /** Whether to enforce strict authentication */
     strictAuth?: boolean;
 }
+/**
+ * Storage provider type for CDN/bucket operations
+ */
+export type BucketProvider = 's3' | 'minio' | 'gcs';
 /**
  * CDN and file storage configuration
  */
 export interface CDNOptions {
+    /** Storage provider type (s3, minio, gcs). Defaults to 'minio' for local dev */
+    provider?: BucketProvider;
     /** S3 bucket name for file storage */
     bucketName?: string;
     /** AWS region for S3 bucket */
@@ -108,7 +114,7 @@ export interface CDNOptions {
     awsAccessKey?: string;
     /** AWS secret key for S3 */
     awsSecretKey?: string;
-    /** MinIO endpoint URL for local development */
+    /** MinIO endpoint URL for local development (only used when provider is 'minio') */
     minioEndpoint?: string;
 }
 /**

package/pgpm.js

@@ -44,6 +44,7 @@ exports.pgpmDefaults = {
         strictAuth: false,
     },
     cdn: {
+        provider: 'minio',
         bucketName: 'test-bucket',
         awsRegion: 'us-east-1',
         awsAccessKey: 'minioadmin',