Merge branch 'aa-framework-js-functions' into 'master'

[ADD] JS functions to the AA framework

See merge request allianceauth/allianceauth!1747

docs/development/custom/aa-framework.md

@@ -13,6 +13,7 @@ The Alliance Auth framework is split into several submodules, each of which is d
 
 framework/api
 framework/css
+framework/js
 framework/templates
 framework/svg-sprite
 :::

docs/development/custom/framework/js.md

@@ -0,0 +1,124 @@
+# JavaScript Framework
+
+This contains some simple JavaScript functions that are used throughout Alliance Auth,
+so they can be used by community app developers as well.
+
+The JS file is already loaded in the base template, so it is globally available.
+
+## Functions
+
+The following functions are available in the JavaScript framework:
+
+### isArray()
+
+Checks if the given value is an array.
+
+Usage:
+
+```javascript
+/* global isArray */
+
+if (isArray(someVariable)) {
+  console.log('This is an array');
+} else {
+  console.log('This is not an array');
+}
+```
+
+### isObject()
+
+Checks if the given value is an object.
+
+Usage:
+
+```javascript
+/* global isObject */
+
+if (isObject(someVariable)) {
+  console.log('This is a plain object');
+} else {
+  console.log('This is not a plain object');
+}
+```
+
+### fetchGet()
+
+Performs a GET request to the given URL and returns a Promise that resolves with the response data.
+
+Usage:
+
+```javascript
+/* global fetchGet */
+
+fetchGet({
+    url: url,
+    responseIsJson: false
+}).then((data) => {
+    // Process the fetched data
+}).catch((error) => {
+    console.error(`Error: ${error.message}`);
+
+    // Handle the error appropriately
+});
+```
+
+#### fetchGet() Parameters
+
+- `url`: The URL to fetch data from.
+- `payload`: Optional data to send with the request. Can be an object or a string.
+- `responseIsJson`: Optional boolean indicating if the response should be parsed as JSON (default is `true`).
+
+### fetchPost()
+
+Performs a POST request to the given URL with the provided data and returns a Promise that resolves with the response data.
+
+Usage:
+
+```javascript
+/* global fetchPost */
+
+fetchPost({
+    url: url,
+    csrfToken: csrfToken,
+    payload: {
+        key: 'value',
+        anotherKey: 'anotherValue'
+    },
+    responseIsJson: true
+}).then((data) => {
+    // Process the fetched data
+}).catch((error) => {
+    console.error(`Error: ${error.message}`);
+
+    // Handle the error appropriately
+});
+```
+
+#### fetchPost() Parameters
+
+- `url`: The URL to send the POST request to.
+- `csrfToken`: The CSRF token to include in the request headers.
+- `payload`: The data as JS object to send with the request.
+- `responseIsJson`: Optional boolean indicating if the response should be parsed as JSON (default is `true`).
+
+### objectDeepMerge()
+
+Recursively merges properties from source objects into a target object. If a property at the current level is an object,
+and both target and source have it, the property is merged. Otherwise, the source property overwrites the target property.
+
+This function does not modify the source objects and prevents prototype pollution by not allowing `__proto__`, `constructor`,
+and `prototype` property names.
+
+Usage:
+
+```javascript
+/* global objectDeepMerge */
+
+const target = {a: 1, b: {c: 2}};
+const source1 = {b: {d: 3}, e: 4 };
+const source2 = {a: 5, b: {c: 6}};
+
+const merged = objectDeepMerge(target, source1, source2);
+
+console.log(merged); // {a: 5, b: {c: 6, d: 3}, e: 4}
+```