typed-contract-in-tests

Use Typed Contract in Integration Tests

Rule

Integration tests should import the typed Contract from fixtures/contract.d.ts instead of using the generic SqlContract<SqlStorage> type. This provides proper type inference for tables, columns, and query results.

The Problem

Using generic contract types loses type information:

// ❌ WRONG: Generic type loses inference
import type { SqlContract, SqlStorage } from '@internal/sql-contract/types';

function loadContractFixture(): SqlContract<SqlStorage> {
  // ...
}

// Later in tests:
const tables = schema(context).tables;
const userTable = tables['user']!;  // Needs non-null assertion
const userColumns = userTable.columns;
const plan = sql({ context })
  .from(userTable)
  .select({ id: userColumns['id']!, email: userColumns['email']! })  // Needs bracket access + assertions
  .build({ params: { cursor: 5 } });

const rows = await executePlanAndCollect(runtime, plan);
expect(rows.map((r) => r['id'] as number)).toEqual([6, 7, 8, 9, 10]);  // Needs type cast

The Solution

Import the typed Contract from the fixtures directory and name it where the JSON enters. A test that builds a client passes the JSON through the target's contractFromJson and gives the result to the client, which infers the contract type from it:

// ✅ CORRECT: the client infers Contract from the typed value
import postgres from '@internal/postgres/runtime';
import { contractFromJson } from '@internal/postgres/static';
import type { Contract } from './fixtures/contract.d';
import contractJson from './fixtures/contract.json' with { type: 'json' };

const db = postgres({ contract: contractFromJson<Contract>(contractJson), url });

Never write the type argument on the client (postgres<Contract>(...)): the clients take only { contract }.

A test that needs a contract without a client validates the JSON with validateSqlContractFully:

// ✅ CORRECT: Typed contract provides full inference
import type { Contract } from './fixtures/contract.d';

function loadContractFixture(): Contract {
  const fixtureDir = dirname(fileURLToPath(import.meta.url));
  const contractPath = join(fixtureDir, 'fixtures/contract.json');
  const json = readFileSync(contractPath, 'utf8');
  const contractJson = JSON.parse(json) as unknown;
  return validateSqlContractFully<Contract>(contractJson);
}

// Later in tests:
const { user } = schema(context).tables;  // Destructure directly
const plan = sql({ context })
  .from(user)
  .select({ id: user.columns.id, email: user.columns.email })  // Direct property access
  .where(user.columns.id.gt(param('cursor')))
  .build({ params: { cursor: 5 } });

const rows = await executePlanAndCollect(runtime, plan);
expect(rows.map((r) => r.id)).toEqual([6, 7, 8, 9, 10]);  // r.id is typed as number