@rawsql-ts/sql-contract 0.1.0 → 0.2.0

package/README.md

@@ -1,51 +1,10 @@
-# @rawsql-ts/sql-contract
+
+# @rawsql-ts/sql-contract
 
 ## Overview
 
-@rawsql-ts/sql-contract is a lightweight library designed to reduce the repetitive, mechanical code commonly encountered when working with handwritten SQL.
-
-It improves the following aspects of the development experience:
-
-- Mapping query results to models
-- Writing simple INSERT, UPDATE, and DELETE statements
-
----
-
-## Features
-
-* Zero runtime dependencies
-  (pure JavaScript; no external packages required at runtime)
-* Zero DBMS dependency
-  (tested with PostgreSQL, MySQL, SQL Server, and SQLite)
-* Zero database client dependency
-  (works with any client that executes SQL and returns rows)
-* Zero framework and ORM dependency
-  (fits into any application architecture that uses raw SQL)
-* No schema models or metadata required
-  (tables, columns, and relationships are defined only in SQL)
-* Result mapping helpers that operate on any SQL returning rows
-  (including SELECT queries and CUD statements with RETURNING or aggregate results)
-* Simple builders for common INSERT, UPDATE, and DELETE cases, without query inference
-
----
-
-## Philosophy
-
-sql-contract treats SQL?especially SELECT statements?as a language for expressing domain requirements.
-
-In SQL development, it is essential to iterate quickly through the cycle of design, writing, verification, and refinement. To achieve this, a SQL client is indispensable. SQL must remain SQL, directly executable and verifiable; it cannot be adequately replaced by a DSL without breaking this feedback loop.
-
-Based on this philosophy, this library intentionally does not provide query construction features for SELECT statements. Queries should be written by humans, as raw SQL, and validated directly against the database.
-
-At the same time, writing SQL inevitably involves mechanical tasks. In particular, mapping returned rows to application-level models is not part of the domain logic, yet it often becomes verbose and error-prone. sql-contract focuses on reducing this burden.
-
-By contrast, write operations such as INSERT, UPDATE, and DELETE generally do not carry the same level of domain significance as SELECT statements. They are often repetitive, consisting of short and predictable patterns such as primary-key-based updates.
-
-To address this, the library provides minimal builder helpers for common cases only.
-
-It deliberately goes no further than this.
-
----
+`@rawsql-ts/sql-contract` is a lightweight library for reducing repetitive, mechanical code around handwritten SQL.  
+It focuses on mapping query results into application-typed models and simplifying common CUD (Create / Update / Delete) statement construction.
 
 ## Getting Started
 
@@ -54,86 +13,74 @@ It deliberately goes no further than this.
 ```sh
 pnpm add @rawsql-ts/sql-contract
 ```
