qubu 0.3.5 → 0.4.1

package/docs/guides/drizzle.md

@@ -5,11 +5,11 @@
 
 ## 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.
+Install the integration next to Qubu and Drizzle. The `@qubu/drizzle` package
+owns schema conversion; the root `qubu` package does not depend on Drizzle.
 
 ```bash
-pnpm add qubu drizzle-orm@rc
+pnpm add qubu @qubu/drizzle drizzle-orm@rc
 ```
 
 The converter supports PostgreSQL, MySQL, and SQLite with Drizzle 1.0.0-rc.4
@@ -21,29 +21,29 @@ 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'
+import { integer, schema, table, text } from "qubu"
+import { toPostgresDrizzleSchema } from "@qubu/drizzle/postgres"
 
-const users = table('user_records', {
+const users = table("user_records", {
   id: integer({ generated: true }),
   name: text(),
   nickname: text({ nullable: true }),
 })
 
-const appSchema = schema({ users }, { namespace: 'app' })
+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()`   |
+| 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
+`@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,
@@ -54,8 +54,8 @@ Use the converted tables in ordinary Drizzle queries. Table objects do not need
 to be passed to `drizzle()`:
 
 ```ts
-import { eq } from 'drizzle-orm'
-import { drizzle } from 'drizzle-orm/node-postgres'
+import { eq } from "drizzle-orm"
+import { drizzle } from "drizzle-orm/node-postgres"
 
 const db = drizzle(pool)
 
@@ -74,12 +74,12 @@ Use `sqliteTimestamp()` when an existing SQLite schema stores dates as integer
 Unix timestamps and Drizzle must continue reading and writing `Date` values:
 
 ```ts
-import { schema, table } from 'qubu'
-import { sqliteTimestamp, toSqliteDrizzleSchema } from 'qubu/drizzle/sqlite'
+import { schema, table } from "qubu"
+import { sqliteTimestamp, toSqliteDrizzleSchema } from "@qubu/drizzle/sqlite"
 
-const events = table('events', {
+const events = table("events", {
   createdAt: sqliteTimestamp({
-    mode: 'timestamp',
+    mode: "timestamp",
     defaultFn: () => new Date(),
   }),
 })
@@ -127,11 +127,11 @@ 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'
+import { nativeColumn, schema, table } from "qubu"
+import { toPostgresDrizzleSchema } from "@qubu/drizzle/postgres"
 
-const records = table('records', {
-  handle: nativeColumn('postgresql', 'CITEXT'),
+const records = table("records", {
+  handle: nativeColumn("postgresql", "CITEXT"),
 })
 
 const tables = toPostgresDrizzleSchema(schema({ records }))

package/docs/guides/extensions/dialects.md

@@ -8,12 +8,12 @@ identifiers, placeholders, or pagination:
 The examples assume a query has already been built.
 
 ```ts
-import { render } from 'qubu'
-import { createDialect } from 'qubu/core'
+import { render } from "qubu"
+import { createDialect } from "qubu/core"
 
 const colonDialect = createDialect({
-  name: 'colon',
-  placeholder: position => ':p' + position,
+  name: "colon",
+  placeholder: (position) => ":p" + position,
 })
 
 render(query, colonDialect)

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