@alextheman/utility 3.7.0 → 3.9.0
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.
- package/README.md +0 -119
- package/dist/index.cjs +89 -0
- package/dist/index.d.cts +65 -1
- package/dist/index.d.ts +65 -1
- package/dist/index.js +85 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -24,122 +24,3 @@ import { formatDateAndTime } from "@alextheman/utility";
|
|
|
24
24
|
const myVariable: NonUndefined<string> = formatDateAndTime(new Date());
|
|
25
25
|
// ...
|
|
26
26
|
```
|
|
27
|
-
|
|
28
|
-
## Contributing
|
|
29
|
-
|
|
30
|
-
### Creating a function
|
|
31
|
-
#### Setup
|
|
32
|
-
To create a new function in the package, you must first checkout a new branch. Do **not** commit directly on main.
|
|
33
|
-
|
|
34
|
-
From there, create the skeleton of the function. This is just the function declaration itself, along with the arguments and their types, along with the return type.
|
|
35
|
-
|
|
36
|
-
```typescript
|
|
37
|
-
function myFunction(firstArg: ArgType): ReturnType {
|
|
38
|
-
// Implementation goes here
|
|
39
|
-
}
|
|
40
|
-
|
|
41
|
-
export default myFunction
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
Note that every function that gets exported from this package **must** have a type annotation. This is also enforced by ESLint. This helps to make the return types extra explicit and more intentional.
|
|
45
|
-
|
|
46
|
-
Once you have this, export the function from `src/functions/index.ts` so that consumers can import your function. Also export any types you may want to export near the bottom of the file:
|
|
47
|
-
|
|
48
|
-
```typescript
|
|
49
|
-
export { default as addDaysToDate } from "src/functions/addDaysToDate";
|
|
50
|
-
export { default as appendSemicolon } from "src/functions/appendSemicolon";
|
|
51
|
-
export { default as camelToKebab } from "src/functions/camelToKebab";
|
|
52
|
-
export { default as convertFileToBase64 } from "src/functions/convertFileToBase64";
|
|
53
|
-
export { default as createFormData } from "src/functions/createFormData";
|
|
54
|
-
export { default as fillArray } from "src/functions/fillArray";
|
|
55
|
-
export { default as formatDateAndTime } from "src/functions/formatDateAndTime";
|
|
56
|
-
// ...
|
|
57
|
-
export { default as myFunction } from "src/functions/myFunction";
|
|
58
|
-
// ...
|
|
59
|
-
|
|
60
|
-
export type { MyFunctionOptions } from "src/functions/myFunction";
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
#### Testing
|
|
64
|
-
|
|
65
|
-
Every function must also be tested. Tests are located in the `tests` folder and follows roughly the same structure as `src`. We use Vitest for our tests, and instead of relying on the global test functions like you might do with Jest, we instead import each test function directly.
|
|
66
|
-
|
|
67
|
-
Tests are generally structured in the following way:
|
|
68
|
-
|
|
69
|
-
```typescript
|
|
70
|
-
import { describe, expect, test } from "vitest";
|
|
71
|
-
|
|
72
|
-
import myFunction from "src/functions/myFunction";
|
|
73
|
-
|
|
74
|
-
describe("myFunction", () => {
|
|
75
|
-
test("Does a thing", () => {
|
|
76
|
-
expect(myFunction("hello")).toBe("world");
|
|
77
|
-
});
|
|
78
|
-
test("Does another thing", () => {
|
|
79
|
-
expect(myFunction("one")).toBe("two");
|
|
80
|
-
});
|
|
81
|
-
// ...
|
|
82
|
-
});
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
That is, we wrap all tests around a describe block grouping all related tests to that function together, then each test block tests a specific behaviour.
|
|
86
|
-
|
|
87
|
-
Every function must at least have one test for the core behaviour of it. Of course, the more tests, the better, but at the very least, test the core behaviour of the function. From there, if you feel like there may be a few edge cases you want to verify the behaviour of, please add tests in for that as well.
|
|
88
|
-
|
|
89
|
-
Some functions that we create may often end up taking in an array or object. Due to the nature of how JavaScript passes these, we must have non-mutation tests in place to prevent unintended mutation of the input array/object. The best way to do this is to use `Object.freeze()`, as that will ensure that we get an error if the function ever even tries to mutate the input.
|
|
90
|
-
|
|
91
|
-
```typescript
|
|
92
|
-
describe("removeDuplicates", () => {
|
|
93
|
-
describe("Mutation checks", () => {
|
|
94
|
-
test("Does not mutate the original array", () => {
|
|
95
|
-
const inputArray = Object.freeze([1, 1, 2, 3, 4]);
|
|
96
|
-
// since the array has been frozen, this will give a TypeError if it tries to mutate the inputArray.
|
|
97
|
-
removeDuplicates(inputArray);
|
|
98
|
-
expect(inputArray).toEqual([1, 1, 2, 3, 4]);
|
|
99
|
-
});
|
|
100
|
-
});
|
|
101
|
-
});
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
Also, if the return type of the function is the same as one or more of the inputs, it's also often helpful to have a test that ensures the output returns a new reference in memory:
|
|
105
|
-
|
|
106
|
-
```typescript
|
|
107
|
-
describe("removeDuplicates", () => {
|
|
108
|
-
describe("Mutation checks", () => {
|
|
109
|
-
test("Returns an array with a new reference in memory", () => {
|
|
110
|
-
const inputArray = [1, 1, 2, 3, 4];
|
|
111
|
-
const outputArray = removeDuplicates(inputArray);
|
|
112
|
-
expect(outputArray).not.toBe(inputArray);
|
|
113
|
-
});
|
|
114
|
-
});
|
|
115
|
-
});
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
Note the use of `.toBe()` over `.toEqual()` here. This is because in this case, we are comparing the variable's memory reference to the output's memory reference rather than the actual contents of the array.
|
|
119
|
-
|
|
120
|
-
### Creating a type
|
|
121
|
-
|
|
122
|
-
Creating a type works in a similar way to creating a function, in the sense that you create a new file for it, add it to `src/types/index.ts`, and test it. Yes, test it. It is possible to test type declarations using `expectTypeOf`. As an example:
|
|
123
|
-
|
|
124
|
-
```typescript
|
|
125
|
-
import type { OptionalOnCondition } from "src/types";
|
|
126
|
-
|
|
127
|
-
import { describe, expectTypeOf, test } from "vitest";
|
|
128
|
-
|
|
129
|
-
describe("OptionalOnCondition", () => {
|
|
130
|
-
test("Resolves to the type of the second type argument if first type argument is true", () => {
|
|
131
|
-
expectTypeOf<OptionalOnCondition<true, string>>().toEqualTypeOf<string>();
|
|
132
|
-
});
|
|
133
|
-
test("Resolves to a union of the second type and undefined if first type argument is false", () => {
|
|
134
|
-
expectTypeOf<OptionalOnCondition<false, string>>().toEqualTypeOf<string | undefined>();
|
|
135
|
-
});
|
|
136
|
-
});
|
|
137
|
-
```
|
|
138
|
-
|
|
139
|
-
Note that when you actually run the tests using `npm test`, the tests will always pass even if the logic is incorrect. This is because type tests run with the TypeScript compiler so it will error in your editor and in linting, but it will never fail in runtime. As such, just remember to be extra careful with these type tests and remember that the actual test results for these show in the editor and not in runtime.
|
|
140
|
-
|
|
141
|
-
### Publishing
|
|
142
|
-
|
|
143
|
-
Once you are happy with your changes, commit the changes to your branch, then change the version number. You can do this by running one of `npm run change-major`, `npm run change-minor`, or `npm run change-patch`. Major changes generally correspond to breaking changes (e.g. removing features, changing the build process substantially), minor changes correspond to non-breaking additions/deprecations, and patch changes are for the small things that aren't as noticeable. Note that your change will fail CI if you change the source code but forget to change the version number. From there, after your changes have been approved and merged, the publish script will automatically run, and if you remembered to change the version number, it will pass the publishing action.
|
|
144
|
-
|
|
145
|
-
Version number changes must also **not** be part of your main commit(s) - they must be their own standalone commit. This helps to make it easier to revert changes if needed - if the version change is part of the main commit, that means that if we need to revert it for whatever reason, the version change also gets reverted, which is not really ideal as it makes re-publishing a bit harder.
|
package/dist/index.cjs
CHANGED
|
@@ -34,6 +34,11 @@ path = __toESM(path);
|
|
|
34
34
|
const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
|
|
35
35
|
var NAMESPACE_EXPORT_REGEX_default = NAMESPACE_EXPORT_REGEX;
|
|
36
36
|
|
|
37
|
+
//#endregion
|
|
38
|
+
//#region src/constants/VERSION_NUMBER_REGEX.ts
|
|
39
|
+
const VERSION_NUMBER_REGEX = "^(?:v)?(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$";
|
|
40
|
+
var VERSION_NUMBER_REGEX_default = VERSION_NUMBER_REGEX;
|
|
41
|
+
|
|
37
42
|
//#endregion
|
|
38
43
|
//#region src/functions/arrayHelpers/fillArray.ts
|
|
39
44
|
/**
|
|
@@ -1058,10 +1063,90 @@ function removeIndents(first, ...args) {
|
|
|
1058
1063
|
}
|
|
1059
1064
|
var removeIndents_default = removeIndents;
|
|
1060
1065
|
|
|
1066
|
+
//#endregion
|
|
1067
|
+
//#region src/functions/versioning/parseVersion.ts
|
|
1068
|
+
/**
|
|
1069
|
+
* Parses a string and verifies it is a valid package version number.
|
|
1070
|
+
*
|
|
1071
|
+
* Valid formats: `X.Y.Z` or `vX.Y.Z`, where X, Y, and Z are non-negative integers.
|
|
1072
|
+
*
|
|
1073
|
+
* @param input - The version string to parse.
|
|
1074
|
+
* @param options - Extra options to apply.
|
|
1075
|
+
*
|
|
1076
|
+
* @throws {DataError} If the input is not a valid version number.
|
|
1077
|
+
*
|
|
1078
|
+
* @returns The validated version number, prefixed with `v` if it was not already.
|
|
1079
|
+
*/
|
|
1080
|
+
function parseVersion(input, options) {
|
|
1081
|
+
if (!RegExp(VERSION_NUMBER_REGEX_default).test(input)) throw new DataError_default(input, `"${input}" is not a valid version number. Version numbers must be of the format "X.Y.Z" or "vX.Y.Z", where X, Y, and Z are non-negative integers.`, "INVALID_VERSION");
|
|
1082
|
+
if (options?.omitPrefix) return input.startsWith("v") ? input.slice(1) : input;
|
|
1083
|
+
return input.startsWith("v") ? input : `v${input}`;
|
|
1084
|
+
}
|
|
1085
|
+
var parseVersion_default = parseVersion;
|
|
1086
|
+
|
|
1087
|
+
//#endregion
|
|
1088
|
+
//#region src/functions/versioning/getIndividualVersionNumbers.ts
|
|
1089
|
+
/**
|
|
1090
|
+
* Gets the individual version numbers from a given version number as a tuple of numbers.
|
|
1091
|
+
*
|
|
1092
|
+
* @param version - The version number.
|
|
1093
|
+
*
|
|
1094
|
+
* @returns A tuple of three numbers indicating `[major, minor, patch]`.
|
|
1095
|
+
*/
|
|
1096
|
+
function getIndividualVersionNumbers(version) {
|
|
1097
|
+
return parseVersion_default(version, { omitPrefix: true }).split(".").map((versionNumber) => {
|
|
1098
|
+
return parseIntStrict_default(versionNumber);
|
|
1099
|
+
});
|
|
1100
|
+
}
|
|
1101
|
+
var getIndividualVersionNumbers_default = getIndividualVersionNumbers;
|
|
1102
|
+
|
|
1103
|
+
//#endregion
|
|
1104
|
+
//#region src/functions/versioning/determineVersionType.ts
|
|
1105
|
+
/**
|
|
1106
|
+
* Determines whether the given version is a major, minor, or patch version.
|
|
1107
|
+
*
|
|
1108
|
+
* @param version - The version number.
|
|
1109
|
+
*
|
|
1110
|
+
* @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
|
|
1111
|
+
*/
|
|
1112
|
+
function determineVersionType(version) {
|
|
1113
|
+
const [_major, minor, patch] = getIndividualVersionNumbers_default(version);
|
|
1114
|
+
if (minor === 0 && patch === 0) return "major";
|
|
1115
|
+
if (patch === 0) return "minor";
|
|
1116
|
+
return "patch";
|
|
1117
|
+
}
|
|
1118
|
+
var determineVersionType_default = determineVersionType;
|
|
1119
|
+
|
|
1120
|
+
//#endregion
|
|
1121
|
+
//#region src/functions/versioning/incrementVersion.ts
|
|
1122
|
+
/**
|
|
1123
|
+
* Increments the given input version depending on the given increment type.
|
|
1124
|
+
*
|
|
1125
|
+
* @param version - The version to increment
|
|
1126
|
+
* @param incrementType - The type of increment. Can be one of the following:
|
|
1127
|
+
* - `"major"`: Change the major version `v1.2.3` → `v2.0.0`
|
|
1128
|
+
* - `"minor"`: Change the minor version `v1.2.3` → `v1.3.0`
|
|
1129
|
+
* - `"patch"`: Change the patch version `v1.2.3` → `v1.2.4`
|
|
1130
|
+
* @param options - Extra options to apply.
|
|
1131
|
+
*
|
|
1132
|
+
* @returns A new string representing the version with the increment applied.
|
|
1133
|
+
*/
|
|
1134
|
+
function incrementVersion(version, incrementType, options) {
|
|
1135
|
+
const [major, minor, patch] = getIndividualVersionNumbers_default(version);
|
|
1136
|
+
const newVersion = {
|
|
1137
|
+
major: `${major + 1}.0.0`,
|
|
1138
|
+
minor: `${major}.${minor + 1}.0`,
|
|
1139
|
+
patch: `${major}.${minor}.${patch + 1}`
|
|
1140
|
+
}[incrementType];
|
|
1141
|
+
return parseVersion_default(newVersion, { omitPrefix: options?.omitPrefix });
|
|
1142
|
+
}
|
|
1143
|
+
var incrementVersion_default = incrementVersion;
|
|
1144
|
+
|
|
1061
1145
|
//#endregion
|
|
1062
1146
|
exports.APIError = APIError_default;
|
|
1063
1147
|
exports.DataError = DataError_default;
|
|
1064
1148
|
exports.NAMESPACE_EXPORT_REGEX = NAMESPACE_EXPORT_REGEX_default;
|
|
1149
|
+
exports.VERSION_NUMBER_REGEX = VERSION_NUMBER_REGEX_default;
|
|
1065
1150
|
exports.addDaysToDate = addDaysToDate_default;
|
|
1066
1151
|
exports.appendSemicolon = appendSemicolon_default;
|
|
1067
1152
|
exports.camelToKebab = camelToKebab_default;
|
|
@@ -1070,11 +1155,14 @@ exports.createFormData = createFormData_default;
|
|
|
1070
1155
|
exports.createTemplateStringsArray = createTemplateStringsArray_default;
|
|
1071
1156
|
exports.deepCopy = deepCopy_default;
|
|
1072
1157
|
exports.deepFreeze = deepFreeze_default;
|
|
1158
|
+
exports.determineVersionType = determineVersionType_default;
|
|
1073
1159
|
exports.fillArray = fillArray_default;
|
|
1074
1160
|
exports.formatDateAndTime = formatDateAndTime_default;
|
|
1161
|
+
exports.getIndividualVersionNumbers = getIndividualVersionNumbers_default;
|
|
1075
1162
|
exports.getRandomNumber = getRandomNumber_default;
|
|
1076
1163
|
exports.getRecordKeys = getRecordKeys_default;
|
|
1077
1164
|
exports.httpErrorCodeLookup = httpErrorCodeLookup;
|
|
1165
|
+
exports.incrementVersion = incrementVersion_default;
|
|
1078
1166
|
exports.interpolate = interpolate_default;
|
|
1079
1167
|
exports.interpolateObjects = interpolateObjects_default;
|
|
1080
1168
|
exports.isAnniversary = isAnniversary_default;
|
|
@@ -1095,6 +1183,7 @@ exports.parseEnv = parseEnv_default;
|
|
|
1095
1183
|
exports.parseFormData = parseFormData_default;
|
|
1096
1184
|
exports.parseIntStrict = parseIntStrict_default;
|
|
1097
1185
|
exports.parseUUID = UUID_default;
|
|
1186
|
+
exports.parseVersion = parseVersion_default;
|
|
1098
1187
|
exports.parseZodSchema = parseZodSchema_default;
|
|
1099
1188
|
exports.randomiseArray = randomiseArray_default;
|
|
1100
1189
|
exports.range = range_default;
|
package/dist/index.d.cts
CHANGED
|
@@ -3,6 +3,9 @@ import z, { ZodType, core, z as z$1 } from "zod";
|
|
|
3
3
|
//#region src/constants/NAMESPACE_EXPORT_REGEX.d.ts
|
|
4
4
|
declare const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
|
|
5
5
|
//#endregion
|
|
6
|
+
//#region src/constants/VERSION_NUMBER_REGEX.d.ts
|
|
7
|
+
declare const VERSION_NUMBER_REGEX: string;
|
|
8
|
+
//#endregion
|
|
6
9
|
//#region src/functions/arrayHelpers/fillArray.d.ts
|
|
7
10
|
/**
|
|
8
11
|
* Creates a new array where each element is the resolved result of the provided asynchronous callback.
|
|
@@ -282,6 +285,9 @@ type OptionalOnCondition<Condition extends boolean, ResolvedTypeIfTrue> = Condit
|
|
|
282
285
|
/** Represents the native Record's possible key type. */
|
|
283
286
|
type RecordKey = string | number | symbol;
|
|
284
287
|
//#endregion
|
|
288
|
+
//#region src/types/VersionType.d.ts
|
|
289
|
+
type VersionType = "major" | "minor" | "patch";
|
|
290
|
+
//#endregion
|
|
285
291
|
//#region src/functions/miscellaneous/createFormData.d.ts
|
|
286
292
|
type FormDataNullableResolutionStrategy = "stringify" | "empty" | "omit";
|
|
287
293
|
type FormDataArrayResolutionStrategy = "stringify" | "multiple";
|
|
@@ -698,4 +704,62 @@ declare function removeIndents(options: RemoveIndentsOptions): RemoveIndentsFunc
|
|
|
698
704
|
*/
|
|
699
705
|
declare function removeIndents(strings: TemplateStringsArray, ...interpolations: unknown[]): string;
|
|
700
706
|
//#endregion
|
|
701
|
-
|
|
707
|
+
//#region src/functions/versioning/determineVersionType.d.ts
|
|
708
|
+
/**
|
|
709
|
+
* Determines whether the given version is a major, minor, or patch version.
|
|
710
|
+
*
|
|
711
|
+
* @param version - The version number.
|
|
712
|
+
*
|
|
713
|
+
* @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
|
|
714
|
+
*/
|
|
715
|
+
declare function determineVersionType(version: string): VersionType;
|
|
716
|
+
//#endregion
|
|
717
|
+
//#region src/functions/versioning/getIndividualVersionNumbers.d.ts
|
|
718
|
+
/**
|
|
719
|
+
* Gets the individual version numbers from a given version number as a tuple of numbers.
|
|
720
|
+
*
|
|
721
|
+
* @param version - The version number.
|
|
722
|
+
*
|
|
723
|
+
* @returns A tuple of three numbers indicating `[major, minor, patch]`.
|
|
724
|
+
*/
|
|
725
|
+
declare function getIndividualVersionNumbers(version: string): [number, number, number];
|
|
726
|
+
//#endregion
|
|
727
|
+
//#region src/functions/versioning/incrementVersion.d.ts
|
|
728
|
+
interface IncrementVersionOptions {
|
|
729
|
+
/** Whether to omit the `v` prefix from the output version or not. */
|
|
730
|
+
omitPrefix?: boolean;
|
|
731
|
+
}
|
|
732
|
+
/**
|
|
733
|
+
* Increments the given input version depending on the given increment type.
|
|
734
|
+
*
|
|
735
|
+
* @param version - The version to increment
|
|
736
|
+
* @param incrementType - The type of increment. Can be one of the following:
|
|
737
|
+
* - `"major"`: Change the major version `v1.2.3` → `v2.0.0`
|
|
738
|
+
* - `"minor"`: Change the minor version `v1.2.3` → `v1.3.0`
|
|
739
|
+
* - `"patch"`: Change the patch version `v1.2.3` → `v1.2.4`
|
|
740
|
+
* @param options - Extra options to apply.
|
|
741
|
+
*
|
|
742
|
+
* @returns A new string representing the version with the increment applied.
|
|
743
|
+
*/
|
|
744
|
+
declare function incrementVersion(version: string, incrementType: VersionType, options?: IncrementVersionOptions): string;
|
|
745
|
+
//#endregion
|
|
746
|
+
//#region src/functions/versioning/parseVersion.d.ts
|
|
747
|
+
interface ParseVersionOptions {
|
|
748
|
+
/** Whether to omit the `v` prefix from the output version or not. */
|
|
749
|
+
omitPrefix?: boolean;
|
|
750
|
+
}
|
|
751
|
+
/**
|
|
752
|
+
* Parses a string and verifies it is a valid package version number.
|
|
753
|
+
*
|
|
754
|
+
* Valid formats: `X.Y.Z` or `vX.Y.Z`, where X, Y, and Z are non-negative integers.
|
|
755
|
+
*
|
|
756
|
+
* @param input - The version string to parse.
|
|
757
|
+
* @param options - Extra options to apply.
|
|
758
|
+
*
|
|
759
|
+
* @throws {DataError} If the input is not a valid version number.
|
|
760
|
+
*
|
|
761
|
+
* @returns The validated version number, prefixed with `v` if it was not already.
|
|
762
|
+
*/
|
|
763
|
+
declare function parseVersion(input: string, options?: ParseVersionOptions): string;
|
|
764
|
+
//#endregion
|
|
765
|
+
export { APIError, ArrayElement, CreateFormDataOptions, CreateFormDataOptionsNullableResolution, CreateFormDataOptionsUndefinedOrNullResolution, DataError, DeepReadonly, DisallowUndefined, Email, Env, FormDataArrayResolutionStrategy, FormDataNullableResolutionStrategy, HTTPErrorCode, IgnoreCase, IncrementVersionOptions, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, OptionalOnCondition, ParseVersionOptions, RecordKey, RemoveIndentsFunction, RemoveIndentsOptions, StringListToArrayOptions, UUID, VERSION_NUMBER_REGEX, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, determineVersionType, fillArray, formatDateAndTime, getIndividualVersionNumbers, getRandomNumber, getRecordKeys, httpErrorCodeLookup, incrementVersion, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, kebabToCamel, normaliseImportPath, normaliseIndents, normalizeImportPath, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEmail, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersion, parseZodSchema, randomiseArray, range, removeDuplicates, removeIndents, stringListToArray, stringToBoolean, truncate, wait };
|
package/dist/index.d.ts
CHANGED
|
@@ -3,6 +3,9 @@ import z, { ZodType, core, z as z$1 } from "zod";
|
|
|
3
3
|
//#region src/constants/NAMESPACE_EXPORT_REGEX.d.ts
|
|
4
4
|
declare const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
|
|
5
5
|
//#endregion
|
|
6
|
+
//#region src/constants/VERSION_NUMBER_REGEX.d.ts
|
|
7
|
+
declare const VERSION_NUMBER_REGEX: string;
|
|
8
|
+
//#endregion
|
|
6
9
|
//#region src/functions/arrayHelpers/fillArray.d.ts
|
|
7
10
|
/**
|
|
8
11
|
* Creates a new array where each element is the resolved result of the provided asynchronous callback.
|
|
@@ -282,6 +285,9 @@ type OptionalOnCondition<Condition extends boolean, ResolvedTypeIfTrue> = Condit
|
|
|
282
285
|
/** Represents the native Record's possible key type. */
|
|
283
286
|
type RecordKey = string | number | symbol;
|
|
284
287
|
//#endregion
|
|
288
|
+
//#region src/types/VersionType.d.ts
|
|
289
|
+
type VersionType = "major" | "minor" | "patch";
|
|
290
|
+
//#endregion
|
|
285
291
|
//#region src/functions/miscellaneous/createFormData.d.ts
|
|
286
292
|
type FormDataNullableResolutionStrategy = "stringify" | "empty" | "omit";
|
|
287
293
|
type FormDataArrayResolutionStrategy = "stringify" | "multiple";
|
|
@@ -698,4 +704,62 @@ declare function removeIndents(options: RemoveIndentsOptions): RemoveIndentsFunc
|
|
|
698
704
|
*/
|
|
699
705
|
declare function removeIndents(strings: TemplateStringsArray, ...interpolations: unknown[]): string;
|
|
700
706
|
//#endregion
|
|
701
|
-
|
|
707
|
+
//#region src/functions/versioning/determineVersionType.d.ts
|
|
708
|
+
/**
|
|
709
|
+
* Determines whether the given version is a major, minor, or patch version.
|
|
710
|
+
*
|
|
711
|
+
* @param version - The version number.
|
|
712
|
+
*
|
|
713
|
+
* @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
|
|
714
|
+
*/
|
|
715
|
+
declare function determineVersionType(version: string): VersionType;
|
|
716
|
+
//#endregion
|
|
717
|
+
//#region src/functions/versioning/getIndividualVersionNumbers.d.ts
|
|
718
|
+
/**
|
|
719
|
+
* Gets the individual version numbers from a given version number as a tuple of numbers.
|
|
720
|
+
*
|
|
721
|
+
* @param version - The version number.
|
|
722
|
+
*
|
|
723
|
+
* @returns A tuple of three numbers indicating `[major, minor, patch]`.
|
|
724
|
+
*/
|
|
725
|
+
declare function getIndividualVersionNumbers(version: string): [number, number, number];
|
|
726
|
+
//#endregion
|
|
727
|
+
//#region src/functions/versioning/incrementVersion.d.ts
|
|
728
|
+
interface IncrementVersionOptions {
|
|
729
|
+
/** Whether to omit the `v` prefix from the output version or not. */
|
|
730
|
+
omitPrefix?: boolean;
|
|
731
|
+
}
|
|
732
|
+
/**
|
|
733
|
+
* Increments the given input version depending on the given increment type.
|
|
734
|
+
*
|
|
735
|
+
* @param version - The version to increment
|
|
736
|
+
* @param incrementType - The type of increment. Can be one of the following:
|
|
737
|
+
* - `"major"`: Change the major version `v1.2.3` → `v2.0.0`
|
|
738
|
+
* - `"minor"`: Change the minor version `v1.2.3` → `v1.3.0`
|
|
739
|
+
* - `"patch"`: Change the patch version `v1.2.3` → `v1.2.4`
|
|
740
|
+
* @param options - Extra options to apply.
|
|
741
|
+
*
|
|
742
|
+
* @returns A new string representing the version with the increment applied.
|
|
743
|
+
*/
|
|
744
|
+
declare function incrementVersion(version: string, incrementType: VersionType, options?: IncrementVersionOptions): string;
|
|
745
|
+
//#endregion
|
|
746
|
+
//#region src/functions/versioning/parseVersion.d.ts
|
|
747
|
+
interface ParseVersionOptions {
|
|
748
|
+
/** Whether to omit the `v` prefix from the output version or not. */
|
|
749
|
+
omitPrefix?: boolean;
|
|
750
|
+
}
|
|
751
|
+
/**
|
|
752
|
+
* Parses a string and verifies it is a valid package version number.
|
|
753
|
+
*
|
|
754
|
+
* Valid formats: `X.Y.Z` or `vX.Y.Z`, where X, Y, and Z are non-negative integers.
|
|
755
|
+
*
|
|
756
|
+
* @param input - The version string to parse.
|
|
757
|
+
* @param options - Extra options to apply.
|
|
758
|
+
*
|
|
759
|
+
* @throws {DataError} If the input is not a valid version number.
|
|
760
|
+
*
|
|
761
|
+
* @returns The validated version number, prefixed with `v` if it was not already.
|
|
762
|
+
*/
|
|
763
|
+
declare function parseVersion(input: string, options?: ParseVersionOptions): string;
|
|
764
|
+
//#endregion
|
|
765
|
+
export { APIError, type ArrayElement, type CreateFormDataOptions, type CreateFormDataOptionsNullableResolution, type CreateFormDataOptionsUndefinedOrNullResolution, DataError, type DeepReadonly, type DisallowUndefined, type Email, type Env, type FormDataArrayResolutionStrategy, type FormDataNullableResolutionStrategy, type HTTPErrorCode, type IgnoreCase, type IncrementVersionOptions, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, type NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, type OptionalOnCondition, type ParseVersionOptions, type RecordKey, RemoveIndentsFunction, RemoveIndentsOptions, type StringListToArrayOptions, type UUID, VERSION_NUMBER_REGEX, type VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, determineVersionType, fillArray, formatDateAndTime, getIndividualVersionNumbers, getRandomNumber, getRecordKeys, httpErrorCodeLookup, incrementVersion, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, kebabToCamel, normaliseImportPath, normaliseIndents, normalizeImportPath, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEmail, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersion, parseZodSchema, randomiseArray, range, removeDuplicates, removeIndents, stringListToArray, stringToBoolean, truncate, wait };
|
package/dist/index.js
CHANGED
|
@@ -5,6 +5,11 @@ import path from "path";
|
|
|
5
5
|
const NAMESPACE_EXPORT_REGEX = "export\\s+\\*\\s+from";
|
|
6
6
|
var NAMESPACE_EXPORT_REGEX_default = NAMESPACE_EXPORT_REGEX;
|
|
7
7
|
|
|
8
|
+
//#endregion
|
|
9
|
+
//#region src/constants/VERSION_NUMBER_REGEX.ts
|
|
10
|
+
const VERSION_NUMBER_REGEX = "^(?:v)?(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$";
|
|
11
|
+
var VERSION_NUMBER_REGEX_default = VERSION_NUMBER_REGEX;
|
|
12
|
+
|
|
8
13
|
//#endregion
|
|
9
14
|
//#region src/functions/arrayHelpers/fillArray.ts
|
|
10
15
|
/**
|
|
@@ -1030,4 +1035,83 @@ function removeIndents(first, ...args) {
|
|
|
1030
1035
|
var removeIndents_default = removeIndents;
|
|
1031
1036
|
|
|
1032
1037
|
//#endregion
|
|
1033
|
-
|
|
1038
|
+
//#region src/functions/versioning/parseVersion.ts
|
|
1039
|
+
/**
|
|
1040
|
+
* Parses a string and verifies it is a valid package version number.
|
|
1041
|
+
*
|
|
1042
|
+
* Valid formats: `X.Y.Z` or `vX.Y.Z`, where X, Y, and Z are non-negative integers.
|
|
1043
|
+
*
|
|
1044
|
+
* @param input - The version string to parse.
|
|
1045
|
+
* @param options - Extra options to apply.
|
|
1046
|
+
*
|
|
1047
|
+
* @throws {DataError} If the input is not a valid version number.
|
|
1048
|
+
*
|
|
1049
|
+
* @returns The validated version number, prefixed with `v` if it was not already.
|
|
1050
|
+
*/
|
|
1051
|
+
function parseVersion(input, options) {
|
|
1052
|
+
if (!RegExp(VERSION_NUMBER_REGEX_default).test(input)) throw new DataError_default(input, `"${input}" is not a valid version number. Version numbers must be of the format "X.Y.Z" or "vX.Y.Z", where X, Y, and Z are non-negative integers.`, "INVALID_VERSION");
|
|
1053
|
+
if (options?.omitPrefix) return input.startsWith("v") ? input.slice(1) : input;
|
|
1054
|
+
return input.startsWith("v") ? input : `v${input}`;
|
|
1055
|
+
}
|
|
1056
|
+
var parseVersion_default = parseVersion;
|
|
1057
|
+
|
|
1058
|
+
//#endregion
|
|
1059
|
+
//#region src/functions/versioning/getIndividualVersionNumbers.ts
|
|
1060
|
+
/**
|
|
1061
|
+
* Gets the individual version numbers from a given version number as a tuple of numbers.
|
|
1062
|
+
*
|
|
1063
|
+
* @param version - The version number.
|
|
1064
|
+
*
|
|
1065
|
+
* @returns A tuple of three numbers indicating `[major, minor, patch]`.
|
|
1066
|
+
*/
|
|
1067
|
+
function getIndividualVersionNumbers(version) {
|
|
1068
|
+
return parseVersion_default(version, { omitPrefix: true }).split(".").map((versionNumber) => {
|
|
1069
|
+
return parseIntStrict_default(versionNumber);
|
|
1070
|
+
});
|
|
1071
|
+
}
|
|
1072
|
+
var getIndividualVersionNumbers_default = getIndividualVersionNumbers;
|
|
1073
|
+
|
|
1074
|
+
//#endregion
|
|
1075
|
+
//#region src/functions/versioning/determineVersionType.ts
|
|
1076
|
+
/**
|
|
1077
|
+
* Determines whether the given version is a major, minor, or patch version.
|
|
1078
|
+
*
|
|
1079
|
+
* @param version - The version number.
|
|
1080
|
+
*
|
|
1081
|
+
* @returns Either `"major"`, `"minor"`, or `"patch"`, depending on the version type.
|
|
1082
|
+
*/
|
|
1083
|
+
function determineVersionType(version) {
|
|
1084
|
+
const [_major, minor, patch] = getIndividualVersionNumbers_default(version);
|
|
1085
|
+
if (minor === 0 && patch === 0) return "major";
|
|
1086
|
+
if (patch === 0) return "minor";
|
|
1087
|
+
return "patch";
|
|
1088
|
+
}
|
|
1089
|
+
var determineVersionType_default = determineVersionType;
|
|
1090
|
+
|
|
1091
|
+
//#endregion
|
|
1092
|
+
//#region src/functions/versioning/incrementVersion.ts
|
|
1093
|
+
/**
|
|
1094
|
+
* Increments the given input version depending on the given increment type.
|
|
1095
|
+
*
|
|
1096
|
+
* @param version - The version to increment
|
|
1097
|
+
* @param incrementType - The type of increment. Can be one of the following:
|
|
1098
|
+
* - `"major"`: Change the major version `v1.2.3` → `v2.0.0`
|
|
1099
|
+
* - `"minor"`: Change the minor version `v1.2.3` → `v1.3.0`
|
|
1100
|
+
* - `"patch"`: Change the patch version `v1.2.3` → `v1.2.4`
|
|
1101
|
+
* @param options - Extra options to apply.
|
|
1102
|
+
*
|
|
1103
|
+
* @returns A new string representing the version with the increment applied.
|
|
1104
|
+
*/
|
|
1105
|
+
function incrementVersion(version, incrementType, options) {
|
|
1106
|
+
const [major, minor, patch] = getIndividualVersionNumbers_default(version);
|
|
1107
|
+
const newVersion = {
|
|
1108
|
+
major: `${major + 1}.0.0`,
|
|
1109
|
+
minor: `${major}.${minor + 1}.0`,
|
|
1110
|
+
patch: `${major}.${minor}.${patch + 1}`
|
|
1111
|
+
}[incrementType];
|
|
1112
|
+
return parseVersion_default(newVersion, { omitPrefix: options?.omitPrefix });
|
|
1113
|
+
}
|
|
1114
|
+
var incrementVersion_default = incrementVersion;
|
|
1115
|
+
|
|
1116
|
+
//#endregion
|
|
1117
|
+
export { APIError_default as APIError, DataError_default as DataError, NAMESPACE_EXPORT_REGEX_default as NAMESPACE_EXPORT_REGEX, VERSION_NUMBER_REGEX_default as VERSION_NUMBER_REGEX, addDaysToDate_default as addDaysToDate, appendSemicolon_default as appendSemicolon, camelToKebab_default as camelToKebab, convertFileToBase64_default as convertFileToBase64, createFormData_default as createFormData, createTemplateStringsArray_default as createTemplateStringsArray, deepCopy_default as deepCopy, deepFreeze_default as deepFreeze, determineVersionType_default as determineVersionType, fillArray_default as fillArray, formatDateAndTime_default as formatDateAndTime, getIndividualVersionNumbers_default as getIndividualVersionNumbers, getRandomNumber_default as getRandomNumber, getRecordKeys_default as getRecordKeys, httpErrorCodeLookup, incrementVersion_default as incrementVersion, interpolate_default as interpolate, interpolateObjects_default as interpolateObjects, isAnniversary_default as isAnniversary, isLeapYear_default as isLeapYear, isMonthlyMultiple_default as isMonthlyMultiple, isOrdered_default as isOrdered, isSameDate_default as isSameDate, kebabToCamel_default as kebabToCamel, normaliseImportPath, normaliseIndents_default as normaliseIndents, normalizeImportPath_default as normalizeImportPath, normalizeIndents, omitProperties_default as omitProperties, paralleliseArrays_default as paralleliseArrays, parseBoolean_default as parseBoolean, Email_default as parseEmail, parseEnv_default as parseEnv, parseFormData_default as parseFormData, parseIntStrict_default as parseIntStrict, UUID_default as parseUUID, parseVersion_default as parseVersion, parseZodSchema_default as parseZodSchema, randomiseArray_default as randomiseArray, range_default as range, removeDuplicates_default as removeDuplicates, removeIndents_default as removeIndents, stringListToArray_default as stringListToArray, stringToBoolean, truncate_default as truncate, wait_default as wait };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alextheman/utility",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.9.0",
|
|
4
4
|
"description": "Helpful utility functions",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"zod": "^4.1.13"
|
|
20
20
|
},
|
|
21
21
|
"devDependencies": {
|
|
22
|
-
"@alextheman/eslint-plugin": "^4.8.
|
|
22
|
+
"@alextheman/eslint-plugin": "^4.8.6",
|
|
23
23
|
"@types/node": "^25.0.1",
|
|
24
24
|
"dotenv-cli": "^11.0.0",
|
|
25
25
|
"eslint": "^9.39.1",
|