+
 ### Minimal CRUD sample
 
 ```ts
 import { Pool } from 'pg'
-import { insert, update, remove } from '@rawsql-ts/sql-contract/writer'
 import {
-  createMapperFromExecutor,
-  mapperPresets,
-  type QueryParams,
-} from '@rawsql-ts/sql-contract/mapper'
-
-type Customer = {
-  customerId: number
-  customerName: string
-  customerStatus: string
-}
+  createReader,
+  createWriter,
+  type QueryParams
+} from '@rawsql-ts/sql-contract'
 
 async function main() {
-  // Prepare an executor that runs SQL and returns rows.
-  // sql-contract remains DBMS- and driver-agnostic by depending only on this function.
-  const pool = new Pool({ connectionString: process.env.DATABASE_URL })
+  const pool = new Pool({
+    connectionString: process.env.DATABASE_URL
+  })
 
   const executor = async (sql: string, params: QueryParams) => {
     const result = await pool.query(sql, params as unknown[])
     return result.rows
   }
 
-  // SELECT:
-  // Map snake_case SQL columns to a typed DTO without writing per-column mapping code.
-  const mapper = createMapperFromExecutor(executor, mapperPresets.appLike())
-  const rows = await mapper.query<Customer>(
-    `
-    select
-      customer_id,
-      customer_name,
-      customer_status
-    from customers
-    where customer_id = $1
-    `,
-    [42],
-  )
+  const reader = createReader(executor)
+  const writer = createWriter(executor)
 
-  // INSERT:
-  // Simplify repetitive SQL for common write operations.
-  const insertResult = insert('customers', {
-    name: 'alice',
-    status: 'pending',
-  })
-  await executor(insertResult.sql, insertResult.params)
+  const rows = await reader.list(
+    `SELECT customer_id, customer_name FROM customers WHERE status = $1`,
+    ['active']
+  )
 
-  // UPDATE:
-  // Simplify repetitive SQL for common write operations.
-  const updateResult = update(
+  await writer.insert('customers', { name: 'alice', status: 'active' })
+  await writer.update(
     'customers',
-    { status: 'active' },
-    { id: 42 },
+    { status: 'inactive' },
+    { id: 42 }
   )
-  await executor(updateResult.sql, updateResult.params)
-
-  // DELETE:
-  // Simplify repetitive SQL for common write operations.
-  const deleteResult = remove('customers', { id: 17 })
-  await executor(deleteResult.sql, deleteResult.params)
+  await writer.remove('customers', { id: 17 })
 
   await pool.end()
+
   void rows
 }
-
-void main()
 ```
 
----
+## Features
+
+* Zero runtime dependencies
+* Zero DBMS and driver dependencies
+* Works with any SQL-executor returning rows
+* Minimal mapping helpers for SELECT results
+* Simple builders for INSERT / UPDATE / DELETE
+
+## Philosophy
+
+### SQL as Domain Specification
+
+SQL is the primary language for expressing domain requirements—precise, unambiguous, and directly verifiable against the database.
+
+Mapping returned rows to typed domain models is mechanical and repetitive.
+This library removes that burden, letting domain logic remain in SQL.
 
-## Executor: DBMS / Driver Integration
+Write operations (INSERT/UPDATE/DELETE) are usually repetitive and predictable.
+So the library offers simple builders for common cases only.
 
-`sql-contract` is designed as a reusable, DBMS-agnostic library.
-To integrate it with a specific database or driver, **you must define a small executor function**.
+## Concepts
 
-An executor receives a SQL string and parameters, executes them using your DB driver, and returns the resulting rows as `Row[]`.
-By doing so, `sql-contract` can consume query results without knowing anything about the underlying database or driver.
+### Executor: DBMS / Driver Integration
+
+To integrate with any database or driver, define a single executor:
 
 ```ts
 const executor = async (sql: string, params: QueryParams) => {
@@ -142,335 +89,494 @@ const executor = async (sql: string, params: QueryParams) => {
 }
 ```
 
-This function is the single integration point between `sql-contract` and the DBMS.
-Connection pooling, transactions, retries, error handling, and other DBMS- or driver-specific concerns should all be handled within the executor.
+Connection pooling, retries, transactions, and error handling belong inside the executor.
+
+### Reader: Query Execution and Result Mapping
+
+Reader executes SELECT queries and maps raw database rows into application-friendly structures.
+
+It supports multiple levels of mapping depending on your needs,
+from quick projections to fully validated domain models.
+
+### Catalog executor: QuerySpec contract and observability
+
+Catalog executor executes queries through a `QuerySpec` instead of running raw
+SQL directly.
 
-The `params` argument uses the exported `QueryParams` type.
-It supports both positional arrays and named records, allowing executors to work with positional, anonymous, or named parameter styles depending on the driver.
+A `QuerySpec` defines a stable query contract that couples an SQL file,
+parameter shape, and output rules. By executing queries through this contract,
+the executor can enforce parameter expectations, apply output mapping or
+validation, and provide a stable identity for debugging and observability.
+
+`createCatalogExecutor` is wired with a SQL loader and a concrete query executor,
+and can optionally apply rewriters, binders, SQL caching,
+`allowNamedParamsWithoutBinder`, extensions, or an `observabilitySink`.
+
+When observability is enabled, execution emits lifecycle events
+(`query_start`, `query_end`, `query_error`) including `spec.id`, `sqlFile`,
+and execution identifiers, allowing queries to be traced and debugged by
+specification rather than raw SQL strings.
 
 ---
