rado 0.3.2 → 0.3.3

package/README.md

@@ -1,275 +1,277 @@
-# 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
-})
-```
+[![npm](https://img.shields.io/npm/v/rado.svg)](https://npmjs.org/package/rado)
+
+# 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/Expr.d.ts

@@ -1,10 +1,9 @@
 import { Fields } from './Fields.js';
 import { OrderBy } from './OrderBy.js';
 import { ParamData } from './Param.js';
-import { QueryData } from './Query.js';
+import { QueryData, Select, SelectFirst } from './Query.js';
 import { Selection } from './Selection.js';
 import { Target } from './Target.js';
-import { Select, SelectFirst } from './query/Select.js';
 export declare enum UnOpType {
     Not = "Not",
     IsNull = "IsNull"
@@ -161,6 +160,7 @@ export declare class Expr<T> {
     map<T, X extends Selection>(this: Expr<Array<T>>, fn: (cursor: Fields<T>) => X): Expr<Array<Selection.Infer<X>>>;
     sure(): Expr<NonNullable<T>>;
     get<T>(name: string): Expr<T>;
+    static [Symbol.hasInstance](instance: any): any;
 }
 export interface ObjectExpr {
     [Expr.Data]: ExprData;

package/dist/define/Expr.js

@@ -386,6 +386,9 @@ class Expr {
   get(name) {
     return new Expr(new ExprData.Field(this[Expr.Data], name));
   }
+  static [Symbol.hasInstance](instance) {
+    return instance?.[Expr.IsExpr];
+  }
 }
 ((Expr2) => {
   Expr2.Data = Symbol("Expr.Data");
@@ -419,7 +422,7 @@ class Expr {
   }
   Expr2.hasExpr = hasExpr;
   function isExpr(input) {
-    return input !== null && (typeof input === "object" || typeof input === "function") && input[Expr2.IsExpr];
+    return input instanceof Expr2;
   }
   Expr2.isExpr = isExpr;
 })(Expr || (Expr = {}));

package/dist/define/Ops.d.ts

@@ -1,11 +1,6 @@
+import { Batch, Delete, InsertInto, RecursiveUnion, Select, Update } from './Query.js';
 import { Selection } from './Selection.js';
 import { Table } from './Table.js';
-import { Batch } from './query/Batch.js';
-import { Delete } from './query/Delete.js';
-import { InsertInto } from './query/Insert.js';
-import { Select } from './query/Select.js';
-import { RecursiveUnion } from './query/Union.js';
-import { Update } from './query/Update.js';
 export declare function withRecursive<Row>(initialSelect: Select<Row>): RecursiveUnion<Row>;
 export declare function alias<T extends Table<{}>>(table: T): Record<string, T>;
 export declare function select<X extends Selection>(selection: X): Select<Selection.Infer<X>>;

package/dist/define/Ops.js

@@ -1,14 +1,17 @@
 import { ExprData } from "./Expr.js";
-import { Query, QueryData } from "./Query.js";
+import {
+  Batch,
+  Delete,
+  InsertInto,
+  Query,
+  QueryData,
+  RecursiveUnion,
+  Select,
+  Update
+} from "./Query.js";
 import { Schema } from "./Schema.js";
 import { Table, createTable } from "./Table.js";
 import { Target } from "./Target.js";
-import { Batch } from "./query/Batch.js";
-import { Delete } from "./query/Delete.js";
-import { InsertInto } from "./query/Insert.js";
-import { Select } from "./query/Select.js";
-import { RecursiveUnion } from "./query/Union.js";
-import { Update } from "./query/Update.js";
 function withRecursive(initialSelect) {
   return new RecursiveUnion(initialSelect[Query.Data]);
 }