qubu 0.0.0 → 0.3.3

package/docs/guides/sql-templates.md

@@ -0,0 +1,157 @@
+# Compose SQL templates
+
+> Use trusted SQL syntax with bound runtime values while retaining the Qubu metadata carried by interpolated expressions, fragments, and queries.
+
+## Bind every runtime value
+
+The `sql` tag treats template text as SQL syntax and every ordinary
+substitution as a parameter. This includes strings, numbers, objects, arrays,
+and `null`:
+
+```ts
+import { integer, render, sql, table, text } from 'qubu'
+
+const users = table('users', { name: text() })
+const posts = table('posts', { id: integer() })
+const search = 'Ada%'
+const predicate = sql`${users.name} LIKE ${search}`
+
+render(predicate)
+// {
+//   text: '"users"."name" LIKE ?',
+//   parameters: ['Ada%'],
+// }
+```
+
+`${users.name}` is a Qubu expression, so the tag renders its quoted column
+reference. `${search}` is an ordinary value, so it cannot become SQL text.
+
+## Compose expressions, templates, and queries
+
+Fragment substitutions use the same rendering context as the enclosing
+statement. Parameters keep one placeholder sequence across nested templates
+and queries:
+
+```ts
+import { eq, from, render, select, sql, where } from 'qubu'
+import { postgresDialect } from 'qubu/postgres'
+
+const selectedNames = select(
+  { displayName: users.name },
+  from(users),
+  where(eq(users.name, 'Ada'))
+)
+
+const exists = sql`EXISTS (${selectedNames}) AND ${users.name} <> ${'root'}`
+
+render(exists, postgresDialect())
+// {
+//   text: 'EXISTS (SELECT "users"."name" AS "display_name" FROM "users" WHERE ("users"."name" = $1)) AND "users"."name" <> $2',
+//   parameters: ['Ada', 'root'],
+// }
+```
+
+The template owns punctuation such as the parentheses around the query. Qubu
+renders a query substitution with SQL-facing projection names, as it does for
+CTEs and scalar subqueries.
+
+## Declare a result domain
+
+An unannotated template has application output `unknown` and SQL domain
+`SqlUnknown`. State both facts when the expression feeds typed operations or a
+named projection:
+
+```ts
+import { from, select, sql } from 'qubu'
+import type { SqlText } from 'qubu'
+
+const normalizedName = sql.type<string, SqlText>()`LOWER(${users.name})`
+
+const query = select({ name: normalizedName }, from(users))
+// typeof query.row is { name: string }
+```
+
+`sql.type<Output, SqlType>()` changes only TypeScript metadata. It does not
+parse the SQL or validate the declared types against the database. The tag
+still binds ordinary substitutions.
+
+Interpolated fragments contribute their source requirements and
+nullability. For example, a `sql.type<string, SqlText>()` template containing a
+column from the right side of a `leftJoin()` produces `string | null` in the
+selected row.
+
+## Keep identifiers and dynamic syntax explicit
+
+Use the substitution kind that matches the value:
+
+| Input                                 | Rendering behavior                                            |
+| ------------------------------------- | ------------------------------------------------------------- |
+| Fixed template text                   | Trusted SQL syntax, appended unchanged                        |
+| An ordinary substitution              | Bound parameter                                               |
+| A Qubu expression, query, or fragment | Rendered through the current dialect and placeholder sequence |
+| `identifier(name)`                    | One dialect-quoted identifier                                 |
+| `qualifiedIdentifier(schema, table)`  | Several dialect-quoted identifier parts                       |
+| `unsafeExpression(text)`              | Unchecked SQL text                                            |
+
+Do not use a dotted string as an identifier. Pass each part to
+`qualifiedIdentifier()`. Keep `unsafeExpression()` for application-controlled
+syntax that cannot use a fixed template segment:
+
+```ts
+import { sql } from 'qubu'
+import { identifier, unsafeExpression } from 'qubu/core'
+
+const sortColumn = 'display_name'
+const direction = 'DESC' as const
+
+const ordering = sql`ORDER BY ${identifier(sortColumn)} ${unsafeExpression(direction)}`
+```
+
+Validate any dynamic syntax against an application-owned allowlist before it
+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.
+
+Use a built-in expression as the substitution when its semantics matter:
+
+```ts
+import { count, sql } from 'qubu'
+import type { SqlInteger } from 'qubu'
+
+const postCount = sql.type<number, SqlInteger>()`${count(posts.id)}`
+```
+
+This wrapper retains the aggregate dependency recorded by `count()`. Writing
+the aggregate name in template text would not record that fact:
+
+```ts
+const untrackedPostCount = sql.type<number, SqlInteger>()`COUNT(${posts.id})`
+```
+
+This renders valid SQL, but Qubu sees an ordinary column dependency because it
+does not parse `COUNT` from the template text.
+
+Declare a capability when the template text itself uses dialect-specific
+syntax:
+
+```ts
+import { sql } from 'qubu'
+import { withDialectCapability } from 'qubu/core'
+import type { SqlBoolean } from 'qubu'
+
+const postgresMatch = withDialectCapability(
+  sql.type<boolean, SqlBoolean>()`${users.name} ILIKE ${search}`,
+  'ilike'
+)
+```
+
+Rendering `postgresMatch` now requires a dialect that advertises `ilike`.
+
+Use [Fragments and metadata](../query-model/fragments.md) for the inherited
+facts, and [SQL semantic types](../sql-semantic-types.md) for result-domain
+compatibility.

