rado 1.2.1 → 1.3.0-preview.1

package/README.md

@@ -3,332 +3,238 @@
 
 # rado
 
-Fully typed, lightweight TypeScript query builder.
+A fully typed, lightweight TypeScript query builder for SQLite, PostgreSQL and
+MySQL.
+
+```ts
+import {eq} from 'rado'
+
+const greatPosts = await db.select().from(Post).where(eq(Post.rating, 5))
+```
+
+If you've used [Drizzle ORM](https://orm.drizzle.team), the code above looks
+familiar. That's intentional. Rado deliberately aligns its query building
+syntax with Drizzle, while making a few different choices under the hood:
+simpler types, immutable queries, a much smaller footprint and queries that can
+run on any of the supported databases. Read about the project's history in
+[Taking the Drizzle challenge](https://ben.mk/notes/taking-the-drizzle-challenge).
 
 ## Features
 
-- Fully typed queries using TypeScript
-- Composable and reusable query structures
-- First-class support for JSON columns
-- No code generation step required
-- Zero dependencies
-- Universal query support for multiple database engines
+- **Fully typed**: schema definitions drive query and result types, with
+  plain, readable TypeScript types
+- **Immutable queries**: every method returns a new query, so you can branch
+  and reuse query fragments without surprises
+- **Universal queries**: write a query once, run it on SQLite, PostgreSQL or
+  MySQL, chosen at runtime
+- **First-class JSON columns**: select and filter on typed JSON fields with
+  plain property access
+- **`include` instead of an ORM**: fetch related rows as nested arrays or
+  objects inside the query builder, no relations setup required
+- **Auto-migrations**: diff your schema against the database and update it
+  anywhere, including the browser
+- **Zero dependencies, small bundle**: `rado` + the PostgreSQL utilities
+  bundle to roughly 8.5 kB gzipped
+- **No code generation step**: your schema is just TypeScript
 
 ## Installation
 
-<pre>npm install <a href="https://www.npmjs.com/package/rado">rado</a></pre>
+```sh
+npm install rado
+```
 
-## Quick Start
+Rado is also published on JSR as [@rado/rado](https://jsr.io/@rado/rado) for
+Deno users.
 
-```typescript
-import {table} from 'rado'
-import {text, integer} from 'rado/postgres'
+## Quick start
+
+```ts
+import {eq} from 'rado'
+import {integer, pgTable, text} from 'rado/postgres'
 import {connect} from 'rado/driver/pg'
 import {Pool} from 'pg'
 
-// Define your schema
-const User = table("user", {
-  id: integer().primaryKey(),
+// Define a schema
+const User = pgTable('user', {
+  id: integer().primaryKey().generatedAlwaysAsIdentity(),
   name: text().notNull(),
   email: text().unique()
 })
 
-// Connect to the database
-const db = connect(new Pool({
-  host: 'localhost',
-  database: 'my_database'
-}))
+// Connect a database
+const db = connect(new Pool({connectionString: process.env.DATABASE_URL}))
 
-// Perform a query
-const users = await db.select().from(User)
-console.log(users)
-```
+// Create the table and start querying
+await db.create(User)
+
+await db.insert(User).values({name: 'Ada', email: 'ada@example.com'})
 
-## Supported Databases
+const users = await db.select().from(User).where(eq(User.name, 'Ada'))
+```
 
-Currently supported drivers:
+## Documentation
 
-| `PostgreSQL              ` | `import                      ` |
-| -------------------------- | ------------------------------ |
-| pg                         | rado/driver/pg                 |
-| @electric-sql/pglite       | rado/driver/pglite             |
-| @neondatabase/serverless   | rado/driver/pg                 |
-| @vercel/postgres           | rado/driver/pg                 |
+The full documentation lives in [docs](docs/README.md). A map of the territory:
 
-| `SQLite                  ` | `import                      ` |
-| -------------------------- | ------------------------------ |
-| better-sqlite3             | rado/driver/better-sqlite3     |
-| bun:sqlite                 | rado/driver/bun-sqlite         |
-| sql.js                     | rado/driver/sql.js             |
-| @libsql/client             | rado/driver/libsql             |
-| Cloudflare D1              | rado/driver/d1                 |
+| Section                                                             | What's inside                                                                                                                                                                             |
+| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Getting started](docs/getting-started.md)                          | Install, connect, define a schema, run your first queries                                                                                                                                 |
+| [Drivers](docs/drivers.md)                                          | Every supported driver and how to connect it                                                                                                                                              |
+| [Tables](docs/schema/tables.md)                                     | Defining tables, column modifiers, defaults, references                                                                                                                                   |
+| [Column types](docs/schema/columns-sqlite.md)                       | Per dialect: [SQLite](docs/schema/columns-sqlite.md), [PostgreSQL](docs/schema/columns-postgres.md), [MySQL](docs/schema/columns-mysql.md), [universal](docs/schema/columns-universal.md) |
+| [Indexes & constraints](docs/schema/indexes-and-constraints.md)     | Primary keys, unique constraints, foreign keys, indexes                                                                                                                                   |
+| [Views](docs/schema/views.md)                                       | Views and PostgreSQL materialized views                                                                                                                                                   |
+| [Schemas & enums](docs/schema/postgres-schemas-and-enums.md)        | `pgSchema` and `pgEnum`                                                                                                                                                                   |
+| [Custom column types](docs/schema/custom-types.md)                  | Mapping your own types to and from the database                                                                                                                                           |
+| [Select](docs/queries/select.md)                                    | Selections, filtering, ordering, grouping, pagination, locking                                                                                                                            |
+| [Joins](docs/queries/joins.md)                                      | Inner/left/right/full/cross joins and lateral variants                                                                                                                                    |
+| [Insert](docs/queries/insert.md)                                    | Values, bulk inserts, upserts, insert-from-select                                                                                                                                         |
+| [Update](docs/queries/update.md) / [Delete](docs/queries/delete.md) | Modifying and removing rows, `returning`                                                                                                                                                  |
+| [Filter operators](docs/queries/operators.md)                       | `eq`, `and`, `or`, `inArray`, `like`, `between` and friends                                                                                                                               |
+| [Aggregates](docs/queries/aggregates.md)                            | `count`, `sum`, `avg`, `min`, `max` and grouping                                                                                                                                          |
+| [Include](docs/queries/include.md)                                  | Nested results without an ORM                                                                                                                                                             |
+| [JSON](docs/queries/json.md)                                        | Typed JSON columns, selecting and filtering nested fields                                                                                                                                 |
+| [Set operations](docs/queries/set-operations.md)                    | `union`, `intersect`, `except`                                                                                                                                                            |
+| [Subqueries & CTEs](docs/queries/subqueries-and-ctes.md)            | `.as()`, `$with`, recursive CTEs                                                                                                                                                          |
+| [The sql tag](docs/queries/sql.md)                                  | Raw SQL escape hatches, safely                                                                                                                                                            |
+| [Transactions & batch](docs/runtime/transactions-and-batch.md)      | Atomic operations, rollbacks, batching                                                                                                                                                    |
+| [Prepared statements](docs/runtime/prepared-statements.md)          | Placeholders, `prepare`, inspecting generated SQL                                                                                                                                         |
+| [Migrations](docs/runtime/migrations.md)                            | `db.create`, `db.migrate` and how diffing works                                                                                                                                           |
+| [Universal queries](docs/runtime/universal-queries.md)              | One query, three databases                                                                                                                                                                |
+| [Coming from Drizzle](docs/drizzle.md)                              | Side-by-side comparison and migration notes                                                                                                                                               |
 
-| `MySQL                   ` | `import                      ` |
-| -------------------------- | ------------------------------ |
-| mysql2                     | rado/driver/mysql2             |
+## Supported drivers
 
-Pass an instance of the database to the `connect` function to get started:
+Pass a database client instance to the matching `connect` function:
 
 ```ts
 import Database from 'better-sqlite3'
 import {connect} from 'rado/driver/better-sqlite3'
 
-const db = connect(new Database('foobar.db'))
-```
-
-## Querying
-
-### Select
-
-Select operations allow you to retrieve data from your database.
-
-```typescript
-// Basic select
-const allUsers = await db.select().from(User)
-
-// Select specific columns
-const userNames = await db.select({id: User.id, name: User.name}).from(User)
+const db = connect(new Database('app.db'))
 ```
 
-### Where conditions
+| Database   | Package                                                                            | Import                       | Sync/async |
+| ---------- | ---------------------------------------------------------------------------------- | ---------------------------- | ---------- |
+| PostgreSQL | [pg](https://www.npmjs.com/package/pg)                                             | `rado/driver/pg`             | async      |
+| PostgreSQL | [@electric-sql/pglite](https://www.npmjs.com/package/@electric-sql/pglite)         | `rado/driver/pglite`         | async      |
+| PostgreSQL | [@neondatabase/serverless](https://www.npmjs.com/package/@neondatabase/serverless) | `rado/driver/pg`             | async      |
+| PostgreSQL | [@vercel/postgres](https://www.npmjs.com/package/@vercel/postgres)                 | `rado/driver/pg`             | async      |
+| SQLite     | [better-sqlite3](https://www.npmjs.com/package/better-sqlite3)                     | `rado/driver/better-sqlite3` | sync       |
+| SQLite     | `bun:sqlite`                                                                       | `rado/driver/bun-sqlite`     | sync       |
+| SQLite     | [sql.js](https://www.npmjs.com/package/sql.js)                                     | `rado/driver/sql.js`         | sync       |
+| SQLite     | [@libsql/client](https://www.npmjs.com/package/@libsql/client)                     | `rado/driver/libsql`         | async      |
+| SQLite     | Cloudflare D1                                                                      | `rado/driver/d1`             | async      |
+| MySQL      | [mysql2](https://www.npmjs.com/package/mysql2)                                     | `rado/driver/mysql2`         | async      |
 
-Where conditions help you filter your query results.
+Synchronous drivers give you a fully synchronous database. No `await`
+required, although awaiting queries still works. See
+[Drivers](docs/drivers.md) for details.
 
-```typescript
-import {eq, and, or, gt, isNull} from 'rado'
+## A taste of the API
 
-// Simple equality
-const john = await db.select().from(User).where(eq(User.name, 'John'))
+### Immutable queries
 
-// Complex conditions
-const users = await db.select().from(User)
-  .where(
-    gt(User.age, 18),
-    or(
-      eq(User.name, 'Alice'),
-      isNull(User.email)
-    )
-  )
-```
-
-### Joins
-
-Joins allow you to combine data from multiple tables.
+Queries are values. Branch them, reuse them, store them in variables. Nothing
+mutates:
 
-```typescript
-const usersWithPosts = await db.select({
-  userName: User.name,
-  postTitle: Post.title,
-})
-.from(User)
-.leftJoin(Post, eq(User.id, Post.authorId))
-```
-
-### Ordering and Grouping
-
-You can order and group your query results:
-
-```typescript
-import {desc, asc, count} from 'rado'
+```ts
+import {count, gt} from 'rado'
 
-const orderedUsers = await db.select()
-  .from(User)
-  .orderBy(asc(User.name))
+const allUsers = db.select(count()).from(User)
+const filtered = allUsers.where(gt(User.id, 1))
 
-const userPostCounts = await db.select({
-  userName: User.name,
-  postCount: count(Post.id)
-})
-.from(User)
-.leftJoin(Post, eq(User.id, Post.authorId))
-.groupBy(User.name)
+const [total] = await allUsers // unaffected by the where above
+const [matching] = await filtered
 ```
 
-### Pagination
+### Nested results with `include`
 
-Pagination helps you manage large datasets by retrieving results in smaller chunks:
+No relations file, no separate query API. Declare the relationship inline:
 
-```typescript
-const pageSize = 10
-const page = 2
+```ts
+import {eq, include} from 'rado'
 
-const paginatedUsers = await db.select()
+const usersWithPosts = await db
+  .select({
+    ...User,
+    posts: include(db.select().from(Post).where(eq(Post.authorId, User.id)))
+  })
   .from(User)
-  .limit(pageSize)
-  .offset((page - 1) * pageSize)
 ```
 
-### JSON columns
+Each row comes back with a typed `posts` array. Use `include.one` for a single
+related row. More in [Include](docs/queries/include.md).
 
-Rado provides first-class support for JSON columns:
+### Typed JSON columns
 
-```typescript
-import {pgTable, serial, text, jsonb} from 'rado/postgres'
+```ts
+import {eq} from 'rado'
+import {jsonb, pgTable, serial, text} from 'rado/postgres'
 
-const User = pgTable("user", {
+const User = pgTable('user', {
   id: serial().primaryKey(),
   name: text(),
-  metadata: jsonb<{subscribed: boolean}>()
+  settings: jsonb<{theme: 'light' | 'dark'; notifications: boolean}>()
 })
 
-const subscribedUsers = await db.select()
+const darkSide = await db
+  .select(User.name)
   .from(User)
-  .where(eq(User.metadata.subscribed, true))
+  .where(eq(User.settings.theme, 'dark'))
 ```
 
-### Subqueries
+That `User.settings.theme` is a real, typed expression that compiles to the
+correct JSON access syntax for your database. More in
+[JSON](docs/queries/json.md).
 
-```typescript
-const subquery = db.select({authorId: Post.authorId})
-  .from(Post)
-  .groupBy(Post.authorId)
-  .having(gt(count(Post.id), 5))
-  .as('authorIds')
+### Universal queries
 
-const prolificAuthors = await db.select()
-  .from(User)
-  .where(inArray(User.id, subquery))
-```
-
-### Include
-
-Aggregate rows using the `include` function:
-
-```typescript
-import {include} from 'rado'
-
-const usersWithPosts = await db.select({
-  ...User,
-  posts: include(
-    db.select().from(Post).where(eq(Post.authorId, User.id))
-  )
-}).from(User)
-
-// Use include.one for a single related record
-const usersWithLatestPost = await db.select({
-  ...User,
-  latestPost: include.one(
-    db.select()
-      .from(Post)
-      .where(eq(Post.authorId, User.id))
-      .orderBy(desc(Post.createdAt))
-      .limit(1)
-  )
-}).from(User)
-```
+Define your schema with `rado/universal` column types and pick the database at
+runtime:
 
-### SQL Operator
-
-The `sql` operator allows you to write raw SQL and interpolate values safely:
-
-```typescript
-import {sql} from 'rado'
-
-const minAge = 18
-const adultUsers = await db.select()
-  .from(User)
-  .where(sql`${User.age} >= ${minAge}`)
-```
-
-## Modifying Data
-
-### Insert
-
-Insert operations allow you to add new records to your database:
-
-```typescript
-// Single insert
-const newUser = await db.insert(User)
-  .values({name: 'Alice', email: 'alice@example.com'})
-  .returning()
-
-// Bulk insert
-const newUsers = await db.insert(User)
-  .values([
-    {name: 'Bob', email: 'bob@example.com'},
-    {name: 'Charlie', email: 'charlie@example.com'},
-  ])
-  .returning()
-```
-
-### Update
-
-Update operations modify existing records:
-
-```typescript
-const updatedCount = await db.update(User)
-  .set({name: 'Johnny'})
-  .where(eq(User.name, 'John'))
-```
-
-### Delete
+```ts
+import {table} from 'rado'
+import {id, text} from 'rado/universal'
 
-Delete operations remove records from your database:
+const User = table('user', {
+  id: id(), // auto-incrementing primary key on every dialect
+  name: text()
+})
 
-```typescript
-await db.delete(User).where(eq(User.name, 'John'))
+const db = useSqlite ? sqliteDb : postgresDb
+const names = await db.select(User.name).from(User)
 ```
 
-### Transactions
+More in [Universal queries](docs/runtime/universal-queries.md).
 
-Transactions allow you to group multiple operations into a single atomic unit.
+### Auto-migrations
 
-```typescript
-const result = await db.transaction(async (tx) => {
-  const user = await tx.insert(User)
-    .values({ name: 'Alice', email: 'alice@example.com' })
-    .returning()
-  const post = await tx.insert(Post)
-    .values({ title: 'My First Post', authorId: user.id })
-    .returning()
-  return {user, post}
-})
+```ts
+// Compares the defined schema to the actual database and applies the diff
+await db.migrate(User, Post)
 ```
 
-## Universal Queries
+Works in Node.js, Bun, Deno and the browser. It is powerful and a little
+direct, so read [Migrations](docs/runtime/migrations.md) before pointing it at
+production.
 
-Rado provides a universal query builder that works across different database 
-engines, whether they run synchronously or asynchronously. This is useful for
-writing database-agnostic code.
+## Coming from Drizzle?
 
-```typescript
-import {table} from 'rado'
-import {id, text} from 'rado/universal'
+Most queries port by changing imports:
 
-const User = table('user', {
-  id: id(),
-  name: text() 
-})
-
-const db = process.env.SQLITE ? sqliteDb : postgresDb
-
-const userNames = await db.select(User.name).from(User)
+```ts
+import {sql, eq, and, or} from 'rado' // was 'drizzle-orm'
+import {pgTable, integer, text} from 'rado/postgres' // was 'drizzle-orm/pg-core'
+import {sqliteTable} from 'rado/sqlite' // was 'drizzle-orm/sqlite-core'
+import {mysqlTable} from 'rado/mysql' // was 'drizzle-orm/mysql-core'
 ```
 
-## Custom Column Types
-
-You can define custom column types, such as a boolean column that is stored as a
-tinyint in the database:
+Rado also exposes compatibility helpers such as `InferSelectModel`,
+`InferInsertModel`, `getTableColumns` and `TransactionRollbackError`. See
+[Coming from Drizzle](docs/drizzle.md) for a full side-by-side comparison of
+what's the same, what's better and what's missing.
 
-```typescript
-import {Column, column, table, sql} from 'rado'
+## License
 
-export function bool(name?: string): Column<boolean | null> {
-  return column({
-    name,
-    type: sql`tinyint(1)`,
-    mapFromDriverValue(value: number): boolean {
-      return value === 1
-    },
-    mapToDriverValue(value: boolean): number {
-      return value ? 1 : 0
-    }
-  })
-}
-
-// Usage
-const User = table('user', {
-  // ...
-  isActive: bool()
-})
-```
+MIT

package/dist/compat.d.ts

@@ -3,6 +3,9 @@ import type { Sql } from './core/Sql.js';
 import type { Table, TableDefinition, TableFields } from './core/Table.js';
 export type { InsertRow as InferInsertModel, SelectRow as InferSelectModel } from './core/Table.js';
 export type SQL<T = unknown> = Sql<T>;
+export declare namespace SQL {
+    type Aliased<T = unknown> = Sql<T>;
+}
 export type SQLWrapper<T = unknown> = HasSql<T>;
 export declare function getTableColumns<Definition extends TableDefinition>(table: Table<Definition>): TableFields<Definition>;
 export { Rollback as TransactionRollbackError } from './core/Database.js';

package/dist/core/Builder.d.ts

@@ -1,14 +1,15 @@
 import { type HasSql, internalData } from './Internal.js';
 import type { IsPostgres, QueryMeta } from './MetaData.js';
 import type { QueryData, SingleQuery } from './Queries.js';
-import type { SelectionInput, SelectionRow } from './Selection.js';
-import type { Table, TableDefinition } from './Table.js';
-import { type CTE } from './query/CTE.js';
-import { DeleteFrom } from './query/Delete.js';
-import { InsertInto } from './query/Insert.js';
+import type { CTE } from './query/CTE.js';
+import { Delete, DeleteFrom } from './query/Delete.js';
+import { Insert, InsertInto } from './query/Insert.js';
 import type { DeleteQuery, FromGuard, FromQuery, FromRow, InsertQuery, QueryBase, SelectionQuery, UpdateQuery } from './query/Query.js';
 import type { UnionBase, WithSelection, WithoutSelection } from './query/Select.js';
-import { UpdateTable } from './query/Update.js';
+import { Update, UpdateTable } from './query/Update.js';
+import { type SelectionInput, type SelectionRow } from './Selection.js';
+import { Sql } from './Sql.js';
+import type { Table, TableDefinition } from './Table.js';
 declare class BuilderBase<Meta extends QueryMeta> {
     readonly [internalData]: QueryData<Meta> & QueryBase;
     constructor(data?: QueryData<Meta> & QueryBase);
@@ -21,15 +22,21 @@ declare class BuilderBase<Meta extends QueryMeta> {
     select<Input extends SelectionInput>(select: Input): WithSelection<Input, Meta>;
     selectDistinct(): WithoutSelection<Meta>;
     selectDistinct<Input extends SelectionInput>(selection: Input): WithSelection<Input, Meta>;
-    selectDistinctOn(this: Builder<IsPostgres>, columns: Array<HasSql>): WithoutSelection<Meta>;
-    selectDistinctOn<Input extends SelectionInput>(this: Builder<IsPostgres>, columns: Array<HasSql>, selection: Input): WithSelection<Input, Meta>;
+    selectDistinctOn(this: BuilderBase<IsPostgres>, columns: Array<HasSql>): WithoutSelection<Meta>;
+    selectDistinctOn<Input extends SelectionInput>(this: BuilderBase<IsPostgres>, columns: Array<HasSql>, selection: Input): WithSelection<Input, Meta>;
     update<Definition extends TableDefinition>(table: Table<Definition>): UpdateTable<Definition, Meta>;
     insert<Definition extends TableDefinition>(into: Table<Definition>): InsertInto<Definition, Meta>;
     delete<Definition extends TableDefinition>(from: Table<Definition>): DeleteFrom<Definition, Meta>;
 }
 export declare class Builder<Meta extends QueryMeta> extends BuilderBase<Meta> {
+    $with<Input extends SelectionInput>(cteName: string, columns: Input): {
+        as(query: Sql): CTE<Input>;
+    };
     $with(cteName: string): {
-        as<Input extends SelectionInput>(query: UnionBase<Input, Meta>): CTE<Input>;
+        as<Input>(query: UnionBase<Input, Meta>): CTE<Input>;
+        as<Input>(query: Delete<Input, Meta>): CTE<Input>;
+        as<Input>(query: Update<Input, Meta>): CTE<Input>;
+        as<Input>(query: Insert<Input, Meta>): CTE<Input>;
     };
     with(...definitions: Array<CTE>): BuilderBase<Meta>;
     withRecursive(...definitions: Array<CTE>): BuilderBase<Meta>;

package/dist/core/Builder.js

@@ -1,10 +1,47 @@
 // src/core/Builder.ts
-import { getData, internalData } from "./Internal.js";
-import { createCTE } from "./query/CTE.js";
+import {
+  getData,
+  getQuery,
+  getSelection,
+  getSql,
+  hasData,
+  hasQuery,
+  hasSql,
+  hasSelection,
+  internalData,
+  internalSelection,
+  internalQuery
+} from "./Internal.js";
 import { Delete, DeleteFrom } from "./query/Delete.js";
 import { Insert, InsertInto } from "./query/Insert.js";
 import { Select } from "./query/Select.js";
 import { Update, UpdateTable } from "./query/Update.js";
+import {
+  StarSelection
+} from "./Selection.js";
+import { Sql } from "./Sql.js";
+import { virtualTarget } from "./Virtual.js";
+function aliasSql(input, name) {
+  const expr = getSql(input);
+  if (expr.alias) return expr;
+  const aliased = new Sql((emitter) => expr.emit(emitter));
+  aliased.alias = name;
+  aliased.mapFromDriverValue = expr.mapFromDriverValue;
+  return aliased;
+}
+function aliasUnnamedFields(input, name) {
+  if (hasSql(input)) {
+    if (!name) return input;
+    return aliasSql(input, name);
+  }
+  if (!input || typeof input !== "object") return input;
+  return Object.fromEntries(
+    Object.entries(input).map(([key, value]) => [
+      key,
+      aliasUnnamedFields(value, key)
+    ])
+  );
+}
 var BuilderBase = class {
   [internalData];
   constructor(data = {}) {
@@ -48,10 +85,21 @@ var BuilderBase = class {
   }
 };
 var Builder = class extends BuilderBase {
-  $with(cteName) {
+  $with(cteName, columns) {
     return {
       as(query) {
-        return createCTE(cteName, query);
+        let input = hasQuery(query) ? hasSelection(query) ? getSelection(query).input : columns : columns;
+        const data = hasQuery(query) && hasData(query) ? getData(query) : void 0;
+        if (input && data?.compound?.length > 1)
+          input = aliasUnnamedFields(input);
+        const target = virtualTarget(cteName, input ?? {});
+        return {
+          ...target,
+          [internalSelection]: new StarSelection(target),
+          get [internalQuery]() {
+            return hasQuery(query) ? getQuery(query).nameSelf(cteName) : getSql(query);
+          }
+        };
       }
     };
   }