File size: 10,114 Bytes
3dee94a
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
# devlop

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Some tools to make developing easier while not including code in production.

## Contents

*   [What is this?](#what-is-this)
*   [When should I use this?](#when-should-i-use-this)
*   [Install](#install)
*   [Use](#use)
*   [API](#api)
    *   [`deprecate(fn, message[, code])`](#deprecatefn-message-code)
    *   [`equal(actual, expected[, message])`](#equalactual-expected-message)
    *   [`ok(value[, message])`](#okvalue-message)
    *   [`unreachable(message?)`](#unreachablemessage)
*   [Types](#types)
*   [Compatibility](#compatibility)
*   [Security](#security)
*   [Related](#related)
*   [Contribute](#contribute)
*   [License](#license)

## What is this?

This package lets you do things in development that are free in production.
It contains useful `assert` functions and a `deprecate` function that are
useful when developing JavaScript packages while being small in production.

If you know Rust, you might know how nice having a
[`debug_assert!`][rust-debug-assert] is.
This is that, and a bit more.
For more on why they’re nice, see
[“Rust’s Two Kinds of ‘Assert’ Make for Better Code”][rust-two-kinds]

## When should I use this?

Many JavaScript programs do not use assertions at all (perhaps because they’re
typed and so assume type safety) or include lots of code to throw errors when
users do weird things (weighing down production code).
This package hopes to improve the sitation by making assertions free and
deprecations cheap.

## Install

This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:

```sh
npm install devlop
```

In Deno with [`esm.sh`][esmsh]:

```js
import {deprecate, equal, ok, unreachable} from 'https://esm.sh/devlop@1'
// For development code:
// import {deprecate, equal, ok} from 'https://esm.sh/devlop@1?conditions=development'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
  import {deprecate, equal, ok, unreachable} from 'https://esm.sh/devlop@1?bundle'
  // For development code:
  // import {deprecate, equal, ok} from 'https://esm.sh/devlop@1?bundle&conditions=development'
</script>
```

## Use

Say we have a small ponyfill for the ES5 `String#includes` function.
It’s deprecated, because folks can use `String#includes` nowadays.
It’s nicely typed so users should be able to figure out what to pass but we
include assertions to show nicer errors when they get it wrong.

`example/string-includes.js`:

```js
import {deprecate, ok} from 'devlop'

export const stringIncludes = deprecate(
  includes,
  'Since ES5, please use `String#includes` itself.'
)

/**
 * @deprecated
 *   Since ES5, please use `String#includes` itself.
 * @param {string} value
 *   Value to search in.
 * @param {string} search
 *   Value to search for.
 * @param {number | undefined} [position=0]
 *   Position to search from (default: `0`).
 * @returns {boolean}
 *   Whether the searched for value exists in the searched value after position.
 */
function includes(value, search, position) {
  ok(typeof value === 'string', 'expected string for `value`')
  ok(typeof search === 'string', 'expected string for `search`')
  ok(position === undefined || typeof position === 'number', 'expected number')
  ok(
    position === undefined ||
      (typeof position === 'number' &&
        !(/* #__PURE__ */ Number.isNaN(position))),
    'expected number'
  )
  // eslint-disable-next-line unicorn/prefer-includes
  return value.indexOf(search, position || 0) !== -1
}
```

`example/index.js`:

```js
import {stringIncludes} from './example-includes.js'

console.log(stringIncludes('blue whale', 'dolphin')) //=> false
console.log(stringIncludes('blue whale', 'whale')) //=> true
```

Say we’d bundle that in development with [`esbuild`][esbuild] and check the
gzip size ([`gzip-size-cli`][gzip-size-cli]), we’d get 1.02 kB of code:

```sh
$ esbuild example/index.js --bundle --conditions=development --format=esm --minify --target=es2022 | gzip-size
1.02 kB
```

But because `devlop` is light in production we’d get:

```sh
$ esbuild example/index.js --bundle --format=esm --minify --target=es2022 | gzip-size
169 B
```

The bundle looks as follows:

```js
function 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"));
```

It depends a bit on which bundler and minifier you use how small the code is:
esbuild keeps the unused message parameter to the `deprecate` function around
and does not know `Number.isNaN` can be dropped without a `/* #__PURE__ */`
annotation.

[`rollup`][rollup] with [`@rollup/plugin-node-resolve`][node-resolve]
and [`@rollup/plugin-terser`][terser] performs even better:

```sh
$ rollup example/index.js -p node-resolve -p terser | gzip-size
118 B
```

The bundle looks as follows:

```js
const l=function(l,e,o){return-1!==l.indexOf(e,o||0)};console.log(l("blue whale","dolphin")),console.log(l("blue whale","whale"));
```

Rollup doesn’t need the `/* #__PURE__ */` comment either!

## API

This package exports the identifiers [`deprecate`][api-deprecate],
[`equal`][api-equal], [`ok`][api-ok], and [`unreachable`][api-unreachable].
There is no default export.

The export map supports the [`development` condition][node-condition].
Run `node --conditions development module.js` to get dev code.
Without this condition, no-ops are loaded.

### `deprecate(fn, message[, code])`

Wrap a function or class to show a deprecation message when first called.

> 👉 **Important**: only shows a message when the `development` condition is
> used, does nothing in production.

When the resulting wrapped `fn` is called, emits a warning once to
`console.error` (`stderr`).
If a code is given, one warning message will be emitted in total per code.

###### Parameters

*   `fn` (`Function`)
    — function or class
*   `message` (`string`)
    — message explaining deprecation
*   `code` (`string`, optional)
    — deprecation identifier (optional); deprecation messages will be generated
    only once per code

###### Returns

Wrapped `fn`.

### `equal(actual, expected[, message])`

Assert deep strict equivalence.

> 👉 **Important**: only asserts when the `development` condition is used, does
> nothing in production.

###### Parameters

*   `actual` (`unknown`)
    — value
*   `expected` (`unknown`)
    — baseline
*   `message` (`Error` or `string`, default: `'Expected values to be deeply
    equal'`)
    — message for assertion error

###### Returns

Nothing (`undefined`).

###### Throws

Throws (`AssertionError`) when `actual` is not deep strict equal to `expected`.

### `ok(value[, message])`

Assert if `value` is truthy.

> 👉 **Important**: only asserts when the `development` condition is used, does
> nothing in production.

###### Parameters

*   `actual` (`unknown`)
    — value to assert
*   `message` (`Error` or `string`, default: `'Expected value to be truthy'`)
    — message for assertion error

###### Returns

Nothing (`undefined`).

###### Throws

Throws (`AssertionError`) when `value` is falsey.

### `unreachable(message?)`

Assert that a code path never happens.

> 👉 **Important**: only asserts when the `development` condition is used,
> does nothing in production.

###### Parameters

*   `message` (`Error` or `string`, default: `'Unreachable'`)
    — message for assertion error

###### Returns

Never (`never`).

###### Throws

Throws (`AssertionError`), always.

## Types

This package is fully typed with [TypeScript][].
It exports no additional types.

## Compatibility

This project is compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `devlop@^1`,
compatible with Node.js 16.

## Security

This package is safe.

## Related

*   [`babel-plugin-unassert`](https://github.com/unassert-js/babel-plugin-unassert)
    — encourage reliable programming with assertions while compiling them away
    in production (can remove arbitrary `assert` modules, works regardless of
    conditions, so has to be configured by the end user)

## Contribute

Yes please!
See [How to Contribute to Open Source][contribute].

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definition -->

[build-badge]: https://github.com/wooorm/devlop/workflows/main/badge.svg

[build]: https://github.com/wooorm/devlop/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/devlop.svg

[coverage]: https://codecov.io/github/wooorm/devlop

[downloads-badge]: https://img.shields.io/npm/dm/devlop.svg

[downloads]: https://www.npmjs.com/package/devlop

[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=devlop

[size]: https://bundlejs.com/?q=devlop

[npm]: https://docs.npmjs.com/cli/install

[esmsh]: https://esm.sh

[license]: license

[author]: https://wooorm.com

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[typescript]: https://www.typescriptlang.org

[contribute]: https://opensource.guide/how-to-contribute/

[node-condition]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions

[rust-debug-assert]: https://doc.rust-lang.org/std/macro.debug_assert.html

[rust-two-kinds]: https://tratt.net/laurie/blog/2023/rusts_two_kinds_of_assert_make_for_better_code.html

[esbuild]: https://esbuild.github.io

[gzip-size-cli]: https://github.com/sindresorhus/gzip-size-cli/tree/main

[rollup]: https://rollupjs.org

[node-resolve]: https://github.com/rollup/plugins/tree/master/packages/node-resolve

[terser]: https://github.com/rollup/plugins/tree/master/packages/terser#readme

[api-deprecate]: #deprecatefn-message-code

[api-equal]: #equalactual-expected-message

[api-ok]: #okvalue-message

[api-unreachable]: #unreachablemessage