rado 0.3.0 → 0.3.2

package/README.md

@@ -1,275 +1,275 @@
-# rado
-
-Fully typed, lightweight TypeScript query builder.
-Currently focused on SQLite.
-
-- Definition via TypeScript types
-- Composable queries
-- Aggregate rows in selects
-- First class JSON columns
-- No code generation step
-- No dependencies
-
-<pre>npm install <a href="https://www.npmjs.com/package/rado">rado</a></pre>
-
-## 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 below
-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()).first(),
-    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
-import {iif} from 'rado/sqlite'
-Person().select({
-  name: Person.firstName.concat(' ').concat(Person.lastName),
-  isMario: Person.firstName.is('Mario'),
-  isActor: Person.id.isIn(Actor().select(Actor.personId)),
-  email: iif(Person.email.isNotNull(), Person.email, 'its.me@mario'),
-  twitterHandle: Person.socialMedia
-    .filter(media => media.type.is('twitter'))
-    .map(media => media.handle)
-    .maybeFirst()
-})
-```
-
-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}).first()
-    }
-
-    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
-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
-})
-```
+# rado
+
+Fully typed, lightweight TypeScript query builder.
+Currently focused on SQLite.
+
+- Definition via TypeScript types
+- Composable queries
+- Aggregate rows in selects
+- First class JSON columns
+- No code generation step
+- No dependencies
+
+<pre>npm install <a href="https://www.npmjs.com/package/rado">rado</a></pre>
+
+## 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 below
+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()).first(),
+    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
+import {iif} from 'rado/sqlite'
+Person().select({
+  name: Person.firstName.concat(' ').concat(Person.lastName),
+  isMario: Person.firstName.is('Mario'),
+  isActor: Person.id.isIn(Actor().select(Actor.personId)),
+  email: iif(Person.email.isNotNull(), Person.email, 'its.me@mario'),
+  twitterHandle: Person.socialMedia
+    .filter(media => media.type.is('twitter'))
+    .map(media => media.handle)
+    .maybeFirst()
+})
+```
+
+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}).first()
+    }
+
+    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
+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

@@ -17,6 +17,8 @@ export interface PartialColumnData {
     primaryKey?: boolean;
     unique?: boolean;
     references?: () => ExprData;
+    onUpdate?: Action;
+    onDelete?: Action;
     enumerable?: boolean;
 }
 export interface ColumnData extends PartialColumnData {
@@ -46,9 +48,20 @@ export declare class ValueColumn<T> extends Callable implements Column<T> {
     get unique(): ValueColumn<T>;
     get autoIncrement(): OptionalColumn<T>;
     primaryKey<K = string>(create?: () => EV<T>): PrimaryColumn<T, K>;
-    references<X extends T>(column: Expr<X> | (() => Expr<X>)): ValueColumn<X>;
+    references<X extends T>(column: Expr<X> | (() => Expr<X>)): ForeignKey<X>;
     default(value: DefaultValue<T>): OptionalColumn<T>;
 }
+export declare enum Action {
+    NoAction = "no action",
+    Restrict = "restrict",
+    SetNull = "set null",
+    SetDefault = "set default",
+    Cascade = "cascade"
+}
+export declare class ForeignKey<T> extends ValueColumn<T> {
+    onUpdate(value: `${Action}`): ForeignKey<unknown>;
+    onDelete(value: `${Action}`): ForeignKey<unknown>;
+}
 export declare class OptionalColumn<T> extends ValueColumn<T> {
     [Column.IsOptional]: true;
 }

package/dist/define/Column.js

@@ -40,7 +40,7 @@ class ValueColumn extends Callable {
     });
   }
   references(column2) {
-    return new ValueColumn({
+    return new ForeignKey({
       ...this[Column.Data],
       references() {
         return ExprData.create(Expr.isExpr(column2) ? column2 : column2());
@@ -57,6 +57,28 @@ class ValueColumn extends Callable {
 function createDefaultValue(value) {
   return typeof value === "function" && !Expr.isExpr(value) ? () => ExprData.create(value()) : ExprData.create(value);
 }
+var Action = /* @__PURE__ */ ((Action2) => {
+  Action2["NoAction"] = "no action";
+  Action2["Restrict"] = "restrict";
+  Action2["SetNull"] = "set null";
+  Action2["SetDefault"] = "set default";
+  Action2["Cascade"] = "cascade";
+  return Action2;
+})(Action || {});
+class ForeignKey extends ValueColumn {
+  onUpdate(value) {
+    return new ForeignKey({
+      ...this[Column.Data],
+      onUpdate: value
+    });
+  }
+  onDelete(value) {
+    return new ForeignKey({
+      ...this[Column.Data],
+      onDelete: value
+    });
+  }
+}
 class OptionalColumn extends ValueColumn {
   [Column.IsOptional];
 }
@@ -147,8 +169,10 @@ class UnTyped extends Callable {
 }
 const column = new UnTyped();
 export {
+  Action,
   Column,
   ColumnType,
+  ForeignKey,
   ObjectColumn,
   OptionalColumn,
   OptionalObjectColumn,