npm package: @postgres-language-server/wasm
Description: WebAssembly bindings for the Postgres Language Server
Author: Supabase Community
Latest version: 0.24.0

# @postgres-language-server/wasm

WebAssembly bindings for the Postgres Language Server. This package provides two independent APIs for working with PostgreSQL SQL in the browser and Node.js.

## Installation

```bash
npm install @postgres-language-server/wasm
# or
bun add @postgres-language-server/wasm
```

## Two APIs

This package provides two separate APIs. Choose the one that fits your use case:

| API                | Use Case                            | Import Path                                |
| ------------------ | ----------------------------------- | ------------------------------------------ |
| **Workspace**      | Direct parse, lint, complete, hover | `@postgres-language-server/wasm/workspace` |
| **LanguageServer** | Full LSP JSON-RPC protocol          | `@postgres-language-server/wasm/lsp`       |

Each API manages its own workspace independently. Use one or the other, not both.

## Workspace API

Use this for custom editor integrations, build-time SQL linting, or simple tooling that doesn't need full LSP.

```typescript
import { createWorkspace } from "@postgres-language-server/wasm/workspace";

const workspace = await createWorkspace();

// Parse SQL and get errors
const errors = workspace.parse("SELECT * FROM users;");
console.log(errors); // []

// Split SQL into individual statements
const statements = workspace.splitStatements("SELECT 1; SELECT 2;");
// [{ sql: "SELECT 1;", start: 0, end: 9 }, { sql: "SELECT 2;", start: 10, end: 19 }]

// Insert a file and lint it
workspace.insertFile("/query.sql", "SELECT * FROM users;");
const diagnostics = workspace.lint("/query.sql");

// Get completions
const completions = workspace.complete("/query.sql", 14); // position after "FROM "

// Get hover info
const hover = workspace.hover("/query.sql", 14); // position over "users"
```

### With Schema

For schema-aware completions and hover, provide your database schema.
TypeScript types exported as `SchemaCache`:

```typescript
import type { SchemaCache } from '@postgres-language-server/wasm';

const workspace = await createWorkspace();

// Set schema
workspace.setSchema(JSON.stringify({
  schemas: [{ id: 1, name: 'public', owner: 'postgres', ... }],
  tables: [{ id: 1, schema: 'public', name: 'users', ... }],
  columns: [{ name: 'id', table_name: 'users', type_name: 'integer', ... }],
  functions: [],
  types: [],
  // ...
} satisfies SchemaCache));

workspace.insertFile('/query.sql', 'SELECT * FROM ');
const completions = workspace.complete('/query.sql', 14);
// completions now include 'users' table
```

## LanguageServer API

Use this for Monaco editor integration with `monaco-languageclient` or any editor that speaks LSP protocol.

```typescript
import { createLanguageServer } from "@postgres-language-server/wasm/lsp";

const lsp = await createLanguageServer();

// Handle LSP messages
const responses = lsp.handleMessage({
  jsonrpc: "2.0",
  id: 1,
  method: "initialize",
  params: { capabilities: {} },
});

// responses is an array of outgoing messages
for (const msg of responses) {
  // Send to client...
}
```

### Web Worker Integration

For Monaco editor, run the language server in a web worker:

```typescript
// lsp-worker.js
import { createLanguageServer } from "@postgres-language-server/wasm/lsp";

let lsp = null;

self.onmessage = async (event) => {
  if (!lsp) {
    lsp = await createLanguageServer();
    self.postMessage({ type: "ready" });
  }

  const responses = lsp.handleMessage(event.data);
  for (const msg of responses) {
    self.postMessage(msg);
  }
};
```

### Setting Schema via LSP

Use the `pgls/setSchema` notification:

```typescript
lsp.handleMessage({
  jsonrpc: "2.0",
  method: "pgls/setSchema",
  params: { schema: JSON.stringify(schemaCache) },
});
```

## API Reference

### Workspace

| Method                      | Description                                 |
| --------------------------- | ------------------------------------------- |
| `parse(sql: string)`        | Parse SQL, returns array of error messages  |
| `splitStatements(sql)`      | Split SQL into statements with byte offsets |
| `insertFile(path, content)` | Add or update a file in the workspace       |
| `removeFile(path)`          | Remove a file from the workspace            |
| `lint(path)`                | Get diagnostics for a file                  |
| `complete(path, offset)`    | Get completions at position                 |
| `hover(path, offset)`       | Get hover info at position                  |
| `setSchema(json)`           | Set database schema                         |
| `clearSchema()`             | Clear the current schema                    |
| `version()`                 | Get library version                         |

### LanguageServer

| Method               | Description                                              |
| -------------------- | -------------------------------------------------------- |
| `handleMessage(msg)` | Process LSP JSON-RPC message, returns array of responses |

### Supported LSP Methods

- `initialize`
- `shutdown`
- `textDocument/didOpen`
- `textDocument/didChange`
- `textDocument/didClose`
- `textDocument/completion`
- `textDocument/hover`
- `pgls/setSchema` (custom notification)

## Building

Requires Emscripten SDK:

```bash
# Build WASM
./crates/pgls_wasm/build-wasm.sh --release

# Build TypeScript
cd packages/@postgres-language-server/wasm
bun run build
```

## License

MIT