qubu 0.4.0 → 0.4.2

package/docs/query-model/fragments.md

@@ -54,20 +54,9 @@ 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', {
+import { and, eq, from, integer, like, render, select, table, text, where } from "qubu"
+
+const users = table("users", {
   id: integer(),
   name: text(),
 })
@@ -75,7 +64,7 @@ const users = table('users', {
 const query = select(
   { id: users.id },
   from(users),
-  where(and(eq(users.id, 7), like(users.name, '%Ada%')))
+  where(and(eq(users.id, 7), like(users.name, "%Ada%"))),
 )
 
 render(query)

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

@@ -7,9 +7,9 @@
 An object projection uses its keys as result names:
 
 ```ts
-import { from, integer, select, table, text, upper } from 'qubu'
+import { from, integer, select, table, text, upper } from "qubu"
 
-const users = table('users', {
+const users = table("users", {
   id: integer(),
   name: text(),
 })
@@ -19,7 +19,7 @@ const query = select(
     id: users.id,
     displayName: upper(users.name),
   },
-  from(users)
+  from(users),
 )
 
 type Row = typeof query.row
@@ -31,12 +31,9 @@ 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'
+import { all, from, select, upper } from "qubu"
 
-const query = select(
-  { ...all(users), normalizedName: upper(users.name) },
-  from(users)
-)
+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
@@ -53,13 +50,13 @@ 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'
+import { count, eq, from, integer, leftJoin, select, table, text } from "qubu"
 
-const users = table('users', {
+const users = table("users", {
   id: integer(),
   name: text(),
 })
-const posts = table('posts', {
+const posts = table("posts", {
   id: integer(),
   authorId: integer(),
   title: text(),
@@ -72,7 +69,7 @@ const query = select(
     postCount: count(posts.id),
   },
   from(users),
-  leftJoin(posts, eq(users.id, posts.authorId))
+  leftJoin(posts, eq(users.id, posts.authorId)),
 )
 
 type Row = typeof query.row
@@ -89,9 +86,9 @@ expression with non-null branches can return a non-null result.
 result includes `null` when the query may return no rows:
 
 ```ts
-import { fetchFirst, from, scalar, select, table, value } from 'qubu'
+import { fetchFirst, from, scalar, select, table, value } from "qubu"
 
-const users = table('users', { id: integer() })
+const users = table("users", { id: integer() })
 const firstUser = select({ id: users.id }, from(users), fetchFirst(1))
 
 const firstId = scalar(firstUser)

package/docs/query-model/source-scope.md

@@ -13,12 +13,12 @@ Qubu reports a missing source when a query selects a column from a table that
 does not appear in the query:
 
 ```ts
-import { from, integer, select, table, text } from 'qubu'
+import { from, integer, select, table, text } from "qubu"
 
-const users = table('users', {
+const users = table("users", {
   id: integer(),
 })
-const posts = table('posts', {
+const posts = table("posts", {
   id: integer(),
   title: text(),
 })
@@ -31,12 +31,12 @@ Add the source that owns the column, or join it with a condition that refers to
 both sources:
 
 ```ts
-import { eq, from, innerJoin, integer, select, table } from 'qubu'
+import { eq, from, innerJoin, integer, select, table } from "qubu"
 
-const users = table('users', {
+const users = table("users", {
   id: integer(),
 })
-const posts = table('posts', {
+const posts = table("posts", {
   id: integer(),
   authorId: integer(),
 })
@@ -44,7 +44,7 @@ const posts = table('posts', {
 const query = select(
   { userId: users.id, postId: posts.id },
   from(users),
-  innerJoin(posts, eq(users.id, posts.authorId))
+  innerJoin(posts, eq(users.id, posts.authorId)),
 )
 ```
 
@@ -54,14 +54,14 @@ Aliases, CTEs, derived queries, and custom sources expose new source identities.
 Use their columns after wrapping the original source:
 
 ```ts
-import { alias, from, integer, select, table, text } from 'qubu'
+import { alias, from, integer, select, table, text } from "qubu"
 
-const users = table('users', {
+const users = table("users", {
   id: integer(),
   name: text(),
 })
 
-const author = alias(users, 'author')
+const author = alias(users, "author")
 const query = select({ name: author.name }, from(author))
 ```
 
@@ -72,10 +72,10 @@ The same rule applies to a CTE or derived query. A query's selected row becomes
 the set of columns exposed by its new source:
 
 ```ts
-import { alias, from, lower, select } from 'qubu'
+import { alias, from, lower, select } from "qubu"
 
 const names = select({ name: lower(users.name) }, from(users))
-const namesSource = alias(names, 'names')
+const namesSource = alias(names, "names")
 
 const query = select({ name: namesSource.name }, from(namesSource))
 ```
@@ -90,35 +90,31 @@ Use `customSource()` for a table-valued function or another relation that
 definitions, and complete relation renderer:
 
 ```ts
-import { eq, from, integer, select, text, where } from 'qubu'
-import { identifier } from 'qubu/core'
-import { customSource } from 'qubu/schema'
+import { eq, from, integer, select, text, where } from "qubu"
+import { identifier } from "qubu/core"
+import { customSource } from "qubu/schema"
 
 const entries = customSource({
   identity: {
-    sourceKind: 'table-function',
-    name: 'json_each',
-    alias: 'entry',
+    sourceKind: "table-function",
+    name: "json_each",
+    alias: "entry",
   },
-  sourceKind: 'table-function',
-  reference: identifier('entry'),
+  sourceKind: "table-function",
+  reference: identifier("entry"),
   columns: {
     key: integer(),
     value: text({ nullable: true }),
   },
   render(context) {
-    context.append('json_each(')
+    context.append("json_each(")
     context.parameter('{"a":1}')
-    context.append(') AS ')
-    context.render(identifier('entry'))
+    context.append(") AS ")
+    context.render(identifier("entry"))
   },
 })
 
-const query = select(
-  { value: entries.value },
-  from(entries),
-  where(eq(entries.key, 7))
-)
+const query = select({ value: entries.value }, from(entries), where(eq(entries.key, 7)))
 ```
 
 `identity` is the type-level source key. `reference` is the SQL qualifier used
@@ -135,20 +131,10 @@ Use `correlate()` when an inner query intentionally reads a source from its
 enclosing query. The provision changes type checking but emits no SQL:
 
 ```ts
-import {
-  correlate,
-  crossJoin,
-  eq,
-  from,
-  integer,
-  lateral,
-  select,
-  table,
-  where,
-} from 'qubu'
-
-const users = table('users', { id: integer() })
-const posts = table('posts', {
+import { correlate, crossJoin, eq, from, integer, lateral, select, table, where } from "qubu"
+
+const users = table("users", { id: integer() })
+const posts = table("posts", {
   id: integer(),
   authorId: integer(),
 })
@@ -157,15 +143,11 @@ const recentPost = select(
   { id: posts.id },
   from(posts),
   correlate(users),
-  where(eq(posts.authorId, users.id))
+  where(eq(posts.authorId, users.id)),
 )
 
-const recent = lateral(recentPost, 'recent_post')
-const query = select(
-  { userId: users.id, postId: recent.id },
-  from(users),
-  crossJoin(recent)
-)
+const recent = lateral(recentPost, "recent_post")
+const query = select({ userId: users.id, postId: recent.id }, from(users), crossJoin(recent))
 ```
 
 The inner query consumes `posts` locally. The enclosing `users` source satisfies

package/docs/reference/mysql-snapshot.md

@@ -7,10 +7,7 @@
 Import the adapter from the optional snapshot entrypoint:
 
 ```ts
-import {
-  createMysqlSchemaSnapshot,
-  tryCreateMysqlSchemaSnapshot,
-} from 'qubu/snapshot'
+import { createMysqlSchemaSnapshot, tryCreateMysqlSchemaSnapshot } from "qubu/snapshot"
 
 const snapshot = createMysqlSchemaSnapshot(appSchema)
 const result = tryCreateMysqlSchemaSnapshot(appSchema)
@@ -44,7 +41,7 @@ a schema may include a MySQL engine or version-specific feature:
 const result = tryCreateMysqlSchemaSnapshot(appSchema)
 if (!result.ok) {
   for (const issue of result.diagnostics) {
-    console.error(issue.path.join('.'), issue.code, issue.message)
+    console.error(issue.path.join("."), issue.code, issue.message)
   }
 }
 ```

package/docs/reference/postgres-snapshot.md

@@ -11,7 +11,7 @@ import {
   createSchemaSnapshot,
   createPostgresSchemaSnapshot,
   postgresSnapshotAdapter,
-} from 'qubu/snapshot'
+} from "qubu/snapshot"
 
 const snapshot = createPostgresSchemaSnapshot(appSchema)
 // Equivalent: createSchemaSnapshot(appSchema, { adapter: postgresSnapshotAdapter })
@@ -46,12 +46,12 @@ schema and application boundaries.
 Use the non-throwing form when a schema may contain a server-specific feature:
 
 ```ts
-import { tryCreatePostgresSchemaSnapshot } from 'qubu/snapshot'
+import { tryCreatePostgresSchemaSnapshot } from "qubu/snapshot"
 
 const result = tryCreatePostgresSchemaSnapshot(appSchema)
 if (!result.ok) {
   for (const issue of result.diagnostics) {
-    console.error(issue.path.join('.'), issue.code, issue.message)
+    console.error(issue.path.join("."), issue.code, issue.message)
   }
 }
 ```

package/docs/reference/sqlite-snapshot.md

@@ -5,10 +5,7 @@
 Import the adapter from the optional snapshot entrypoint:
 
 ```ts
-import {
-  createSqliteSchemaSnapshot,
-  tryCreateSqliteSchemaSnapshot,
-} from 'qubu/snapshot'
+import { createSqliteSchemaSnapshot, tryCreateSqliteSchemaSnapshot } from "qubu/snapshot"
 
 const snapshot = createSqliteSchemaSnapshot(appSchema)
 const result = tryCreateSqliteSchemaSnapshot(appSchema)
@@ -42,7 +39,7 @@ schema may include a feature that depends on a SQLite version or table shape:
 const result = tryCreateSqliteSchemaSnapshot(appSchema)
 if (!result.ok) {
   for (const issue of result.diagnostics) {
-    console.error(issue.path.join('.'), issue.code, issue.message)
+    console.error(issue.path.join("."), issue.code, issue.message)
   }
 }
 ```

package/docs/reference/supported-surface.md

@@ -4,32 +4,32 @@
 
 ## Package entrypoints
 
-| Import                  | Kind             | Use it for                                                                                                       |
-| ----------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `qubu`                  | Runtime          | Ordinary query and schema definitions, reads, writes, SQL templates, rendering, EXPLAIN, and execution contracts |
-| `qubu/core`             | Runtime          | Fragment and rendering primitives, dialect construction, SQL types, and extension constructors                   |
-| `qubu/codegen`          | Runtime          | Deterministic machine-owned TypeScript schemas from complete, non-lossy introspection                            |
-| `qubu/ddl`              | Runtime          | DDL preflight and deterministic PostgreSQL, SQLite, or MySQL emission from a migration plan                      |
-| `qubu/diff`             | Runtime          | Canonical Snapshot v1 or v2 comparison, rename hints, suggestions, and safety diagnostics                        |
-| `qubu/drizzle`          | Runtime          | Shared Drizzle conversion errors and dialect types                                                               |
-| `qubu/introspection`    | Runtime          | Catalog readers, normalized catalogs, and mapping to Snapshot v1 or v2                                           |
-| `qubu/migration`        | Runtime          | Pure migration planning with dependencies, decisions, preconditions, and explicit custom SQL                     |
-| `qubu/mysql`            | Runtime          | The MySQL query dialect policy                                                                                   |
-| `qubu/postgres`         | Runtime          | PostgreSQL query dialect helpers such as `postgresDialect()` and `ilike()`                                       |
-| `qubu/schema`           | Runtime          | Advanced schema metadata, storage and constraint models, source models, and schema-expression extensions         |
-| `qubu/snapshot`         | Runtime          | Canonical Snapshot v1 and v2 traversal, encoding, decoding, diagnostics, and digests                             |
-| `qubu/sqlite`           | Runtime          | The SQLite query dialect policy                                                                                  |
-| `qubu/vite`             | Runtime          | The optional `qubu()` Vite compiler hint                                                                         |
-| `qubu/package.json`     | JSON             | The published package manifest                                                                                   |
-| `qubu/drizzle/mysql`    | Runtime          | Runtime conversion from Qubu schemas to MySQL Drizzle tables                                                     |
-| `qubu/drizzle/postgres` | Runtime          | Runtime conversion from Qubu schemas to PostgreSQL Drizzle tables                                                |
-| `qubu/drizzle/sqlite`   | Runtime          | Runtime conversion from Qubu schemas to SQLite Drizzle tables                                                    |
-| `qubu/globals`          | TypeScript types | Opt-in ambient declarations for directive-bearing modules                                                        |
-
-The package validator confirms 17 runtime entrypoints, 18 type entrypoints,
-`qubu/package.json` as JSON, and `qubu/globals` as type-only. Concrete dialect
-constructors live on their database subpaths. The root renderer uses Qubu's
-standard SQL policy by default.
+| Import                   | Kind             | Use it for                                                                                                       |
+| ------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `qubu`                   | Runtime          | Ordinary query and schema definitions, reads, writes, SQL templates, rendering, EXPLAIN, and execution contracts |
+| `qubu/core`              | Runtime          | Fragment and rendering primitives, dialect construction, SQL types, and extension constructors                   |
+| `qubu/codegen`           | Runtime          | Deterministic machine-owned TypeScript schemas from complete, non-lossy introspection                            |
+| `qubu/ddl`               | Runtime          | DDL preflight and deterministic PostgreSQL, SQLite, or MySQL emission from a migration plan                      |
+| `qubu/diff`              | Runtime          | Canonical Snapshot v1 or v2 comparison, rename hints, suggestions, and safety diagnostics                        |
+| `qubu/introspection`     | Runtime          | Catalog readers, normalized catalogs, and mapping to Snapshot v1 or v2                                           |
+| `qubu/migration`         | Runtime          | Pure migration planning with dependencies, decisions, preconditions, and explicit custom SQL                     |
+| `qubu/mysql`             | Runtime          | The MySQL query dialect policy                                                                                   |
+| `qubu/postgres`          | Runtime          | PostgreSQL query dialect helpers such as `postgresDialect()` and `ilike()`                                       |
+| `qubu/schema`            | Runtime          | Advanced schema metadata, storage and constraint models, source models, and schema-expression extensions         |
+| `qubu/snapshot`          | Runtime          | Canonical Snapshot v1 and v2 traversal, encoding, decoding, diagnostics, and digests                             |
+| `qubu/sqlite`            | Runtime          | The SQLite query dialect policy                                                                                  |
+| `qubu/vite`              | Runtime          | The optional `qubu()` Vite compiler hint                                                                         |
+| `qubu/package.json`      | JSON             | The published package manifest                                                                                   |
+| `@qubu/drizzle`          | Runtime          | Shared Drizzle conversion errors and dialect types                                                               |
+| `@qubu/drizzle/mysql`    | Runtime          | Runtime conversion from Qubu schemas to MySQL Drizzle tables                                                     |
+| `@qubu/drizzle/postgres` | Runtime          | Runtime conversion from Qubu schemas to PostgreSQL Drizzle tables                                                |
+| `@qubu/drizzle/sqlite`   | Runtime          | Runtime conversion from Qubu schemas to SQLite Drizzle tables                                                    |
+| `@qubu/better-auth`      | Runtime          | Better Auth schema derivation and native PostgreSQL, MySQL, and SQLite adapter behavior                          |
+| `qubu/globals`           | TypeScript types | Opt-in ambient declarations for directive-bearing modules                                                        |
+
+The package validator checks every declared entrypoint in each packed workspace
+package. Concrete dialect constructors live on their database subpaths. The
+root renderer uses Qubu's standard SQL policy by default.
 
 Snapshot dialect behavior is documented in the [PostgreSQL](postgres-snapshot.md),
 [SQLite](sqlite-snapshot.md), and [MySQL](mysql-snapshot.md) support matrices.

package/docs/schema/catalog-model.md

@@ -12,7 +12,7 @@ families and an immutable materializer:
 import {
   createCompleteIntrospectionCatalog,
   mapCatalogToCompleteSnapshot,
-} from 'qubu/introspection'
+} from "qubu/introspection"
 
 const completeCatalog = createCompleteIntrospectionCatalog(catalog)
 const result = mapCatalogToCompleteSnapshot(completeCatalog)
@@ -36,10 +36,7 @@ references and are not used as logical IDs.
 `qubu/snapshot` provides the strict complete format as a separate API:
 
 ```ts
-import {
-  decodeCompleteSchemaSnapshot,
-  encodeCompleteSchemaSnapshot,
-} from 'qubu/snapshot'
+import { decodeCompleteSchemaSnapshot, encodeCompleteSchemaSnapshot } from "qubu/snapshot"
 
 const encoded = encodeCompleteSchemaSnapshot(snapshotV2)
 const decoded = decodeCompleteSchemaSnapshot(encoded)

package/docs/schema/code-generation.md

@@ -12,19 +12,19 @@ Read and map one namespace in strict mode, then pass that exact result to the
 generator:
 
 ```ts
-import { writeFile } from 'node:fs/promises'
-import { generateSchemaSource } from 'qubu/codegen'
-import { mapCatalogToSnapshot, readSqliteCatalog } from 'qubu/introspection'
+import { writeFile } from "node:fs/promises"
+import { generateSchemaSource } from "qubu/codegen"
+import { mapCatalogToSnapshot, readSqliteCatalog } from "qubu/introspection"
 
-const catalog = await readSqliteCatalog(connection, { namespace: 'main' })
-const introspection = mapCatalogToSnapshot(catalog, { namespace: 'main' })
+const catalog = await readSqliteCatalog(connection, { namespace: "main" })
+const introspection = mapCatalogToSnapshot(catalog, { namespace: "main" })
 const generated = generateSchemaSource(introspection)
 
 if (!generated.ok) {
-  throw new Error(generated.diagnostics.map(issue => issue.message).join('\n'))
+  throw new Error(generated.diagnostics.map((issue) => issue.message).join("\n"))
 }
 
-await writeFile('src/schema.generated.ts', generated.source, 'utf8')
+await writeFile("src/schema.generated.ts", generated.source, "utf8")
 ```
 
 `writeFile()` belongs to the application; `generateSchemaSource()` only
@@ -48,13 +48,13 @@ the generated module is accepted, its serialized snapshot becomes the identity
 baseline for the next catalog read:
 
 ```ts
-import { mapCatalogToSnapshot } from 'qubu/introspection'
-import { createSqliteSchemaSnapshot } from 'qubu/snapshot'
-import { mainSchema } from './schema.generated.ts'
+import { mapCatalogToSnapshot } from "qubu/introspection"
+import { createSqliteSchemaSnapshot } from "qubu/snapshot"
+import { mainSchema } from "./schema.generated.ts"
 
 const previousSnapshot = createSqliteSchemaSnapshot(mainSchema)
 const next = mapCatalogToSnapshot(nextCatalog, {
-  namespace: 'main',
+  namespace: "main",
   previousSnapshot,
 })
 ```
@@ -75,17 +75,17 @@ Use the controlled callbacks to adopt trusted names or application mappings:
 ```ts
 const generated = generateSchemaSource(introspection, {
   naming(context) {
-    if (context.kind === 'table' && context.physicalName === 'user_records') {
-      return 'users'
+    if (context.kind === "table" && context.physicalName === "user_records") {
+      return "users"
     }
   },
   mapColumn(context) {
-    if (context.columnPhysicalName === 'account_id') {
+    if (context.columnPhysicalName === "account_id") {
       return {
-        output: 'string',
-        insert: 'string',
-        update: 'string',
-        sqlDomain: 'uuid',
+        output: "string",
+        insert: "string",
+        update: "string",
+        sqlDomain: "uuid",
       }
     }
   },

package/docs/schema/columns-and-writes.md

@@ -17,9 +17,9 @@ Use `column<Output, Insert, Update>()` when the driver returns a different type
 from the type the application writes:
 
 ```ts
-import { column, integer, table, text } from 'qubu'
+import { column, integer, table, text } from "qubu"
 
-const accounts = table('accounts', {
+const accounts = table("accounts", {
   id: integer({ generated: true }),
   email: text(),
   nickname: text({ nullable: true, hasDefault: true }),
@@ -36,27 +36,19 @@ The legacy hasDefault and generated flags describe the write contract. Use
 complete metadata when schema tooling also needs the database fact:
 
 ```ts
-import {
-  boolean,
-  generatedColumn,
-  identityColumn,
-  integer,
-  table,
-  text,
-  value,
-} from 'qubu'
-import { defineSchemaExpression } from 'qubu/schema'
-
-const currentTimestamp = defineSchemaExpression('function', context => {
-  context.append('CURRENT_TIMESTAMP')
+import { boolean, generatedColumn, identityColumn, integer, table, text, value } from "qubu"
+import { defineSchemaExpression } from "qubu/schema"
+
+const currentTimestamp = defineSchemaExpression("function", (context) => {
+  context.append("CURRENT_TIMESTAMP")
 })
 
-const accounts = table('accounts', {
-  id: integer({ identity: identityColumn('always') }),
-  status: text({ default: 'pending' }),
+const accounts = table("accounts", {
+  id: integer({ identity: identityColumn("always") }),
+  status: text({ default: "pending" }),
   active: boolean({ default: true }),
   score: integer({
-    generatedColumn: generatedColumn(value(1), 'stored'),
+    generatedColumn: generatedColumn(value(1), "stored"),
   }),
   createdAt: text({
     default: currentTimestamp,
@@ -90,10 +82,10 @@ Use `$type<T>()` to narrow a helper's TypeScript type without changing its
 runtime column definition:
 
 ```ts
-import { table, text } from 'qubu'
+import { table, text } from "qubu"
 
-const users = table('users', {
-  status: text().$type<'active' | 'disabled'>(),
+const users = table("users", {
+  status: text().$type<"active" | "disabled">(),
 })
 ```
 
@@ -106,14 +98,14 @@ does not validate values at runtime or add a database constraint.
 code. The following example uses the accounts table from the earlier example:
 
 ```ts
-import type { TableInsertInput, TableUpdateInput } from 'qubu'
+import type { TableInsertInput, TableUpdateInput } from "qubu"
 
 type AccountInsert = TableInsertInput<typeof accounts.definitions>
 type AccountUpdate = TableUpdateInput<typeof accounts.definitions>
 
 const insert: AccountInsert = {
-  email: 'ada@example.com',
-  externalScore: '10',
+  email: "ada@example.com",
+  externalScore: "10",
 }
 
 const update: AccountUpdate = {