xdbc 1.0.93 → 1.0.95

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+Callari@WaXCode.net.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

package/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to XDBC
+
+Thank you for your interest in contributing to XDBC! We welcome contributions of all kinds, including bug reports, feature requests, code contributions, and documentation improvements.
+
+## Reporting Issues
+
+If you find a bug or have a feature request, please open an issue on GitHub. When reporting a bug, please include:
+
+* Steps to reproduce the bug
+* Expected behavior
+* Actual behavior
+* Your operating system and browser (if applicable)
+
+## Contributing Code
+
+1.  Fork the repository.
+2.  Create a branch for your changes: `git checkout -b my-feature-branch`.
+3.  Make your changes and commit them: `git commit -am 'Add some feature'`.
+4.  Push your changes to your fork: `git push origin my-feature-branch`.
+5.  Open a pull request on GitHub.
+
+## Code Style
+
+Please follow the coding style guidelines used in the project. We use Biome, so please run it before submitting a pull request.
+
+## Documentation
+
+We welcome improvements to the documentation. Please submit pull requests with your changes.
+
+## License
+
+By contributing to XDBC, you agree that your contributions will be licensed under the MIT license.
+
+## Code of Conduct
+
+Please review and abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Contact
+
+If you have any questions, please mail to [XDBC@WaXcode.net](mailto:XDBC@WaXCode.net).

package/FUNDING.yml

