pgeon

library0.0.6jsnpmunverified

A zero-dependency, type-safe Postgres client for Node.js (v0.0.6). It includes a from-scratch implementation of the Postgres protocol with connection pooling, query cancellation, and SQL injection prevention via prepared statements. Its standout feature is a webpack loader that type-checks static SQL queries at compile time using TypeScript template literal types, catching errors before runtime. Designed for strict one-to-one mapping between Postgres and JavaScript types. Released as an experimental alpha with monthly updates.

database

npm install pgeon

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PGEON

pgeon

databasejavascriptv0.0.6

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.

newPool

✓ import { newPool } from 'pgeon'

✗ const { newPool } = require('pgeon')

ESM only; CommonJS require may not work because the package is ESM-first.

sql

✓ import { sql } from 'pgeon'

✗ import sql from 'pgeon'

sql is a named export, not default. It is a template literal tag used for static query type-checking.

PoolOptions

✓ import type { PoolOptions } from 'pgeon'

✗ import { PoolOptions } from 'pgeon'

Used for TypeScript types only; should be imported with 'import type' in type-strict projects.

Shows connecting to a Postgres database using a connection pool and executing a static query with type safety via the sql template literal tag.

import { newPool, sql } from 'pgeon' const db = newPool({ host: process.env.PGHOST ?? 'localhost', port: Number(process.env.PGPORT) || 5432, username: process.env.PGUSER ?? 'postgres', password: process.env.PGPASSWORD ?? '', minConnections: 1, maxConnections: 10 }) async function main() { const result = await db.run(sql`SELECT 1 AS num`) console.log(result.rows) // [{ num: 1 }] await db.close() } main().catch(console.error)

Debug

Known issues

gotchaThe sql tag must not be aliased or renamed, and no other template literal tag named sql should exist in the codebase.

fix

Always import sql from pgeon and use it directly without renaming.

affects: >=0.0.1

breakingThe webpack loader must be placed after the TypeScript loader in the rules array.

fix

Order loaders as: ['ts-loader', 'pgeon/webpack-loader.ts'] in the use array.

affects: >=0.0.1

deprecatedThe package is in early alpha (0.0.x). Breaking changes may occur without major version bumps.

fix

Pin to exact version and expect API changes.

affects: <1.0.0

gotchaDynamic queries do not get compile-time type checking; only static sql tagged queries are checked.

fix

Use sql tag for all queries that have static structure, and manually type dynamic queries.

affects: >=0.0.1

gotchaThe library requires Node >=14.0.0 and is ESM-only. CommonJS require may fail.

fix

Use ESM imports (import) and set type: 'module' in package.json.

affects: >=0.0.1

Errors

Common errors & fixes

Error: Cannot find module 'pgeon'

Package not installed or missing from node_modules.

fix

Run npm install pgeon

TypeError: db.run is not a function

The pool was not properly created or db is not a Pool object.

fix

Ensure db = newPool() and that newPool is imported correctly.

Webpack: ModuleParseError: Unexpected token (1:8)

The webpack loader for .ts files is not set up correctly; ts-loader may be missing or misconfigured.

fix

Add ts-loader and ensure rules array includes ts-loader before pgeon's webpack-loader.

Upgrade

Version history

0.0.6latest on npm

Audit

Dependencies

webpackoptionalRequired for the compile-time SQL type-checking loader.

ts-nodeoptionalNeeded to write webpack config in TypeScript and reference TypeScript loaders.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/inad9300/pgeon ↗

packagepgeon ↗

homepagehttps://github.com/inad9300/pgeon ↗