qubu 0.0.0 → 0.3.4

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

@@ -0,0 +1,106 @@
+# Tables and names
+
+> Define query-facing tables, keep their TypeScript identities stable, and control how fields become SQL names.
+
+`table()` definitions describe the columns Qubu can select and write. They are
+not database introspection and they do not create or migrate a database.
+
+## Register tables under stable IDs
+
+Use `schema()` when several table declarations belong to one database model. The
+record keys become logical table IDs and stay stable when a physical SQL name
+changes:
+
+```ts
+import { integer, schema, table, text } from 'qubu'
+
+const accounts = table('account_records', {
+  id: integer(),
+  email: text(),
+})
+const memberships = table('membership_records', {
+  accountId: integer(),
+})
+
+const appSchema = schema({ accounts, memberships }, { namespace: 'public' })
+```
+
+appSchema.registry.accounts.id is "accounts", while the physical table name is
+"account_records". Registering the table does not change its query source, SQL
+rendering, or row and mutation types. The namespace belongs to schema metadata
+and is not added to ordinary queries.
+
+The registry is immutable. Qubu validates duplicate IDs, duplicate physical
+names, invalid namespaces, and collisions in generated names before returning
+the model. A failed registry construction throws `SchemaValidationError`; its
+diagnostics array contains every invalid path.
+
+The generated-name policy is versioned. Import `generatedTableName()` from
+`qubu/schema` when a schema tool needs to preview the policy. It returns
+`user_id` for `userId` under policy version 1. Explicit names passed to
+`table()` remain unchanged. The policy gives snapshot encoders stable names
+without changing TypeScript source identity.
+
+## Map field names to SQL
+
+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'
+
+const events = table('events', {
+  userId: uuid(),
+  createdAt: timestamp(),
+})
+
+const query = select(
+  { userId: events.userId, createdAt: events.createdAt },
+  from(events)
+)
+```
+
+The query selects "events"."user_id" and "events"."created_at", then aliases
+them as "userId" and "createdAt" for the returned row. Inserts and updates
+accept the same camelCase keys.
+
+Acronym boundaries are preserved:
+
+| TypeScript key | SQL name         |
+| -------------- | ---------------- |
+| userID         | user_id          |
+| APIKey         | api_key          |
+| XMLHttpRequest | xml_http_request |
+
+Prefer `userId` and `apiKey` when you control the TypeScript name. Use `sqlName` when
+the database name does not follow the convention:
+
+```ts
+const events = table('events', {
+  createdAt: timestamp({ sqlName: 'creation_timestamp' }),
+})
+```
+
+Qubu rejects fields that resolve to the same SQL name, such as `userId` and
+userID in one table.
+
+CTEs, derived tables, lateral queries, and subqueries remain SQL relations, so
+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'
+
+const accounts = table('user_accounts', {
+  id: uuid(),
+})
+```
+
+## Read next
+
+- [Column behavior and write types](columns-and-writes.md) covers nullability,
+  defaults, generated columns, and application types.
+- [Constraints, keys, and indexes](constraints-and-indexes.md) covers the
+  metadata used by grouping and schema checks.
+- [Storage and schema SQL](storage-and-schema-sql.md) covers physical storage
+  and deterministic schema expressions.

package/docs/sql-semantic-types.md

