qubu 0.0.0 → 0.3.4

package/docs/guides/json.md

@@ -0,0 +1,65 @@
+# Read JSON scalars
+
+> Extract a string, number, or boolean from a JSON column without writing a raw SQL path.
+
+Use a structured jsonPath() when a query needs a scalar or an existence check
+inside a JSON document:
+
+```ts
+import {
+  from,
+  json,
+  jsonBoolean,
+  jsonExists,
+  jsonNumber,
+  jsonPath,
+  jsonText,
+  select,
+  table,
+} from 'qubu'
+
+const events = table('events', {
+  payload: json<{
+    user?: { name?: string; active?: boolean; score?: number }
+  }>(),
+})
+
+const query = select(
+  {
+    name: jsonText(events.payload, jsonPath('user', 'name')),
+    active: jsonBoolean(events.payload, jsonPath('user', 'active')),
+    score: jsonNumber(events.payload, jsonPath('user', 'score')),
+    hasUser: jsonExists(events.payload, jsonPath('user')),
+  },
+  from(events)
+)
+```
+
+Strings are object keys. Non-negative integers are array indexes. Qubu keeps the
+path structured so a dialect can encode each key and index without
+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
+JSON null, false for a missing path, and false when the document itself is SQL
+NULL.
+
+These rules keep path existence separate from extraction nullability.
+
+## Check dialect support
+
+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.
+
+For the SQL domain and nullability rules behind JSON columns, read
+[SQL semantic types](../sql-semantic-types.md).

package/docs/guides/mutations.md

