Poke
A lightweight and handy JS HTTP Client.
Why use Poke?
-
😌 Very easy to use - 👨🏻💻 Written in TypeScript
-
🚀 Lightweight - ⼮ Stream support
-
💾 Easy to download file
Installation
npm i js.poke --saveor
yarn js.pokeEasy to use!
Poke allows you to make http request in the simplest way. See the following example:
const poke = require('js.poke')
// Using promise
poke('https://foo.api.com/candys')
.promise()
.then(result => {
// response body here
console.log('> body(string): ', result.body)
// get result in json format
return result.json()
})
.then(json => {
// here is the json object
console.log('> json: ', json)
})
.catch(err => {
console.log('> Error: ', err)
})Usage
How to use poke
Poke accepts hostname, pokeOptions and the callback function as the inputs.
then it returns some methods for you to apply in different scenarios.
Omit the callback function if you would like to handle the result with Promise.
promise
const poke = require('js.poke')
// Using promise
poke(hostname , pokeOptions)
.promise()
.then(result => {
// do your handling here
...
})
.catch(error => {
// handle error
...
})callback
const poke = require('js.poke')
// Using callback
poke(hostname , pokeOptions, result => {
// status code
console.log(result.statusCode)
// body
console.log(result.body)
// in json format
result.json(json => {
console.log(json)
})
// error
console.log(result.error)
})Form Data
poke(
'https://httpbin.org/post',
{
method : 'POST',
// Specify your form data with `boby`
body : JSON.stringify({
name : 'kfhk!sdkm!'
})
}
)
// ...
Listening to events by using on
const poke = require('js.poke')
// Using callback
poke(hostname , pokeOptions)
// listen to response retrived
.on('response', result => {
console.log(result)
})
// on chunk is recieved
.on('data', (chunk) => {
// handle your data here
console.log(chunk)
})
// on request eneded
.on('end', () => {
console.log('Request is finished')
})
// listening to error
.on('error', (result) => {
// handle error
console.log(result.error)
})Stream
const fs = require('fs')
const poke = require('js.poke')
// get image
poke('https://via.placeholder.com/100x100')
// write data as an image file
.pipe(fs.createWriteStream('image.png'))Even we can using Poke as a proxy!
const poke = require('js.poke')
const serv = http.createServer((req, res) => {
if (req.url === '/placeholder') {
// get image or whatever you want
poke('https://via.placeholder.com/100x100')
// pipe response to res
.pipe(res)
} else {
res.end('Bye!')
}
})
serv.listen(4321)The Poke Options
The pokeOptions allows you to customize your request.
// The poke option
const options = {
// POST, PUT, DELETE
method : "GET",
path : "/",
port : 3001,
// will set automatically, you may override the auto-detect value by specify this boolean
gzip : true,
// in millisecond, if timeout is set and theer is no response return before timeout, request will abort
timeout : 1000
// username and password for Basic Auth
username : 'foo_user',
password : 'foo_secret'
// customize your header here
headers : {
"content-type" : "application/json"
},
// will parse your query object to query string automatically
query : { page : 3 }
// form body
body : JSON.stringify({
first_name : "Poke",
last_name : "You"
})
}
poke('https://foo.api.com', options)PokeResult
The PokeResult is returned with one of the following types PokeSuccess and PokeError.
PokeSuccess
PokeSuccess contains the req, body, statusCode, json() and headers. call json() returns a promise and parse the body into json object.
PokeError
if the request is failed, PokeError contains error(type: Error) will be returned.
poke('https://foo.api.com', options)
.promise()
.then(result => {
// status code
console.log(result.statusCode)
// body:string
console.log(result.body)
// headers
console.log(result.headers)
// parse json
return result.json()
})
.then(json => {
// handle with parsed json
console.log(json)
})
.catch(result => {
// handler error
console.log(result.error);
})Authentication
Basic-auth
Simply put your basic-auth's username and password in PokeOption.
const options = {
method : "GET",
// username and password for Basic Auth
username : 'foo_user',
password : 'foo_secret',
}
poke('https://foo.api.com', options)
.promise()
.then(result => result.json())
.then(json => console.log(result))
.catch(result => console.log(result.error))Bearer auth
Put the bearer token into header for doing bearer authentication.
const options = {
method : "GET",
headers : {
'authorization' : `Bearer ${your_bearer_token}`
}
}
poke('https://foo.api.com', options)
.promise()
.then(result => result.json())
.then(json => console.log(result))
.catch(result => console.log(result.error))Customize header
Put custom headers attributes into headers of PokeOption.
poke('https://foo.api.com', {
...
headers : {
// put your headers here....
'content-type' : 'application/json',
}
})Become a contirbutor!
Million thanks to whom contributes to this project!
Pull requests are welcome! Please see CONTRIBUTING.md
What's Next?
-
🔌 WebSocket (Upcoming)