-## Mapper: Query Result Mapping (R)
 
-The mapper is responsible for projecting query results (`Row[]`) into DTOs.
+#### Basic result APIs: one and list
+
+Reader provides two primary methods:
 
-R looks like this:
+- one : returns a single row
+- list : returns multiple rows
 
 ```ts
-const reader = mapper.bind(customerMapping)
-await reader.one('SELECT ...', [42])
+const customer = await reader.one(
+  'select customer_id, customer_name from customers where customer_id = $1',
+  [1]
+)
+
+const customers = await reader.list(
+  'select customer_id, customer_name from customers'
+)
 ```
 
-In a typical application, a mapper is created once and reused across queries.
-It defines application-wide mapping behavior, while individual queries decide how results are projected.
+These methods focus only on execution.
+Mapping behavior depends on how the reader is configured.
 
-The mapper operates purely on returned rows and never inspects SQL, parameters, or execution behavior.
-To keep mapping predictable, it does not guess column semantics or relationships.
-All transformations are applied through explicit configuration.
+---
+
+#### Duck typing (minimal, disposable)
+
+For quick or localized queries, you can rely on structural typing without defining models.
 
 ```ts
-import {
-  createMapperFromExecutor,
-  mapperPresets,
-} from '@rawsql-ts/sql-contract/mapper'
-
-// `executor` is defined according to the Executor section above.
-const mapper = createMapperFromExecutor(
-  executor,
-  mapperPresets.appLike(),
+const rows = await reader.list<{ customerId: number }>(
+  'select customer_id from customers limit 1',
 )
 ```
 
-This example shows a typical mapper setup.
+You can also omit the DTO type entirely:
+
+```ts
+const rows = await reader.list(
+  'select customer_id from customers limit 1',
+)
+```
 
-For read-heavy flows you can also call `createReader(executor)`, which aliases the same factory and applies `mapperPresets.appLike()` by default so you get camelCase mapping with minimal setup.
+This approach is:
 
-`createMapperFromExecutor` binds an executor to a mapper and accepts optional mapping options.
-These options control how column names are normalized, how values are coerced, and how identifiers are treated.
+* Fast to write
+* Suitable for one-off queries
+* No runtime validation
 
-For convenience, `mapperPresets` provide reusable configurations for common scenarios:
+---
 
-| Preset                    | Description                                                                                                 |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `mapperPresets.appLike()` | Applies common application-friendly defaults, such as snake_case to camelCase conversion and date coercion. |
-| `mapperPresets.safe()`    | Leaves column names and values untouched, suitable for exploratory queries or legacy schemas.               |
+#### Custom mapping
 
-When a specific query needs fine-grained control, you can also provide a custom options object.
-This allows localized adjustments without changing the preset used elsewhere.
+Reader allows custom projection logic when structural mapping is insufficient.
 
 ```ts
-const mapper = createMapperFromExecutor(executor, {
-  keyTransform: 'snake_to_camel',
-  coerceDates: true,
-  idKeysAsString: true,
-  typeHints: {
-    createdAt: 'date',
-  },
-})
+const rows = await reader.map(
+  'select price, quantity from order_items',
+  (row) => ({
+    total: row.price * row.quantity,
+  })
+)
 ```
 
-This form mirrors `mapperPresets.appLike()` while allowing targeted overrides for a specific mapping.
+This is useful for:
+
+* Derived values
+* Format conversion
+* Aggregated projections
 
 ---
 
-### Duck-typed mapping (no model definitions)
 
