@muze-nl/assert 0.1.0 → 0.1.2

package/README.md

@@ -4,9 +4,53 @@
 
 This is a light-weight library to do optional assertion checking. By default any assertions made are not tested. Assertion code is not run. Unless you toggle assertion checking, usually in developer mode, by calling `enable`. Now your assertions are run, and if any assertions fail, an error is thrown with information about the specific failure.
 
-## Asserting preconditions
+_Note:_ This library was created as part of the [@muze-nl/metro](https://github.com/muze-nl/metro/) package initially, but has escaped its confines. In the rest of the documentation, when referring to 'middleware', we mean middleware modules for the metro http client in the browser.
+
+## Installation
+
+### Using NPM:
+
+```shell
+npm install @muze-nl/assert
+```
+
+The include it in your javascript code like this:
+```javascript
+import * as assert from '@muze-nl/assert'
+```
+
+Or if you are a fan of shorter assertions:
+
+```javascript
+import { assert, enable, disable, Optional, Required, Recommended, oneOf, anyOf, not, validURL, instanceOf } from '@muze-nl/assert'
+```
+
+### Using a CDN like jsdelivr
+```html
+<script src="https://cdn.jsdelivr.net/npm/@muze-nl/assert@0.1.1/dist/browser.js" integrity="sha384-fqO47gvA1/4UGo0iokMu6ZXdBCkRUbNfXejhrmZrWpJaP+7FPaJqJ03Irhzl1ifk" crossorigin="anonymous"></script>
+```
+
+_Note_: jsdelivr.com doesn't calculate the integrity hash for you, I've used https://www.srihash.org here.
+
+Using a CDN like this means that assert is loaded globally as window.assert.
+
+## Usage
 
-This library was created as part of the [@muze-nl/metro](https://github.com/muze-nl/metro/) package initially, but has escaped its confines.
+```javascript
+function myFunction(param1, param2) {
+  assert(param1, Required(validURL))
+  assert(param2, Optional(not(/foo.*/)))
+  // do your own stuff here
+}
+```
+
+When calling myFunction above, none of the assertions are actually checked, unless you enable assertion checking first, like this:
+
+```javascript
+enable()
+```
+
+## Asserting preconditions
 
 When writing middleware there is usually quite a lot of preconditions to check. When a developer wants to use your middleware, it is nice to have explicit feedback about what he or she is doing wrong. However this is only useful during development. Once in production you should assume that there are no developer mistakes anymore... or at least that the end user has no use for detailed error reports about your middleware.
 

package/dist/browser.js

@@ -0,0 +1,2 @@
+function e(e,t,a,n){Object.defineProperty(e,t,{get:a,set:n,enumerable:!0,configurable:!0})}var t={};function a(){globalThis.assertEnabled=!0}function n(){globalThis.assertEnabled=!1}e(t,"enable",()=>a),e(t,"disable",()=>n),e(t,"assert",()=>r),e(t,"fails",()=>b),e(t,"Optional",()=>s),e(t,"Required",()=>o),e(t,"Recommended",()=>i),e(t,"oneOf",()=>l),e(t,"error",()=>m),e(t,"anyOf",()=>f),e(t,"validURL",()=>d),e(t,"validEmail",()=>u),e(t,"instanceOf",()=>c),e(t,"not",()=>h),globalThis.assertEnabled=!1;const r=(e,t)=>{if(globalThis.assertEnabled){let a=b(e,t);if(a)throw new y("Assertions failed",a,e)}},s=e=>t=>null!=t&&void 0!==t&&b(t,e),o=e=>t=>b(t,e),i=e=>t=>null==t||void 0===t?(console.warning("data does not contain recommended value",t,e),!1):b(t,e),l=(...e)=>t=>{for(let a of e)if(!b(t,a))return!1;return m("data does not match oneOf patterns",t,e)},f=(...e)=>t=>{if(!Array.isArray(t))return m("data is not an array",t,"anyOf");for(let a of t)if(l(...e)(a))return m("data does not match anyOf patterns",a,e);return!1};function d(e){try{if(e instanceof URL&&(e=e.href),new URL(e).href!=e)return m("data is not a valid url",e,"validURL")}catch(t){return m("data is not a valid url",e,"validURL")}return!1}function u(e){return!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(e)&&m("data is not a valid email",e,"validEmail")}const c=e=>t=>!(t instanceof e)&&m("data is not an instanceof pattern",t,e),h=e=>t=>!b(t,e)&&m("data matches pattern, when required not to",t,e);function b(e,t,a){a||(a=e);let n=[];if(t===Boolean)"boolean"!=typeof e&&n.push(m("data is not a boolean",e,t));else if(t===Number)"number"!=typeof e&&n.push(m("data is not a number",e,t));else if(t instanceof RegExp){if(Array.isArray(e)){let r=e.findIndex(e=>b(e,t,a));r>-1&&n.push(m("data["+r+"] does not match pattern",e[r],t))}else t.test(e)||n.push(m("data does not match pattern",e,t))}else if(t instanceof Function)t(e,a)&&n.push(m("data does not match function",e,t));else if(Array.isArray(t))for(p of(Array.isArray(e)||n.push(m("data is not an array",e,[])),t)){let t=b(e,p,a);Array.isArray(t)?n.concat(t):t&&n.push(t)}else if(t&&"object"==typeof t){if(Array.isArray(e)){let r=e.findIndex(e=>b(e,t,a));r>-1&&n.push(m("data["+r+"] does not match pattern",e[r],t))}else if(e&&"object"==typeof e){e instanceof URLSearchParams&&(e=Object.fromEntries(e));let r=n[n.length-1];for(let[s,o]of Object.entries(t)){let t=b(e[s],o,a);t&&(r&&"string"!=typeof r||(r={},n.push(m(r,e[s],o))),r[s]=t.problems)}}else n.push(m("data is not an object, pattern is",e,t))}else t!=e&&n.push(m("data and pattern are not equal",e,t));return!!n.length&&n}class y extends Error{constructor(e,t,...a){super(e),this.problems=t,this.details=a}}function m(e,t,a){return{message:e,found:t,expected:a}}globalThis.assert=t;
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"mappings":"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","sources":["<anon>","src/browser.mjs","src/assert.mjs"],"sourcesContent":["\nfunction $parcel$export(e, n, v, s) {\n  Object.defineProperty(e, n, {get: v, set: s, enumerable: true, configurable: true});\n}\nvar $2ddd80d1adc2ea42$exports = {};\n\n$parcel$export($2ddd80d1adc2ea42$exports, \"enable\", () => $2ddd80d1adc2ea42$export$d7c4a0dd6a4567e5);\n$parcel$export($2ddd80d1adc2ea42$exports, \"disable\", () => $2ddd80d1adc2ea42$export$e20fbacbb41798b);\n$parcel$export($2ddd80d1adc2ea42$exports, \"assert\", () => $2ddd80d1adc2ea42$export$a7a9523472993e97);\n$parcel$export($2ddd80d1adc2ea42$exports, \"fails\", () => $2ddd80d1adc2ea42$export$478159de811fd37d);\n$parcel$export($2ddd80d1adc2ea42$exports, \"Optional\", () => $2ddd80d1adc2ea42$export$7acb7b24c478f9c6);\n$parcel$export($2ddd80d1adc2ea42$exports, \"Required\", () => $2ddd80d1adc2ea42$export$1788c381af06add2);\n$parcel$export($2ddd80d1adc2ea42$exports, \"Recommended\", () => $2ddd80d1adc2ea42$export$a83bcf183f49ea9);\n$parcel$export($2ddd80d1adc2ea42$exports, \"oneOf\", () => $2ddd80d1adc2ea42$export$a9a18ae5ba42aeab);\n$parcel$export($2ddd80d1adc2ea42$exports, \"error\", () => $2ddd80d1adc2ea42$export$a3bc9b8ed74fc);\n$parcel$export($2ddd80d1adc2ea42$exports, \"anyOf\", () => $2ddd80d1adc2ea42$export$b26c150f612c10f7);\n$parcel$export($2ddd80d1adc2ea42$exports, \"validURL\", () => $2ddd80d1adc2ea42$export$c6f1a4382426409f);\n$parcel$export($2ddd80d1adc2ea42$exports, \"validEmail\", () => $2ddd80d1adc2ea42$export$9ab921aaffe56820);\n$parcel$export($2ddd80d1adc2ea42$exports, \"instanceOf\", () => $2ddd80d1adc2ea42$export$ca03416d6c9e029e);\n$parcel$export($2ddd80d1adc2ea42$exports, \"not\", () => $2ddd80d1adc2ea42$export$6003a5f097c73977);\n/**\n * assertEnabled (Boolean) used to toggle whether the assert()\n * method should test assertions or not.\n */ globalThis.assertEnabled = false;\nfunction $2ddd80d1adc2ea42$export$d7c4a0dd6a4567e5() {\n    globalThis.assertEnabled = true;\n}\nfunction $2ddd80d1adc2ea42$export$e20fbacbb41798b() {\n    globalThis.assertEnabled = false;\n}\nconst $2ddd80d1adc2ea42$export$a7a9523472993e97 = (source, test)=>{\n    if (globalThis.assertEnabled) {\n        let problems = $2ddd80d1adc2ea42$export$478159de811fd37d(source, test);\n        if (problems) throw new $2ddd80d1adc2ea42$var$assertError(\"Assertions failed\", problems, source);\n    }\n};\nconst $2ddd80d1adc2ea42$export$7acb7b24c478f9c6 = (pattern)=>(data)=>data == null || typeof data == \"undefined\" ? false : $2ddd80d1adc2ea42$export$478159de811fd37d(data, pattern);\nconst $2ddd80d1adc2ea42$export$1788c381af06add2 = (pattern)=>(data)=>$2ddd80d1adc2ea42$export$478159de811fd37d(data, pattern);\nconst $2ddd80d1adc2ea42$export$a83bcf183f49ea9 = (pattern)=>(data)=>data == null || typeof data == \"undefined\" ? (()=>{\n            console.warning(\"data does not contain recommended value\", data, pattern);\n            return false;\n        })() : $2ddd80d1adc2ea42$export$478159de811fd37d(data, pattern);\nconst $2ddd80d1adc2ea42$export$a9a18ae5ba42aeab = (...patterns)=>(data)=>{\n        for (let pattern of patterns){\n            if (!$2ddd80d1adc2ea42$export$478159de811fd37d(data, pattern)) return false;\n        }\n        return $2ddd80d1adc2ea42$export$a3bc9b8ed74fc(\"data does not match oneOf patterns\", data, patterns);\n    };\nconst $2ddd80d1adc2ea42$export$b26c150f612c10f7 = (...patterns)=>(data)=>{\n        if (!Array.isArray(data)) return $2ddd80d1adc2ea42$export$a3bc9b8ed74fc(\"data is not an array\", data, \"anyOf\");\n        for (let value of data){\n            if ($2ddd80d1adc2ea42$export$a9a18ae5ba42aeab(...patterns)(value)) return $2ddd80d1adc2ea42$export$a3bc9b8ed74fc(\"data does not match anyOf patterns\", value, patterns);\n        }\n        return false;\n    };\nfunction $2ddd80d1adc2ea42$export$c6f1a4382426409f(data) {\n    try {\n        if (data instanceof URL) data = data.href;\n        let url = new URL(data);\n        if (url.href != data) return $2ddd80d1adc2ea42$export$a3bc9b8ed74fc(\"data is not a valid url\", data, \"validURL\");\n    } catch (e) {\n        return $2ddd80d1adc2ea42$export$a3bc9b8ed74fc(\"data is not a valid url\", data, \"validURL\");\n    }\n    return false;\n}\nfunction $2ddd80d1adc2ea42$export$9ab921aaffe56820(data) {\n    if (/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(data)) return false // data matches email regex\n    ;\n    return $2ddd80d1adc2ea42$export$a3bc9b8ed74fc(\"data is not a valid email\", data, \"validEmail\");\n}\nconst $2ddd80d1adc2ea42$export$ca03416d6c9e029e = (constructor)=>(data)=>!(data instanceof constructor) ? $2ddd80d1adc2ea42$export$a3bc9b8ed74fc(\"data is not an instanceof pattern\", data, constructor) : false;\nconst $2ddd80d1adc2ea42$export$6003a5f097c73977 = (pattern)=>(data)=>$2ddd80d1adc2ea42$export$478159de811fd37d(data, pattern) ? false : $2ddd80d1adc2ea42$export$a3bc9b8ed74fc(\"data matches pattern, when required not to\", data, pattern);\nfunction $2ddd80d1adc2ea42$export$478159de811fd37d(data, pattern, root) {\n    if (!root) root = data;\n    let problems = [];\n    if (pattern === Boolean) {\n        if (typeof data != \"boolean\") problems.push($2ddd80d1adc2ea42$export$a3bc9b8ed74fc(\"data is not a boolean\", data, pattern));\n    } else if (pattern === Number) {\n        if (typeof data != \"number\") problems.push($2ddd80d1adc2ea42$export$a3bc9b8ed74fc(\"data is not a number\", data, pattern));\n    } else if (pattern instanceof RegExp) {\n        if (Array.isArray(data)) {\n            let index = data.findIndex((element)=>$2ddd80d1adc2ea42$export$478159de811fd37d(element, pattern, root));\n            if (index > -1) problems.push($2ddd80d1adc2ea42$export$a3bc9b8ed74fc(\"data[\" + index + \"] does not match pattern\", data[index], pattern));\n        } else if (!pattern.test(data)) problems.push($2ddd80d1adc2ea42$export$a3bc9b8ed74fc(\"data does not match pattern\", data, pattern));\n    } else if (pattern instanceof Function) {\n        if (pattern(data, root)) problems.push($2ddd80d1adc2ea42$export$a3bc9b8ed74fc(\"data does not match function\", data, pattern));\n    } else if (Array.isArray(pattern)) {\n        if (!Array.isArray(data)) problems.push($2ddd80d1adc2ea42$export$a3bc9b8ed74fc(\"data is not an array\", data, []));\n        for (p of pattern){\n            let problem = $2ddd80d1adc2ea42$export$478159de811fd37d(data, p, root);\n            if (Array.isArray(problem)) problems.concat(problem);\n            else if (problem) problems.push(problem);\n        }\n    } else if (pattern && typeof pattern == \"object\") {\n        if (Array.isArray(data)) {\n            let index = data.findIndex((element)=>$2ddd80d1adc2ea42$export$478159de811fd37d(element, pattern, root));\n            if (index > -1) problems.push($2ddd80d1adc2ea42$export$a3bc9b8ed74fc(\"data[\" + index + \"] does not match pattern\", data[index], pattern));\n        } else if (!data || typeof data != \"object\") problems.push($2ddd80d1adc2ea42$export$a3bc9b8ed74fc(\"data is not an object, pattern is\", data, pattern));\n        else {\n            if (data instanceof URLSearchParams) data = Object.fromEntries(data);\n            let p1 = problems[problems.length - 1];\n            for (const [wKey, wVal] of Object.entries(pattern)){\n                let result = $2ddd80d1adc2ea42$export$478159de811fd37d(data[wKey], wVal, root);\n                if (result) {\n                    if (!p1 || typeof p1 == \"string\") {\n                        p1 = {};\n                        problems.push($2ddd80d1adc2ea42$export$a3bc9b8ed74fc(p1, data[wKey], wVal));\n                    }\n                    p1[wKey] = result.problems;\n                }\n            }\n        }\n    } else if (pattern != data) problems.push($2ddd80d1adc2ea42$export$a3bc9b8ed74fc(\"data and pattern are not equal\", data, pattern));\n    if (problems.length) return problems;\n    return false;\n}\n/**\n * Class used in assert() to add problems found and details to the error object\n */ class $2ddd80d1adc2ea42$var$assertError extends Error {\n    constructor(message, problems, ...details){\n        super(message);\n        this.problems = problems;\n        this.details = details;\n    }\n}\nfunction $2ddd80d1adc2ea42$export$a3bc9b8ed74fc(message, found, expected) {\n    return {\n        message: message,\n        found: found,\n        expected: expected\n    };\n}\n\n\nglobalThis.assert = $2ddd80d1adc2ea42$exports;\n\n\n//# sourceMappingURL=browser.js.map\n","import * as assert from './assert.mjs'\n\nglobalThis.assert = assert\n","/**\n * assertEnabled (Boolean) used to toggle whether the assert()\n * method should test assertions or not.\n */\nglobalThis.assertEnabled = false\n\n/**\n * Enables assertion testing with assert()\n */\nexport function enable() {\n\tglobalThis.assertEnabled = true\n}\n\n/**\n * Disables assertion testing with assert()\n */\nexport function disable() {\n\tglobalThis.assertEnabled = false\n}\n\n/**\n * This function will check the source for the assertions in test, if\n * assertion checking is enabled globally.\n * If it is, and any assertion fails, it will throw an assertError\n * with a list of problems and other details.\n */\nexport const assert = (source, test) => {\n\tif (globalThis.assertEnabled) {\n\t\tlet problems = fails(source,test)\n\t\tif (problems) {\n\t\t\tthrow new assertError('Assertions failed', problems, source)\n\t\t}\n\t}\n}\n\n/**\n * Tests a given value against a pattern, only if the value is not null or undefined\n */\nexport const Optional = (pattern) => \n\t(data) => (data==null || typeof data == 'undefined') ? false : fails(data, pattern)\n\n/**\n * Tests a given value against a pattern, always.\n */\nexport const Required = (pattern) =>\n\t(data) => fails(data, pattern)\n\n/**\n * Tests a given value against a pattern, only if the value is not null or undefined\n * If null or undefined, it does print a warning to the console.\n */\nexport const Recommended = (pattern) =>\n\t(data) => (data==null || typeof data == 'undefined') ? (() => {\n\t\tconsole.warning('data does not contain recommended value', data, pattern)\n\t\treturn false\n\t})() : fails(data, pattern)\n\n/**\n * Tests a given value against a set of patterns, untill one succeeds\n * Returns an error if none succeed\n */\nexport const oneOf = (...patterns) => \n\t(data) => {\n\t\tfor(let pattern of patterns) {\n\t\t\tif (!fails(data, pattern)) {\n\t\t\t\treturn false\n\t\t\t}\n\t\t}\n\t\treturn error('data does not match oneOf patterns',data,patterns)\n\t}\n\n/**\n * Tests a given array of values against a set of patterns\n * If any value does not match one of the patterns, it will return an error\n * If not given an array to test, it will return an error\n */\nexport const anyOf = (...patterns) =>\n\t(data) => {\n\t\tif (!Array.isArray(data)) {\n\t\t\treturn error('data is not an array',data,'anyOf')\n\t\t}\n\t\tfor (let value of data) {\n\t\t\tif (oneOf(...patterns)(value)) {\n\t\t\t\treturn error('data does not match anyOf patterns',value,patterns)\n\t\t\t}\n\t\t}\n\t\treturn false\n\t}\n\n/**\n * Tests a given value to see if it is a valid (and absolute) URL, by\n * parsing it with the URL() constructor, and then testing the href\n * value to be equal to the initial value.\n */\nexport function validURL(data) {\n\ttry {\n\t\tif (data instanceof URL) {\n\t\t\tdata = data.href\n\t\t}\n\t\tlet url = new URL(data)\n\t\tif (url.href!=data) {\n\t\t\treturn error('data is not a valid url',data,'validURL')\n\t\t}\n\t} catch(e) {\n\t\treturn error('data is not a valid url',data,'validURL')\n\t}\n\treturn false\n}\n\n/**\n * Tests a given value to see if it looks like a valid email address, by\n * testing it against a regular expression. So there are no guarantees that\n * it is an actual working email address, just that it looks like one.\n */\nexport function validEmail(data) {\n\tif (/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(data)) {\n\t\treturn false // data matches email regex\n\t}\n\treturn error('data is not a valid email',data,'validEmail')\n}\n\n/**\n * Tests a given value to see if it is an object which is an instance of the given\n * constructor\n */\nexport const instanceOf = (constructor) =>\n\t(data) => !(data instanceof constructor) \n\t\t? error('data is not an instanceof pattern',data,constructor)\n\t\t: false\n\n/**\n * Runs the given test pattern on a value, if the test succeeds, it fails\n * the not() test.\n */\nexport const not = (pattern) =>\n\t(data) => fails(data, pattern) \n\t\t? false \n\t\t: error('data matches pattern, when required not to', data, pattern)\n\n/**\n * returns an array of problems if the data fails to satisfy \n * the assertions in the given pattern, false otherwise\n * @param {any} data    The data to match\n * @param {any} pattern The pattern to match\n * @param {any} root    Root object for assertions, set to data by default\n * @return {Array|false} Array with problems if the pattern fails, false otherwise\n */\nexport function fails(data, pattern, root) {\n\tif (!root) {\n\t\troot = data\n\t}\n\tlet problems = []\n\tif (pattern === Boolean) {\n\t\tif (typeof data != 'boolean') {\n\t\t\tproblems.push(error('data is not a boolean', data, pattern))\n\t\t}\t\t\n\t} else if (pattern === Number) {\n\t\tif (typeof data != 'number') {\n\t\t\tproblems.push(error('data is not a number', data, pattern))\n\t\t}\n\t} else if (pattern instanceof RegExp) {\n    \tif (Array.isArray(data)) {\n\t\t\tlet index = data.findIndex(element => fails(element,pattern,root))\n            if (index>-1) {\n            \tproblems.push(error('data['+index+'] does not match pattern', data[index], pattern))\n            }\n    \t} else if (!pattern.test(data)) {\n        \tproblems.push(error('data does not match pattern', data, pattern))\n        }\n    } else if (pattern instanceof Function) {\n        if (pattern(data, root)) {\n        \tproblems.push(error('data does not match function', data, pattern))\n        }\n    } else if (Array.isArray(pattern)) {\n\t\tif (!Array.isArray(data)) {\n\t\t\tproblems.push(error('data is not an array',data,[]))\n\t\t}\n\t\tfor (p of pattern) {\n\t\t\tlet problem = fails(data, p, root)\n\t\t\tif (Array.isArray(problem)) {\n\t\t\t\tproblems.concat(problem)\n\t\t\t} else if (problem) {\n\t\t\t\tproblems.push(problem)\n\t\t\t}\n    \t}\n    } else if (pattern && typeof pattern == 'object') {\n        if (Array.isArray(data)) {\n            let index = data.findIndex(element => fails(element,pattern,root))\n            if (index>-1) {\n            \tproblems.push(error('data['+index+'] does not match pattern', data[index], pattern))\n            }\n        } else if (!data || typeof data != 'object') {\n        \tproblems.push(error('data is not an object, pattern is', data, pattern))\n        } else {\n        \tif (data instanceof URLSearchParams) {\n        \t\tdata = Object.fromEntries(data)\n        \t}\n\t        let p = problems[problems.length-1]\n\t        for (const [wKey, wVal] of Object.entries(pattern)) {\n\t            let result = fails(data[wKey], wVal, root)\n\t            if (result) {\n\t            \tif (!p || typeof p == 'string') {\n\t            \t\tp = {}\n\t            \t\tproblems.push(error(p, data[wKey], wVal))\n\t            \t}\n\t            \tp[wKey] = result.problems\n\t            }\n\t        }\n\t    }\n    } else {\n    \tif (pattern!=data) {\n    \t\tproblems.push(error('data and pattern are not equal', data, pattern))\n    \t}\n    }\n    if (problems.length) {\n    \treturn problems\n    }\n    return false\n}\n\n\n/**\n * Class used in assert() to add problems found and details to the error object\n */\nclass assertError extends Error {\n\tconstructor(message, problems, ...details) {\n\t\tsuper(message)\n\t\tthis.problems = problems\n\t\tthis.details = details\n\t}\n}\n\n/**\n * Returns an object with message, found and expected properties\n */ \nexport function error(message, found, expected) {\n\treturn {\n\t\tmessage,\n\t\tfound,\n\t\texpected\n\t}\n}\n"],"names":["$parcel$export","e","n","v","s","Object","defineProperty","get","set","enumerable","configurable","$2ddd80d1adc2ea42$exports","$2ddd80d1adc2ea42$export$d7c4a0dd6a4567e5","globalThis","assertEnabled","$2ddd80d1adc2ea42$export$e20fbacbb41798b","$2ddd80d1adc2ea42$export$a7a9523472993e97","$2ddd80d1adc2ea42$export$478159de811fd37d","$2ddd80d1adc2ea42$export$7acb7b24c478f9c6","$2ddd80d1adc2ea42$export$1788c381af06add2","$2ddd80d1adc2ea42$export$a83bcf183f49ea9","$2ddd80d1adc2ea42$export$a9a18ae5ba42aeab","$2ddd80d1adc2ea42$export$a3bc9b8ed74fc","$2ddd80d1adc2ea42$export$b26c150f612c10f7","$2ddd80d1adc2ea42$export$c6f1a4382426409f","$2ddd80d1adc2ea42$export$9ab921aaffe56820","$2ddd80d1adc2ea42$export$ca03416d6c9e029e","$2ddd80d1adc2ea42$export$6003a5f097c73977","source","test","problems","$2ddd80d1adc2ea42$var$assertError","pattern","data","console","warning","patterns","Array","isArray","value","URL","href","url","constructor","root","Boolean","push","Number","RegExp","index","findIndex","element","Function","p","problem","concat","URLSearchParams","fromEntries","p1","length","wKey","wVal","entries","result","Error","message","details","found","expected","assert"],"version":3,"file":"browser.js.map","sourceRoot":"../"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muze-nl/assert",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "light optional assert library",
   "type": "module",
   "main": "src/assert.mjs",
@@ -26,7 +26,16 @@
   },
   "files": [
     "/src",
+    "/dist",
     "/LICENSE",
     "/README.md"
-  ]
+  ],
+  "source": [ "src/browser.mjs" ],
+  "targets": {
+    "default": {
+      "distDir": "./dist",
+      "optimize": true
+    },
+    "main": false
+  }
 }

