@supabase/postgrest-js 2.89.1-canary.1 → 2.89.1-canary.3

package/README.md

@@ -47,10 +47,10 @@ const REST_URL = 'http://localhost:3000'
 const postgrest = new PostgrestClient(REST_URL)
 ```
 
-- select(): https://supabase.com/docs/reference/javascript/select
-- insert(): https://supabase.com/docs/reference/javascript/insert
-- update(): https://supabase.com/docs/reference/javascript/update
-- delete(): https://supabase.com/docs/reference/javascript/delete
+- [select()](https://supabase.com/docs/reference/javascript/select)
+- [insert()](https://supabase.com/docs/reference/javascript/insert)
+- [update()](https://supabase.com/docs/reference/javascript/update)
+- [delete()](https://supabase.com/docs/reference/javascript/delete)
 
 #### Custom `fetch` implementation
 
@@ -72,45 +72,22 @@ This package is part of the [Supabase JavaScript monorepo](https://github.com/su
 ### Building
 
 ```bash
-# Complete build (from monorepo root)
+# Build (from monorepo root)
 npx nx build postgrest-js
 
 # Build with watch mode for development
-npx nx build postgrest-js --watch
-
-# Individual build targets
-npx nx build:cjs postgrest-js   # CommonJS build
-npx nx build:esm postgrest-js   # ES Modules wrapper
-
-# Other useful commands
-npx nx clean postgrest-js       # Clean build artifacts
-npx nx format postgrest-js      # Format code with Prettier
-npx nx lint postgrest-js        # Run ESLint
-npx nx type-check postgrest-js  # TypeScript type checking
-npx nx docs postgrest-js        # Generate documentation
-```
-
-#### Build Outputs
-
-- **CommonJS (`dist/cjs/`)** - For Node.js environments
-  - `index.js` - Main entry point
-  - `index.d.ts` - TypeScript definitions
-- **ES Modules (`dist/esm/`)** - For modern bundlers
-  - `wrapper.mjs` - ESM wrapper that imports CommonJS
-
-#### Special Build Setup
+npx nx build:watch postgrest-js
 
-Unlike other packages, postgrest-js uses a hybrid approach:
+# TypeScript type checking
+npx nx type-check postgrest-js
 
-- The main code is compiled to CommonJS
-- An ESM wrapper (`wrapper.mjs`) is provided for ES Module environments
-- This ensures maximum compatibility across different JavaScript environments
-
-The `wrapper.mjs` file simply re-exports the CommonJS build, allowing the package to work seamlessly in both CommonJS and ESM contexts.
+# Generate documentation
+npx nx docs postgrest-js
+```
 
 ### Testing
 
