{"id":21615836,"url":"https://github.com/valango/assert-fine","last_synced_at":"2025-03-18T17:19:13.301Z","repository":{"id":57185004,"uuid":"291022760","full_name":"valango/assert-fine","owner":"valango","description":"A tiny utility, that helps to find cause of seemingly random failures in your code.","archived":false,"fork":false,"pushed_at":"2022-02-13T09:17:58.000Z","size":1014,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"development","last_synced_at":"2024-04-25T15:21:17.505Z","etag":null,"topics":["assertion","back-end","callback","failures","front-end","sporadic"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/valango.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-08-28T10:51:52.000Z","updated_at":"2021-10-08T07:58:01.000Z","dependencies_parsed_at":"2022-09-14T10:11:11.291Z","dependency_job_id":null,"html_url":"https://github.com/valango/assert-fine","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valango%2Fassert-fine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valango%2Fassert-fine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valango%2Fassert-fine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valango%2Fassert-fine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/valango","download_url":"https://codeload.github.com/valango/assert-fine/tar.gz/refs/heads/development","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244267475,"owners_count":20425835,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assertion","back-end","callback","failures","front-end","sporadic"],"created_at":"2024-11-24T22:12:57.508Z","updated_at":"2025-03-18T17:19:13.282Z","avatar_url":"https://github.com/valango.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# assert-fine\n[![Build Status](https://travis-ci.org/valango/assert-fine.svg?branch=master)](https://travis-ci.org/valango/assert-fine)  [![Code coverage](https://codecov.io/gh/valango/assert-fine/branch/master/graph/badge.svg)](https://codecov.io/gh/valango/assert-fine)\n\nA lightweight wrapper making assertion testing much easier.\n\n## Why and How\n1. After assertion failure, we'll have stack trace, showing the execution context.\nBut sometimes we need a _**detailed view of dynamic data**_, even\n_**interactive debugging**_, _before_ _`AssertionError`_ is thrown.\u003cbr /\u003e\nThe [`beforeThrow()`](#function-beforethrowcallback) hook makes it easy.\n1. Including dynamic data to assertion messages comes at cost of additional code and\nperformance penalty.\u003cbr /\u003e\nThe overridden [`ok()`](#function-ok-value-args-), [`fail()`](#function-fail-failure-args-)\nand [`ifError()`](#function-iferror-value-args-) functions feature _**lazy formatting**_\nin a backwards-compatible manner.\n1. Front-end assertion is supported too, with minimalistic API of `(AssertionError, fail, ifError, ok)`\nby default. So you can use _**same code**_ in both back- and front-end (via a bundler).\n1. The [`use()`](#function-use-engine-) function lets you switch the _assertion engine_ programmatically, w/o re-loading\nany modules.\n\nWhen loaded, the `assert-fine` package object instance transparently wraps around\nthe environment-specific\n_**assertion engine**_ like the [Node.js assert](http://nodejs.org/api/assert.html)\n\nThe #1 functionality was actually proposed, but rejected _Node.js\nfeature request [#5312](https://github.com/nodejs/node/issues/5312)_.\n\n## Installation\n`  npm install -S assert-fine`\u003cbr /\u003eor\u003cbr /\u003e`  yarn add assert-fine`\n\n## Usage\n```js\nconst assert = require('assert-fine')\n\nassert.beforeThrow(() =\u003e {  //  This call is optional.\n  return false              //  The breakpoint place.\n})\n\n//  Somewhere in your code\nassert(value === expected, 'assert(%o)', value, someFunction, ...argsForFunction)\n\nassert.equal(value, expected, 'Bang!')  //  Not affected by `assert-fine`.\n```\nIn the example above, the someFunction will be called, and the message is formatted only\nwhen the assertion fails.\n\n## Package exports (API)\n\n### Default export\nDefault export equals the `ok()` function.\n\n### function `beforeThrow([callback: function|false])`\nSets, resets or just queries the global callback function.\n\nThe callback will be called right before the assertion error is thrown.\nIt's main purpose is to provide debugger breakpoint.\n**Returns** `function | undefined` the global callback value so far.\u003cbr/\u003e\n**Throws** `TypeError` if supplied argument is not function nor falsy.\n\n### function `fail( [failure], ...args )`\nReplaces its [Node.js counterpart](http://nodejs.org/api/assert.html#assert_assert_fail_message),\nfeaturing the lazy formatting and invoking the callback set via `beforeThrow()`.\n\nArguments:\u003cbr/\u003e\n`failure: Error | function `- if a function supplied, it is treated as Error constructor,\nand error instance is created with `message` property composed of args;\nif _`Error`_ instance is supplied, the string composed of args is appended to its `message`.\u003cbr/\u003e\n`args: any` - optional arguments. If the first one is a string, it will be supplied to `util.format`\nor to its front-end substitute. If any of the _`args`_ is a function, it will be called\nwith the rest opf arguments supplying its return value to `format()`.\n\n### function `ifError( value, ...args )`\nReplaces its [Node.js counterpart](http://nodejs.org/api/assert.html#assert_assert_iferror_value),\nfeaturing the lazy formatting and invoking the callback set via `beforeThrow()`. Arguments:\u003cbr/\u003e\n`value: any`\u003cbr/\u003e\n`args: any `- optional arguments, working exactly as those of [`fail()`](#function-fail-failure-args-).\n\n### function `ok( value, ...args )`\nReplaces its [Node.js counterpart](http://nodejs.org/api/assert.html#assert_assert_ok_message),\nfeaturing the lazy formatting and invoking the callback set via `beforeThrow()`. Arguments:\u003cbr/\u003e\n`value: any`\u003cbr/\u003e\n`args: any`- optional arguments, working exactly as those of [`fail()`](#function-fail-failure-args-).\n\n### function `use( engine )`\nWraps the _assertion engine_, putting it into use.\nThis function is called internally upon\nloading the package, with Node.js built-in _`assert`_ package or with its own substitute,\nwhen loaded via a bundler ([browserify](https://browserify.org/), [webpack](https://webpack.js.org/),\n[rollup](https://rollupjs.org) or similar.)\u003cbr/\u003e\nYou might need this function when using something like\n[assert](https://github.com/browserify/commonjs-assert) package for front-end.\n\nThis function _**does not** modify_ the supplied _`engine`_ instance in any way, and\u003cbr/\u003e\nit does not alter the exported ( _`beforeThrow, fail, ifError, ok, use`_ ) values either.\n\nAll other properties of the engine argument will be assigned to the already exported API.\n\n### property `strict?: function()`\nIs present only if the assertion engine in use has such property\n(see [Node.js docs](http://nodejs.org/api/assert.html)), it will be mirrored to the\npackage object instance. For subtle details, see the [source code](src/common.js).\n\n### Other properties\nAny properties of the assertion engine, not shadowed by the API described above,\nwill be directly assigned to package object instance.\n\n## Advanced topics\n### Changing package settings\nCalls to _`beforeThrow()`_ or _`use()`_ anywhere in your code affect the state `assert-fine` instance\nkept in [_`require.cache`_](http://nodejs.org/api/modules.html#modules_require_cache) or alike.\nIt is preferable to make these calls from the application boot module, before executing\nany other code.\n\n### Switching the assertion engine\nIf you need something special in place of the default engine, do something like this:\n```js\nimport engine from 'assert'         //  A npm package for front-end applications.\nimport assert from 'assert-fine'\n\nassert.use(engine)  //  Should be executed _before_ any possible assertion call.\n```\nTechnically, it is possible to switch engines at any moment.\n\n### The global callback function\nThis function, if set  via [`beforeThrow()`](#function-beforethrowcallback), should be kept\nas simple as possible. It's typical use is just to provide a code line for debugger breakpoint.\n\nIf the callback itself throws an error, it will be stored in assertion instance's _`extra`_\nproperty and its _`message`_ will be appended to the assertion message using '[EXTRA]:' prefix.\n\nThe callback receives two arguments:\u003cbr/\u003e\n`error: Error` - the instance that will be thrown;\u003cbr/\u003e\n`args: any[]` - the _`args`_ from the call of `fail()`, `ifError()` or `ok()`.\n\n## Acknowledgements\n[assert](https://github.com/browserify/commonjs-assert) npm package - I borrowed quite some\npieces of code from there - thanks a lot, folks!\n\n[debug](https://github.com/visionmedia/debug) npm package - inspecting its source code\nhelped me to fix the disastrous bug (issue #1) of this package - thanks again!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvalango%2Fassert-fine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvalango%2Fassert-fine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvalango%2Fassert-fine/lists"}