PQ: Human Readable Promise Chain Query Compiler
Promises are awesome. But when it comes to write promise chains, it becomes kind of hard to write. PQ solves this issue and allows you to create human readable promise chains
- Make your Promises more human-readable.
- Allows to create your own DSL.
- Zero-dependency.
pq.debug()
gives you a cool debugger to debug your queries
Install
You can simply use NPM/Bower to download pq.
# Using NPM
npm install pquery --save
# Using Bower
bower install pquery --save
Overview
What you write:
// or more functional // or Unix way // or reverse pipeline
This is actually what you run:
Why?
I use promises in many cases in my daily work. And calling a promise chain is a bit boring to write. I used to write then
keyword again and again to create a chain and this drive me crazy, they seem ugly.
So, I created pq to make this chains easier to write and easier to read.
Let's checkout a real-world promise example:
var foo = foo // this then's may go to the sky, or the hell!
This is how to write this using pq:
Queries are Powerful Strings
Since pq is just a string, you can create queries anywhere you want and these may be handy to write your own DSL. Here is a real-world example:
Instead of writing this promise chain:
Just write this:
{% $data.forEach(function (item) { %} {{ item.name }} costs {{ item.price }} {% }) %}
How to Write Queries
There are few simple rules to write a readable query:
Promise Chain Keywords
then
and of
are main keywords to generate promise chains. foo then bar
is actually foo.then(function (r) { return r.bar })
. Since they are chained, the left part of chain must have the right of the chain.
of
(reverse promise keyword) makes the query more readable. Just like the SQL, you define what you want at first. bar of foo
is foo.then(function (r) { return r.bar })
, too.
Keyword | Description | Example |
---|---|---|
.. then or .. -> .. or |> or | |
Simple promise chain | @json then data , @json -> data |
.. of .. or .. <- .. or <| |
Simple promise chain, reversed | data of @json , data <- @json |
You can use
of
andthen
together:full_name of user then last_letter of first_name
. This will be run like:(full_name of user) then (last_letter of first_name)
, which is actuallyuser then full_name then first_name then last_letter
.
If it becomes confusing to you, do not use them together
Meta Characters (Optional)
Meta characters are optional. But they want to make your query easier to read/write. If you want to call a function, you can just put a @
character beginning of it. @json
will be converted to json()
.
The most useful meta character is %{number}
. It allows you to pass arguments to the pq
. ("a of %1", "b")
will be a of b
.
Character | Description | Example | Equivalent |
---|---|---|---|
@ |
Method Calling | @methodName |
methodName() |
%{number} |
Simple Parameters | pq(promise, "%1 of @json", "hello") |
pq(promise, "hello of @json") |
& |
This Object | &.length of users of @json |
this.length of users of json() |
# |
Single Call | @json of #fetch(...) |
|
! |
Promisify | response of !functionWithCallback |
Tutorial
This is a simple, delayed Promised function:
{ return { return { return } }} { return { }}
Let's query this using pq:
Let's make it more complex:
How to Write Custom Parsers
It's too easy to add custom parsers using pq.parse
command:
pq pq
Then you'll be able to use your custom parsers.
Query Reducers
Query reducers helps you to manage your data flow easier.
pq.before
pq.before
will give you the raw query so you can make changes on it on-the-fly.
pq
pq.after
pq.after
will give you compiled promise fragments.
pq
License
MIT Licensed - Copyright © 2016 by Fatih Kadir Akın