@@ -0,0 +1,3 @@
+github: CallariS
+patreon: salvatorecallari
+custom: ['https://paypal.me/CallariS']

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Salvatore Callari
+
+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,96 @@
+# XDbC / e**X**plicit **D**esign **b**y **C**ontract™
+
+Leverages the explicit nature of metadata to provide a **D**esign **b**y **C**ontract™ Framework in a precise and comprehensible manner.
+
+| Do...             | Instead Of                                                 |
+|-------------------|------------------------------------------------------------|
+| <pre>@DBC.ParamvalueProvider<br>public method(@AE.PRE([new REGEX(/^\.*XDBC.\*$/i)]) input : Array\<string>) {<br> ... <br>}</pre>|<pre>public method( input : Array\<string>) {<br>  input.forEach(( element, index ) => {<br>   console.assert(/^.\*XDBC.\*$/i.test(element),"inconsistent error message");<br>  });<br><br>  ...<br>}</pre>
+| <pre>@REGEX.INVARIANT(/^.\*XDBC.\*$/i)<br>public field = "XDBC";</pre>|<pre>get field() : string { return ... }<br>set field( toSet : string ) {<br> console.assert(/^.\*XDBC.\*$/i.test(element),"Inconsistent error message"); <br><br> ...<br>}</pre>
+| <pre>@REGEX.POST(/^XDBC$/i)<br>public method( input : unknown ) : string {<br> ...<br><br> return result ;<br>}</pre>|<pre>public method( input : unknown ) : string {<br> ...<br><br> if(!/^.\*XDBC.\*$/i.test(result) {<br>   throw new Error("inconsistent error message");<br> }<br><br> return result ;<br>}</pre>
+<pre>...and get consistent details about errors like: <code style = "background-color : beige ; color : red ;">[ XDBC Infringement [ From "method" in "MyClass": [ Parameter-value "+1d,+5d,-x10y" of the 1st parameter did not fulfill one of it's contracts: Violating-Arrayelement at index 2. Value has to comply to regular expression "/^(?i:(NOW)|([+-]\d+[dmy]))$/i"]]]</code></pre>
+
+## What is **D**esign **b**y **C**ontract™ ?
+[**D**esign **b**y **C**ontract™ (DbC)](https://en.wikipedia.org/wiki/Design_by_contract) is a software development approach focused on defining precise and verifiable contracts between software components. These contracts specify the preconditions that must be true when calling a component (e.g., a function or method), the postconditions guaranteed after the component's execution, and the invariants that must hold true throughout the lifetime of an object or class.
+
+## Benefits of Design by Contract:
+
+| Benefit               | Description                                                |
+|-----------------------|------------------------------------------------------------|
+| More Reliable         | Early error detection through contract checking            |
+| More Maintainable     | Clear responsibilities and expected behavior               |
+| Better Documentation  | Contracts as living behavior descriptions                  |
+| Easier Debugging      | Error causes traceable through contract violations         |
+
+
+**DbC** improves software quality and maintainability by explicitly defining and verifying contract conditions.
+
+## What is the difference between DbC and Assertions ?
+
+| Feature          | DBC with Decorators                    | Assertions                            |
+|------------------|----------------------------------------|---------------------------------------|
+| Formality        | Formal, explicit in definition         | Informal, often within the body       |
+| Integration      | Metadata                               | Built-in keyword                      |
+| Features         | Can be more feature-rich               | Simple, primarily for error detection |
+| Readability      | Generally good, contracts are clear    | Can become cluttered                  |
+| Maintainability  | Often better, contracts are localized  | Can be harder to track and modify     |
+| Production       | Contracts can be kept or disabled      | Often disabled for performance        |
+
+## Demo & API Documentation
+Check out the **Demo.ts** to see some examples usages and the [API](https://callaris.github.io/XDBC/)'s documentation.
+
+## Installation
+
+```sh
+npm install --save xdbc
+```
+
+## Usage
+
+As by now there're nine contracts that can be used:
+
+- AE (*Each element of the value-array has to fulfill a certain set of contracts*)
+- EQ (*Value has to be equal to a supplied reference value*)
+- GREATER (*Value has to be greater than a supplied reference value*)
+- INSTANCE (*Value has to be an instance of a supplied type*)
+- JSON.OP (*Value has to contain certain properties of certain type*)
+- JSON.Parse (*String-value has to be a parsable JSON*)
+- OR (*At least one of a set of contracts has to be fulfilled*)
+- REGEX (*Value has to be validated by a supplied regular expression*)
+- TYPE (*Value has to be of a certain type*)
+
+All of which expose a method **PRE**, **POST** and **INVARIANT** (*precondition, postcondition and invariant*).<br>
+Import the classes to use from **xdbc**. If parameters shall be decorated with contracts import class **DBC** also. <br><br>
+
+The **PRE**-Method can be used to decorate method-parameter: <code>public method(@REGEX.PRE(/XDBC.\*/g) input : string)</code>.<br>Whenever the method is invoked the value will be checked. Since parameter decorators don't have access to the parameter's value, the method itself must additionally be decorated with the **ParamvalueProvider**:<br>
+<code>
+@DBC.**ParamvalueProvider**<br>
+public method(@REGEX.PRE(/XDBC.\*/g) input : string)
+</code><br><br>
+The **POST**-Method can be used to decorate a method:<br>
+<code>
+@EQ.POST(10)<br>
+public method() { return 10 ;}<br></code>
+Whenever the method returns, it's return-value will be checked.<br>
+
+The **INVARIANT**-Method can be used to decorate fields:<br>
+<code>
+@REGEX.INVARIANT(/^a$/)<br>
+public testProperty = "a";
+</code><br>
+Whenever the field is assigned a value and also when initialized, the new value will be checked. So there's no need to write a getter and setter just because there's is the necessity to perform checks on the value anymore.<br>
+
+Certain contracts take other contracts as a parameter. For example the **AE** contract that applies a specified set of contracts on each element of the tagged object's value if it is an array or the object itself if it isn't: <code>@AE.PRE([new REGEX(/^(?i:(NOW)|([+-]\d+[dmy]))$/i, new GREATER(10,"length")])</code>.
+
+With **PRE**, **POST** and **INVARIANT** decorators an optional **path** parameter may be specified. This parameter is a dotted path to a nested property of the tagged object that shall be checked instead of the tagged one. Thus **@DBC.INVARIANT([new REGEX(/^.$/)])** could also be defined as: **@DBC.INVARIANT([new EQ(1)],"length")**, that way demanding that the value to be set is a string with exactly one character.
+
+Multiple instances of the class **DBC** with varying settings for e.g. reporting infringements may be instantiated. Which of these instances is used to report can be defined when either using **PRE**, **POST** or **INVARIANT** by defining their **dbc** parameter: **@DBC.INVARIANT([new EQ(1)],"length","MyVendor.MyDBCInstance")**, for example. The standard path (*WaXCode.DBC*) leads to an automatically created instance, that is generated when the Framework is imported.
+
+Many contracts got further features like the **AE**-Contract that can check specific ranges within the tagged array or the **EQ**- and **GREATER**-Contract that can be inverted turning them into **not EQual**- or **LESS**-Contracts. Check out the [API](https://callaris.github.io/XDBC/) for details.
+
+A **DBC**'s **warningSettings** & **infringementSettings** determine what happens on warnings and errors, whereas warnings are not implemented yet.
+
+## Contribution
+Participation is highly valued and warmly welcomed. The ultimate goal is to create a tool that proves genuinely useful and empowers a wide range of developers to build more robust and reliable applications.
+
+
+

package/SECURITY.md

@@ -0,0 +1,36 @@
+# Security Policy
+
+## Introduction
+
+This security policy outlines our commitment to ensuring the security of XDBC and its users.
+
+## Reporting Vulnerabilities
+
+To report a security vulnerability, please send an email to [Security@WaXCode.net](mailto:Security@WaXCode.net). Please include the following information:
+
+* Description of the vulnerability
+* Steps to reproduce
+* Affected components/versions
+* Potential impact
+
+We will acknowledge your report within 24 - 48 hours and provide updates as we investigate.
+
+## Vulnerability Handling
+
+We will triage and assess reported vulnerabilities, prioritizing them based on severity. We will develop and test patches, and communicate updates to users.
+
+## Disclosure Policy
+
+We will publicly disclose vulnerabilities after a fix is available. We may provide credit to reporters with their consent.
+
+## Security Best Practices
+
+We follow secure coding standards and regularly update dependencies.
+
+## Responsible Disclosure
+
+We encourage responsible disclosure and will not take legal action against reporters.
+
+## Policy Updates
+
+This policy will be reviewed and updated regularly.

package/Test.html

@@ -8,7 +8,7 @@
 <body>
     <h1>Loading test.js Script</h1>
 
-    <script src="dist/test.js" type="module"></script>
+    <script src="dist/bundle.js" type="module"></script>
     <script>
         
     </script>

package/__tests__/DBC/AE.test.ts

@@ -0,0 +1,62 @@
+import { AE } from "../../src/DBC/AE";
+import { REGEX } from "../../src/DBC/REGEX";
+import { EQ } from "../../src/DBC/EQ";
+
+describe("AE", () => {
+	const ae = new AE([new REGEX(/^a$/), new EQ("a")]);
+
+	test("Should report no infringement with 'a' to check", () => {
+		expect(ae.check("a" as unknown as object)).toBe(true);
+	});
+
+	test("Should report no infringement with ['a','a','a'] to check", () => {
+		expect(ae.check(["a", "a", "a"] as unknown as object)).toBe(true);
+	});
+
+	test("Should report infringement with ['a','b','a'] to check", () => {
+		expect(typeof ae.check(["a", "b", "a"] as unknown as object)).toBe(
+			"string",
+		);
+		1;
+	});
+
+	test("Should not report infringement with ['b','a','b'] to check when checking only index 1", () => {
+		expect(
+			new AE([new REGEX(/^a$/), new EQ("a")], 1).check([
+				"b",
+				"a",
+				"b",
+			] as unknown as object),
+		).toBe(true);
+	});
+
+	test("Should report infringement with ['b','a','b'] to check when checking from index 1 on", () => {
+		expect(
+			typeof new AE([new REGEX(/^a$/), new EQ("a")], 1, -1).check([
+				"b",
+				"a",
+				"b",
+			] as unknown as object),
+		).toBe("string");
+	});
+
+	test("Should not report infringement with ['a','a','b'] to check when checking from index 0 to 1", () => {
+		expect(
+			new AE([new REGEX(/^a$/), new EQ("a")], 0, 1).check([
+				"a",
+				"a",
+				"b",
+			] as unknown as object),
+		).toBe(true);
+	});
+
+	test("Should report infringement with ['a','a','b'] to check when checking from index 0 to 1 case of EQ-Condition", () => {
+		expect(
+			typeof new AE([new REGEX(/^a$/), new EQ("b")], 0, 1).check([
+				"a",
+				"a",
+				"b",
+			] as unknown as object),
+		).toBe("string");
+	});
+});

package/__tests__/DBC/EQ.test.ts

@@ -0,0 +1,13 @@
+import { EQ } from "../../src/DBC/EQ";
+
+describe("EQ", () => {
+	const eq = new EQ("b");
+
+	test("Should not report infringement with 'b' to check", () => {
+		expect(eq.check("b")).toBe(true);
+	});
+
+	test("Should report infringement with 'c' to check", () => {
+		expect(typeof eq.check("c")).toBe("string");
+	});
+});

package/__tests__/DBC/GREATER.test.ts

@@ -0,0 +1,29 @@
+import { GREATER } from "../../src/DBC/GREATER";
+
+describe("GREATER", () => {
+	const greater = new GREATER(1);
+
+	test("Should not report infringement with '2' to check", () => {
+		expect(greater.check(2)).toBe(true);
+	});
+
+	test("Should report infringement with '0' to check", () => {
+		expect(typeof greater.check(0)).toBe("string");
+	});
+
+	test("Should report infringement with '0' to check", () => {
+		expect(typeof greater.check(0)).toBe("string");
+	});
+
+	test("Should not report infringement with '1' and '1' to check since equality is now permitted", () => {
+		expect(new GREATER(1, true).check(1)).toBe(true);
+	});
+
+	test("Should not report infringement with '2' and '1' to check since inverting the result is now on", () => {
+		expect(new GREATER(1, true, true).check(1)).toBe(true);
+	});
+
+	test("Should not report infringement with 'undefined' and 'undefined' to check", () => {
+		expect(new GREATER(undefined).check(undefined)).toBe(true);
+	});
+});

package/__tests__/DBC/INSTANCE.test.ts

@@ -0,0 +1,13 @@
+import { INSTANCE } from "../../src/DBC/INSTANCE";
+
+describe("INSTANCE", () => {
+	const instance = new INSTANCE(RegExp);
+
+	test("Should not report infringement with '/a/g' to check", () => {
+		expect(instance.check(/a/g)).toBe(true);
+	});
+
+	test("Should report infringement with 'd' to check", () => {
+		expect(typeof instance.check("d")).toBe("string");
+	});
+});

package/__tests__/DBC/JSON.OP.test.ts

@@ -0,0 +1,47 @@
+import { JSON_OP } from "../../src/DBC/JSON.OP";
+
+describe("JSON.OP", () => {
+	const jsonOP = new JSON_OP([
+		{ name: "x", type: "string" },
+		{ name: "y", type: "number" },
+	]);
+
+	test("Should not report infringement with { x: 'x', y: 1 } to check", () => {
+		expect(jsonOP.check({ x: "x", y: 1 })).toBe(true);
+	});
+
+	test("Should report infringement with { x: 1 } to check", () => {
+		expect(typeof jsonOP.check({ x: 1 })).toBe("string");
+	});
+
+	test("Should not report infringement with [{ x: 'x', y: 1 },{ x: 'xs', y: 2 }] to check in 'checkElements' mode", () => {
+		expect(
+			new JSON_OP(
+				[
+					{ name: "x", type: "string" },
+					{ name: "y", type: "number" },
+				],
+				true,
+			).check([
+				{ x: "x", y: 1 },
+				{ x: "xs", y: 2 },
+			]),
+		).toBe(true);
+	});
+
+	test("Should report infringement with [{ x: 'x', y: 1 },{ x: 'xs', y: 2 }] to check with no 'checkElements' mode", () => {
+		expect(
+			typeof new JSON_OP([
+				{ name: "x", type: "string" },
+				{ name: "y", type: "number" },
+			]).check([
+				{ x: "x", y: 1 },
+				{ x: "xs", y: 2 },
+			]),
+		).toBe("string");
+	});
+
+	test("Should report infringement with [] to check", () => {
+		expect(typeof jsonOP.check([])).toBe("string");
+	});
+});

package/__tests__/DBC/JSON.Parse.test.ts

@@ -0,0 +1,17 @@
+import { JSON_Parse } from "../../src/DBC/JSON.Parse";
+
+describe("EQ", () => {
+	const jsonParse = new JSON_Parse();
+
+	test(`Should not report infringement with '{"d":"o"}' to check`, () => {
+		expect(jsonParse.check('{"d":"o"}')).toBe(true);
+	});
+
+	test(`Should report infringement with '{"d":o}' to check`, () => {
+		expect(typeof jsonParse.check('{"d":o}')).toBe("string");
+	});
+
+	test(`Should not report infringement or throw "referenceException" with '{"d":"o"}' to check and "receptor" not defined`, () => {
+		expect(new JSON_Parse().check('{"d":"o"}')).toBe(true);
+	});
+});

package/__tests__/DBC/OR.test.ts

@@ -0,0 +1,14 @@
+import { OR } from "../../src/DBC/OR";
+import { EQ } from "../../src/DBC/EQ";
+
+describe("EQ", () => {
+	const or = new OR([new EQ("a"), new EQ("b")]);
+
+	test("Should not report infringement with 'b' to check", () => {
+		expect(or.check("b")).toBe(true);
+	});
+
+	test("Should report infringement with 'c' to check", () => {
+		expect(typeof or.check("c")).toBe("string");
+	});
+});

package/__tests__/DBC/REGEX.test.ts

@@ -0,0 +1,13 @@
+import { REGEX } from "../../src/DBC/REGEX";
+
+describe("EQ", () => {
+	const regex = new REGEX(/^a$/);
+
+	test("Should not report infringement with 'a' to check", () => {
+		expect(regex.check("a")).toBe(true);
+	});
+
+	test("Should report infringement with 'c' to check", () => {
+		expect(typeof regex.check("c")).toBe("string");
+	});
+});

package/__tests__/DBC/TYPE.test.ts

@@ -0,0 +1,13 @@
+import { TYPE } from "../../src/DBC/TYPE";
+
+describe("EQ", () => {
+	const type = new TYPE("string");
+
+	test("Should not report infringement with 'a' to check", () => {
+		expect(type.check("a")).toBe(true);
+	});
+
+	test("Should report infringement with 1 to check", () => {
+		expect(typeof type.check(1)).toBe("string");
+	});
+});

package/babel.rc

@@ -0,0 +1,12 @@
+{
+	"presets": [
+		[
+			"@babel/preset-env",
+			{
+				"targets": {
+					"node": "current"
+				}
+			}
+		]
+	]
+}