Add typescript declaration file (#1)

Author: yannvgn

package.json

@@ -11,18 +11,22 @@
     "pg"
   ],
   "files": [
-    "sql.js"
+    "sql.js",
+    "types/index.d.ts"
   ],
+  "types": "types",
   "scripts": {
     "test": "jest",
     "prettier": "prettier --write '**/*.{js,json,css,md}' --ignore-path .gitignore",
-    "lint": "eslint '**/*.js' --ignore-path .gitignore"
+    "lint": "eslint '**/*.js' --ignore-path .gitignore",
+    "dtslint": "dtslint types"
   },
   "devDependencies": {
     "@sequencework/eslint-config": "^0.0.7",
-    "jest": "^23.5.0",
+    "dtslint": "^0.3.0",
     "eslint": "5.4.0",
     "husky": "1.0.0-rc.13",
+    "jest": "^23.5.0",
     "lint-staged": "7.2.2",
     "prettier": "1.14.2"
   },
@@ -50,6 +54,10 @@
     "*.{json,css,md}": [
       "prettier --write",
       "git add"
+    ],
+    "*.ts": [
+      "prettier --write",
+      "git add"
     ]
   }
 }

readme.md

@@ -9,6 +9,7 @@ Transforms a template literal in an object that can be read by [node-postgres](h
 - Nested sql tags
 - `undefined` expressions are ignored
 - Useful [shorthand for node-postgres](#shorthand-fo-postgres) : sql(db)\`...\`
+- [TypeScript-friendly](#usage-with-typescript)
 
 ### Installation
 
@@ -179,6 +180,23 @@ const listMoviesByYear = async (db, yearRange) => sql(db)`
 `
 ```
 
+### Usage with TypeScript
+
+`sql` comes with its TypeScript declaration file. You can directly use it within your TypeScript projects:
+
+```ts
+import sql = require('@sequencework/sql')
+
+const yearRange: ReadonlyArray<number> = [1983, 1992]
+
+const query = sql`
+  select * from movies
+  where
+    year >= ${yearRange[0]}
+    and year <= ${yearRange[1]}
+`
+```
+
 ### More
 
 This package is inspired by the great [sql-template-strings](https://github.com/felixfbecker/node-sql-template-strings). Some interesting features that we were missing :

test/sql.test.js

@@ -84,7 +84,7 @@ test('shorthand for node-postgres', async () => {
       if (text === 'select * from books') {
         return { rows: sampleBooks }
       }
-      return { rows: false }
+      return { rows: [] }
     }
   }
 

types/index.d.ts

@@ -0,0 +1,24 @@
+// TypeScript Version: 2.9
+
+export = sql
+
+declare function sql(chains: {
+  readonly query: (
+    queryExpression: sql.QueryConfig
+  ) => Promise<{
+    rows: any[]
+  }>
+}): (chains: ReadonlyArray<string>, ...expressions: any[]) => Promise<any[]>
+
+declare function sql(
+  chains: ReadonlyArray<string>,
+  ...expressions: any[]
+): sql.QueryConfig
+
+declare namespace sql {
+  interface QueryConfig {
+    _sql?: { chains: ReadonlyArray<string>; expressions: any[] }
+    text: string
+    values: any[]
+  }
+}

types/test.ts

@@ -0,0 +1,68 @@
+// This contains sample code which tests the typings. This code does not run, but it is type-checked.
+// See https://github.com/DefinitelyTyped/DefinitelyTyped
+
+import sql = require('@sequencework/sql')
+
+const yearRange = [1983, 1992]
+
+// basic usage
+// $ExpectType QueryConfig
+sql`
+  select * from movies
+  where
+    year >= ${yearRange[0]}
+    and year <= ${yearRange[1]}
+`
+
+// expressions returning undefined
+// $ExpectType QueryConfig
+sql`
+  select * from books
+  ${undefined}
+`
+
+// expressions returning booleans
+// $ExpectType QueryConfig
+sql`select * from books where read = ${false}`
+
+// expressions returning null
+// $ExpectType QueryConfig
+sql`select * from books where author = ${null}`
+
+// imbricated sql tags
+const author = 'steinbeck'
+// $ExpectType QueryConfig
+sql`
+  select * from books
+  ${author && sql`where author = ${author}`}
+`
+
+// imbricated sql tags (2 levels)
+const [expr0, expr1, expr2] = ['i', 'like', 'sql']
+// $ExpectType QueryConfig
+sql`
+  level 0 ${expr0}
+  ${sql`
+    level 1 ${expr1}
+    ${sql`
+      level 2 ${expr2}
+    `}
+  `}
+`
+
+// shorthand for node-postgres
+const sampleBooks = ['book1', 'book2']
+const db = {
+  query: async ({ text, values }: { text: string; values: any[] }) => {
+    if (text === 'select * from books') {
+      return { rows: sampleBooks }
+    }
+    return { rows: [] }
+  }
+}
+const getBooks = async (): Promise<string[]> => {
+  const rows = await sql(db)`select * from books`
+  return rows as string[]
+}
+// $ExpectType Promise<string[]>
+getBooks()

types/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "lib": ["es6"],
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "noEmit": true,
+
+    // If the library is an external module (uses `export`), this allows your test file to import "mylib" instead of "./index".
+    // If the library is global (cannot be imported via `import` or `require`), leave this out.
+    "baseUrl": ".",
+    "paths": { "@sequencework/sql": ["."] }
+  }
+}

types/tslint.json

@@ -0,0 +1,7 @@
+{
+  "extends": "dtslint/dtslint.json",
+  "rules": {
+    "semicolon": false,
+    "indent": [true, "spaces", 2]
+  }
+}