qubu 0.0.0 → 0.3.3

package/docs/guides/compose-queries.md

@@ -0,0 +1,225 @@
+# Compose queries
+
+> Reuse a query's inferred row shape as a typed source for CTEs, derived tables, subqueries, and set operations.
+
+## Turn a query into a CTE
+
+`cte()` exposes the selected fields of a query as columns on a new source.
+Attach it with `withCte()` and use the CTE source in `from()`:
+
+```ts
+import {
+  cte,
+  eq,
+  from,
+  integer,
+  select,
+  table,
+  text,
+  where,
+  withCte,
+} from 'qubu'
+
+const users = table('users', {
+  id: integer(),
+  name: text(),
+})
+
+const activeUsers = cte(
+  'active_users',
+  select(
+    { id: users.id, name: users.name },
+    from(users),
+    where(eq(users.id, 7))
+  )
+)
+
+const report = select(
+  { displayName: activeUsers.name },
+  withCte(activeUsers),
+  from(activeUsers)
+)
+```
+
+`activeUsers.name` is a typed column derived from the first query's row shape.
+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.
+
+## Build a recursive CTE
+
+`recursiveCte()` uses the anchor projection as the contract for a recursive
+member. The callback receives a typed self-reference; introduce it through
+`from()` or a join before selecting its fields:
+
+```ts
+import {
+  add,
+  cast,
+  from,
+  integer,
+  lt,
+  recursiveCte,
+  select,
+  value,
+  where,
+  withCte,
+} from 'qubu'
+
+const numbers = recursiveCte(
+  'numbers',
+  select({ value: cast(value(1), integer()) }),
+  self =>
+    select({ value: add(self.value, 1) }, from(self), where(lt(self.value, 3)))
+)
+
+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
+`cast()` when the database cannot infer it from surrounding columns; PostgreSQL
+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.
+
+## Use a derived table
+
+Alias a query when it should be used as an inline source:
+
+```ts
+import { alias, from, lower, select } from 'qubu'
+import type { SqlTypeOf } from 'qubu'
+
+const names = select({ name: lower(users.name) }, from(users))
+const namesSource = alias(names, 'names')
+
+const query = select({ name: namesSource.name }, from(namesSource))
+type NameSqlDomain = SqlTypeOf<typeof namesSource.name>
+// SqlText
+```
+
+The alias gets the selected query's fields, while the new source identity keeps
+scope checks from confusing `namesSource.name` with `users.name`.
+
+Its SQL domain is retained too. The projected `lower(users.name)` remains
+`SqlText` through this query alias, and the same preservation applies to a CTE,
+so downstream text operations remain checked without redeclaring the field.
+
+## Nest a scalar subquery
+
+`scalar()` turns a query with exactly one selected field into an expression:
+
+```ts
+import { from, scalar, select, value } from 'qubu'
+
+const firstId = select({ id: users.id }, from(users))
+const query = select(
+  {
+    name: users.name,
+    firstId: scalar(firstId),
+  },
+  from(users)
+)
+```
+
+`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
+as `select({ value: value(42) })` is known to produce exactly one row.
+
+Qubu does not treat an arbitrary predicate as proof of exactness. Use
+`exists()`, `notExists()`, or `inQuery()` for boolean subquery predicates.
+
+## Combine compatible queries
+
+Set operations preserve the left query's row shape. Both queries must select
+compatible rows:
+
+```ts
+import { eq, from, select, unionAll, where } from 'qubu'
+
+const first = select({ id: users.id }, from(users))
+const second = select({ id: users.id }, from(users), where(eq(users.id, 7)))
+
+const allUsers = unionAll(first, second)
+```
+
+Use `union`, `unionAll`, `intersect`, or `except` depending on the SQL
+operation. Each input renderer still contributes its runtime parameters, which
+are collected in traversal order.
+
+## Prefer values over a builder chain
+
+Build reusable pieces as ordinary values and pass them into the final query:
+
+```ts
+import { desc, eq, from, orderBy, select, where } from 'qubu'
+
+const byId = where(eq(users.id, 7))
+const newest = orderBy(desc(users.id))
+
+const query = select(
+  { id: users.id, name: users.name },
+  from(users),
+  byId,
+  newest
+)
+```
+
+This makes it possible to share a predicate or projection without mutating a
+query object. The final `select()` call remains the place where source scope
+and result shape are checked. Qubu also accepts these independent values in
+another order, but SQL order is the canonical visual style for finished query
+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.
+
+For an application-level requirement, describe the required JavaScript row:
+
+```ts
+import { eq, where } from 'qubu'
+import type { TableLike } from 'qubu'
+
+function byStringId<TTable extends TableLike<{ id: string }>>(
+  table: TTable,
+  id: string
+) {
+  return where(eq(table.columns.id, id))
+}
+```
+
+`{ id: string }` means a non-null selected string. It accepts a table with
+extra fields and rejects `string | null`, but it does not distinguish
+`SqlText` from `SqlUuid` because both have a JavaScript output of `string`.
+
+Use `FieldLike` when the fragment depends on SQL semantics:
+
+```ts
+import { eq, where } from 'qubu'
+import type { FieldLike, SourceLike, SqlTextLike } from 'qubu'
+
+type NonNullTextId = FieldLike<{
+  sqlType: SqlTextLike
+  nullable: false
+}>
+
+function byTextId<TSource extends SourceLike<{ id: NonNullTextId }>>(
+  source: TSource,
+  id: string
+) {
+  return where(eq(source.columns.id, id))
+}
+```
+
+This version accepts known text-like and permissive `SqlUnknown` fields. It
+rejects nullable text and known non-text domains such as `SqlUuid`. Add an
+`output` property to the `FieldLike` descriptor when the fragment also needs a
+specific JavaScript result type.

