@thi.ng/errors 2.2.17 → 2.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/CHANGELOG.md +7 -1
  2. package/README.md +3 -2
  3. package/ensure.d.ts +110 -0
  4. package/ensure.js +115 -0
  5. package/index.d.ts +1 -0
  6. package/index.js +1 -0
  7. package/package.json +9 -6
package/CHANGELOG.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Change Log
2
2
 
3
- - **Last updated**: 2023-06-14T07:58:51Z
3
+ - **Last updated**: 2023-08-10T12:16:43Z
4
4
  - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
5
5
 
6
6
  All notable changes to this project will be documented in this file.
@@ -9,6 +9,12 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
9
9
  **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
10
10
  and/or version bumps of transitive dependencies.
11
11
 
12
+ ## [2.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/errors@2.3.0) (2023-08-04)
13
+
14
+ #### 🚀 Features
15
+
16
+ - add ensureXXX() functions ([be70868](https://github.com/thi-ng/umbrella/commit/be70868))
17
+
12
18
  ### [2.2.3](https://github.com/thi-ng/umbrella/tree/@thi.ng/errors@2.2.3) (2022-10-28)
13
19
 
14
20
  #### 🩹 Bug fixes
package/README.md CHANGED
@@ -1,6 +1,7 @@
1
1
  <!-- This file is generated - DO NOT EDIT! -->
2
+ <!-- Please see: https://github.com/thi-ng/umbrella/blob/develop/CONTRIBUTING.md#changes-to-readme-files -->
2
3
 
3
- # ![@thi.ng/errors](https://media.thi.ng/umbrella/banners-20220914/thing-errors.svg?e0537a6e)
4
+ # ![@thi.ng/errors](https://media.thi.ng/umbrella/banners-20230807/thing-errors.svg?e0537a6e)
4
5
 
5
6
  [![npm version](https://img.shields.io/npm/v/@thi.ng/errors.svg)](https://www.npmjs.com/package/@thi.ng/errors)
6
7
  ![npm downloads](https://img.shields.io/npm/dm/@thi.ng/errors.svg)
@@ -60,7 +61,7 @@ For Node.js REPL:
60
61
  const errors = await import("@thi.ng/errors");
61
62
  ```
62
63
 
63
- Package sizes (brotli'd, pre-treeshake): ESM: 497 bytes
64
+ Package sizes (brotli'd, pre-treeshake): ESM: 749 bytes
64
65
 
65
66
  ## Dependencies
66
67
 
package/ensure.d.ts ADDED
@@ -0,0 +1,110 @@
1
+ /**
2
+ * Higher-order function to define ensurance assertions. Takes a `pred`icate
3
+ * function and an `expected` (type) name, returns a new function which accepts
4
+ * 2 args (an arbitrary value `x` and optional error `msg`). When called, checks
5
+ * `x` for non-null and if so applies given `pred`icate. If result is false (or
6
+ * `x` is nullish) and iff {@link assert} is enabled, throws a
7
+ * {@link AssertionError} with given `msg` (or a constructed default msg).
8
+ * Otherwise function is a no-op.
9
+ *
10
+ * @param pred
11
+ * @param expected
12
+ */
13
+ export declare const defEnsure: <T>(pred: (x: any) => boolean, expected: string) => (x: any, msg?: string) => T;
14
+ /**
15
+ * Only enabled if {@link assert} is enabled (otherwise no-op). Checks if `x` is
16
+ * a JS array and if not throws {@link AssertionError}, optionally with given
17
+ * `msg`.
18
+ *
19
+ * @remarks
20
+ * See {@link defEnsure} for details.
21
+ *
22
+ * @param x
23
+ * @param msg
24
+ */
25
+ export declare const ensureArray: (x: any, msg?: string) => any[];
26
+ /**
27
+ * Only enabled if {@link assert} is enabled (otherwise no-op). Checks if `x` is
28
+ * a bigint and if not throws {@link AssertionError}, optionally with given
29
+ * `msg`.
30
+ *
31
+ * @remarks
32
+ * See {@link defEnsure} for details.
33
+ *
34
+ * @param x
35
+ * @param msg
36
+ */
37
+ export declare const ensureBigInt: (x: any, msg?: string) => bigint;
38
+ /**
39
+ * Only enabled if {@link assert} is enabled (otherwise no-op). Checks if `x` is
40
+ * a boolean and if not throws {@link AssertionError}, optionally with given
41
+ * `msg`.
42
+ *
43
+ * @remarks
44
+ * See {@link defEnsure} for details.
45
+ *
46
+ * @param x
47
+ * @param msg
48
+ */
49
+ export declare const ensureBoolean: (x: any, msg?: string) => boolean;
50
+ /**
51
+ * Only enabled if {@link assert} is enabled (otherwise no-op). Checks if `x` is
52
+ * a function and if not throws {@link AssertionError}, optionally with given
53
+ * `msg`.
54
+ *
55
+ * @remarks
56
+ * See {@link defEnsure} for details.
57
+ *
58
+ * @param x
59
+ * @param msg
60
+ */
61
+ export declare const ensureFunction: (x: any, msg?: string) => Function;
62
+ /**
63
+ * Only enabled if {@link assert} is enabled (otherwise no-op). Checks if `x` is
64
+ * an ES6 iterable and if not throws {@link AssertionError}, optionally with
65
+ * given `msg`.
66
+ *
67
+ * @remarks
68
+ * See {@link defEnsure} for details.
69
+ *
70
+ * @param x
71
+ * @param msg
72
+ */
73
+ export declare const ensureIterable: (x: any, msg?: string) => Iterable<any>;
74
+ /**
75
+ * Only enabled if {@link assert} is enabled (otherwise no-op). Checks if `x` is
76
+ * a number and if not throws {@link AssertionError}, optionally with given
77
+ * `msg`.
78
+ *
79
+ * @remarks
80
+ * See {@link defEnsure} for details.
81
+ *
82
+ * @param x
83
+ * @param msg
84
+ */
85
+ export declare const ensureNumber: (x: any, msg?: string) => number;
86
+ /**
87
+ * Only enabled if {@link assert} is enabled (otherwise no-op). Checks if `x` is
88
+ * a string and if not throws {@link AssertionError}, optionally with given
89
+ * `msg`.
90
+ *
91
+ * @remarks
92
+ * See {@link defEnsure} for details.
93
+ *
94
+ * @param x
95
+ * @param msg
96
+ */
97
+ export declare const ensureString: (x: any, msg?: string) => string;
98
+ /**
99
+ * Only enabled if {@link assert} is enabled (otherwise no-op). Checks if `x` is
100
+ * a symbol and if not throws {@link AssertionError}, optionally with given
101
+ * `msg`.
102
+ *
103
+ * @remarks
104
+ * See {@link defEnsure} for details.
105
+ *
106
+ * @param x
107
+ * @param msg
108
+ */
109
+ export declare const ensureSymbol: (x: any, msg?: string) => symbol;
110
+ //# sourceMappingURL=ensure.d.ts.map
package/ensure.js ADDED
@@ -0,0 +1,115 @@
1
+ import { assert } from "./assert.js";
2
+ /**
3
+ * Higher-order function to define ensurance assertions. Takes a `pred`icate
4
+ * function and an `expected` (type) name, returns a new function which accepts
5
+ * 2 args (an arbitrary value `x` and optional error `msg`). When called, checks
6
+ * `x` for non-null and if so applies given `pred`icate. If result is false (or
7
+ * `x` is nullish) and iff {@link assert} is enabled, throws a
8
+ * {@link AssertionError} with given `msg` (or a constructed default msg).
9
+ * Otherwise function is a no-op.
10
+ *
11
+ * @param pred
12
+ * @param expected
13
+ */
14
+ export const defEnsure = (pred, expected) => (x, msg) => {
15
+ x != null
16
+ ? assert(() => pred(x), msg || `expected ${expected}, got ${typeof x}`)
17
+ : assert(false, `expected ${expected}, got ${x}`);
18
+ return x;
19
+ };
20
+ /**
21
+ * Only enabled if {@link assert} is enabled (otherwise no-op). Checks if `x` is
22
+ * a JS array and if not throws {@link AssertionError}, optionally with given
23
+ * `msg`.
24
+ *
25
+ * @remarks
26
+ * See {@link defEnsure} for details.
27
+ *
28
+ * @param x
29
+ * @param msg
30
+ */
31
+ export const ensureArray = defEnsure((x) => Array.isArray(x), `array`);
32
+ /**
33
+ * Only enabled if {@link assert} is enabled (otherwise no-op). Checks if `x` is
34
+ * a bigint and if not throws {@link AssertionError}, optionally with given
35
+ * `msg`.
36
+ *
37
+ * @remarks
38
+ * See {@link defEnsure} for details.
39
+ *
40
+ * @param x
41
+ * @param msg
42
+ */
43
+ export const ensureBigInt = defEnsure((x) => typeof x === "bigint", "bigint");
44
+ /**
45
+ * Only enabled if {@link assert} is enabled (otherwise no-op). Checks if `x` is
46
+ * a boolean and if not throws {@link AssertionError}, optionally with given
47
+ * `msg`.
48
+ *
49
+ * @remarks
50
+ * See {@link defEnsure} for details.
51
+ *
52
+ * @param x
53
+ * @param msg
54
+ */
55
+ export const ensureBoolean = defEnsure((x) => typeof x === "boolean", "boolean");
56
+ /**
57
+ * Only enabled if {@link assert} is enabled (otherwise no-op). Checks if `x` is
58
+ * a function and if not throws {@link AssertionError}, optionally with given
59
+ * `msg`.
60
+ *
61
+ * @remarks
62
+ * See {@link defEnsure} for details.
63
+ *
64
+ * @param x
65
+ * @param msg
66
+ */
67
+ export const ensureFunction = defEnsure((x) => typeof x === "function", "function");
68
+ /**
69
+ * Only enabled if {@link assert} is enabled (otherwise no-op). Checks if `x` is
70
+ * an ES6 iterable and if not throws {@link AssertionError}, optionally with
71
+ * given `msg`.
72
+ *
73
+ * @remarks
74
+ * See {@link defEnsure} for details.
75
+ *
76
+ * @param x
77
+ * @param msg
78
+ */
79
+ export const ensureIterable = defEnsure((x) => typeof x[Symbol.iterator] === "function", "iterable");
80
+ /**
81
+ * Only enabled if {@link assert} is enabled (otherwise no-op). Checks if `x` is
82
+ * a number and if not throws {@link AssertionError}, optionally with given
83
+ * `msg`.
84
+ *
85
+ * @remarks
86
+ * See {@link defEnsure} for details.
87
+ *
88
+ * @param x
89
+ * @param msg
90
+ */
91
+ export const ensureNumber = defEnsure((x) => typeof x === "number", "number");
92
+ /**
93
+ * Only enabled if {@link assert} is enabled (otherwise no-op). Checks if `x` is
94
+ * a string and if not throws {@link AssertionError}, optionally with given
95
+ * `msg`.
96
+ *
97
+ * @remarks
98
+ * See {@link defEnsure} for details.
99
+ *
100
+ * @param x
101
+ * @param msg
102
+ */
103
+ export const ensureString = defEnsure((x) => typeof x === "string", "string");
104
+ /**
105
+ * Only enabled if {@link assert} is enabled (otherwise no-op). Checks if `x` is
106
+ * a symbol and if not throws {@link AssertionError}, optionally with given
107
+ * `msg`.
108
+ *
109
+ * @remarks
110
+ * See {@link defEnsure} for details.
111
+ *
112
+ * @param x
113
+ * @param msg
114
+ */
115
+ export const ensureSymbol = defEnsure((x) => typeof x === "symbol", "symbol");
package/index.d.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  export * from "./deferror.js";
2
2
  export * from "./assert.js";
3
+ export * from "./ensure.js";
3
4
  export * from "./illegal-arguments.js";
4
5
  export * from "./illegal-arity.js";
5
6
  export * from "./illegal-state.js";
package/index.js CHANGED
@@ -1,5 +1,6 @@
1
1
  export * from "./deferror.js";
2
2
  export * from "./assert.js";
3
+ export * from "./ensure.js";
3
4
  export * from "./illegal-arguments.js";
4
5
  export * from "./illegal-arity.js";
5
6
  export * from "./illegal-state.js";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@thi.ng/errors",
3
- "version": "2.2.17",
3
+ "version": "2.3.1",
4
4
  "description": "Custom error types and error factory functions",
5
5
  "type": "module",
6
6
  "module": "./index.js",
@@ -34,13 +34,13 @@
34
34
  "test": "testament test"
35
35
  },
36
36
  "devDependencies": {
37
- "@microsoft/api-extractor": "^7.35.3",
38
- "@thi.ng/testament": "^0.3.17",
39
- "@types/node": "^20.3.1",
37
+ "@microsoft/api-extractor": "^7.36.3",
38
+ "@thi.ng/testament": "^0.3.19",
39
+ "@types/node": "^20.4.6",
40
40
  "rimraf": "^5.0.1",
41
41
  "tools": "^0.0.1",
42
42
  "typedoc": "^0.24.8",
43
- "typescript": "^5.1.3"
43
+ "typescript": "^5.1.6"
44
44
  },
45
45
  "keywords": [
46
46
  "assert",
@@ -71,6 +71,9 @@
71
71
  "./deferror": {
72
72
  "default": "./deferror.js"
73
73
  },
74
+ "./ensure": {
75
+ "default": "./ensure.js"
76
+ },
74
77
  "./illegal-arguments": {
75
78
  "default": "./illegal-arguments.js"
76
79
  },
@@ -93,5 +96,5 @@
93
96
  "thi.ng": {
94
97
  "year": 2018
95
98
  },
96
- "gitHead": "54e825a976c72067a244cff8725ca98f5416d26d\n"
99
+ "gitHead": "672fb5ede530598da51c9d1cee48fe58c23bad34\n"
97
100
  }