package/docs/guides/vite-plugin.md

@@ -0,0 +1,92 @@
+# 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.
+
+The optional Vite plugin recognizes the `"use qubu"` directive and injects only
+the referenced named imports from the configured module.
+
+## Install the plugin
+
+Add the plugin to Vite and add the matching ambient declarations to TypeScript:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { qubu } from 'qubu/vite'
+
+export default defineConfig({
+  plugins: [qubu()],
+})
+```
+
+```jsonc
+{
+  "compilerOptions": {
+    // Merge this with any existing project-specific entries.
+    "types": ["qubu/globals"],
+  },
+}
+```
+
+The plugin supplies runtime imports. `qubu/globals` supplies the corresponding
+ambient value and type declarations for the TypeScript compiler.
+
+## Mark a module explicitly
+
+Put the directive in the module's initial directive prologue:
+
+```ts
+'use qubu'
+
+const users = table('users', {
+  id: integer(),
+  name: text(),
+})
+
+const query = select(
+  { id: users.id, name: users.name },
+  from(users),
+  where(eq(users.id, 42))
+)
+```
+
+Conceptually, the transform adds the imports that this module references:
+
+```ts
+import { eq, from, integer, select, table, text, where } from 'qubu'
+```
+
+Existing imports remain valid. The transform does not rewrite member properties,
+strings, comments, or names outside the public Qubu global catalog.
+
+## Configure the transform
+
+```ts
+qubu({
+  module: 'qubu',
+  include: id => id.includes('/src/'),
+  exclude: /\.stories\./,
+  globals: ['select', 'from', 'where', 'eq', 'table'],
+})
+```
+
+| Option    | Effect                                  | Default               |
+| --------- | --------------------------------------- | --------------------- |
+| `module`  | Import source for injected names        | `'qubu'`              |
+| `include` | Restrict matching module IDs            | no filter             |
+| `exclude` | Skip matching module IDs                | no filter             |
+| `globals` | Narrow the names eligible for injection | Qubu's public catalog |
+
+## Know the boundaries
+
+- Only JavaScript and TypeScript script extensions are considered.
+- Files under `node_modules` are skipped.
+- `include` and `exclude` filters run against the module ID.
+- A module without the directive is unchanged.
+- A module that references no eligible Qubu global is unchanged.
+- Normal ES module imports remain the explicit fallback when the hint is not a
+  good fit.
+
+The plugin has no runtime dependency on Vite; it returns the small transform
+shape Vite expects. Use the package root directly when you want ordinary import
+semantics everywhere.

package/docs/index.md

@@ -0,0 +1,111 @@
+# Qubu
+
+> Build parameterized SQL from typed tables, expressions, and clauses.
+
+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.
+
+The preferred source style names each projected field and writes the final
+`select()` clauses in SQL order. Clause values remain order-independent at
+runtime, so a reusable `where()` or `orderBy()` fragment can be built earlier
+and placed in that final call where it reads best.
+
+## Start here
+
+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 a `SELECT`](guides/select/overview.md) with projections, joins,
+  predicates, ordering, and grouping.
+- [Compose queries](guides/compose-queries.md) with CTEs, derived tables,
+  subqueries, and set operations.
+- [Compose SQL templates](guides/sql-templates.md) for trusted syntax with
+  bound values and metadata-preserving fragment substitutions.
+- [Write mutations](guides/mutations.md) with typed `INSERT`, `UPDATE`, and
+  `DELETE` statements.
+- [Use Qubu tables with Drizzle](guides/drizzle.md) while moving query call
+  sites without duplicating schema declarations.
+- [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.
+- [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.
+- [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.
+
+## The query pipeline
+
+The same query value can be rendered for inspection or passed to an adapter for
+execution. The application-owned adapter handles the driver, database
+connection, and driver-specific row and mutation-result details.
+
+```mermaid
+flowchart LR
+A["Tables and columns"] --> B["Expressions and clauses"]
+B --> C["Typed query"]
+C --> D["Dialect renderer"]
+D --> E["SQL text + ordered parameters"]
+E --> F["Application-owned adapter"]
+F --> G["Rows + optional mutation facts"]
+```
+
+Values become bound parameters, and the active dialect quotes identifiers. Raw
+SQL is available through explicit unsafe helpers. The call site shows where
+that unchecked syntax enters the query.
+
+## Understand the Qubu model
+
+Use these pages when a guide leaves a rule unexplained or when an extension
+needs to preserve a fact across composition:
+
+| Model                    | Start with                                          | Covers                                                                              |
+| ------------------------ | --------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Query model              | [Source scope](query-model/source-scope.md)         | Source identity, result shapes, fragments, metadata, and query composition          |
+| Schema model             | [Tables and names](schema/tables-and-names.md)      | Tables, snapshots, diffs, migration plans, and DDL emission                         |
+| Database introspection   | [Database introspection](schema/introspection.md)   | Catalog readers, Snapshot v1 mapping, identities, diagnostics, and support limits   |
+| Schema source generation | [Generate a schema](schema/code-generation.md)      | Machine-owned TypeScript, identity handoff, controlled mappings, and v1 exclusions  |
+| Rendering and execution  | [Dialects and execution](dialects-and-execution.md) | Placeholder and identifier policies, capabilities, adapters, and raw-SQL boundaries |
+| SQL semantic types       | [SQL semantic types](sql-semantic-types.md)         | Application types, SQL domains, nullability, and compatible operations              |
+
+## A small example
+
+```ts
+import { eq, from, integer, render, select, table, text, where } from 'qubu'
+
+const users = table('users', {
+  id: integer(),
+  name: text(),
+})
+
+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" = ?)',
+// parameters: [7],
+// }
+```
+
+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. Qubu emits DDL, but the application owns
+migration execution and database lifecycle. [Troubleshooting](troubleshooting.md)
+starts from common errors and points to the concept page behind each one.

package/docs/query-model/fragments.md

@@ -0,0 +1,109 @@
+# Fragments and metadata
+
+> Build custom SQL from values while preserving the source, result, grouping, and capability facts that later composition checks.
+
+## A fragment has a renderer and metadata
+
+The runtime unit is a `Fragment`:
+
+```ts
+Fragment<Metadata>
+```
+
+The renderer appends SQL and parameters to a context. The metadata type records
+facts that the next composition step needs. The main groups are:
+
+| Fact                                                    | What it records                                                                                       |
+| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `ResultMeta<Output, NullableFrom, SqlType>`             | The value or row produced, sources that can make it `null`, and its SQL domain.                       |
+| `CardinalityMeta<QueryCardinality>`                     | Whether a query returns `many`, `zero-or-one`, or `exactly-one` rows.                                 |
+| `RequiresSourceMeta` and `ProvidesSourceMeta`           | Which source a fragment needs and which source a `FROM` or join introduces.                           |
+| `RequiresOuterSourceMeta` and `ProvidesOuterSourceMeta` | Which enclosing source a correlated or LATERAL query reads and how `correlate()` provides it.         |
+| `NullableSourceMeta`                                    | Which source became nullable through an outer join.                                                   |
+| `ExpressionMeta`, `AggregateMeta`, and `GroupingMeta`   | The columns an expression reads, consumes inside an aggregate, or makes available through `GROUP BY`. |
+
+An untyped extension uses `SqlUnknown` for its SQL domain. Declare a domain when
+the extension needs incompatible operations to fail at the call site. See
+[SQL semantic types](../sql-semantic-types.md).
+
+## Preserve metadata when composing fragments
+
+Composition helpers keep the facts that their children already carry:
+
+| Composition                                                     | Result                                                                                           |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `sequence()`, `commaSeparated()`, `keyword()`, `parenthesize()` | Preserve inherited source and nullability facts without inventing a result or query cardinality. |
+| An expression wrapper such as `expressionFragment()`            | Preserve the wrapped result, source, nullability, and SQL domain.                                |
+| A source-aware operator such as `upper(column)`                 | Create a new result while inheriting the operand's source and nullability facts.                 |
+| An aggregate such as `count(column)`                            | Mark argument dependencies as aggregate-consumed, so they do not need to appear in `GROUP BY`.   |
+| `groupBy()`                                                     | Record grouping expressions and the column dependencies they make available.                     |
+| `leftJoin()`                                                    | Add `NullableSourceMeta` for the joined source.                                                  |
+
+The type-level contract stays small. `OutputOf<T>` describes a result,
+`SqlTypeOf<T>` its SQL domain, `RequiresOf<T>` its required sources, and
+`NullabilityOf<T>` the sources that can make it null after an outer join.
+
+Qubu does not infer every SQL rule. Grouping checks use declared dependencies,
+and functional dependencies from database keys are handled where the source
+model explicitly proves them. New metadata belongs in this union only when a
+producer, consumer, and regression test all exist.
+
+## Parameters are runtime data
+
+Parameter values are not fragment metadata. A renderer calls
+`context.parameter(value)`, and `render()` collects values in placeholder order:
+
+```ts
+import {
+  and,
+  eq,
+  from,
+  integer,
+  like,
+  render,
+  select,
+  table,
+  text,
+  where,
+} from 'qubu'
+
+const users = table('users', {
+  id: integer(),
+  name: text(),
+})
+
+const query = select(
+  { id: users.id },
+  from(users),
+  where(and(eq(users.id, 7), like(users.name, '%Ada%')))
+)
+
+render(query)
+// text:       ... WHERE (("users"."id" = ?) AND ("users"."name" LIKE ?))
+// parameters: [7, '%Ada%']
+```
+
+The parameter array follows the placeholders in the rendered text. `select()`
+normalizes independent clause values, but keep the final call in SQL order in
+new code so source scope and repair hints are visible at a glance.
+
+The public [`sql` template tag](../guides/sql-templates.md) uses the same
+renderer. Ordinary substitutions call `context.parameter()`, while expression,
+query, and fragment substitutions call back into the active render context.
+The tag therefore keeps placeholder numbering, dialect behavior, and inherited
+metadata in one composition path.
+
+## Keep the boundary explicit
+
+Qubu tracks source scope, result shape, nullability, cardinality, and portable
+SQL capabilities. It does not encode every vendor grammar rule or implicit
+conversion. Use standard fragments for portable SQL and move vendor-specific
+syntax to [dialects or custom extensions](../dialects-and-execution.md).
+
+## Read next
+
+- [Source scope](source-scope.md) covers source identities and correlation.
+- [Result shapes and cardinality](result-shapes.md) covers projections and
+  nullable results.
+- [Extend Qubu](../guides/extensions/overview.md) applies this model to custom
+  expressions, clauses, and sources.

package/docs/query-model/result-shapes.md

@@ -0,0 +1,125 @@
+# Result shapes and cardinality
+
+> Choose a projection, understand how joins change its nullability, and check when a nested query can return no row.
+
+## Name the selected row
+
+An object projection uses its keys as result names:
+
+```ts
+import { from, integer, select, table, text, upper } from 'qubu'
+
+const users = table('users', {
+  id: integer(),
+  name: text(),
+})
+
+const query = select(
+  {
+    id: users.id,
+    displayName: upper(users.name),
+  },
+  from(users)
+)
+
+type Row = typeof query.row
+// { id: number; displayName: string }
+```
+
+The projection key also names the SQL output column. Use explicit fields for a
+shaped result. Reserve `all(source)` for a whole-source result contract. It
+expands to named columns, so the SQL columns and inferred row keys stay aligned:
+
+```ts
+import { all, from, select, upper } from 'qubu'
+
+const query = select(
+  { ...all(users), normalizedName: upper(users.name) },
+  from(users)
+)
+```
+
+When a query becomes a CTE or derived table, its row shape becomes the columns
+available from that new source. `RETURNING` uses the same projection rules.
+See [Compose queries](../guides/compose-queries.md) and
+[Write mutations](../guides/mutations.md) for those workflows.
+
+The examples below continue with the `users` table from the first example.
+
+## Account for nullable joins
+
+`leftJoin()` marks the joined source as nullable. A selected column from that
+source widens with `null`, while an expression with its own non-null result
+contract can stay non-null:
+
+```ts
+import { count, eq, from, integer, leftJoin, select, table, text } from 'qubu'
+
+const users = table('users', {
+  id: integer(),
+  name: text(),
+})
+const posts = table('posts', {
+  id: integer(),
+  authorId: integer(),
+  title: text(),
+})
+
+const query = select(
+  {
+    userName: users.name,
+    postTitle: posts.title,
+    postCount: count(posts.id),
+  },
+  from(users),
+  leftJoin(posts, eq(users.id, posts.authorId))
+)
+
+type Row = typeof query.row
+// { userName: string; postTitle: string | null; postCount: number }
+```
+
+The same rule applies inside expressions. `upper(posts.title)` remains
+nullable because it depends on the joined row. `coalesce()` and a `CASE`
+expression with non-null branches can return a non-null result.
+
+## Check scalar cardinality
+
+`scalar()` turns a query with exactly one selected field into an expression. The
+result includes `null` when the query may return no rows:
+
+```ts
+import { fetchFirst, from, scalar, select, table, value } from 'qubu'
+
+const users = table('users', { id: integer() })
+const firstUser = select({ id: users.id }, from(users), fetchFirst(1))
+
+const firstId = scalar(firstUser)
+// OutputOf<typeof firstId> is number | null
+```
+
+`fetchFirst(1)` proves an upper bound, not that a row exists. A source-free
+select is different:
+
+```ts
+const constant = select({ value: value(42) })
+const constantValue = scalar(constant)
+// OutputOf<typeof constantValue> is number
+```
+
+Qubu does not infer exactness from a predicate such as `WHERE id = 1`. That
+predicate can match no rows, so the scalar result remains nullable.
+
+## Keep SQL domains with the row
+
+Projections preserve the SQL domains of their expressions. A text expression
+stays `SqlText` through a CTE, derived table, scalar subquery, set operation, or
+mutation `RETURNING` projection. See [SQL semantic types](../sql-semantic-types.md)
+for the domain rules.
+
+## Read next
+
+- [Source scope](source-scope.md) explains why a column must come from `FROM`,
+  a join, or an intentional correlation.
+- [Fragments and metadata](fragments.md) explains how result and nullability
+  facts move through custom composition.