@twin.org/core 0.0.1 → 0.0.2-next.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/dist/cjs/index.cjs +915 -849
  2. package/dist/esm/index.mjs +915 -849
  3. package/dist/types/errors/alreadyExistsError.d.ts +2 -2
  4. package/dist/types/errors/baseError.d.ts +23 -4
  5. package/dist/types/errors/conflictError.d.ts +2 -2
  6. package/dist/types/errors/generalError.d.ts +2 -2
  7. package/dist/types/errors/notFoundError.d.ts +2 -2
  8. package/dist/types/errors/notSupportedError.d.ts +2 -2
  9. package/dist/types/errors/unauthorizedError.d.ts +2 -2
  10. package/dist/types/errors/unprocessableError.d.ts +2 -2
  11. package/dist/types/factories/factory.d.ts +1 -1
  12. package/dist/types/helpers/errorHelper.d.ts +3 -3
  13. package/dist/types/models/IComponent.d.ts +6 -15
  14. package/dist/types/models/IError.d.ts +2 -2
  15. package/dist/types/utils/is.d.ts +6 -0
  16. package/docs/changelog.md +229 -0
  17. package/docs/reference/classes/AlreadyExistsError.md +91 -7
  18. package/docs/reference/classes/ArrayHelper.md +0 -8
  19. package/docs/reference/classes/BaseError.md +83 -7
  20. package/docs/reference/classes/ConflictError.md +91 -7
  21. package/docs/reference/classes/EnvHelper.md +1 -1
  22. package/docs/reference/classes/ErrorHelper.md +3 -3
  23. package/docs/reference/classes/Factory.md +2 -2
  24. package/docs/reference/classes/GeneralError.md +91 -7
  25. package/docs/reference/classes/GuardError.md +88 -4
  26. package/docs/reference/classes/Guards.md +2 -2
  27. package/docs/reference/classes/I18n.md +2 -2
  28. package/docs/reference/classes/Is.md +30 -2
  29. package/docs/reference/classes/NotFoundError.md +91 -7
  30. package/docs/reference/classes/NotImplementedError.md +88 -4
  31. package/docs/reference/classes/NotSupportedError.md +91 -7
  32. package/docs/reference/classes/UnauthorizedError.md +91 -7
  33. package/docs/reference/classes/UnprocessableError.md +91 -7
  34. package/docs/reference/classes/Validation.md +1 -1
  35. package/docs/reference/classes/ValidationError.md +88 -4
  36. package/docs/reference/interfaces/IComponent.md +9 -21
  37. package/docs/reference/interfaces/IError.md +3 -3
  38. package/docs/reference/variables/CoerceType.md +1 -1
  39. package/docs/reference/variables/CompressionType.md +1 -1
  40. package/package.json +2 -2
@@ -374,6 +374,19 @@ class Is {
374
374
  static regexp(value) {
375
375
  return value instanceof RegExp;
376
376
  }
377
+ /**
378
+ * Is the provided object a class constructor.
379
+ * @param obj The object to check.
380
+ * @returns True if the object is a class, false otherwise.
381
+ */
382
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
383
+ static class(obj) {
384
+ if (typeof obj !== "function") {
385
+ return false;
386
+ }
387
+ const str = Function.prototype.toString.call(obj);
388
+ return /^class\s/.test(str);
389
+ }
377
390
  }
378
391
 
379
392
  // Copyright 2024 IOTA Stiftung.
