@twin.org/core 0.0.1-next.55 → 0.0.1-next.57

package/dist/cjs/index.cjs

@@ -1494,6 +1494,49 @@ class ValidationError extends BaseError {
     }
 }
 
+/**
+ * Class to help with arrays.
+ */
+class ArrayHelper {
+    /**
+     * Do the two arrays match.
+     * @param arr1 The first array.
+     * @param arr2 The second array.
+     * @returns True if both arrays are empty of have the same values.
+     */
+    static matches(arr1, arr2) {
+        if (Is.empty(arr1) && Is.empty(arr2)) {
+            return true;
+        }
+        if (!((Is.array(arr1) && Is.array(arr2)) || (Is.typedArray(arr1) && Is.typedArray(arr2)))) {
+            return false;
+        }
+        if (arr1.length !== arr2.length) {
+            return false;
+        }
+        for (let i = 0; i < arr1.length; i++) {
+            if (arr1[i] !== arr2[i]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Convert an object or array to an array.
+     * @param value The object or array to convert.
+     * @returns The array.
+     */
+    static fromObjectOrArray(value) {
+        if (Is.empty(value)) {
+            return undefined;
+        }
+        if (Is.array(value)) {
+            return value;
+        }
+        return [value];
+    }
+}
+
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 /**
@@ -1776,6 +1819,50 @@ class Guards {
             throw new GuardError(source, "guard.arrayOneOf", property, value, options.join(", "));
         }
     }
+    /**
+     * Does the array start with the specified data.
+     * @param source The source of the error.
+     * @param property The name of the property.
+     * @param value The value to test.
+     * @param startValues The values that must start the array.
+     * @throws GuardError If the value does not match the assertion.
+     */
+    static arrayStartsWith(source, property, value, startValues) {
+        if (!Is.arrayValue(value)) {
+            throw new GuardError(source, "guard.array", property, value);
+        }
+        const startValuesArray = ArrayHelper.fromObjectOrArray(startValues);
+        if (!Is.arrayValue(startValuesArray)) {
+            throw new GuardError(source, "guard.array", property, startValuesArray);
+        }
+        for (let i = 0; i < startValuesArray.length; i++) {
+            if (value[i] !== startValuesArray[i]) {
+                throw new GuardError(source, "guard.arrayStartsWith", property, value, startValuesArray.join(", "));
+            }
+        }
+    }
+    /**
+     * Does the array end with the specified data.
+     * @param source The source of the error.
+     * @param property The name of the property.
+     * @param value The value to test.
+     * @param endValues The values that must end the array.
+     * @throws GuardError If the value does not match the assertion.
+     */
+    static arrayEndsWith(source, property, value, endValues) {
+        if (!Is.arrayValue(value)) {
+            throw new GuardError(source, "guard.array", property, value);
+        }
+        const endValuesArray = ArrayHelper.fromObjectOrArray(endValues);
+        if (!Is.arrayValue(endValuesArray)) {
+            throw new GuardError(source, "guard.array", property, endValuesArray);
+        }
+        for (let i = 0; i < endValuesArray.length; i++) {
+            if (value[value.length - i - 1] !== endValuesArray[endValuesArray.length - i - 1]) {
+                throw new GuardError(source, "guard.arrayEndsWith", property, value, endValuesArray.join(", "));
+            }
+        }
+    }
     /**
      * Is the property a Uint8Array.
      * @param source The source of the error.
@@ -2120,37 +2207,6 @@ class Factory {
 // eslint-disable-next-line @typescript-eslint/naming-convention
 const ComponentFactory = Factory.createFactory("component");
 
-// Copyright 2024 IOTA Stiftung.
-// SPDX-License-Identifier: Apache-2.0.
-/**
- * Class to help with arrays.
- */
-class ArrayHelper {
-    /**
-     * Do the two arrays match.
-     * @param arr1 The first array.
-     * @param arr2 The second array.
-     * @returns True if both arrays are empty of have the same values.
-     */
-    static matches(arr1, arr2) {
-        if (Is.empty(arr1) && Is.empty(arr2)) {
-            return true;
-        }
-        if (!((Is.array(arr1) && Is.array(arr2)) || (Is.typedArray(arr1) && Is.typedArray(arr2)))) {
-            return false;
-        }
-        if (arr1.length !== arr2.length) {
-            return false;
-        }
-        for (let i = 0; i < arr1.length; i++) {
-            if (arr1[i] !== arr2[i]) {
-                return false;
-            }
-        }
-        return true;
-    }
-}
-
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 /* eslint-disable no-bitwise */

package/dist/esm/index.mjs

@@ -1492,6 +1492,49 @@ class ValidationError extends BaseError {
     }
 }
 
+/**
+ * Class to help with arrays.
+ */
+class ArrayHelper {
+    /**
+     * Do the two arrays match.
+     * @param arr1 The first array.
+     * @param arr2 The second array.
+     * @returns True if both arrays are empty of have the same values.
+     */
+    static matches(arr1, arr2) {
+        if (Is.empty(arr1) && Is.empty(arr2)) {
+            return true;
+        }
+        if (!((Is.array(arr1) && Is.array(arr2)) || (Is.typedArray(arr1) && Is.typedArray(arr2)))) {
+            return false;
+        }
+        if (arr1.length !== arr2.length) {
+            return false;
+        }
+        for (let i = 0; i < arr1.length; i++) {
+            if (arr1[i] !== arr2[i]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Convert an object or array to an array.
+     * @param value The object or array to convert.
+     * @returns The array.
+     */
+    static fromObjectOrArray(value) {
+        if (Is.empty(value)) {
+            return undefined;
+        }
+        if (Is.array(value)) {
+            return value;
+        }
+        return [value];
+    }
+}
+
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 /**
@@ -1774,6 +1817,50 @@ class Guards {
             throw new GuardError(source, "guard.arrayOneOf", property, value, options.join(", "));
         }
     }
+    /**
+     * Does the array start with the specified data.
+     * @param source The source of the error.
+     * @param property The name of the property.
+     * @param value The value to test.
+     * @param startValues The values that must start the array.
+     * @throws GuardError If the value does not match the assertion.
+     */
+    static arrayStartsWith(source, property, value, startValues) {
+        if (!Is.arrayValue(value)) {
+            throw new GuardError(source, "guard.array", property, value);
+        }
+        const startValuesArray = ArrayHelper.fromObjectOrArray(startValues);
+        if (!Is.arrayValue(startValuesArray)) {
+            throw new GuardError(source, "guard.array", property, startValuesArray);
+        }
+        for (let i = 0; i < startValuesArray.length; i++) {
+            if (value[i] !== startValuesArray[i]) {
+                throw new GuardError(source, "guard.arrayStartsWith", property, value, startValuesArray.join(", "));
+            }
+        }
+    }
+    /**
+     * Does the array end with the specified data.
+     * @param source The source of the error.
+     * @param property The name of the property.
+     * @param value The value to test.
+     * @param endValues The values that must end the array.
+     * @throws GuardError If the value does not match the assertion.
+     */
+    static arrayEndsWith(source, property, value, endValues) {
+        if (!Is.arrayValue(value)) {
+            throw new GuardError(source, "guard.array", property, value);
+        }
+        const endValuesArray = ArrayHelper.fromObjectOrArray(endValues);
+        if (!Is.arrayValue(endValuesArray)) {
+            throw new GuardError(source, "guard.array", property, endValuesArray);
+        }
+        for (let i = 0; i < endValuesArray.length; i++) {
+            if (value[value.length - i - 1] !== endValuesArray[endValuesArray.length - i - 1]) {
+                throw new GuardError(source, "guard.arrayEndsWith", property, value, endValuesArray.join(", "));
+            }
+        }
+    }
     /**
      * Is the property a Uint8Array.
      * @param source The source of the error.
@@ -2118,37 +2205,6 @@ class Factory {
 // eslint-disable-next-line @typescript-eslint/naming-convention
 const ComponentFactory = Factory.createFactory("component");
 
-// Copyright 2024 IOTA Stiftung.
-// SPDX-License-Identifier: Apache-2.0.
-/**
- * Class to help with arrays.
- */
-class ArrayHelper {
-    /**
-     * Do the two arrays match.
-     * @param arr1 The first array.
-     * @param arr2 The second array.
-     * @returns True if both arrays are empty of have the same values.
-     */
-    static matches(arr1, arr2) {
-        if (Is.empty(arr1) && Is.empty(arr2)) {
-            return true;
-        }
-        if (!((Is.array(arr1) && Is.array(arr2)) || (Is.typedArray(arr1) && Is.typedArray(arr2)))) {
-            return false;
-        }
-        if (arr1.length !== arr2.length) {
-            return false;
-        }
-        for (let i = 0; i < arr1.length; i++) {
-            if (arr1[i] !== arr2[i]) {
-                return false;
-            }
-        }
-        return true;
-    }
-}
-
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 /* eslint-disable no-bitwise */

package/dist/types/helpers/arrayHelper.d.ts

@@ -1,3 +1,4 @@
+import type { ObjectOrArray } from "../models/objectOrArray";
 /**
  * Class to help with arrays.
  */
@@ -9,4 +10,16 @@ export declare class ArrayHelper {
      * @returns True if both arrays are empty of have the same values.
      */
     static matches(arr1: unknown, arr2: unknown): boolean;
+    /**
+     * Convert an object or array to an array.
+     * @param value The object or array to convert.
+     * @returns The array.
+     */
+    static fromObjectOrArray<T = unknown>(value: undefined): undefined;
+    /**
+     * Convert an object or array to an array.
+     * @param value The object or array to convert.
+     * @returns The array.
+     */
+    static fromObjectOrArray<T = unknown>(value: ObjectOrArray<T>): T[];
 }

package/dist/types/index.d.ts

@@ -38,6 +38,7 @@ export * from "./models/ILocalesIndex";
 export * from "./models/IPatchOperation";
 export * from "./models/IUrlParts";
 export * from "./models/IValidationFailure";
+export * from "./models/objectOrArray";
 export * from "./types/bitString";
 export * from "./types/url";
 export * from "./types/urn";

package/dist/types/models/objectOrArray.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Object or array data type
+ */
+export type ObjectOrArray<T = unknown> = T | T[];

package/dist/types/utils/guards.d.ts

@@ -1,3 +1,4 @@
+import type { ObjectOrArray } from "../models/objectOrArray";
 /**
  * Class to handle guard operations for parameters.
  */
@@ -178,6 +179,24 @@ export declare class Guards {
      * @throws GuardError If the value does not match the assertion.
      */
     static arrayOneOf<T>(source: string, property: string, value: T, options: T[]): asserts value is T;
+    /**
+     * Does the array start with the specified data.
+     * @param source The source of the error.
+     * @param property The name of the property.
+     * @param value The value to test.
+     * @param startValues The values that must start the array.
+     * @throws GuardError If the value does not match the assertion.
+     */
+    static arrayStartsWith<T>(source: string, property: string, value: unknown, startValues: ObjectOrArray<T>): asserts value is T[];
+    /**
+     * Does the array end with the specified data.
+     * @param source The source of the error.
+     * @param property The name of the property.
+     * @param value The value to test.
+     * @param endValues The values that must end the array.
+     * @throws GuardError If the value does not match the assertion.
+     */
+    static arrayEndsWith<T>(source: string, property: string, value: unknown, endValues: ObjectOrArray<T>): asserts value is T[];
     /**
      * Is the property a Uint8Array.
      * @param source The source of the error.

package/docs/changelog.md

@@ -1,5 +1,19 @@
 # @twin.org/core - Changelog
 
+## [0.0.1-next.57](https://github.com/twinfoundation/framework/compare/core-v0.0.1-next.56...core-v0.0.1-next.57) (2025-06-10)
+
+
+### Features
+
+* add guards arrayEndsWith and arrayStartsWith ([95d875e](https://github.com/twinfoundation/framework/commit/95d875ec8ccb4713c145fdde941d4cfedcec2ed3))
+
+## [0.0.1-next.56](https://github.com/twinfoundation/framework/compare/core-v0.0.1-next.55...core-v0.0.1-next.56) (2025-05-08)
+
+
+### Features
+
+* add ObjectOrArray and ArrayHelper methods ([0ac9077](https://github.com/twinfoundation/framework/commit/0ac907764d64b38ad1b04b0e9c3027055b527559))
+
 ## [0.0.1-next.55](https://github.com/twinfoundation/framework/compare/core-v0.0.1-next.54...core-v0.0.1-next.55) (2025-05-07)
 
 

package/docs/reference/classes/ArrayHelper.md

@@ -39,3 +39,73 @@ The second array.
 `boolean`
 
 True if both arrays are empty of have the same values.
+
+***
+
+### fromObjectOrArray()
+
+Convert an object or array to an array.
+
+#### Param
+
+The object or array to convert.
+
+#### Call Signature
+
+> `static` **fromObjectOrArray**\<`T`\>(`value`): `undefined`
+
+Convert an object or array to an array.
+
+##### Type Parameters
+
+###### T
+
+`T` = `unknown`
+
+##### Parameters
+
+###### value
+
+`undefined`
+
+The object or array to convert.
+
+##### Returns
+
+`undefined`
+
+The array.
+
+##### Param
+
+The object or array to convert.
+
+#### Call Signature
+
+> `static` **fromObjectOrArray**\<`T`\>(`value`): `T`[]
+
+Convert an object or array to an array.
+
+##### Type Parameters
+
+###### T
+
+`T` = `unknown`
+
+##### Parameters
+
+###### value
+
+[`ObjectOrArray`](../type-aliases/ObjectOrArray.md)\<`T`\>
+
+The object or array to convert.
+
+##### Returns
+
+`T`[]
+
+The array.
+
+##### Param
+
+The object or array to convert.

package/docs/reference/classes/Guards.md

@@ -824,6 +824,102 @@ GuardError If the value does not match the assertion.
 
 ***
 
+### arrayStartsWith()
+
+> `static` **arrayStartsWith**\<`T`\>(`source`, `property`, `value`, `startValues`): `asserts value is T[]`
+
+Does the array start with the specified data.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### source
+
+`string`
+
+The source of the error.
+
+##### property
+
+`string`
+
+The name of the property.
+
+##### value
+
+`unknown`
+
+The value to test.
+
+##### startValues
+
+[`ObjectOrArray`](../type-aliases/ObjectOrArray.md)\<`T`\>
+
+The values that must start the array.
+
+#### Returns
+
+`asserts value is T[]`
+
+#### Throws
+
+GuardError If the value does not match the assertion.
+
+***
+
+### arrayEndsWith()
+
+> `static` **arrayEndsWith**\<`T`\>(`source`, `property`, `value`, `endValues`): `asserts value is T[]`
+
+Does the array end with the specified data.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### source
+
+`string`
+
+The source of the error.
+
+##### property
+
+`string`
+
+The name of the property.
+
+##### value
+
+`unknown`
+
+The value to test.
+
+##### endValues
+
+[`ObjectOrArray`](../type-aliases/ObjectOrArray.md)\<`T`\>
+
+The values that must end the array.
+
+#### Returns
+
+`asserts value is T[]`
+
+#### Throws
+
+GuardError If the value does not match the assertion.
+
+***
+
 ### uint8Array()
 
 > `static` **uint8Array**(`source`, `property`, `value`): `asserts value is Uint8Array<ArrayBufferLike>`

package/docs/reference/classes/Is.md

@@ -708,7 +708,7 @@ True if the value is a Uint8Array.
 
 ### typedArray()
 
-> `static` **typedArray**(`value`): value is Int8Array\<ArrayBufferLike\> \| Uint8Array\<ArrayBufferLike\> \| Int16Array\<ArrayBufferLike\> \| Uint16Array\<ArrayBufferLike\> \| Int32Array\<ArrayBufferLike\> \| Uint32Array\<ArrayBufferLike\> \| Float32Array\<ArrayBufferLike\> \| Float64Array\<ArrayBufferLike\>
+> `static` **typedArray**(`value`): value is Uint8Array\<ArrayBufferLike\> \| Int8Array\<ArrayBufferLike\> \| Uint16Array\<ArrayBufferLike\> \| Int16Array\<ArrayBufferLike\> \| Uint32Array\<ArrayBufferLike\> \| Int32Array\<ArrayBufferLike\> \| Float32Array\<ArrayBufferLike\> \| Float64Array\<ArrayBufferLike\>
 
 Is the value a TypedArray.
 
@@ -722,7 +722,7 @@ The value to test.
 
 #### Returns
 
-value is Int8Array\<ArrayBufferLike\> \| Uint8Array\<ArrayBufferLike\> \| Int16Array\<ArrayBufferLike\> \| Uint16Array\<ArrayBufferLike\> \| Int32Array\<ArrayBufferLike\> \| Uint32Array\<ArrayBufferLike\> \| Float32Array\<ArrayBufferLike\> \| Float64Array\<ArrayBufferLike\>
+value is Uint8Array\<ArrayBufferLike\> \| Int8Array\<ArrayBufferLike\> \| Uint16Array\<ArrayBufferLike\> \| Int16Array\<ArrayBufferLike\> \| Uint32Array\<ArrayBufferLike\> \| Int32Array\<ArrayBufferLike\> \| Float32Array\<ArrayBufferLike\> \| Float64Array\<ArrayBufferLike\>
 
 True if the value is a TypedArray.
 

package/docs/reference/index.md

@@ -59,6 +59,7 @@
 
 - [CoerceType](type-aliases/CoerceType.md)
 - [CompressionType](type-aliases/CompressionType.md)
+- [ObjectOrArray](type-aliases/ObjectOrArray.md)
 
 ## Variables
 

package/docs/reference/interfaces/IPatchOperation.md

@@ -6,7 +6,7 @@ Interface describing a patch operation to add a property.
 
 ### op
 
-> **op**: `"replace"` \| `"add"` \| `"remove"` \| `"copy"` \| `"move"` \| `"test"`
+> **op**: `"add"` \| `"remove"` \| `"replace"` \| `"move"` \| `"copy"` \| `"test"`
 
 The operation that was performed on the item.
 

package/docs/reference/type-aliases/ObjectOrArray.md

@@ -0,0 +1,11 @@
+# Type Alias: ObjectOrArray\<T\>
+
+> **ObjectOrArray**\<`T`\> = `T` \| `T`[]
+
+Object or array data type
+
+## Type Parameters
+
+### T
+
+`T` = `unknown`

package/locales/en.json

@@ -65,6 +65,8 @@
 			"array": "Property \"{property}\" must be an array, it is \"{value}\"",
 			"arrayValue": "Property \"{property}\" must be an array with at least one item",
 			"arrayOneOf": "Property \"{property}\" must be one of [{options}], it is \"{value}\"",
+			"arrayStartsWith": "Property \"{property}\" must be an array starting with [{startValues}], it is \"{value}\"",
+			"arrayEndsWith": "Property \"{property}\" must be an array ending with [{endValues}], it is \"{value}\"",
 			"uint8Array": "Property \"{property}\" must be a Uint8Array, it is \"{value}\"",
 			"function": "Property \"{property}\" must be a function, it is \"{value}\"",
 			"urn": "Property \"{property}\" must be a Urn formatted string, it is \"{value}\"",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/core",
-	"version": "0.0.1-next.55",
+	"version": "0.0.1-next.57",
 	"description": "Helper methods/classes for data type checking/validation/guarding/error handling",
 	"repository": {
 		"type": "git",