Merge pull request #129 from launchql/multi/parser

Multi/parser

Author: pyramation

.github/workflows/ci.yml

@@ -163,6 +163,18 @@ jobs:
         run: pnpm install
         working-directory: parser
 
+      - name: Download v13 WASM Artifacts 📥
+        uses: actions/download-artifact@v4
+        with:
+          name: wasm-artifacts-v13
+          path: versions/13/wasm/
+
+      - name: Download v14 WASM Artifacts 📥
+        uses: actions/download-artifact@v4
+        with:
+          name: wasm-artifacts-v14
+          path: versions/14/wasm/
+
       - name: Download v15 WASM Artifacts 📥
         uses: actions/download-artifact@v4
         with:
@@ -181,6 +193,15 @@ jobs:
           name: wasm-artifacts-v17
           path: versions/17/wasm/
 
+      - name: Build Types Packages 🏗
+        run: |
+          for version in 13 14 15 16 17; do
+            echo "Building types for v${version}..."
+            cd types/${version}
+            pnpm run build
+            cd ../..
+          done
+
       - name: Build Parser 🏗
         run: pnpm run build
         working-directory: parser
@@ -234,6 +255,18 @@ jobs:
         run: pnpm install
         working-directory: parser
 
+      - name: Download v13 WASM Artifacts 📥
+        uses: actions/download-artifact@v4
+        with:
+          name: wasm-artifacts-v13
+          path: versions/13/wasm/
+
+      - name: Download v14 WASM Artifacts 📥
+        uses: actions/download-artifact@v4
+        with:
+          name: wasm-artifacts-v14
+          path: versions/14/wasm/
+
       - name: Download v15 WASM Artifacts 📥
         uses: actions/download-artifact@v4
         with:

.gitignore

@@ -25,3 +25,4 @@ libpg_query/**/*.proto
 npm-debug.log
 .claude
 .openhands/
+.DS_Store

PUBLISH.md

@@ -41,6 +41,39 @@ This interactive script will:
 - Build, prepare, and publish each selected version
 - Optionally promote pg17 to latest
 
+### Parser Package
+
+The parser package supports multiple build configurations:
+
+#### Full Build (all versions 13-17)
+```bash
+pnpm run publish:parser
+# or with specific build type
+PARSER_BUILD_TYPE=full pnpm run publish:parser
+```
+
+#### LTS Build (versions 16-17)
+```bash
+PARSER_BUILD_TYPE=lts pnpm run publish:parser
+```
+
+#### Latest Only (version 17)
+```bash
+PARSER_BUILD_TYPE=latest pnpm run publish:parser
+```
+
+#### Legacy Build (versions 13-15)
+```bash
+PARSER_BUILD_TYPE=legacy pnpm run publish:parser
+```
+
+This command will:
+- Navigate to the parser directory
+- Build the parser with the specified configuration
+- Publish the @pgsql/parser package to npm with appropriate dist-tag
+- Note: You should manually bump the version and commit changes before running this
+- **Prerequisite**: The version packages must be built first as the parser copies their WASM files during build
+
 ## Manual Publishing
 
 ### Types Packages
@@ -156,4 +189,118 @@ npm dist-tag add @libpg-query/parser@pg17 latest
 ```bash
 npm install @libpg-query/parser@pg17   # PostgreSQL 17 specific
 npm install @libpg-query/parser        # Latest version
+```
+
+## Parser Package (@pgsql/parser)
+
+### Quick Publish
+```bash
+cd parser
+pnpm version patch
+git add . && git commit -m "release: bump @pgsql/parser version"
+pnpm build
+pnpm test
+pnpm publish
+```
+
+### Build Configurations
+
+The parser package is now a simple distribution package that copies pre-built WASM files. No TypeScript compilation needed!
+
+#### Available Build Types:
+- **full**: All versions (13, 14, 15, 16, 17) - Default
+- **lts**: LTS versions only (16, 17)
+- **latest**: Latest version only (17)
+- **legacy**: Legacy versions (13, 14, 15)
+
+```bash
+# Full build (default)
+npm run build
+
+# Specific builds
+npm run build:lts
+npm run build:latest
+npm run build:legacy
+
+# Or using environment variable
+PARSER_BUILD_TYPE=lts npm run build
+```
+
+### Build Process
+The simplified parser package:
+1. Copies WASM files from the `versions/*/wasm/` directories
+2. Copies TypeScript type definitions from the `types/*/dist/` directories
+3. Updates import paths to use local types instead of `@pgsql/types`
+4. Generates index files from templates based on the build configuration
+5. Creates version-specific export files
+6. Creates a `build-info.json` file documenting what was included
+
+The templates automatically adjust to include only the versions specified in the build configuration, ensuring proper TypeScript types and runtime validation. The package is completely self-contained with all necessary types bundled.
+
+**Note**: Build scripts use `cross-env` for Windows compatibility.
+
+**Important**: Before building the parser package, ensure that the version packages are built first:
+```bash
+# Build all version packages first
+pnpm build  # builds libpg-query versions
+
+# Then build the parser with desired configuration
+cd parser
+npm run build:lts  # or build:full, build:latest, etc.
+```
+
+### Types Bundling
+The parser build process automatically:
+1. Copies TypeScript type definitions from `types/*/dist/` directories
+2. Places them in `wasm/v*/types/` for each version
+3. Updates all import references from `@pgsql/types` to `./types`
+4. Makes the package self-contained without external type dependencies
+
+### Publishing with Different Tags
+
+```bash
+# Publish full version as latest
+npm run build:full
+npm publish
+
+# Publish LTS version with lts tag
+npm run build:lts
+npm publish --tag lts
+
+# Publish legacy version with legacy tag
+npm run build:legacy
+npm publish --tag legacy
+```
+
+### What it does
+- Publishes `@pgsql/parser` - a multi-version PostgreSQL parser with dynamic version selection
+- Provides a unified interface to work with multiple PostgreSQL versions
+- Supports different build configurations for different use cases
+- Includes both CommonJS and ESM builds
+- Exports version-specific parsers via subpaths (e.g., `@pgsql/parser/v17`)
+- **Self-contained**: Bundles TypeScript types locally (no external @pgsql/types dependency)
+
+### Install published package
+```bash
+# Install latest (full build)
+npm install @pgsql/parser
+
+# Install LTS version
+npm install @pgsql/parser@lts
+
+# Install legacy version
+npm install @pgsql/parser@legacy
+
+# Use version-specific imports:
+# import { parse } from '@pgsql/parser/v17'
+# import { parse } from '@pgsql/parser/v16'
+# import { parse } from '@pgsql/parser/v13'
+```
+
+### Alternative: Using npm scripts from root
+```bash
+# From the repository root:
+pnpm build:parser    # Build the parser package (full build)
+PARSER_BUILD_TYPE=lts pnpm build:parser  # Build LTS version
+pnpm publish:parser  # Publish the parser package
 ```

