prisma-ts-select 0.0.33 → 0.0.34

package/README.md

@@ -1,8 +1,8 @@
 # prisma-ts-select
 
 ![npm version](https://img.shields.io/npm/v/prisma-ts-select)
+![build](https://github.com/adrianbrowning/prisma-ts-select/actions/workflows/CI.yml/badge.svg)
 ![license](https://img.shields.io/github/license/adrianbrowning/prisma-ts-select)
-<!--![build](https://github.com/adrianbrowning/prisma-ts-select/actions/workflows/build.yml/badge.svg)-->
 
 <!-- toc -->
 
@@ -13,18 +13,36 @@
     + [Generator](#generator)
   * [API](#api)
     + [`.$from`](#from)
+      - [Example](#example)
+      - [Example - With Table Alias](#example---with-table-alias)
+        * [SQL](#sql)
+      - [Example - Inline Alias Syntax](#example---inline-alias-syntax)
+        * [SQL](#sql-1)
+    + [Table Aliases](#table-aliases)
+      - [Table Alias Syntax Options](#table-alias-syntax-options)
+      - [Basic Table Alias](#basic-table-alias)
+        * [SQL](#sql-2)
+      - [Table Aliases with Joins](#table-aliases-with-joins)
+        * [Inline Alias Syntax](#inline-alias-syntax)
+        * [Object Syntax](#object-syntax)
+        * [SQL](#sql-3)
+      - [Self-Joins with Aliases](#self-joins-with-aliases)
+        * [SQL](#sql-4)
+      - [Table.* with Aliases](#table-with-aliases)
+        * [SQL](#sql-5)
+        * [SQL](#sql-6)
     + [Joins](#joins)
       - [`.join`](#join)
-        * [Example](#example)
-        * [SQL](#sql)
+        * [Example](#example-1)
+        * [SQL](#sql-7)
         * [Parameters](#parameters)
       - [`.joinUnsafeTypeEnforced`](#joinunsafetypeenforced)
-        * [Example](#example-1)
-        * [SQL](#sql-1)
+        * [Example](#example-2)
+        * [SQL](#sql-8)
         * [Parameters](#parameters-1)
       - [`.joinUnsafeIgnoreType`](#joinunsafeignoretype)
-        * [Example](#example-2)
-        * [SQL](#sql-2)
+        * [Example](#example-3)
+        * [SQL](#sql-9)
         * [Parameters](#parameters-2)
     + [Where](#where)
       - [`.where`](#where)
@@ -37,45 +55,53 @@
           + [$NOT](#not)
           + [$NOR](#nor)
       - [`.whereNotNull`](#wherenotnull)
-        * [Example](#example-3)
-        * [SQL](#sql-3)
-      - [`.whereIsNull`](#whereisnull)
         * [Example](#example-4)
-        * [SQL](#sql-4)
-      - [`.whereRaw`](#whereraw)
+        * [SQL](#sql-10)
+      - [`.whereIsNull`](#whereisnull)
         * [Example](#example-5)
-        * [SQL](#sql-5)
+        * [SQL](#sql-11)
+      - [`.whereRaw`](#whereraw)
+        * [Example](#example-6)
+        * [SQL](#sql-12)
     + [Group By](#group-by)
-      - [Example](#example-6)
-      - [SQL](#sql-6)
+      - [Example](#example-7)
+      - [SQL](#sql-13)
     + [Selecting](#selecting)
       - [`.selectDistinct`](#selectdistinct)
-      - [Example](#example-7)
-      - [SQL](#sql-7)
+      - [Example](#example-8)
+      - [SQL](#sql-14)
       - [`.selectAll`](#selectall)
       - [Example - Single Table](#example---single-table)
-        * [SQL](#sql-8)
+        * [SQL](#sql-15)
       - [Example - Join table](#example---join-table)
-        * [SQL](#sql-9)
+        * [SQL](#sql-16)
       - [`.select`](#select)
       - [Example - `*`](#example---)
-        * [SQL](#sql-10)
+        * [SQL](#sql-17)
+      - [Example - `Table.*` (Single Table)](#example---table-single-table)
+        * [SQL](#sql-18)
+      - [Example - `Table.*` (With Join)](#example---table-with-join)
+        * [SQL](#sql-19)
       - [Example - Chained](#example---chained)
-        * [SQL](#sql-11)
+        * [SQL](#sql-20)
       - [Example - Join + Chained](#example---join--chained)
-        * [SQL](#sql-12)
+        * [SQL](#sql-21)
+      - [Example - Column Aliases](#example---column-aliases)
+        * [SQL](#sql-22)
+      - [Example - Aliases with Joins](#example---aliases-with-joins)
+        * [SQL](#sql-23)
     + [Having](#having)
-      - [Example](#example-8)
-        * [SQL](#sql-13)
-    + [Order By](#order-by)
       - [Example](#example-9)
-        * [SQL](#sql-14)
-    + [Limit](#limit)
+        * [SQL](#sql-24)
+    + [Order By](#order-by)
       - [Example](#example-10)
-        * [SQL](#sql-15)
-    + [Offset](#offset)
+        * [SQL](#sql-25)
+    + [Limit](#limit)
       - [Example](#example-11)
-        * [SQL](#sql-16)
+        * [SQL](#sql-26)
+    + [Offset](#offset)
+      - [Example](#example-12)
+        * [SQL](#sql-27)
   * [Future updates](#future-updates)
   * [Changelog / Versioning](#changelog--versioning)
   * [License](#license)
@@ -180,6 +206,141 @@ The way the methods are chained, are heavily inspired by [Dr Milan Milanović](h
 ### `.$from`
 This takes the `base` table to work from.
 
+#### Example
+```typescript
+prisma.$from("User")
+```
+
+#### Example - With Table Alias
+```typescript
+prisma.$from("User", "u")
+```
+
+##### SQL
+```sql
+FROM User AS u
+```
+
+**Note:** Table aliases are particularly useful for self-joins where you need to join a table to itself with different aliases.
+
+#### Example - Inline Alias Syntax
+```typescript
+prisma.$from("User u")
+```
+##### SQL
+```sql
+FROM User AS u
+```
+**Note:** Alias can be inline (space-separated) or as second parameter.
+
+### Table Aliases
+
+Table aliases allow you to give tables shorter or more meaningful names in your queries. This is especially useful for:
+- Self-joins (joining a table to itself)
+- Long table names
+- Clearer query readability
+
+#### Table Alias Syntax Options
+
+Multiple syntaxes supported:
+- **Inline in .$from()**: `prisma.$from("User u")``
+- **Inline in .join()**: `.join("Post p", "authorId", "User.id")`
+- **Object syntax**: `.join({table: "Post", src: "authorId", on: "User.id", alias: "p"})`
+
+#### Basic Table Alias
+
+```typescript
+prisma.$from("User", "u")
+  .select("u.name")
+  .select("u.email")
+  .run();
+```
+
+##### SQL
+```sql
+SELECT name, email FROM User AS u;
+```
+
+#### Table Aliases with Joins
+
+##### Inline Alias Syntax
+```typescript
+prisma.$from("User u")
+  .join("Post p", "authorId", "u.id")
+  .select("u.name")
+  .select("p.title")
+  .run();
+```
+
+##### Object Syntax
+```typescript
+prisma.$from("User", "u")
+  .join({table: "Post", src: "authorId", on: "u.id", alias: "p"})
+  .select("u.name")
+  .select("p.title")
+  .run();
+```
+
+##### SQL
+```sql
+SELECT name, title
+FROM User AS u
+JOIN Post AS p ON authorId = u.id;
+```
+
+**Note:** The object syntax provides a foundation for future enhancements like multiple join conditions and complex WHERE-style conditions in joins.
+
+#### Self-Joins with Aliases
+
+Self-joins require aliases to distinguish between the different "instances" of the same table:
+
+```typescript
+prisma.$from("User", "u1")
+  .joinUnsafeTypeEnforced("User", "id", "u1.id", "u2")
+  .select("u1.name", "user1Name")
+  .select("u2.name", "user2Name")
+  .run();
+```
+
+##### SQL
+```sql
+SELECT u1.name AS `user1Name`, u2.name AS `user2Name`
+FROM User AS u1
+JOIN User AS u2 ON User.id = u1.id;
+```
+
+#### Table.* with Aliases
+
+You can use the `alias.*` syntax to select all columns from an aliased table:
+
+```typescript
+prisma.$from("User", "u")
+  .select("u.*")
+  .run();
+```
+
+##### SQL
+```sql
+SELECT u.id, u.email, u.name FROM User AS u;
+```
+
+With joins:
+```typescript
+prisma.$from("User", "u")
+  .join("Post", "authorId", "u.id", "p")
+  .select("u.*")
+  .select("p.*")
+  .run();
+```
+
+##### SQL
+```sql
+SELECT u.id AS `u.id`, u.email AS `u.email`, u.name AS `u.name`,
+       p.id AS `p.id`, p.title AS `p.title`, p.content AS `p.content`
+FROM User AS u
+JOIN Post AS p ON authorId = u.id;
+```
+
 ### Joins
 #### `.join`
 
@@ -203,11 +364,25 @@ JOIN Post ON authorId = User.id;
 ```
 
 ##### Parameters
-| column      | Description                                                                                                                          |
-|-------------|--------------------------------------------------------------------------------------------------------------------------------------|
-| `table`     | The table to join on. <br/>TS autocomplete will show tables that can join with previously defined tables on.                         | 
-| `field`     | Column on table. <br/>TS autocomplete will show known columns that this table, can join with previously defined tables on.           | 
-| `reference` | `Table.Column` to a previously defined table (either the base, or another join), with a FK that is defined in the schema definition. | 
+| column      | Description                                                                                                                                                    |
+|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `table`     | The table to join on (supports inline alias: `"Post p"` or `"Post", "p"`). <br/>TS autocomplete will show tables that can join with previously defined tables on. |
+| `field`     | Column on table. <br/>TS autocomplete will show known columns that this table, can join with previously defined tables on.                                     |
+| `reference` | `Table.Column` to a previously defined table (either the base, or another join), with a FK that is defined in the schema definition.                           |
+
+**Alternative Syntaxes:**
+```typescript
+// Inline alias
+.join("Post p", "authorId", "User.id")
+    
+// Object syntax
+.join({
+  table: "Post",
+  src: "authorId",
+  on: "User.id",
+  alias: "p"  // optional
+})
+``` 
 
 #### `.joinUnsafeTypeEnforced`
 
@@ -229,11 +404,11 @@ JOIN Post ON Post.title = User.name;
 ```
 
 ##### Parameters
-| column      | Description                                                                                                                |
-|-------------|----------------------------------------------------------------------------------------------------------------------------|
-| `table`     | The table to join on. <br/>TS autocomplete will show tables that can join with previously defined tables on.               | 
-| `field`     | Column on table. <br/>TS autocomplete will show known columns that this table, can join with previously defined tables on. | 
-| `reference` | `Table.Column` to a previously defined table (either the base, or another join), with a column that is of the same type.   |
+| column      | Description                                                                                                                                                    |
+|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `table`     | The table to join on (supports inline alias: `"Post p"` or `"Post", "p"`). <br/>TS autocomplete will show tables that can join with previously defined tables on. |
+| `field`     | Column on table. <br/>TS autocomplete will show known columns that this table, can join with previously defined tables on.                                     |
+| `reference` | `Table.Column` to a previously defined table (either the base, or another join), with a column that is of the same type.                                       |
 
 #### `.joinUnsafeIgnoreType`
 
@@ -255,11 +430,11 @@ JOIN Post ON Post.id = User.name
 ```
 
 ##### Parameters
-| column      | Description                                                                                                                |
-|-------------|----------------------------------------------------------------------------------------------------------------------------|
-| `table`     | The table to join on. <br/>TS autocomplete will show tables that can join with previously defined tables on.               | 
-| `field`     | Column on table. <br/>TS autocomplete will show known columns that this table, can join with previously defined tables on. | 
-| `reference` | `Table.Column` to a previously defined table (either the base, or another join). Referencing any column, of any type.      |
+| column      | Description                                                                                                                                                    |
+|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `table`     | The table to join on (supports inline alias: `"Post p"` or `"Post", "p"`). <br/>TS autocomplete will show tables that can join with previously defined tables on. |
+| `field`     | Column on table. <br/>TS autocomplete will show known columns that this table, can join with previously defined tables on.                                     |
+| `reference` | `Table.Column` to a previously defined table (either the base, or another join). Referencing any column, of any type.                                          |
 
 ### Where
 
@@ -515,7 +690,7 @@ JOIN Post ON authorId = User.id
 
 #### `.select`
 
-You can supply either; `*` OR `table.field` and then chain them together.
+You can supply either; `*`, `Table.*` OR `table.field` and then chain them together.
 
 #### Example - `*`
 ```typescript
@@ -528,9 +703,49 @@ The resulting SQL will look like:
 
 ```sql
 SELECT *
-FROM User; 
+FROM User;
+```
+
+#### Example - `Table.*` (Single Table)
+```typescript
+prisma.$from("User")
+       .select("User.*");
+```
+
+##### SQL
+The resulting SQL will look like:
+
+```sql
+SELECT User.id, User.email, User.name
+FROM User;
 ```
 
+#### Example - `Table.*` (With Join)
+```typescript
+prisma.$from("User")
+      .join("Post", "authorId", "User.id")
+      .select("User.*")
+      .select("Post.*");
+```
+
+##### SQL
+The resulting SQL will look like:
+
+```sql
+SELECT User.id AS `User.id`,
+       User.email AS `User.email`,
+       User.name AS `User.name`,
+       Post.id AS `Post.id`,
+       Post.title AS `Post.title`,
+       Post.content AS `Post.content`,
+       Post.published AS `Post.published`
+FROM User
+JOIN Post ON authorId = User.id;
+```
+
+[!NOTE]
+> When using `Table.*` with joins, all columns are automatically aliased with the table name prefix to avoid column name conflicts.
+
 #### Example - Chained
 ```typescript
 prisma.$from("User")
@@ -543,28 +758,78 @@ The resulting SQL will look like:
 
 ```sql
 SELECT name, email
-FROM User; 
+FROM User;
 ```
 
 #### Example - Join + Chained
 ```typescript
 prisma.$from("User")
-      .join("Post", "authorId", "User.id")        
+      .join("Post", "authorId", "User.id")
       .select("name")
       .select("Post.title");
 ```
 
-[!NOTE]
-> Support for `Table.*` isn't complete yet. This will be tracked [here](https://github.com/adrianbrowning/prisma-ts-select/issues/31).
+##### SQL
+The resulting SQL will look like:
+
+```sql
+SELECT name, Post.title
+FROM User
+JOIN Post ON authorId = User.id;
+```
+
+#### Example - Column Aliases
+```typescript
+// Basic alias
+prisma.$from("User")
+      .select("User.name", "username");
+
+// Multiple aliases
+prisma.$from("User")
+      .select("User.id", "userId")
+      .select("User.email", "emailAddress");
+
+// Mixing aliased and non-aliased columns
+prisma.$from("User")
+      .select("User.id")
+      .select("User.name", "username")
+      .select("User.email");
+```
 
 ##### SQL
 The resulting SQL will look like:
 
 ```sql
-SELECT name, email
-FROM User; 
+-- Basic alias
+SELECT User.name AS `username` FROM User;
+
+-- Multiple aliases
+SELECT User.id AS `userId`, User.email AS `emailAddress` FROM User;
+
+-- Mixed
+SELECT User.id, User.name AS `username`, User.email FROM User;
+```
+
+#### Example - Aliases with Joins
+```typescript
+prisma.$from("User")
+      .join("Post", "authorId", "User.id")
+      .select("User.name", "authorName")
+      .select("Post.title", "postTitle");
 ```
 
+##### SQL
+The resulting SQL will look like:
+
+```sql
+SELECT User.name AS `authorName`, Post.title AS `postTitle`
+FROM User
+JOIN Post ON authorId = User.id;
+```
+
+[!NOTE]
+> When using column aliases, you can reference the alias in `ORDER BY` clauses. The returned type will use the alias names instead of the original column names.
+
 ### Having
 
 `.having` uses the same syntax as [`.where`](#where). Please see the previous section for details.