qubu 0.6.1 → 0.6.3

package/docs/guides/json.md

@@ -1,8 +1,121 @@
-# Read JSON scalars
+# Query nested JSON
 
-> Extract a string, number, or boolean from a JSON column without writing a raw SQL path.
+> Build inferred nested results, or read scalar values from stored JSON documents.
 
-Use a structured jsonPath() when a query needs a scalar or an existence check
+## 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:
+
+```ts
+import {
+  correlate,
+  desc,
+  eq,
+  fetchFirst,
+  from,
+  integer,
+  jsonArrayFrom,
+  jsonObjectFrom,
+  orderBy,
+  select,
+  table,
+  text,
+  where,
+} from "qubu"
+
+const users = table("users", { id: integer(), name: text() })
+const posts = table("posts", {
+  id: integer(),
+  authorId: integer(),
+  title: text(),
+})
+const latestPosts = select(
+  { id: posts.id, title: posts.title },
+  from(posts),
+  correlate(users),
+  where(eq(posts.authorId, users.id)),
+  orderBy(desc(posts.id)),
+  fetchFirst(3),
+)
+const latestPost = select(
+  { title: posts.title },
+  from(posts),
+  correlate(users),
+  where(eq(posts.authorId, users.id)),
+  orderBy(desc(posts.id)),
+  fetchFirst(1),
+)
+const query = select(
+  {
+    name: users.name,
+    posts: jsonArrayFrom(latestPosts),
+    latestPost: jsonObjectFrom(latestPost),
+  },
+  from(users),
+)
+// Row: { name: string; posts: { id: number; title: string }[];
+//        latestPost: { title: string } | null }
+```
+
+### 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.
+
+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.
+
+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.
+
+### 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.
+
+### 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
+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
+not provide runtime decoding information.
+
+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
 inside a JSON document:
 
 ```ts
@@ -42,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.
 
@@ -50,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,11 +175,49 @@ 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`.
 
+## Update duplicate keys in MySQL
+
+Use `onDuplicateKeyUpdate()` from `qubu/mysql` to update a row when an insert
+conflicts with any primary or unique key. MySQL chooses the conflicting key;
+this clause has no conflict-target argument or `RETURNING` support.
+
+```ts
+import { insertInto, values } from "qubu"
+import { incoming, onDuplicateKeyUpdate } from "qubu/mysql"
+
+const proposed = incoming(users)
+const query = insertInto(
+  users,
+  values({ name: "Ada", email: "ada@example.com" }),
+  onDuplicateKeyUpdate(users, { name: proposed.name }),
+)
+await db.execute(query)
+```
+
+Declare a unique key on `email` in the database for this example. A duplicate
+email replaces the existing name with the proposed name. Assignments accept
+writable target columns, target-table expressions, `incoming(table)` columns,
+or `omit`. Raw values retain the target column's parameter encoder. At least
+one assignment must remain after omissions.
+
+Incoming references are available only inside the matching table's duplicate-key
+assignments. Qubu renders MySQL row aliases for `values()` and `defaultValues()`.
+For `insertSelect()`, it wraps the query in a derived projection and maps its
+fields positionally to the target-column list. Incoming references then cover
+only that list; referencing an omitted target column fails during rendering.
+This syntax requires MySQL 8.0.19 or later.
+
+The result retains mysql2's `affectedRows`, `changedRows`, and `insertId` metadata
+when supplied by the driver. These facts do not identify which branch ran for
+every row of a batch. Read rows with a separate query when needed.
+
 ## Delete with a predicate
 
 ```ts
@@ -201,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

package/docs/guides/sql-templates.md

@@ -1,6 +1,6 @@
 # Compose SQL templates
 
-> Use trusted SQL syntax with bound runtime values while retaining the Qubu metadata carried by interpolated expressions, fragments, and queries.
+> Write SQL templates that bind values safely and preserve type information from Qubu expressions.
 
 ## Bind every runtime value
 
@@ -108,10 +108,16 @@ reaches `unsafeExpression()`.
 
 ## Preserve metadata through interpolated fragments
 
-The tag inherits source dependencies, conservative outer-join nullability,
-grouping facts, aggregate and window state, subquery state, and dialect
-capability requirements from Qubu fragment substitutions. It does not infer
-those facts from unchecked template text.
+Qubu fragment substitutions pass these facts to the template:
+
+- Required sources.
+- Possible nulls from outer joins.
+- Grouping dependencies.
+- Aggregate and window state.
+- Subquery state.
+- Required dialect capabilities.
+
+Qubu does not infer these facts from template text.
 
 Use a built-in expression as the substitution when its semantics matter:
 

package/docs/guides/valtio-sync.md

@@ -102,11 +102,17 @@ const handlers = applyOpsWithQubu<SyncContext>({
 export const sync = valtioSync({ schema: { todos }, handlers })
 ```
 
