{"_id":"devlop","_rev":"3274720","name":"devlop","description":"Do things in development and nothing otherwise","dist-tags":{"latest":"1.1.0"},"maintainers":[{"name":"wooorm","email":"tituswormer@gmail.com"}],"time":{"modified":"2024-03-21T10:20:57.000Z","created":"2023-06-16T16:08:56.375Z","1.1.0":"2023-06-29T15:17:11.346Z","1.0.0":"2023-06-16T16:08:56.375Z"},"users":{},"author":{"name":"Titus Wormer","email":"tituswormer@gmail.com","url":"https://wooorm.com"},"repository":{"type":"git","url":"git+https://github.com/wooorm/devlop.git"},"versions":{"1.1.0":{"name":"devlop","version":"1.1.0","description":"Do things in development and nothing otherwise","license":"MIT","keywords":["assert","deprecate","develop","development"],"repository":{"type":"git","url":"git+https://github.com/wooorm/devlop.git"},"bugs":{"url":"https://github.com/wooorm/devlop/issues"},"funding":{"type":"github","url":"https://github.com/sponsors/wooorm"},"author":{"name":"Titus Wormer","email":"tituswormer@gmail.com","url":"https://wooorm.com"},"contributors":[{"name":"Titus Wormer","email":"tituswormer@gmail.com","url":"https://wooorm.com"}],"sideEffects":false,"type":"module","exports":{"types":"./lib/development.d.ts","development":"./lib/development.js","default":"./lib/default.js"},"dependencies":{"dequal":"^2.0.0"},"devDependencies":{"@rollup/plugin-node-resolve":"^15.1.0","@rollup/plugin-terser":"^0.4.3","@types/node":"^20.0.0","c8":"^8.0.0","esbuild":"^0.18.0","prettier":"^2.0.0","remark-cli":"^11.0.0","remark-preset-wooorm":"^9.0.0","type-coverage":"^2.0.0","typescript":"^5.0.0","xo":"^0.54.0"},"scripts":{"prepack":"npm run build && npm run format","build":"tsc --build --clean && tsc --build && type-coverage","format":"remark . -qfo && prettier . -w --loglevel warn && xo --fix","test-api-development":"node --conditions development test-development.js","test-api-default":"node test-default.js","test-api":"npm run test-api-development && npm run test-api-default","test-coverage":"c8 --100 --reporter lcov npm run test-api","test":"npm run build && npm run format && npm run test-coverage"},"prettier":{"bracketSpacing":false,"semi":false,"singleQuote":true,"tabWidth":2,"trailingComma":"none","useTabs":false},"remarkConfig":{"plugins":["remark-preset-wooorm"]},"typeCoverage":{"atLeast":100,"detail":true,"ignoreCatch":true,"strict":true},"xo":{"prettier":true},"gitHead":"ef6cc1df94505f8daa2eab4c52efbc3ee310e002","homepage":"https://github.com/wooorm/devlop#readme","_id":"devlop@1.1.0","_nodeVersion":"20.0.0","_npmVersion":"9.6.4","dist":{"shasum":"4db7c2ca4dc6e0e834c30be70c94bbc976dc7018","size":6714,"noattachment":false,"key":"/devlop/-/devlop-1.1.0.tgz","tarball":"http://registry.cnpm.dingdandao.com/devlop/download/devlop-1.1.0.tgz"},"_npmUser":{"name":"wooorm","email":"tituswormer@gmail.com"},"directories":{},"maintainers":[{"name":"wooorm","email":"tituswormer@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/devlop_1.1.0_1688051831175_0.15591005201532027"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2023-06-29T15:17:11.346Z","publish_time":1688051831346,"_source_registry_name":"default","_cnpm_publish_time":1688051831346},"1.0.0":{"name":"devlop","version":"1.0.0","description":"Do things in development and nothing otherwise","license":"MIT","keywords":["assert","deprecate","develop","development"],"repository":{"type":"git","url":"git+https://github.com/wooorm/devlop.git"},"bugs":{"url":"https://github.com/wooorm/devlop/issues"},"funding":{"type":"github","url":"https://github.com/sponsors/wooorm"},"author":{"name":"Titus Wormer","email":"tituswormer@gmail.com","url":"https://wooorm.com"},"contributors":[{"name":"Titus Wormer","email":"tituswormer@gmail.com","url":"https://wooorm.com"}],"sideEffects":false,"type":"module","exports":{"types":"./lib/development.d.ts","development":"./lib/development.js","default":"./lib/default.js"},"dependencies":{"dequal":"^2.0.0"},"devDependencies":{"@rollup/plugin-node-resolve":"^15.1.0","@rollup/plugin-terser":"^0.4.3","@types/node":"^20.0.0","c8":"^8.0.0","esbuild":"^0.18.0","prettier":"^2.0.0","remark-cli":"^11.0.0","remark-preset-wooorm":"^9.0.0","type-coverage":"^2.0.0","typescript":"^5.0.0","xo":"^0.54.0"},"scripts":{"prepack":"npm run build && npm run format","build":"tsc --build --clean && tsc --build && type-coverage","format":"remark . -qfo && prettier . -w --loglevel warn && xo --fix","test-api-development":"node --conditions development test-development.js","test-api-default":"node test-default.js","test-api":"npm run test-api-development && npm run test-api-default","test-coverage":"c8 --100 --reporter lcov npm run test-api","test":"npm run build && npm run format && npm run test-coverage"},"prettier":{"bracketSpacing":false,"semi":false,"singleQuote":true,"tabWidth":2,"trailingComma":"none","useTabs":false},"remarkConfig":{"plugins":["remark-preset-wooorm"]},"typeCoverage":{"atLeast":100,"detail":true,"ignoreCatch":true,"strict":true},"xo":{"prettier":true},"gitHead":"bb08d1604939ac71291f6bdfc2d9a18e8dbd6b8e","homepage":"https://github.com/wooorm/devlop#readme","_id":"devlop@1.0.0","_nodeVersion":"20.0.0","_npmVersion":"9.6.4","dist":{"shasum":"f416dd252974279afc349a71ec3392b5c4443e6f","size":6546,"noattachment":false,"key":"/devlop/-/devlop-1.0.0.tgz","tarball":"http://registry.cnpm.dingdandao.com/devlop/download/devlop-1.0.0.tgz"},"_npmUser":{"name":"wooorm","email":"tituswormer@gmail.com"},"directories":{},"maintainers":[{"name":"wooorm","email":"tituswormer@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/devlop_1.0.0_1686931736143_0.2616762669272956"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2023-06-16T16:08:56.375Z","publish_time":1686931736375,"_source_registry_name":"default","_cnpm_publish_time":1686931736375}},"readme":"# devlop\n\n[![Build][build-badge]][build]\n[![Coverage][coverage-badge]][coverage]\n[![Downloads][downloads-badge]][downloads]\n[![Size][size-badge]][size]\n\nSome tools to make developing easier while not including code in production.\n\n## Contents\n\n*   [What is this?](#what-is-this)\n*   [When should I use this?](#when-should-i-use-this)\n*   [Install](#install)\n*   [Use](#use)\n*   [API](#api)\n    *   [`deprecate(fn, message[, code])`](#deprecatefn-message-code)\n    *   [`equal(actual, expected[, message])`](#equalactual-expected-message)\n    *   [`ok(value[, message])`](#okvalue-message)\n    *   [`unreachable(message?)`](#unreachablemessage)\n*   [Types](#types)\n*   [Compatibility](#compatibility)\n*   [Security](#security)\n*   [Related](#related)\n*   [Contribute](#contribute)\n*   [License](#license)\n\n## What is this?\n\nThis package lets you do things in development that are free in production.\nIt contains useful `assert` functions and a `deprecate` function that are\nuseful when developing JavaScript packages while being small in production.\n\nIf you know Rust, you might know how nice having a\n[`debug_assert!`][rust-debug-assert] is.\nThis is that, and a bit more.\nFor more on why they’re nice, see\n[“Rust’s Two Kinds of ‘Assert’ Make for Better Code”][rust-two-kinds]\n\n## When should I use this?\n\nMany JavaScript programs do not use assertions at all (perhaps because they’re\ntyped and so assume type safety) or include lots of code to throw errors when\nusers do weird things (weighing down production code).\nThis package hopes to improve the sitation by making assertions free and\ndeprecations cheap.\n\n## Install\n\nThis package is [ESM only][esm].\nIn Node.js (version 16+), install with [npm][]:\n\n```sh\nnpm install devlop\n```\n\nIn Deno with [`esm.sh`][esmsh]:\n\n```js\nimport {deprecate, equal, ok, unreachable} from 'https://esm.sh/devlop@1'\n// For development code:\n// import {deprecate, equal, ok} from 'https://esm.sh/devlop@1?conditions=development'\n```\n\nIn browsers with [`esm.sh`][esmsh]:\n\n```html\n<script type=\"module\">\n  import {deprecate, equal, ok, unreachable} from 'https://esm.sh/devlop@1?bundle'\n  // For development code:\n  // import {deprecate, equal, ok} from 'https://esm.sh/devlop@1?bundle&conditions=development'\n</script>\n```\n\n## Use\n\nSay we have a small ponyfill for the ES5 `String#includes` function.\nIt’s deprecated, because folks can use `String#includes` nowadays.\nIt’s nicely typed so users should be able to figure out what to pass but we\ninclude assertions to show nicer errors when they get it wrong.\n\n`example/string-includes.js`:\n\n```js\nimport {deprecate, ok} from 'devlop'\n\nexport const stringIncludes = deprecate(\n  includes,\n  'Since ES5, please use `String#includes` itself.'\n)\n\n/**\n * @deprecated\n *   Since ES5, please use `String#includes` itself.\n * @param {string} value\n *   Value to search in.\n * @param {string} search\n *   Value to search for.\n * @param {number | undefined} [position=0]\n *   Position to search from (default: `0`).\n * @returns {boolean}\n *   Whether the searched for value exists in the searched value after position.\n */\nfunction includes(value, search, position) {\n  ok(typeof value === 'string', 'expected string for `value`')\n  ok(typeof search === 'string', 'expected string for `search`')\n  ok(position === undefined || typeof position === 'number', 'expected number')\n  ok(\n    position === undefined ||\n      (typeof position === 'number' &&\n        !(/* #__PURE__ */ Number.isNaN(position))),\n    'expected number'\n  )\n  // eslint-disable-next-line unicorn/prefer-includes\n  return value.indexOf(search, position || 0) !== -1\n}\n```\n\n`example/index.js`:\n\n```js\nimport {stringIncludes} from './example-includes.js'\n\nconsole.log(stringIncludes('blue whale', 'dolphin')) //=> false\nconsole.log(stringIncludes('blue whale', 'whale')) //=> true\n```\n\nSay we’d bundle that in development with [`esbuild`][esbuild] and check the\ngzip size ([`gzip-size-cli`][gzip-size-cli]), we’d get 1.02 kB of code:\n\n```sh\n$ esbuild example/index.js --bundle --conditions=development --format=esm --minify --target=es2022 | gzip-size\n1.02 kB\n```\n\nBut because `devlop` is light in production we’d get:\n\n```sh\n$ esbuild example/index.js --bundle --format=esm --minify --target=es2022 | gzip-size\n169 B\n```\n\nThe bundle looks as follows:\n\n```js\nfunction u(n){return n}var r=u(c,\"Since ES5, please use `String#includes` itself.\");function c(n,t,e){return n.indexOf(t,e||0)!==-1}console.log(r(\"blue whale\",\"dolphin\"));console.log(r(\"blue whale\",\"whale\"));\n```\n\nIt depends a bit on which bundler and minifier you use how small the code is:\nesbuild keeps the unused message parameter to the `deprecate` function around\nand does not know `Number.isNaN` can be dropped without a `/* #__PURE__ */`\nannotation.\n\n[`rollup`][rollup] with [`@rollup/plugin-node-resolve`][node-resolve]\nand [`@rollup/plugin-terser`][terser] performs even better:\n\n```sh\n$ rollup example/index.js -p node-resolve -p terser | gzip-size\n118 B\n```\n\nThe bundle looks as follows:\n\n```js\nconst l=function(l,e,o){return-1!==l.indexOf(e,o||0)};console.log(l(\"blue whale\",\"dolphin\")),console.log(l(\"blue whale\",\"whale\"));\n```\n\nRollup doesn’t need the `/* #__PURE__ */` comment either!\n\n## API\n\nThis package exports the identifiers [`deprecate`][api-deprecate],\n[`equal`][api-equal], [`ok`][api-ok], and [`unreachable`][api-unreachable].\nThere is no default export.\n\nThe export map supports the [`development` condition][node-condition].\nRun `node --conditions development module.js` to get dev code.\nWithout this condition, no-ops are loaded.\n\n### `deprecate(fn, message[, code])`\n\nWrap a function or class to show a deprecation message when first called.\n\n> ???? **Important**: only shows a message when the `development` condition is\n> used, does nothing in production.\n\nWhen the resulting wrapped `fn` is called, emits a warning once to\n`console.error` (`stderr`).\nIf a code is given, one warning message will be emitted in total per code.\n\n###### Parameters\n\n*   `fn` (`Function`)\n    — function or class\n*   `message` (`string`)\n    — message explaining deprecation\n*   `code` (`string`, optional)\n    — deprecation identifier (optional); deprecation messages will be generated\n    only once per code\n\n###### Returns\n\nWrapped `fn`.\n\n### `equal(actual, expected[, message])`\n\nAssert deep strict equivalence.\n\n> ???? **Important**: only asserts when the `development` condition is used, does\n> nothing in production.\n\n###### Parameters\n\n*   `actual` (`unknown`)\n    — value\n*   `expected` (`unknown`)\n    — baseline\n*   `message` (`Error` or `string`, default: `'Expected values to be deeply\n    equal'`)\n    — message for assertion error\n\n###### Returns\n\nNothing (`undefined`).\n\n###### Throws\n\nThrows (`AssertionError`) when `actual` is not deep strict equal to `expected`.\n\n### `ok(value[, message])`\n\nAssert if `value` is truthy.\n\n> ???? **Important**: only asserts when the `development` condition is used, does\n> nothing in production.\n\n###### Parameters\n\n*   `actual` (`unknown`)\n    — value to assert\n*   `message` (`Error` or `string`, default: `'Expected value to be truthy'`)\n    — message for assertion error\n\n###### Returns\n\nNothing (`undefined`).\n\n###### Throws\n\nThrows (`AssertionError`) when `value` is falsey.\n\n### `unreachable(message?)`\n\nAssert that a code path never happens.\n\n> ???? **Important**: only asserts when the `development` condition is used,\n> does nothing in production.\n\n###### Parameters\n\n*   `message` (`Error` or `string`, default: `'Unreachable'`)\n    — message for assertion error\n\n###### Returns\n\nNever (`never`).\n\n###### Throws\n\nThrows (`AssertionError`), always.\n\n## Types\n\nThis package is fully typed with [TypeScript][].\nIt exports no additional types.\n\n## Compatibility\n\nThis project is compatible with maintained versions of Node.js.\n\nWhen we cut a new major release, we drop support for unmaintained versions of\nNode.\nThis means we try to keep the current release line, `devlop@^1`,\ncompatible with Node.js 16.\n\n## Security\n\nThis package is safe.\n\n## Related\n\n*   [`babel-plugin-unassert`](https://github.com/unassert-js/babel-plugin-unassert)\n    — encourage reliable programming with assertions while compiling them away\n    in production (can remove arbitrary `assert` modules, works regardless of\n    conditions, so has to be configured by the end user)\n\n## Contribute\n\nYes please!\nSee [How to Contribute to Open Source][contribute].\n\n## License\n\n[MIT][license] © [Titus Wormer][author]\n\n<!-- Definition -->\n\n[build-badge]: https://github.com/wooorm/devlop/workflows/main/badge.svg\n\n[build]: https://github.com/wooorm/devlop/actions\n\n[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/devlop.svg\n\n[coverage]: https://codecov.io/github/wooorm/devlop\n\n[downloads-badge]: https://img.shields.io/npm/dm/devlop.svg\n\n[downloads]: https://www.npmjs.com/package/devlop\n\n[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=devlop\n\n[size]: https://bundlejs.com/?q=devlop\n\n[npm]: https://docs.npmjs.com/cli/install\n\n[esmsh]: https://esm.sh\n\n[license]: license\n\n[author]: https://wooorm.com\n\n[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c\n\n[typescript]: https://www.typescriptlang.org\n\n[contribute]: https://opensource.guide/how-to-contribute/\n\n[node-condition]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions\n\n[rust-debug-assert]: https://doc.rust-lang.org/std/macro.debug_assert.html\n\n[rust-two-kinds]: https://tratt.net/laurie/blog/2023/rusts_two_kinds_of_assert_make_for_better_code.html\n\n[esbuild]: https://esbuild.github.io\n\n[gzip-size-cli]: https://github.com/sindresorhus/gzip-size-cli/tree/main\n\n[rollup]: https://rollupjs.org\n\n[node-resolve]: https://github.com/rollup/plugins/tree/master/packages/node-resolve\n\n[terser]: https://github.com/rollup/plugins/tree/master/packages/terser#readme\n\n[api-deprecate]: #deprecatefn-message-code\n\n[api-equal]: #equalactual-expected-message\n\n[api-ok]: #okvalue-message\n\n[api-unreachable]: #unreachablemessage\n","_attachments":{},"homepage":"https://github.com/wooorm/devlop#readme","bugs":{"url":"https://github.com/wooorm/devlop/issues"},"license":"MIT"}