Document libpg_query C Functions and WASM Wrapper Improvements

.npmignore

@@ -4,7 +4,7 @@ test
 .travis.yml
 package.json
 build
-docker
+
 libpg_query/**/*.a
 libpg_query/**/*.h
 

CHANGELOG.md

@@ -1,3 +1,14 @@
+# 17.2.1
+* Remove proto.js dependency (5.4MB bundle size reduction)
+* Add normalize() and normalizeSync() functions for SQL normalization
+* Add parseQueryDetailed() and parseQueryDetailedSync() with enhanced error reporting
+* Add fingerprint() and fingerprintSync() functions for query fingerprinting
+* Add isReady() function to check WASM module initialization status
+* Improve memory management and error handling in WASM wrapper
+* Remove unused dependencies (lodash, deasync, @launchql/protobufjs)
+* Split test suite into separate files for better organization
+* Update documentation with comprehensive function examples
+
 # 1.2.1
 * Rename package
 

Makefile

@@ -50,12 +50,13 @@ $(LIBPG_QUERY_ARCHIVE): $(LIBPG_QUERY_DIR)
 # Build libpg-query-node WASM module
 $(OUT_FILES): $(LIBPG_QUERY_ARCHIVE) $(LIBPG_QUERY_HEADER) $(SRC_FILES)
 ifdef EMSCRIPTEN
-	@ $(CC) \
+	$(CC) \
+		-v \
 		$(CXXFLAGS) \
 		-I$(LIBPG_QUERY_DIR) \
 		-L$(LIBPG_QUERY_DIR) \
-		-sEXPORTED_FUNCTIONS="['_malloc','_free','_wasm_parse_query','_wasm_deparse_protobuf','_wasm_parse_plpgsql','_wasm_fingerprint','_wasm_free_string']" \
-		-sEXPORTED_RUNTIME_METHODS="['lengthBytesUTF8','stringToUTF8','UTF8ToString','HEAPU8']" \
+		-sEXPORTED_FUNCTIONS="['_malloc','_free','_wasm_parse_query','_wasm_parse_query_protobuf','_wasm_get_protobuf_len','_wasm_deparse_protobuf','_wasm_parse_plpgsql','_wasm_fingerprint','_wasm_normalize_query','_wasm_parse_query_detailed','_wasm_free_detailed_result','_wasm_free_string']" \
+		-sEXPORTED_RUNTIME_METHODS="['lengthBytesUTF8','stringToUTF8','UTF8ToString','HEAPU8','HEAPU32']" \
 		-sEXPORT_NAME="$(WASM_MODULE_NAME)" \
 		-sENVIRONMENT="web,node" \
 		-sMODULARIZE=1 \

README.md

@@ -113,6 +113,100 @@ const sql = deparseSync(parseTree[0]);
 // Returns: string - reconstructed SQL query
 ```
 
+### `fingerprint(sql: string): Promise<string>`
+
+Generates a unique fingerprint for a SQL query that can be used for query identification and caching. Returns a Promise for a 16-character fingerprint string.
+
+```typescript
+import { fingerprint } from 'libpg-query';
+
+const fp = await fingerprint('SELECT * FROM users WHERE active = $1');
+// Returns: string - unique 16-character fingerprint (e.g., "50fde20626009aba")
+```
+
+### `fingerprintSync(sql: string): string`
+
+Synchronous version that generates a unique fingerprint for a SQL query directly.
+
+```typescript
+import { fingerprintSync } from 'libpg-query';
+
+const fp = fingerprintSync('SELECT * FROM users WHERE active = $1');
+// Returns: string - unique 16-character fingerprint
+```
+
+### `normalize(sql: string): Promise<string>`
+
+Normalizes a SQL query by removing comments, standardizing whitespace, and converting to a canonical form. Returns a Promise for the normalized SQL string.
+
+```typescript
+import { normalize } from 'libpg-query';
+
+const normalized = await normalize('SELECT * FROM users WHERE active = true');
+// Returns: string - normalized SQL query
+```
+
+### `normalizeSync(sql: string): string`
+
+Synchronous version that normalizes a SQL query directly.
+
+```typescript
+import { normalizeSync } from 'libpg-query';
+
+const normalized = normalizeSync('SELECT * FROM users WHERE active = true');
+// Returns: string - normalized SQL query
+```
+
+### `parseQueryDetailed(sql: string): Promise<DetailedParseResult>`
+
+Parses a SQL query with enhanced error reporting that includes detailed location information for parse errors. Returns a Promise for either the parse tree or detailed error information.
+
+```typescript
+import { parseQueryDetailed } from 'libpg-query';
+
+try {
+  const result = await parseQueryDetailed('SELECT * FROM users WHERE');
+} catch (error) {
+  // Enhanced error with line number, position, and context information
+  console.log(error.message); // "Parse error: syntax error at end of input at line 1, position 26"
+}
+```
+
+### `parseQueryDetailedSync(sql: string): DetailedParseResult`
+
+Synchronous version of detailed parsing with enhanced error reporting.
+
+```typescript
+import { parseQueryDetailedSync } from 'libpg-query';
+
+const result = parseQueryDetailedSync('SELECT * FROM users WHERE active = true');
+// Returns: DetailedParseResult with enhanced error information if parsing fails
+```
+
+### `isReady(): boolean`
+
+Checks if the WebAssembly module is initialized and ready for synchronous operations. This is useful when using sync methods to avoid "WASM module not initialized" errors.
+
+```typescript
+import { isReady, parseQuerySync, parseQuery } from 'libpg-query';
+
+// Check if module is ready before using sync methods
+if (isReady()) {
+  const result = parseQuerySync('SELECT * FROM users');
+} else {
+  // Initialize by calling any async method first
+  await parseQuery('SELECT 1');
+  // Now sync methods will work
+  const result = parseQuerySync('SELECT * FROM users');
+}
+
+// Alternative pattern - always safe
+if (!isReady()) {
+  await parseQuery('SELECT 1'); // Initialize module
+}
+const result = parseQuerySync('SELECT * FROM users');
+```
+
 ### Type Definitions
 
 ```typescript