@@ -0,0 +1,141 @@
+# SQL semantic types
+
+> Use SQL domains to constrain valid query composition without conflating database semantics with driver-decoded application values.
+
+Qubu tracks four independent facts for a field or result expression:
+
+| Fact            | Question it answers                                       | Example                   |
+| --------------- | --------------------------------------------------------- | ------------------------- |
+| JavaScript type | What value does the driver give the application?          | `string`                  |
+| Write types     | What values may an insert or update accept?               | `string`, `Date`, or both |
+| Nullability     | Can the selected value be `null`?                         | `false`                   |
+| SQL domain      | Which portable SQL operations may consume the expression? | `SqlText` or `SqlUuid`    |
+
+The axes are deliberately separate. Both `text()` and `uuid()` decode to a
+JavaScript `string`, but their SQL behavior differs. Likewise, two
+`timestamp()` definitions may share `SqlTimestamp` while a custom column uses
+different JavaScript output and write types for its driver.
+
+## Built-in domains and capabilities
+
+Schema helpers attach these portable semantic domains:
+
+| Helpers       | SQL domain     | Portable capabilities               |
+| ------------- | -------------- | ----------------------------------- |
+| `text()`      | `SqlText`      | text, equality, ordering            |
+| `uuid()`      | `SqlUuid`      | equality                            |
+| `integer()`   | `SqlInteger`   | numeric, equality, numeric ordering |
+| `numeric()`   | `SqlDecimal`   | numeric, equality, numeric ordering |
+| `boolean()`   | `SqlBoolean`   | equality                            |
+| `date()`      | `SqlDate`      | equality, date ordering             |
+| `timestamp()` | `SqlTimestamp` | equality, timestamp ordering        |
+| `json<T>()`   | `SqlJson<T>`   | no portable comparison capability   |
+| `bigint()`    | `SqlBigInt`    | numeric, equality, numeric ordering |
+| `binary()`    | `SqlBinary`    | equality                            |
+
+Capabilities describe portable operation families. `SqlTextLike` is accepted
+by text functions and pattern matching, `SqlNumericLike` by arithmetic and
+numeric aggregates, and `SqlOrderable<Group>` by ordering operations. Equality
+and ordering groups allow related domains to interoperate: `SqlInteger` and
+`SqlDecimal` share the `numeric` group, for example.
+
+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'
+
+const metrics = table('metrics', {
+  label: text(),
+  sampleCount: integer(),
+})
+
+const normalized = lower(metrics.label)
+type LowerDomain = SqlTypeOf<typeof normalized>
+// SqlText
+
+const mean = avg(metrics.sampleCount)
+type MeanDomain = SqlTypeOf<typeof mean>
+// SqlDecimal
+```
+
+`SqlTypeOf<T>` reads the domain of any result-bearing expression. Named query
+projections retain a map of domains through `QuerySqlTypeMap<T>`; aliases,
+CTEs, LATERAL sources, scalar subqueries, set operations, and mutation
+`RETURNING` projections carry those domains forward.
+
+## UUID is not text-like
+
+A UUID may be decoded as a JavaScript string without acquiring SQL text
+semantics. Contextual JavaScript literals remain ergonomic for compatible
+operators:
+
+```ts
+import { asc, eq, inList, like, lower, orderBy, table, uuid } from 'qubu'
+
+const records = table('records', { id: uuid() })
+
+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
+orderBy(asc(records.id)) // TypeScript error: SqlUuid is not portably orderable
+```
+
+Plain JavaScript operands take their domain from the typed expression in that
+operation. This contextual typing does not relabel an expression: comparing a
+`SqlUuid` expression with a `SqlText` expression is still rejected. Cast when
+the database operation intentionally changes domains:
+
+```ts
+import { cast, like, text } from 'qubu'
+
+const idAsText = cast(records.id, text())
+like(idAsText, '108c%')
+```
+
+Built-in definitions carry logical cast targets, so the active dialect can
+render `TEXT`, MySQL `CHAR`, or another configured spelling while the result
+remains `string`/`SqlText`. Use a custom definition or `typedCast()` when the
+target is vendor-specific.
+
+## Known incompatibility is rejected
+
+Qubu checks capabilities and compatibility when it knows both SQL domains.
+Arithmetic and `SUM`/`AVG` require numeric-like expressions; text functions,
+concatenation, `LIKE`, and PostgreSQL `ILIKE` require text-like expressions;
+ordering and range comparisons require compatible ordering groups; and
+equality, `IN`, `CASE`, `COALESCE`, and set-operation fields require compatible
+equality groups. Boolean clauses require a boolean SQL domain.
+
+These checks model portable capability and group relationships, not every
+database's implicit casts. An expression accepted by one database after an
+implicit conversion may therefore need an explicit typed cast in portable
+Qubu code.
+
+## Unknown domains preserve compatibility
+
+`column()`, `value()`, `call()`, and untyped custom expressions default to
+`SqlUnknown`. Unknown is intentionally permissive, so existing extensions keep
+composing while authors adopt semantic types incrementally:
+
+```ts
+const legacyId = column<string>()
+// ColumnSqlType<typeof legacyId> is SqlUnknown
+```
+
+`SqlUnknown` is an escape hatch, not evidence about the database. Prefer a
+declared domain for reusable extensions so incompatible composition fails at
+the call site. See [Typed expressions](guides/extensions/typed-expressions.md#declare-a-custom-sql-domain)
+for custom domains, functions, values, casts, and raw expressions.
+
+## Static metadata is not database proof
+
+SQL semantic domains affect TypeScript only. A definition used explicitly as a
+cast target also contributes a logical or named runtime target. Those domains
+do not inspect the database, prove a migration safe, select a wire encoding, or
+verify that the rendered type name exists. The application remains responsible
+for keeping table definitions aligned with the database, and the driver
+adapter remains responsible for encoding parameters and decoding rows.

package/docs/troubleshooting.md

@@ -0,0 +1,151 @@
+# Troubleshooting
+
+> Start from the observed error or output, verify the boundary that produced it, and apply the smallest fix that changes the result.
+
+## Column is not available in this query scope
+
+Qubu found a column whose source is not in `FROM` or `JOIN` clauses.
+Read [Source scope](query-model/source-scope.md) for the source
+identity rules behind this error.
+
+Check that the query includes the original source or use the columns exposed by
+the alias, CTE, or derived table you actually placed in the query:
+
+```ts
+import { alias, from, select } from 'qubu'
+
+const author = alias(users, 'author')
+
+select({ name: author.name }, from(author))
+```
+
+`author.name` is valid in this query; `users.name` is a different source
+identity after aliasing.
+
+## UPDATE/DELETE requires a WHERE
+
+This is the default mutation safety check. Add a source-aware predicate:
+
+```ts
+import { deleteFrom, eq, update, where } from 'qubu'
+
+update(users, { name: 'Ada' }, where(eq(users.id, 7)))
+deleteFrom(users, where(eq(users.id, 8)))
+```
+
+If every row is intentionally affected, pass `allowAll()` explicitly and keep
+that decision close to the authorization or maintenance code that justifies
+it.
+
+## scalar() requires one selected column
+
+A scalar subquery must return one selected field. Reduce the projection before
+calling `scalar()`:
+
+```ts
+import { from, scalar, select } from 'qubu'
+
+const idQuery = select({ id: users.id }, from(users))
+const idExpression = scalar(idQuery)
+```
+
+Use a normal derived table or CTE when the nested query needs multiple fields.
+For scalar result nullability, see [Result shapes and cardinality](query-model/result-shapes.md).
+
+## Placeholders do not match the driver
+
+Render with the dialect that the adapter expects and inspect both fields of the
+result:
+
+```ts
+import { render } from 'qubu'
+import { postgresDialect } from 'qubu/postgres'
+
+const statement = render(query, postgresDialect())
+console.log(statement.text)
+console.log(statement.parameters)
+```
+
+`statement.parameters` is ordered to match the placeholders in `statement.text`.
+Do not interpolate the values into the text or use a PostgreSQL dialect with a
+driver that expects `?` placeholders.
+
+## Read and repair query diagnostics
+
+Type-level query failures carry stable properties in the diagnostic type, and
+runtime authoring failures throw `QueryValidationError`. Read the code, context,
+path, and hint before changing the query. The hint names the repair boundary;
+the path points to the clause or field that needs attention.
+
+```ts
+import { QueryValidationError, fetchFirst } from 'qubu'
+
+try {
+  fetchFirst(-1)
+} catch (error) {
+  if (error instanceof QueryValidationError) {
+    console.error(error.code, error.context, error.path, error.hint)
+  }
+}
+```
+
+TypeScript diagnostics expose the same names through `QueryTypeValidation`:
+`__qubu_error_code__`, `__qubu_error_context__`, and
+`__qubu_error_hint__`. Treat those fields as the repair contract. Do not cast
+away a failed query type just to reach rendering.
+
+| Code                         | Usual repair                                                                 |
+| ---------------------------- | ---------------------------------------------------------------------------- |
+| `invalid-selection`          | Give `select()` at least one valid projected field.                          |
+| `duplicate-clause`           | Keep one instance of a clause that Qubu allows only once.                    |
+| `invalid-mutation`           | Fix the mutation shape before rendering it.                                  |
+| `unsafe-mutation`            | Add `where(...)` or opt into `allowAll()` deliberately.                      |
+| `invalid-update`             | Use target-table columns and valid assignment values.                        |
+| `invalid-insert`             | Supply required target columns and no unknown columns.                       |
+| `invalid-comparison`         | Use operands with compatible nullability or SQL domains.                     |
+| `invalid-boolean-expression` | Pass a boolean expression to `where()`, `having()`, or boolean operators.    |
+| `invalid-pagination`         | Pass a non-negative integer to `offset()`, `fetchFirst()`, or `fetchNext()`. |
+| `invalid-json-path`          | Use string object keys and non-negative integer array indexes.               |
+| `missing-source`             | Add the owning source with `from()`, a join, or intentional `correlate()`.   |
+| `invalid-grouping`           | Group visible dependencies or project them through an aggregate.             |
+| `incompatible-sql-domain`    | Use an expression with the required SQL capability.                          |
+| `incompatible-sql-equality`  | Compare values from the same SQL equality group.                             |
+| `incompatible-sql-order`     | Compare or order values from the same SQL ordering group.                    |
+| `incompatible-set-domain`    | Make corresponding set-operation fields use compatible domains.              |
+| `invalid-subquery`           | Give `scalar()` or `inQuery()` the required field count and shape.           |
+| `invalid-omission`           | Use `omit` only for a conditional projection or supported query clause.      |
+| `missing-dialect-capability` | Render with a dialect that advertises the query's required capability.       |
+
+After the smallest source or clause fix, run the type check again, then render
+the query with the adapter's dialect and inspect `text` and `parameters`
+together.
+
+## A Vite global is undefined or missing from TypeScript
+
+Verify all three opt-ins:
+
+1. The Vite config includes `qubu()` from `qubu/vite`.
+2. The source module starts its directive prologue with `'use qubu'` (after any
+   other directive is also supported).
+3. TypeScript includes `qubu/globals` in its `types` list or includes the
+   declaration explicitly.
+
+The transform skips non-script files, dependencies under `node_modules`, files
+excluded by filters, and modules that reference no eligible Qubu global.
+
+## Parameters are in an unexpected order
+
+`select()` accepts clauses as independent values and normalizes their SQL
+placement. Rendering traverses that normalized statement, so inspect the final
+`text` and `parameters` together rather than assuming source argument order:
+
+```ts
+import { eq, fetchFirst, from, render, select, where } from 'qubu'
+
+const statement = render(
+  select({ id: users.id }, from(users), where(eq(users.id, 7)), fetchFirst(10))
+)
+```
+
+The `WHERE` parameter renders before the pagination parameter because the SQL
+text places `WHERE` before pagination.

package/package.json

@@ -1,13 +1,135 @@
 {
   "name": "qubu",
-  "version": "0.0.0",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "0.3.4",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aleclarson/qubu"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "docs",
+    "skills"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./codegen": {
+      "types": "./dist/codegen.d.mts",
+      "import": "./dist/codegen.mjs"
+    },
+    "./core": {
+      "types": "./dist/core.d.mts",
+      "import": "./dist/core.mjs"
+    },
+    "./ddl": {
+      "types": "./dist/ddl.d.mts",
+      "import": "./dist/ddl.mjs"
+    },
+    "./diff": {
+      "types": "./dist/diff.d.mts",
+      "import": "./dist/diff.mjs"
+    },
+    "./drizzle": {
+      "types": "./dist/drizzle.d.mts",
+      "import": "./dist/drizzle.mjs"
+    },
+    "./introspection": {
+      "types": "./dist/introspection.d.mts",
+      "import": "./dist/introspection.mjs"
+    },
+    "./migration": {
+      "types": "./dist/migration.d.mts",
+      "import": "./dist/migration.mjs"
+    },
+    "./mysql": {
+      "types": "./dist/mysql.d.mts",
+      "import": "./dist/mysql.mjs"
+    },
+    "./postgres": {
+      "types": "./dist/postgres.d.mts",
+      "import": "./dist/postgres.mjs"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.mts",
+      "import": "./dist/schema.mjs"
+    },
+    "./snapshot": {
+      "types": "./dist/snapshot.d.mts",
+      "import": "./dist/snapshot.mjs"
+    },
+    "./sqlite": {
+      "types": "./dist/sqlite.d.mts",
+      "import": "./dist/sqlite.mjs"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.mts",
+      "import": "./dist/vite.mjs"
+    },
+    "./package.json": "./package.json",
+    "./drizzle/mysql": {
+      "types": "./dist/drizzle-mysql.d.mts",
+      "import": "./dist/drizzle-mysql.mjs"
+    },
+    "./drizzle/postgres": {
+      "types": "./dist/drizzle-postgres.d.mts",
+      "import": "./dist/drizzle-postgres.mjs"
+    },
+    "./drizzle/sqlite": {
+      "types": "./dist/drizzle-sqlite.d.mts",
+      "import": "./dist/drizzle-sqlite.mjs"
+    },
+    "./globals": {
+      "types": "./dist/vite/ambient.d.ts"
+    }
+  },
+  "prettier": "@alloc/prettier-config",
+  "devDependencies": {
+    "@alloc/prettier-config": "^1.0.0",
+    "@pg-nano/pg-tmp": "^2.0.3",
+    "@types/bun": "^1.3.0",
+    "@types/node": "^24.6.2",
+    "@types/pg": "^8.23.1",
+    "drizzle-orm": "1.0.0-rc.4",
+    "lildocs": "^0.1.27",
+    "mysql2": "^3.23.4",
+    "pg": "^8.23.0",
+    "picospawn": "^0.3.10",
+    "prettier": "^3.6.2",
+    "qubu": "link:",
+    "radashi": "^12.6.2",
+    "tinyglobby": "^0.2.15",
+    "tsdown": "^0.22.14",
+    "type-fest": "^5.0.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.0.0"
   },
-  "keywords": [],
-  "author": "",
-  "license": "MIT",
-  "type": "commonjs"
-}
+  "peerDependencies": {
+    "drizzle-orm": "^1.0.0-rc.4"
+  },
+  "peerDependenciesMeta": {
+    "drizzle-orm": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check:package": "node ./scripts/test-package.mjs --check-built",
+    "playground": "bun run ./playground/playground.ts",
+    "test": "vitest",
+    "test:e2e": "vitest --run test/e2e/dialects.test.ts",
+    "test:type-performance": "node ./scripts/test-type-performance.mjs",
+    "diff-check": "vitest --run test/diff.test.ts test/migration.test.ts",
+    "test:bun": "node ./scripts/test-package.mjs --runtime=bun",
+    "test:package": "node ./scripts/test-package.mjs",
+    "test:package:node": "node ./scripts/test-package.mjs --runtime=node",
+    "typecheck": "vitest --typecheck --run",
+    "typecheck:playground": "tsc --project ./playground/tsconfig.json",
+    "lint": "prettier --check . && npm run typecheck"
+  }
+}

package/skills/qubu/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: qubu
+description: Route Qubu query, schema, and repair work to the exact installed package's canonical docs. Use when a project depends on Qubu and the task needs product guidance rather than a generic SQL answer.
+---
+
+# Qubu
+
+Use the documentation shipped with the Qubu package in the current project.
+Resolve the package first so the guidance matches the installed version:
+
+```sh
+node -e "const path=require.resolve('qubu/package.json'); console.log(require('node:path').join(require('node:path').dirname(path), 'docs'))"
+```
+
+If resolution fails, Qubu is not installed in the current project. Do not use
+docs from another checkout or version as a substitute.
+
+Read the smallest page that matches the task:
+
+- first query or canonical `SELECT` style: `docs/getting-started.md` or
+  `docs/guides/select/overview.md`
+- optional predicates, result shape, cardinality, or query composition:
+  `docs/guides/select/conditions.md`, `docs/query-model/result-shapes.md`, or
+  `docs/guides/compose-queries.md`
+- `INSERT`, `UPDATE`, or `DELETE`: `docs/guides/mutations.md`
+- a compile-time or runtime query failure: `docs/troubleshooting.md`
+- schema metadata or storage: `docs/schema/tables-and-names.md`,
+  `docs/schema/columns-and-writes.md`, or
+  `docs/schema/storage-and-schema-sql.md`
+- snapshots or catalog reads: `docs/schema/snapshots.md` or
+  `docs/schema/introspection.md`
+- snapshot comparison or migration planning:
+  `docs/schema/diff.md` or `docs/schema/migration-plans.md`
+- approved-plan DDL emission: `docs/schema/ddl-emission.md`
+- custom expressions, sources, clauses, or dialects: the matching page under
+  `docs/guides/extensions/`
+- package ownership or entrypoint selection: `docs/reference/supported-surface.md`
+
+Follow the page's root/core/schema ownership and use its examples as the
+canonical source style. If the task spans concerns, read the smallest page for
+each concern and keep the installed package's `docs/` directory as the only
+product reference. Do not recreate API inventories or examples in this skill.

package/skills/qubu/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: 'Qubu'
+  short_description: 'Route Qubu work to package docs'
+  default_prompt: 'Use $qubu to find the smallest canonical Qubu guide for this task.'
+policy:
+  allow_implicit_invocation: true

package/readme.md

@@ -1 +0,0 @@
-Coming soon...