qubu 0.6.2 → 0.7.0

package/docs/getting-started.md

@@ -1,6 +1,6 @@
 # Getting started
 
-> Define a typed table, build one parameterized query, and inspect the exact SQL before connecting a driver.
+> Define a table and inspect your first query’s SQL and parameters.
 
 ## Install Qubu
 
@@ -13,10 +13,9 @@ pnpm add qubu
 Import query-building functions from the package root. Qubu does not need a
 database connection to construct or render a query.
 
-The examples use the same order as the rendered statement: projection, `FROM`,
-then `WHERE`, ordering, grouping, and pagination. `select()` still accepts
-independent clauses in any order, which lets reusable values be composed, but
-keeping the final call in SQL order makes the query easy to scan and repair.
+The examples write clauses in SQL order so the query is easy to scan.
+`select()` also accepts independent clauses in any order and puts them in SQL
+order when rendering.
 
 ## Define a table
 
@@ -38,10 +37,9 @@ nullable email column is inferred as `string | null` when selected.
 
 ## Build and render a query
 
-Pass a named projection and the final clauses to `select()` in SQL order. Qubu
-also accepts independent clause values in another order when composition needs
-it, then renders the normalized statement in SQL order. The example uses the
-`users` table from the previous section.
+Pass the fields you want to return as a named object, called the projection.
+Then add the clauses. This example uses the `users` table from the previous
+section.
 
 ```ts
 import { eq, from, render, select, where } from "qubu"
@@ -69,6 +67,8 @@ statement.parameters
 // [7]
 ```
 
+### Inspect the result type
+
 The selected row type is available on the query value:
 
 ```ts

package/docs/guides/better-auth.md

@@ -1,6 +1,8 @@
 # Better Auth
 
-> Derive Qubu-owned auth tables and run Better Auth through a transactional Qubu client.
+> Define auth tables with Qubu and connect Better Auth to a transactional Qubu client.
+
+## Install the integration
 
 Install the integration next to Qubu and Better Auth:
 
@@ -8,10 +10,15 @@ Install the integration next to Qubu and Better Auth:
 pnpm add qubu @qubu/better-auth better-auth
 ```
 
-Define the Better Auth options once. The schema derivation reads Better Auth's
-resolved public metadata, so core tables, renamed models and fields, additional
-fields, plugin tables, references, unique constraints, and compound indexes all
-participate.
+## Define the auth schema
+
+Define the Better Auth options once. Qubu derives its schema from Better Auth’s
+resolved public metadata, including:
+
+- Core tables and renamed models or fields.
+- Additional fields and plugin tables.
+- References and unique constraints.
+- Compound indexes.
 
 ```ts
 import { betterAuth } from "better-auth"
@@ -44,6 +51,8 @@ export const auth = betterAuth({
 migration-plan, and DDL workflows. The adapter's Better Auth `createSchema`
 hook emits a TypeScript module that reconstructs the same Qubu-owned metadata.
 
+## Database requirements
+
 The package never imports PostgreSQL, MySQL, or SQLite drivers. It executes
 through Qubu's query and transaction boundaries. PostgreSQL and SQLite use one
 limited mutation statement for atomic consume and guarded increment operations;
@@ -51,6 +60,8 @@ MySQL locks one selected row inside the Qubu-owned transaction. A client without
 transaction support, or a dialect other than PostgreSQL, MySQL, or SQLite, is
 rejected during adapter construction.
 
+## Enum limitation
+
 Better Auth enum metadata is currently rejected because Qubu cannot preserve
 the closed value set as a portable column without adding a database constraint.
 The error includes the model and field path instead of silently widening it to

package/docs/guides/compose-queries.md

@@ -1,6 +1,6 @@
 # Compose queries
 
-> Reuse a query's inferred row shape as a typed source for CTEs, derived tables, subqueries, and set operations.
+> Reuse a query as a CTE, a derived table, or a subquery, and combine query results.
 
 ## Turn a query into a CTE
 
@@ -28,6 +28,8 @@ The rendered statement includes the `WITH` clause before `SELECT`. Selected
 camelCase keys use snake_case while they belong to the CTE relation; the outer
 result projection aliases them back to camelCase for the returned row.
 
+### Use a CTE in a mutation
+
 Attach the same clause to an insert, update, or delete when the mutation reads
 through the CTE. For example, an insert can consume a filtered CTE through
 `insertSelect()`:
@@ -66,11 +68,20 @@ const numbers = recursiveCte("numbers", select({ value: cast(value(1), integer()
 const query = select({ value: numbers.value }, withCte(numbers), from(numbers))
 ```
 
