@typed-sql/core

The stable, driver- and grammar-neutral foundation of typed-sql. It defines queries, fragments, rendering, database adapters, diagnostics, schema contracts, and the interface implemented by every SQL grammar.

pnpm add @typed-sql/core @typed-sql/postgres pg

Application queries import sql from the selected grammar so the compiler can associate each template with its dialect:

import { sql } from "@typed-sql/postgres";
import type { QueryParameters, QueryRow } from "@typed-sql/core";

const query = sql`
  SELECT account.id, account.email
  FROM accounts AS account
  WHERE account.id = ${42n}
`;

type Account = QueryRow<typeof query>;
type Parameters = QueryParameters<typeof query>;

Runtime adapters share grammar-neutral result and control contracts: all, one, and maybeOne preserve the inferred row, accept optional signals or absolute deadlines, and expose stable cardinality and cancellation errors. Adapter capabilities are explicit; unsupported controls are never silently ignored.

Optional adapter services use namespaced capability tokens rather than widening the common Database interface. getAdapterCapability and requireAdapterCapability preserve the service type without adding a protocol or driver dependency to core.

DatabaseObserver provides redacted query, batch, pipeline, stream, cancellation, and nested transaction lifecycles. It is disabled by default and does not add a telemetry dependency to core.

sql.validateResult(query, schema) optionally validates decoded rows through the structural Standard Schema V1 interface. Validator output must agree with the inferred row; core does not install Zod, Valibot, or another validator package.

createRoutedDatabase provides conservative, grammar-neutral primary/replica selection and bounded explicit-transaction retries from semantic evidence. Dialect packages supply the semantic resolver; applications continue owning every database adapter and topology decision.

Grammar and adapter authors can use DialectPlugin, DIALECT_CONTRACT_VERSION, assertDialectPlugin, defineQuerySemantics, mergeQuerySemantics, createDatabase, renderQuery, the prepared-query skeleton helpers, and the neutral resolver primitives from the package root. The package has no parser, grammar, database driver, TypeScript compiler, or editor dependency.

Read the query API, architecture, routing and retry guide, bulk data guide, result validation guide, and custom grammar guide.

MIT © typed-sql contributors