-For lightweight or localized use cases, the mapper supports duck-typed projections without defining any schema or mapping models.
+#### Column naming conventions (default behavior)
 
-In duck-typed mapping, the mapper applies no additional structural assumptions beyond its configured defaults.
-The shape of the result is defined locally at the query site, either by providing a TypeScript type or by relying on the raw row shape.
+Reader applies a default naming rule that converts snake_case database columns
+into camelCase JavaScript properties.
 
-```ts
-// Explicitly typed projection
-const rows = await mapper.query<{ customerId: number }>(
-  'select customer_id from customers limit 1',
-)
+This allows most queries to work without explicit mapping.
+
+Example:
+
+```sql
+select customer_id, created_at from customers
 ```
 
-Although not recommended, you can omit the DTO type for quick exploration:
+becomes:
 
 ```ts
-const rows = await mapper.query(
-  'select customer_id from customers limit 1',
-)
+{
+  customerId: number
+  createdAt: Date
+}
 ```
 
-Duck-typed mapping is intentionally minimal and local.
-If the shape of the query results is important or reused throughout your application, consider moving to explicit row mapping.
+No mapping definition is required for this transformation.
 
 ---
 
-### Mapping to a Single Model
+#### Mapper presets
+
+You can configure how column names are transformed.
 
-sql-contract allows you to map query results to typed DTOs.
+Example:
 
 ```ts
-type Customer = {
-  customerId: number
-  customerName: string
-}
+const reader = createReader(executor, mapperPresets.safe())
+```
 
-const rows = await mapper.query<Customer>(
-  `
-  select
-    customer_id,
-    customer_name
-  from customers
-  where customer_id = $1
-  `,
-  [42],
-)
+Common presets include:
 
-// rows[0].customerName is type-safe
-```
+* appLike : snake_case → camelCase conversion
+* safe : no column name transformation
+
+Choose a preset based on how closely your domain models align with database naming.
+
+---
+
+#### When explicit mapping is useful
 
-The normalization rules applied during mapping are controlled by the selected mapper preset.
+Even with automatic naming conversion, explicit mappings become valuable when:
 
-You can also define one-off mapping rules using columnMap.
+* Domain terms differ from column names
+* Multiple columns combine into one field
+* Queries are reused across modules
+* Schema stability should be decoupled from application models
+
+---
+
+#### Single model mapping (reusable definition)
+
+Mapping models provide explicit control over how rows map to domain objects.
+
+Example:
 
 ```ts
-const customerMapping = rowMapping<Customer>({
+const orderSummaryMapping = rowMapping({
+  name: 'OrderSummary',
+  key: 'orderId',
   columnMap: {
-    customerId: 'customer_id',
-    customerName: 'customer_name',
+    orderId: 'order_id',
+    customerLabel: 'customer_display_name',
+    totalAmount: 'grand_total',
   },
 })
 
-const rows = await mapper.query<Customer>(
-  `
-  select
-    customer_id,
-    customer_name
-  from customers
-  where customer_id = $1
-  `,
-  [42],
-  customerMapping, // explicitly specify the mapping rule
-)
-
-// rows[0].customerName is type-safe
+const summaries = await reader
+  .bind(orderSummaryMapping)
+  .list(`
+    select
+      order_id,
+      customer_display_name,
+      grand_total
+    from order_view
+  `)
 ```
 
-The `rowMapping()` helper replaces the previous `entity()` alias. The old name is still supported for now but is deprecated in favor of `rowMapping()`.
+In this example:
 
-When a query includes JOINs or relationships, explicit row mappings are required.
-The structure for such mappings is explained in the next section.
+* Domain terminology differs from database naming
+* Mapping clarifies intent
+* The definition can be reused across queries
+
+Benefits:
+
+* Reusable mapping definitions
+* Explicit domain language alignment
+* Reduced accidental schema coupling
+* Better long-term maintainability
 
 ---
 
