This project is no longer in active development. It was a way for me to try out new tools.
This utility is used to add filters to an Objection query builder
Objection ORM is added as a dependency in this project as certain functionalities are required.
Table of contents
In your package.json
, add the following dependency:
"objection-filters-util": "git+ssh://git@github.com:cmburcus/util_ObjectionFilters.git"
Then install your dependencies with npm
or yarn
In your code, import the package:
const objectionFiltersUtil = require('objection-filters-util');
Use the following functions as required:
The query builder is required at all times
If the parameters are undefined, the query builder will be returned as is
If the parameter are not a string or are not the right format, an error will be thrown (exception for pagination where numbers are allowed)
Function: addSelect(queryBuilder, selectString)
Appends a select query to the query builder. It assumes the string is comma separated.
Example of properly formatted string: 'column_one,column_two'
Function: addFilter(queryBuilder, filterString)
Appends additional filters to the query. The filterString should be a valid JSON array containing filter objects
Allowed filter keys:
column
: the database column nameoperator
: valid operator as defined below- gt
- gte
- lt
- lte
- ne
- eq
- like
value
: values to check againstcondition
: valid condition as defined below- and
- or
range
: valid range type as defined below- in
- orIn
- notIn
- orNotIn
- between
- orBetween
- notBetween
- orNotBetween
Other notes:
column
andvalue
must ALWAYS be definedcolumn
must be a stringcondition
will be ignored ifrange
is defined. Just use the conditional range if you need to (eg. orNotBetween)
Function: addOrderBy(queryBuilder, orderByString)
Appends an order by to the query builder. If ASC
or DESC
is not defined, ASC
will be default
Examples of properly formatted string:
'column_one'
- Returns ascending order'column_one,ASC'
or'column_one,asc'
- Returns ascending order'column_one,DESC'
or'column_one,desc'
- Returns descending order
Function: addPagination(queryBuilder, page, pageSize)
Adds pagination to the query builder
Examples:
addPagination(queryBuilder, 1, 50);
addPagination(queryBuilder, '1', '50');
To make development and deployment easy, this service makes use of Docker and Docker Compose.
Containers
- node:9.11.1
- name: objection_filters_util_node
In order to run this project, you simply need Docker and Docker Compose.
Any other system dependencies come already set up using Docker so you do not need to install them locally on your machine.
- Docker >= 18.03
- Docker Compose >= 1.21
git clone git@github.com:cmburcus/util_ObjectionFilters.git
cd util_ObjectionFilters
You shouldn't have to run the commands inside the package.json
file as you should be using docker to run your project. The commands to run are setup in the Makefile
file
Build development environment
make build
Your docker container will be built (including having dependencies installed)
Build and run tests in the environment
make test
Runs the build
command but also runs your tests and closes the environment once it's done
Build container
make start
Simply builds your docker container
Stop development environment
make stop
Stops the docker container
Clean development environment
make clean
Stops environment and removes associated images.
Install node dependencies
make install-dependencies
Installs the node dependencies in the node container
run-tests
make run-tests
Runs the series of tests
NOTE: It assumes that the environment is up and dependencies have been installed
SSH into the node container
make ssh
Gives SSH access to the node container
Display logs
make logs
Displays the logs generated
Format code with ESLint and Prettier
make format
This will spin up the environment, format the code and then stop the environment
Testing should be a priority. All aspects of the application should be fully tested as much as possible.
This project is using Mocha with Chai. The test subdirectories and files should be placed under the test
folder.
To run the tests one time
This command will start the environment (unless already running), run the tests and then stop the environment
make test
If you're planning on running tests multiple times, you can run the following commands instead
Start the environment
make build
Run your tests. You can modify the test files in between runs
make run-tests
When you're done, you can stop the testing environment
make stop
Migrate database
make migrate-database
Migrates the database (The sqlite database is only used for testing purposes)
Features
Adding new functionality to the application or changing existing functionalities
Case A: Small feature (one branch)
- Branch out of
master
- Prefix branch name with
feature/your-branch-name
- Before committing:
- Rebase your branch from
master
to get the latest changes - Run
make format
to ensure code standards (There is no automated system) - Run
make test
to test the application
- Rebase your branch from
- Make a Pull Request into
master
Case B - Bigger feature (two or more branches)
- Branch out of
master
- Create an integration branch named
feature-name/master
- Push
feature-name/master
to origin - For each small feature:
- Branch out of
feature-name/master
- Name your branch
feature/your-branch-name
- Before committing:
- Rebase your branch from
feature-name/master
to get the latest changes - Run
make format
to ensure code standards (There is no automated system) - Run
make test
to test the application
- Rebase your branch from
- Make a Pull Request into
feature-name/master
- Branch out of
- When your big feature is complete:
- Rebase
feature-name/master
frommaster
to get the newest version - Run
make format
to ensure code standards (There is no automated system) - Run
make test
to test the application - Make a Pull Request from
feature-name/master
tomaster
- Rebase
Fixes
Fixing bugs that might have been generated from features
- Branch out of
master
- Name your branch
fix/your-branch-name
- Before committing:
- Rebase your branch from
master
to get the latest changes - Run
make format
to ensure code standards (There is no automated system) - Run
make test
to test the application
- Rebase your branch from
- Make a Pull Request into
master
- Make a Pull Request into
develop
Support
No code modification should be performed in a support branch. You may update documentation or perform tasks to improve development (such as updating node_modules).
- Branch out of
master
- Name your branch
support/your-branch-name
- Before committing:
- Rebase your branch from
master
to get the latest changes - Run
make format
to ensure code standards (There is no automated system) - Run
make test
to test the application
- Rebase your branch from
- Make a Pull Request into
develop
Releases
Version that has aquired enough features / bug fixes to be released.
Use pre-release
as needed. Ideally all major versions should have a pre-release, but it can also be used for minor versions.
Versioning
major.minor.patch
or major.minor.patch-rc.iteration
patch
- MUST be incremented if only backwards compatible bug fixes are introducedminor
- MUST be incremented if new backwards compatible functionality is introduced- SHOULD be incremented if a functionality is marked as deprecated
- MAY be incremented if substantial new functionality or improvements are introduced within the private code
- MAY include patch level changes
- Patch version MUST be reset to 0 when minor version is incremented
major
- MUST be incremented if any backwards incompatiblerc
- Stands for release candiateiteration
- MUST be incremented when changes were brought to the release candidate
Case A: Pre-release
No new features should be added until release is ready!
- Make sure you are on the latest version of
master
- Create an anotated tag using the format
major.minor.patch-rc.iteration
- You may continue adding
fix
orsupport
branches tomaster
if the release candidate requires it. If you do, you MUST create a new pre-release and increment the iteration when ready
Case B: Release - Ready to be deployed to production
- Make sure you are on the latest version of
master
- Create an anotated tag using the format
major.minor.patch
# Once done with any of the two cases above, push the tags
git push origin --tags