suparisma 0.0.4 → 1.0.1

package/README.md

@@ -1,49 +1,120 @@
 # Suparisma
-
-A React hook generator for Supabase that is driven by your Prisma schema, giving you type-safe, real-time enabled hooks to interact with your Supabase database.
-
-## Why?
-CRUD typesafetey with Supabase should be easy, currently it is not with a lot of issues that can rise easily espeically if you're not using Prisma.
-
-Prisma solved supabase typesafely issue on the server, and TRPC helped making the client even more type safe but realtime capabilites from the DB to the browser was still lacking and that lead to a lot of unnecessary GET, POST requests if you just simply need to have realtime support.
-
-Supabase's rules are also powerful and if you're using TRPC or any server solution you're easily missing out on them.
-
-This package solves all this focusing, it lets you:
-- Create typesafe CRUD hooks for all your supabase tables.
-- Enables you to easily paginate, search and query in each table.
-- Uses Prisma and Supabase official SDKs.
-- Respects Supabase's auth rules enabling an easy way to secure your DB.
-- Works with any React env. like NextJS/Remix/Tanstack Start/Router/etc..
+Supabase + Prisma!
+
+![Suparisma Logo](https://vg-bunny-cdn.b-cdn.net/random/suparisma-banner.png)
+
+A powerful, typesafe React hook generator for Supabase, driven by your Prisma schema. Suparisma provides you with real-time enabled CRUD hooks to interact with your Supabase database without writing any boilerplate code.
+
+[![npm version](https://img.shields.io/npm/v/suparisma.svg?style=flat-square)](https://www.npmjs.com/package/suparisma)
+[![TypeScript](https://img.shields.io/badge/TypeScript-4.9+-blue?style=flat-square)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
+## Table of Contents
+
+- [Why Suparisma?](#why-suparisma)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Detailed Usage](#detailed-usage)
+  - [Basic CRUD Operations](#basic-crud-operations)
+  - [Realtime Updates](#realtime-updates)
+  - [Filtering Data](#filtering-data)
+  - [Sorting Data](#sorting-data)
+  - [Pagination](#pagination)
+  - [Search Functionality](#search-functionality)
+- [Schema Annotations](#schema-annotations)
+- [Building UI Components](#building-ui-components)
+  - [Table with Filtering, Sorting, and Pagination](#table-with-filtering-sorting-and-pagination)
+- [Configuration](#configuration)
+  - [Environment Variables](#environment-variables)
+  - [CLI Commands](#cli-commands)
+- [Advanced Usage](#advanced-usage)
+  - [Custom Hooks](#custom-hooks)
+  - [Error Handling](#error-handling)
+  - [Performance Optimization](#performance-optimization)
+- [API Reference](#api-reference)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Why Suparisma?
+
+I love Supabase and Prisma and use them extensively in my projects, but combining them effectively for frontend development has always been frustrating. The typical solutions involve either setting up tRPC with constant refetching or implementing complex websocket solutions that often feel like overkill.
+
+While Prisma gives me perfect type safety on the server, and Supabase offers great realtime capabilities, bridging these two worlds has remained a pain point. I've struggled to maintain type safety across the stack while efficiently leveraging Supabase's realtime features without resorting to excessive API calls or overly complex architectures.
+
+Suparisma bridges this gap by:
+
+- Creating **typesafe CRUD hooks** for all your Supabase tables
+- Enabling easy **pagination, filtering, and search** on your data
+- Leveraging both **Prisma** and **Supabase** official SDKs
+- Respecting **Supabase's auth rules** for secure database access
+- Working seamlessly with any React environment (Next.js, Remix, Tanstack Router, etc.)
 
 ## Features
 
 - 🚀 **Auto-generated React hooks** based on your Prisma schema
-- 🔄 **Real-time updates by default** for all tables (opt-out available)
+- 🔄 **Real-time updates by default** for all tables (with opt-out capability)
 - 🔒 **Type-safe interfaces** for all database operations
-- 🔍 **Full-text search** capabilities with optional annotations
-- 🔄 **Prisma-like API** that feels familiar if you use Prisma
+- 🔍 **Full-text search** with configurable annotations
+- 🔢 **Pagination and sorting** built into every hook
+- 🧩 **Prisma-like API** that feels familiar if you already use Prisma
+- 📱 **Works with any React framework** including Next.js, Remix, etc.
+- 🛠️ **Simple CLI** to generate hooks with a single command
 
 ## Installation
 
 ```bash
+# Using npm
 npm install suparisma
-# or
+
+# Using yarn
 yarn add suparisma
-# or
+
+# Using pnpm
 pnpm install suparisma
 ```
 
 ## Quick Start
 
-1. **Add a Prisma schema**: Make sure you have a valid `prisma/schema.prisma` file in your project.
+1. **Add a Prisma schema**: Ensure you have a valid `prisma/schema.prisma` file in your project
+
+```prisma
+// This is a sample Prisma schema file
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+// Realtime is enabled by default
+model Thing {
+  id        String   @id @default(uuid())
+  name      String?  // @enableSearch
+  someNumber Int     @default(0)
+  someEnum  String   @default("ONE")
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}
+
+// @disableRealtime - Opt out of realtime for this model
+model AuditLog {
+  id        String   @id @default(uuid())
+  action    String
+  details   String?
+  createdAt DateTime @default(now())
+}
+```
 
 2. **Set up required environment variables** in a `.env` file:
 
 ```
 # Required for Prisma and Supabase
 DATABASE_URL="postgresql://user:password@host:port/database"
-DIRECT_URL="postgresql://user:password@host:port/database"  # Direct Postgres connection
+DIRECT_URL="postgresql://user:password@host:port/database"
 NEXT_PUBLIC_SUPABASE_URL="https://your-project.supabase.co"
 NEXT_PUBLIC_SUPABASE_ANON_KEY="your-anon-key"
 ```
@@ -53,75 +124,475 @@ NEXT_PUBLIC_SUPABASE_ANON_KEY="your-anon-key"
 ```bash
 npx suparisma generate
 ```
-
-This will:
-- Read your Prisma schema from the current directory
-- Configure your database for realtime functionality and search
-- Generate type-safe React hooks in `src/suparisma/generated` (configurable)
+Note: you can adjust the prisma schema path and the generated files output path with these ENV variables:
+```bash
+SUPARISMA_PRISMA_SCHEMA_PATH="./prisma/schema.prisma"
+SUPARISMA_OUTPUT_DIR="./src/suparisma/generated"
+```
+Also make sure to not change any of these generated files directly as **they will always be overwritten**
 
 4. **Use the hooks** in your React components:
 
 ```tsx
 import useSuparisma from './src/suparisma/generated';
 
-function UserList() {
-  const users = useSuparisma.user();
+function ThingList() {
+  const { 
+    data: things,
+    loading,
+    error,
+    create: createThing
+  } = useSuparisma.thing();
   
-  if (users.loading) return <div>Loading...</div>;
-  if (users.error) return <div>Error: {users.error.message}</div>;
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
   
   return (
     <div>
-      <h1>Users</h1>
+      <h1>Things</h1>
       <ul>
-        {users.data?.map(user => (
-          <li key={user.id}>{user.name}</li>
+        {things?.map(thing => (
+          <li key={thing.id}>{thing.name} (Number: {thing.someNumber})</li>
         ))}
       </ul>
       
-      <button onClick={() => users.create({ name: "New User" })}>
-        Add User
+      <button onClick={() => createThing({ 
+        name: "New Thing", 
+        someNumber: Math.floor(Math.random() * 100)
+      })}>
+        Add Thing
       </button>
     </div>
   );
 }
 ```
 
-## Annotations in Your Prisma Schema
+## Detailed Usage
+
+### Basic CRUD Operations
+
+Every generated hook provides a complete set of CRUD operations:
+
+```tsx
+const { 
+  // State
+  data,              // Array of records
+  loading,           // Boolean loading state
+  error,             // Error object if any
+  
+  // Actions
+  create,            // Create a new record
+  update,            // Update existing record(s)
+  delete,            // Delete a record
+  upsert,            // Create or update a record
+  
+  // Helpers
+  count,             // Get count of records (respects where filters)
+  refresh,           // Manually refresh data
+} = useSuparisma.modelName();
+```
+
+#### Creating Records
+
+```tsx
+const { create: createThing } = useSuparisma.thing();
+
+// Create a single record
+await createThing({ name: "Cool Thing", someNumber: 42 });
+
+// Create with nested data if your schema supports it
+await createThing({
+  name: "Cool Thing",
+  someNumber: 42,
+  // If you had relations defined:
+  // tags: {
+  //   create: [
+  //     { name: "Important" },
+  //     { name: "Featured" }
+  //   ]
+  // }
+});
+```
+
+#### Reading Records
+
+```tsx
+// Get all records with default pagination (first 10)
+const { data: things } = useSuparisma.thing();
+
+// With filtering
+const { data: importantThings } = useSuparisma.thing({
+  where: { someEnum: "ONE" }
+});
+
+// With custom pagination
+const { data: recentThings } = useSuparisma.thing({
+  orderBy: { createdAt: "desc" },
+  limit: 5
+});
+```
+
+#### Updating Records
+
+```tsx
+const { update: updateThing } = useSuparisma.thing();
+
+// Update by ID
+await updateThing({ 
+  where: { id: "thing-id-123" },
+  data: { name: "Updated Thing" }
+});
+
+// Update many records matching a filter
+await updateThing({
+  where: { someEnum: "ONE" },
+  data: { someEnum: "TWO" }
+});
+```
+
+#### Deleting Records
+
+```tsx
+const { delete: deleteThing } = useSuparisma.thing();
+
+// Delete by ID
+await deleteThing({ id: "thing-id-123" });
+
+// Delete with more complex filter
+await deleteThing({ someNumber: 0 });
+```
+
+### Realtime Updates
+
+Realtime updates are enabled by default for all models. The `data` will automatically update when changes occur in the database.
+
+```tsx
+// Enable realtime (default)
+const { data: things } = useSuparisma.thing({ realtime: true });
+
+// Disable realtime for this particular hook instance
+const { data: logsNoRealtime } = useSuparisma.auditLog({ realtime: false });
+```
+
+### Filtering Data
+
+Filter data using Prisma-like syntax:
+
+```tsx
+// Basic equality
+const { data } = useSuparisma.thing({ 
+  where: { someEnum: "ONE" } 
+});
+
+// Multiple conditions (AND)
+const { data } = useSuparisma.thing({
+  where: {
+    someEnum: "ONE",
+    someNumber: { gt: 10 }
+  }
+});
+
+// Using operators
+const { data } = useSuparisma.thing({
+  where: {
+    createdAt: { gte: new Date('2023-01-01') },
+    name: { contains: "cool" }
+  }
+});
+```
+
+### Sorting Data
+
+Sort data using Prisma-like ordering:
+
+```tsx
+// Single field sort
+const { data } = useSuparisma.thing({
+  orderBy: { createdAt: "desc" }
+});
+
+// Multiple field sort
+const { data } = useSuparisma.thing({
+  orderBy: [
+    { someEnum: "asc" },
+    { createdAt: "desc" }
+  ]
+});
+```
+
+### Pagination
+
+Suparisma supports offset-based pagination:
+
+```tsx
+// Offset-based pagination (page 1, 10 items per page)
+const { data } = useSuparisma.thing({
+  offset: 0,
+  limit: 10
+});
+
+// Next page
+const { data: page2 } = useSuparisma.thing({
+  offset: 10,
+  limit: 10
+});
+
+// Get total count
+const { data, count } = useSuparisma.thing();
+```
+
+### Search Functionality
+
+For fields annotated with `// @enableSearch`, you can use full-text search:
+
+```tsx
+// Search things by name
+const { data: searchResults } = useSuparisma.thing({
+  search: {
+    query: "cool",
+    fields: ["name"]
+  }
+});
+```
+
+## Schema Annotations
 
-Add annotations directly in your Prisma schema as comments:
+Suparisma uses comments in your Prisma schema to configure behavior:
 
 ```prisma
-// Realtime is enabled by default for this model
-model User {
-  id        String   @id @default(uuid())
-  email     String   @unique
-  name      String?  // @enableSearch
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-}
+// Model level annotations
 
 // @disableRealtime - Opt out of realtime for this model
 model AuditLog {
-  id        String   @id @default(uuid())
-  action    String
-  details   String?
-  createdAt DateTime @default(now())
+  // ...fields
+}
+
+// Field level annotations
+
+model Thing {
+  id        String  @id @default(uuid())
+  name      String? // @enableSearch - Enable full-text search for this field
+  description String? // @enableSearch - Can add to multiple fields
+  someNumber Int
 }
 ```
 
-## Stale Models Cleanup
+Available annotations:
 
-When you delete a model from your Prisma schema and run the generation command, Suparisma automatically:
-- Detects changes to your schema
-- Deletes the entire generated directory
-- Regenerates all hooks and types based on your current schema
+| Annotation | Description | Location |
+|------------|-------------|----------|
+| `@disableRealtime` | Disables real-time updates for this model | Model (before definition) |
+| `@enableSearch` | Enables full-text search on this field | Field (after definition) |
 
-This ensures you don't have stale files lingering around for models that no longer exist in your schema.
+## Building UI Components
 
-## CLI Commands
+### Table with Filtering, Sorting, and Pagination
 
-Suparisma provides a simple CLI with the following commands:
+Here's a complete example of a data table with filtering, sorting, and pagination:
+
+```tsx
+import { useState } from "react";
+import useSuparisma from '../generated';
+
+export default function ThingTable() {
+  const itemsPerPage = 10;
+  const [page, setPage] = useState(0);
+  const [enumFilter, setEnumFilter] = useState("");
+  const [sortField, setSortField] = useState("updatedAt");
+  const [sortDirection, setSortDirection] = useState("desc");
+
+  const { 
+    data: things,
+    loading: isLoading,
+    error,
+    create: createThing,
+    update: updateThing,
+    delete: deleteThing,
+    count: thingCount,
+  } = useSuparisma.thing({
+    realtime: true,
+    limit: itemsPerPage,
+    offset: page * itemsPerPage,
+    where: enumFilter ? {
+      someEnum: enumFilter
+    } : undefined,
+    orderBy: {
+      [sortField]: sortDirection
+    }
+  });
+
+  if(error) {
+    return <div>Error: {error.message}</div>;
+  }
+
+  return (
+    <div className="container mx-auto p-4">
+      <div className="flex justify-between items-center mb-4">
+        <h1 className="text-2xl font-bold">Thing List</h1>
+        <button 
+          onClick={() => createThing({ 
+            name: 'New Thing', 
+            someNumber: Math.floor(Math.random() * 100) 
+          })}
+          className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
+        >
+          Create New Thing
+        </button>
+      </div>
+
+      {/* Filter and Sort Controls */}
+      <div className="mb-4 grid grid-cols-1 md:grid-cols-3 gap-4">
+        <div>
+          <label htmlFor="enumFilter" className="block text-sm font-medium mb-1">
+            Filter by Enum
+          </label>
+          <select
+            value={enumFilter}
+            onChange={(e) => {
+              setEnumFilter(e.target.value);
+              setPage(0); // Reset to first page when filter changes
+            }}
+            className="w-full p-2 border rounded-md"
+          >
+            <option value="">All</option>
+            <option value="ONE">ONE</option>
+            <option value="TWO">TWO</option>
+            <option value="THREE">THREE</option>
+          </select>
+        </div>
+        
+        <div>
+          <label htmlFor="sortField" className="block text-sm font-medium mb-1">
+            Sort By
+          </label>
+          <select
+            value={sortField}
+            onChange={(e) => {
+              setSortField(e.target.value);
+              setPage(0);
+            }}
+            className="w-full p-2 border rounded-md"
+          >
+            <option value="createdAt">Created Date</option>
+            <option value="updatedAt">Updated Date</option>
+            <option value="someNumber">Number</option>
+          </select>
+        </div>
+        
+        <div>
+          <label htmlFor="sortDirection" className="block text-sm font-medium mb-1">
+            Direction
+          </label>
+          <select
+            value={sortDirection}
+            onChange={(e) => {
+              setSortDirection(e.target.value);
+              setPage(0);
+            }}
+            className="w-full p-2 border rounded-md"
+          >
+            <option value="asc">Ascending</option>
+            <option value="desc">Descending</option>
+          </select>
+        </div>
+      </div>
+
+      {/* Data Table */}
+      <div className="overflow-x-auto">
+        <table className="min-w-full bg-white border">
+          <thead>
+            <tr className="bg-gray-100">
+              <th className="py-2 px-4 border-b text-left">Name</th>
+              <th className="py-2 px-4 border-b text-left">Number</th>
+              <th className="py-2 px-4 border-b text-left">Enum</th>
+              <th className="py-2 px-4 border-b text-left">ID</th>
+              <th className="py-2 px-4 border-b text-left">Actions</th>
+            </tr>
+          </thead>
+          <tbody>
+            {isLoading ? (
+              <tr>
+                <td colSpan={5} className="py-4 text-center">Loading...</td>
+              </tr>
+            ) : things?.length === 0 ? (
+              <tr>
+                <td colSpan={5} className="py-4 text-center text-gray-500">
+                  No records found
+                </td>
+              </tr>
+            ) : (
+              things?.map((thing) => (
+                <tr key={thing.id} className="hover:bg-gray-50">
+                  <td className="py-2 px-4 border-b">{thing.name}</td>
+                  <td className="py-2 px-4 border-b">{thing.someNumber}</td>
+                  <td className="py-2 px-4 border-b">{thing.someEnum}</td>
+                  <td className="py-2 px-4 border-b">{thing.id}</td>
+                  <td className="py-2 px-4 border-b">
+                    <button 
+                      onClick={() => updateThing({ 
+                        where: { id: thing.id }, 
+                        data: { name: `Updated ${thing.name}` } 
+                      })}
+                      className="bg-green-500 hover:bg-green-700 text-white py-1 px-2 rounded mr-2 text-sm"
+                    >
+                      Update
+                    </button>
+                    <button 
+                      onClick={() => deleteThing({ id: thing.id })}
+                      className="bg-red-500 hover:bg-red-700 text-white py-1 px-2 rounded text-sm"
+                    >
+                      Delete
+                    </button>
+                  </td>
+                </tr>
+              ))
+            )}
+          </tbody>
+        </table>
+      </div>
+
+      {/* Pagination Controls */}
+      <div className="mt-4 flex justify-center items-center">
+        <button
+          onClick={() => setPage(prev => Math.max(0, prev - 1))}
+          disabled={page === 0}
+          className="bg-gray-300 hover:bg-gray-400 text-gray-800 py-2 px-4 rounded-l disabled:opacity-50"
+        >
+          Previous
+        </button>
+        <span className="py-2 px-4">
+          Page {page + 1}
+          {thingCount && ` of ${Math.ceil(Number(thingCount) / itemsPerPage)}`}
+        </span>
+        <button
+          onClick={() => setPage(prev => prev + 1)}
+          disabled={!things || things.length < itemsPerPage}
+          className="bg-gray-300 hover:bg-gray-400 text-gray-800 py-2 px-4 rounded-r disabled:opacity-50"
+        >
+          Next
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description | Example |
+|----------|----------|-------------|---------|
+| `DATABASE_URL` | Yes | Postgres database URL used by Prisma | `postgresql://user:pass@host:port/db` |
+| `DIRECT_URL` | Yes | Direct URL to Postgres DB for realtime setup | `postgresql://user:pass@host:port/db` |
+| `NEXT_PUBLIC_SUPABASE_URL` | Yes | Your Supabase project URL | `https://xyz.supabase.co` |
+| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Yes | Supabase anonymous key | `eyJh...` |
+| `SUPARISMA_OUTPUT_DIR` | No | Custom output directory | `src/lib/suparisma` |
+| `SUPARISMA_PRISMA_SCHEMA_PATH` | No | Custom schema path | `db/schema.prisma` |
+
+### CLI Commands
+
+Suparisma provides a simple command-line interface:
 
 ```bash
 # Generate hooks based on your Prisma schema
@@ -131,26 +602,191 @@ npx suparisma generate
 npx suparisma help
 ```
 
-## Configuration
+## Stale Models Cleanup
+
+When you delete a model from your Prisma schema and run the generation command, Suparisma automatically:
+- Detects changes to your schema
+- Deletes the entire generated directory
+- Regenerates all hooks and types based on your current schema
+
+This ensures you never have stale files lingering around for models that no longer exist in your schema.
+
+## Advanced Usage
 
-You can customize the behavior using environment variables:
+### Custom Hooks
 
+You can combine Suparisma hooks with your own custom hooks for advanced use cases:
+
+```tsx
+import { useState } from 'react';
+import useSuparisma from '../generated';
+
+// Custom hook for managing important things
+function useImportantThings() {
+  const [category, setCategory] = useState<string>("ONE");
+  
+  const {
+    data: things,
+    loading,
+    error,
+    create: createThing,
+    update: updateThing,
+  } = useSuparisma.thing({
+    where: { someEnum: category },
+    orderBy: { someNumber: "desc" }
+  });
+
+  const addThing = (name: string, number: number) => {
+    return createThing({
+      name,
+      someNumber: number,
+      someEnum: category
+    });
+  };
+  
+  const changeCategory = (newCategory: string) => {
+    setCategory(newCategory);
+  };
+  
+  return {
+    things,
+    loading,
+    error,
+    addThing,
+    updateThing,
+    currentCategory: category,
+    changeCategory
+  };
+}
+```
+
+### Error Handling
+
+Handle errors gracefully with try/catch blocks:
+
+```tsx
+const { create, error } = useSuparisma.thing();
+
+async function handleSubmit(event) {
+  event.preventDefault();
+  try {
+    const result = await create({
+      name: formData.name,
+      someNumber: parseInt(formData.number)
+    });
+    console.log('Created!', result);
+  } catch (err) {
+    console.error('Failed to create thing:', err);
+  }
+}
+```
+
+### Performance Optimization
+
+Optimize performance by:
+
+1. Disabling realtime when not needed
+2. Using pagination to limit data size
+3. Using precise filter conditions
+
+```tsx
+// Only get what you need
+const { data } = useSuparisma.thing({
+  realtime: false, // Disable realtime if not needed
+  where: { someEnum: "ONE" }, // Only get specific items
+  select: { id: true, name: true, someNumber: true }, // Only select needed fields
+  limit: 10 // Limit results
+});
 ```
-# Optional: Customize output directory
-SUPARISMA_OUTPUT_DIR="src/hooks/generated"
 
-# Optional: Specify custom schema path 
-SUPARISMA_PRISMA_SCHEMA_PATH="path/to/schema.prisma"
+## API Reference
+
+### Hook Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `where` | `object` | Filter conditions for the query |
+| `orderBy` | `object \| array` | Sorting options |
+| `limit` | `number` | Maximum number of records to return |
+| `offset` | `number` | Number of records to skip for pagination |
+| `realtime` | `boolean` | Enable/disable real-time updates |
+| `select` | `object` | Fields to include in the response |
+| `include` | `object` | Related records to include |
+| `search` | `object` | Full-text search configuration |
+
+### Hook Return Value
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `data` | `array` | Array of records matching the query |
+| `loading` | `boolean` | Loading state |
+| `error` | `Error \| null` | Error object if request failed |
+| `create` | `function` | Create a new record |
+| `update` | `function` | Update existing record(s) |
+| `delete` | `function` | Delete a record |
+| `upsert` | `function` | Create or update a record |
+| `count` | `function` | Get count of records |
+| `refresh` | `function` | Manually refresh data |
+
+## Troubleshooting
+
+### Common Issues
+
+**Realtime not working**
+- First, make sure you have ran npx suparisma generate as that will automatically add all your tables to the realtime supabase publication.
+- Second, Make sure to have realtime: true in the hook usage and also in supabase go to tables > publications > supabase_realtime and there you must find the tables you created in prisma in there or the realtime is not working properly.
+
+**No permissions/this table doesn't exist**
+- If you ever run into such issue make sure the **anon** has suffiecient permissions to access your tables, this issue especially is common when you do prisma migrate.
+```sql
+-- Replace YOUR_TABLE_NAME with the actual table names affected by your migration
+
+-- Grant usage on the schema to anon
+GRANT USAGE ON SCHEMA public TO anon;
+
+-- Grant SELECT, INSERT, UPDATE, DELETE on tables to anon
+GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO anon;
+
+-- Ensure future tables also grant these permissions
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO anon;
+
+-- Grant usage on sequences to anon (if using auto-increment IDs)
+GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO anon;
+
+-- Ensure future sequences also grant usage to anon
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+GRANT USAGE, SELECT ON SEQUENCES TO anon;
 ```
 
-## Environment Variables
+**"Unknown command: undefined"**
+
+This happens when running the CLI without specifying a command. Use `npx suparisma generate` instead.
+
+**"DIRECT_URL environment variable not found"**
+
+You need to provide a direct PostgreSQL connection URL in your `.env` file for realtime functionality.
+
+**"Table X was already in supabase_realtime publication"**
+
+This is just an informational message, not an error. Your table is already configured for realtime updates.
+
+**Hook data doesn't update in real-time**
+
+Check:
+1. The model doesn't have `@disableRealtime` annotation
+2. The hook is called with `realtime: true` (default)
+3. Your Supabase project has realtime enabled in the dashboard
+
+## Contributing
 
-The following environment variables are required:
+Contributions are welcome! Please feel free to submit a Pull Request.
 
-- `DATABASE_URL` - Your Postgres database URL (used by Prisma)
-- `DIRECT_URL` - Direct URL to your Postgres database (for setting up realtime)
-- `NEXT_PUBLIC_SUPABASE_URL` - Your Supabase project URL
-- `NEXT_PUBLIC_SUPABASE_ANON_KEY` - Your Supabase anonymous key
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 
 ## License
 

package/dist/generators/coreGenerator.js

@@ -155,6 +155,37 @@ export type SearchState = {
   clearQueries: () => void;
 };
 
+/**
+ * Compare two values for sorting with proper type handling
+ */
+function compareValues(a: any, b: any, direction: 'asc' | 'desc'): number {
+  // Handle undefined/null values
+  if (a === undefined || a === null) return direction === 'asc' ? -1 : 1;
+  if (b === undefined || b === null) return direction === 'asc' ? 1 : -1;
+  
+  // Handle numbers properly to ensure numeric comparison
+  if (typeof a === 'number' && typeof b === 'number') {
+    return direction === 'asc' 
+      ? a - b
+      : b - a;
+  }
+  
+  // Handle dates (convert to timestamps for comparison)
+  if (a instanceof Date && b instanceof Date) {
+    return direction === 'asc' 
+      ? a.getTime() - b.getTime()
+      : b.getTime() - a.getTime();
+  }
+  
+  // Handle strings or mixed types with string conversion
+  const aStr = String(a);
+  const bStr = String(b);
+  
+  return direction === 'asc'
+    ? aStr.localeCompare(bStr)
+    : bStr.localeCompare(aStr);
+}
+
 /**
  * Convert a type-safe where filter to Supabase filter string
  */
@@ -316,11 +347,17 @@ export function applyOrderBy<T>(
   
   // Apply each order by clause
   let orderedQuery = query;
-  for (const [key, direction] of Object.entries(orderBy)) {
-    // @ts-ignore: Supabase typing issue
-    orderedQuery = orderedQuery.order(key, {
-      ascending: direction === 'asc'
-    });
+  
+  // Handle orderBy as array or single object
+  const orderByArray = Array.isArray(orderBy) ? orderBy : [orderBy];
+  
+  for (const orderByClause of orderByArray) {
+    for (const [key, direction] of Object.entries(orderByClause)) {
+      // @ts-ignore: Supabase typing issue
+      orderedQuery = orderedQuery.order(key, {
+        ascending: direction === 'asc'
+      });
+    }
   }
   
   return orderedQuery;
@@ -387,9 +424,29 @@ export function createSuparismaHook<
       offset,
     } = options;
     
-    // Compute the actual filter string from the type-safe where object or use legacy filter
-    const computedFilter = where ? buildFilterString(where) : realtimeFilter;
-    
+    // Refs to store the latest options for realtime handlers
+    const whereRef = useRef(where);
+    const orderByRef = useRef(orderBy);
+    const limitRef = useRef(limit);
+    const offsetRef = useRef(offset);
+
+    // Update refs whenever options change
+    useEffect(() => {
+      whereRef.current = where;
+    }, [where]);
+
+    useEffect(() => {
+      orderByRef.current = orderBy;
+    }, [orderBy]);
+
+    useEffect(() => {
+      limitRef.current = limit;
+    }, [limit]);
+
+    useEffect(() => {
+      offsetRef.current = offset;
+    }, [offset]);
+
     // Single data collection for holding results
     const [data, setData] = useState<TWithRelations[]>([]);
     const [error, setError] = useState<Error | null>(null);
@@ -680,7 +737,7 @@ export function createSuparismaHook<
         }
         
         // Apply offset if provided (for pagination)
-        if (params?.skip) {
+        if (params?.skip !== undefined && params.skip >= 0) {
           query = query.range(params.skip, params.skip + (params.take || 10) - 1);
         }
         
@@ -773,14 +830,11 @@ export function createSuparismaHook<
       
       const channelId = channelName || \`changes_to_\${tableName}_\${Math.random().toString(36).substring(2, 15)}\`;
       
-      // Store the current filter and options for closure
-      const currentFilter = computedFilter;
-      const currentWhere = where;
-      const currentOrderBy = orderBy;
-      const currentLimit = limit;
-      const currentOffset = offset;
-      
-      console.log(\`Setting up subscription for \${tableName} with filter: \${currentFilter}\`);
+      // Use a dynamic filter string builder inside the event handler or rely on Supabase
+      // For the subscription filter, we must use the initial computedFilter or a stable one.
+      // However, for client-side logic (sorting, adding/removing from list), we use refs.
+      const initialComputedFilter = where ? buildFilterString(where) : realtimeFilter;
+      console.log(\`Setting up subscription for \${tableName} with initial filter: \${initialComputedFilter}\`);
       
       const channel = supabase
         .channel(channelId)
@@ -790,11 +844,17 @@ export function createSuparismaHook<
             event: '*',
             schema: 'public',
             table: tableName,
-            filter: currentFilter,
+            filter: initialComputedFilter, // Subscription filter uses initial state
           },
           (payload) => {
             console.log(\`Received \${payload.eventType} event for \${tableName}\`, payload);
             
+            // Access current options via refs inside the event handler
+            const currentWhere = whereRef.current;
+            const currentOrderBy = orderByRef.current;
+            const currentLimit = limitRef.current;
+            const currentOffset = offsetRef.current; // Not directly used in handlers but good for consistency
+
             // Skip realtime updates when search is active
             if (isSearchingRef.current) return;
             
@@ -806,7 +866,7 @@ export function createSuparismaHook<
                   console.log(\`Processing INSERT for \${tableName}\`, { newRecord });
                   
                   // Check if this record matches our filter if we have one
-                  if (currentWhere) {
+                  if (currentWhere) { // Use ref value
                     let matchesFilter = true;
                     
                     // Check each filter condition
@@ -838,27 +898,43 @@ export function createSuparismaHook<
                   }
                   
                   // Add the new record to the data
-                  let newData = [newRecord, ...prev];
+                  let newData = [...prev, newRecord]; // Changed: Use spread on prev for immutability
                   
                   // Apply ordering if specified
-                  if (currentOrderBy) {
-                    const [orderField, direction] = Object.entries(currentOrderBy)[0] || [];
-                    if (orderField) {
-                      newData = [...newData].sort((a, b) => {
-                        const aValue = a[orderField as keyof typeof a] ?? '';
-                        const bValue = b[orderField as keyof typeof b] ?? '';
-                        
-                        if (direction === 'asc') {
-                          return aValue < bValue ? -1 : aValue > bValue ? 1 : 0;
-                        } else {
-                          return aValue > bValue ? -1 : aValue < bValue ? 1 : 0;
+                  if (currentOrderBy) { // Use ref value
+                    // Convert orderBy to array format for consistency if it's an object
+                    const orderByArray = Array.isArray(currentOrderBy) 
+                      ? currentOrderBy 
+                      : [currentOrderBy];
+                      
+                    // Apply each sort in sequence
+                    newData = [...newData].sort((a, b) => {
+                      // Check each orderBy clause in sequence
+                      for (const orderByClause of orderByArray) {
+                        for (const [field, direction] of Object.entries(orderByClause)) {
+                          const aValue = a[field as keyof typeof a];
+                          const bValue = b[field as keyof typeof b];
+                          
+                          // Skip if values are equal and move to next criterion
+                          if (aValue === bValue) continue;
+                          
+                          // Use the compareValues function for proper type handling
+                          return compareValues(aValue, bValue, direction as 'asc' | 'desc');
                         }
-                      });
-                    }
+                      }
+                      return 0; // Equal if all criteria match
+                    });
+                  } else if (hasCreatedAt) {
+                    // Default sort by createdAt desc if no explicit sort but has timestamp
+                    newData = [...newData].sort((a, b) => {
+                      const aValue = a[createdAtField as keyof typeof a];
+                      const bValue = b[createdAtField as keyof typeof b];
+                      return compareValues(aValue, bValue, 'desc');
+                    });
                   }
                   
                   // Apply limit if specified
-                  if (currentLimit && currentLimit > 0) {
+                  if (currentLimit && currentLimit > 0) { // Use ref value
                     newData = newData.slice(0, currentLimit);
                   }
                   
@@ -874,6 +950,10 @@ export function createSuparismaHook<
             } else if (payload.eventType === 'UPDATE') {
               // Process update event 
               setData((prev) => {
+                // Access current options via refs
+                const currentOrderBy = orderByRef.current; 
+                const currentLimit = limitRef.current; // If needed for re-fetch logic on update
+
                 // Skip if search is active
                 if (isSearchingRef.current) {
                   return prev;
@@ -886,15 +966,57 @@ export function createSuparismaHook<
                     : item
                 );
                 
+                // Apply ordering again after update to ensure consistency
+                let sortedData = [...newData];
+                
+                // Apply ordering if specified
+                if (currentOrderBy) { // Use ref value
+                  // Convert orderBy to array format for consistency if it's an object
+                  const orderByArray = Array.isArray(currentOrderBy) 
+                    ? currentOrderBy 
+                    : [currentOrderBy];
+                    
+                  // Apply each sort in sequence
+                  sortedData = sortedData.sort((a, b) => {
+                    // Check each orderBy clause in sequence
+                    for (const orderByClause of orderByArray) {
+                      for (const [field, direction] of Object.entries(orderByClause)) {
+                        const aValue = a[field as keyof typeof a];
+                        const bValue = b[field as keyof typeof b];
+                        
+                        // Skip if values are equal and move to next criterion
+                        if (aValue === bValue) continue;
+                        
+                        // Use the compareValues function for proper type handling
+                        return compareValues(aValue, bValue, direction as 'asc' | 'desc');
+                      }
+                    }
+                    return 0; // Equal if all criteria match
+                  });
+                } else if (hasCreatedAt) {
+                  // Default sort by createdAt desc if no explicit sort but has timestamp
+                  sortedData = sortedData.sort((a, b) => {
+                    const aValue = a[createdAtField as keyof typeof a];
+                    const bValue = b[createdAtField as keyof typeof b];
+                    return compareValues(aValue, bValue, 'desc');
+                  });
+                }
+                
                 // Fetch the updated count after the data changes
                 // For updates, the count might not change but we fetch anyway to be consistent
                 setTimeout(() => fetchTotalCount(), 0);
                 
-                return newData;
+                return sortedData;
               });
             } else if (payload.eventType === 'DELETE') {
               // Process delete event
               setData((prev) => {
+                // Access current options via refs
+                const currentWhere = whereRef.current;
+                const currentOrderBy = orderByRef.current;
+                const currentLimit = limitRef.current;
+                const currentOffset = offsetRef.current;
+
                 // Skip if search is active
                 if (isSearchingRef.current) {
                   return prev;
@@ -913,21 +1035,61 @@ export function createSuparismaHook<
                 setTimeout(() => fetchTotalCount(), 0);
                 
                 // If we need to maintain the size with a limit
-                if (currentLimit && currentLimit > 0 && filteredData.length < currentSize && currentSize === currentLimit) {
+                if (currentLimit && currentLimit > 0 && filteredData.length < currentSize && currentSize === currentLimit) { // Use ref value
                   console.log(\`Record deleted with limit \${currentLimit}, will fetch additional record to maintain size\`);
                   
                   // Use setTimeout to ensure this state update completes first
                   setTimeout(() => {
                     findMany({
-                      where: currentWhere,
-                      orderBy: currentOrderBy,
-                      take: currentLimit,
-                      skip: currentOffset
+                      where: currentWhere, // Use ref value
+                      orderBy: currentOrderBy, // Use ref value
+                      take: currentLimit, // Use ref value
+                      skip: currentOffset // Use ref value (passed as skip to findMany)
                     });
                   }, 0);
+                  
+                  // Return the filtered data without resizing for now
+                  // The findMany call above will update the data later
+                  return filteredData;
+                }
+                
+                // Re-apply ordering to maintain consistency
+                let sortedData = [...filteredData];
+                
+                // Apply ordering if specified
+                if (currentOrderBy) { // Use ref value
+                  // Convert orderBy to array format for consistency if it's an object
+                  const orderByArray = Array.isArray(currentOrderBy) 
+                    ? currentOrderBy 
+                    : [currentOrderBy];
+                    
+                  // Apply each sort in sequence
+                  sortedData = sortedData.sort((a, b) => {
+                    // Check each orderBy clause in sequence
+                    for (const orderByClause of orderByArray) {
+                      for (const [field, direction] of Object.entries(orderByClause)) {
+                        const aValue = a[field as keyof typeof a];
+                        const bValue = b[field as keyof typeof b];
+                        
+                        // Skip if values are equal and move to next criterion
+                        if (aValue === bValue) continue;
+                        
+                        // Use the compareValues function for proper type handling
+                        return compareValues(aValue, bValue, direction as 'asc' | 'desc');
+                      }
+                    }
+                    return 0; // Equal if all criteria match
+                  });
+                } else if (hasCreatedAt) {
+                  // Default sort by createdAt desc if no explicit sort but has timestamp
+                  sortedData = sortedData.sort((a, b) => {
+                    const aValue = a[createdAtField as keyof typeof a];
+                    const bValue = b[createdAtField as keyof typeof b];
+                    return compareValues(aValue, bValue, 'desc');
+                  });
                 }
                 
-                return filteredData;
+                return sortedData;
               });
             }
           }
@@ -942,7 +1104,7 @@ export function createSuparismaHook<
       return () => {
         console.log(\`Unsubscribing from \${channelId}\`);
         if (channelRef.current) {
-          channelRef.current.unsubscribe();
+          supabase.removeChannel(channelRef.current); // Correct way to remove channel
           channelRef.current = null;
         }
         
@@ -951,7 +1113,7 @@ export function createSuparismaHook<
           searchTimeoutRef.current = null;
         }
       };
-    }, [realtime, channelName, computedFilter]);
+    }, [realtime, channelName, tableName, initialLoadRef]); // Removed where, orderBy, limit, offset from deps
 
     // Create a memoized options object to prevent unnecessary re-renders
     const optionsRef = useRef({ where, orderBy, limit, offset });

package/package.json

@@ -1,8 +1,12 @@
 {
 	"name": "suparisma",
-	"version": "0.0.4",
+	"version": "1.0.1",
 	"description": "Opinionated typesafe React realtime CRUD hooks generator for all your Supabase tables, powered by Prisma.",
 	"main": "dist/index.js",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Moe03/suparisma"
+	},
 	"scripts": {
 		"build": "tsc",
 		"start": "node dist/index.js",