-### Mapping to multiple models (joined rows)
+#### Composite keys
 
-The mapper also supports mapping joined result sets into multiple related models.
+`rowMapping` keys can now be more than a single column without breaking existing consumers:
 
-Relations are explicitly defined and never inferred.
+* **Array-based composite keys** — pass the raw column names in SQL order (`key: ['col_a', 'col_b']`). These column values are extracted directly from the executor’s row, so `columnMap` / `prefix` rules are not involved.
+* **Derived keys** — supply a function, e.g. `key: (row) => [row.col_a, row.col_b]`, that returns strings/numbers/bigints or an array thereof. The library type-tags each component so `'1'` and `1` are never conflated, and order of the array is preserved.
 
-```ts
-const orderMapping = rowMapping({
-  name: 'order',
-  key: 'orderId',
-  prefix: 'order_',
-}).belongsTo('customer', customerMapping, 'customerId')
-```
+Both forms feed through a single normalization path, so you can combine mixed types safely and receive clear errors if a value is `null`, `undefined`, or missing. Creating a synthetic column inside SQL (e.g. `SELECT CONCAT(col_a, '|', col_b) AS composite_key`) still works as a workaround, but we recommend using the multi-column helpers because they keep the schema explicit and avoid delimiter collisions.
 
-Joined queries remain transparent and deterministic:
+`name` continues to serve as the user-visible label for error messages, independent of whether the key is scalar, composite, or derived.
+
+#### Multi-model mapping
+
+Reader supports mapping joined results into multiple domain models by composing `rowMapping` definitions.
 
 ```ts
-const mapper = createMapperFromExecutor(executor)
+const customerMapping = rowMapping({
+  name: 'Customer',
+  key: 'customerId',
+  columnMap: {
+    customerId: 'customer_customer_id',
+    customerName: 'customer_customer_name',
+  },
+})
+
+const orderMapping = rowMapping<{
+  orderId: number
+  orderTotal: number
+  customerId: number
+  customer: { customerId: number; customerName: string }
+}>({
+  name: 'Order',
+  key: 'orderId',
+  columnMap: {
+    orderId: 'order_order_id',
+    orderTotal: 'order_total',
+    customerId: 'order_customer_id',
+  },
+}).belongsTo('customer', customerMapping, 'customerId')
 
-const rows = await mapper.query(
-  `
+const result = await reader
+  .bind(orderMapping)
+  .list(`
     select
-      o.order_id,
-      o.order_total,
-      c.customer_id,
-      c.customer_name
-    from orders o
-    join customers c on c.customer_id = o.customer_id
-    where o.order_id = $1
-  `,
-  [123],
-  orderMapping,
-)
+      c.id as customer_customer_id,
+      c.name as customer_customer_name,
+      o.id as order_order_id,
+      o.total as order_total,
+      o.customer_id as order_customer_id
+    from customers c
+    join orders o on o.customer_id = c.customer_id
+  `)
 ```
 
+`belongsTo` attaches each customer row to its owning order, so the mapped result exposes a nested `customer` object without duplicating join logic.
+
+This enables structured projections from complex joins.
+
 ---
 
-## Writer: emitting simple C / U / D statements
+#### Validator-backed mapping (recommended)
 
-The writer helpers provide a small, opinionated DSL for common
-INSERT, UPDATE, and DELETE statements.
+Runtime validation ensures data correctness.
+Zod integration is the recommended approach.
 
-They accept table names and plain objects of column-value pairs, and deterministically emit `{ sql, params }`.
+```ts
+import { z } from 'zod'
 
-The writer focuses on *construction*, not execution.
+const CustomerSchema = z.object({
+  customerId: z.number(),
+  customerName: z.string(),
+})
+
+const row = await reader
+  .validator(CustomerSchema)
+  .one(
+    'select customer_id, customer_name from customers where customer_id = $1',
+    [1]
+  )
+```
 
-### Writer basics
+Benefits include:
 
