@muze-nl/assert 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Auke van Slooten
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# Asserts
+
+[![Project stage: Experimental][project-stage-badge: Experimental]][project-stage-page]
+
+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
+
+This library was created as part of the [@muze-nl/metro](https://github.com/muze-nl/metro/) package initially, but has escaped its confines.
+
+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.
+
+This is especially true about mock middleware. Mock middleware is middleware that blocks the actual transmission of a request, and returns a mock response instead. Your browser doesn't actually fetch the requests URL.
+
+The [oauth2 middleware](https://github.com/muze-nl/metro-oauth2) for example, has unit tests that use the oauth2 mock-server middleware to mimick a server. This way you can be sure that the oauth2 client implementation works, without having to setup a real oauth2 server anywhere.
+
+Since these mock middleware servers are especially meant for the initial development of new middleware, they should assert as much as they can. And send comprehensive error messages to the console. Here the [`assert.fails()`](./docs/fails.md) method comes in handy.
+
+`assert.fails()` returns `false` if there are no problems. If one or more assertions do fail, it will return an array with messages about each failed assertion. So one way of using it is like this:
+
+```javascript
+let error
+
+if (error = assert.fails(url, {
+  searchParams: {
+    response_type: 'code',
+    client_id: 'mockClientId',
+    state: assert.Optional(/.+/)
+  }
+})) {
+  return metro.response({
+    url: req.url,
+    status: 400,
+    statusText: 'Bad Request',
+    body: '400 Bad Request'
+  })
+}
+```
+
+The first parameter to `assert.fails` contains the data you want to check. The second (or third, fourth, etc.) contain the assertions. If the data is an object, the assertions can use the same property names to add assertions for those specific properties. Here the `url.searchParams.response_type` must be equal to `code`, or the assertion will fail. You can also use numbers and booleans like this.
+
+You can also add functions to the assertions. In this case the `assert.optional()` method adds a function that will only fail if the property is set and not `null`, but does not match the assertions passed to `assert.optional()`.
+
+An assertion may also be a regular expression. If the property value fails to match that expression, the assertion fails. Here the `url.searchParams.state` is tested to make sure that, if it is set, it must not be empty.
+
+In a mock middleware function, it is all well and good to always test your preconditions. But in production many preconditions may be assumed to be valid. These preconditions are not expected to fail in production, only in development. In that case you may use [`assert.check()`]('./docs/check.md'). This function by default does nothing. Only when you enable assertions does this function do anything. This allows you to selectively turn on assertions only in a development context. And avoid doing unnecessary work while in production. This is how it is used in the [oauth2 middleware](./middleware/oauth2.md) (not the mock server, the actual client code):
+
+```javascript
+assert.assert(oauth2, {
+	client_id: /.+/,
+	authRedirectURL: /.+/,
+	scope: /.*/
+})
+```
+
+This makes sure that the `client_id` and `authRedirectURL` configuration options have been set and are not empty. But when the code is used in production, this should never happen. There is no need to constantly test for this. And in production it won't actually get checked. Only when you enable assertions will this code actually perform the tests:
+
+```javascript
+assert.enable()
+```
+
+Once the [`assert.enable()`](./docs/enable.md) function is called, now `assert.check()` will throw an error if any assertion fails. The error is also logged to the console.
+
+
+[project-stage-badge: Experimental]: https://img.shields.io/badge/Project%20Stage-Experimental-yellow.svg
+[project-stage-page]: https://blog.pother.ca/project-stages/

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@muze-nl/assert",
+  "version": "0.1.0",
+  "description": "light optional assert library",
+  "type": "module",
+  "main": "src/assert.mjs",
+  "scripts": {
+    "test": "tap test/*.mjs",
+    "tap": "tap"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/muze-nl/assert.git"
+  },
+  "author": "auke@muze.nl",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/muze-nl/assert/issues"
+  },
+  "homepage": "https://github.com/muze-nl/assert/#readme",
+  "devDependencies": {
+    "tap": "^16.0.1"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "/src",
+    "/LICENSE",
+    "/README.md"
+  ]
+}

package/src/assert.mjs

@@ -0,0 +1,197 @@
+// 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
+globalThis.assertEnabled = false
+
+export function enable() {
+	globalThis.assertEnabled = true
+}
+
+export function disable() {
+	globalThis.assertEnabled = false
+}
+
+export function error(message, found, expected) {
+	return {
+		message,
+		found,
+		expected
+	}
+}
+
+/**
+ * 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
+ */
+export function fails(data, pattern, container) {
+	let problems = []
+	if (pattern === Boolean) {
+		if (typeof data != 'boolean') {
+			problems.push(error('data is not a boolean', data, pattern))
+		}		
+	} else if (pattern === Number) {
+		if (typeof data != 'number') {
+			problems.push(error('data is not a number', data, pattern))
+		}
+	} else if (pattern instanceof RegExp) {
+    	if (Array.isArray(data)) {
+			let index = data.findIndex(element => fails(element,pattern))
+            if (index>-1) {
+            	problems.push(error('data['+index+'] does not match pattern', data[index], pattern))
+            }
+    	} else if (!pattern.test(data)) {
+        	problems.push(error('data does not match pattern', data, pattern))
+        }
+    } else if (pattern instanceof Function) {
+        if (pattern(data, container)) {
+        	problems.push(error('data does not match function', data, pattern))
+        }
+    } else if (Array.isArray(pattern)) {
+		if (!Array.isArray(data)) {
+			problems.push(error('data is not an array',data,[]))
+		}
+		for (p of pattern) {
+			let problem = fails(data, p)
+			if (Array.isArray(problem)) {
+				problems.concat(problem)
+			} else if (problem) {
+				problems.push(problem)
+			}
+    	}
+    } else if (pattern && typeof pattern == 'object') {
+        if (Array.isArray(data)) {
+            let index = data.findIndex(element => fails(element,pattern))
+            if (index>-1) {
+            	problems.push(error('data['+index+'] does not match pattern', data[index], pattern))
+            }
+        } else if (!data || typeof data != 'object') {
+        	problems.push(error('data is not an object, pattern is', data, pattern))
+        } else {
+        	if (data instanceof URLSearchParams) {
+        		data = Object.fromEntries(data)
+        	}
+	        let p = problems[problems.length-1]
+	        for (const [wKey, wVal] of Object.entries(pattern)) {
+	            let result = fails(data[wKey], wVal, data)
+	            if (result) {
+	            	if (!p || typeof p == 'string') {
+	            		p = {}
+	            		problems.push(error(p, data[wKey], wVal))
+	            	}
+	            	p[wKey] = result.problems
+	            }
+	        }
+	    }
+    } else {
+    	if (pattern!=data) {
+    		problems.push(error('data and pattern are not equal', data, pattern))
+    	}
+    }
+    if (problems.length) {
+    	return problems
+    }
+    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 assertError {
+	constructor(problems, ...details) {
+		this.problems = problems
+		this.details = details
+		console.trace()
+	}
+}