supabase-typed-query

npm install supabase-typed-query functype
# or
pnpm add supabase-typed-query functype
# or
yarn add supabase-typed-query functype

npx supabase gen types typescript --project-id your-project-id > database.types.ts

import { createClient } from "@supabase/supabase-js"
import type { Database } from "./database.types"

const supabase = createClient<Database>("your-supabase-url", "your-anon-key")

import { query } from "supabase-typed-query"

// Simple query
const user = await query(supabase, "users", { id: "123" }).one()

// Query with OR conditions
const posts = await query(supabase, "posts", { status: "published" }).or({ status: "draft", author_id: userId }).many()

// Query with functional operations
const titles = await query(supabase, "posts", { status: "published" })
  .map((post) => post.title)
  .filter((title) => title.length > 10)
  .many()

import { Entity } from "supabase-typed-query"

// Create an entity for your table with configuration
const PostEntity = Entity(supabase, "posts", {
  softDelete: true, // Automatically exclude soft-deleted items
})

// Get all posts
const posts = await PostEntity.getItems({
  where: { status: "published" },
  order: ["created_at", { ascending: false }],
}).many()

// Get a single post
const post = await PostEntity.getItem({
  id: "post-123",
  where: { status: "published" },
}).one()

// Add posts
const newPosts = await PostEntity.addItems({
  items: [{ title: "New Post", content: "Content here", status: "draft" }],
}).execute()

// Update a post
const updated = await PostEntity.updateItem({
  id: "post-123",
  item: { status: "published" },
}).execute()

// Greater than / Less than
const recentPosts = await query(supabase, "posts", {
  created_at: { gte: new Date("2024-01-01") },
}).many()

// Pattern matching
const searchResults = await query(supabase, "posts", {
  title: { ilike: "%typescript%" },
}).many()

// IN queries
const selectedPosts = await query(supabase, "posts", {
  id: { in: ["id1", "id2", "id3"] },
}).many()

// IS NULL checks
const drafts = await query(supabase, "posts", {
  published_at: { is: null },
}).many()

// IS NOT NULL checks (using NOT operator)
const publishedPosts = await query(supabase, "posts", {
  not: { is: { published_at: null } },
}).many()

// NOT IN queries
const activePosts = await query(supabase, "posts", {
  not: { in: { status: ["draft", "archived"] } },
}).many()

// IS NOT NULL - find posts with external_id set
const linkedPosts = await PostEntity.getItems({
  not: { is: { external_id: null } },
}).many()

// IS NOT TRUE / IS NOT FALSE
const nonFeatured = await PostEntity.getItems({
  not: { is: { featured: true } },
}).many()

// NOT IN - exclude specific statuses
const visiblePosts = await PostEntity.getItems({
  not: { in: { status: ["spam", "trash", "deleted"] } },
}).many()

// Combine NOT with other conditions
const activeLinkedPosts = await PostEntity.getItems({
  where: { status: "published" },
  not: { is: { external_id: null } },
}).many()

const results = await query(supabase, "users", { role: "admin" })
  .or({ role: "moderator" })
  .or({ role: "editor", active: true })
  .many()

// Entity with soft deletes enabled (excludes deleted by default)
const UserEntity = Entity(supabase, "users", {
  softDelete: true, // Automatically filters out deleted items
})

// Override soft delete behavior per query
const allUsers = await UserEntity.getItems().includeDeleted().many()
const deletedOnly = await UserEntity.getItems().onlyDeleted().many()
const activeOnly = await UserEntity.getItems().excludeDeleted().many() // Redundant - already excluded

// Entity without soft deletes (includes all items)
const AdminEntity = Entity(supabase, "users", {
  softDelete: false, // No automatic filtering
})

import { Entity, PartitionedEntity, query } from "supabase-typed-query"

// Entity with custom schema
const InventoryEntity = Entity(supabase, "items", {
  softDelete: false,
  schema: "inventory", // Uses client.schema("inventory").from("items")
})

const items = await InventoryEntity.getItems({ where: { active: true } }).many()

// PartitionedEntity with custom schema
const TenantItemsEntity = PartitionedEntity(supabase, "items", {
  partitionField: "tenant_id",
  softDelete: true,
  schema: "tenant_data",
})

// Query API with custom schema (7th parameter)
const results = await query(
  supabase,
  "items",
  { active: true },
  undefined, // is conditions
  undefined, // wherein conditions
  undefined, // order
  "inventory", // schema
).many()

import { ViewEntity, PartitionedViewEntity } from "supabase-typed-query"

// Create a read-only view entity
const AuthUsersView = ViewEntity(supabase, "auth_users_view", {
  schema: "agent_gate", // Optional: defaults to "public"
})

// Query the view - only getItem and getItems are available
const user = await AuthUsersView.getItem({ id: "123" }).one()
const activeUsers = await AuthUsersView.getItems({
  where: { is_active: true },
  order: ["created_at", { ascending: false }],
}).many()

// For multi-tenant views, use PartitionedViewEntity
const TenantStatsView = PartitionedViewEntity(supabase, "tenant_stats_view", {
  partitionField: "tenant_id",
})

// All queries require partition key
const stats = await TenantStatsView.getItems(tenantId, {
  where: { period: "monthly" },
}).many()

// Create a tenant-scoped entity
const TenantPostEntity = Entity(supabase, "posts", {
  softDelete: true,
  partitionKey: { tenant_id: "tenant-123" }, // All queries automatically include this filter
})

// All queries are automatically scoped to the tenant
const tenantPosts = await TenantPostEntity.getItems({
  where: { status: "published" },
}).many()
// Equivalent to: WHERE tenant_id = 'tenant-123' AND status = 'published' AND deleted IS NULL

// Create a global/admin entity (no partition)
const GlobalPostEntity = Entity(supabase, "posts", {
  softDelete: true,
  // No partitionKey - queries all tenants
})

const allPosts = await GlobalPostEntity.getItems().many()
// Equivalent to: WHERE deleted IS NULL

// Using TaskOutcome (recommended for explicit error handling)
const result = await query(supabase, "users", { id: userId }).one()

if (result.isOk()) {
  const maybeUser = result.getOrThrow()
  if (maybeUser.isSome()) {
    console.log("User found:", maybeUser.getOrThrow())
  }
} else {
  console.error("Query failed:", result.error)
}

// Using OrThrow methods (simpler but throws errors)
try {
  const user = await query(supabase, "users", { id: userId }).oneOrThrow()
  console.log("User:", user)
} catch (error) {
  console.error("Query failed:", error)
}

// TypeScript will enforce correct field names and types
const posts = await query(supabase, "posts", {
  // ✅ TypeScript knows these fields exist and their types
  title: "My Post",
  published: true,
  view_count: { gte: 100 },

  // ❌ TypeScript error: property doesn't exist
  nonexistent_field: "value",
}).many()

# Clone the repository
git clone https://github.com/jordanburke/supabase-typed-query.git
cd supabase-typed-query

# Install dependencies
pnpm install

# Run validation pipeline
pnpm validate

# Development
pnpm validate          # Run full validation: format, lint, typecheck, test, build
pnpm test             # Run tests
pnpm test:watch       # Run tests in watch mode
pnpm test:coverage    # Run tests with coverage
pnpm build            # Build for production
pnpm build:dev:watch  # Build in watch mode for development

# Code Quality
pnpm format           # Format code with Prettier
pnpm lint             # Fix ESLint issues
pnpm typecheck        # Type check with TypeScript

# Ensure you're logged into NPM
npm login

# Run validation and publish
pnpm build:publish