qubu 0.3.5 → 0.4.1

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 = {

package/docs/schema/constraints-and-indexes.md

@@ -20,45 +20,38 @@ import {
   text,
   unique,
   value,
-} from 'qubu'
+} from "qubu"
 
-const accounts = table(
-  'accounts',
-  { id: integer(), slug: text() },
-  accounts => ({
-    constraints: {
-      accountsPrimary: primaryKey(accounts.id),
-    },
-    indexes: {
-      accountsSlug: index([accounts.slug], { unique: true }),
-    },
-  })
-)
+const accounts = table("accounts", { id: integer(), slug: text() }, (accounts) => ({
+  constraints: {
+    accountsPrimary: primaryKey(accounts.id),
+  },
+  indexes: {
+    accountsSlug: index([accounts.slug], { unique: true }),
+  },
+}))
 
 const memberships = table(
-  'memberships',
+  "memberships",
   {
     id: integer(),
     accountId: integer(),
     slug: text(),
     displayName: text(),
   },
-  memberships => ({
+  (memberships) => ({
     constraints: {
       membershipsPrimary: primaryKey(memberships.id),
       membershipsUnique: unique(memberships.accountId, memberships.slug),
-      membershipsAccount: foreignKey(
-        [memberships.accountId],
-        references(accounts, accounts.id)
-      ),
-      membershipsCheck: check(eq(memberships.slug, value('public'))),
+      membershipsAccount: foreignKey([memberships.accountId], references(accounts, accounts.id)),
+      membershipsCheck: check(eq(memberships.slug, value("public"))),
     },
     indexes: {
       membershipsAccountSlug: index([memberships.accountId, memberships.slug], {
         unique: true,
       }),
     },
-  })
+  }),
 )
 ```
 
@@ -81,21 +74,17 @@ Use `uniqueConstraint()` when the database enforces uniqueness but the rule shou
 not prove a functional dependency:
 
 ```ts
-import { table, text, uniqueConstraint } from 'qubu'
-
-const accounts = table(
-  'accounts',
-  { email: text({ nullable: true }) },
-  accounts => ({
-    constraints: {
-      emailUnique: uniqueConstraint(accounts.email, {
-        nulls: 'distinct',
-        physicalName: 'accounts_email_key',
-      }),
-    },
-    indexes: {},
-  })
-)
+import { table, text, uniqueConstraint } from "qubu"
+
+const accounts = table("accounts", { email: text({ nullable: true }) }, (accounts) => ({
+  constraints: {
+    emailUnique: uniqueConstraint(accounts.email, {
+      nulls: "distinct",
+      physicalName: "accounts_email_key",
+    }),
+  },
+  indexes: {},
+}))
 ```
 
 `nulls: 'distinct'` describes the common rule where multiple NULLs do not
@@ -115,20 +104,15 @@ eligible unique index. Options such as onUpdate, onDelete, match, deferrable,
 and initially remain metadata:
 
 ```ts
-const memberships = table(
-  'memberships',
-  { accountId: integer() },
-  memberships => ({
-    constraints: {
-      accountForeign: foreignKey(
-        [memberships.accountId],
-        references(accounts, accounts.id),
-        { onDelete: 'cascade', onUpdate: 'cascade' }
-      ),
-    },
-    indexes: {},
-  })
-)
+const memberships = table("memberships", { accountId: integer() }, (memberships) => ({
+  constraints: {
+    accountForeign: foreignKey([memberships.accountId], references(accounts, accounts.id), {
+      onDelete: "cascade",
+      onUpdate: "cascade",
+    }),
+  },
+  indexes: {},
+}))
 ```
 
 Use the preliminary callback table for direct self-references. Wrap the target
@@ -145,12 +129,12 @@ Grouping every column in a declared candidate key lets Qubu select other
 columns from that source:
 
 ```ts
-import { count, from, groupBy, select } from 'qubu'
+import { count, from, groupBy, select } from "qubu"
 
 const summary = select(
   { displayName: memberships.displayName, total: count() },
   from(memberships),
-  groupBy(memberships.accountId, memberships.slug)
+  groupBy(memberships.accountId, memberships.slug),
 )
 ```
 

package/docs/schema/ddl-emission.md

@@ -8,13 +8,13 @@ migration journal. Preflight runs before rendering, so a blocked or incompatible
 plan returns diagnostics and no SQL.
 
 ```ts