-Writer helpers are intentionally limited:
+* Runtime safety
+* Explicit schema documentation
+* Refactoring confidence
+* AI-friendly feedback loops
 
-* `undefined` values are omitted
-* identifiers are validated against ASCII-safe patterns unless explicitly allowed
-* WHERE clauses are limited to equality-based AND fragments
-* no inference, no joins, no multi-table logic
+---
 
-If `returning` is provided, a `RETURNING` clause is appended.
-Using `'all'` maps to `RETURNING *`; otherwise, column names are sorted alphabetically.
+### Scalar Queries
 
-The writer never checks backend support for `RETURNING`.
-It emits SQL exactly as specified so that success or failure remains observable at execution time.
+Use scalar helpers when a query returns a single value.
 
-### INSERT
+#### Basic scalar usage
 
 ```ts
-await writer.insert(
-  'projects',
-  { name: 'Apollo', owner_id: 7 },
-  { returning: ['project_id'] },
+const count = await reader.scalar(
+  'select count(*) from customers where status = $1',
+  ['active']
 )
 ```
 
-### UPDATE
+This is useful for:
+
+* COUNT queries
+* Aggregate values
+* Existence checks
+
+---
+
+#### Typed scalar mapping
+
+You can explicitly define the expected scalar type.
 
 ```ts
-await writer.update(
-  'projects',
-  { name: 'Apollo' },
-  { project_id: 1 },
+const count = await reader.scalar<number>(
+  'select count(*) from customers where status = $1',
+  ['active']
 )
 ```
 
-### DELETE
+This improves readability and helps prevent accidental misuse.
+
+---
+
+#### Scalar validation with Zod (recommended)
+
+For stricter guarantees, scalar values can be validated at runtime.
 
 ```ts
-await writer.remove(
-  'projects',
-  { project_id: 1 },
+import { z } from 'zod'
+
+const count = await reader.scalar(
+  z.number(),
+  'select count(*) from customers where status = $1',
+  ['active']
 )
 ```
 
-Statements can also be built without execution:
+This approach ensures:
+
+* Runtime type safety
+* Clear intent
+* Safer refactoring
+
+---
+
+### Zod integration and coercion helpers
+
+Reader integrates smoothly with Zod for runtime validation and safe type conversion.
+
+Zod validation helps ensure that query results match your domain expectations,
+especially when working with numeric or date values returned as strings by drivers.
+
+---
+
+#### Row validation with Zod
 
 ```ts
-const built = writer.build.insert(
-  'projects',
-  { name: 'Apollo', owner_id: 7 },
-  { returning: ['project_id'] },
-)
+import { z } from 'zod'
+
+const CustomerSchema = z.object({
+  customerId: z.number(),
+  customerName: z.string(),
+})
+
+const row = await reader
+  .validator(CustomerSchema)
+  .one(
+    'select customer_id, customer_name from customers where customer_id = $1',
+    [1]
+  )
 ```
 
-### Writer presets and placeholder strategies
+This provides:
 
-Advanced usage flows through `createWriter` (aliasing the historic `createWriterFromExecutor`), which binds an executor to a concrete placeholder strategy.
+* Runtime safety
+* Clear schema documentation
+* Refactoring confidence
 
-A writer preset defines:
+---
 
-1. how placeholders are formatted,
-2. whether parameters are positional or named,
-3. how parameters are ordered and bound.
+#### Scalar validation with Zod
 
 ```ts
-import { createWriter, writerPresets } from '@rawsql-ts/sql-contract/writer'
-
-const writer = createWriter(
-  executor,
-  writerPresets.named({
-    formatPlaceholder: (paramName) => ':' + paramName,
-  }),
+const count = await reader.scalar(
+  z.number(),
+  'select count(*) from customers'
 )
 ```
 
-### Named placeholders
+---
+
+#### Coercion helpers for numeric values
 
-Named presets derive parameter names from column names.
+Some database drivers return numeric values as strings.
+The package provides helpers to safely convert them.
 
