@polyglot-sql/sdk 0.1.10 → 0.1.12

package/README.md

@@ -532,7 +532,7 @@ if (!result.success) {
 Trace how columns flow through SQL queries, from source tables to the result set.
 
 ```typescript
-import { lineage, getSourceTables } from '@polyglot-sql/sdk';
+import { lineage, lineageWithSchema, getSourceTables } from '@polyglot-sql/sdk';
 
 // Trace a column through joins, CTEs, and subqueries
 const result = lineage('total', 'SELECT o.total FROM orders o JOIN users u ON o.user_id = u.id');
@@ -541,6 +541,19 @@ if (result.success) {
   console.log(result.lineage.downstream);  // source nodes
 }
 
+// Schema-aware lineage (same schema format as validateWithSchema)
+const schema = {
+  tables: [
+    { name: 'users', columns: [{ name: 'id', type: 'INT' }] },
+    { name: 'orders', columns: [{ name: 'user_id', type: 'INT' }] },
+  ],
+};
+const schemaLineage = lineageWithSchema(
+  'id',
+  'SELECT id FROM users u JOIN orders o ON u.id = o.user_id',
+  schema,
+);
+
 // Get all source tables that contribute to a column
 const tables = getSourceTables('total', 'SELECT o.total FROM orders o JOIN users u ON o.user_id = u.id');
 if (tables.success) {
@@ -625,6 +638,7 @@ const formattedSafe = pg.formatWithOptions('SELECT a,b FROM t', Dialect.Generic,
 | Function | Description |
 |----------|-------------|
 | `lineage(column, sql, dialect?, trimSelects?)` | Trace column lineage through a query |
+| `lineageWithSchema(column, sql, schema, dialect?, trimSelects?)` | Trace lineage with schema-based qualification |
 | `getSourceTables(column, sql, dialect?)` | Get source tables for a column |
 | `diff(source, target, dialect?, options?)` | Diff two SQL statements |
 | `hasChanges(edits)` | Check if diff has non-keep edits |
@@ -804,6 +818,113 @@ console.log(isInitialized()); // true
 
 > **Note:** The ESM build (`import`) auto-initializes via top-level `await`, so `init()` is not required there. The CJS build requires it because `require()` is synchronous.
 
+## Bundler Configuration
+
+The ESM build uses **top-level `await`** (ES2022) and **`new URL("...", import.meta.url)`** for WASM loading. Both are web standards supported by all modern bundlers, but some require explicit configuration.
+
+### Vite
+
+Vite works out of the box with `vite-plugin-wasm`. This is the setup used by the [Polyglot Playground](https://github.com/tobilg/polyglot):
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import wasm from 'vite-plugin-wasm';
+
+export default defineConfig({
+  plugins: [wasm()],
+  build: {
+    target: 'esnext', // required for top-level await
+  },
+  optimizeDeps: {
+    exclude: ['@polyglot-sql/sdk'], // prevent esbuild from pre-bundling WASM
+  },
+});
+```
+
+### Next.js
+
+Next.js requires enabling WebAssembly experiments in the webpack config:
+
+```javascript
+// next.config.js
+module.exports = {
+  webpack: (config) => {
+    config.experiments = {
+      ...config.experiments,
+      asyncWebAssembly: true,
+      topLevelAwait: true,
+      layers: true,
+    };
+    return config;
+  },
+};
+```
+
+For **production SSR builds**, Next.js may emit `.wasm` files at a different path than where it tries to load them. A common workaround is to add a plugin that fixes the output path:
+
+```javascript
+// next.config.js
+class WasmChunksFixPlugin {
+  apply(compiler) {
+    compiler.hooks.thisCompilation.tap('WasmChunksFixPlugin', (compilation) => {
+      compilation.hooks.processAssets.tap(
+        { name: 'WasmChunksFixPlugin' },
+        (assets) =>
+          Object.entries(assets).forEach(([pathname, source]) => {
+            if (!pathname.match(/\.wasm$/)) return;
+            compilation.deleteAsset(pathname);
+            const name = pathname.split('/')[1];
+            const info = compilation.assetsInfo.get(pathname);
+            compilation.emitAsset(name, source, info);
+          })
+      );
+    });
+  }
+}
+
+module.exports = {
+  webpack: (config, { isServer, dev }) => {
+    config.experiments = {
+      ...config.experiments,
+      asyncWebAssembly: true,
+      topLevelAwait: true,
+      layers: true,
+    };
+    if (!dev && isServer) {
+      config.output.webassemblyModuleFilename = 'chunks/[id].wasm';
+      config.plugins.push(new WasmChunksFixPlugin());
+    }
+    return config;
+  },
+};
+```
+
+### webpack 5 (standalone)
+
+Enable the required experiments in your webpack config:
+
+```javascript
+// webpack.config.js
+module.exports = {
+  experiments: {
+    asyncWebAssembly: true,
+    topLevelAwait: true,
+  },
+  // ...
+};
+```
+
+`topLevelAwait` is enabled by default since webpack 5.83.0. `asyncWebAssembly` must be set explicitly.
+
+### Troubleshooting
+
+If you see `undefined` exports (e.g., `Dialect` is `undefined`) or errors about `require("fs")`:
+
+1. Make sure `asyncWebAssembly` and `topLevelAwait` experiments are enabled in your bundler config
+2. Ensure the bundler is resolving the ESM build (the `"import"` or `"browser"` export condition), not the CJS build which uses Node.js APIs
+3. For SSR frameworks (Next.js, Nuxt), check that the `.wasm` file is correctly included in the server build output
+
 ## License
 
 [MIT](../../LICENSE)