@@ -0,0 +1,138 @@
+# Write mutations
+
+> Build typed `INSERT`, `UPDATE`, and `DELETE` statements from the same table metadata while keeping destructive operations explicit.
+
+## Define write-time rules
+
+Generated and default columns affect which input fields are required. Nullable
+columns accept `null` as a value, which is distinct from omitting a defaulted
+field:
+
+```ts
+import { integer, table, text } from 'qubu'
+
+const users = table('users', {
+  id: integer({ generated: true }),
+  name: text(),
+  email: text({ nullable: true, hasDefault: true }),
+})
+```
+
+The generated `id` is omitted from inserts and updates. `email` is optional on
+insert, but `{ email: null }` explicitly writes `NULL` when supplied.
+
+## Insert rows
+
+Pass one or more rows to `values()`. Qubu checks that every row uses the same
+columns and that required, non-generated fields are present:
+
+```ts
+import { insertInto, render, returning, values } from 'qubu'
+
+const query = insertInto(
+  users,
+  values(
+    { name: 'Ada', email: null },
+    { name: 'Grace', email: 'grace@example.com' }
+  ),
+  returning({ id: users.id, name: users.name })
+)
+
+render(query)
+// {
+//   text: 'INSERT INTO "users" ("name", "email") VALUES (?, ?), (?, ?) RETURNING "users"."id" AS "id", "users"."name" AS "name"',
+//   parameters: ['Ada', null, 'Grace', 'grace@example.com'],
+// }
+```
+
+Use `defaultValues()` only when every non-generated column has a database
+default. Use `insertSelect(query, columns)` for an `INSERT ... SELECT` source.
+
+## Update with a predicate
+
+`UPDATE` assignments accept either application values or expressions built from
+the target table:
+
+```ts
+import { eq, returning, update, upper, where } from 'qubu'
+
+const query = update(
+  users,
+  { name: upper(users.name) },
+  where(eq(users.id, 7)),
+  returning({ id: users.id, name: users.name })
+)
+```
+
+The assignment expression is source-aware, so a column from an unrelated table
+cannot silently enter the update.
+
+Use `omit` for a runtime-conditional assignment. Qubu removes omitted fields
+before validating and rendering the effective assignment set:
+
+```ts
+import { eq, omit, update, where } from 'qubu'
+
+const query = update(
+  users,
+  {
+    name: rename ? 'Archived' : omit,
+    email: clearEmail ? null : omit,
+  },
+  where(eq(users.id, 7))
+)
+```
+
+`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
+before rendering when every field is omitted. Possible expression branches
+remain source- and capability-aware even when their runtime alternative is
+`omit`.
+
+## Delete with a predicate
+
+```ts
+import { deleteFrom, eq, returning, where } from 'qubu'
+
+const query = deleteFrom(
+  users,
+  where(eq(users.id, 8)),
+  returning({ id: users.id })
+)
+```
+
+## Keep unrestricted writes explicit
+
+Both `UPDATE` and `DELETE` require a `WHERE` clause by default. If an operation
+really must affect every row, opt in at the call site:
+
+```ts
+import { allowAll, update } from 'qubu'
+
+const query = update(users, { name: 'Archived' }, allowAll())
+```
+
+`allowAll()` is a safety boundary, not a replacement for authorization or
+application-level confirmation. Keep it close to the code that proves the
+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
+`(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
+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.
+
+`db.execute()` and the standalone `execute()` function also return optional
+`affectedRows`, `changedRows`, and `insertId` facts supplied by the adapter. Use
+`db.rows()` or `executeRows()` when only the returned rows matter. The
+[execution guide](../dialects-and-execution.md) defines which driver facts
+belong in each field.
+
+See [Column behavior and write types](../schema/columns-and-writes.md)
+for custom output, insert, and update types, then [Dialects and execution](../dialects-and-execution.md)
+for the driver boundary.

package/docs/guides/select/conditions.md

@@ -0,0 +1,110 @@
+# Add optional conditions
+
+> Keep optional predicates, null checks, and empty-list behavior explicit while
+> the query keeps the same structural shape.
+
+The examples use the `users` table from [Build a `SELECT`](overview.md).
+
+## Omit query parts conditionally
+
+Use `omit` as the other branch of a JavaScript conditional when a `WHERE`,
+`HAVING`, `ORDER BY`, or `DISTINCT` clause is optional:
+
+```ts
+import { eq, from, omit, select, where } from 'qubu'
+
+declare const userId: number | undefined
+
+const query = select(
+  { id: users.id, name: users.name },
+  from(users),
+  userId === undefined ? omit : where(eq(users.id, userId))
+)
+```
+
+The ordinary ternary narrows `userId`, and the unused clause is never built.
+Qubu removes `omit` before validating and ordering the remaining clauses.
+
+Use the same token inside `and()`, `or()`, and `orderBy()` when individual
+predicates or ordering terms are conditional:
+
+```ts
+import { and, desc, eq, omit, orderBy, where } from 'qubu'
+
+declare const includeName: boolean
+declare const newestFirst: boolean
+
+const filter = where(
+  and(eq(users.id, 7), includeName ? eq(users.name, 'Ada') : omit)
+)
+const ordering = orderBy(newestFirst ? desc(users.name) : omit)
+```
+
+Each helper removes omitted members while retaining the source and grouping
+requirements of every member that may be present. If no predicate remains,
+`and()` or `or()` propagates `omit` through `where()` or `having()`; if no
+ordering term remains, `orderBy()` propagates `omit` directly. The resulting
+query emits no empty clause.
+
+The same token can conditionally include a projection field:
+
+```ts
+declare const includeEmail: boolean
+
+const query = select(
+  {
+    id: users.id,
+    email: includeEmail ? users.email : omit,
+  },
+  from(users)
+)
+
+// typeof query.row:
+// { id: number; email?: string | null }
+```
+
+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.
+
+## Handle `NULL` and empty lists deliberately
+
+Equality with `null` is translated to the SQL null predicate:
+
+```ts
+import { eq, isDistinctFrom, ne } from 'qubu'
+
+eq(users.name, null) // ... IS NULL
+ne(users.name, null) // ... IS NOT NULL
+isDistinctFrom(users.name, null) // ... IS DISTINCT FROM ?
+```
+
+Relational comparisons such as `gt(users.id, null)` are rejected because SQL
+does not give them ordinary boolean comparison semantics. Use `isNull`,
+`isNotNull`, or a distinctness predicate when that is the intended operation.
+
+Empty membership lists remain valid and portable:
+
+```ts
+inList(users.id, []) // (1 = 0)
+notIn(users.id, []) // (1 = 1)
+```
+
+## Read next
+
+- [Order and paginate](ordering-and-pagination.md) covers stable ordering and
+  optional row limits.
+- [Group and rank rows](grouping-and-windows.md) covers aggregates and window
+  expressions.
+- [Source scope](../../query-model/source-scope.md) explains why a column is
+  valid only after its source enters the query.

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

@@ -0,0 +1,82 @@
+# Group and rank rows
+
+> Use aggregates, grouping, and window expressions while preserving the dependencies and result types that make each expression valid.
+
+The examples use the `users` and `posts` tables from [Build a
+`SELECT`](overview.md).
+
+## Group and aggregate
+
+Object projection keys provide stable names for aggregates. Group every
+non-aggregate column dependency:
+
+```ts
+import {
+  count,
+  desc,
+  eq,
+  from,
+  groupBy,
+  gt,
+  having,
+  leftJoin,
+  orderBy,
+  select,
+} from 'qubu'
+
+const counts = select(
+  {
+    name: users.name,
+    postCount: count(posts.id),
+  },
+  from(users),
+  leftJoin(posts, eq(users.id, posts.authorId)),
+  groupBy(users.name),
+  having(gt(count(posts.id), 0)),
+  orderBy(desc(count(posts.id)))
+)
+```
+
+`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
+explicit key metadata and keeps the proof within the source boundary. See
+[Constraints, keys, and indexes](../../schema/constraints-and-indexes.md#use-key-metadata-for-grouped-queries).
+
+## Window functions
+
+Use `over()` to attach an inline window specification to a typed expression.
+The initial window scope supports `PARTITION BY` and `ORDER BY`; the same
+`asc()` and `desc()` terms used by a query-level `orderBy()` can be reused:
+
+```ts
+import { desc, from, over, rowNumber, select } from 'qubu'
+
+const rankedUsers = select(
+  {
+    id: users.id,
+    rowNumber: over(rowNumber(), {
+      partitionBy: [users.name],
+      orderBy: [desc(users.id)],
+    }),
+  },
+  from(users)
+)
+```
+
+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
+the initial inline scope.
+
+## Read next
+
+- [Order and paginate](ordering-and-pagination.md) covers stable ordering and
+  row limits.
+- [Compose queries](../compose-queries.md) covers CTEs, derived tables, scalar
+  subqueries, and set operations.
+- [Result shapes and cardinality](../../query-model/result-shapes.md) explains
+  the row and scalar types produced by nested queries.

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

@@ -0,0 +1,78 @@
+# Order and paginate
+
+> Choose a stable order and apply optional row limits while keeping SQL clause order and query cardinality visible.
+
+The examples use the `users` table from [Build a `SELECT`](overview.md).
+
+## Order rows
+
+Wrap ordering terms in `orderBy()`:
+
+```ts
+import { desc, from, orderBy, select } from 'qubu'
+
+const ordered = select(
+  { id: users.id, name: users.name },
+  from(users),
+  orderBy(desc(users.name))
+)
+```
+
+Use `asc()` or `desc()` for each term. The selected dialect controls the
+identifier quoting and any dialect-specific ordering syntax.
+
+## Paginate results
+
+Choose `fetchFirst()` or `offset()` for pagination:
+
+```ts
+import {
+  desc,
+  eq,
+  fetchFirst,
+  from,
+  offset,
+  orderBy,
+  select,
+  where,
+} from 'qubu'
+
+const page = select(
+  { id: users.id, name: users.name },
+  from(users),
+  where(eq(users.id, 7)),
+  orderBy(desc(users.name)),
+  offset(20),
+  fetchFirst(20)
+)
+```
+
+The rendered clause order is still `FROM`, `WHERE`, `ORDER BY`, and
+pagination. The active dialect decides whether pagination uses standard
+`FETCH` syntax or a driver-specific `LIMIT` form.
+
+Pair a pagination clause with `omit` when the row bound is optional at runtime:
+
+```ts
+import { fetchFirst, omit } from 'qubu'
+
+declare const pageSize: number | undefined
+
+const page = select(
+  { id: users.id, name: users.name },
+  from(users),
+  pageSize === undefined ? omit : fetchFirst(pageSize)
+)
+```
+
+When `pageSize` is undefined, the query emits no pagination. Because the row
+bound may be absent, conditional pagination does not narrow the query's
+cardinality. An unconditional `fetchFirst(1)` retains its existing
+`zero-or-one` inference.
+
+## Read next
+
+- [Add optional conditions](conditions.md) covers conditional clauses and
+  null-aware predicates.
+- [Group and rank rows](grouping-and-windows.md) covers aggregates and window
+  expressions.

package/docs/guides/select/overview.md

@@ -0,0 +1,139 @@
+# Build a `SELECT`
+
+> Build a `SELECT` from typed tables, then inspect its sources, projection, joins, and result row.
+
+## Start with a projection and a source
+
+The first argument to `select()` is the projection. The remaining arguments are
+independent clauses. A source-aware column must be provided by `from()` or a
+join:
+
+```ts
+import { eq, from, integer, render, select, table, text, where } from 'qubu'
+
+const users = table('users', {
+  id: integer(),
+  name: text(),
+  email: text({ nullable: true }),
+})
+
+const query = select(
+  { id: users.id, name: users.name },
+  from(users),
+  where(eq(users.id, 7))
+)
+
+render(query).text
+// SELECT "users"."id" AS "id", "users"."name" AS "name" FROM "users" WHERE ("users"."id" = ?)
+```
+
+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
+named projection object, so it can still be spread alongside computed
+expressions:
+
+```ts
+import { all, from, select, upper } from 'qubu'
+
+const query = select(
+  { ...all(users), normalizedName: upper(users.name) },
+  from(users)
+)
+```
+
+`all(source)` expands to explicit named columns rather than emitting
+`source.*`. That keeps the SQL output and the inferred row keys aligned.
+
+Named object projections keep the row shape visible at the selection site,
+which is useful when the result is consumed by application code.
+
+## Add joins and predicates
+
+Join functions add a source and make the join condition part of the same scope
+check as the projection and `WHERE` clause:
+
+```ts
+import {
+  count,
+  eq,
+  from,
+  innerJoin,
+  isNotNull,
+  leftJoin,
+  select,
+  table,
+  text,
+  integer,
+  where,
+} from 'qubu'
+
+const posts = table('posts', {
+  id: integer(),
+  authorId: integer(),
+  title: text(),
+})
+
+const query = select(
+  { userId: users.id, title: posts.title },
+  from(users),
+  innerJoin(posts, eq(users.id, posts.authorId)),
+  where(isNotNull(users.email))
+)
+```
+
+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.
+
+`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:
+
+```ts
+const summary = select(
+  {
+    userName: users.name,
+    postTitle: posts.title,
+    postCount: count(posts.id),
+  },
+  from(users),
+  leftJoin(posts, eq(users.id, posts.authorId))
+)
+
+// typeof summary.row:
+// { userName: string; postTitle: string | null; postCount: number }
+```
+
+Compose boolean expressions explicitly:
+
+```ts
+import { and, gt, inList, or } from 'qubu'
+
+const filter = and(
+  gt(users.id, 0),
+  or(inList(users.id, [7, 8]), eq(users.name, 'Ada'))
+)
+
+const filtered = select(
+  { id: users.id, name: users.name },
+  from(users),
+  where(filter)
+)
+```
+
+Values such as `7`, `'Ada'`, and list members become parameters. They are not
+interpolated into SQL.
+
+## Read next
+
+- [Add optional conditions](conditions.md) covers conditional clauses, null
+  checks, and empty membership lists.
+- [Order and paginate](ordering-and-pagination.md) covers stable ordering and
+  optional row limits.
+- [Group and rank rows](grouping-and-windows.md) covers aggregates and window
+  expressions.
+- [Source scope](../../query-model/source-scope.md) explains why each column
+  must come from a source in the query.
+- [Result shapes and cardinality](../../query-model/result-shapes.md) explains
+  how joins and nested queries affect row types.