package.json

@@ -21,6 +21,9 @@
     "publish:versions": "node scripts/publish-versions.js",
     "update:versions-types": "node scripts/update-versions-types.js",
     "build:parser": "pnpm --filter @pgsql/parser build",
+    "build:parser:lts": "PARSER_BUILD_TYPE=lts pnpm --filter @pgsql/parser build",
+    "build:parser:full": "PARSER_BUILD_TYPE=full pnpm --filter @pgsql/parser build",
+    "build:parser:legacy": "PARSER_BUILD_TYPE=legacy pnpm --filter @pgsql/parser build",
     "test:parser": "pnpm --filter @pgsql/parser test",
     "publish:parser": "pnpm --filter @pgsql/parser publish"
   },

parser/.gitignore

@@ -1,10 +1,4 @@
 node_modules/
-dist/
-dist-esm/
+wasm/
 *.log
-.DS_Store
-src/wasm/*.wasm
-src/wasm/*.js
-src/types/15/
-src/types/16/
-src/types/17/
+.DS_Store

parser/Makefile.shared

@@ -13,12 +13,19 @@
    <a href="https://github.com/launchql/libpg-query-node/actions/workflows/ci.yml"><img height="20" src="https://img.shields.io/badge/Linux-available-333333?logo=linux&logoColor=white" /></a>
 </p>
 
-Multi-version PostgreSQL parser with dynamic version selection. This package provides a unified interface to parse PostgreSQL queries using different parser versions (15, 16, 17).
+Multi-version PostgreSQL parser with dynamic version selection. This package provides a unified interface to parse PostgreSQL queries using different parser versions (13, 14, 15, 16, 17).
 
 ## Installation
 
 ```bash
+# Install latest (full build with all versions)
 npm install @pgsql/parser
+
+# Install LTS version (PostgreSQL 16-17 only)
+npm install @pgsql/parser@lts
+
+# Install legacy version (PostgreSQL 13-15 only)
+npm install @pgsql/parser@legacy
 ```
 
 ## Usage
@@ -71,12 +78,12 @@ if (result.error) {
 
 ## API
 
-### `parse(query: string, version?: 15 | 16 | 17): Promise<ParseResult>`
+### `parse(query: string, version?: 13 | 14 | 15 | 16 | 17): Promise<ParseResult>`
 
 Parse a SQL query with the specified PostgreSQL version.
 
 - `query`: The SQL query string to parse
-- `version`: PostgreSQL version (15, 16, or 17). Defaults to 17.
+- `version`: PostgreSQL version (13, 14, 15, 16, or 17). Defaults to 17.
 
 Returns a promise that resolves to:
 - On success: `{ version: number, result: AST }`
@@ -88,12 +95,14 @@ Class for creating a parser instance with a specific version.
 
 ```javascript
 const parser = new PgParser(version);
-await parser.parse(query);
-parser.parseSync(query); // Only available after first parse()
+const result = await parser.parse(query);
+const syncResult = parser.parseSync(query); // Only available after first parse()
 ```
 
 ## Version Exports
 
+- `@pgsql/parser/v13` - PostgreSQL 13 parser
+- `@pgsql/parser/v14` - PostgreSQL 14 parser
 - `@pgsql/parser/v15` - PostgreSQL 15 parser
 - `@pgsql/parser/v16` - PostgreSQL 16 parser  
 - `@pgsql/parser/v17` - PostgreSQL 17 parser
@@ -103,6 +112,20 @@ Each version export provides:
 - `parse(query)`: Parse a query (async)
 - `parseSync(query)`: Parse a query (sync, requires loadModule first)
 
+## Build Configurations
+
+This package supports different build configurations for different use cases:
+
+- **full** (default): All versions (13, 14, 15, 16, 17)
+- **lts**: LTS versions only (16, 17)
+- **latest**: Latest version only (17)
+- **legacy**: Legacy versions (13, 14, 15)
+
+When installing from npm, you can choose the appropriate build using tags:
+- `npm install @pgsql/parser` - Full build
+- `npm install @pgsql/parser@lts` - LTS build
+- `npm install @pgsql/parser@legacy` - Legacy build
+
 ## Credits
 
 Built on the excellent work of several contributors: