qubu 0.4.0 → 0.4.2

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

@@ -8,18 +8,18 @@ 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'
+import { from, render, select, table, text } from "qubu"
+import { customClause } from "qubu/core"
 
-const users = table('users', { name: text() })
+const users = table("users", { name: text() })
 
 const fetchWithTies = customClause({
-  name: 'fetch-with-ties',
+  name: "fetch-with-ties",
   order: 100,
   render(context) {
-    context.append('FETCH FIRST ')
+    context.append("FETCH FIRST ")
     context.parameter(10)
-    context.append(' ROWS WITH TIES')
+    context.append(" ROWS WITH TIES")
   },
 })
 
@@ -41,23 +41,23 @@ shape is known to the application but cannot be declared with `table()`. Its
 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'
+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'),
+  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.append("json_each(")
     context.parameter('{"a":1}')
-    context.append(') AS ')
-    context.render(identifier('row'))
+    context.append(") AS ")
+    context.render(identifier("row"))
   },
 })
 

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

@@ -29,22 +29,18 @@ 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'
+import { cast, column } from "qubu"
+import type { SqlEqualityComparable, SqlOrderable, SqlSemanticType, SqlTextLike } from "qubu"
 
 interface SqlCitext
-  extends SqlSemanticType<'postgres.citext'>,
+  extends
+    SqlSemanticType<"postgres.citext">,
     SqlTextLike,
-    SqlOrderable<'text'>,
-    SqlEqualityComparable<'text'> {}
+    SqlOrderable<"text">,
+    SqlEqualityComparable<"text"> {}
 
 const citext = column<string, string, string, SqlCitext>({
-  castType: 'CITEXT',
+  castType: "CITEXT",
 })
 
 const nameAsCitext = cast(users.name, citext)
@@ -61,13 +57,13 @@ 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'
+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()')
+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()`

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

@@ -6,11 +6,11 @@
 modeled yet. They do not quote identifiers or bind values for you:
 
 ```ts
-import { select } from 'qubu'
-import { unsafeExpression } from 'qubu/core'
+import { select } from "qubu"
+import { unsafeExpression } from "qubu/core"
 
 const query = select({
-  today: unsafeExpression('CURRENT_DATE'),
+  today: unsafeExpression("CURRENT_DATE"),
 })
 ```
 

package/docs/guides/json.md

@@ -16,9 +16,9 @@ import {
   jsonText,
   select,
   table,
-} from 'qubu'
+} from "qubu"
 
-const events = table('events', {
+const events = table("events", {
   payload: json<{
     user?: { name?: string; active?: boolean; score?: number }
   }>(),
@@ -26,12 +26,12 @@ const events = table('events', {
 
 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')),
+    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)
+  from(events),
 )
 ```
 

package/docs/guides/mutations.md

@@ -9,9 +9,9 @@ columns accept `null` as a value, which is distinct from omitting a defaulted
 field:
 
 ```ts
-import { integer, table, text } from 'qubu'
+import { integer, table, text } from "qubu"
 
-const users = table('users', {
+const users = table("users", {
   id: integer({ generated: true }),
   name: text(),
   email: text({ nullable: true, hasDefault: true }),
@@ -27,15 +27,12 @@ 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'
+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 })
+  values({ name: "Ada", email: null }, { name: "Grace", email: "grace@example.com" }),
+  returning({ id: users.id, name: users.name }),
 )
 
 render(query)
@@ -54,13 +51,13 @@ default. Use `insertSelect(query, columns)` for an `INSERT ... SELECT` source.
 the target table:
 
 ```ts
-import { eq, returning, update, upper, where } from 'qubu'
+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 })
+  returning({ id: users.id, name: users.name }),
 )
 ```
 
@@ -71,15 +68,15 @@ 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'
+import { eq, omit, update, where } from "qubu"
 
 const query = update(
   users,
   {
-    name: rename ? 'Archived' : omit,
+    name: rename ? "Archived" : omit,
     email: clearEmail ? null : omit,
   },
-  where(eq(users.id, 7))
+  where(eq(users.id, 7)),
 )
 ```
 
@@ -93,13 +90,9 @@ remain source- and capability-aware even when their runtime alternative is
 ## Delete with a predicate
 
 ```ts
-import { deleteFrom, eq, returning, where } from 'qubu'
+import { deleteFrom, eq, returning, where } from "qubu"
 
-const query = deleteFrom(
-  users,
-  where(eq(users.id, 8)),
-  returning({ id: users.id })
-)
+const query = deleteFrom(users, where(eq(users.id, 8)), returning({ id: users.id }))
 ```
 
 ## Keep unrestricted writes explicit
@@ -108,9 +101,9 @@ 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'
+import { allowAll, update } from "qubu"
 
-const query = update(users, { name: 'Archived' }, allowAll())
+const query = update(users, { name: "Archived" }, allowAll())
 ```
 
 `allowAll()` is a safety boundary, not a replacement for authorization or

package/docs/guides/select/conditions.md

@@ -11,14 +11,14 @@ 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'
+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))
+  userId === undefined ? omit : where(eq(users.id, userId)),
 )
 ```
 
@@ -29,14 +29,12 @@ 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'
+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 filter = where(and(eq(users.id, 7), includeName ? eq(users.name, "Ada") : omit))
 const ordering = orderBy(newestFirst ? desc(users.name) : omit)
 ```
 
@@ -56,7 +54,7 @@ const query = select(
     id: users.id,
     email: includeEmail ? users.email : omit,
   },
-  from(users)
+  from(users),
 )
 
 // typeof query.row:
@@ -82,7 +80,7 @@ separate queries when those structural parts differ at runtime.
 Equality with `null` is translated to the SQL null predicate:
 
 ```ts
-import { eq, isDistinctFrom, ne } from 'qubu'
+import { eq, isDistinctFrom, ne } from "qubu"
 
 eq(users.name, null) // ... IS NULL
 ne(users.name, null) // ... IS NOT NULL

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

@@ -11,18 +11,7 @@ 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'
+import { count, desc, eq, from, groupBy, gt, having, leftJoin, orderBy, select } from "qubu"
 
 const counts = select(
   {
@@ -33,7 +22,7 @@ const counts = select(
   leftJoin(posts, eq(users.id, posts.authorId)),
   groupBy(users.name),
   having(gt(count(posts.id), 0)),
-  orderBy(desc(count(posts.id)))
+  orderBy(desc(count(posts.id))),
 )
 ```
 
@@ -52,7 +41,7 @@ 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'
+import { desc, from, over, rowNumber, select } from "qubu"
 
 const rankedUsers = select(
   {
@@ -62,7 +51,7 @@ const rankedUsers = select(
       orderBy: [desc(users.id)],
     }),
   },
-  from(users)
+  from(users),
 )
 ```
 

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

@@ -9,13 +9,9 @@ The examples use the `users` table from [Build a `SELECT`](overview.md).
 Wrap ordering terms in `orderBy()`:
 
 ```ts
-import { desc, from, orderBy, select } from 'qubu'
+import { desc, from, orderBy, select } from "qubu"
 
-const ordered = select(
-  { id: users.id, name: users.name },
-  from(users),
-  orderBy(desc(users.name))
-)
+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
@@ -26,16 +22,7 @@ identifier quoting and any dialect-specific ordering syntax.
 Choose `fetchFirst()` or `offset()` for pagination:
 
 ```ts
-import {
-  desc,
-  eq,
-  fetchFirst,
-  from,
-  offset,
-  orderBy,
-  select,
-  where,
-} from 'qubu'
+import { desc, eq, fetchFirst, from, offset, orderBy, select, where } from "qubu"
 
 const page = select(
   { id: users.id, name: users.name },
@@ -43,7 +30,7 @@ const page = select(
   where(eq(users.id, 7)),
   orderBy(desc(users.name)),
   offset(20),
-  fetchFirst(20)
+  fetchFirst(20),
 )
 ```
 
@@ -54,14 +41,14 @@ pagination. The active dialect decides whether pagination uses standard
 Pair a pagination clause with `omit` when the row bound is optional at runtime:
 
 ```ts
-import { fetchFirst, omit } from 'qubu'
+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)
+  pageSize === undefined ? omit : fetchFirst(pageSize),
 )
 ```
 

package/docs/guides/select/overview.md

@@ -9,19 +9,15 @@ 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'
+import { eq, from, integer, render, select, table, text, where } from "qubu"
 
-const users = table('users', {
+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))
-)
+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" = ?)
@@ -34,12 +30,9 @@ named projection object, so it can still be spread alongside computed
 expressions:
 
 ```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))
 ```
 
 `all(source)` expands to explicit named columns rather than emitting
@@ -66,9 +59,9 @@ import {
   text,
   integer,
   where,
-} from 'qubu'
+} from "qubu"
 
-const posts = table('posts', {
+const posts = table("posts", {
   id: integer(),
   authorId: integer(),
   title: text(),
@@ -78,7 +71,7 @@ const query = select(
   { userId: users.id, title: posts.title },
   from(users),
   innerJoin(posts, eq(users.id, posts.authorId)),
-  where(isNotNull(users.email))
+  where(isNotNull(users.email)),
 )
 ```
 
@@ -98,7 +91,7 @@ const summary = select(
     postCount: count(posts.id),
   },
   from(users),
-  leftJoin(posts, eq(users.id, posts.authorId))
+  leftJoin(posts, eq(users.id, posts.authorId)),
 )
 
 // typeof summary.row:
