@pgsql/transform-ast 18.3.0

package/18/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Dan Lynch <pyramation@gmail.com>
+
+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,141 @@
+# @pgsql/transform-ast
+
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/pgsql-parser/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/constructive-io/pgsql-parser/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+   <a href="https://github.com/constructive-io/pgsql-parser/blob/main/LICENSE-MIT"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
+   <a href="https://www.npmjs.com/package/@pgsql/transform-ast"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/pgsql-parser?filename=packages%2Ftransform-ast%2Fpackage.json"/></a>
+</p>
+
+`@pgsql/transform-ast` is a TypeScript library for transforming PostgreSQL ASTs between different PostgreSQL versions. It serves as a crucial component for building a single source of truth deparser that can handle SQL from multiple PostgreSQL versions while maintaining backward compatibility.
+
+## Transforming ASTs Between PG Versions
+
+The transform package enables you to:
+
+- **Transform legacy ASTs**: Convert ASTs from PostgreSQL versions 13-16 to version 17
+- **Build unified deparsers**: Create a single deparser pipeline that works with multiple PostgreSQL versions
+- **Maintain backward compatibility**: Support legacy codebases while leveraging the latest PostgreSQL features
+
+## Key Limitation
+
+This package only supports ASTs derived from SQL that is parseable by PostgreSQL 17. This means:
+
+- ✅ **Supported**: SQL from PG13-16 that remains valid in PG17
+- ❌ **Not supported**: Deprecated syntax from older versions that was removed
+- ❌ **Not supported**: SQL that cannot be parsed by the PG17 parser
+
+This design ensures all transformed ASTs can be reliably deparsed using the latest PostgreSQL grammar.
+
+## Installation
+
+```bash
+npm install @pgsql/transform-ast
+```
+
+## 🚀 Quick Start
+
+### Multi-Version Transformer
+
+```typescript
+import { ASTTransformer } from '@pgsql/transform-ast';
+
+const transformer = new ASTTransformer();
+
+// Transform any version to PG17
+const pg17Ast = transformer.transformToLatest(pg13Ast, 13);
+
+// Transform between specific versions
+const pg15Ast = transformer.transform(pg13Ast, 13, 15);
+
+// Convenience methods
+const result = transformer.transform13To17(pg13Ast);
+```
+
+### Direct Transformers
+
+For better performance when you know source and target versions:
+
+```typescript
+import { PG13ToPG17Transformer } from '@pgsql/transform-ast';
+
+const transformer = new PG13ToPG17Transformer();
+const pg17Ast = transformer.transform(pg13Ast);
+```
+
+### Integration Example
+
+```typescript
+import { parse } from '@pgsql/parser';
+import { deparse } from 'pgsql-deparser';
+import { PG13ToPG17Transformer } from '@pgsql/transform-ast';
+
+// Parse with older version
+const pg13Ast = await parse('SELECT * FROM users', { version: 13 });
+
+// Transform to latest
+const transformer = new PG13ToPG17Transformer();
+const pg17Ast = transformer.transform(pg13Ast);
+
+// Deparse with latest grammar
+const sql = await deparse(pg17Ast);
+```
+
+## 🔄 Transformation Chain
+
+**Incremental**: PG13 → PG14 → PG15 → PG16 → PG17
+- Step-by-step version upgrades
+- Useful for debugging transformation issues
+
+**Direct**: PG13 → PG17, PG14 → PG17, etc.
+- Single-step transformations
+- Optimized for performance
+
+## 📋 Supported Transformations
+
+| From | To | Transformer |
+|------|----|-----------| 
+| PG13 | PG14, PG15, PG16, PG17 | `V13ToV14Transformer`, `PG13ToPG17Transformer` |
+| PG14 | PG15, PG16, PG17 | `V14ToV15Transformer`, `PG14ToPG17Transformer` |
+| PG15 | PG16, PG17 | `V15ToV16Transformer`, `PG15ToPG17Transformer` |
+| PG16 | PG17 | `V16ToV17Transformer`, `PG16ToPG17Transformer` |
+
+## 🏗️ Architecture
+
+The transform package fits into the broader pgsql-parser ecosystem:
+
+1. **Parse** legacy SQL with version-specific parsers
+2. **Transform** ASTs to the latest version
+3. **Deparse** using the unified, latest-version deparser
+
+This enables a single source of truth for SQL generation while supporting legacy codebases.
+
+---
+
+**🛠 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).**
+
+## Related
+
+* [pgpm](https://pgpm.dev): A Postgres Package Manager that brings modular development to PostgreSQL with reusable packages, deterministic migrations, recursive dependency resolution, and tag-aware versioning.
+* [pgsql-test](https://www.npmjs.com/package/pgsql-test): Instant, isolated PostgreSQL databases for each test with automatic transaction rollbacks, context switching, and clean seeding for fast, reliable database testing.
+* [pgsql-seed](https://www.npmjs.com/package/pgsql-seed): PostgreSQL seeding utilities for CSV, JSON, SQL data loading, and pgpm deployment.
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): The real PostgreSQL parser for Node.js, providing symmetric parsing and deparsing of SQL statements with actual PostgreSQL parser integration.
+* [pgsql-deparser](https://www.npmjs.com/package/pgsql-deparser): A streamlined tool designed for converting PostgreSQL ASTs back into SQL queries, focusing solely on deparser functionality to complement `pgsql-parser`.
+* [@pgsql/parser](https://www.npmjs.com/package/@pgsql/parser): Multi-version PostgreSQL parser with dynamic version selection at runtime, supporting PostgreSQL 15, 16, and 17 in a single package.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): Offers TypeScript type definitions for PostgreSQL AST nodes, facilitating type-safe construction, analysis, and manipulation of ASTs.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): Provides TypeScript enum definitions for PostgreSQL constants, enabling type-safe usage of PostgreSQL enums and constants in your applications.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): A comprehensive utility library for PostgreSQL, offering type-safe AST node creation and enum value conversions, simplifying the construction and manipulation of PostgreSQL ASTs.
+* [@pgsql/traverse](https://www.npmjs.com/package/@pgsql/traverse): PostgreSQL AST traversal utilities for pgsql-parser, providing a visitor pattern for traversing PostgreSQL Abstract Syntax Tree nodes, similar to Babel's traverse functionality but specifically designed for PostgreSQL AST structures.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): A TypeScript tool that parses PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [libpg-query](https://github.com/constructive-io/libpg-query-node): The real PostgreSQL parser exposed for Node.js, used primarily in `pgsql-parser` for parsing and deparsing SQL queries.
+
+## 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 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 Software code or Software CLI, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/esm/13/enums.js

@@ -0,0 +1 @@
+export {};

package/esm/13/types.js

@@ -0,0 +1 @@
+export {};

package/esm/14/enums.js

@@ -0,0 +1 @@
+export {};

package/esm/14/types.js

@@ -0,0 +1 @@
+export {};

package/esm/15/enums.js

@@ -0,0 +1 @@
+export {};

package/esm/15/types.js

@@ -0,0 +1 @@
+export {};

package/esm/16/enums.js

@@ -0,0 +1 @@
+export {};

package/esm/16/types.js

@@ -0,0 +1 @@
+export {};

package/esm/17/enums.js

@@ -0,0 +1 @@
+export {};

package/esm/17/types.js

@@ -0,0 +1 @@
+export {};

package/esm/18/enums.js

@@ -0,0 +1 @@
+export {};

package/esm/18/types.js

@@ -0,0 +1 @@
+export {};

package/esm/index.js

@@ -0,0 +1,22 @@
+import * as PG13Types from './13/types';
+import * as PG14Types from './14/types';
+import * as PG15Types from './15/types';
+import * as PG16Types from './16/types';
+import * as PG17Types from './17/types';
+import * as PG18Types from './18/types';
+export { ASTTransformer } from './multi-version-transformer';
+export { V13ToV14Transformer } from './transformers/v13-to-v14';
+export { V14ToV15Transformer } from './transformers/v14-to-v15';
+export { V15ToV16Transformer } from './transformers/v15-to-v16';
+export { V16ToV17Transformer } from './transformers/v16-to-v17';
+export { V17ToV18Transformer } from './transformers/v17-to-v18';
+export { PG13ToPG17Transformer } from './transformers-direct/v13-to-v17';
+export { PG14ToPG17Transformer } from './transformers-direct/v14-to-v17';
+export { PG15ToPG17Transformer } from './transformers-direct/v15-to-v17';
+export { PG16ToPG17Transformer } from './transformers-direct/v16-to-v17';
+export { PG13ToPG18Transformer } from './transformers-direct/v13-to-v18';
+export { PG14ToPG18Transformer } from './transformers-direct/v14-to-v18';
+export { PG15ToPG18Transformer } from './transformers-direct/v15-to-v18';
+export { PG16ToPG18Transformer } from './transformers-direct/v16-to-v18';
+export { PG17ToPG18Transformer } from './transformers-direct/v17-to-v18';
+export { PG13Types, PG14Types, PG15Types, PG16Types, PG17Types, PG18Types };

package/esm/multi-version-transformer.js

@@ -0,0 +1,80 @@
+import { V13ToV14Transformer } from './transformers/v13-to-v14';
+import { V14ToV15Transformer } from './transformers/v14-to-v15';
+import { V15ToV16Transformer } from './transformers/v15-to-v16';
+import { V16ToV17Transformer } from './transformers/v16-to-v17';
+import { V17ToV18Transformer } from './transformers/v17-to-v18';
+export class ASTTransformer {
+    transformers = {
+        '13-14': new V13ToV14Transformer(),
+        '14-15': new V14ToV15Transformer(),
+        '15-16': new V15ToV16Transformer(),
+        '16-17': new V16ToV17Transformer(),
+        '17-18': new V17ToV18Transformer(),
+    };
+    transform(ast, fromVersion, toVersion) {
+        if (fromVersion === toVersion) {
+            return ast;
+        }
+        if (fromVersion > toVersion) {
+            throw new Error(`Cannot transform backwards from v${fromVersion} to v${toVersion}`);
+        }
+        let currentAst = ast;
+        let currentVersion = fromVersion;
+        while (currentVersion < toVersion) {
+            const nextVersion = currentVersion + 1;
+            const transformerKey = `${currentVersion}-${nextVersion}`;
+            // Use explicit switch to avoid complex union types
+            switch (transformerKey) {
+                case '13-14':
+                    currentAst = this.transformers['13-14'].transform(currentAst, { parentNodeTypes: [] });
+                    break;
+                case '14-15':
+                    currentAst = this.transformers['14-15'].transform(currentAst, { parentNodeTypes: [] });
+                    break;
+                case '15-16':
+                    currentAst = this.transformers['15-16'].transform(currentAst, { parentNodeTypes: [] });
+                    break;
+                case '16-17':
+                    currentAst = this.transformers['16-17'].transform(currentAst, { parentNodeTypes: [] });
+                    break;
+                case '17-18':
+                    currentAst = this.transformers['17-18'].transform(currentAst, { parentNodeTypes: [] });
+                    break;
+                default:
+                    throw new Error(`No transformer available for v${currentVersion} to v${nextVersion}`);
+            }
+            currentVersion = nextVersion;
+        }
+        return currentAst;
+    }
+    transformToLatest(ast, fromVersion) {
+        return this.transform(ast, fromVersion, 18);
+    }
+    transform13To17(ast) {
+        return this.transform(ast, 13, 17);
+    }
+    transform14To17(ast) {
+        return this.transform(ast, 14, 17);
+    }
+    transform15To17(ast) {
+        return this.transform(ast, 15, 17);
+    }
+    transform16To17(ast) {
+        return this.transform(ast, 16, 17);
+    }
+    transform13To18(ast) {
+        return this.transform(ast, 13, 18);
+    }
+    transform14To18(ast) {
+        return this.transform(ast, 14, 18);
+    }
+    transform15To18(ast) {
+        return this.transform(ast, 15, 18);
+    }
+    transform16To18(ast) {
+        return this.transform(ast, 16, 18);
+    }
+    transform17To18(ast) {
+        return this.transform(ast, 17, 18);
+    }
+}

package/esm/transformers/context.js

@@ -0,0 +1 @@
+export {};