Registry / database / zapatos

zapatos

JSON →
library6.6.1jsnpmunverified

Zapatos is a 'zero-abstraction' database library specifically designed for TypeScript and Postgres. It provides strong type safety by generating a detailed TypeScript schema directly from your existing Postgres database, reducing the boilerplate and common pitfalls associated with traditional ORMs. The library facilitates writing arbitrary SQL queries using tagged templates, offers shortcut functions for everyday CRUD operations, and supports complex data structures like nested JSON via LATERAL JOINs, all while maintaining full type inference. Unlike many ORMs, Zapatos does not manage connection pools, explicitly relying on the underlying `pg` module, and does not aim to be database-agnostic or provide a 'code-first' approach. Currently at version 6.6.1, Zapatos maintains an active development status, with a focus on integrating seamlessly with Postgres's native capabilities and TypeScript's type system.

npm install zapatos
INSTALL
IMPORT
SIG · ZAPATOS
Z
zapatos
databasejavascriptv6.6.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

db
import * as db from 'zapatos/db';
const db = require('zapatos/db');
Imports the core database interaction functions (e.g., `select`, `insert`, `update`, `transaction`). Zapatos primarily uses ES Modules.
s
import type * as s from 'zapatos/schema';
import * as s from 'zapatos/schema';
Imports the generated database schema types (e.g., `s.users.Selectable`, `s.products.Insertable`). Use `import type` to avoid runtime module loading issues, especially with tools like ts-jest.
zg
import * as zg from 'zapatos/generate';
const zg = require('zapatos/generate');
Imports functions for programmatic schema generation, an alternative to the CLI. Zapatos primarily uses ES Modules.

This quickstart demonstrates basic Zapatos operations: connecting to a PostgreSQL database via `pg`, inserting a new record, selecting all records, updating a record, and executing operations within a transaction, all using generated TypeScript types for safety.

import pg from 'pg'; import * as db from 'zapatos/db'; import type * as s from 'zapatos/schema'; const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL ?? 'postgres://user:password@localhost:5432/mydb', }); pool.on('error', (err) => console.error('PostgreSQL client error:', err)); async function runExample() { try { // Ensure schema is generated beforehand via `npx zapatos` // or programmatic generation with `zapatos/generate` // Example: Insert a new user const newUser: s.users.Insertable = { name: 'Alice Smith', email: 'alice@example.com' }; const insertedUsers = await db.insert('users', newUser).run(pool); console.log('Inserted user:', insertedUsers[0]); // Example: Select users older than 30 (assuming an 'age' column) // For a real-world example, ensure 'age' exists in your schema. // Here, we'll demonstrate a simple select without 'age' for broader applicability. const allUsers = await db.select('users', db.all).run(pool); console.log('All users:', allUsers); // Example: Update a user's email const updatedUsers = await db.update('users', { email: 'alice.s@example.com' }, { id: db.sql`${insertedUsers[0].id}` }).run(pool); console.log('Updated user:', updatedUsers[0]); // Example: Run a transaction await db.transaction(pool, async (txn) => { const product: s.products.Insertable = { name: 'New Widget', price: 99.99 }; await db.insert('products', product).run(txn); console.log('Product inserted within transaction.'); }); } catch (error) { console.error('Database operation failed:', error); } finally { await pool.end(); } } runExample();
Debug
Known issues
breakingZapatos version 6.3 introduced a warning for 'bigint' or 'numeric' (decimal) columns during schema generation. These types can cause precision issues when parsed as standard JavaScript numbers in JSON.
fix
Set `"customJSONParsingForLargeNumbers": true` in your `zapatosconfig.json` file. This changes the TypeScript types for these columns in `JSONSelectable` to `number | `${number}``.
affects: >=6.3
gotchaWhen importing schema types from `zapatos/schema`, it is critical to use `import type * as s from 'zapatos/schema';` (or similar `import type` syntax). Using a plain `import` can lead to issues with certain build tools and testing frameworks like `ts-jest`.
fix
Always use `import type` for Zapatos schema imports to ensure they are treated purely as type definitions and not bundled at runtime.
affects: >=1.0
gotchaZapatos is a 'zero-abstraction' library and does not manage your PostgreSQL connection pool. It expects you to provide an instance of `pg.Pool` (or `pg.Client`) for all database operations.
fix
Manually set up and manage your `pg.Pool` instance and pass it to Zapatos's `.run()` methods for queries and transactions.
affects: >=1.0
gotchaZapatos is designed exclusively for PostgreSQL and follows a database-first approach. It does not offer multi-database support or a code-first (migrations) ORM-like structure, as its strength lies in direct, type-safe interaction with an existing Postgres schema.
fix
Understand that Zapatos's design is opinionated towards PostgreSQL and an existing database schema. If you require a database-agnostic ORM or code-first migrations, Zapatos may not be the right fit.
affects: >=1.0
Errors
Common errors & fixes
new row for relation "tableName" violates check constraint "tableName_columnName_check"
This error originates from the PostgreSQL database, indicating that an `INSERT` or `UPDATE` statement violated a `CHECK` constraint defined on the table or column.
fix
Review the data being inserted or updated and compare it against the `CHECK` constraints defined in your PostgreSQL schema. Zapatos propagates these database errors directly, ensuring you are aware of underlying data integrity rules.
Property 'someProperty' does not exist on type 's.TableName.Selectable'.
This TypeScript error occurs when trying to access a property (column) on a Zapatos generated type that does not exist in the database table's schema, or if the schema has changed and types haven't been regenerated.
fix
Verify that `someProperty` exists in your PostgreSQL table `TableName`. If the database schema has recently changed, run `npx zapatos` to regenerate your TypeScript schema definitions (`zapatos/schema.d.ts`) to reflect the latest database structure.
Upgrade
Version history
6.6.1latest on npm
Audit
Dependencies
@types/pgrequiredProvides TypeScript definitions for the 'pg' client, which Zapatos uses internally for database interaction.
pgrequiredThe underlying PostgreSQL client library that Zapatos operates on.
typescriptrequiredRequired for compiling Zapatos's generated schema and for general project type-checking.
Agent activity
44 hits · last 30 days
node
36
OpenAI (training)
1
Resources