@@ -108,18 +101,11 @@ const summary = select(
 Compose boolean expressions explicitly:
 
 ```ts
-import { and, gt, inList, or } from 'qubu'
+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 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)
-)
+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

package/docs/guides/sql-templates.md

@@ -9,11 +9,11 @@ substitution as a parameter. This includes strings, numbers, objects, arrays,
 and `null`:
 
 ```ts
-import { integer, render, sql, table, text } from 'qubu'
+import { integer, render, sql, table, text } from "qubu"
 
-const users = table('users', { name: text() })
-const posts = table('posts', { id: integer() })
-const search = 'Ada%'
+const users = table("users", { name: text() })
+const posts = table("posts", { id: integer() })
+const search = "Ada%"
 const predicate = sql`${users.name} LIKE ${search}`
 
 render(predicate)
@@ -33,16 +33,12 @@ 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'
+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 selectedNames = select({ displayName: users.name }, from(users), where(eq(users.name, "Ada")))
 
-const exists = sql`EXISTS (${selectedNames}) AND ${users.name} <> ${'root'}`
+const exists = sql`EXISTS (${selectedNames}) AND ${users.name} <> ${"root"}`
 
 render(exists, postgresDialect())
 // {
@@ -62,8 +58,8 @@ An unannotated template has application output `unknown` and SQL domain
 named projection:
 
 ```ts
-import { from, select, sql } from 'qubu'
-import type { SqlText } from 'qubu'
+import { from, select, sql } from "qubu"
+import type { SqlText } from "qubu"
 
 const normalizedName = sql.type<string, SqlText>()`LOWER(${users.name})`
 
@@ -98,11 +94,11 @@ Do not use a dotted string as an identifier. Pass each part to
 syntax that cannot use a fixed template segment:
 
 ```ts
-import { sql } from 'qubu'
-import { identifier, unsafeExpression } from 'qubu/core'
+import { sql } from "qubu"
+import { identifier, unsafeExpression } from "qubu/core"
 
-const sortColumn = 'display_name'
-const direction = 'DESC' as const
+const sortColumn = "display_name"
+const direction = "DESC" as const
 
 const ordering = sql`ORDER BY ${identifier(sortColumn)} ${unsafeExpression(direction)}`
 ```
@@ -120,8 +116,8 @@ 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'
+import { count, sql } from "qubu"
+import type { SqlInteger } from "qubu"
 
 const postCount = sql.type<number, SqlInteger>()`${count(posts.id)}`
 ```
@@ -140,13 +136,13 @@ 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'
+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'
+  "ilike",
 )
 ```
 

package/docs/guides/vite-plugin.md

@@ -11,8 +11,8 @@ 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'
+import { defineConfig } from "vite"
+import { qubu } from "qubu/vite"
 
 export default defineConfig({
   plugins: [qubu()],
@@ -36,24 +36,20 @@ ambient value and type declarations for the TypeScript compiler.
 Put the directive in the module's initial directive prologue:
 
 ```ts
-'use qubu'
+"use qubu"
 
-const users = table('users', {
+const users = table("users", {
   id: integer(),
   name: text(),
 })
 
-const query = select(
-  { id: users.id, name: users.name },
-  from(users),
-  where(eq(users.id, 42))
-)
+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'
+import { eq, from, integer, select, table, text, where } from "qubu"
 ```
 
 Existing imports remain valid. The transform does not rewrite member properties,
@@ -63,10 +59,10 @@ strings, comments, or names outside the public Qubu global catalog.
 
 ```ts
 qubu({
-  module: 'qubu',
-  include: id => id.includes('/src/'),
+  module: "qubu",
+  include: (id) => id.includes("/src/"),
   exclude: /\.stories\./,
-  globals: ['select', 'from', 'where', 'eq', 'table'],
+  globals: ["select", "from", "where", "eq", "table"],
 })
 ```
 

package/docs/index.md

@@ -29,6 +29,8 @@ define a table, build a `SELECT`, and inspect its SQL and parameters.
   `DELETE` statements.
 - [Use Qubu tables with Drizzle](guides/drizzle.md) while moving query call
   sites without duplicating schema declarations.
+- [Use Qubu with Better Auth](guides/better-auth.md) with plugin-aware schema
+  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.
@@ -82,18 +84,14 @@ needs to preserve a fact across composition:
 ## A small example
 
 ```ts
-import { eq, from, integer, render, select, table, text, where } from 'qubu'
+import { eq, from, integer, render, select, table, text, where } from "qubu"
 
-const users = table('users', {
+const users = table("users", {
   id: integer(),
   name: text(),
 })
 
-const query = select(
-  { id: users.id, name: users.name },
-  from(users),
-  where(eq(users.id, 7))
-)
+const query = select({ id: users.id, name: users.name }, from(users), where(eq(users.id, 7)))
 
 render(query)
 // {