@@ -631,31 +644,33 @@ class BaseError extends Error {
631
644
  */
632
645
  properties;
633
646
  /**
634
- * The inner error if there was one.
647
+ * The cause of the error.
635
648
  */
636
- inner;
649
+ cause;
637
650
  /**
638
651
  * Create a new instance of BaseError.
639
652
  * @param name The name of the error.
640
653
  * @param source The source of the error.
641
654
  * @param message The message as a code.
642
655
  * @param properties Any additional information for the error.
643
- * @param inner The inner error if we have wrapped another error.
656
+ * @param cause The cause of error if we have wrapped another error.
644
657
  */
645
- constructor(name, source, message, properties, inner) {
658
+ constructor(name, source, message, properties, cause) {
646
659
  super(message);
647
660
  this.name = name;
648
661
  this.source = source;
662
+ this.cause = Is.notEmpty(cause) ? BaseError.fromError(cause).toJsonObject(true) : undefined;
663
+ this.properties = properties;
649
664
  // If the message is camel case but has no namespace then prefix it
650
- // with the source name in camel case
665
+ // with the source name in camel case.
651
666
  if (Is.stringValue(source) &&
652
667
  Is.stringValue(message) &&
653
668
  !message.includes(".") &&
669
+ // This comparison checks that it is most likely a camel case name
670
+ // and not a free text error with a dot in it
654
671
  StringHelper.camelCase(message) === message) {
655
672
  this.message = `${StringHelper.camelCase(source)}.${message}`;
656
673
  }
657
- this.properties = properties;
658
- this.inner = inner ? BaseError.fromError(inner).toJsonObject() : undefined;
659
674
  }
660
675
  /**
661
676
  * Construct an error from an existing one.
@@ -667,7 +682,7 @@ class BaseError extends Error {
667
682
  let message;
668
683
  let source;
669
684
  let properties;
670
- let inner;
685
+ let cause;
671
686
  let stack;
672
687
  if (Is.object(err) && Is.stringValue(err.error)) {
673
688
  message = err.error;
@@ -685,8 +700,12 @@ class BaseError extends Error {
685
700
  if (Is.notEmpty(err.properties)) {
686
701
  properties = err.properties;
687
702
  }
688
- if (Is.notEmpty(err.inner)) {
689
- inner = err.inner;
703
+ if (BaseError.isAggregateError(err)) {
704
+ properties ??= {};
705
+ properties.errors = err.errors;
706
+ }
707
+ if (Is.notEmpty(err.cause)) {
708
+ cause = err.cause;
690
709
  }
691
710
  if (Is.notEmpty(err.stack)) {
692
711
  stack = err.stack;
@@ -698,7 +717,7 @@ class BaseError extends Error {
698
717
  else {
699
718
  message = JSON.stringify(err);
700
719
  }
701
- const baseError = new BaseError(name, source ?? "", message ?? "", properties, inner);
720
+ const baseError = new BaseError(name, source ?? "", message ?? "", properties, cause);
702
721
  baseError.stack = stack;
703
722
  return baseError;
704
723
  }
@@ -711,10 +730,10 @@ class BaseError extends Error {
711
730
  const flattened = [];
712
731
  let e = BaseError.fromError(err).toJsonObject(true);
713
732
  while (e) {
714
- const inner = e.inner;
715
- e.inner = undefined;
733
+ const cause = e.cause;
734
+ e.cause = undefined;
716
735
  flattened.push(e);
717
- e = inner;
736
+ e = cause;
718
737
  }
719
738
  return flattened;
720
739
  }
@@ -729,8 +748,8 @@ class BaseError extends Error {
729
748
  first = errors[0];
730
749
  let current = first;
731
750
  for (let i = 1; i < errors.length; i++) {
732
- current.inner = errors[i];
733
- current = current.inner;
751
+ current.cause = errors[i];
752
+ current = current.cause;
734
753
  }
735
754
  }
736
755
  return first;
@@ -803,6 +822,37 @@ class BaseError extends Error {
803
822
  static someErrorCode(error, code) {
804
823
  return BaseError.flatten(error).some(e => BaseError.isErrorCode(e, code));
805
824
  }
825
+ /**
826
+ * Is the error empty, i.e. does it have no message, source, properties, or cause?
827
+ * @param err The error to check for being empty.
828
+ * @returns True if the error is empty.
829
+ */
830
+ static isEmpty(err) {
831
+ return (!Is.stringValue(err.message) &&
832
+ !Is.stringValue(err.source) &&
833
+ !Is.objectValue(err.properties) &&
834
+ Is.empty(err.cause));
835
+ }
836
+ /**
837
+ * Is the error an aggregate error.
838
+ * @param err The error to check for being an aggregate error.
839
+ * @returns True if the error is an aggregate error.
840
+ */
841
+ static isAggregateError(err) {
842
+ return err instanceof AggregateError;
843
+ }
844
+ /**
845
+ * Convert the aggregate error to an array of errors.
846
+ * @param err The error to convert.
847
+ * @param includeStackTrace Whether to include the error stack in the model, defaults to false.
848
+ * @returns The array of errors.
849
+ */
850
+ static fromAggregate(err, includeStackTrace) {
851
+ if (BaseError.isAggregateError(err)) {
852
+ return err.errors.map(e => BaseError.fromError(e).toJsonObject(includeStackTrace));
853
+ }
854
+ return [BaseError.fromError(err).toJsonObject(includeStackTrace)];
855
+ }
806
856
  /**
807
857
  * Serialize the error to the error model.
808
858
  * @param includeStackTrace Whether to include the error stack in the model, defaults to false.
@@ -825,8 +875,8 @@ class BaseError extends Error {
825
875
  if ((includeStackTrace ?? false) && Is.stringValue(this.stack)) {
826
876
  err.stack = this.stack;
827
877
  }
828
- if (Is.notEmpty(this.inner)) {
829
- err.inner = BaseError.fromError(this.inner).toJsonObject(includeStackTrace);
878
+ if (Is.notEmpty(this.cause)) {
879
+ err.cause = BaseError.fromError(this.cause).toJsonObject(includeStackTrace);
830
880
  }
831
881
  return err;
832
882
  }
@@ -845,1062 +895,1073 @@ class GeneralError extends BaseError {
845
895
  * @param source The source of the error.
846
896
  * @param message The message as a code.
847
897
  * @param properties Any additional information for the error.
848
- * @param inner The inner error if we have wrapped another error.
898
+ * @param cause The cause of the error if we have wrapped another error.
849
899
  */
850
- constructor(source, message, properties, inner) {
851
- super(GeneralError.CLASS_NAME, source, message, properties, inner);
900
+ constructor(source, message, properties, cause) {
901
+ super(GeneralError.CLASS_NAME, source, message, properties, cause);
852
902
  }
853
903
  }
854
904
 
855
- // Copyright 2024 IOTA Stiftung.
856
- // SPDX-License-Identifier: Apache-2.0.
857
- /* eslint-disable no-bitwise */
858
905
  /**
859
- * Class to help with base63 Encoding/Decoding.
906
+ * Class to handle errors which are triggered by data guards.
860
907
  */
861
- class Base32 {
908
+ class GuardError extends BaseError {
862
909
  /**
863
910
  * Runtime name for the class.
864
- * @internal
865
- */
866
- static _CLASS_NAME = "Base32";
867
- /**
868
- * Alphabet table for encoding.
869
- * @internal
870
- */
871
- static _ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
872
- /**
873
- * Convert the base 32 string to a byte array.
874
- * @param base32 The base32 string to convert.
875
- * @returns The byte array.
876
- * @throws If the input string contains a character not in the Base32 alphabet.
877
911
  */
878
- static decode(base32) {
879
- let bits = 0;
880
- let value = 0;
881
- base32 = base32.replace(/=+$/, "");
882
- let index = 0;
883
- const output = new Uint8Array(Math.trunc((base32.length * 5) / 8));
884
- for (let i = 0; i < base32.length; i++) {
885
- const idx = Base32._ALPHABET.indexOf(base32[i]);
886
- if (idx === -1) {
887
- throw new GeneralError(Base32._CLASS_NAME, "invalidCharacter", {
888
- invalidCharacter: base32[i]
889
- });
890
- }
891
- value = (value << 5) | idx;
892
- bits += 5;
893
- if (bits >= 8) {
894
- output[index++] = (value >>> (bits - 8)) & 255;
895
- bits -= 8;
896
- }
897
- }
898
- return output;
899
- }
912
+ static CLASS_NAME = "GuardError";
900
913
  /**
901
- * Convert a byte array to base 32.
902
- * @param bytes The byte array to convert.
903
- * @returns The data as base32 string.
914
+ * Create a new instance of GuardError.
915
+ * @param source The source of the error.
916
+ * @param message The message as a code.
917
+ * @param propertyName The property which triggered the guard error for the item.
918
+ * @param propertyValue The property value which triggered the guard error for the item.
919
+ * @param propertyOptions The property options which might be allowed.
904
920
  */
905
- static encode(bytes) {
906
- let bits = 0;
907
- let value = 0;
908
- let output = "";
909
- for (let i = 0; i < bytes.byteLength; i++) {
910
- value = (value << 8) | bytes[i];
911
- bits += 8;
912
- while (bits >= 5) {
913
- output += Base32._ALPHABET[(value >>> (bits - 5)) & 31];
914
- bits -= 5;
915
- }
916
- }
917
- if (bits > 0) {
918
- output += Base32._ALPHABET[(value << (5 - bits)) & 31];
919
- }
920
- while (output.length % 8 !== 0) {
921
- output += "=";
922
- }
923
- return output;
921
+ constructor(source, message, propertyName, propertyValue, propertyOptions) {
922
+ super(GuardError.CLASS_NAME, source, message, {
923
+ property: propertyName ?? "property",
924
+ value: Is.undefined(propertyValue) ? "undefined" : propertyValue,
925
+ options: propertyOptions
926
+ });
924
927
  }
925
928
  }
926
929
 
927
930
  /**
928
- * Class to help with base58 Encoding/Decoding.
931
+ * Class to help with arrays.
929
932
  */
930
- class Base58 {
931
- /**
932
- * Runtime name for the class.
933
- * @internal
934
- */
935
- static _CLASS_NAME = "Base58";
936
- /**
937
- * Alphabet table for encoding.
938
- * @internal
939
- */
940
- static _ALPHABET =
941
- // cspell:disable-next-line
942
- "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
943
- /**
944
- * Reverse map for decoding.
945
- * @internal
946
- */
947
- static _ALPHABET_REVERSE = [
948
- -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
949
- -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
950
- -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, -1, -1, -1, -1, -1, -1, -1, 9, 10, 11, 12, 13, 14, 15, 16, -1,
951
- 17, 18, 19, 20, 21, -1, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, -1, -1, -1, -1, -1, -1, 33,
952
- 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, -1, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56,
953
- 57, -1, -1, -1, -1, -1
954
- ];
933
+ class ArrayHelper {
955
934
  /**
956
- * Convert the base 58 string to a byte array.
957
- * @param base58 The base58 string to convert.
958
- * @returns The byte array.
959
- * @throws If the input string contains a character not in the Base58 alphabet.
935
+ * Do the two arrays match.
936
+ * @param arr1 The first array.
937
+ * @param arr2 The second array.
938
+ * @returns True if both arrays are empty of have the same values.
960
939
  */
961
- static decode(base58) {
962
- let zeroes = 0;
963
- for (let i = 0; i < base58.length; i++) {
964
- if (base58[i] !== "1") {
965
- break;
966
- }
967
- zeroes += 1;
940
+ static matches(arr1, arr2) {
941
+ if (Is.empty(arr1) && Is.empty(arr2)) {
942
+ return true;
968
943
  }
969
- const size = Math.trunc((base58.length * 733) / 1000) + 1;
970
- const b256 = new Uint8Array(size).fill(0);
971
- let length = 0;
972
- for (let i = zeroes; i < base58.length; i++) {
973
- const ch = base58.charCodeAt(i);
974
- if (ch & 0xff80) {
975
- throw new GeneralError(Base58._CLASS_NAME, "invalidCharacter", { invalidCharacter: ch });
976
- }
977
- const val = Base58._ALPHABET_REVERSE[ch];
978
- if (val === -1) {
979
- throw new GeneralError(Base58._CLASS_NAME, "invalidCharacter", { invalidCharacter: ch });
980
- }
981
- let carry = val;
982
- let j = 0;
983
- for (let k = size - 1; k >= 0; k--, j++) {
984
- if (carry === 0 && j >= length) {
985
- break;
986
- }
987
- carry += b256[k] * 58;
988
- b256[k] = carry;
989
- carry >>>= 8;
990
- }
991
- length = j;
944
+ if (!((Is.array(arr1) && Is.array(arr2)) || (Is.typedArray(arr1) && Is.typedArray(arr2)))) {
945
+ return false;
992
946
  }
993
- const out = new Uint8Array(zeroes + length);
994
- let j;
995
- for (j = 0; j < zeroes; j++) {
996
- out[j] = 0;
947
+ if (arr1.length !== arr2.length) {
948
+ return false;
997
949
  }
998
- let i = size - length;
999
- while (i < size) {
1000
- out[j++] = b256[i++];
950
+ for (let i = 0; i < arr1.length; i++) {
951
+ if (arr1[i] !== arr2[i]) {
952
+ return false;
953
+ }
1001
954
  }
1002
- return out;
955
+ return true;
1003
956
  }
1004
957
  /**
1005
- * Convert a byte array to base 58.
1006
- * @param bytes The byte array to encode.
1007
- * @returns The data as base58 string.
958
+ * Convert an object or array to an array.
959
+ * @param value The object or array to convert.
960
+ * @returns The array.
1008
961
  */
1009
- static encode(bytes) {
1010
- let zeroes = 0;
1011
- for (let i = 0; i < bytes.length; i++) {
1012
- if (bytes[i] !== 0) {
1013
- break;
1014
- }
1015
- zeroes += 1;
1016
- }
1017
- const size = Math.trunc(((bytes.length - zeroes) * 138) / 100) + 1;
1018
- const b58 = new Uint8Array(size).fill(0);
1019
- let length = 0;
1020
- for (let i = zeroes; i < bytes.length; i++) {
1021
- let carry = bytes[i];
1022
- let j = 0;
1023
- for (let k = size - 1; k >= 0; k--, j++) {
1024
- if (carry === 0 && j >= length) {
1025
- break;
1026
- }
1027
- carry += b58[k] * 256;
1028
- b58[k] = carry % 58;
1029
- carry = Math.trunc(carry / 58);
1030
- }
1031
- length = j;
1032
- }
1033
- let i = size - length;
1034
- while (i < size && b58[i] === 0) {
1035
- i += 1;
1036
- }
1037
- let str = "";
1038
- for (let j = 0; j < zeroes; j++) {
1039
- str += "1";
962
+ static fromObjectOrArray(value) {
963
+ if (Is.empty(value)) {
964
+ return undefined;
1040
965
  }
1041
- while (i < size) {
1042
- str += Base58._ALPHABET[b58[i++]];
966
+ if (Is.array(value)) {
967
+ return value;
1043
968
  }
1044
- return str;
969
+ return [value];
1045
970
  }
1046
971
  }
1047
972
 
1048
973
  // Copyright 2024 IOTA Stiftung.
1049
974
  // SPDX-License-Identifier: Apache-2.0.
1050
- /* eslint-disable no-bitwise */
1051
- /* eslint-disable no-mixed-operators */
1052
975
  /**
1053
- * Class to help with base64 Encoding/Decoding.
1054
- * Sourced from https://github.com/beatgammit/base64-js.
976
+ * Class to handle guard operations for parameters.
1055
977
  */
1056
- class Base64 {
978
+ class Guards {
1057
979
  /**
1058
- * Runtime name for the class.
1059
- * @internal
980
+ * Is the property defined.
981
+ * @param source The source of the error.
982
+ * @param property The name of the property.
983
+ * @param value The value to test.
984
+ * @throws GuardError If the value does not match the assertion.
1060
985
  */
1061
- static _CLASS_NAME = "Base64";
986
+ static defined(source, property, value) {
987
+ if (Is.undefined(value)) {
988
+ throw new GuardError(source, "guard.undefined", property, value);
989
+ }
990
+ }
1062
991
  /**
1063
- * Alphabet table for encoding.
1064
- * @internal
992
+ * Is the property a string.
993
+ * @param source The source of the error.
994
+ * @param property The name of the property.
995
+ * @param value The value to test.
996
+ * @throws GuardError If the value does not match the assertion.
1065
997
  */
1066
- static _LOOKUP = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
998
+ static string(source, property, value) {
999
+ if (!Is.string(value)) {
1000
+ throw new GuardError(source, "guard.string", property, value);
1001
+ }
1002
+ }
1067
1003
  /**
1068
- * Alphabet table for decoding.
1069
- * @internal
1004
+ * Is the property a string with a value.
1005
+ * @param source The source of the error.
1006
+ * @param property The name of the property.
1007
+ * @param value The value to test.
1008
+ * @throws GuardError If the value does not match the assertion.
1070
1009
  */
1071
- static _REVERSE_LOOKUP = {
1072
- "43": 62,
1073
- "45": 62,
1074
- "47": 63,
1075
- "48": 52,
1076
- "49": 53,
1077
- "50": 54,
1078
- "51": 55,
1079
- "52": 56,
1080
- "53": 57,
1081
- "54": 58,
1082
- "55": 59,
1083
- "56": 60,
1084
- "57": 61,
1085
- "65": 0,
1086
- "66": 1,
1087
- "67": 2,
1088
- "68": 3,
1089
- "69": 4,
1090
- "70": 5,
1091
- "71": 6,
1092
- "72": 7,
1093
- "73": 8,
1094
- "74": 9,
1095
- "75": 10,
1096
- "76": 11,
1097
- "77": 12,
1098
- "78": 13,
1099
- "79": 14,
1100
- "80": 15,
1101
- "81": 16,
1102
- "82": 17,
1103
- "83": 18,
1104
- "84": 19,
1105
- "85": 20,
1106
- "86": 21,
1107
- "87": 22,
1108
- "88": 23,
1109
- "89": 24,
1110
- "90": 25,
1111
- "95": 63,
1112
- "97": 26,
1113
- "98": 27,
1114
- "99": 28,
1115
- "100": 29,
1116
- "101": 30,
1117
- "102": 31,
1118
- "103": 32,
1119
- "104": 33,
1120
- "105": 34,
1121
- "106": 35,
1122
- "107": 36,
1123
- "108": 37,
1124
- "109": 38,
1125
- "110": 39,
1126
- "111": 40,
1127
- "112": 41,
1128
- "113": 42,
1129
- "114": 43,
1130
- "115": 44,
1131
- "116": 45,
1132
- "117": 46,
1133
- "118": 47,
1134
- "119": 48,
1135
- "120": 49,
1136
- "121": 50,
1137
- "122": 51
1138
- };
1010
+ static stringValue(source, property, value) {
1011
+ if (!Is.string(value)) {
1012
+ throw new GuardError(source, "guard.string", property, value);
1013
+ }
1014
+ if (value.length === 0) {
1015
+ throw new GuardError(source, "guard.stringEmpty", property, value);
1016
+ }
1017
+ }
1139
1018
  /**
1140
- * Get the byte length of the data.
1141
- * @param base64 The base64 string.
1142
- * @returns The byte length of the data.
1019
+ * Is the property a JSON value.
1020
+ * @param source The source of the error.
1021
+ * @param property The name of the property.
1022
+ * @param value The value to test.
1023
+ * @throws GuardError If the value does not match the assertion.
1143
1024
  */
1144
- static byteLength(base64) {
1145
- const lens = Base64.getLengths(base64);
1146
- return Base64.calcByteLength(lens[0], lens[1]);
1025
+ static json(source, property, value) {
1026
+ if (!Is.json(value)) {
1027
+ throw new GuardError(source, "guard.stringJson", property, value);
1028
+ }
1147
1029
  }
1148
1030
  /**
1149
- * Convert the base 64 string to a byte array.
1150
- * @param base64 The base64 string to convert.
1151
- * @returns The byte array.
1031
+ * Is the property a base64 string.
1032
+ * @param source The source of the error.
1033
+ * @param property The name of the property.
1034
+ * @param value The value to test.
1035
+ * @throws GuardError If the value does not match the assertion.
1152
1036
  */
1153
- static decode(base64) {
1154
- let tmp;
1155
- const lens = Base64.getLengths(base64);
1156
- const validLen = lens[0];
1157
- const placeHoldersLen = lens[1];
1158
- const arr = new Uint8Array(Base64.calcByteLength(validLen, placeHoldersLen));
1159
- let curByte = 0;
1160
- // if there are placeholders, only get up to the last complete 4 chars
1161
- const len = placeHoldersLen > 0 ? validLen - 4 : validLen;
1162
- let i;
1163
- for (i = 0; i < len; i += 4) {
1164
- tmp =
1165
- (Base64._REVERSE_LOOKUP[base64.charCodeAt(i)] << 18) |
1166
- (Base64._REVERSE_LOOKUP[base64.charCodeAt(i + 1)] << 12) |
1167
- (Base64._REVERSE_LOOKUP[base64.charCodeAt(i + 2)] << 6) |
1168
- Base64._REVERSE_LOOKUP[base64.charCodeAt(i + 3)];
1169
- arr[curByte++] = (tmp >> 16) & 0xff;
1170
- arr[curByte++] = (tmp >> 8) & 0xff;
1171
- arr[curByte++] = tmp & 0xff;
1172
- }
1173
- if (placeHoldersLen === 2) {
1174
- tmp =
1175
- (Base64._REVERSE_LOOKUP[base64.charCodeAt(i)] << 2) |
1176
- (Base64._REVERSE_LOOKUP[base64.charCodeAt(i + 1)] >> 4);
1177
- arr[curByte++] = tmp & 0xff;
1037
+ static stringBase64(source, property, value) {
1038
+ if (!Is.stringBase64(value)) {
1039
+ throw new GuardError(source, "guard.base64", property, value);
1178
1040
  }
1179
- if (placeHoldersLen === 1) {
1180
- tmp =
1181
- (Base64._REVERSE_LOOKUP[base64.charCodeAt(i)] << 10) |
1182
- (Base64._REVERSE_LOOKUP[base64.charCodeAt(i + 1)] << 4) |
1183
- (Base64._REVERSE_LOOKUP[base64.charCodeAt(i + 2)] >> 2);
1184
- arr[curByte++] = (tmp >> 8) & 0xff;
1185
- arr[curByte++] = tmp & 0xff;
1041
+ }
1042
+ /**
1043
+ * Is the property a base64 url string.
1044
+ * @param source The source of the error.
1045
+ * @param property The name of the property.
1046
+ * @param value The value to test.
1047
+ * @throws GuardError If the value does not match the assertion.
1048
+ */
1049
+ static stringBase64Url(source, property, value) {
1050
+ if (!Is.stringBase64Url(value)) {
1051
+ throw new GuardError(source, "guard.base64Url", property, value);
1186
1052
  }
1187
- return arr;
1188
1053
  }
1189
1054
  /**
1190
- * Convert a byte array to base 64.
1191
- * @param bytes The byte array to convert.
1192
- * @returns The data as base64 string.
1055
+ * Is the property a base58 string.
1056
+ * @param source The source of the error.
1057
+ * @param property The name of the property.
1058
+ * @param value The value to test.
1059
+ * @throws GuardError If the value does not match the assertion.
1193
1060
  */
1194
- static encode(bytes) {
1195
- let tmp;
1196
- const len = bytes.length;
1197
- const extraBytes = len % 3; // if we have 1 byte left, pad 2 bytes
1198
- const parts = [];
1199
- const maxChunkLength = 16383; // must be multiple of 3
1200
- // go through the array every three bytes, we'll deal with trailing stuff later
1201
- for (let i = 0, len2 = len - extraBytes; i < len2; i += maxChunkLength) {
1202
- parts.push(Base64.encodeChunk(bytes, i, Math.min(i + maxChunkLength, len2)));
1061
+ static stringBase58(source, property, value) {
1062
+ if (!Is.stringBase58(value)) {
1063
+ throw new GuardError(source, "guard.base58", property, value);
1203
1064
  }
1204
- // pad the end with zeros, but make sure to not forget the extra bytes
1205
- if (extraBytes === 1) {
1206
- tmp = bytes[len - 1];
1207
- parts.push(`${Base64._LOOKUP[tmp >> 2] + Base64._LOOKUP[(tmp << 4) & 0x3f]}==`);
1065
+ }
1066
+ /**
1067
+ * Is the property a string with a hex value.
1068
+ * @param source The source of the error.
1069
+ * @param property The name of the property.
1070
+ * @param value The value to test.
1071
+ * @param allowPrefix Allow the hex to have the 0x prefix.
1072
+ * @throws GuardError If the value does not match the assertion.
1073
+ */
1074
+ static stringHex(source, property, value, allowPrefix = false) {
1075
+ Guards.stringValue(source, property, value);
1076
+ if (!HexHelper.isHex(value, allowPrefix)) {
1077
+ throw new GuardError(source, "guard.stringHex", property, value);
1208
1078
  }
1209
- else if (extraBytes === 2) {
1210
- tmp = (bytes[len - 2] << 8) + bytes[len - 1];
1211
- parts.push(`${Base64._LOOKUP[tmp >> 10] + Base64._LOOKUP[(tmp >> 4) & 0x3f] + Base64._LOOKUP[(tmp << 2) & 0x3f]}=`);
1079
+ }
1080
+ /**
1081
+ * Is the property a string with a hex value with fixed length.
1082
+ * @param source The source of the error.
1083
+ * @param property The name of the property.
1084
+ * @param value The value to test.
1085
+ * @param length The length of the string to match.
1086
+ * @param allowPrefix Allow the hex to have the 0x prefix.
1087
+ * @throws GuardError If the value does not match the assertion.
1088
+ */
1089
+ static stringHexLength(source, property, value, length, allowPrefix = false) {
1090
+ Guards.stringHex(source, property, value, allowPrefix);
1091
+ if (HexHelper.stripPrefix(value).length !== length) {
1092
+ throw new GuardError(source, "guard.stringHexLength", property, value.length, length.toString());
1212
1093
  }
1213
- return parts.join("");
1214
1094
  }
1215
1095
  /**
1216
- * Calculate the byte length.
1217
- * @param validLen The valid length.
1218
- * @param placeHoldersLen The placeholder length.
1219
- * @returns The length.
1220
- * @internal
1096
+ * Is the property a number.
1097
+ * @param source The source of the error.
1098
+ * @param property The name of the property.
1099
+ * @param value The value to test.
1100
+ * @throws GuardError If the value does not match the assertion.
1221
1101
  */
1222
- static calcByteLength(validLen, placeHoldersLen) {
1223
- return ((validLen + placeHoldersLen) * 3) / 4 - placeHoldersLen;
1102
+ static number(source, property, value) {
1103
+ if (!Is.number(value)) {
1104
+ throw new GuardError(source, "guard.number", property, value);
1105
+ }
1224
1106
  }
1225
1107
  /**
1226
- * Get the valid and placeholder lengths from a bas64 string.
1227
- * @param base64 The base64 string.
1228
- * @returns The lengths.
1229
- * @internal
1108
+ * Is the property an integer.
1109
+ * @param source The source of the error.
1110
+ * @param property The name of the property.
1111
+ * @param value The value to test.
1112
+ * @throws GuardError If the value does not match the assertion.
1230
1113
  */
1231
- static getLengths(base64) {
1232
- const len = base64.length;
1233
- if (len % 4 > 0) {
1234
- throw new GeneralError(Base64._CLASS_NAME, "length4Multiple", { value: len });
1114
+ static integer(source, property, value) {
1115
+ if (!Is.integer(value)) {
1116
+ throw new GuardError(source, "guard.integer", property, value);
1235
1117
  }
1236
- // Trim off extra bytes after placeholder bytes are found
1237
- // See: https://github.com/beatgammit/base64-js/issues/42
1238
- let validLen = base64.indexOf("=");
1239
- if (validLen === -1) {
1240
- validLen = len;
1118
+ }
1119
+ /**
1120
+ * Is the property a bigint.
1121
+ * @param source The source of the error.
1122
+ * @param property The name of the property.
1123
+ * @param value The value to test.
1124
+ * @throws GuardError If the value does not match the assertion.
1125
+ */
1126
+ static bigint(source, property, value) {
1127
+ if (!Is.bigint(value)) {
1128
+ throw new GuardError(source, "guard.bigint", property, value);
1241
1129
  }
1242
- const placeHoldersLen = validLen === len ? 0 : 4 - (validLen % 4);
1243
- return [validLen, placeHoldersLen];
1244
1130
  }
1245
1131
  /**
1246
- * Convert the triplet to base 64.
1247
- * @param num The number to convert.
1248
- * @returns The base64 encoding.
1249
- * @internal
1132
+ * Is the property a boolean.
1133
+ * @param source The source of the error.
1134
+ * @param property The name of the property.
1135
+ * @param value The value to test.
1136
+ * @throws GuardError If the value does not match the assertion.
1250
1137
  */
1251
- static tripletToBase64(num) {
1252
- return (Base64._LOOKUP[(num >> 18) & 0x3f] +
1253
- Base64._LOOKUP[(num >> 12) & 0x3f] +
1254
- Base64._LOOKUP[(num >> 6) & 0x3f] +
1255
- Base64._LOOKUP[num & 0x3f]);
1138
+ static boolean(source, property, value) {
1139
+ if (!Is.boolean(value)) {
1140
+ throw new GuardError(source, "guard.boolean", property, value);
1141
+ }
1256
1142
  }
1257
1143
  /**
1258
- * Encode a chunk.
1259
- * @param bytes The byte array.
1260
- * @param start The start index in the buffer.
1261
- * @param end The end index in the buffer.
1262
- * @returns The encoded chunk.
1263
- * @internal
1144
+ * Is the property a date.
1145
+ * @param source The source of the error.
1146
+ * @param property The name of the property.
1147
+ * @param value The value to test.
1148
+ * @throws GuardError If the value does not match the assertion.
1264
1149
  */
1265
- static encodeChunk(bytes, start, end) {
1266
- let tmp;
1267
- const output = [];
1268
- for (let i = start; i < end; i += 3) {
1269
- tmp = ((bytes[i] << 16) & 0xff0000) + ((bytes[i + 1] << 8) & 0xff00) + (bytes[i + 2] & 0xff);
1270
- output.push(Base64.tripletToBase64(tmp));
1150
+ static date(source, property, value) {
1151
+ if (!Is.date(value)) {
1152
+ throw new GuardError(source, "guard.date", property, value);
1271
1153
  }
1272
- return output.join("");
1273
1154
  }
1274
- }
1275
-
1276
- // Copyright 2024 IOTA Stiftung.
1277
- // SPDX-License-Identifier: Apache-2.0.
1278
- /**
1279
- * Class to help with base64 URL Encoding/Decoding.
1280
- * https://www.rfc-editor.org/rfc/rfc4648#section-5.
1281
- */
1282
- class Base64Url {
1283
1155
  /**
1284
- * Convert the base 64 string to a byte array.
1285
- * @param base64Url The base64 url string to convert.
1286
- * @returns The byte array.
1156
+ * Is the property a timestamp in milliseconds.
1157
+ * @param source The source of the error.
1158
+ * @param property The name of the property.
1159
+ * @param value The value to test.
1160
+ * @throws GuardError If the value does not match the assertion.
1287
1161
  */
1288
- static decode(base64Url) {
1289
- let base64 = base64Url;
1290
- // Base 64 url can have padding removed, so add it back if it is missing.
1291
- if (base64.length > 0 && !base64.endsWith("=")) {
1292
- const placeHoldersLen = 4 - (base64.length % 4);
1293
- if (placeHoldersLen > 0 && placeHoldersLen < 4) {
1294
- base64 = base64.padEnd(base64.length + placeHoldersLen, "=");
1295
- }
1162
+ static timestampMilliseconds(source, property, value) {
1163
+ if (!Is.timestampMilliseconds(value)) {
1164
+ throw new GuardError(source, "guard.timestampMilliseconds", property, value);
1296
1165
  }
1297
- base64 = base64.replace(/-/g, "+").replace(/_/g, "/");
1298
- return Base64.decode(base64);
1299
1166
  }
1300
1167
  /**
1301
- * Convert a byte array to base 64 url.
1302
- * @param bytes The byte array to convert.
1303
- * @returns The data as base64 url string.
1168
+ * Is the property a timestamp in seconds.
1169
+ * @param source The source of the error.
1170
+ * @param property The name of the property.
1171
+ * @param value The value to test.
1172
+ * @throws GuardError If the value does not match the assertion.
1304
1173
  */
1305
- static encode(bytes) {
1306
- const base64 = Base64.encode(bytes);
1307
- // Base 64 url can have padding removed, so remove it.
1308
- return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
1174
+ static timestampSeconds(source, property, value) {
1175
+ if (!Is.timestampSeconds(value)) {
1176
+ throw new GuardError(source, "guard.timestampSeconds", property, value);
1177
+ }
1309
1178
  }
1310
- }
1311
-
1312
- /**
1313
- * Class to handle errors which are triggered by data already existing.
1314
- */
1315
- class AlreadyExistsError extends BaseError {
1316
1179
  /**
1317
- * Runtime name for the class.
1180
+ * Is the property an object.
1181
+ * @param source The source of the error.
1182
+ * @param property The name of the property.
1183
+ * @param value The value to test.
1184
+ * @throws GuardError If the value does not match the assertion.
1318
1185
  */
1319
- static CLASS_NAME = "AlreadyExistsError";
1186
+ static object(source, property, value) {
1187
+ if (Is.undefined(value)) {
1188
+ throw new GuardError(source, "guard.objectUndefined", property, value);
1189
+ }
1190
+ if (!Is.object(value)) {
1191
+ throw new GuardError(source, "guard.object", property, value);
1192
+ }
1193
+ }
1320
1194
  /**
1321
- * Create a new instance of AlreadyExistsError.
1195
+ * Is the property is an object with at least one property.
1322
1196
  * @param source The source of the error.
1323
- * @param message The message as a code.
1324
- * @param existingId The id for the item.
1325
- * @param inner The inner error if we have wrapped another error.
1197
+ * @param property The name of the property.
1198
+ * @param value The value to test.
1199
+ * @throws GuardError If the value does not match the assertion.
1326
1200
  */
1327
- constructor(source, message, existingId, inner) {
1328
- super(AlreadyExistsError.CLASS_NAME, source, message, { existingId }, inner);
1201
+ static objectValue(source, property, value) {
1202
+ if (Is.undefined(value)) {
1203
+ throw new GuardError(source, "guard.objectUndefined", property, value);
1204
+ }
1205
+ if (!Is.object(value)) {
1206
+ throw new GuardError(source, "guard.object", property, value);
1207
+ }
1208
+ if (Object.keys(value || {}).length === 0) {
1209
+ throw new GuardError(source, "guard.objectValue", property, value);
1210
+ }
1329
1211
  }
1330
- }
1331
-
1332
- /**
1333
- * Class to handle errors which are triggered by conflicting data.
1334
- */
1335
- class ConflictError extends BaseError {
1336
1212
  /**
1337
- * Runtime name for the class.
1213
+ * Is the property is an array.
1214
+ * @param source The source of the error.
1215
+ * @param property The name of the property.
1216
+ * @param value The value to test.
1217
+ * @throws GuardError If the value does not match the assertion.
1338
1218
  */
1339
- static CLASS_NAME = "ConflictError";
1219
+ static array(source, property, value) {
1220
+ if (!Is.array(value)) {
1221
+ throw new GuardError(source, "guard.array", property, value);
1222
+ }
1223
+ }
1340
1224
  /**
1341
- * Create a new instance of ConflictError.
1225
+ * Is the property is an array with at least one item.
1342
1226
  * @param source The source of the error.
1343
- * @param message The message as a code.
1344
- * @param conflictId The id that has conflicts.
1345
- * @param conflicts The conflicts that occurred.
1346
- * @param inner The inner error if we have wrapped another error.
1227
+ * @param property The name of the property.
1228
+ * @param value The value to test.
1229
+ * @throws GuardError If the value does not match the assertion.
1347
1230
  */
1348
- constructor(source, message, conflictId, conflicts, inner) {
1349
- super(ConflictError.CLASS_NAME, source, message, { conflictId, conflicts }, inner);
1231
+ static arrayValue(source, property, value) {
1232
+ if (!Is.array(value)) {
1233
+ throw new GuardError(source, "guard.array", property, value);
1234
+ }
1235
+ if (value.length === 0) {
1236
+ throw new GuardError(source, "guard.arrayValue", property, value);
1237
+ }
1350
1238
  }
1351
- }
1352
-
1353
- /**
1354
- * Class to handle errors which are triggered by data guards.
1355
- */
1356
- class GuardError extends BaseError {
1357
1239
  /**
1358
- * Runtime name for the class.
1240
+ * Is the property one of a list of items.
1241
+ * @param source The source of the error.
1242
+ * @param property The name of the property.
1243
+ * @param value The value to test.
1244
+ * @param options The options the value must be one of.
1245
+ * @throws GuardError If the value does not match the assertion.
1359
1246
  */
1360
- static CLASS_NAME = "GuardError";
1247
+ static arrayOneOf(source, property, value, options) {
1248
+ if (!Is.array(options)) {
1249
+ throw new GuardError(source, "guard.array", property, value);
1250
+ }
1251
+ if (!options.includes(value)) {
1252
+ throw new GuardError(source, "guard.arrayOneOf", property, value, options.join(", "));
1253
+ }
1254
+ }
1361
1255
  /**
1362
- * Create a new instance of GuardError.
1256
+ * Does the array start with the specified data.
1363
1257
  * @param source The source of the error.
1364
- * @param message The message as a code.
1365
- * @param propertyName The property which triggered the guard error for the item.
1366
- * @param propertyValue The property value which triggered the guard error for the item.
1367
- * @param propertyOptions The property options which might be allowed.
1258
+ * @param property The name of the property.
1259
+ * @param value The value to test.
1260
+ * @param startValues The values that must start the array.
1261
+ * @throws GuardError If the value does not match the assertion.
1368
1262
  */
1369
- constructor(source, message, propertyName, propertyValue, propertyOptions) {
1370
- super(GuardError.CLASS_NAME, source, message, {
1371
- property: propertyName ?? "property",
1372
- value: Is.undefined(propertyValue) ? "undefined" : propertyValue,
1373
- options: propertyOptions
1374
- });
1263
+ static arrayStartsWith(source, property, value, startValues) {
1264
+ if (!Is.arrayValue(value)) {
1265
+ throw new GuardError(source, "guard.array", property, value);
1266
+ }
1267
+ const startValuesArray = ArrayHelper.fromObjectOrArray(startValues);
1268
+ if (!Is.arrayValue(startValuesArray)) {
1269
+ throw new GuardError(source, "guard.array", property, startValuesArray);
1270
+ }
1271
+ for (let i = 0; i < startValuesArray.length; i++) {
1272
+ if (value[i] !== startValuesArray[i]) {
1273
+ throw new GuardError(source, "guard.arrayStartsWith", property, value, startValuesArray.join(", "));
1274
+ }
1275
+ }
1375
1276
  }
1376
- }
1377
-
1378
- /**
1379
- * Class to handle errors which are triggered by data not being found.
1380
- */
1381
- class NotFoundError extends BaseError {
1382
1277
  /**
1383
- * Runtime name for the class.
1278
+ * Does the array end with the specified data.
1279
+ * @param source The source of the error.
1280
+ * @param property The name of the property.
1281
+ * @param value The value to test.
1282
+ * @param endValues The values that must end the array.
1283
+ * @throws GuardError If the value does not match the assertion.
1384
1284
  */
1385
- static CLASS_NAME = "NotFoundError";
1285
+ static arrayEndsWith(source, property, value, endValues) {
1286
+ if (!Is.arrayValue(value)) {
1287
+ throw new GuardError(source, "guard.array", property, value);
1288
+ }
1289
+ const endValuesArray = ArrayHelper.fromObjectOrArray(endValues);
1290
+ if (!Is.arrayValue(endValuesArray)) {
1291
+ throw new GuardError(source, "guard.array", property, endValuesArray);
1292
+ }
1293
+ for (let i = 0; i < endValuesArray.length; i++) {
1294
+ if (value[value.length - i - 1] !== endValuesArray[endValuesArray.length - i - 1]) {
1295
+ throw new GuardError(source, "guard.arrayEndsWith", property, value, endValuesArray.join(", "));
1296
+ }
1297
+ }
1298
+ }
1386
1299
  /**
1387
- * Create a new instance of NotFoundError.
1300
+ * Is the property a Uint8Array.
1388
1301
  * @param source The source of the error.
1389
- * @param message The message as a code.
1390
- * @param notFoundId The id for the item.
1391
- * @param inner The inner error if we have wrapped another error.
1302
+ * @param property The name of the property.
1303
+ * @param value The value to test.
1304
+ * @throws GuardError If the value does not match the assertion.
1392
1305
  */
1393
- constructor(source, message, notFoundId, inner) {
1394
- super(NotFoundError.CLASS_NAME, source, message, { notFoundId }, inner);
1306
+ static uint8Array(source, property, value) {
1307
+ if (!Is.uint8Array(value)) {
1308
+ throw new GuardError(source, "guard.uint8Array", property, value);
1309
+ }
1395
1310
  }
1396
- }
1397
-
1398
- /**
1399
- * Class to handle errors.
1400
- */
1401
- class NotImplementedError extends BaseError {
1402
1311
  /**
1403
- * Runtime name for the class.
1312
+ * Is the property a function.
1313
+ * @param source The source of the error.
1314
+ * @param property The name of the property.
1315
+ * @param value The value to test.
1316
+ * @returns True if the value is a function.
1317
+ * @throws GuardError If the value does not match the assertion.
1404
1318
  */
1405
- static CLASS_NAME = "NotImplementedError";
1319
+ static function(source, property, value) {
1320
+ if (!Is.function(value)) {
1321
+ throw new GuardError(source, "guard.function", property, value);
1322
+ }
1323
+ return true;
1324
+ }
1406
1325
  /**
1407
- * Create a new instance of NotImplementedError.
1326
+ * Is the property a string formatted as an email address.
1408
1327
  * @param source The source of the error.
1409
- * @param method The method for the error.
1328
+ * @param property The name of the property.
1329
+ * @param value The value to test.
1330
+ * @throws GuardError If the value does not match the assertion.
1410
1331
  */
1411
- constructor(source, method) {
1412
- super(NotImplementedError.CLASS_NAME, source, "common.notImplementedMethod", {
1413
- method
1414
- });
1332
+ static email(source, property, value) {
1333
+ if (!Is.email(value)) {
1334
+ throw new GuardError(source, "guard.email", property, value);
1335
+ }
1415
1336
  }
1416
1337
  }
1417
1338
 
1339
+ // Copyright 2024 IOTA Stiftung.
1340
+ // SPDX-License-Identifier: Apache-2.0.
1341
+ /* eslint-disable no-bitwise */
1418
1342
  /**
1419
- * Class to handle errors when a feature is unsupported.
1343
+ * Class to help with base63 Encoding/Decoding.
1420
1344
  */
1421
- class NotSupportedError extends BaseError {
1345
+ class Base32 {
1422
1346
  /**
1423
1347
  * Runtime name for the class.
1348
+ * @internal
1424
1349
  */
1425
- static CLASS_NAME = "NotSupportedError";
1350
+ static _CLASS_NAME = "Base32";
1426
1351
  /**
1427
- * Create a new instance of NotSupportedError.
1428
- * @param source The source of the error.
1429
- * @param message The message as a code.
1430
- * @param inner The inner error if we have wrapped another error.
1352
+ * Alphabet table for encoding.
1353
+ * @internal
1431
1354
  */
1432
- constructor(source, message, inner) {
1433
- super(NotSupportedError.CLASS_NAME, source, message, undefined, inner);
1434
- }
1435
- }
1436
-
1437
- /**
1438
- * Class to handle errors which are triggered by access not being unauthorized.
1439
- */
1440
- class UnauthorizedError extends BaseError {
1355
+ static _ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
1441
1356
  /**
1442
- * Runtime name for the class.
1357
+ * Convert the base 32 string to a byte array.
1358
+ * @param base32 The base32 string to convert.
1359
+ * @returns The byte array.
1360
+ * @throws If the input string contains a character not in the Base32 alphabet.
1443
1361
  */
1444
- static CLASS_NAME = "UnauthorizedError";
1362
+ static decode(base32) {
1363
+ Guards.string(Base32._CLASS_NAME, "base32", base32);
1364
+ let bits = 0;
1365
+ let value = 0;
1366
+ base32 = base32.replace(/=+$/, "");
1367
+ let index = 0;
1368
+ const output = new Uint8Array(Math.trunc((base32.length * 5) / 8));
1369
+ for (let i = 0; i < base32.length; i++) {
1370
+ const idx = Base32._ALPHABET.indexOf(base32[i]);
1371
+ if (idx === -1) {
1372
+ throw new GeneralError(Base32._CLASS_NAME, "invalidCharacter", {
1373
+ invalidCharacter: base32[i]
1374
+ });
1375
+ }
1376
+ value = (value << 5) | idx;
1377
+ bits += 5;
1378
+ if (bits >= 8) {
1379
+ output[index++] = (value >>> (bits - 8)) & 255;
1380
+ bits -= 8;
1381
+ }
1382
+ }
1383
+ return output;
1384
+ }
1445
1385
  /**
1446
- * Create a new instance of UnauthorizedError.
1447
- * @param source The source of the error.
1448
- * @param message The message as a code.
1449
- * @param inner The inner error if we have wrapped another error.
1386
+ * Convert a byte array to base 32.
1387
+ * @param bytes The byte array to convert.
1388
+ * @returns The data as base32 string.
1450
1389
  */
1451
- constructor(source, message, inner) {
1452
- super(UnauthorizedError.CLASS_NAME, source, message, undefined, inner);
1390
+ static encode(bytes) {
1391
+ Guards.uint8Array(Base32._CLASS_NAME, "bytes", bytes);
1392
+ let bits = 0;
1393
+ let value = 0;
1394
+ let output = "";
1395
+ for (let i = 0; i < bytes.byteLength; i++) {
1396
+ value = (value << 8) | bytes[i];
1397
+ bits += 8;
1398
+ while (bits >= 5) {
1399
+ output += Base32._ALPHABET[(value >>> (bits - 5)) & 31];
1400
+ bits -= 5;
1401
+ }
1402
+ }
1403
+ if (bits > 0) {
1404
+ output += Base32._ALPHABET[(value << (5 - bits)) & 31];
1405
+ }
1406
+ while (output.length % 8 !== 0) {
1407
+ output += "=";
1408
+ }
1409
+ return output;
1453
1410
  }
1454
1411
  }
1455
1412
 
1456
1413
  /**
1457
- * Class to handle errors when some data can not be processed.
1414
+ * Class to help with base58 Encoding/Decoding.
1458
1415
  */
1459
- class UnprocessableError extends BaseError {
1416
+ class Base58 {
1460
1417
  /**
1461
1418
  * Runtime name for the class.
1419
+ * @internal
1462
1420
  */
1463
- static CLASS_NAME = "UnprocessableError";
1464
- /**
1465
- * Create a new instance of UnprocessableError.
1466
- * @param source The source of the error.
1467
- * @param message The message as a code.
1468
- * @param properties Any additional information for the error.
1469
- * @param inner The inner error if we have wrapped another error.
1470
- */
1471
- constructor(source, message, properties, inner) {
1472
- super(UnprocessableError.CLASS_NAME, source, message, properties, inner);
1473
- }
1474
- }
1475
-
1476
- /**
1477
- * Class to handle errors which are triggered by entity validation.
1478
- */
1479
- class ValidationError extends BaseError {
1421
+ static _CLASS_NAME = "Base58";
1480
1422
  /**
1481
- * Runtime name for the class.s
1423
+ * Alphabet table for encoding.
1424
+ * @internal
1482
1425
  */
1483
- static CLASS_NAME = "ValidationError";
1426
+ static _ALPHABET =
1427
+ // cspell:disable-next-line
1428
+ "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
1484
1429
  /**
1485
- * Create a new instance of ValidationError.
1486
- * @param source The source of the error.
1487
- * @param validationObject The object that failed validation.
1488
- * @param validationFailures The validation failures.
1430
+ * Reverse map for decoding.
1431
+ * @internal
1489
1432
  */
1490
- constructor(source, validationObject, validationFailures) {
1491
- super(ValidationError.CLASS_NAME, source, "common.validation", {
1492
- validationObject,
1493
- validationFailures
1494
- });
1495
- }
1496
- }
1497
-
1498
- /**
1499
- * Class to help with arrays.
1500
- */
1501
- class ArrayHelper {
1433
+ static _ALPHABET_REVERSE = [
1434
+ -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
1435
+ -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
1436
+ -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, -1, -1, -1, -1, -1, -1, -1, 9, 10, 11, 12, 13, 14, 15, 16, -1,
1437
+ 17, 18, 19, 20, 21, -1, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, -1, -1, -1, -1, -1, -1, 33,
1438
+ 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, -1, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56,
1439
+ 57, -1, -1, -1, -1, -1
1440
+ ];
1502
1441
  /**
1503
- * Do the two arrays match.
1504
- * @param arr1 The first array.
1505
- * @param arr2 The second array.
1506
- * @returns True if both arrays are empty of have the same values.
1442
+ * Convert the base 58 string to a byte array.
1443
+ * @param base58 The base58 string to convert.
1444
+ * @returns The byte array.
1445
+ * @throws If the input string contains a character not in the Base58 alphabet.
1507
1446
  */
1508
- static matches(arr1, arr2) {
1509
- if (Is.empty(arr1) && Is.empty(arr2)) {
1510
- return true;
1447
+ static decode(base58) {
1448
+ Guards.string(Base58._CLASS_NAME, "base58", base58);
1449
+ let zeroes = 0;
1450
+ for (let i = 0; i < base58.length; i++) {
1451
+ if (base58[i] !== "1") {
1452
+ break;
1453
+ }
1454
+ zeroes += 1;
1511
1455
  }
1512
- if (!((Is.array(arr1) && Is.array(arr2)) || (Is.typedArray(arr1) && Is.typedArray(arr2)))) {
1513
- return false;
1456
+ const size = Math.trunc((base58.length * 733) / 1000) + 1;
1457
+ const b256 = new Uint8Array(size).fill(0);
1458
+ let length = 0;
1459
+ for (let i = zeroes; i < base58.length; i++) {
1460
+ const ch = base58.charCodeAt(i);
1461
+ if (ch & 0xff80) {
1462
+ throw new GeneralError(Base58._CLASS_NAME, "invalidCharacter", { invalidCharacter: ch });
1463
+ }
1464
+ const val = Base58._ALPHABET_REVERSE[ch];
1465
+ if (val === -1) {
1466
+ throw new GeneralError(Base58._CLASS_NAME, "invalidCharacter", { invalidCharacter: ch });
1467
+ }
1468
+ let carry = val;
1469
+ let j = 0;
1470
+ for (let k = size - 1; k >= 0; k--, j++) {
1471
+ if (carry === 0 && j >= length) {
1472
+ break;
1473
+ }
1474
+ carry += b256[k] * 58;
1475
+ b256[k] = carry;
1476
+ carry >>>= 8;
1477
+ }
1478
+ length = j;
1514
1479
  }
1515
- if (arr1.length !== arr2.length) {
1516
- return false;
1480
+ const out = new Uint8Array(zeroes + length);
1481
+ let j;
1482
+ for (j = 0; j < zeroes; j++) {
1483
+ out[j] = 0;
1517
1484
  }
1518
- for (let i = 0; i < arr1.length; i++) {
1519
- if (arr1[i] !== arr2[i]) {
1520
- return false;
1521
- }
1485
+ let i = size - length;
1486
+ while (i < size) {
1487
+ out[j++] = b256[i++];
1522
1488
  }
1523
- return true;
1489
+ return out;
1524
1490
  }
1525
1491
  /**
1526
- * Convert an object or array to an array.
1527
- * @param value The object or array to convert.
1528
- * @returns The array.
1492
+ * Convert a byte array to base 58.
1493
+ * @param bytes The byte array to encode.
1494
+ * @returns The data as base58 string.
1529
1495
  */
1530
- static fromObjectOrArray(value) {
1531
- if (Is.empty(value)) {
1532
- return undefined;
1496
+ static encode(bytes) {
1497
+ Guards.uint8Array(Base58._CLASS_NAME, "bytes", bytes);
1498
+ let zeroes = 0;
1499
+ for (let i = 0; i < bytes.length; i++) {
1500
+ if (bytes[i] !== 0) {
1501
+ break;
1502
+ }
1503
+ zeroes += 1;
1533
1504
  }
1534
- if (Is.array(value)) {
1535
- return value;
1505
+ const size = Math.trunc(((bytes.length - zeroes) * 138) / 100) + 1;
1506
+ const b58 = new Uint8Array(size).fill(0);
1507
+ let length = 0;
1508
+ for (let i = zeroes; i < bytes.length; i++) {
1509
+ let carry = bytes[i];
1510
+ let j = 0;
1511
+ for (let k = size - 1; k >= 0; k--, j++) {
1512
+ if (carry === 0 && j >= length) {
1513
+ break;
1514
+ }
1515
+ carry += b58[k] * 256;
1516
+ b58[k] = carry % 58;
1517
+ carry = Math.trunc(carry / 58);
1518
+ }
1519
+ length = j;
1536
1520
  }
1537
- return [value];
1521
+ let i = size - length;
1522
+ while (i < size && b58[i] === 0) {
1523
+ i += 1;
1524
+ }
1525
+ let str = "";
1526
+ for (let j = 0; j < zeroes; j++) {
1527
+ str += "1";
1528
+ }
1529
+ while (i < size) {
1530
+ str += Base58._ALPHABET[b58[i++]];
1531
+ }
1532
+ return str;
1538
1533
  }
1539
1534
  }
1540
1535
 
1541
1536
  // Copyright 2024 IOTA Stiftung.
1542
1537
  // SPDX-License-Identifier: Apache-2.0.
1538
+ /* eslint-disable no-bitwise */
1539
+ /* eslint-disable no-mixed-operators */
1543
1540
  /**
1544
- * Class to handle guard operations for parameters.
1541
+ * Class to help with base64 Encoding/Decoding.
1542
+ * Sourced from https://github.com/beatgammit/base64-js.
1545
1543
  */
1546
- class Guards {
1544
+ class Base64 {
1547
1545
  /**
1548
- * Is the property defined.
1549
- * @param source The source of the error.
1550
- * @param property The name of the property.
1551
- * @param value The value to test.
1552
- * @throws GuardError If the value does not match the assertion.
1546
+ * Runtime name for the class.
1547
+ * @internal
1553
1548
  */
1554
- static defined(source, property, value) {
1555
- if (Is.undefined(value)) {
1556
- throw new GuardError(source, "guard.undefined", property, value);
1557
- }
1558
- }
1549
+ static _CLASS_NAME = "Base64";
1550
+ /**
1551
+ * Alphabet table for encoding.
1552
+ * @internal
1553
+ */
1554
+ static _LOOKUP = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
1555
+ /**
1556
+ * Alphabet table for decoding.
1557
+ * @internal
1558
+ */
1559
+ static _REVERSE_LOOKUP = {
1560
+ "43": 62,
1561
+ "45": 62,
1562
+ "47": 63,
1563
+ "48": 52,
1564
+ "49": 53,
1565
+ "50": 54,
1566
+ "51": 55,
1567
+ "52": 56,
1568
+ "53": 57,
1569
+ "54": 58,
1570
+ "55": 59,
1571
+ "56": 60,
1572
+ "57": 61,
1573
+ "65": 0,
1574
+ "66": 1,
1575
+ "67": 2,
1576
+ "68": 3,
1577
+ "69": 4,
1578
+ "70": 5,
1579
+ "71": 6,
1580
+ "72": 7,
1581
+ "73": 8,
1582
+ "74": 9,
1583
+ "75": 10,
1584
+ "76": 11,
1585
+ "77": 12,
1586
+ "78": 13,
1587
+ "79": 14,
1588
+ "80": 15,
1589
+ "81": 16,
1590
+ "82": 17,
1591
+ "83": 18,
1592
+ "84": 19,
1593
+ "85": 20,
1594
+ "86": 21,
1595
+ "87": 22,
1596
+ "88": 23,
1597
+ "89": 24,
1598
+ "90": 25,
1599
+ "95": 63,
1600
+ "97": 26,
1601
+ "98": 27,
1602
+ "99": 28,
1603
+ "100": 29,
1604
+ "101": 30,
1605
+ "102": 31,
1606
+ "103": 32,
1607
+ "104": 33,
1608
+ "105": 34,
1609
+ "106": 35,
1610
+ "107": 36,
1611
+ "108": 37,
1612
+ "109": 38,
1613
+ "110": 39,
1614
+ "111": 40,
1615
+ "112": 41,
1616
+ "113": 42,
1617
+ "114": 43,
1618
+ "115": 44,
1619
+ "116": 45,
1620
+ "117": 46,
1621
+ "118": 47,
1622
+ "119": 48,
1623
+ "120": 49,
1624
+ "121": 50,
1625
+ "122": 51
1626
+ };
1559
1627
  /**
1560
- * Is the property a string.
1561
- * @param source The source of the error.
1562
- * @param property The name of the property.
1563
- * @param value The value to test.
1564
- * @throws GuardError If the value does not match the assertion.
1628
+ * Get the byte length of the data.
1629
+ * @param base64 The base64 string.
1630
+ * @returns The byte length of the data.
1565
1631
  */
1566
- static string(source, property, value) {
1567
- if (!Is.string(value)) {
1568
- throw new GuardError(source, "guard.string", property, value);
1569
- }
1632
+ static byteLength(base64) {
1633
+ const lens = Base64.getLengths(base64);
1634
+ return Base64.calcByteLength(lens[0], lens[1]);
1570
1635
  }
1571
1636
  /**
1572
- * Is the property a string with a value.
1573
- * @param source The source of the error.
1574
- * @param property The name of the property.
1575
- * @param value The value to test.
1576
- * @throws GuardError If the value does not match the assertion.
1637
+ * Convert the base 64 string to a byte array.
1638
+ * @param base64 The base64 string to convert.
1639
+ * @returns The byte array.
1577
1640
  */
1578
- static stringValue(source, property, value) {
1579
- if (!Is.string(value)) {
1580
- throw new GuardError(source, "guard.string", property, value);
1641
+ static decode(base64) {
1642
+ Guards.string(Base64._CLASS_NAME, "base64", base64);
1643
+ let tmp;
1644
+ const lens = Base64.getLengths(base64);
1645
+ const validLen = lens[0];
1646
+ const placeHoldersLen = lens[1];
1647
+ const arr = new Uint8Array(Base64.calcByteLength(validLen, placeHoldersLen));
1648
+ let curByte = 0;
1649
+ // if there are placeholders, only get up to the last complete 4 chars
1650
+ const len = placeHoldersLen > 0 ? validLen - 4 : validLen;
1651
+ let i;
1652
+ for (i = 0; i < len; i += 4) {
1653
+ tmp =
1654
+ (Base64._REVERSE_LOOKUP[base64.charCodeAt(i)] << 18) |
1655
+ (Base64._REVERSE_LOOKUP[base64.charCodeAt(i + 1)] << 12) |
1656
+ (Base64._REVERSE_LOOKUP[base64.charCodeAt(i + 2)] << 6) |
1657
+ Base64._REVERSE_LOOKUP[base64.charCodeAt(i + 3)];
1658
+ arr[curByte++] = (tmp >> 16) & 0xff;
1659
+ arr[curByte++] = (tmp >> 8) & 0xff;
1660
+ arr[curByte++] = tmp & 0xff;
1581
1661
  }
1582
- if (value.length === 0) {
1583
- throw new GuardError(source, "guard.stringEmpty", property, value);
1662
+ if (placeHoldersLen === 2) {
1663
+ tmp =
1664
+ (Base64._REVERSE_LOOKUP[base64.charCodeAt(i)] << 2) |
1665
+ (Base64._REVERSE_LOOKUP[base64.charCodeAt(i + 1)] >> 4);
1666
+ arr[curByte++] = tmp & 0xff;
1584
1667
  }
1585
- }
1586
- /**
1587
- * Is the property a JSON value.
1588
- * @param source The source of the error.
1589
- * @param property The name of the property.
1590
- * @param value The value to test.
1591
- * @throws GuardError If the value does not match the assertion.
1592
- */
1593
- static json(source, property, value) {
1594
- if (!Is.json(value)) {
1595
- throw new GuardError(source, "guard.stringJson", property, value);
1668
+ if (placeHoldersLen === 1) {
1669
+ tmp =
1670
+ (Base64._REVERSE_LOOKUP[base64.charCodeAt(i)] << 10) |
1671
+ (Base64._REVERSE_LOOKUP[base64.charCodeAt(i + 1)] << 4) |
1672
+ (Base64._REVERSE_LOOKUP[base64.charCodeAt(i + 2)] >> 2);
1673
+ arr[curByte++] = (tmp >> 8) & 0xff;
1674
+ arr[curByte++] = tmp & 0xff;
1596
1675
  }
1676
+ return arr;
1597
1677
  }
1598
1678
  /**
1599
- * Is the property a base64 string.
1600
- * @param source The source of the error.
1601
- * @param property The name of the property.
1602
- * @param value The value to test.
1603
- * @throws GuardError If the value does not match the assertion.
1679
+ * Convert a byte array to base 64.
1680
+ * @param bytes The byte array to convert.
1681
+ * @returns The data as base64 string.
1604
1682
  */
1605
- static stringBase64(source, property, value) {
1606
- if (!Is.stringBase64(value)) {
1607
- throw new GuardError(source, "guard.base64", property, value);
1683
+ static encode(bytes) {
1684
+ Guards.uint8Array(Base64._CLASS_NAME, "bytes", bytes);
1685
+ let tmp;
1686
+ const len = bytes.length;
1687
+ const extraBytes = len % 3; // if we have 1 byte left, pad 2 bytes
1688
+ const parts = [];
1689
+ const maxChunkLength = 16383; // must be multiple of 3
1690
+ // go through the array every three bytes, we'll deal with trailing stuff later
1691
+ for (let i = 0, len2 = len - extraBytes; i < len2; i += maxChunkLength) {
1692
+ parts.push(Base64.encodeChunk(bytes, i, Math.min(i + maxChunkLength, len2)));
1693
+ }
1694
+ // pad the end with zeros, but make sure to not forget the extra bytes
1695
+ if (extraBytes === 1) {
1696
+ tmp = bytes[len - 1];
1697
+ parts.push(`${Base64._LOOKUP[tmp >> 2] + Base64._LOOKUP[(tmp << 4) & 0x3f]}==`);
1698
+ }
1699
+ else if (extraBytes === 2) {
1700
+ tmp = (bytes[len - 2] << 8) + bytes[len - 1];
1701
+ parts.push(`${Base64._LOOKUP[tmp >> 10] + Base64._LOOKUP[(tmp >> 4) & 0x3f] + Base64._LOOKUP[(tmp << 2) & 0x3f]}=`);
1608
1702
  }
1703
+ return parts.join("");
1609
1704
  }
1610
1705
  /**
1611
- * Is the property a base64 url string.
1612
- * @param source The source of the error.
1613
- * @param property The name of the property.
1614
- * @param value The value to test.
1615
- * @throws GuardError If the value does not match the assertion.
1706
+ * Calculate the byte length.
1707
+ * @param validLen The valid length.
1708
+ * @param placeHoldersLen The placeholder length.
1709
+ * @returns The length.
1710
+ * @internal
1616
1711
  */
1617
- static stringBase64Url(source, property, value) {
1618
- if (!Is.stringBase64Url(value)) {
1619
- throw new GuardError(source, "guard.base64Url", property, value);
1620
- }
1712
+ static calcByteLength(validLen, placeHoldersLen) {
1713
+ return ((validLen + placeHoldersLen) * 3) / 4 - placeHoldersLen;
1621
1714
  }
1622
1715
  /**
1623
- * Is the property a base58 string.
1624
- * @param source The source of the error.
1625
- * @param property The name of the property.
1626
- * @param value The value to test.
1627
- * @throws GuardError If the value does not match the assertion.
1716
+ * Get the valid and placeholder lengths from a bas64 string.
1717
+ * @param base64 The base64 string.
1718
+ * @returns The lengths.
1719
+ * @internal
1628
1720
  */
1629
- static stringBase58(source, property, value) {
1630
- if (!Is.stringBase58(value)) {
1631
- throw new GuardError(source, "guard.base58", property, value);
1721
+ static getLengths(base64) {
1722
+ const len = base64.length;
1723
+ if (len % 4 > 0) {
1724
+ throw new GeneralError(Base64._CLASS_NAME, "length4Multiple", { value: len });
1725
+ }
1726
+ // Trim off extra bytes after placeholder bytes are found
1727
+ // See: https://github.com/beatgammit/base64-js/issues/42
1728
+ let validLen = base64.indexOf("=");
1729
+ if (validLen === -1) {
1730
+ validLen = len;
1632
1731
  }
1732
+ const placeHoldersLen = validLen === len ? 0 : 4 - (validLen % 4);
1733
+ return [validLen, placeHoldersLen];
1633
1734
  }
1634
1735
  /**
1635
- * Is the property a string with a hex value.
1636
- * @param source The source of the error.
1637
- * @param property The name of the property.
1638
- * @param value The value to test.
1639
- * @param allowPrefix Allow the hex to have the 0x prefix.
1640
- * @throws GuardError If the value does not match the assertion.
1736
+ * Convert the triplet to base 64.
1737
+ * @param num The number to convert.
1738
+ * @returns The base64 encoding.
1739
+ * @internal
1641
1740
  */
1642
- static stringHex(source, property, value, allowPrefix = false) {
1643
- Guards.stringValue(source, property, value);
1644
- if (!HexHelper.isHex(value, allowPrefix)) {
1645
- throw new GuardError(source, "guard.stringHex", property, value);
1646
- }
1741
+ static tripletToBase64(num) {
1742
+ return (Base64._LOOKUP[(num >> 18) & 0x3f] +
1743
+ Base64._LOOKUP[(num >> 12) & 0x3f] +
1744
+ Base64._LOOKUP[(num >> 6) & 0x3f] +
1745
+ Base64._LOOKUP[num & 0x3f]);
1647
1746
  }
1648
1747
  /**
1649
- * Is the property a string with a hex value with fixed length.
1650
- * @param source The source of the error.
1651
- * @param property The name of the property.
1652
- * @param value The value to test.
1653
- * @param length The length of the string to match.
1654
- * @param allowPrefix Allow the hex to have the 0x prefix.
1655
- * @throws GuardError If the value does not match the assertion.
1748
+ * Encode a chunk.
1749
+ * @param bytes The byte array.
1750
+ * @param start The start index in the buffer.
1751
+ * @param end The end index in the buffer.
1752
+ * @returns The encoded chunk.
1753
+ * @internal
1656
1754
  */
1657
- static stringHexLength(source, property, value, length, allowPrefix = false) {
1658
- Guards.stringHex(source, property, value, allowPrefix);
1659
- if (HexHelper.stripPrefix(value).length !== length) {
1660
- throw new GuardError(source, "guard.stringHexLength", property, value.length, length.toString());
1755
+ static encodeChunk(bytes, start, end) {
1756
+ let tmp;
1757
+ const output = [];
1758
+ for (let i = start; i < end; i += 3) {
1759
+ tmp = ((bytes[i] << 16) & 0xff0000) + ((bytes[i + 1] << 8) & 0xff00) + (bytes[i + 2] & 0xff);
1760
+ output.push(Base64.tripletToBase64(tmp));
1661
1761
  }
1762
+ return output.join("");
1662
1763
  }
1764
+ }
1765
+
1766
+ /**
1767
+ * Class to help with base64 URL Encoding/Decoding.
1768
+ * https://www.rfc-editor.org/rfc/rfc4648#section-5.
1769
+ */
1770
+ class Base64Url {
1663
1771
  /**
1664
- * Is the property a number.
1665
- * @param source The source of the error.
1666
- * @param property The name of the property.
1667
- * @param value The value to test.
1668
- * @throws GuardError If the value does not match the assertion.
1772
+ * Runtime name for the class.
1773
+ * @internal
1669
1774
  */
1670
- static number(source, property, value) {
1671
- if (!Is.number(value)) {
1672
- throw new GuardError(source, "guard.number", property, value);
1673
- }
1674
- }
1775
+ static _CLASS_NAME = "Base64";
1675
1776
  /**
1676
- * Is the property an integer.
1677
- * @param source The source of the error.
1678
- * @param property The name of the property.
1679
- * @param value The value to test.
1680
- * @throws GuardError If the value does not match the assertion.
1777
+ * Convert the base 64 string to a byte array.
1778
+ * @param base64Url The base64 url string to convert.
1779
+ * @returns The byte array.
1681
1780
  */
1682
- static integer(source, property, value) {
1683
- if (!Is.integer(value)) {
1684
- throw new GuardError(source, "guard.integer", property, value);
1781
+ static decode(base64Url) {
1782
+ Guards.string(Base64Url._CLASS_NAME, "base64Url", base64Url);
1783
+ let base64 = base64Url;
1784
+ // Base 64 url can have padding removed, so add it back if it is missing.
1785
+ if (base64.length > 0 && !base64.endsWith("=")) {
1786
+ const placeHoldersLen = 4 - (base64.length % 4);
1787
+ if (placeHoldersLen > 0 && placeHoldersLen < 4) {
1788
+ base64 = base64.padEnd(base64.length + placeHoldersLen, "=");
1789
+ }
1685
1790
  }
1791
+ base64 = base64.replace(/-/g, "+").replace(/_/g, "/");
1792
+ return Base64.decode(base64);
1686
1793
  }
1687
1794
  /**
1688
- * Is the property a bigint.
1689
- * @param source The source of the error.
1690
- * @param property The name of the property.
1691
- * @param value The value to test.
1692
- * @throws GuardError If the value does not match the assertion.
1795
+ * Convert a byte array to base 64 url.
1796
+ * @param bytes The byte array to convert.
1797
+ * @returns The data as base64 url string.
1693
1798
  */
1694
- static bigint(source, property, value) {
1695
- if (!Is.bigint(value)) {
1696
- throw new GuardError(source, "guard.bigint", property, value);
1697
- }
1799
+ static encode(bytes) {
1800
+ Guards.uint8Array(Base64Url._CLASS_NAME, "bytes", bytes);
1801
+ const base64 = Base64.encode(bytes);
1802
+ // Base 64 url can have padding removed, so remove it.
1803
+ return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
1698
1804
  }
1805
+ }
1806
+
1807
+ /**
1808
+ * Class to handle errors which are triggered by data already existing.
1809
+ */
1810
+ class AlreadyExistsError extends BaseError {
1811
+ /**
1812
+ * Runtime name for the class.
1813
+ */
1814
+ static CLASS_NAME = "AlreadyExistsError";
1699
1815
  /**
1700
- * Is the property a boolean.
1816
+ * Create a new instance of AlreadyExistsError.
1701
1817
  * @param source The source of the error.
1702
- * @param property The name of the property.
1703
- * @param value The value to test.
1704
- * @throws GuardError If the value does not match the assertion.
1818
+ * @param message The message as a code.
1819
+ * @param existingId The id for the item.
1820
+ * @param cause The cause of the error if we have wrapped another error.
1705
1821
  */
1706
- static boolean(source, property, value) {
1707
- if (!Is.boolean(value)) {
1708
- throw new GuardError(source, "guard.boolean", property, value);
1709
- }
1822
+ constructor(source, message, existingId, cause) {
1823
+ super(AlreadyExistsError.CLASS_NAME, source, message, { existingId });
1710
1824
  }
1825
+ }
1826
+
1827
+ /**
1828
+ * Class to handle errors which are triggered by conflicting data.
1829
+ */
1830
+ class ConflictError extends BaseError {
1711
1831
  /**
1712
- * Is the property a date.
1713
- * @param source The source of the error.
1714
- * @param property The name of the property.
1715
- * @param value The value to test.
1716
- * @throws GuardError If the value does not match the assertion.
1832
+ * Runtime name for the class.
1717
1833
  */
1718
- static date(source, property, value) {
1719
- if (!Is.date(value)) {
1720
- throw new GuardError(source, "guard.date", property, value);
1721
- }
1722
- }
1834
+ static CLASS_NAME = "ConflictError";
1723
1835
  /**
1724
- * Is the property a timestamp in milliseconds.
1836
+ * Create a new instance of ConflictError.
1725
1837
  * @param source The source of the error.
1726
- * @param property The name of the property.
1727
- * @param value The value to test.
1728
- * @throws GuardError If the value does not match the assertion.
1838
+ * @param message The message as a code.
1839
+ * @param conflictId The id that has conflicts.
1840
+ * @param conflicts The conflicts that occurred.
1841
+ * @param cause The cause or the error if we have wrapped another error.
1729
1842
  */
1730
- static timestampMilliseconds(source, property, value) {
1731
- if (!Is.timestampMilliseconds(value)) {
1732
- throw new GuardError(source, "guard.timestampMilliseconds", property, value);
1733
- }
1843
+ constructor(source, message, conflictId, conflicts, cause) {
1844
+ super(ConflictError.CLASS_NAME, source, message, { conflictId, conflicts }, cause);
1734
1845
  }
1846
+ }
1847
+
1848
+ /**
1849
+ * Class to handle errors which are triggered by data not being found.
1850
+ */
1851
+ class NotFoundError extends BaseError {
1735
1852
  /**
1736
- * Is the property a timestamp in seconds.
1737
- * @param source The source of the error.
1738
- * @param property The name of the property.
1739
- * @param value The value to test.
1740
- * @throws GuardError If the value does not match the assertion.
1853
+ * Runtime name for the class.
1741
1854
  */
1742
- static timestampSeconds(source, property, value) {
1743
- if (!Is.timestampSeconds(value)) {
1744
- throw new GuardError(source, "guard.timestampSeconds", property, value);
1745
- }
1746
- }
1855
+ static CLASS_NAME = "NotFoundError";
1747
1856
  /**
1748
- * Is the property an object.
1857
+ * Create a new instance of NotFoundError.
1749
1858
  * @param source The source of the error.
1750
- * @param property The name of the property.
1751
- * @param value The value to test.
1752
- * @throws GuardError If the value does not match the assertion.
1859
+ * @param message The message as a code.
1860
+ * @param notFoundId The id for the item.
1861
+ * @param cause The cause of the error if we have wrapped another error.
1753
1862
  */
1754
- static object(source, property, value) {
1755
- if (Is.undefined(value)) {
1756
- throw new GuardError(source, "guard.objectUndefined", property, value);
1757
- }
1758
- if (!Is.object(value)) {
1759
- throw new GuardError(source, "guard.object", property, value);
1760
- }
1863
+ constructor(source, message, notFoundId, cause) {
1864
+ super(NotFoundError.CLASS_NAME, source, message, { notFoundId }, cause);
1761
1865
  }
1866
+ }
1867
+
1868
+ /**
1869
+ * Class to handle errors.
1870
+ */
1871
+ class NotImplementedError extends BaseError {
1762
1872
  /**
1763
- * Is the property is an object with at least one property.
1764
- * @param source The source of the error.
1765
- * @param property The name of the property.
1766
- * @param value The value to test.
1767
- * @throws GuardError If the value does not match the assertion.
1873
+ * Runtime name for the class.
1768
1874
  */
1769
- static objectValue(source, property, value) {
1770
- if (Is.undefined(value)) {
1771
- throw new GuardError(source, "guard.objectUndefined", property, value);
1772
- }
1773
- if (!Is.object(value)) {
1774
- throw new GuardError(source, "guard.object", property, value);
1775
- }
1776
- if (Object.keys(value || {}).length === 0) {
1777
- throw new GuardError(source, "guard.objectValue", property, value);
1778
- }
1779
- }
1875
+ static CLASS_NAME = "NotImplementedError";
1780
1876
  /**
1781
- * Is the property is an array.
1877
+ * Create a new instance of NotImplementedError.
1782
1878
  * @param source The source of the error.
1783
- * @param property The name of the property.
1784
- * @param value The value to test.
1785
- * @throws GuardError If the value does not match the assertion.
1879
+ * @param method The method for the error.
1786
1880
  */
1787
- static array(source, property, value) {
1788
- if (!Is.array(value)) {
1789
- throw new GuardError(source, "guard.array", property, value);
1790
- }
1881
+ constructor(source, method) {
1882
+ super(NotImplementedError.CLASS_NAME, source, "common.notImplementedMethod", {
1883
+ method
1884
+ });
1791
1885
  }
1886
+ }
1887
+
1888
+ /**
1889
+ * Class to handle errors when a feature is unsupported.
1890
+ */
1891
+ class NotSupportedError extends BaseError {
1792
1892
  /**
1793
- * Is the property is an array with at least one item.
1794
- * @param source The source of the error.
1795
- * @param property The name of the property.
1796
- * @param value The value to test.
1797
- * @throws GuardError If the value does not match the assertion.
1893
+ * Runtime name for the class.
1798
1894
  */
1799
- static arrayValue(source, property, value) {
1800
- if (!Is.array(value)) {
1801
- throw new GuardError(source, "guard.array", property, value);
1802
- }
1803
- if (value.length === 0) {
1804
- throw new GuardError(source, "guard.arrayValue", property, value);
1805
- }
1806
- }
1895
+ static CLASS_NAME = "NotSupportedError";
1807
1896
  /**
1808
- * Is the property one of a list of items.
1897
+ * Create a new instance of NotSupportedError.
1809
1898
  * @param source The source of the error.
1810
- * @param property The name of the property.
1811
- * @param value The value to test.
1812
- * @param options The options the value must be one of.
1813
- * @throws GuardError If the value does not match the assertion.
1899
+ * @param message The message as a code.
1900
+ * @param cause The cause of the error if we have wrapped another error.
1814
1901
  */
1815
- static arrayOneOf(source, property, value, options) {
1816
- if (!Is.array(options)) {
1817
- throw new GuardError(source, "guard.array", property, value);
1818
- }
1819
- if (!options.includes(value)) {
1820
- throw new GuardError(source, "guard.arrayOneOf", property, value, options.join(", "));
1821
- }
1902
+ constructor(source, message, cause) {
1903
+ super(NotSupportedError.CLASS_NAME, source, message, undefined, cause);
1822
1904
  }
1905
+ }
1906
+
1907
+ /**
1908
+ * Class to handle errors which are triggered by access not being unauthorized.
1909
+ */
1910
+ class UnauthorizedError extends BaseError {
1823
1911
  /**
1824
- * Does the array start with the specified data.
1825
- * @param source The source of the error.
1826
- * @param property The name of the property.
1827
- * @param value The value to test.
1828
- * @param startValues The values that must start the array.
1829
- * @throws GuardError If the value does not match the assertion.
1912
+ * Runtime name for the class.
1830
1913
  */
1831
- static arrayStartsWith(source, property, value, startValues) {
1832
- if (!Is.arrayValue(value)) {
1833
- throw new GuardError(source, "guard.array", property, value);
1834
- }
1835
- const startValuesArray = ArrayHelper.fromObjectOrArray(startValues);
1836
- if (!Is.arrayValue(startValuesArray)) {
1837
- throw new GuardError(source, "guard.array", property, startValuesArray);
1838
- }
1839
- for (let i = 0; i < startValuesArray.length; i++) {
1840
- if (value[i] !== startValuesArray[i]) {
1841
- throw new GuardError(source, "guard.arrayStartsWith", property, value, startValuesArray.join(", "));
1842
- }
1843
- }
1844
- }
1914
+ static CLASS_NAME = "UnauthorizedError";
1845
1915
  /**
1846
- * Does the array end with the specified data.
1916
+ * Create a new instance of UnauthorizedError.
1847
1917
  * @param source The source of the error.
1848
- * @param property The name of the property.
1849
- * @param value The value to test.
1850
- * @param endValues The values that must end the array.
1851
- * @throws GuardError If the value does not match the assertion.
1918
+ * @param message The message as a code.
1919
+ * @param cause The cause of the error if we have wrapped another error.
1852
1920
  */
1853
- static arrayEndsWith(source, property, value, endValues) {
1854
- if (!Is.arrayValue(value)) {
1855
- throw new GuardError(source, "guard.array", property, value);
1856
- }
1857
- const endValuesArray = ArrayHelper.fromObjectOrArray(endValues);
1858
- if (!Is.arrayValue(endValuesArray)) {
1859
- throw new GuardError(source, "guard.array", property, endValuesArray);
1860
- }
1861
- for (let i = 0; i < endValuesArray.length; i++) {
1862
- if (value[value.length - i - 1] !== endValuesArray[endValuesArray.length - i - 1]) {
1863
- throw new GuardError(source, "guard.arrayEndsWith", property, value, endValuesArray.join(", "));
1864
- }
1865
- }
1921
+ constructor(source, message, cause) {
1922
+ super(UnauthorizedError.CLASS_NAME, source, message, undefined, cause);
1866
1923
  }
1924
+ }
1925
+
1926
+ /**
1927
+ * Class to handle errors when some data can not be processed.
1928
+ */
1929
+ class UnprocessableError extends BaseError {
1867
1930
  /**
1868
- * Is the property a Uint8Array.
1869
- * @param source The source of the error.
1870
- * @param property The name of the property.
1871
- * @param value The value to test.
1872
- * @throws GuardError If the value does not match the assertion.
1931
+ * Runtime name for the class.
1873
1932
  */
1874
- static uint8Array(source, property, value) {
1875
- if (!Is.uint8Array(value)) {
1876
- throw new GuardError(source, "guard.uint8Array", property, value);
1877
- }
1878
- }
1933
+ static CLASS_NAME = "UnprocessableError";
1879
1934
  /**
1880
- * Is the property a function.
1935
+ * Create a new instance of UnprocessableError.
1881
1936
  * @param source The source of the error.
1882
- * @param property The name of the property.
1883
- * @param value The value to test.
1884
- * @returns True if the value is a function.
1885
- * @throws GuardError If the value does not match the assertion.
1937
+ * @param message The message as a code.
1938
+ * @param properties Any additional information for the error.
1939
+ * @param cause The cause of the error if we have wrapped another error.
1886
1940
  */
1887
- static function(source, property, value) {
1888
- if (!Is.function(value)) {
1889
- throw new GuardError(source, "guard.function", property, value);
1890
- }
1891
- return true;
1941
+ constructor(source, message, properties, cause) {
1942
+ super(UnprocessableError.CLASS_NAME, source, message, properties, cause);
1892
1943
  }
1944
+ }
1945
+
1946
+ /**
1947
+ * Class to handle errors which are triggered by entity validation.
1948
+ */
1949
+ class ValidationError extends BaseError {
1893
1950
  /**
1894
- * Is the property a string formatted as an email address.
1951
+ * Runtime name for the class.s
1952
+ */
1953
+ static CLASS_NAME = "ValidationError";
1954
+ /**
1955
+ * Create a new instance of ValidationError.
1895
1956
  * @param source The source of the error.
1896
- * @param property The name of the property.
1897
- * @param value The value to test.
1898
- * @throws GuardError If the value does not match the assertion.
1957
+ * @param validationObject The object that failed validation.
1958
+ * @param validationFailures The validation failures.
1899
1959
  */
1900
- static email(source, property, value) {
1901
- if (!Is.email(value)) {
1902
- throw new GuardError(source, "guard.email", property, value);
1903
- }
1960
+ constructor(source, validationObject, validationFailures) {
1961
+ super(ValidationError.CLASS_NAME, source, "common.validation", {
1962
+ validationObject,
1963
+ validationFailures
1964
+ });
1904
1965
  }
1905
1966
  }
1906
1967
 
@@ -2093,6 +2154,7 @@ class Factory {
2093
2154
  * @throws GeneralError if no item exists to get.
2094
2155
  */
2095
2156
  get(name) {
2157
+ Guards.stringValue(Factory._CLASS_NAME, "name", name);
2096
2158
  const instance = this.getIfExists(name);
2097
2159
  if (!instance) {
2098
2160
  throw new GeneralError(Factory._CLASS_NAME, "noGet", {
@@ -2108,6 +2170,9 @@ class Factory {
2108
2170
  * @returns An instance of the item or undefined if it does not exist.
2109
2171
  */
2110
2172
  getIfExists(name) {
2173
+ if (Is.empty(name)) {
2174
+ return;
2175
+ }
2111
2176
  Guards.stringValue(Factory._CLASS_NAME, "name", name);
2112
2177
  const matchName = this._matcher(Object.keys(this._generators), name);
2113
2178
  if (Is.stringValue(matchName) && this._generators[matchName]) {
@@ -3136,7 +3201,7 @@ class ErrorHelper {
3136
3201
  * Format Errors and returns just their messages.
3137
3202
  * @param error The error to format.
3138
3203
  * @param includeDetails Whether to include error details, defaults to false.
3139
- * @returns The error formatted including any inner errors.
3204
+ * @returns The error formatted including any causes errors.
3140
3205
  */
3141
3206
  static formatErrors(error, includeDetails) {
3142
3207
  const localizedErrors = ErrorHelper.localizeErrors(error);
@@ -3154,7 +3219,7 @@ class ErrorHelper {
3154
3219
  return localizedErrors.map(e => e.message);
3155
3220
  }
3156
3221
  /**
3157
- * Localize the content of an error and any inner errors.
3222
+ * Localize the content of an error and any causes.
3158
3223
  * @param error The error to format.
3159
3224
  * @returns The localized version of the errors flattened.
3160
3225
  */
@@ -3195,7 +3260,7 @@ class ErrorHelper {
3195
3260
  return formattedErrors;
3196
3261
  }
3197
3262
  /**
3198
- * Localize the content of an error and any inner errors.
3263
+ * Localize the content of an error and any causes.
3199
3264
  * @param error The error to format.
3200
3265
  * @returns The localized version of the errors flattened.
3201
3266
  */
@@ -3510,6 +3575,7 @@ class Coerce {
3510
3575
  * @returns The coerced value.
3511
3576
  */
3512
3577
  static byType(value, type) {
3578
+ // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
3513
3579
  switch (type) {
3514
3580
  case CoerceType.String:
3515
3581
  return Coerce.string(value);
@@ -4263,7 +4329,7 @@ class Compression {
4263
4329
  static async compress(bytes, type) {
4264
4330
  Guards.uint8Array(Compression._CLASS_NAME, "bytes", bytes);
4265
4331
  Guards.arrayOneOf(Compression._CLASS_NAME, "type", type, Object.values(CompressionType));
4266
- const blob = new Blob([bytes]);
4332
+ const blob = new Blob([new Uint8Array(bytes)]);
4267
4333
  const compressionStream = new CompressionStream(type);
4268
4334
  const compressionPipe = blob.stream().pipeThrough(compressionStream);
4269
4335
  const compressedBlob = await new Response(compressionPipe).blob();
@@ -4285,7 +4351,7 @@ class Compression {
4285
4351
  static async decompress(compressedBytes, type) {
4286
4352
  Guards.uint8Array(Compression._CLASS_NAME, "compressedBytes", compressedBytes);
4287
4353
  Guards.arrayOneOf(Compression._CLASS_NAME, "type", type, Object.values(CompressionType));
4288
- const blob = new Blob([compressedBytes]);
4354
+ const blob = new Blob([new Uint8Array(compressedBytes)]);
4289
4355
  const decompressionStream = new DecompressionStream(type);
4290
4356
  const decompressionPipe = blob.stream().pipeThrough(decompressionStream);
4291
4357
  const decompressedBlob = await new Response(decompressionPipe).blob();