Better sql`` types (porsager#84)

Minigugus · web-flow · commit f82d679b5f66 · 2021-02-12T10:03:09.000+01:00
* Improve rows typings

* Drop non top level array support
Only `YourType[]` accepted

* Add TypeScript in README
diff --git a/README.md b/README.md
@@ -120,6 +120,46 @@ const [new_user] = await sql`
 // new_user = { user_id: 1, name: 'Murray', age: 68 }
 ```
 
+
+#### TypeScript support
+
+`postgres` has TypeScript support. You can pass a row list type for your queries in this way:
+```ts
+interface User {
+  id: number
+  name: string
+}
+
+const users = await sql<User[]>`SELECT * FROM users`
+users[0].id // ok => number
+users[1].name // ok => string
+users[0].invalid // fails: `invalid` does not exists on `User`
+```
+
+However, be sure to check the array length to avoid accessing properties of `undefined` rows:
+```ts
+const users = await sql<User[]>`SELECT * FROM users WHERE id = ${id}`
+if (!users.length)
+  throw new Error('Not found')
+return users[0]
+```
+
+You can also prefer destructuring when you only care about a fixed number of rows.
+In this case, we recommand you to prefer using tuples to handle `undefined` properly:
+```ts
+const [user]: [User?] = await sql`SELECT * FROM users WHERE id = ${id}`
+if (!user) // => User | undefined
+  throw new Error('Not found')
+return user // => User
+
+// NOTE:
+const [first, second]: [User?] = await sql`SELECT * FROM users WHERE id = ${id}` // fails: `second` does not exist on `[User?]`
+// vs
+const [first, second] = await sql<[User?]>`SELECT * FROM users WHERE id = ${id}` // ok but should fail
+```
+
+All the public API is typed. Also, TypeScript support is still in beta. Feel free to open an issue if you have trouble with types.
+
 #### Query parameters
 
 Parameters are automatically inferred and handled by Postgres so that SQL injection isn't possible. No special handling is necessary, simply use JS tagged template literals as usual.
diff --git a/types/index.d.ts b/types/index.d.ts
@@ -247,6 +247,18 @@ declare namespace postgres {
     [column: string]: any;
   }
 
+  interface UnlabeledRow<T = any> {
+    '?column?': T;
+  }
+
+  type MaybeRow = Row | undefined;
+
+  type TransformRow<T> = T extends Serializable
+    ? { '?column?': T; }
+    : T;
+
+    type AsRowList<T extends any[]> = { [k in keyof T]: TransformRow<T[k]> };
+
   interface Column<T extends string> {
     name: T;
     type: number;
@@ -272,13 +284,13 @@ declare namespace postgres {
   }
 
   type ExecutionResult<T> = [] & ResultQueryMeta<number, T>;
-  type RowList<T extends readonly Row[]> = T & ResultQueryMeta<T['length'], keyof T[number]>;
+  type RowList<T extends MaybeRow[]> = T & Iterable<NonNullable<T[number]>> & ResultQueryMeta<T['length'], keyof T[number]>;
 
-  interface PendingQuery<TRow extends readonly Row[]> extends Promise<RowList<TRow>> {
-    stream(cb: (row: TRow[number], result: ExecutionResult<TRow[number]>) => void): Promise<ExecutionResult<keyof TRow[number]>>;
-    cursor(cb: (row: TRow[number]) => void): Promise<ExecutionResult<keyof TRow[number]>>;
-    cursor(size: 1, cb: (row: TRow[number]) => void): Promise<ExecutionResult<keyof TRow[number]>>;
-    cursor(size: number, cb: (rows: TRow) => void): Promise<ExecutionResult<keyof TRow[number]>>;
+  interface PendingQuery<TRow extends MaybeRow[]> extends Promise<RowList<TRow>> {
+    stream(cb: (row: NonNullable<TRow[number]>, result: ExecutionResult<NonNullable<TRow[number]>>) => void): Promise<ExecutionResult<keyof NonNullable<TRow[number]>>>;
+    cursor(cb: (row: NonNullable<TRow[number]>) => void): Promise<ExecutionResult<keyof NonNullable<TRow[number]>>>;
+    cursor(size: 1, cb: (row: NonNullable<TRow[number]>) => void): Promise<ExecutionResult<keyof NonNullable<TRow[number]>>>;
+    cursor(size: number, cb: (rows: NonNullable<TRow[number]>[]) => void): Promise<ExecutionResult<keyof NonNullable<TRow[number]>>>;
   }
 
   interface PendingRequest extends Promise<[] & ResultMeta<null>> { }
@@ -296,7 +308,7 @@ declare namespace postgres {
      * @param args Interpoled values of the template string
      * @returns A promise resolving to the result of your query
      */
-    <T extends Row | Row[] = Row>(template: TemplateStringsArray, ...args: SerializableParameter[]): PendingQuery<T extends Row[] ? T : T[]>;
+    <T extends any[] = Row[]>(template: TemplateStringsArray, ...args: SerializableParameter[]): PendingQuery<AsRowList<T>>;
 
     /**
      * Escape column names
@@ -321,8 +333,8 @@ declare namespace postgres {
     begin<T>(cb: (sql: TransactionSql<TTypes>) => T | Promise<T>): Promise<UnwrapPromiseArray<T>>;
     begin<T>(options: string, cb: (sql: TransactionSql<TTypes>) => T | Promise<T>): Promise<UnwrapPromiseArray<T>>;
     end(options?: { timeout?: number }): Promise<void>;
-    file<T extends Row | Row[] = Row>(path: string, options?: { cache?: boolean }): PendingQuery<T extends Row[] ? T : T[]>;
-    file<T extends Row | Row[] = Row>(path: string, args: SerializableParameter[], options?: { cache?: boolean }): PendingQuery<T extends Row[] ? T : T[]>;
+    file<T extends any[] = Row[]>(path: string, options?: { cache?: boolean }): PendingQuery<AsRowList<T>>;
+    file<T extends any[] = Row[]>(path: string, args: SerializableParameter[], options?: { cache?: boolean }): PendingQuery<AsRowList<T>>;
     json(value: any): Parameter;
     listen(channel: string, cb: (value?: string) => void): PendingRequest;
     notify(channel: string, payload: string): PendingRequest;
@@ -333,7 +345,7 @@ declare namespace postgres {
       ? (...args: Parameters<TTypes[name]>) => postgres.Parameter<ReturnType<TTypes[name]>>
       : (...args: any) => postgres.Parameter<any>;
     };
-    unsafe<T extends Row | Row[] = any[]>(query: string, parameters?: SerializableParameter[]): PendingQuery<T extends Row[] ? T : T[]>;
+    unsafe<T extends any[] = Row[]>(query: string, parameters?: SerializableParameter[]): PendingQuery<AsRowList<T>>;
   }
 
   interface TransactionSql<TTypes extends JSToPostgresTypeMap> extends Sql<TTypes> {
