initial commit

.gitignore

@@ -0,0 +1,6 @@
+node_modules
+.idea
+test-coverage
+examples/*/*.db
+*.iml
+*.DS_Store

.istanbul.yml

@@ -0,0 +1,2 @@
+reporting:
+  dir: ./test-coverage

.travis.yml

@@ -0,0 +1,19 @@
+# .travis.yml
+language: node_js
+
+node_js:
+  - '0.10'
+  - '0.12'
+
+before_script:
+  - psql -c "create database objection_find_test;" -U postgres
+  - mysql -e "create database objection_find_test;"
+
+after_script:
+  - npm run-script coveralls
+
+notifications:
+  email: false
+
+addons:
+  postgresql: '9.4'

LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Sami Koskimäki
+
+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.
+

README.md

@@ -0,0 +1,170 @@
+[![Build Status](https://travis-ci.org/Vincit/objection-find.js.svg?branch=master)](https://travis-ci.org/Vincit/objection-find.js) [![Coverage Status](https://coveralls.io/repos/Vincit/objection-find.js/badge.svg)](https://coveralls.io/r/Vincit/objection-find.js)
+
+# Topics
+
+- [Introduction](#fast-introduction)
+- [Installation](#installation)
+- [Getting started](#getting-started)
+- [Query parameters](#query-parameters)
+- [API documentation](#api-documentation)
+
+# Introduction
+
+Objection-find is a module for building search queries for [objection.js](https://github.com/Vincit/objection.js/)
+models using HTTP query parameters. You can easily filter the results based on model's properties and properties
+of the model's relations using simple expressions. Result can also be paged and sorted using query parameters.
+
+Using objection-find in an [express](http://expressjs.com/) route is as easy as this:
+
+```js
+var findQuery = require('objection-find');
+// Our objection.js model.
+var Person = require('../models/Person');
+
+expressApp.get('/api/persons', function (req, res, next) {
+  findQuery(Person).build(req.query).then(function (persons) {
+    res.send(persons);
+  }).catch(next);
+});
+```
+
+Objection-find can be used with any node.js framework. Express is not a requirement. The route we just created can
+be used like this:
+
+```js
+$http({
+  method: 'GET',
+  url: '/api/persons',
+
+  params: {
+    // Select all persons whose first name starts with 'j'
+    'firstName:likeLower': 'J%',
+
+    // And who have acted in the movie 'Silver Linings Playbook'.
+    // This checks if the relation `movies` contains at least
+    // one movie whose name equals 'Silver Linings Playbook'.
+    'movies.name:eq': 'Silver Linings Playbook',
+
+    // And who have at least one child younger than 10.
+    // This checks if the relation `children` contains at least
+    // one person whose age is less than 10.
+    'children.age:lt': 10,
+
+    // Order the result by person's parent's last name.
+    // `parent` is a one-to-one relation.
+    'orderBy': 'parent.lastName',
+
+    // Fetch relations for the results
+    'eager': '[children, movies, parent.movies]',
+
+    // Select a range starting from index 0
+    'rangeStart': 0,
+
+    // Select a range ending to index 4
+    'rangeEnd': 4
+  }
+}).then(function (res) {
+  var persons = res.data.results;
+
+  console.log(persons.length); // --> 5
+  console.log(persons[0].children);
+  console.log(persons[0].movie);
+  console.log(persons[0].parent.movies);
+
+  // Total size of the result if the range wasn't given.
+  console.log(res.data.total);
+});
+```
+
+In our example `Person` model had a one-to-one relation `parent`, a many-to-many relation `movies` and one-to-many
+relation `children`. This example used the `$http` module of [AngularJS](https://angularjs.org/) but you can use
+objection-find with anything that can send an HTTP request.
+
+Documentation on the supported query parameters can be found [here](#query-parameters) and API documentation
+[here](#api-documentation).
+
+# Installation
+
+```sh
+npm install objection objection-find
+```
+
+# Getting started
+
+Easiest way to get started is to use [the objection.js example project](https://github.com/Vincit/objection.js/tree/master/examples/express)
+and copy paste this to the `api.js` file:
+
+```js
+var findQuery = require('objection-find');
+
+app.get('/persons/search', function (req, res, next) {
+  findQuery(Person).build(req.query).then(function (persons) {
+    res.send(persons);
+  }).catch(next);
+});
+```
+
+You also need to run this in the root of the example project to install objection-find:
+
+```sh
+npm install --save objection-find
+```
+
+Now you can start bombing the `/persons/search` route. Documentation on the supported query parameters can be found
+[here](#query-parameters)
+
+# Query parameters
+
+Objection-find understands two kinds of query parameters: `filters` and `special parameters`.
+
+## Filters
+
+A filter parameter has the following format:
+
+```
+<propertyReference>|<propertyReference>|...:<filter>=<value>
+```
+
+A <propertyReference> is either simply a property name like `firstName` or a reference to a
+relation's property like `children.age` (`children` is the name of the relation).
+
+<filter> is one of the built-in filters `eq`, `lt`, `lte`, `gt`, `gte`, `like`, `likeLower`
+`in`, `notNull` or `isNull`. Filter can also be a custom filter registered using the
+`registerFilter` method.
+
+The following examples explain how filter parameters work:
+
+| Filter query parameter             | Explanation                                                                                             |
+|------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `firstName=Jennifer`               | Returns all Persons whose firstName is 'Jennifer'.                                                      |
+| `firstName:eq=Jennifer`            | Returns all Persons whose firstName is 'Jennifer'.                                                      |
+| `children.firstName:like=%rad%`    | Returns all Persons who have at least one child whose first name contains 'rad'.                        |
+| `lastName|movies.name:like=%Gump%` | Returns all Persons whose last name contains 'Gump' or who acted in a movie whose name contains 'Gump'. |
+| `parent.age:lt=60`                 | Returns all persons whose parent's age is less than 60.                                                 |
+| `parent.age:in=20,22,24`           | Returns all persons whose parent's age is 20, 22 or 24.                                                 |
+
+Filter query parameters are joined with `AND` operator so for example the query string:
+
+```
+firstName:eq=Jennifer&parent.age:lt=60&children.firstName:like=%rad%
+```
+
+would return the Persons whose firstName is 'Jennifer' and whose parent's age is less than 60 and who have
+at least one child whose name contains 'rad'.
+
+
+## Special parameters
+
+In addition to the filter parameters, there is a set of query parameters that have a special meaning:
+
+| Special parameter                 | Explanation                                                                                  |
+|-----------------------------------|----------------------------------------------------------------------------------------------|
+| `eager=[children, parent.movies]` | Which relations to fetch eagerly for the result models. An objection.js relation expression. |
+| `orderBy=firstName`               | Sort the result by certain property.                                                         |
+| `orderByDesc=firstName`           | Sort the result by certain property in descending order.                                     |
+| `rangeStart=10`                   | The start of the result range. The result will be `{total: 12343, results: [ ... ]}`.        |
+| `rangeEnd=50`                     | The end of the result range. The result will be `{total: 12343, results: [ ... ]}`.          |
+
+# API documentation
+
+TODO