-The anchor names the fields, application types, nullability, and SQL domains
-that the returned source exposes. The member must project those same fields
-with compatible types. Give bound anchor values an explicit SQL type with
+The anchor defines the fields the CTE returns:
+
+- Field names.
+- Application types.
+- Nullability.
+- SQL domains.
+
+The recursive member must select the same fields with compatible types.
+
+Give bound anchor values an explicit SQL type with
 `cast()` when the database cannot infer it from surrounding columns; PostgreSQL
-requires this for recursive CTE anchors. Qubu renders `WITH RECURSIVE`, an
+requires this for recursive CTE anchors.
+
+Qubu renders `WITH RECURSIVE`, an
 explicit relation column list, and `anchor UNION ALL member`; ordinary and
 recursive CTEs can share one `withCte()` clause.
 
@@ -117,7 +128,9 @@ const query = select(
 `scalar()` throws at runtime when the query selects more than one field. Its
 type is the selected field's value type, widened with `null` when the query may
 return no rows. An ordinary select and `fetchFirst(1)` are both nullable: the
-limit proves at most one row, not that a row exists. A source-free select such
+limit proves at most one row, not that a row exists.
+
+A source-free select such
 as `select({ value: value(42) })` is known to produce exactly one row.
 
 Qubu does not treat an arbitrary predicate as proof of exactness. Use
@@ -163,9 +176,8 @@ code.
 ## Constrain a reusable fragment by required fields
 
 Use `TableLike` when a fragment requires a physical table and `SourceLike`
-when aliases, CTEs, derived tables, or custom sources are also valid. Both are
-lower-bound constraints: the source may contain additional fields, and the
-generic function retains its exact source identity.
+when aliases, CTEs, derived tables, or custom sources are also valid. Both allow the source to contain additional fields. The generic function
+retains the source’s exact identity.
 
 For an application-level requirement, describe the required JavaScript row:
 

package/docs/guides/drizzle.md

@@ -123,9 +123,14 @@ override.
 ## Runtime metadata
 
 Each dialect adapter maps Qubu storage descriptors to its own Drizzle builders.
-It also transfers concrete defaults, generated expressions, common primary and
-unique constraints, checks, foreign keys, and indexes. Native storage must
-belong to the selected dialect:
+It also transfers:
+
+- Concrete defaults and generated expressions.
+- Common primary and unique constraints.
+- Checks and foreign keys.
+- Indexes.
+
+Native storage must belong to the selected dialect:
 
 ```ts
 import { nativeColumn, schema, table } from "qubu"

package/docs/guides/extensions/dialects.md

@@ -1,6 +1,6 @@
 # Add a dialect policy
 
-> Change identifiers, placeholders, pagination, or cast targets at the rendering boundary without changing portable query construction.
+> Customize how Qubu renders SQL for your driver.
 
 Use `createDialect()` when the query is portable but the driver changes
 identifiers, placeholders, or pagination:

package/docs/guides/extensions/overview.md

@@ -1,6 +1,6 @@
 # Extend Qubu
 
-> Choose an extension boundary when the built-in API does not cover a driver-specific or uncommon SQL feature.
+> Add SQL features that Qubu’s built-in helpers do not cover.
 
 Qubu extensions are values that render SQL and carry the metadata later
 composition needs. Choose the page that matches the thing you are adding:

package/docs/guides/extensions/sources-and-clauses.md

@@ -1,6 +1,6 @@
 # Add sources and clauses
 
-> Publish a custom SQL clause or relation while preserving parameter order and source-scope checks.
+> Add a SQL clause or table-like source that works with Qubu’s query checks.
 
 ## Add a custom clause
 
@@ -67,9 +67,13 @@ render(query)
 ```
 
 `identity` is the source-scope key; `reference` is the SQL qualifier used by
-the generated columns. A nullable column remains nullable intrinsically, and a
+the generated columns.
+
+A nullable column remains nullable, and a
 `leftJoin(rows, ...)` adds outer-join nullability to every selected row
-column. Render the complete relation in the producer and bind values with
+column.
+
+Render the complete relation in the producer and bind values with
 `context.parameter()`; the normal renderer preserves parameter order.
 
 ## Read next

package/docs/guides/extensions/typed-expressions.md

@@ -1,6 +1,6 @@
 # Add typed expressions
 
-> Extend Qubu with expressions that retain source, nullability, result, and SQL-domain metadata.
+> Build custom expressions that preserve result types and query checks.
 
 ## Build expressions from public helpers
 
@@ -47,13 +47,21 @@ const nameAsCitext = cast(users.name, citext)
 ```
 
 The first three `column` type arguments are output, insert, and update values;
-the fourth is the SQL domain. The `text` equality and ordering groups make the
-custom domain compatible with `SqlText`. Use a distinct group when cross-type
-comparison is not portable. `castType` also makes this definition a cast
-target; its SQL text is emitted verbatim, so keep it in trusted extension code.
+the fourth is the SQL domain.
+
+The `text` equality and ordering groups make the custom domain compatible with `SqlText`. Use a distinct group when cross-type
+comparison is not portable.
+
+### Use the definition as a cast target
+
+`castType` also makes this definition a cast target. Its SQL text is emitted
+unchanged, so keep it in trusted extension code.
+
 Definitions with schema flags are not accepted as cast targets because cast
 nullability comes from the operand and write flags have no cast meaning.
 
+### Type individual expressions
+
 Declare result domains at other extension boundaries too:
 
 ```ts
@@ -66,13 +74,17 @@ const rawNameAsText = typedCast<string, SqlText>()(users.name, "TEXT")
 const generated = unsafeExpression<string, SqlText>("custom_text()")
 ```
 
-`typedCall()` preserves source requirements from its arguments. `typedCast()`
-is the fallback when no reusable definition describes the target. It preserves
-operand nullability and source metadata while emitting its supplied type name
-verbatim. `typedValue()` binds a parameter and declares its runtime SQL domain
-for the adapter; it does not select a JavaScript result decoder. Schema columns
-carry result-decoder metadata separately. `unsafeExpression()` emits its string
-unchanged and should remain a last resort.
+Choose the helper for the operation:
+
+- `typedCall()` preserves source requirements from its arguments.
+- `typedCast()` supplies a cast target when no reusable definition describes
+  it. It preserves operand nullability and source metadata, and emits the
+  supplied type name unchanged.
+- `typedValue()` binds a parameter and declares its runtime SQL domain for
+  the adapter. It does not choose a JavaScript result decoder; schema columns
+  carry decoder metadata separately.
+- `unsafeExpression()` emits its string unchanged. Use it only when the other
+  helpers cannot express the syntax.
 
 The lower-level forms also expose the SQL domain in their generic lists:
 `call<Output, Name, Arguments, NullableFrom, SqlType>()` and
@@ -80,7 +92,7 @@ The lower-level forms also expose the SQL domain in their generic lists:
 argument or nullability types in its own generic signature.
 
 Untyped `column()`, `value()`, `call()`, and custom expressions use
-`SqlUnknown`, which stays permissive for backward compatibility. Declaring a
+`SqlUnknown`, which allows composition without SQL-domain checks. Declaring a
 known domain opts the extension into incompatible-operation errors. See
 [SQL semantic types](../../sql-semantic-types.md) for the capability model and
 its limits.

package/docs/guides/extensions/unsafe-syntax.md

@@ -14,12 +14,16 @@ const query = select({
 })
 ```
 
-Keep raw identifiers and values out of the string. Prefer a typed custom
-fragment when the syntax will be reused. Use the [`sql` template
-tag](../sql-templates.md) when fixed trusted syntax needs bound runtime values
-or existing Qubu fragments. Keep dynamic SQL text on `unsafeExpression()` and
-runtime identifiers on `identifier()` or `qualifiedIdentifier()` from
-`qubu/core`.
+## Choose the right helper
+
+Keep raw identifiers and values out of the string:
+
+- Use a typed custom fragment for syntax you will reuse.
+- Use the [`sql` template tag](../sql-templates.md) for fixed trusted syntax
+  with bound values or existing Qubu fragments.
+- Use `unsafeExpression()` for trusted dynamic SQL text.
+- Use `identifier()` or `qualifiedIdentifier()` from `qubu/core` for runtime
+  identifiers.
 
 Read [Dialects and execution](../../dialects-and-execution.md) for the boundary
 between rendering and driver behavior. Read [Add typed

package/docs/guides/json.md

@@ -2,7 +2,9 @@
 
 > Build inferred nested results, or read scalar values from stored JSON documents.
 
-Use jsonArrayFrom() to nest a query's rows and jsonObjectFrom() for a query
+## Nest query results
+
+Use `jsonArrayFrom()` to nest a query's rows and `jsonObjectFrom()` for a query
 proven to return at most one row. Both preserve filtering, correlation,
 ordering, and pagination:
 
@@ -57,45 +59,63 @@ const query = select(
 //        latestPost: { title: string } | null }
 ```
 
-Execute the query through a Qubu adapter to decode nested results. An empty
-array query returns []; an empty object query returns null. A source-free
-query proven to return exactly one row produces a non-null object type.
-Object queries need Qubu's cardinality proof: an unconditional fetchFirst(1)
-or fetchFirst(0) establishes the bound. A conditional limit does not.
+### Empty results and row limits
+
+Execute the query through a Qubu adapter to decode nested results:
+
+- An empty array query returns `[]`.
+- An empty object query returns `null`.
+- A source-free query proven to return exactly one row produces a non-null object.
 
-The helpers compose inside further select() projections, so nesting can
-continue without result-type assertions. correlate() and the outer query's
-FROM/JOIN scope remain checked at every level.
+An object query must be known to return at most one row. An unconditional
+`fetchFirst(1)` or `fetchFirst(0)` proves that limit; a conditional limit does not.
 
-### Preserve ordering and logical values
+The helpers compose inside further `select()` projections, so nesting can
+continue without result-type assertions. `correlate()` and the outer query's
+`FROM/JOIN` scope remain checked at every level.
 
-Nested arrays retain explicit ORDER BY and pagination. Tied sort keys retain
+### Preserve ordering
+
+Nested arrays retain explicit `ORDER BY` and pagination. Tied sort keys retain
 SQL's unspecified tie order; add a unique tie-breaker when order matters.
-DISTINCT ordering must use the same expressions as the selection. Without an
-ORDER BY, array order is unspecified.
+`DISTINCT` ordering must use the same expressions as the selection. Without an
+`ORDER BY`, array order is unspecified.
+
+### Supported databases
 
 Nested results support PostgreSQL, MySQL 8.0.21+, and SQLite 3.45+. Other
 dialects fail during rendering. SQLite's minimum includes the JSON aggregate
 ordering fix needed to retain object values.
 
+### Decode nested values
+
 Built-in column domains decode to their declared types, including bigint,
-Uint8Array, Date, boolean, and nested JSON. Qubu transports precision-sensitive
+`Uint8Array`, `Date`, boolean, and nested JSON. Qubu transports precision-sensitive
 values as text and rejects numbers that lose significant decimal digits or
 exceed JavaScript's safe integer range. Use bigint columns for exact large
-integers. Unknown or custom SQL domains need a supported explicit cast, for
-example cast(value(7), integer()); declaring a TypeScript result alone does
+integers.
+
+Unknown or custom SQL domains need a supported explicit cast, for
+example `cast(value(7), integer())`; declaring a TypeScript result alone does
 not provide runtime decoding information.
 
-Custom mapResult() and column decoders receive the JSON transport value as
-unknown: bigint and decimal strings, hexadecimal binary strings, serialized
-JSON strings, or ordinary JSON scalar values. They own conversion to their
-advertised application type. Adapter-wide decoders do not run inside nested
-objects. Keep arbitrary stored JSON within JavaScript's numeric precision;
+Custom `mapResult()` and column decoders receive the JSON transport value as
+`unknown`. The value may be:
+
+- A bigint or decimal string.
+- A hexadecimal binary string.
+- A serialized JSON string.
+- An ordinary JSON scalar.
+
+The custom decoder converts it to the declared application type. Adapter-wide
+decoders do not run inside nested objects.
+
+Keep arbitrary stored JSON within JavaScript’s numeric precision;
 unsupported numeric representations fail instead of silently rounding.
 
 ## Read stored JSON scalars
 
-Use a structured jsonPath() when a query needs a scalar or an existence check
+Use a structured `jsonPath()` when a query needs a scalar or an existence check
 inside a JSON document:
 
 ```ts
@@ -135,7 +155,7 @@ interpolating caller-provided SQL.
 ## Understand missing values
 
 Scalar reads return SQL NULL when the path is missing, contains JSON null, or
-resolves to another JSON scalar type. jsonExists() returns true for a present
+resolves to another JSON scalar type. `jsonExists()` returns true for a present
 JSON null, false for a missing path, and false when the document itself is SQL
 NULL.
 
@@ -143,16 +163,21 @@ These rules keep path existence separate from extraction nullability.
 
 ## Check dialect support
 
-The standard dialect emits SQL/JSON JSON_VALUE and JSON_EXISTS syntax.
+The standard dialect emits SQL/JSON `JSON_VALUE` and `JSON_EXISTS` syntax.
 PostgreSQL, MySQL, and SQLite use their native JSON policies. The current
 policies require PostgreSQL 12 or newer, MySQL 8.0.21 or newer, and SQLite JSON
 functions. An application-created dialect must provide a JSON renderer.
 
 ## Know the current limits
 
-JSON paths cover deterministic key and index traversal. Wildcards, filters,
-recursive descent, JSON-returning extraction, document mutation, and row
-expansion remain dialect-specific extensions.
+JSON paths follow explicit keys and indexes. These features require
+dialect-specific extensions:
+
+- Wildcards and filters.
+- Recursive descent.
+- Extraction that returns JSON.
+- Document mutation.
+- Row expansion.
 
 For the SQL domain and nullability rules behind JSON columns, read
 [SQL semantic types](../sql-semantic-types.md).

package/docs/guides/mutations.md

@@ -1,6 +1,6 @@
 # Write mutations
 
-> Build typed `INSERT`, `UPDATE`, and `DELETE` statements from the same table metadata while keeping destructive operations explicit.
+> Insert, update, and delete rows with typed inputs and explicit safeguards.
 
 ## Define write-time rules
 
@@ -121,6 +121,8 @@ const query = update(
 The assignment expression is source-aware, so a column from an unrelated table
 cannot silently enter the update.
 
+### Update from another source
+
 PostgreSQL updates can introduce one or more typed sources with `updateFrom()`.
 Those sources are available to assignments, the predicate, and `RETURNING`:
 
@@ -153,6 +155,8 @@ with the default, SQLite, or MySQL dialect is rejected. Qubu still requires a
 predicate or an explicit `allowAll()` marker; introducing a source does not
 authorize an unrestricted update.
 
+### Omit an assignment at runtime
+
 Use `omit` for a runtime-conditional assignment. Qubu removes omitted fields
 before validating and rendering the effective assignment set:
 
@@ -171,7 +175,9 @@ const query = update(
 
 `omit` means that the column is absent from `SET`. It is distinct from `null`
 and explicit `undefined`, which remain bound assignment values, and it does not
-emit SQL `DEFAULT`. At least one assignment must remain; `update()` throws
+emit SQL `DEFAULT`.
+
+At least one assignment must remain; `update()` throws
 before rendering when every field is omitted. Possible expression branches
 remain source- and capability-aware even when their runtime alternative is
 `omit`.
@@ -237,11 +243,14 @@ unrestricted operation is intended.
 
 ## Return typed rows
 
-`returning()` uses the same named object projection as `SELECT`. Reserve
-`{ ...all(table) }` for the intentional contract of returning every table
-column. When present, the mutation's `row` type is inferred from that projection, so
+`returning()` uses the same named object projection as `SELECT`. Use
+`{ ...all(table) }` when you want every table column.
+
+The mutation’s `row` type is inferred from that projection, so
 `(await db.execute(query)).rows` has the same shape as a read query when `db`
-comes from `qubu(adapter)`. The projection's SQL semantic domains are
+comes from `qubu(adapter)`.
+
+The projection’s SQL semantic domains are
 retained too, so a returned query used by typed composition does not collapse
 UUID, text, numeric, or other known fields to their JavaScript types alone.
 

package/docs/guides/select/conditions.md

@@ -1,7 +1,6 @@
 # Add optional conditions
 
-> Keep optional predicates, null checks, and empty-list behavior explicit while
-> the query keeps the same structural shape.
+> Add or omit conditions at runtime, and handle NULL values and empty lists.
 
 The examples use the `users` table from [Build a `SELECT`](overview.md).
 
@@ -65,15 +64,23 @@ Here `omit` affects only whether `email` belongs to the projection. It does
 not make the expression nullable: a non-nullable expression would produce
 `email?: string`, while this nullable column produces `email?: string | null`.
 
-This support is specific to boolean operand lists, query-level ordering terms,
-and the complete clauses named above. Generic `sequence()` and
-`commaSeparated()` collections do not discard `omit`. Clauses that provide
-sources or change structural guarantees cannot be conditional. Pagination is
-the exception: `offset()`, `fetchFirst()`, and `fetchNext()` can be paired
-with `omit`, but a conditional row bound keeps the query's inferred
-cardinality at `many`. Qubu still rejects `omit` branches paired with
-`from()`, joins, `groupBy()`, correlation, CTEs, or custom clauses. Build
-separate queries when those structural parts differ at runtime.
+### Where omission is supported
+
+Use `omit` in the clauses and expression lists shown above. Generic
+`sequence()` and `commaSeparated()` collections do not discard it.
+
+Pagination also supports `omit`: pair it with `offset()`, `fetchFirst()`, or
+`fetchNext()`. A conditional limit keeps the inferred cardinality at `many`
+because the limit may be absent.
+
+Build separate queries when any of these parts differ at runtime. They cannot
+be paired with `omit`:
+
+- `from()` or joins.
+- `groupBy()`.
+- Correlation.
+- CTEs.
+- Custom clauses.
 
 ## Handle `NULL` and empty lists deliberately
 

package/docs/guides/select/grouping-and-windows.md

@@ -1,6 +1,6 @@
 # Group and rank rows
 
-> Use aggregates, grouping, and window expressions while preserving the dependencies and result types that make each expression valid.
+> Summarize rows with aggregates and rank them with window functions.
 
 The examples use the `users` and `posts` tables from [Build a
 `SELECT`](overview.md).
@@ -28,6 +28,7 @@ const counts = select(
 
 `users.name` is grouped, while `posts.id` is consumed by `COUNT()`. The
 same dependency rule applies to `HAVING` and grouped `ORDER BY` expressions.
+
 A projection such as `{ email: users.email, postCount: count(posts.id) }` is
 rejected unless `users.email` is grouped or is functionally determined by a
 grouped primary or unique key declared in the table schema. Qubu uses only
@@ -58,7 +59,9 @@ const rankedUsers = select(
 Window expressions remain ordinary expressions. They can be projected, aliased,
 and passed to `orderBy()`. Their source requirements and result types are
 retained through `over()`, and values rendered inside the window
-specification remain parameters. Named windows and frame clauses are outside
+specification remain parameters.
+
+Named windows and frame clauses are outside
 the initial inline scope.
 
 ## Read next

package/docs/guides/select/ordering-and-pagination.md

@@ -1,6 +1,6 @@
 # Order and paginate
 
-> Choose a stable order and apply optional row limits while keeping SQL clause order and query cardinality visible.
+> Sort results and limit the rows a query returns.
 
 The examples use the `users` table from [Build a `SELECT`](overview.md).
 
@@ -34,10 +34,12 @@ const page = select(
 )
 ```
 
-The rendered clause order is still `FROM`, `WHERE`, `ORDER BY`, and
-pagination. The active dialect decides whether pagination uses standard
+The rendered clauses follow SQL order: `FROM` comes before `WHERE`, followed
+by `ORDER BY` and pagination. The active dialect decides whether pagination uses standard
 `FETCH` syntax or a driver-specific `LIMIT` form.
 
+### Make the limit optional
+
 Pair a pagination clause with `omit` when the row bound is optional at runtime:
 
 ```ts

package/docs/guides/select/overview.md

@@ -1,6 +1,6 @@
 # Build a `SELECT`
 
-> Build a `SELECT` from typed tables, then inspect its sources, projection, joins, and result row.
+> Choose fields, add a source, and join tables to build a typed SELECT query.
 
 ## Start with a projection and a source
 
@@ -24,8 +24,7 @@ render(query).text
 ```
 
 An object projection uses its keys as result names. Name the fields you intend
-to return in the usual case. Reserve `all(source)` for a result contract that
-intentionally returns every source column. It returns the source's columns as a
+to return in the usual case. Use `all(source)` when you want every source column. It returns the source's columns as a
 named projection object, so it can still be spread alongside computed
 expressions:
 
@@ -79,6 +78,8 @@ Use `innerJoin`, `leftJoin`, `rightJoin`, or `fullJoin` with an `ON`
 condition. `crossJoin` and `naturalJoin` add a source without a condition;
 use them only when that SQL behavior is intentional.
 
+### Handle missing joined rows
+
 `leftJoin()` also carries nullability into the selected row. A column from the
 joined source is nullable because the row may be missing, while an expression
 with a deliberately non-nullable result such as `count()` remains non-null:
@@ -98,6 +99,8 @@ const summary = select(
 // { userName: string; postTitle: string | null; postCount: number }
 ```
 
+### Add conditions
+
 Compose boolean expressions explicitly:
 
 ```ts