rado 0.1.63 → 0.2.0

package/README.md

@@ -1 +1,270 @@
 # rado
+
+Fully typed, lightweight TypeScript query builder.
+Currently focused on SQLite.
+
+```
+npm install rado
+```
+
+- Definition via TypeScript types
+- Composable queries
+- Aggregate rows in selects
+- First class JSON columns
+- No code generation step
+- No dependencies
+
+## Queries
+
+#### Where
+
+Conditions can be created by accessing the fields of the table
+instances and using the operators of `Expr`:
+
+```ts
+User.id // This is an Expr<number> which has an `is` method to compare
+User.id.is(1) // Compare with a value, results in an Expr<boolean>
+User.id.is(Post.userId) // Compare to fields on other tables
+```
+
+Rows can be selected by passing the condition in the where method:
+
+```ts
+// Call a table instance to start a query selecting from that table
+User().where(User.id.is(1))
+// Conditions can be as complex as you want
+User().where(User.id.isGreater(1).and(User.id.isLess(5)))
+// `And` conditions can also be comma separated in `where` to improve readability
+User().where(User.id.isGreater(1), User.id.isLess(5))
+```
+
+There's a shortcut for comparing columns of a table directly in its call.
+The first comparison above can be simplified to:
+
+```ts
+User({id: 1}) // Is the same as User().where(User.id.is(1))
+```
+
+This comes in handy when joining tables too:
+
+```ts
+User({id: 1}).innerJoin(Post({userId: User.id}))
+// Is equal to:
+User().innerJoin(Post, Post.userId.is(User.id)).where(User.id.is(1))
+```
+
+#### Select
+
+Retrieve a single field
+
+```ts
+User().select(User.name)
+```
+
+Or an object of data
+
+```ts
+User().select({
+  ...User, // Get all user fields: id, username
+  posts: Post({userId: User.id}) // Aggregate posts of this user
+})
+```
+
+You can call the `posts` helper method defined in the example schema to achieve
+the same:
+
+```ts
+User().select({
+  ...User,
+  posts: User.posts()
+})
+```
+
+Retrieve all posts with their author and tags and count the tag usage in other
+posts:
+
+```ts
+import {count} from 'rado/sqlite'
+// Alias tables using `as`
+const pt = PostTags().as('pt')
+Post().select({
+  ...Post,
+  author: Post.author().select(User.username),
+  tags: Post.tags().select({
+    count: pt({tagId: Tag.id}).select(count()).sure(),
+    name: Tag.name
+  })
+})
+```
+
+Join other tables and select fields from either table:
+
+```ts
+User({id: 1}).innerJoin(Post({userId: User.id})).select({
+  username: User.username
+  post: Post
+})
+```
+
+Create expressions to select complex values:
+
+```ts
+Person().select({
+  name: Person.firstName.concat(' ').concat(Person.lastName),
+  isMario: Person.firstName.is('Mario')
+})
+```
+
+Order, group, limit queries:
+
+```ts
+User()
+  .orderBy(User.username.asc())
+  .groupBy(User.id, User.username)
+  .skip(20)
+  .take(10)
+```
+
+#### Insert
+
+Insert a single row and return the result:
+
+```ts
+User().insertOne({username: 'Mario'})
+```
+
+Insert multiple rows:
+
+```ts
+User().insertAll([{username: 'Mario'}, {username: 'Luigi'}])
+```
+
+#### Update
+
+Set values
+
+```ts
+User({id: 1}).set({username: 'Bowser'})
+```
+
+Use expressions to update complex values:
+
+```ts
+User()
+  .set({username: User.username.concat(' [removed]')})
+  .where(User.deleted)
+```
+
+#### Delete
+
+Delete rows
+
+```ts
+User({id: 1}).delete()
+```
+
+## Schema definition
+
+```ts
+import {table, column} from 'rado'
+
+const User = table({
+  // Pass a definition under a key with the actual name of the table in database
+  user: class {
+    id = column.integer().primaryKey()
+    username = column.string()
+
+    // Define helper methods directly on the model
+    posts() {
+      return Post({userId: this.id})
+    }
+  }
+})
+
+const Post = table({
+  post: class {
+    id = column.integer().primaryKey()
+    userId = column.integer().references(() => User.id)
+    content = column.string()
+
+    author() {
+      return User({id: this.userId}).sure()
+    }
+
+    tags() {
+      return Tag({id: PostTags.tagId}).innerJoin(PostTags({postId: this.id}))
+    }
+  }
+})
+
+const Tag = table({
+  tag: class {
+    id = column.integer().primaryKey()
+    name = column.string()
+  }
+})
+
+const PostTags = table({
+  post_tag: class {
+    postId = column.integer().references(() => Post.id)
+    tagId = column.integer().references(() => Tag.id)
+  }
+})
+```
+
+## Connections
+
+Currently supported SQLite drivers:
+`better-sqlite3`, `sql.js`, `sqlite3`, `bun:sqlite`
+
+Pass an instance of the database to the `connect` function to get started:
+
+```ts
+import Database from 'better-sqlite3'
+import {connect} from 'rado/driver/better-sqlite3'
+
+const db = connect(new Database('foobar.db'))
+```
+
+Currently all drivers are synchronous except for the `sqlite3` driver which is
+async.
+
+#### Run queries
+
+Call the connection with a query to retrieve its results:
+
+```ts
+const posts = db(Post())
+// For async drivers this will be a Promise:
+const posts = await db(Post())
+```
+
+#### Iterate results
+
+Iterate over query results:
+
+```ts
+const allPosts = Post()
+for (const row of db.iterate(allPosts)) {
+  console.log(row)
+}
+// For async drivers:
+for await (const row of db.iterate(allPosts)) {
+  console.log(row)
+}
+```
+
+#### Transactions
+
+Run transactions within the `transaction` method which will isolate a connection
+for you and can optionally return a result:
+
+```ts
+const firstUserId = db.transaction(tx => {
+  const createTable = User().create()
+  tx(createTable)
+  const insertUser = User().insertOne({username: 'Mario'})
+  tx(insertUser)
+  return insertUser.id
+})
+```

