vlquery

library8.2.0jsnpmunverified

VLQuery is a TypeScript ORM for PostgreSQL with a unique query syntax using lambda expressions that are translated to SQL. Version 8.2.0 is current, with active development. Key differentiators include type-safe queries via TypeScript generics, database-first approach, built-in audit support, and no raw SQL strings. Alternatives like Prisma or TypeORM use different paradigms (schema-first or active record).

database

npm install vlquery

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VLQUERY

vlquery

databasejavascriptv8.2.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.

createDatabase

✓ import { createDatabase } from 'vlquery'

✗ const createDatabase = require('vlquery')

ESM-only; no CommonJS support.

Database

✓ import type { Database } from 'vlquery'

✗ import { Database } from 'vlquery'

Database is a type, not a runtime value. Use import type for TypeScript.

default import

✓ import vlquery from 'vlquery'

✗ import * as vlquery from 'vlquery'

Default export is the main entry point; namespace export may not work.

Connects to PostgreSQL, queries the 'person' table for adults sorted by name, and prints results.

import { createDatabase } from 'vlquery'; async function main() { const db = await createDatabase({ host: process.env.DB_HOST ?? 'localhost', port: parseInt(process.env.DB_PORT ?? '5432'), user: process.env.DB_USER ?? 'postgres', password: process.env.DB_PASSWORD ?? '', database: process.env.DB_NAME ?? 'mydb', }); // Assuming a 'person' table exists with columns: id, name, age const adults = await db.person .where(person => person.age >= 18) .orderByAscending(person => person.name) .toArray(); console.log(adults); } main().catch(console.error);

Debug

Known issues

breakingIn version 7.x, createDatabase returned a promise. In 8.x, it still returns a promise but the internal structure changed.

fix

Update code to handle async database creation if not already.

affects: >=8.0.0

gotchaQuery lambda expressions cannot use external variables; only direct property access and literals work.

fix

Inline all values directly in the lambda, e.g., .where(book => book.title == 'My Title') instead of using a variable.

affects: *

gotchaThe database-first approach expects the schema to exist; VLQuery does not create tables automatically.

fix

Run database migrations separately before using VLQuery.

affects: *

deprecatedThe .first() method without a predicate is deprecated in 8.x; use find() instead.

fix

Replace db.person.first() with db.person.find(id) for primary key lookup.

affects: >=8.0.0

gotchaNested includes (eager loading) are limited; only one level of relationship is supported.

fix

Avoid deep includes; manually query related data if needed.

affects: *

Errors

Common errors & fixes

Error: connect ECONNREFUSED 127.0.0.1:5432

PostgreSQL server not running or wrong connection config.

fix

Ensure PostgreSQL is started and check host/port env variables.

TypeError: db.person.where is not a function

Database not properly initialized; createDatabase promise not awaited.

fix

Ensure you await createDatabase before using db.

The expression could not be translated to SQL. Only simple member access and binary expressions are supported.

Unsupported lambda expression complexity (e.g., calling external functions).

fix

Refactor the lambda to use only property accesses and operators.

Cannot find module 'vlquery' or its corresponding type declarations.

Package not installed or TypeScript not configured to resolve modules.

fix

Run npm install vlquery and ensure tsconfig.json has 'moduleResolution': 'node'.

Upgrade

Version history

8.2.0latest on npm

Audit

Dependencies

pgrequiredPostgreSQL client driver for database connections

Agent activity

16 hits · last 30 days

node