-**Docker Required!** The postgrest-js tests need a local PostgreSQL database and PostgREST server running in Docker containers.
+**Supabase CLI Required!** The `postgrest-js` tests use the [Supabase CLI](https://supabase.com/docs/guides/local-development/cli/getting-started) to run a local PostgreSQL database and PostgREST server.
 
 #### Quick Start
 
@@ -121,72 +98,99 @@ npx nx test:ci:postgrest postgrest-js
 
 This single command automatically:
 
-1. Cleans any existing test containers
-2. Starts PostgreSQL database and PostgREST server in Docker
-3. Waits for services to be ready
-4. Runs format checking
-5. Runs TypeScript type tests
-6. Generates and validates TypeScript types from the database schema
-7. Runs all Jest unit tests with coverage
-8. Runs CommonJS and ESM smoke tests
-9. Cleans up Docker containers
+1. Stops any existing Supabase CLI containers
+2. Starts PostgreSQL database and PostgREST server via Supabase CLI
+3. Resets and seeds the database
+4. Runs all Jest unit tests with coverage
+5. Cleans up containers
 
 #### Individual Test Commands
 
 ```bash
-# Run tests with coverage
+# Run Jest tests with coverage (requires infrastructure running)
 npx nx test:run postgrest-js
 
-# Update test snapshots and regenerate types
-npx nx test:update postgrest-js
-
-# Type checking only
+# Run type tests with tstyche
 npx nx test:types postgrest-js
 
+# Run smoke tests (CommonJS and ESM imports)
+npx nx test:smoke postgrest-js
+
+# Format code
+npx nx format postgrest-js
+
+# Check formatting
+npx nx format:check postgrest-js
 ```
 
 #### Test Infrastructure
 
-The tests use Docker Compose to spin up:
+The tests use Supabase CLI to spin up:
 
-- **PostgreSQL** - Database with test schema and dummy data
-- **PostgREST** - REST API server that the client connects to
+- **PostgreSQL** - Database with test schema and seed data (port 54322)
+- **PostgREST** - REST API server that the client connects to (port 54321)
 
 ```bash
-# Manually manage test infrastructure
-npx nx db:run postgrest-js     # Start containers
-npx nx db:clean postgrest-js   # Stop and remove containers
+# Manually manage test infrastructure (from monorepo root)
+npx nx test:infra postgrest-js      # Start containers
+npx nx test:clean-pre postgrest-js  # Stop and remove containers
 ```
 
-#### What `test:update` Does
+Or directly via Supabase CLI:
 
-The `test:update` command is useful when:
+```bash
+cd packages/core/postgrest-js/test
+supabase start        # Start all services
+supabase db reset     # Reset and seed database
+supabase stop         # Stop all services
+```
 
-- Database schema changes require updating TypeScript types
-- Test snapshots need to be updated after intentional changes
+#### Regenerating TypeScript Types
 
-It performs these steps:
+When the database schema changes, regenerate TypeScript types from the actual database:
 
-1. Starts fresh database containers
-2. **Regenerates TypeScript types** from the actual database schema
-3. **Updates Jest snapshots** for all tests
-4. Cleans up containers
+```bash
+npx nx db:generate-test-types postgrest-js
+```
+
+This connects to the running Supabase instance and generates types in `test/types.generated.ts`.
 
 #### Test Types Explained
 
-- **Format Check** - Ensures code formatting with Prettier
-- **Type Tests** - Validates TypeScript types using `tstyche`
-- **Generated Types Test** - Ensures generated types match database schema
-- **Unit Tests** - Jest tests covering all client functionality
-- **Smoke Tests** - Basic import/require tests for CommonJS and ESM
+- **Unit Tests** - Jest tests covering all client functionality (`npx nx test:run postgrest-js`)
+- **Type Tests** - Validates TypeScript types using tstyche (`npx nx test:types postgrest-js`)
+- **Smoke Tests** - Basic import/require tests for CommonJS and ESM (`npx nx test:smoke postgrest-js`)
 
 #### Prerequisites
 
-- **Docker** must be installed and running
-- **Port 3000** - PostgREST server (API)
-- **Port 8080** - Database schema endpoint (for type generation)
+- **Supabase CLI** must be installed ([instructions](https://supabase.com/docs/guides/local-development/cli/getting-started)) or can be used through `npx` (`npx supabase`)
+- **Docker** must be installed and running (Supabase CLI uses Docker under the hood)
+- **Port 54321** - PostgREST API
+- **Port 54322** - PostgreSQL database
+- **Port 54323** - Supabase Studio (used for type generation)
+
+#### PostgREST v12 Backward Compatibility Tests
+
+We maintain backward compatibility tests for PostgREST v12 (the current Supabase CLI uses v14+). These tests ensure the SDK works correctly for users still running older PostgREST versions.
+
+```bash
+# Run v12 compatibility tests (requires Docker)
+npx nx test:ci:v12 postgrest-js
+```
+
+This command:
+
+1. Starts PostgREST v12 + PostgreSQL in Docker (ports 3012/5433)
+2. Runs runtime tests that verify v12-specific behavior
+3. Cleans up containers
+
+**Type-only tests** for v12 compatibility also run as part of the regular type tests:
+
+```bash
+npx nx test:types postgrest-js  # Includes v12-compat.test-d.ts
+```
 
-**Note:** Unlike a full Supabase instance, this uses a minimal PostgREST setup specifically for testing the SDK.
+**Note:** These v12 tests will be removed when v3 ships (sometime in 2026).
 
 ### Contributing