gem-hunter

Installation

npm install zodgres

Quick Start

import { connect, z } from 'zodgres';

// Set-up database connection
const db = connect('postgres://user:password@localhost:5432/mydb');

// Define a collection with Zod schema
const users = db.collection('users', {
  id: z.number().optional(), // auto-incrementing
  name: z.string().max(100),
  age: z.number().min(0).max(100).optional(),
});

// Open the connection and run collection migrations
await db.open();

// Create records
const user = await users.create({ name: 'John Doe', age: 30 });
// Result: { id: 1, name: 'John Doe', age: 30 }

// Create multiple records
const newUsers = await users.create([
  { name: 'Alice' },
  { name: 'Bob', age: 25 }
]);
// Result: [{ id: 2, name: 'Alice' }, { id: 3, name: 'Bob', age: 25 }]

// Query records
const allUsers = await users.select(); // or users.select`*`
const adults = await users.select`* WHERE age >= ${18}`;

// Close connection
await db.close();

API Overview

Database Connection

connect(uri, options?)

// Connect to Postgres
const db = connect('postgres://user:password@localhost:5432/mydb');

// Use in-memory database (great for testing)
const testDb = connect(':memory:');

Collection Definition

db.collection(name, schema, params?)

const items = db.collection('items', {
  id: z.number().optional(),          // auto-incrementing primary key
  name: z.string().max(100),          // required string with max length
  price: z.number().positive(),       // required positive number
  description: z.string().optional(), // optional string
});

Collection Operations

create(data) / create(data[])

// Single record
const item = await items.create({
  name: 'Widget',
  price: 19.99
});

// Multiple records
const newItems = await items.create([
  { name: 'Gadget', price: 29.99 },
  { name: 'Tool', price: 39.99, description: 'Useful tool' }
]);

select() / select``query `

// Select all records
const all = await items.select();

// Select with conditions
const expensive = await items.select`* WHERE price > ${25}`;
const byName = await items.select`* WHERE name = ${'Widget'}`;

// Complex queries
const recent = await items.select`
  name, price
  WHERE created_at > ${new Date('2024-01-01')}
  ORDER BY price DESC
  LIMIT ${10}
`;

Testing

import { connect, z } from 'zodgres';

describe('My tests', () => {
  let db;

  before(async () => {
    db = await connect(':memory:').open(); // Uses PGLite
  });

  after(async () => {
    await db.close();
  });

  it('should create users', async () => {
    const users = db.collection('users', {
      id: z.number().optional(),
      name: z.string(),
    });

    const user = await users.create({ name: 'Test User' });
    assert.deepStrictEqual(user, { id: 1, name: 'Test User' });
  });
});

Schema Validation

const products = db.collection('products', {
  id: z.number().optional(),
  name: z.string().min(1).max(100),
  price: z.number().positive(),
  category: z.enum(['electronics', 'books', 'clothing']),
  tags: z.array(z.string()).optional(),
  metadata: z.record(z.any()).optional(),
});

// This will throw validation error
await products.create({
  name: '', // too short
  price: -10, // not positive
  category: 'invalid' // not in enum
});

License