-Authorization, conflict checks, the application mutation, and
-`syncEvents.write()` run in that order inside one Qubu transaction. If any step
-fails, the adapter rolls the transaction back. The event sequence becomes
-`serverVersion` unless the mutation handler returns an explicit version. Read
-handlers pass through unchanged.
+Each mutation runs these steps in one Qubu transaction:
+
+1. Check authorization.
+2. Check conflicts.
+3. Apply the application mutation.
+4. Write the sync event with `syncEvents.write()`.
+
+If any step fails, the adapter rolls the transaction back.
+
+The event sequence becomes `serverVersion` unless the mutation handler returns
+an explicit version. Read handlers pass through unchanged.
 
 The integration does not define persistence tables, import Drizzle, or execute
 driver APIs. The application owns table design, authorization, conflict policy,

package/docs/guides/vite-plugin.md

@@ -1,6 +1,6 @@
 # Vite compiler hint
 
-> Opt a JavaScript or TypeScript module into Qubu's ambient query API while keeping the transform limited to explicit directive-bearing files.
+> Use a "use qubu" directive to add the Qubu imports a module needs.
 
 The optional Vite plugin recognizes the `"use qubu"` directive and injects only
 the referenced named imports from the configured module.
@@ -33,7 +33,7 @@ ambient value and type declarations for the TypeScript compiler.
 
 ## Mark a module explicitly
 
-Put the directive in the module's initial directive prologue:
+Put the directive at the start of the module, alongside any other directives:
 
 ```ts
 "use qubu"

package/docs/index.md

@@ -1,11 +1,17 @@
 # Qubu
 
-> Build parameterized SQL from typed tables, expressions, and clauses.
+> Build SQL queries from typed tables and reusable values.
 
-Qubu builds SQL from values. Tables, expressions, clauses, and complete queries
-compose without a mutable query builder. TypeScript tracks selected row shapes,
-source scope, and nullability, while rendering returns SQL text and ordered
-parameters.
+Qubu builds SQL from reusable values. You can combine query parts without
+changing a shared query-builder object.
+
+TypeScript checks:
+
+- Which fields the query returns and their types.
+- Whether each column belongs to a source in the query.
+- Whether a result can be `null`.
+
+Render a query to inspect its SQL text and ordered parameters.
 
 The preferred source style names each projected field and writes the final
 `select()` clauses in SQL order. Clause values remain order-independent at
@@ -17,7 +23,7 @@ and placed in that final call where it reads best.
 If this is your first query, follow [Getting started](getting-started.md) to
 define a table, build a `SELECT`, and inspect its SQL and parameters.
 
-## Choose a task
+## Build and run queries
 
 - [Build a `SELECT`](guides/select/overview.md) with projections, joins,
   predicates, ordering, and grouping.
@@ -33,21 +39,21 @@ define a table, build a `SELECT`, and inspect its SQL and parameters.
   derivation and a native transactional database adapter.
 - [Extend Qubu](guides/extensions/overview.md) with a custom source, clause,
   dialect policy, or typed expression.
-- [Read JSON scalars](guides/json.md) from structured JSON paths.
+- [Query nested JSON](guides/json.md) or read scalars from structured paths.
 - [Enable the Vite compiler hint](guides/vite-plugin.md) when query modules
   should opt into named imports through a directive.
-- [Inspect an existing database](schema/introspection.md) through the optional
-  user-owned catalog boundary.
-- [Generate a schema module](schema/code-generation.md) from one complete,
-  non-lossy Snapshot v1 introspection result.
+
+## Work with schemas and migrations
+
+- [Inspect an existing database](schema/introspection.md) using a connection you provide.
+- [Generate a schema module](schema/code-generation.md) from an introspection result without losing schema facts.
 - [Compare snapshots](schema/diff.md) with explicit rename hints and reviewable
   safety diagnostics.
 - [Build migration plans](schema/migration-plans.md) as reviewed, deterministic
   data before DDL emission.
 - [Emit DDL](schema/ddl-emission.md) from an approved migration plan without
   handing Qubu a database connection.
-- [Operate migrations](migrations/index.md) with versioned artifacts, verified
-  adapter profiles, baselines, a portable executor, and explicit recovery.
+- [Operate migrations](migrations/index.md) with reviewed migration files and a verified adapter.
 
 ## The query pipeline
 
@@ -106,8 +112,9 @@ render(query)
 The inferred row is `{ id: number; name: string }`. The value `7` stays out
 of the SQL text and appears in the `parameters` array in placeholder order.
 
-The [supported features](reference/supported-surface.md) page is the canonical
-package-entrypoint and ownership map. Applications may use Qubu's portable
-migration executor while retaining credentials, approval policy, custom SQL,
-and deployment lifecycle ownership. [Troubleshooting](troubleshooting.md)
-starts from common errors and points to the concept page behind each one.
+## Find support details
+
+- [Supported features](reference/supported-surface.md) lists package imports and
+  explains which responsibilities stay with your application.
+- [Troubleshooting](troubleshooting.md) starts from common errors and explains
+  how to fix them.