package/docs/guides/drizzle.md

@@ -0,0 +1,129 @@
+# Use a Qubu schema with Drizzle
+
+> Derive Drizzle tables at runtime so Qubu and Drizzle queries can share one
+> schema declaration during a gradual migration.
+
+## Install the optional integration
+
+Install Drizzle next to Qubu. The Drizzle entrypoints use an optional peer
+dependency, so importing the rest of Qubu does not load the ORM.
+
+```bash
+pnpm add qubu drizzle-orm
+```
+
+The converter supports PostgreSQL, MySQL, and SQLite with Drizzle 0.45.2 through
+the current 0.x line.
+
+## Convert the schema
+
+Declare tables and the root registry with Qubu, then import the converter for
+your database:
+
+```ts
+import { integer, schema, table, text } from 'qubu'
+import { toPostgresDrizzleSchema } from 'qubu/drizzle/postgres'
+
+const users = table('user_records', {
+  id: integer({ generated: true }),
+  name: text(),
+  nickname: text({ nullable: true }),
+})
+
+const appSchema = schema({ users }, { namespace: 'app' })
+const drizzleTables = toPostgresDrizzleSchema(appSchema)
+```
+
+The import path selects the dialect. Each module imports only its matching
+Drizzle core package:
+
+| Database   | Import                  | Converter                   |
+| ---------- | ----------------------- | --------------------------- |
+| PostgreSQL | `qubu/drizzle/postgres` | `toPostgresDrizzleSchema()` |
+| MySQL      | `qubu/drizzle/mysql`    | `toMysqlDrizzleSchema()`    |
+| SQLite     | `qubu/drizzle/sqlite`   | `toSqliteDrizzleSchema()`   |
+
+`qubu/drizzle` exports the shared conversion error and dialect types. It does
+not import a dialect core or provide a universal runtime converter.
+
+`drizzleTables.users` is a real Drizzle `PgTable`. The logical `users` key,
+physical `user_records` name, `app` namespace, field keys, and physical column
+names all come from the Qubu declaration.
+
+Pass the converted record to Drizzle and use it in ordinary queries:
+
+```ts
+import { eq } from 'drizzle-orm'
+import { drizzle } from 'drizzle-orm/node-postgres'
+
+const db = drizzle(pool, { schema: drizzleTables })
+
+const rows = await db
+  .select({ id: drizzleTables.users.id, name: drizzleTables.users.name })
+  .from(drizzleTables.users)
+  .where(eq(drizzleTables.users.id, 7))
+```
+
+Existing Qubu queries can keep importing `users`. Move call sites to
+`drizzleTables.users` one at a time without duplicating the table declaration.
+
+## Type behavior
+
+The converted columns preserve selected values, nullability, required insert
+keys, defaults, and generated-column omission:
+
+```ts
+type User = typeof drizzleTables.users.$inferSelect
+// { id: number; name: string; nickname: string | null }
+
+type NewUser = typeof drizzleTables.users.$inferInsert
+// { name: string; nickname: string | null }
+```
+
+Qubu requires a nullable insert field unless that field has a default. The
+adapter retains that rule even though hand-written Drizzle schemas normally
+make nullable fields optional.
+
+Drizzle has one application value type per column. Qubu can instead declare
+different select, insert, and update types with
+`column<Output, Insert, Update>()`. That declaration has no lossless Drizzle
+equivalent, so each dialect converter rejects it at compile time. Built-in
+Qubu columns and `$type()` narrowing use one value type and convert without an
+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:
+
+```ts
+import { nativeColumn, schema, table } from 'qubu'
+import { toPostgresDrizzleSchema } from 'qubu/drizzle/postgres'
+
+const records = table('records', {
+  handle: nativeColumn('postgresql', 'CITEXT'),
+})
+
+const tables = toPostgresDrizzleSchema(schema({ records }))
+```
+
+Conversion first runs Qubu's snapshot validation for the selected dialect.
+Metadata that Drizzle 0.45 cannot express, such as deferred constraints or
+included index columns, raises `DrizzleSchemaConversionError` with a `code` and
+`path`.
+
+PostgreSQL schemas and MySQL databases become Drizzle table namespaces. Drizzle
+SQLite tables have no namespace field, so a Qubu SQLite namespace remains
+snapshot metadata and is not attached to the converted table.
+
+> [!IMPORTANT]
+> An external default or generated descriptor records that another authority
+> owns the SQL definition. The adapter preserves its Drizzle write types but
+> cannot invent the missing expression. Keep Qubu snapshots and migration plans
+> as the DDL authority while those descriptors remain external.
+
+The returned record contains tables, not Drizzle `relations()` declarations.
+Add relations beside the converted record if the application uses Drizzle's
+relational query API.

