|
1 | 1 | # Deparser Entry Point Analysis |
2 | 2 |
|
| 3 | +## Implementation Status |
| 4 | + |
| 5 | +✅ **Phase 1 Complete** (Commit: a240d13) |
| 6 | + |
| 7 | +### Implemented Changes: |
| 8 | + |
| 9 | +1. **Added Type Guards** |
| 10 | + - `isParseResult()` - Detects bare ParseResult objects |
| 11 | + - `isWrappedParseResult()` - Detects wrapped ParseResult nodes |
| 12 | + |
| 13 | +2. **Added ParseResult Method** |
| 14 | + - Handles wrapped ParseResult nodes properly |
| 15 | + - Filters null/undefined RawStmt entries |
| 16 | + - Joins statements with double newlines |
| 17 | + |
| 18 | +3. **Updated RawStmt Method** |
| 19 | + - Handles empty statements gracefully |
| 20 | + - Adds semicolons based on stmt_len presence |
| 21 | + |
| 22 | +4. **Refactored Constructor** |
| 23 | + - Uses type guards for proper type detection |
| 24 | + - Wraps bare ParseResult as `{ ParseResult: tree }` for consistency |
| 25 | + - Maintains backward compatibility |
| 26 | + |
| 27 | +5. **Updated deparseQuery()** |
| 28 | + - Filters out empty results |
| 29 | + - Joins with double newlines |
| 30 | + |
| 31 | +6. **Removed Unused Methods** |
| 32 | + - Removed `stmt()` method (never used) |
| 33 | + - Removed `version()` method (never used) |
| 34 | + |
| 35 | +7. **Added Comprehensive Documentation** |
| 36 | + - Clear explanation of all entry points |
| 37 | + - Important note about ParseResult.stmts structure |
| 38 | + - Examples for each entry point type |
| 39 | + |
| 40 | +8. **Added Test Suite** |
| 41 | + - 14 test cases covering all entry points |
| 42 | + - Tests for edge cases (empty objects, undefined stmts) |
| 43 | + - All tests passing |
| 44 | + |
| 45 | +### Key Clarification: |
| 46 | + |
| 47 | +The structure from libpg-query is: |
| 48 | +```typescript |
| 49 | +ParseResult { |
| 50 | + version: number; |
| 51 | + stmts: RawStmt[]; // Array of RawStmt objects directly (NOT wrapped) |
| 52 | +} |
| 53 | + |
| 54 | +// Each RawStmt in the array has this structure: |
| 55 | +RawStmt { |
| 56 | + stmt: Node; |
| 57 | + stmt_len?: number; |
| 58 | + stmt_location?: number; |
| 59 | +} |
| 60 | +``` |
| 61 | + |
| 62 | +This is different from wrapped nodes like `{ RawStmt: {...} }` which are used when explicitly creating a Node. |
| 63 | + |
3 | 64 | ## Overview |
4 | 65 |
|
5 | 66 | This document analyzes the entry points of the deparser system, focusing on how users interact with the top-level API and how we can refactor to make the system more consistent and intuitive. |
|
0 commit comments