-import { emitMigrationPlan } from 'qubu/ddl'
-import { postgresSchemaDialect } from 'qubu/snapshot'
+import { emitMigrationPlan } from "qubu/ddl"
+import { postgresSchemaDialect } from "qubu/snapshot"
 
 const result = emitMigrationPlan(plan, postgresSchemaDialect)
 if (!result.ok) {
   // Review result.diagnostics. result.sql is an empty string.
-  throw new Error(result.diagnostics.map(item => item.message).join('\n'))
+  throw new Error(result.diagnostics.map((item) => item.message).join("\n"))
 }
 
 for (const statement of result.statements) {
@@ -44,9 +44,9 @@ produces `transaction-conflict`; no transaction is opened by the emitter.
 
 ```ts
 const result = emitMigrationPlan(plan, postgresSchemaDialect, {
-  transaction: 'managed',
-  lock: 'exclusive',
-  serverVersion: '16',
+  transaction: "managed",
+  lock: "exclusive",
+  serverVersion: "16",
 })
 ```
 

package/docs/schema/diff.md

@@ -8,7 +8,7 @@ It keeps the object kind, namespace, logical ID, physical name, dialect, path,
 and catalog evidence on every result object.
 
 ```ts
-import { diffSnapshots } from 'qubu/diff'
+import { diffSnapshots } from "qubu/diff"
 
 const result = diffSnapshots(previousSnapshot, currentSnapshot)
 
@@ -32,10 +32,10 @@ use an ID, a physical name, or an exact path when a nested scope repeats an ID.
 const result = diffSnapshots(previousSnapshot, currentSnapshot, {
   renameHints: [
     {
-      kind: 'table',
-      namespace: 'public',
-      from: 'legacy_accounts',
-      to: 'accounts',
+      kind: "table",
+      namespace: "public",
+      from: "legacy_accounts",
+      to: "accounts",
     },
   ],
 })

package/docs/schema/introspection.md

@@ -37,10 +37,10 @@ queries, authenticate, or start a transaction. Adapt the driver you already
 use to `CatalogConnection`:
 
 ```ts
-import type { CatalogConnection } from 'qubu/introspection'
+import type { CatalogConnection } from "qubu/introspection"
 
 const connection: CatalogConnection = {
-  dialect: 'sqlite',
+  dialect: "sqlite",
   query(statement, options) {
     // Adapt this call to the driver used by the application.
     return db.query(statement, options)
@@ -59,16 +59,16 @@ catalog can later support inspection, source generation, or another snapshot
 format:
 
 ```ts
-import { mapCatalogToSnapshot, readSqliteCatalog } from 'qubu/introspection'
+import { mapCatalogToSnapshot, readSqliteCatalog } from "qubu/introspection"
 
-const catalog = await readSqliteCatalog(connection, { namespace: 'main' })
+const catalog = await readSqliteCatalog(connection, { namespace: "main" })
 const result = mapCatalogToSnapshot(catalog, {
-  namespace: 'main',
-  mode: 'strict',
+  namespace: "main",
+  mode: "strict",
 })
 
 if (!result.ok) {
-  throw new Error(result.diagnostics.map(issue => issue.message).join('\n'))
+  throw new Error(result.diagnostics.map((issue) => issue.message).join("\n"))
 }
 
 result.snapshot.tables // canonical Snapshot v1 data

package/docs/schema/migration-plans.md

@@ -8,7 +8,7 @@ logical and physical identity evidence, dependency edges, preconditions, safety,
 lock and transaction requirements, and reversibility markers.
 
 ```ts
-import { createMigrationPlan } from 'qubu/migration'
+import { createMigrationPlan } from "qubu/migration"
 
 const result = createMigrationPlan(diff)
 if (!result.ok) {
@@ -31,11 +31,11 @@ kind, namespace, and path, and each decision carries a review reason.
 ```ts
 const reviewed = createMigrationPlan(diff, {
   decisions: result.plan.operations
-    .filter(operation => operation.status === 'decision-required')
-    .map(operation => ({
+    .filter((operation) => operation.status === "decision-required")
+    .map((operation) => ({
       operationId: operation.id,
-      action: 'allow',
-      reason: 'Reviewed against the deployment change request',
+      action: "allow",
+      reason: "Reviewed against the deployment change request",
     })),
 })
 ```
@@ -48,10 +48,10 @@ dialect, safety declaration, reason, reversibility, and dependency position:
 createMigrationPlan(diff, {
   customSql: [
     {
-      sql: 'ALTER TABLE accounts VALIDATE CONSTRAINT accounts_check',
-      dialect: { name: 'postgresql', version: 1 },
-      safety: 'review-required',
-      reason: 'The dialect emitter does not model this catalog fact yet',
+      sql: "ALTER TABLE accounts VALIDATE CONSTRAINT accounts_check",
+      dialect: { name: "postgresql", version: 1 },
+      safety: "review-required",
+      reason: "The dialect emitter does not model this catalog fact yet",
       reversible: false,
       position: 3,
     },

package/docs/schema/snapshots.md

@@ -8,7 +8,7 @@ hashed, checked into source control, and handed to a dialect adapter. Importing
 the snapshot entrypoint is optional; ordinary query imports do not load it.
 
 ```ts
-import { createSchemaSnapshot, encodeSchemaSnapshot } from 'qubu/snapshot'
+import { createSchemaSnapshot, encodeSchemaSnapshot } from "qubu/snapshot"
 
 const snapshot = createSchemaSnapshot(appSchema)
 const json = encodeSchemaSnapshot(snapshot)
@@ -29,12 +29,12 @@ expression retains its dialect tag and is rejected when it does not match the
 selected snapshot dialect.
 
 ```ts
-import { decodeSchemaSnapshot } from 'qubu/snapshot'
+import { decodeSchemaSnapshot } from "qubu/snapshot"
 
 const decoded = decodeSchemaSnapshot(json)
 if (!decoded.ok) {
   for (const issue of decoded.diagnostics) {
-    console.error(issue.path.join('.'), issue.code, issue.message)
+    console.error(issue.path.join("."), issue.code, issue.message)
   }
 }
 ```

package/docs/schema/storage-and-schema-sql.md

@@ -33,10 +33,10 @@ Use a dialect-native descriptor when a column needs an exact vendor
 declaration:
 
 ```ts
-import { nativeColumn, nativeStorage, table } from 'qubu'
+import { nativeColumn, nativeStorage, table } from "qubu"
 
-const accounts = table('accounts', {
-  handle: nativeColumn(nativeStorage('postgresql', 'citext COLLATE "C"')),
+const accounts = table("accounts", {
+  handle: nativeColumn(nativeStorage("postgresql", 'citext COLLATE "C"')),
 })
 ```
 
@@ -52,12 +52,12 @@ can be rendered for checks, generated columns, indexes, and other declaration
 metadata:
 
 ```ts
-import { eq, table, text } from 'qubu'
-import { renderSchemaSql } from 'qubu/schema'
+import { eq, table, text } from "qubu"
+import { renderSchemaSql } from "qubu/schema"
 
-const accounts = table('accounts', { status: text() })
+const accounts = table("accounts", { status: text() })
 
-renderSchemaSql(eq(accounts.status, 'active'), { mode: 'check' })
+renderSchemaSql(eq(accounts.status, "active"), { mode: "check" })
 // ("status" = 'active')
 ```
 
@@ -74,13 +74,13 @@ subqueries are rejected in every schema mode.
 An extension must opt into the schema contract with `defineSchemaExpression()`:
 
 ```ts
-import { defineSchemaExpression, renderSchemaSql } from 'qubu/schema'
+import { defineSchemaExpression, renderSchemaSql } from "qubu/schema"
 
-const currentDate = defineSchemaExpression('function', context => {
-  context.append('CURRENT_DATE')
+const currentDate = defineSchemaExpression("function", (context) => {
+  context.append("CURRENT_DATE")
 })
 
-renderSchemaSql(currentDate, { mode: 'default' })
+renderSchemaSql(currentDate, { mode: "default" })
 ```
 
 ## Use raw schema SQL only when necessary

package/docs/schema/tables-and-names.md

@@ -12,17 +12,17 @@ record keys become logical table IDs and stay stable when a physical SQL name
 changes:
 
 ```ts
-import { integer, schema, table, text } from 'qubu'
+import { integer, schema, table, text } from "qubu"
 
-const accounts = table('account_records', {
+const accounts = table("account_records", {
   id: integer(),
   email: text(),
 })
-const memberships = table('membership_records', {
+const memberships = table("membership_records", {
   accountId: integer(),
 })
 
-const appSchema = schema({ accounts, memberships }, { namespace: 'public' })
+const appSchema = schema({ accounts, memberships }, { namespace: "public" })
 ```
 
 appSchema.registry.accounts.id is "accounts", while the physical table name is
@@ -47,17 +47,14 @@ Write schema keys in camelCase. Qubu converts them to snake_case in SQL, then
 uses the camelCase keys in the returned row:
 
 ```ts
-import { from, select, table, timestamp, uuid } from 'qubu'
+import { from, select, table, timestamp, uuid } from "qubu"
 
-const events = table('events', {
+const events = table("events", {
   userId: uuid(),
   createdAt: timestamp(),
 })
 
-const query = select(
-  { userId: events.userId, createdAt: events.createdAt },
-  from(events)
-)
+const query = select({ userId: events.userId, createdAt: events.createdAt }, from(events))
 ```
 
 The query selects "events"."user_id" and "events"."created_at", then aliases
@@ -76,8 +73,8 @@ Prefer `userId` and `apiKey` when you control the TypeScript name. Use `sqlName`
 the database name does not follow the convention:
 
 ```ts
-const events = table('events', {
-  createdAt: timestamp({ sqlName: 'creation_timestamp' }),
+const events = table("events", {
+  createdAt: timestamp({ sqlName: "creation_timestamp" }),
 })
 ```
 
@@ -89,9 +86,9 @@ their projected names stay snake_case. Only the outer result projection uses
 camelCase aliases. Pass the database relation name explicitly:
 
 ```ts
-import { table, uuid } from 'qubu'
+import { table, uuid } from "qubu"
 
-const accounts = table('user_accounts', {
+const accounts = table("user_accounts", {
   id: uuid(),
 })
 ```

package/docs/sql-semantic-types.md

@@ -43,10 +43,10 @@ Specific result domains are still retained. `lower(textColumn)` produces
 `SqlText`, while `avg(integerColumn)` produces `SqlDecimal`:
 
 ```ts
-import { avg, integer, lower, table, text } from 'qubu'
-import type { SqlTypeOf } from 'qubu'
+import { avg, integer, lower, table, text } from "qubu"
+import type { SqlTypeOf } from "qubu"
 
-const metrics = table('metrics', {
+const metrics = table("metrics", {
   label: text(),
   sampleCount: integer(),
 })
@@ -72,15 +72,15 @@ semantics. Contextual JavaScript literals remain ergonomic for compatible
 operators:
 
 ```ts
-import { asc, eq, inList, like, lower, orderBy, table, uuid } from 'qubu'
+import { asc, eq, inList, like, lower, orderBy, table, uuid } from "qubu"
 
-const records = table('records', { id: uuid() })
+const records = table("records", { id: uuid() })
 
-eq(records.id, '108cb836-20d2-41b2-8c23-f0c94700aa7e') // valid
-inList(records.id, ['first-id', 'second-id']) // valid
+eq(records.id, "108cb836-20d2-41b2-8c23-f0c94700aa7e") // valid
+inList(records.id, ["first-id", "second-id"]) // valid
 
 lower(records.id) // TypeScript error: SqlUuid is not SqlTextLike
-like(records.id, '%uuid%') // TypeScript error: SqlUuid is not SqlTextLike
+like(records.id, "%uuid%") // TypeScript error: SqlUuid is not SqlTextLike
 orderBy(asc(records.id)) // TypeScript error: SqlUuid is not portably orderable
 ```
 
@@ -90,10 +90,10 @@ operation. This contextual typing does not relabel an expression: comparing a
 the database operation intentionally changes domains:
 
 ```ts
-import { cast, like, text } from 'qubu'
+import { cast, like, text } from "qubu"
 
 const idAsText = cast(records.id, text())
-like(idAsText, '108c%')
+like(idAsText, "108c%")
 ```
 
 Built-in definitions carry logical cast targets, so the active dialect can