package/docs/guides/extensions/dialects.md

@@ -0,0 +1,40 @@
+# Add a dialect policy
+
+> Change identifiers, placeholders, pagination, or cast targets at the rendering boundary without changing portable query construction.
+
+Use `createDialect()` when the query is portable but the driver changes
+identifiers, placeholders, or pagination:
+
+The examples assume a query has already been built.
+
+```ts
+import { render } from 'qubu'
+import { createDialect } from 'qubu/core'
+
+const colonDialect = createDialect({
+  name: 'colon',
+  placeholder: position => ':p' + position,
+})
+
+render(query, colonDialect)
+// ... WHERE ... = :p1
+```
+
+`createDialect()` uses Qubu's standard double-quoted identifier policy unless
+you provide `quoteIdentifier`. A complete pagination policy can be supplied
+through the optional `pagination` renderer.
+
+For the full rendering and execution boundary, read
+[Dialects and execution](../../dialects-and-execution.md). It covers capability
+requirements, the driver adapter, and the values that cross the boundary.
+
+For syntax that is not a small policy decision, add a
+[custom fragment or clause](sources-and-clauses.md) instead of making the
+standard dialect pretend that vendor behavior is portable.
+
+## Read next
+
+- [Add sources and clauses](sources-and-clauses.md) covers custom relations and
+  clause placement.
+- [Add typed expressions](typed-expressions.md) covers custom SQL domains and
+  cast targets.

package/docs/guides/extensions/overview.md