package/dist/define/Column.d.ts

@@ -15,44 +15,44 @@ interface PartialColumnData {
     primaryKey?: boolean;
     unique?: boolean;
     references?: () => ExprData;
+    enumerable?: boolean;
 }
 export interface ColumnData extends PartialColumnData {
     type: ColumnType;
     name: string;
 }
-export declare class Column<T> {
+export declare class Column<T> extends Expr<T> {
     data: PartialColumnData;
     constructor(data: PartialColumnData);
     name(name: string): Column<T>;
     nullable(): Column<T | null>;
-    autoIncrement(): Column<Column.IsOptional<T>>;
-    primaryKey<K extends string>(create?: () => EV<T>): Column<Column.IsPrimary<T, K>>;
+    autoIncrement(): OptionalColumn<T>;
+    primaryKey<K = string>(create?: () => EV<T>): PrimaryColumn<T, K>;
     references<X extends T>(column: Expr<X> | (() => Expr<X>)): Column<X>;
     unique(): Column<T>;
-    defaultValue(create: () => EV<T>): Column<Column.IsOptional<T>>;
-    defaultValue(value: EV<T>): Column<Column.IsOptional<T>>;
+    defaultValue(create: () => EV<T>): OptionalColumn<T>;
+    defaultValue(value: EV<T>): OptionalColumn<T>;
 }
-export type PrimaryKey<T, K> = string extends K ? T : T & {
-    [Column.isPrimary]: K;
-};
 export declare namespace Column {
     const isOptional: unique symbol;
-    type IsOptional<T> = {
-        [isOptional]: true;
-        __t: T;
-    };
     const isPrimary: unique symbol;
-    type IsPrimary<T, K> = {
-        [isPrimary]: K;
-        __t: T;
-    };
 }
+export declare class OptionalColumn<T> extends Column<T> {
+    [Column.isOptional]: true;
+}
+export declare class PrimaryColumn<T, K> extends Column<T> {
+    [Column.isPrimary]: K;
+}
+export type PrimaryKey<T, K> = string extends K ? T : T & {
+    [Column.isPrimary]: K;
+};
 export declare const column: {
     string<T extends string = string>(): Column<T>;
     integer<T_1 extends number = number>(): Column<T_1>;
     number<T_2 extends number = number>(): Column<T_2>;
     boolean<T_3 extends boolean = boolean>(): Column<T_3>;
-    object<T_4 extends object = object>(): Column<T_4>;
-    array<T_5 = any>(): Column<T_5[]>;
+    json<T_4 = any>(): Column<T_4>;
+    object<T_5 extends object = object>(): Column<T_5>;
+    array<T_6 = any>(): Column<T_6[]>;
 };
 export {};

package/dist/define/Column.js

@@ -1,5 +1,5 @@
 // src/define/Column.ts
-import { ExprData } from "./Expr.js";
+import { Expr, ExprData } from "./Expr.js";
 var ColumnType = /* @__PURE__ */ ((ColumnType2) => {
   ColumnType2["String"] = "String";
   ColumnType2["Integer"] = "Integer";
@@ -8,8 +8,9 @@ var ColumnType = /* @__PURE__ */ ((ColumnType2) => {
   ColumnType2["Json"] = "Json";
   return ColumnType2;
 })(ColumnType || {});
-var Column = class {
+var Column = class extends Expr {
   constructor(data) {
+    super(void 0);
     this.data = data;
   }
   name(name) {
@@ -19,10 +20,10 @@ var Column = class {
     return new Column({ ...this.data, nullable: true });
   }
   autoIncrement() {
-    return new Column({ ...this.data, autoIncrement: true });
+    return new OptionalColumn({ ...this.data, autoIncrement: true });
   }
   primaryKey(create) {
-    return new Column({
+    return new PrimaryColumn({
       ...this.data,
       primaryKey: true,
       defaultValue: create ? () => ExprData.create(create()) : this.data.defaultValue
@@ -40,7 +41,7 @@ var Column = class {
     return new Column({ ...this.data, unique: true });
   }
   defaultValue(value) {
-    return new Column({
+    return new OptionalColumn({
       ...this.data,
       defaultValue: typeof value === "function" ? () => ExprData.create(value()) : ExprData.create(value)
     });
@@ -48,6 +49,12 @@ var Column = class {
 };
 ((Column2) => {
 })(Column || (Column = {}));
+var OptionalColumn = class extends Column {
+  [Column.isOptional];
+};
+var PrimaryColumn = class extends Column {
+  [Column.isPrimary];
+};
 var column = {
   string() {
     return new Column({ type: "String" /* String */ });
@@ -61,6 +68,9 @@ var column = {
   boolean() {
     return new Column({ type: "Boolean" /* Boolean */ });
   },
+  json() {
+    return new Column({ type: "Json" /* Json */ });
+  },
   object() {
     return new Column({ type: "Json" /* Json */ });
   },
@@ -71,5 +81,7 @@ var column = {
 export {
   Column,
   ColumnType,
+  OptionalColumn,
+  PrimaryColumn,
   column
 };

package/dist/define/Cursor.d.ts

@@ -3,18 +3,17 @@ import { CompileOptions } from '../lib/Formatter';
 import { EV, Expr } from './Expr';
 import { OrderBy } from './OrderBy';
 import { Query } from './Query';
-import { Schema } from './Schema';
 import { Selection } from './Selection';
-import { Table } from './Table';
-import { Update as UpdateSet } from './Update';
+import { Table, TableData } from './Table';
 export declare class Cursor<T> {
     [Selection.__cursorType](): T;
     constructor(query: Query<T>);
     static all(strings: TemplateStringsArray, ...params: Array<any>): Cursor<any>;
     query(): Query<T>;
+    next<T>(cursor: Cursor<T>): Cursor<T>;
     on(driver: Driver.Sync): T;
     on(driver: Driver.Async): Promise<T>;
-    compile(driver: Driver, options?: CompileOptions): import("..").Statement;
+    toSql(driver: Driver, options?: CompileOptions): string;
     toJSON(): Query<T>;
 }
 export declare namespace Cursor {
@@ -26,62 +25,74 @@ export declare namespace Cursor {
         take(limit: number | undefined): Delete;
         skip(offset: number | undefined): Delete;
     }
-    class Update<T> extends Cursor<{
+    class Update<Definition> extends Cursor<{
         rowsAffected: number;
     }> {
         query(): Query.Update;
-        set(set: UpdateSet<T>): Update<T>;
-        where(...where: Array<EV<boolean>>): Update<T>;
-        take(limit: number | undefined): Update<T>;
-        skip(offset: number | undefined): Update<T>;
+        set(set: Table.Update<Definition>): Update<Definition>;
+        where(...where: Array<EV<boolean>>): Update<Definition>;
+        take(limit: number | undefined): Update<Definition>;
+        skip(offset: number | undefined): Update<Definition>;
     }
     class InsertValuesReturning<T> extends Cursor<T> {
     }
-    class InsertValues extends Cursor<{
+    class Inserted extends Cursor<{
         rowsAffected: number;
     }> {
         query(): Query.Insert;
         returning<X extends Selection>(selection: X): InsertValuesReturning<Selection.Infer<X>>;
     }
-    class Insert<T> {
-        protected into: Schema;
-        constructor(into: Schema);
-        values(...data: Array<Table.Insert<T>>): InsertValues;
+    class Insert<Definition> {
+        protected into: TableData;
+        constructor(into: TableData);
+        selection(query: Cursor.SelectMultiple<Table.Select<Definition>>): Inserted;
+        values(...data: Array<Table.Insert<Definition>>): Inserted;
     }
     class CreateTable extends Cursor<void> {
-        protected table: Schema;
-        constructor(table: Schema);
+        protected table: TableData;
+        constructor(table: TableData);
     }
     class Batch<T = void> extends Cursor<T> {
         protected queries: Array<Query>;
+        query(): Query.Batch;
         constructor(queries: Array<Query>);
+        next<T>(cursor: Cursor<T>): Cursor<T>;
     }
-    class SelectMultiple<T> extends Cursor<Array<T>> {
+    class SelectMultiple<Row> extends Cursor<Array<Row>> {
         query(): Query.Select;
-        leftJoin<C>(that: Table<C>, ...on: Array<EV<boolean>>): SelectMultiple<T>;
-        innerJoin<C>(that: Table<C>, ...on: Array<EV<boolean>>): SelectMultiple<T>;
+        leftJoin<C>(that: Table<C> | TableSelect<C>, ...on: Array<EV<boolean>>): SelectMultiple<Row>;
+        innerJoin<C>(that: Table<C> | TableSelect<C>, ...on: Array<EV<boolean>>): SelectMultiple<Row>;
         select<X extends Selection>(selection: X): SelectMultiple<Selection.Infer<X>>;
         count(): SelectSingle<number>;
-        orderBy(...orderBy: Array<Expr<any> | OrderBy>): SelectMultiple<T>;
-        groupBy(...groupBy: Array<Expr<any>>): SelectMultiple<T>;
-        first(): SelectSingle<T | undefined>;
-        sure(): SelectSingle<T>;
-        where(...where: Array<EV<boolean>>): SelectMultiple<T>;
-        take(limit: number | undefined): SelectMultiple<T>;
-        skip(offset: number | undefined): SelectMultiple<T>;
-        toExpr(): Expr<T>;
+        orderBy(...orderBy: Array<Expr<any> | OrderBy>): SelectMultiple<Row>;
+        groupBy(...groupBy: Array<Expr<any>>): SelectMultiple<Row>;
+        first(): SelectSingle<Row | undefined>;
+        sure(): SelectSingle<Row>;
+        where(...where: Array<EV<boolean>>): SelectMultiple<Row>;
+        take(limit: number | undefined): SelectMultiple<Row>;
+        skip(offset: number | undefined): SelectMultiple<Row>;
     }
-    class SelectSingle<T> extends Cursor<T> {
+    class TableSelect<Definition> extends SelectMultiple<Table.Select<Definition>> {
+        protected table: TableData;
+        constructor(table: TableData, conditions?: Array<EV<boolean>>);
+        as(alias: string): Table<Definition>;
+        create(): CreateTable;
+        insertSelect(query: SelectMultiple<Table.Insert<Definition>>): Inserted;
+        insertOne(record: Table.Insert<Definition>): Cursor<Table.Select<Definition>>;
+        insertAll(data: Array<Table.Insert<Definition>>): Inserted;
+        set(data: Table.Update<Definition>): Update<Definition>;
+        delete(): Delete;
+    }
+    class SelectSingle<Row> extends Cursor<Row> {
         query(): Query.Select;
-        leftJoin<C>(that: Table<C>, ...on: Array<EV<boolean>>): SelectSingle<T>;
-        innerJoin<C>(that: Table<C>, ...on: Array<EV<boolean>>): SelectSingle<T>;
+        leftJoin<C>(that: Table<C> | TableSelect<C>, ...on: Array<EV<boolean>>): SelectSingle<Row>;
+        innerJoin<C>(that: Table<C> | TableSelect<C>, ...on: Array<EV<boolean>>): SelectSingle<Row>;
         select<X extends Selection>(selection: X): SelectSingle<Selection.Infer<X>>;
-        orderBy(...orderBy: Array<OrderBy>): SelectSingle<T>;
-        groupBy(...groupBy: Array<Expr<any>>): SelectSingle<T>;
-        where(...where: Array<EV<boolean>>): SelectSingle<T>;
-        take(limit: number | undefined): SelectSingle<T>;
-        skip(offset: number | undefined): SelectSingle<T>;
-        all(): SelectMultiple<T>;
-        toExpr(): Expr<T>;
+        orderBy(...orderBy: Array<OrderBy>): SelectSingle<Row>;
+        groupBy(...groupBy: Array<Expr<any>>): SelectSingle<Row>;
+        where(...where: Array<EV<boolean>>): SelectSingle<Row>;
+        take(limit: number | undefined): SelectSingle<Row>;
+        skip(offset: number | undefined): SelectSingle<Row>;
+        all(): SelectMultiple<Row>;
     }
 }