sql-typechecker

library0.1.0jsnpmunverified

SQL-Typechecker is a CLI tool (v0.1.0) written in TypeScript that parses PostgreSQL DDL and SQL function files, performs type-checking beyond what PostgreSQL natively offers, and generates TypeScript type definitions including branded types. It aims to provide rigorous type-checking for SQL functions and supports nested JSON outputs, branded types (newtypes), and a subset of PostgreSQL syntax. The project is under active development but has been used in production for years. It differentiates from tools like pgtyped by not relying on PostgreSQL’s own type-checker and by generating branded types.

database devops

npm install sql-typechecker

package ↗

INSTALL

IMPORT

SIG · SQL-TYPECHECKER

sql-typechecker

databasejavascriptv0.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CLI usage

✓ npx sql-typechecker --dir ./sql --out ./ts

✗ sql-typechecker --dir ./sql --out ./ts (if not installed globally)

The tool is invoked as a CLI command, not imported as a library.

Generated types (e.g., customer_id)

✓ import { customer_id } from './out/types'; const id: customer_id = 42 as customer_id;

✗ import { customer_id } from 'sql-typechecker';

Types are generated in an output file (e.g., types.ts). They are not exported from the package itself.

Generated function (e.g., my_function)

✓ import { my_function } from './out/out'; const result = await my_function(pool, {});

✗ const { my_function } = require('./out/out');

Generated functions are ESM exports from the output file. Use dynamic import or configure TypeScript for ESM.

TypeScript types for Pool

✓ import { Pool } from 'pg'; const pool = new Pool();

✗ import { Pool } from 'sql-typechecker';

Pool comes from the pg library; sql-typechecker only uses it in generated function signatures.

Shows minimal usage: create a SQL schema file and a function file, run sql-typechecker, and view the generated TypeScript types.

mkdir -p ./sql echo 'CREATE TABLE users ( id int8 NOT NULL PRIMARY KEY, name text );' > ./sql/schema.sql echo 'CREATE FUNCTION get_users() RETURNS SETOF record AS $$ SELECT id, name FROM users $$ LANGUAGE sql;' > ./sql/functions.sql npx sql-typechecker --dir ./sql --out ./sql-generated cat ./sql-generated/out.ts # Output includes: # async function get_users(pool: Pool, args: {}): Promise<{ id: number; name: string | null }[]>

Debug

Known issues

breakingPeer dependency @js-joda/core is required but not automatically installed.

fix

Run 'npm install @js-joda/core' before using sql-typechecker.

affects: >=0.1.0

gotchaThe tool only supports a subset of PostgreSQL syntax; complex functions may fail to parse.

fix

Simplify SQL functions or check the list of supported syntax in the documentation. Avoid plpgsql functions as they are not supported.

affects: >=0.1.0

gotchaGenerated function names may collide with existing exports; output file is overwritten each run.

fix

Use the '--out' flag to specify a separate output directory to avoid conflicts.

affects: >=0.1.0

deprecatedNo official deprecations yet; breaking changes may occur between minor versions before v1.0.

fix

Pin to a specific version in package.json (e.g., "sql-typechecker": "0.1.0").

affects: <1.0.0

Errors

Common errors & fixes

Error: Cannot find module '@js-joda/core'

Missing peer dependency @js-joda/core.

fix

Install the peer dependency: npm install @js-joda/core

Error: Unsupported SQL syntax at line X: ...

The SQL function uses syntax not yet supported by sql-typechecker.

fix

Rewrite the function to use supported constructs (see documentation) or avoid using unsupported features like plpgsql blocks.

Error: Could not find DDL file (schema.sql) in directory ./sql

Missing or misnamed schema file; the tool expects a file (default name schema.sql) or use --dsn flag.

fix

Ensure a SQL DDL file exists in the input directory, or use the '--dsn' flag to specify a connection string for dynamic schema extraction.

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

@js-joda/corerequiredRuntime dependency for date/time type handling (peer dependency, required).

Agent activity

17 hits · last 30 days

node