@@ -0,0 +1,36 @@
+# Extend Qubu
+
+> Choose an extension boundary when the built-in API does not cover a driver-specific or uncommon SQL feature.
+
+Qubu extensions are values that render SQL and carry the metadata later
+composition needs. Choose the page that matches the thing you are adding:
+
+Ordinary query code stays on the `qubu` root entrypoint. Import fragment,
+dialect, and extension constructors from `qubu/core`; import custom sources and
+schema-expression constructors from `qubu/schema`. The [supported
+surface](../../reference/supported-surface.md) keeps the full entrypoint map in
+one place.
+
+| You need to add...                  | Read...                                       |
+| ----------------------------------- | --------------------------------------------- |
+| A custom relation or clause         | [Sources and clauses](sources-and-clauses.md) |
+| A dialect-specific rendering policy | [A dialect policy](dialects.md)               |
+| A typed expression or SQL domain    | [Typed expressions](typed-expressions.md)     |
+| Parameterized trusted SQL syntax    | [SQL templates](../sql-templates.md)          |
+| Syntax Qubu does not model          | [Unsafe syntax](unsafe-syntax.md)             |
+
+Use `context.parameter()` for runtime values. Use the typed forms when a
+custom expression or source must preserve source, result, nullability, or SQL
+domain metadata. The [sources and clauses](sources-and-clauses.md) page starts
+with a complete custom-clause example.
+
+## Read the concept pages
+
+- [Source scope](../../query-model/source-scope.md) explains the identities
+  custom sources must provide.
+- [Fragments and metadata](../../query-model/fragments.md) explains the facts
+  composition carries between fragments.
+- [Dialects and execution](../../dialects-and-execution.md) explains the
+  rendering and driver boundary.
+- [SQL semantic types](../../sql-semantic-types.md) explains capability checks
+  for typed expressions.

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

@@ -0,0 +1,82 @@
+# Add sources and clauses
+
+> Publish a custom SQL clause or relation while preserving parameter order and source-scope checks.
+
+## Add a custom clause
+
+Qubu extensions are ordinary fragments. A custom clause supplies a placement,
+render order, and renderer:
+
+```ts
+import { from, render, select, table, text } from 'qubu'
+import { customClause } from 'qubu/core'
+
+const users = table('users', { name: text() })
+
+const fetchWithTies = customClause({
+  name: 'fetch-with-ties',
+  order: 100,
+  render(context) {
+    context.append('FETCH FIRST ')
+    context.parameter(10)
+    context.append(' ROWS WITH TIES')
+  },
+})
+
+const query = select({ name: users.name }, from(users), fetchWithTies)
+
+render(query)
+// ... FETCH FIRST ? ROWS WITH TIES
+```
+
+`context.parameter(10)` binds the value at render time, and the rendered
+parameter is still ordered with every other parameter in the query. Parameter
+value types are intentionally not part of fragment metadata.
+
+## Add a typed custom FROM source
+
+Use `customSource()` for a table-valued function or another relation whose row
+shape is known to the application but cannot be declared with `table()`. Its
+`columns` definitions create the same direct and `.columns` references as a
+table, while `from()` or a join supplies the source to the query scope:
+
+```ts
+import { from, integer, render, select, text } from 'qubu'
+import { identifier } from 'qubu/core'
+import { customSource } from 'qubu/schema'
+
+const rows = customSource({
+  identity: { sourceKind: 'table-function', name: 'json_each', alias: 'row' },
+  sourceKind: 'table-function',
+  reference: identifier('row'),
+  columns: {
+    key: integer(),
+    value: text({ nullable: true }),
+  },
+  render(context) {
+    context.append('json_each(')
+    context.parameter('{"a":1}')
+    context.append(') AS ')
+    context.render(identifier('row'))
+  },
+})
+
+const query = select({ value: rows.value }, from(rows))
+render(query)
+// ... FROM json_each(?) AS "row"
+```
+
+`identity` is the source-scope key; `reference` is the SQL qualifier used by
+the generated columns. A nullable column remains nullable intrinsically, and a
+`leftJoin(rows, ...)` adds outer-join nullability to every selected row
+column. Render the complete relation in the producer and bind values with
+`context.parameter()`; the normal renderer preserves parameter order.
+
+## Read next
+
+- [Add typed expressions](typed-expressions.md) covers custom SQL domains and
+  metadata-preserving expression wrappers.
+- [Add a dialect policy](dialects.md) covers identifier, placeholder, and
+  pagination policies.
+- [Source scope](../../query-model/source-scope.md) explains the identity rules
+  custom sources must satisfy.

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