package/src/assert.mjs

@@ -1,35 +1,154 @@
-// global state switch to enable/disable assert
-// uses globalThis so that even if npm installs multiple
-// versions of this library, all use this same state
+/**
+ * assertEnabled (Boolean) used to toggle whether the assert()
+ * method should test assertions or not.
+ */
 globalThis.assertEnabled = false
 
+/**
+ * Enables assertion testing with assert()
+ */
 export function enable() {
 	globalThis.assertEnabled = true
 }
 
+/**
+ * Disables assertion testing with assert()
+ */
 export function disable() {
 	globalThis.assertEnabled = false
 }
 
-export function error(message, found, expected) {
-	return {
-		message,
-		found,
-		expected
+/**
+ * This function will check the source for the assertions in test, if
+ * assertion checking is enabled globally.
+ * If it is, and any assertion fails, it will throw an assertError
+ * with a list of problems and other details.
+ */
+export const assert = (source, test) => {
+	if (globalThis.assertEnabled) {
+		let problems = fails(source,test)
+		if (problems) {
+			throw new assertError('Assertions failed', problems, source)
+		}
+	}
+}
+
+/**
+ * Tests a given value against a pattern, only if the value is not null or undefined
+ */
+export const Optional = (pattern) => 
+	(data) => (data==null || typeof data == 'undefined') ? false : fails(data, pattern)
+
+/**
+ * Tests a given value against a pattern, always.
+ */
+export const Required = (pattern) =>
+	(data) => fails(data, pattern)
+
+/**
+ * Tests a given value against a pattern, only if the value is not null or undefined
+ * If null or undefined, it does print a warning to the console.
+ */
+export const Recommended = (pattern) =>
+	(data) => (data==null || typeof data == 'undefined') ? (() => {
+		console.warning('data does not contain recommended value', data, pattern)
+		return false
+	})() : fails(data, pattern)
+
+/**
+ * Tests a given value against a set of patterns, untill one succeeds
+ * Returns an error if none succeed
+ */
+export const oneOf = (...patterns) => 
+	(data) => {
+		for(let pattern of patterns) {
+			if (!fails(data, pattern)) {
+				return false
+			}
+		}
+		return error('data does not match oneOf patterns',data,patterns)
+	}
+
+/**
+ * Tests a given array of values against a set of patterns
+ * If any value does not match one of the patterns, it will return an error
+ * If not given an array to test, it will return an error
+ */
+export const anyOf = (...patterns) =>
+	(data) => {
+		if (!Array.isArray(data)) {
+			return error('data is not an array',data,'anyOf')
+		}
+		for (let value of data) {
+			if (oneOf(...patterns)(value)) {
+				return error('data does not match anyOf patterns',value,patterns)
+			}
+		}
+		return false
 	}
+
+/**
+ * Tests a given value to see if it is a valid (and absolute) URL, by
+ * parsing it with the URL() constructor, and then testing the href
+ * value to be equal to the initial value.
+ */
+export function validURL(data) {
+	try {
+		if (data instanceof URL) {
+			data = data.href
+		}
+		let url = new URL(data)
+		if (url.href!=data) {
+			return error('data is not a valid url',data,'validURL')
+		}
+	} catch(e) {
+		return error('data is not a valid url',data,'validURL')
+	}
+	return false
 }
 
 /**
- * returns new Boolean(true) if data does not match pattern
- * you can't return new Boolean(false), or at least that evaluates
- * to true, so if the data does match, it returns a primitive false
- * the Boolean(true) has an extra property called 'problems', which is
- * an array with a list of all fields that do not match, and why
- * @param  {any} data    The data to match
- * @param  {any} pattern The pattern to match
- * @return {Array|false} Array with problems if the pattern fails, false
+ * Tests a given value to see if it looks like a valid email address, by
+ * testing it against a regular expression. So there are no guarantees that
+ * it is an actual working email address, just that it looks like one.
+ */
+export function validEmail(data) {
+	if (/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(data)) {
+		return false // data matches email regex
+	}
+	return error('data is not a valid email',data,'validEmail')
+}
+
+/**
+ * Tests a given value to see if it is an object which is an instance of the given
+ * constructor
+ */
+export const instanceOf = (constructor) =>
+	(data) => !(data instanceof constructor) 
+		? error('data is not an instanceof pattern',data,constructor)
+		: false
+
+/**
+ * Runs the given test pattern on a value, if the test succeeds, it fails
+ * the not() test.
  */
-export function fails(data, pattern, container) {
+export const not = (pattern) =>
+	(data) => fails(data, pattern) 
+		? false 
+		: error('data matches pattern, when required not to', data, pattern)
+
+/**
+ * returns an array of problems if the data fails to satisfy 
+ * the assertions in the given pattern, false otherwise
+ * @param {any} data    The data to match
+ * @param {any} pattern The pattern to match
+ * @param {any} root    Root object for assertions, set to data by default
+ * @return {Array|false} Array with problems if the pattern fails, false otherwise
+ */
+export function fails(data, pattern, root) {
+	if (!root) {
+		root = data
+	}
 	let problems = []
 	if (pattern === Boolean) {
 		if (typeof data != 'boolean') {
@@ -41,7 +160,7 @@ export function fails(data, pattern, container) {
 		}
 	} else if (pattern instanceof RegExp) {
     	if (Array.isArray(data)) {
-			let index = data.findIndex(element => fails(element,pattern))
+			let index = data.findIndex(element => fails(element,pattern,root))
             if (index>-1) {
             	problems.push(error('data['+index+'] does not match pattern', data[index], pattern))
             }
@@ -49,7 +168,7 @@ export function fails(data, pattern, container) {
         	problems.push(error('data does not match pattern', data, pattern))
         }
     } else if (pattern instanceof Function) {
-        if (pattern(data, container)) {
+        if (pattern(data, root)) {
         	problems.push(error('data does not match function', data, pattern))
         }
     } else if (Array.isArray(pattern)) {
@@ -57,7 +176,7 @@ export function fails(data, pattern, container) {
 			problems.push(error('data is not an array',data,[]))
 		}
 		for (p of pattern) {
-			let problem = fails(data, p)
+			let problem = fails(data, p, root)
 			if (Array.isArray(problem)) {
 				problems.concat(problem)
 			} else if (problem) {
@@ -66,7 +185,7 @@ export function fails(data, pattern, container) {
     	}
     } else if (pattern && typeof pattern == 'object') {
         if (Array.isArray(data)) {
-            let index = data.findIndex(element => fails(element,pattern))
+            let index = data.findIndex(element => fails(element,pattern,root))
             if (index>-1) {
             	problems.push(error('data['+index+'] does not match pattern', data[index], pattern))
             }
@@ -78,7 +197,7 @@ export function fails(data, pattern, container) {
         	}
 	        let p = problems[problems.length-1]
 	        for (const [wKey, wVal] of Object.entries(pattern)) {
-	            let result = fails(data[wKey], wVal, data)
+	            let result = fails(data[wKey], wVal, root)
 	            if (result) {
 	            	if (!p || typeof p == 'string') {
 	            		p = {}
@@ -99,99 +218,25 @@ export function fails(data, pattern, container) {
     return false
 }
 
-export function assert(source, test) {
-	if (!globalThis.assertEnabled) {
-		return
-	}
-	let result = fails(source,test)
-	if (result) {
-		throw new assertError(result,source)
-	}
-}
-
-export function Optional(pattern) {
-	return function(data) {
-		if (data==null || typeof data == 'undefined') {
-			return false
-		}
-		return fails(data, pattern)
-	}
-}
-
-export function Required(pattern) {
-	return function(data) {
-		return fails(data, pattern)
-	}
-}
 
-export function Recommended(pattern) {
-	if (data==null || typeof data == 'undefined') {
-		console.warning('data does not contain recommended value', data, pattern)
-		return false
-	}
-	return fails(data, pattern)
-}
-
-export function oneOf(...patterns) {
-	return function(data) {
-		for(let pattern of patterns) {
-			if (!fails(data, pattern)) {
-				return false
-			}
-		}
-		return error('data does not match oneOf patterns',data,patterns)
-	}
-}
-
-export function anyOf(...patterns) {
-	return function(data) {
-		if (!Array.isArray(data)) {
-			return error('data is not an array',data,'anyOf')
-		}
-		for (let value of data) {
-			if (oneOf(...patterns)(value)) {
-				return error('data does not match anyOf patterns',value,patterns)
-			}
-		}
-		return false
-	}
-}
-
-export function validURL(data) {
-	try {
-		let url = new URL(data)
-		if (url.href!=data) {
-			return error('data is not a fully qualified url',data,'validURL')
-		}
-	} catch(e) {
-		return error('data is not a valid url',data,'validURL')
-	}
-	return false
-}
-
-export function instanceOf(constructor) {
-	return function(data) {
-		if (!(data instanceof constructor)) {
-			return error('data is not an instanceof pattern',data,constructor)
-		}
-		return false
-	}
-}
-
-export function not(pattern) {
-	return function(data) {
-		let problem = fails(data, pattern)
-		if (problem) {
-			return false
-		}
-		return error('data matches pattern, when required not to', data, pattern)
+/**
+ * Class used in assert() to add problems found and details to the error object
+ */
+class assertError extends Error {
+	constructor(message, problems, ...details) {
+		super(message)
+		this.problems = problems
+		this.details = details
 	}
 }
 
-class assertError {
-	constructor(problems, ...details) {
-		this.problems = problems
-		this.details = details
-		console.trace()
+/**
+ * Returns an object with message, found and expected properties
+ */ 
+export function error(message, found, expected) {
+	return {
+		message,
+		found,
+		expected
 	}
 }

package/src/browser.mjs

@@ -0,0 +1,3 @@
+import * as assert from './assert.mjs'
+
+globalThis.assert = assert