Low-level package to handle completion and errors of sync or asynchronous functions, using once and dezalgo libs. Useful for and used in higher-level libs such as always-done to handle completion of anything.
npm i try-catch-core --save
For more use-cases see the tests
const fs = require('fs')
const tryCatchCore = require('try-catch-core')
tryCatchCore((cb) => {
fs.readFile('./package.json', 'utf8', cb)
}, (err, res) => {
if (err) return console.error(err)
let json = JSON.parse(res)
console.log(json.name) // => 'try-catch-core'
})Why this exists? What is useful for? What's its core purpose and why not to use something other? Why not plain try/catch block? What is this?
Simply said, just try/catch block. But on steroids. Simple try/catch block with a callback to be called when some function completes - no matter that function is asynchronous or synchronous, no matter it throws.
There are few reasons why this is built.
- simplicity: built on try-catch-callback, once and dezalgo - with few lines of code
- flexibility: allows to pass custom function context and custom arguments
- guarantees: completion is always handled and always in next tick
- low-level: allows to build more robust wrappers around it in higher level, such as always-done to handle completion of anything - observables, promises, streams, synchronous and async/await functions.
It's always useful to have low-level libs as this one. Because you can build more higher level libs on top of this one. For example you can create one library to handle completion of generator functions. It would be simply one type check, converting that generator function to function that returns a promise, than handle that promise in the callback.
Brilliant example of higher level lib is always-done which just pass given function to this lib, and handles the returned value inside callback with a few checks.
Another thing can be to be used as "thunkify" lib, because if you does not give a callback it returns a function (thunk) that accepts a callback.
Guarantees. This package gives you guarantees that you will get correct result and/or error of execution of some function. And removes the boilerplate stuff. Also works with both synchronous and asynchronous functions. But the very main thing that it does is that it calls the given callback in the next tick of event loop and that callback always will be called only once.
Executes given
fnand pass results/errors to thecallbackif given, otherwise returns a thunk. In below example you will see how passing custom arguments can be useful and why such options exists.
Params
<fn>{Function}: function to be called.[opts]{Object}: optional options, such ascontextandargs, passed to try-catch-callback[opts.context]{Object}: context to be passed tofn[opts.args]{Array}: custom argument(s) to be pass tofn, given value is arrayified[opts.passCallback]{Boolean}: passtrueif you wantcbto be passed tofnargs.[cb]{Function}: callback withcb(err, res)signature.returns{Function}thunk: ifcbnot given.
Example
var tryCatch = require('try-catch-core')
var options = {
context: { num: 123, bool: true }
args: [require('assert')]
}
// `next` is always there, until
// you pass `passCallback: false` to options
tryCatch(function (assert, next) {
assert.strictEqual(this.num, 123)
assert.strictEqual(this.bool, true)
next()
}, function (err) {
console.log('done', err)
})Handle completion of synchronous functions (functions that retunrs something) and asynchronous (also known as callbacks), but not
async/awaitor other functions that returns promises, streams and etc - for such thing use always-done.
const tryCatchCore = require('try-catch-core')
tryCatchCore(() => {
return 123
}, (err, res) => {
console.log(err, res) // => null, 123
})const tryCatchCore = require('try-catch-core')
tryCatchCore(() => {
foo // ReferenceError
return 123
}, (err) => {
console.log(err) // => ReferenceError: foo is not defined
})const fs = require('fs')
const tryCatchCore = require('try-catch-core')
tryCatchCore((cb) => {
// do some async stuff
fs.readFile('./package.json', 'utf8', cb)
}, (e, res) => {
console.log(res) // => contents of package.json
})const fs = require('fs')
const tryCatchCore = require('try-catch-core')
tryCatchCore((cb) => {
fs.stat('foo-bar-baz', cb)
}, (err) => {
console.log(err) // => ENOENT Error, file not found
})const tryCatchCore = require('try-catch-core')
const opts = {
context: { foo: 'bar' }
}
tryCatchCore(function () {
console.log(this.foo) // => 'bar'
}, opts, () => {
console.log('done')
})It may be strange, but this allows you to pass more arguments to that first function and the last argument always will be "callback" until
fnis async or sync but withpassCallback: trueoption.
const tryCatchCore = require('try-catch-core')
const options = {
args: [1, 2]
}
tryCatchCore((a, b) => {
console.log(arguments.length) // => 2
console.log(a) // => 1
console.log(b) // => 2
return a + b + 3
}, options, (e, res) => {
console.log(res) // => 9
})Can be used as thunkify lib without problems, just don't pass a done callback.
const fs = require('fs')
const tryCatchCore = require('try-catch-core')
const readFileThunk = tryCatchCore((cb) => {
fs.readFile('./package.json', cb)
})
readFileThunk((err, res) => {
console.log(err, res) // => null, Buffer
})- catchup: Graceful error handling. Because core
domainmodule is deprecated. This share almost… more | homepage - function-arguments: Get arguments of a function, useful for and used in dependency injectors… more | homepage
- gana-compile: Pretty small synchronous template engine built on ES2015 Template Strings, working on… more | homepage
- gana: Small and powerful template engine with only sync and async compile. The… more | homepage
- is-async-function: Is function really asynchronous function? Trying to guess that based on check… more | homepage
- relike: Simple promisify async or sync function with sane defaults. Lower level than… more | homepage
- try-catch-callback: try/catch block with a callback, used in try-catch-core. Use it when you… more | homepage
- try-require-please: Try to require the given module, failing loudly with default message if… more | homepage
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Please read the contributing guidelines for advice on opening issues, pull requests, and coding standards.
If you need some help and can spent some cash, feel free to contact me at CodeMentor.io too.
In short: If you want to contribute to that project, please follow these things
- Please DO NOT edit README.md, CHANGELOG.md and .verb.md files. See "Building docs" section.
- Ensure anything is okey by installing the dependencies and run the tests. See "Running tests" section.
- Always use
npm run committo commit changes instead ofgit commit, because it is interactive and user-friendly. It uses commitizen behind the scenes, which follows Conventional Changelog idealogy. - Do NOT bump the version in package.json. For that we use
npm run release, which is standard-version and follows Conventional Changelog idealogy.
Thanks a lot! :)
Documentation and that readme is generated using verb-generate-readme, which is a verb generator, so you need to install both of them and then run verb command like that
$ npm install verbose/verb#dev verb-generate-readme --global && verb
Please don't edit the README directly. Any changes to the readme must be made in .verb.md.
Clone repository and run the following in that cloned directory
$ npm install && npm test
Charlike Mike Reagent
Copyright © 2016-2017, Charlike Mike Reagent. MIT
This file was generated by verb-generate-readme, v0.4.2, on March 01, 2017.
Project scaffolded using charlike cli.