-Each bind increments a counter and produces deterministic names such as
-`name_1`, `owner_id_2`.
+Example:
 
 ```ts
-await writer.insert('projects', { name: 'Apollo', owner_id: 7 })
-// SQL: INSERT INTO projects (name, owner_id) VALUES (:name_1, :owner_id_2)
-// params: { name_1: 'Apollo', owner_id_2: 7 }
+import { z } from 'zod'
+import {
+  zNumberFromString,
+  zBigIntFromString
+} from '@rawsql-ts/sql-contract-zod'
+
+const schema = z.object({
+  totalAmount: zNumberFromString,
+  largeCounter: zBigIntFromString,
+})
 ```
 
+These helpers:
+
+* Convert strings into numeric types
+* Fail fast when values are invalid
+* Reduce manual parsing logic
+
 ---
 
-## DBMS and driver differences
+#### When to use coercion
 
-`sql-contract` does not normalize SQL dialects or placeholder styles.
+Use coercion helpers when:
 
-Write SQL using the placeholder syntax required by your driver, and bind parameters exactly as that driver expects.
-Whether parameters are positional or named is a concern of the executor and driver, not `sql-contract`.
+* Working with NUMERIC / DECIMAL columns
+* Drivers return BIGINT as strings
+* You want runtime guarantees
 
-Examples of common placeholder styles:
+---
+
+### Writer: Simple CUD Helpers
 
-| DBMS / driver                     | Placeholder style  |
-| --------------------------------- | ------------------ |
-| PostgreSQL / Neon (node-postgres) | `$1`, `$2`, ...    |
-| PostgreSQL / pg-promise           | `$/name/`          |
-| MySQL / SQLite                    | `?`                |
-| SQL Server                        | `@p1`, `@p2`, ...  |
-| Oracle                            | `:1`, `:name`, ... |
+Writer helpers build simple INSERT/UPDATE/DELETE SQL:
 
 ```ts
-await executor(
-  'select * from customers where customer_id = $1',
-  [42],
+await writer.insert('projects', {
+  name: 'Apollo',
+  owner_id: 7
+})
+
+await writer.update(
+  'projects',
+  { name: 'Apollo' },
+  { project_id: 1 }
 )
+
+await writer.remove('projects', { project_id: 1 })
 ```
 
+You can also build statements without execution:
+
 ```ts
-await executor(
-  'select * from customers where customer_id = :customerId',
-  { customerId: 42 },
+const stmt = writer.build.insert(
+  'projects',
+  { name: 'Apollo' }
 )
 ```
 
-All DBMS- and driver-specific concerns live in the executor.
-Both writer and mapper remain independent of these differences.
+## Reducers (Coercion Helpers)
 
----
+The package exposes pure coercion helpers:
 
-## Influences / Related Ideas
+* `decimalStringToNumberUnsafe`
+* `bigintStringToBigInt`
+
+They convert raw DB output strings into numbers or bigints when needed.
 
-Sql-contract is inspired by minimal mapping libraries such as Dapper and other thin contracts that keep SQL visible while wiring rows to typed results. These projects demonstrate the value of stopping short of a full ORM and instead providing a predictable, testable layer for purely mechanical concerns.
+## DBMS Differences
+
+sql-contract does not normalize SQL dialects or placeholder styles.
+You must use the placeholder syntax required by your driver.
+
+Examples:
+
+```ts
+await executor(
+ 'select * from customers where id = $1',
+ [42],
+)
+await executor(
+ 'select * from customers where id = :id',
+ { id: 42 },
+)
+```
+
+## Influences / Related Ideas
 
-Sql-contract adopts that lesson within the rawsql-ts ecosystem: SQL remains the domain language, and this package automates only the tedious bridging work around it.
+sql-contract is inspired by minimal mapping libraries such as Dapper,
+stopping short of a full ORM and instead providing a predictable, transparent layer.