Brunobkr/llama.cpp_AlgMor24_github

1# devlop2 3[![Build][build-badge]][build]4[![Coverage][coverage-badge]][coverage]5[![Downloads][downloads-badge]][downloads]6[![Size][size-badge]][size]7 8Some tools to make developing easier while not including code in production.9 10## Contents11 12*   [What is this?](#what-is-this)13*   [When should I use this?](#when-should-i-use-this)14*   [Install](#install)15*   [Use](#use)16*   [API](#api)17    *   [`deprecate(fn, message[, code])`](#deprecatefn-message-code)18    *   [`equal(actual, expected[, message])`](#equalactual-expected-message)19    *   [`ok(value[, message])`](#okvalue-message)20    *   [`unreachable(message?)`](#unreachablemessage)21*   [Types](#types)22*   [Compatibility](#compatibility)23*   [Security](#security)24*   [Related](#related)25*   [Contribute](#contribute)26*   [License](#license)27 28## What is this?29 30This package lets you do things in development that are free in production.31It contains useful `assert` functions and a `deprecate` function that are32useful when developing JavaScript packages while being small in production.33 34If you know Rust, you might know how nice having a35[`debug_assert!`][rust-debug-assert] is.36This is that, and a bit more.37For more on why they’re nice, see38[“Rust’s Two Kinds of ‘Assert’ Make for Better Code”][rust-two-kinds]39 40## When should I use this?41 42Many JavaScript programs do not use assertions at all (perhaps because they’re43typed and so assume type safety) or include lots of code to throw errors when44users do weird things (weighing down production code).45This package hopes to improve the sitation by making assertions free and46deprecations cheap.47 48## Install49 50This package is [ESM only][esm].51In Node.js (version 16+), install with [npm][]:52 53```sh54npm install devlop55```56 57In Deno with [`esm.sh`][esmsh]:58 59```js60import {deprecate, equal, ok, unreachable} from 'https://esm.sh/devlop@1'61// For development code:62// import {deprecate, equal, ok} from 'https://esm.sh/devlop@1?conditions=development'63```64 65In browsers with [`esm.sh`][esmsh]:66 67```html68<script type="module">69  import {deprecate, equal, ok, unreachable} from 'https://esm.sh/devlop@1?bundle'70  // For development code:71  // import {deprecate, equal, ok} from 'https://esm.sh/devlop@1?bundle&conditions=development'72</script>73```74 75## Use76 77Say we have a small ponyfill for the ES5 `String#includes` function.78It’s deprecated, because folks can use `String#includes` nowadays.79It’s nicely typed so users should be able to figure out what to pass but we80include assertions to show nicer errors when they get it wrong.81 82`example/string-includes.js`:83 84```js85import {deprecate, ok} from 'devlop'86 87export const stringIncludes = deprecate(88  includes,89  'Since ES5, please use `String#includes` itself.'90)91 92/**93 * @deprecated94 *   Since ES5, please use `String#includes` itself.95 * @param {string} value96 *   Value to search in.97 * @param {string} search98 *   Value to search for.99 * @param {number | undefined} [position=0]100 *   Position to search from (default: `0`).101 * @returns {boolean}102 *   Whether the searched for value exists in the searched value after position.103 */104function includes(value, search, position) {105  ok(typeof value === 'string', 'expected string for `value`')106  ok(typeof search === 'string', 'expected string for `search`')107  ok(position === undefined || typeof position === 'number', 'expected number')108  ok(109    position === undefined ||110      (typeof position === 'number' &&111        !(/* #__PURE__ */ Number.isNaN(position))),112    'expected number'113  )114  // eslint-disable-next-line unicorn/prefer-includes115  return value.indexOf(search, position || 0) !== -1116}117```118 119`example/index.js`:120 121```js122import {stringIncludes} from './example-includes.js'123 124console.log(stringIncludes('blue whale', 'dolphin')) //=> false125console.log(stringIncludes('blue whale', 'whale')) //=> true126```127 128Say we’d bundle that in development with [`esbuild`][esbuild] and check the129gzip size ([`gzip-size-cli`][gzip-size-cli]), we’d get 1.02 kB of code:130 131```sh132$ esbuild example/index.js --bundle --conditions=development --format=esm --minify --target=es2022 | gzip-size1331.02 kB134```135 136But because `devlop` is light in production we’d get:137 138```sh139$ esbuild example/index.js --bundle --format=esm --minify --target=es2022 | gzip-size140169 B141```142 143The bundle looks as follows:144 145```js146function 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"));147```148 149It depends a bit on which bundler and minifier you use how small the code is:150esbuild keeps the unused message parameter to the `deprecate` function around151and does not know `Number.isNaN` can be dropped without a `/* #__PURE__ */`152annotation.153 154[`rollup`][rollup] with [`@rollup/plugin-node-resolve`][node-resolve]155and [`@rollup/plugin-terser`][terser] performs even better:156 157```sh158$ rollup example/index.js -p node-resolve -p terser | gzip-size159118 B160```161 162The bundle looks as follows:163 164```js165const l=function(l,e,o){return-1!==l.indexOf(e,o||0)};console.log(l("blue whale","dolphin")),console.log(l("blue whale","whale"));166```167 168Rollup doesn’t need the `/* #__PURE__ */` comment either!169 170## API171 172This package exports the identifiers [`deprecate`][api-deprecate],173[`equal`][api-equal], [`ok`][api-ok], and [`unreachable`][api-unreachable].174There is no default export.175 176The export map supports the [`development` condition][node-condition].177Run `node --conditions development module.js` to get dev code.178Without this condition, no-ops are loaded.179 180### `deprecate(fn, message[, code])`181 182Wrap a function or class to show a deprecation message when first called.183 184> 👉 **Important**: only shows a message when the `development` condition is185> used, does nothing in production.186 187When the resulting wrapped `fn` is called, emits a warning once to188`console.error` (`stderr`).189If a code is given, one warning message will be emitted in total per code.190 191###### Parameters192 193*   `fn` (`Function`)194    — function or class195*   `message` (`string`)196    — message explaining deprecation197*   `code` (`string`, optional)198    — deprecation identifier (optional); deprecation messages will be generated199    only once per code200 201###### Returns202 203Wrapped `fn`.204 205### `equal(actual, expected[, message])`206 207Assert deep strict equivalence.208 209> 👉 **Important**: only asserts when the `development` condition is used, does210> nothing in production.211 212###### Parameters213 214*   `actual` (`unknown`)215    — value216*   `expected` (`unknown`)217    — baseline218*   `message` (`Error` or `string`, default: `'Expected values to be deeply219    equal'`)220    — message for assertion error221 222###### Returns223 224Nothing (`undefined`).225 226###### Throws227 228Throws (`AssertionError`) when `actual` is not deep strict equal to `expected`.229 230### `ok(value[, message])`231 232Assert if `value` is truthy.233 234> 👉 **Important**: only asserts when the `development` condition is used, does235> nothing in production.236 237###### Parameters238 239*   `actual` (`unknown`)240    — value to assert241*   `message` (`Error` or `string`, default: `'Expected value to be truthy'`)242    — message for assertion error243 244###### Returns245 246Nothing (`undefined`).247 248###### Throws249 250Throws (`AssertionError`) when `value` is falsey.251 252### `unreachable(message?)`253 254Assert that a code path never happens.255 256> 👉 **Important**: only asserts when the `development` condition is used,257> does nothing in production.258 259###### Parameters260 261*   `message` (`Error` or `string`, default: `'Unreachable'`)262    — message for assertion error263 264###### Returns265 266Never (`never`).267 268###### Throws269 270Throws (`AssertionError`), always.271 272## Types273 274This package is fully typed with [TypeScript][].275It exports no additional types.276 277## Compatibility278 279This project is compatible with maintained versions of Node.js.280 281When we cut a new major release, we drop support for unmaintained versions of282Node.283This means we try to keep the current release line, `devlop@^1`,284compatible with Node.js 16.285 286## Security287 288This package is safe.289 290## Related291 292*   [`babel-plugin-unassert`](https://github.com/unassert-js/babel-plugin-unassert)293    — encourage reliable programming with assertions while compiling them away294    in production (can remove arbitrary `assert` modules, works regardless of295    conditions, so has to be configured by the end user)296 297## Contribute298 299Yes please!300See [How to Contribute to Open Source][contribute].301 302## License303 304[MIT][license] © [Titus Wormer][author]305 306<!-- Definition -->307 308[build-badge]: https://github.com/wooorm/devlop/workflows/main/badge.svg309 310[build]: https://github.com/wooorm/devlop/actions311 312[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/devlop.svg313 314[coverage]: https://codecov.io/github/wooorm/devlop315 316[downloads-badge]: https://img.shields.io/npm/dm/devlop.svg317 318[downloads]: https://www.npmjs.com/package/devlop319 320[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=devlop321 322[size]: https://bundlejs.com/?q=devlop323 324[npm]: https://docs.npmjs.com/cli/install325 326[esmsh]: https://esm.sh327 328[license]: license329 330[author]: https://wooorm.com331 332[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c333 334[typescript]: https://www.typescriptlang.org335 336[contribute]: https://opensource.guide/how-to-contribute/337 338[node-condition]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions339 340[rust-debug-assert]: https://doc.rust-lang.org/std/macro.debug_assert.html341 342[rust-two-kinds]: https://tratt.net/laurie/blog/2023/rusts_two_kinds_of_assert_make_for_better_code.html343 344[esbuild]: https://esbuild.github.io345 346[gzip-size-cli]: https://github.com/sindresorhus/gzip-size-cli/tree/main347 348[rollup]: https://rollupjs.org349 350[node-resolve]: https://github.com/rollup/plugins/tree/master/packages/node-resolve351 352[terser]: https://github.com/rollup/plugins/tree/master/packages/terser#readme353 354[api-deprecate]: #deprecatefn-message-code355 356[api-equal]: #equalactual-expected-message357 358[api-ok]: #okvalue-message359 360[api-unreachable]: #unreachablemessage361