@@ -0,0 +1,94 @@
+# Add typed expressions
+
+> Extend Qubu with expressions that retain source, nullability, result, and SQL-domain metadata.
+
+## Build expressions from public helpers
+
+The examples use the `users` table from [Sources and clauses](sources-and-clauses.md).
+
+`fragment()`, `makeExpression()`, `parameter()`, `identifier()`, `syntax()`,
+`customClause()`, and `customSource()` are public extension building blocks.
+Import fragment, dialect, and expression constructors from `qubu/core`; import
+custom source and schema metadata constructors from `qubu/schema`. Preserve the
+same metadata model that built-ins use:
+
+- use `RequiresSourceMeta<Source>` for every source that the expression reads;
+- use `ResultMeta<Output, NullableFrom, SqlType>` when the fragment exposes a
+  typed result, or accept its default `SqlUnknown` domain intentionally;
+- inherit child source and nullability facts when composing fragments; and
+- use `context.parameter()` for values instead of concatenating them into SQL.
+
+`sequence()` is useful for a reusable fragment assembled from arbitrary child
+fragments. Its `const` type parameter preserves the children's metadata, so
+source-scope checking continues to work without `as const` at the call site.
+
+## Declare a custom SQL domain
+
+Extend `SqlSemanticType` and only the portable capabilities the database type
+actually supports. Compatibility groups allow a dialect-specific domain to
+interoperate with a built-in family:
+
+```ts
+import { cast, column } from 'qubu'
+import type {
+  SqlEqualityComparable,
+  SqlOrderable,
+  SqlSemanticType,
+  SqlTextLike,
+} from 'qubu'
+
+interface SqlCitext
+  extends SqlSemanticType<'postgres.citext'>,
+    SqlTextLike,
+    SqlOrderable<'text'>,
+    SqlEqualityComparable<'text'> {}
+
+const citext = column<string, string, string, SqlCitext>({
+  castType: 'CITEXT',
+})
+
+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.
+Definitions with schema flags are not accepted as cast targets because cast
+nullability comes from the operand and write flags have no cast meaning.
+
+Declare result domains at other extension boundaries too:
+
+```ts
+import { typedCall, typedCast, typedValue, unsafeExpression } from 'qubu/core'
+import type { SqlText, SqlUuid } from 'qubu'
+
+const id = typedValue<SqlUuid, string>('108cb836-20d2-41b2-8c23-f0c94700aa7e')
+const normalized = typedCall<SqlText, string>()('custom_text', users.name)
+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. `unsafeExpression()` emits its
+string unchanged and should remain a last resort.
+
+The lower-level forms also expose the SQL domain in their generic lists:
+`call<Output, Name, Arguments, NullableFrom, SqlType>()` and
+`cast<Output, SqlType>()`. They are useful when an extension already computes
+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
+known domain opts the extension into incompatible-operation errors. See
+[SQL semantic types](../../sql-semantic-types.md) for the capability model and
+its limits.
+
+## Read next
+
+- [Add sources and clauses](sources-and-clauses.md) covers custom relations and
+  clause renderers.
+- [Use unsafe syntax](unsafe-syntax.md) covers the raw-SQL boundary.

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

@@ -0,0 +1,27 @@
+# Use unsafe syntax
+
+> Keep raw SQL visible and trusted when Qubu does not model the syntax you need.
+
+`unsafeExpression()` and related escape hatches exist for syntax that cannot be
+modeled yet. They do not quote identifiers or bind values for you:
+
+```ts
+import { select } from 'qubu'
+import { unsafeExpression } from 'qubu/core'
+
+const query = select({
+  today: unsafeExpression('CURRENT_DATE'),
+})
+```
+
+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`.
+
+Read [Dialects and execution](../../dialects-and-execution.md) for the boundary
+between rendering and driver behavior. Read [Add typed
+expressions](typed-expressions.md) when the extension needs a result domain or
+source metadata.