@@ -138,43 +232,33 @@ This package uses a **WASM-only build system** for true cross-platform compatibi
 ### Prerequisites
 
 - Node.js (version 16 or higher recommended)
-- Docker (for WASM compilation using Emscripten)
-- yarn or npm
 
 ### Building WASM Artifacts
 
 1. **Install dependencies:**
    ```bash
    npm install
-   # or
-   yarn install
    ```
 
 2. **Build WASM artifacts:**
    ```bash
    npm run wasm:build
-   # or
-   yarn wasm:build
    ```
 
 3. **Clean WASM build (if needed):**
    ```bash
    npm run wasm:clean
-   # or
-   yarn wasm:clean
    ```
 
 4. **Rebuild WASM artifacts from scratch:**
    ```bash
    npm run wasm:clean && npm run wasm:build
-   # or
-   yarn wasm:clean && yarn wasm:build
    ```
 
 ### Build Process Details
 
 The WASM build process:
-- Uses Docker with Emscripten SDK for compilation
+- Uses Emscripten SDK for compilation
 - Compiles C wrapper code to WebAssembly
 - Generates `wasm/libpg-query.js` and `wasm/libpg-query.wasm` files
 - No native compilation or node-gyp dependencies required
@@ -185,8 +269,6 @@ The WASM build process:
 
 ```bash
 npm test
-# or
-yarn test
 ```
 
 ### Test Requirements
@@ -228,9 +310,9 @@ Our latest is built with `17-latest` branch from libpg_query
 - Ensure you call an async method first to initialize the WASM module
 - Or use the async versions of methods which handle initialization automatically
 
-**Docker permission errors:**
-- Ensure Docker is running and accessible
-- On Linux, you may need to add your user to the docker group
+**Build environment issues:**
+- Ensure Emscripten SDK is properly installed and configured
+- Check that all required build dependencies are available
 
 ### Build Artifacts
 

index.d.ts

@@ -1,4 +1,5 @@
 import { ParseResult } from "@pgsql/types";
+
 export function parseQuery(sql: string): Promise<ParseResult>;
 export function parsePlPgSQL(funcsSql: string): Promise<any>;
 export function parseQuerySync(sql: string): ParseResult;
@@ -7,4 +8,9 @@ export function deparse(parseTree: any): Promise<string>;
 export function deparseSync(parseTree: any): any;
 export function fingerprint(sql: string): Promise<string>;
 export function fingerprintSync(sql: string): string;
-export * from '@pgsql/types';
+export function normalize(sql: string): Promise<string>;
+export function normalizeSync(sql: string): string;
+export function parseQueryDetailed(sql: string): Promise<ParseResult>;
+export function parseQueryDetailedSync(sql: string): ParseResult;
+export function isReady(): boolean;
+export * from '@pgsql/types';

index.js

@@ -17,14 +17,31 @@ function fingerprintSync(query) {
   return wasmModule.fingerprintSync(query);
 }
 
+function normalizeSync(query) {
+  return wasmModule.normalizeSync(query);
+}
+
+function parseQueryDetailedSync(query) {
+  return wasmModule.parseQueryDetailedSync(query);
+}
+
+function isReady() {
+  return wasmModule.isReady();
+}
+
 module.exports = {
   parseQuery: wasmModule.parseQuery,
   deparse: wasmModule.deparse,
   parsePlPgSQL: wasmModule.parsePlPgSQL,
   fingerprint: wasmModule.fingerprint,
+  normalize: wasmModule.normalize,
+  parseQueryDetailed: wasmModule.parseQueryDetailed,
 
   parseQuerySync,
   deparseSync,
   parsePlPgSQLSync,
-  fingerprintSync
+  fingerprintSync,
+  normalizeSync,
+  parseQueryDetailedSync,
+  isReady
 };