PGRestify

📖 Complete Documentation | Getting Started | API Reference

The definitive TypeScript client library for PostgREST APIs. Choose between PostgREST's native syntax or a complete ORM-style approach with repositories and query builders. No API keys required, PostgreSQL role-based security, and enterprise-grade features with zero-config setup.

✨ Key Features

🎯 Zero Configuration - No API keys required! Just provide your PostgREST URL
🏗️ Dual Query Syntax - Choose PostgREST syntax OR ORM-style repositories
🚀 ORM-Style Methods - Familiar find(), save(), createQueryBuilder() methods
🔐 PostgreSQL Roles - Built-in role-based security with dynamic switching
⚡ Real-time & Caching - WebSocket subscriptions and intelligent caching
🔗 Framework Ready - React hooks, Next.js adapter, query library support
🔒 Full Type Safety - Complete TypeScript support with schema inference
📦 Lightweight - Core library < 15KB gzipped

📦 Installation

npm install @webcoded/pgrestify
# or
yarn add @webcoded/pgrestify
# or
pnpm add @webcoded/pgrestify

🚀 Quick Start

import { createClient } from '@webcoded/pgrestify';

// 1. Create client (zero config!)
const client = createClient({
  url: 'http://localhost:3000'
});

// 2. Define your types
interface User {
  id: number;
  name: string;
  email: string;
  active: boolean;
}

// 3. Choose your style:

// 🎯 PostgREST Syntax
const users = await client
  .from<User>('users')
  .select('*')
  .eq('active', true)
  .execute();

// 🏗️ Repository Pattern
const userRepo = client.getRepository<User>('users');
const activeUsers = await userRepo.find({ where: { active: true } });
const user = await userRepo.findOne({ id: 1 });

// Save data
await userRepo.save({
  name: 'John Doe',
  email: 'john@example.com',
  active: true
});

// 🚀 Query Builder
const users = await userRepo
  .createQueryBuilder()
  .where('active = :active', { active: true })
  .orderBy('created_at', 'DESC')
  .getMany();

🎯 Framework Integrations

React Hooks

import { useQuery, useMutation } from '@webcoded/pgrestify/react';

function UserList() {
  const { data: users, loading } = useQuery('users', 
    query => query.select('*').eq('active', true)
  );
  
  return <div>{users?.map(user => <div key={user.id}>{user.name}</div>)}</div>;
}

Next.js

// App Router
import { createServerClient } from '@webcoded/pgrestify/nextjs';

export default async function Page() {
  const client = createServerClient();
  const users = await client.from('users').find();
  return <div>{/* render users */}</div>;
}

Query Libraries

import { useQuery } from '@tanstack/react-query';

function useUsers() {
  return useQuery({
    queryKey: ['users'],
    queryFn: () => client.from('users').find()
  });
}

🔥 Advanced Features

// Real-time subscriptions
await client.realtime.connect();
client.realtime.from('users').onInsert(payload => {
  console.log('New user:', payload.new);
});

// Authentication with auto-refresh
const { data } = await client.auth.signIn({
  email: 'user@example.com',
  password: 'password123'
});

// Smart caching with TTL
const client = createClient({
  url: 'http://localhost:3000',
  cache: { enabled: true, ttl: 300000 }
});

// PostgreSQL role switching
await client.switchRole('admin');
const adminData = await client.from('users').find();

📖 View Complete Documentation for detailed guides on:

📖 Documentation

📖 Complete Documentation

Quick Links

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

# Clone the repository
git clone https://github.com/pgrestify/pgrestify.git

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build the library
pnpm build

📄 License

🙏 Acknowledgments

PostgREST - The amazing REST API for PostgreSQL
Popular ORM libraries - Inspiration for the repository pattern
Modern query libraries - Caching strategy inspiration

⭐ Star us on GitHub • 📖 Complete Documentation

Built with ❤️ for the PostgreSQL and TypeScript communities