feat: inital release

Tombre · Tombre · commit a7f220027dfc · 2019-07-30T16:56:56.000+08:00
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,11 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,3 @@
+node_modules
+dist
+.DS_Store
diff --git a/.npmignore b/.npmignore
@@ -0,0 +1,2 @@
+yarn.lock
+__snapshots__/
diff --git a/.prettierignore b/.prettierignore
@@ -0,0 +1 @@
+package.json
diff --git a/.prettierrc b/.prettierrc
@@ -0,0 +1,5 @@
+{
+    "semi": false,
+    "singleQuote": true,
+    "tabWidth": 4
+}
diff --git a/.travis.yml b/.travis.yml
@@ -0,0 +1,20 @@
+language: node_js
+node_js:
+    - lts/*
+cache: yarn
+notifications:
+    email: false
+script: yarn verify
+jobs:
+    include:
+        - stage: release
+          node_js: lts/*
+          deploy:
+              provider: script
+              skip_cleanup: true
+              script:
+                  - npx semantic-release
+env:
+    global:
+        - secure: HHvgRKLtWU+akAItiK4P4HU6O0AAzLSsxu2ccAXRLN+ZctziMvw/M5/K829bjj5CDVRPY6LK9IwFGcNFGsx8dqZq8pLjsJZT3gpXRkLb3qHkvfuLFeTTRXj24tgFg3kySbqu2CRAFM70zxnM0eaJuKeoOreS4Wzxgw5xAFYjzvkn5vhjl3h9Qe9MZcAGueeAi7Jgb2QIXtuSXV96Qvlv+a6u4J2cAj7x56O5nIYCT+GoxG2bYoDQwosV6KgzdTpGungY0/0saByiIih/NiKfzA+BjXjDoDb9NxrbRyqEYarFDZTXBgAoRaWbrK+sPmWGPfyMfDEjytK/5+PVKtWVSrkHyjHVBlG0JOqCzUL0ZS331/5EUHuW5uRJ/s/GlMfRaeUcmpGu2YELKiNu6WTOTA/IMiVYv1Lv0H7bDPhSTCxYazpbQfigNyO4KmlIgC7DpfE1RSB01ukRo6nfGU0s0Du0zUl+3iLacG2w2UGRLOA6D1r8Eul/TQnwFtwyT3AYhZeYe0JZDdgdSeJ934LwAnTFvLfM98Isaq6g7nIjzeUuS3Kw3T54dLq4dn+zb7mLb6mPx8ziTyvD+IsXz3JEMdhGkyl3oHg1iItkeB1l3eJua8hk2qulw64U7rq4w+vESas+N7mRjQQqoZjvhWLK3hWoRQJ5mgwqRkoJvhRS9eg=
+        - secure: gayubakLx4qkVEvwyKl4l8/QOfinaoMath9XuE2Nyq0J/npVMYzho812O3tVHDaTzfmEyPgn1mzHIROVDVJDbA1X5I29/yWhQ0fZF75AC8cDsVDcSPHOUV6koz1dtsms5yDGtbnC+Gqkw8xANvLx+7MdQYRDGO4rZkvemdyPIaS9ZgeAEnYwu814HQpmoRtvUSIv9fmghV+WsxvykiOGQ9nEqETG/YAFU06e0PJ7/QBS46Dk5CsvyuNNl0CmvK88aP20CgKWNt/zcy7RMyolo80tkaK9N4csfMRmZTD/Q0M2rnPAVROCnsk9E0esqsuBrMwHRZ7e6t/3Xpb2jstX/zATAkkEWj71fgQCKzMyIWJ0BGECVsRvVft4UQjM45ddFSAeMPhb5RZs6uXajeaYeQH3UrQx6L+volPZF+30LfN3vx7QMsn3LVOSCoOIIp6hvXZ4eP4kbL8tzLxuu9efzX9yedOSy3g1q9RcsZd2VWUe5leJfMfRZZB+jHnfYoU/q+7iMFQUTcVkfJetYD5WMzg11K1BNCz7h0scPA4x/30Tb4cVTHTx9HnqUGpq5gEgln2GOwreE8YJ7KCLyEQYtp4keGa167PUOAsK9VVVvTq+16EjEqyM4N6cxfEQBk5Ca0bUvnqn/aPU9mut4dpjBljPbQxskVQ3T0ahWXe9+Jo=
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -0,0 +1,17 @@
+{
+    // Use IntelliSense to learn about possible Node.js debug attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Debug tests: current file",
+            "program": "${workspaceRoot}/node_modules/.bin/jest",
+            "args": ["${relativeFile}", "--runInBand"],
+            "cwd": "${workspaceRoot}",
+            "sourceMaps": true
+        }
+    ]
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,3 @@
+{
+    "editor.formatOnSave": true
+}
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
@@ -0,0 +1,16 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "type": "typescript",
+            "tsconfig": "tsconfig.json",
+            "problemMatcher": ["$tsc"],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        }
+    ]
+}
diff --git a/LICENCE b/LICENCE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Seven West Media
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -0,0 +1,187 @@
+# Node query executor
+
+[![Build Status](https://travis-ci.com/sevenwestmedia-labs/node-knex-query-executor.svg?branch=master)](https://travis-ci.com/sevenwestmedia-labs/node-knex-query-executor) ![](https://img.shields.io/npm/v/node-knex-query-executor.svg)
+
+A simple library which enables encapsulation of knex queries inside functions. It enables inversion of control for database queries, making it easy to mock the database layer entirely while making database queries themselves easy to test.
+
+## Why
+
+Using knex directly in code means often it is hard to create re-usable database queries, to avoid this the queries are put into functions and the `knex` instance passed into those function. This approach is hard to test and often results in many queries being written inline in places query code should not be written directly.
+
+By forcing all queries to be encapsulated it encourages reuse of queries and building a collection of well tested queries.
+
+## Usage
+
+This library extends this concept to introduce a `QueryExecutor` which can be instructed to execute queries. There are 3 variations, the `ReadQueryExecutor` which is the entry point, when the `unitOfWork` function is called a `UnitOfWorkQueryExecutor` is passed in the callback, everything inside this callback will be executed inside a transaction. If the promise rejects the transaction will be rolled back.
+
+### Constructor
+
+The query executor is a class, to start using it you need to create an instance of the `ReadQueryExecutor`.
+
+```ts
+const queryExecutor = new ReadQueryExecutor(
+    // The knex instance
+    knex,
+    // The services object is available to all queries, ie a logger
+    {
+        logger
+    },
+    // Table names is an object with the tables you would like to access,
+    // mapping from the JS name to the database table name
+    {
+        tableOne: 'table-one'
+    },
+    // Optional, you can wrap every query before execution, allowing you to hook in logs or
+    // some other manipulation
+    query => query
+)
+```
+
+#### Query Executor types
+
+There are 3 query executor classes, you should only need to construct the `ReadQueryExecutor` as above.
+
+-   `ReadQueryExecutor`: Entry point, represents a query executor not in a transaction
+-   `UnitOfWorkQueryExecutor`: Type used when function wants to execute a query inside a transaction
+-   `QueryExecutor`: Type when code does not care if the query is executed inside or outside a transaction
+
+### Executing a query
+
+```ts
+// If using TypeScript it is advised to use the create query helper
+// which can infer all the types from usage
+interface QueryArgs {
+    someArg: string
+}
+
+interface QueryResult {
+    col1: string
+}
+
+// NOTE: Name your functions here if possible, it makes the error messages when using
+// the mock query executor better
+const exampleQuery = queryExecutor.createQuery(async function exampleQuery<
+    QueryArgs,
+    QueryResult
+>({ args, tables, tableNames, query }) {
+    // You can access the query arguments through `args`
+    const { someArg } = args
+
+    // Use tables to get Knex.QueryBuilder's for each table
+    const result = await tables.tableOne().where(...).select('col1')
+
+    // Use tableNames if you need to access a table name directly (for joins etc)
+    // Use query() to access knex directly (it is a callback for wrapping purposes)
+    const result = await query(knex => knex(tableNames.tableOne).select('col1'))
+
+    // It is the queries responsibility to ensure the type is correct
+    return result
+})
+
+// Then execute the query
+const queryResult = await queryExecutor.execute(exampleQuery).withArgs({})
+```
+
+### Wrapping database queries
+
+Sometimes you may want to instrument knex queries (for benchmarking, debugging etc), the query executor makes this really easy.
+
+```ts
+const queryExecutor = new ReadQueryExecutor(knex, {}, tables, {
+    queryBuilderWrapper: (query: Knex.QueryBuilder) => {
+        // Do what you want here
+
+        return query
+    },
+    rawQueryWrapper: (query: Knex.Raw) => {
+        // Do what you want here
+
+        return query
+    }
+})
+```
+
+### Testing
+
+```ts
+import { NoMatch, MockQueryExecutor } from 'node-query-executor'
+
+const queryExecutor = new MockQueryExecutor()
+
+const exampleQuery = queryExecutor.createQuery<{}, number>(async ({}) => {
+    // real query here
+})
+const exampleQuery2 = queryExecutor.createQuery<{ input: number }, number>(
+    async ({}) => {
+        // real query here
+    }
+)
+
+// Setup the mock in the query executor, returning the same value no matter the args
+queryExecutor.mock(exampleQuery).match(() => {
+    return 1
+})
+
+// You can also chain matches, inspecting the query arguments
+queryExecutor
+    .mock(exampleQuery2)
+    .match(({ input }) => {
+        // Return 1 if even
+        if (input % 2 === 0) {
+            return 1
+        }
+
+        // Use the NoMatch symbol otherwise
+        return NoMatch
+    })
+    .match(({ input }) => {
+        // Return 0 if odd
+        if (input % 2 === 1) {
+            return 0
+        }
+
+        return NoMatch
+    })
+```
+
+## Simplifying types
+
+Because the QueryExecutor types are generic, it often is verbose writing `QueryExecutor<typeof keyof tableNames, YourQueryServices>`, it is suggested you export your own closed generic types to make them easy to pass around.
+
+```ts
+import * as KnexQueryExecutor from 'node-knex-query-executor'
+
+interface YourQueryServices {
+    log: Logger
+}
+
+export type Query<QueryArguments, QueryResult> = KnexQueryExecutor.Query<
+    QueryArguments,
+    QueryResult,
+    keyof typeof tableNames,
+    YourQueryServices
+>
+export type QueryExecutor = KnexQueryExecutor.QueryExecutor<
+    keyof typeof tableNames,
+    YourQueryServices
+>
+export type ReadQueryExecutor = KnexQueryExecutor.ReadQueryExecutor<
+    keyof typeof tableNames,
+    YourQueryServices
+>
+export type UnitOfWorkQueryExecutor = KnexQueryExecutor.UnitOfWorkQueryExecutor<
+    keyof typeof tableNames,
+    YourQueryServices
+>
+export type TableNames = KnexQueryExecutor.TableNames<keyof typeof tableNames>
+export type Tables = KnexQueryExecutor.Tables<keyof typeof tableNames>
+```
+
+## Further reading
+
+This library is inspired by a few object oriented patterns, and a want to move away from repositories.
+
+https://en.wikipedia.org/wiki/Specification_pattern  
+https://martinfowler.com/eaaCatalog/queryObject.html  
+https://lostechies.com/chadmyers/2008/08/02/query-objects-with-the-repository-pattern/  
+https://codeopinion.com/query-objects-instead-of-repositories/
diff --git a/jest.config.js b/jest.config.js
@@ -0,0 +1,4 @@
+module.exports = {
+    preset: 'ts-jest',
+    testEnvironment: 'node'
+}
diff --git a/package.json b/package.json
@@ -0,0 +1,29 @@
+{
+    "name": "typescript-object-validator",
+    "version": "0.0.0",
+    "description": "TypeScript first object validator",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "prepack": "yarn build",
+        "build": "tsc -p tsconfig.build.json",
+        "lint": "yarn tslint --project .",
+        "test": "jest",
+        "verify": "yarn tsc -p tsconfig.json && yarn test && yarn lint",
+        "cz": "git-cz"
+    },
+    "author": "Jake Ginnivan",
+    "license": "MIT",
+    "devDependencies": {
+        "@types/jest": "^23.3.10",
+        "commitizen": "^3.0.5",
+        "cz-conventional-changelog": "^2.1.0",
+        "jest": "^23.6.0",
+        "semantic-release": "^15.13.2",
+        "ts-jest": "^23.10.5",
+        "tslint": "^5.12.0",
+        "tslint-config-prettier": "^1.17.0",
+        "tslint-eslint-rules": "^5.4.0",
+        "typescript": "^3.2.2"
+    }
+}
diff --git a/src/index.ts b/src/index.ts
diff --git a/src/validation.spec.ts b/src/validation.spec.ts
diff --git a/tsconfig.build.json b/tsconfig.build.json
diff --git a/tsconfig.json b/tsconfig.json
diff --git a/tslint.json b/tslint.json
diff --git a/yarn.lock b/yarn.lock

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+node_modules`
	`2`	`+dist`
	`3`	`+.DS_Store`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "editor.formatOnSave": true`
	`3`	`+}`