@alextheman/utility 3.8.0 → 3.9.0

package/README.md

@@ -24,122 +24,3 @@ import { formatDateAndTime } from "@alextheman/utility";
 const myVariable: NonUndefined<string> = formatDateAndTime(new Date());
 // ...
 ```
-
-## Contributing
-
-### Creating a function
-#### Setup
-To create a new function in the package, you must first checkout a new branch. Do **not** commit directly on main.
-
-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.
-
-```typescript
-function myFunction(firstArg: ArgType): ReturnType {
-  // Implementation goes here
-}
-
-export default myFunction
-```
-
-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.
-
-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:
-
-```typescript
-export { default as addDaysToDate } from "src/functions/addDaysToDate";
-export { default as appendSemicolon } from "src/functions/appendSemicolon";
-export { default as camelToKebab } from "src/functions/camelToKebab";
-export { default as convertFileToBase64 } from "src/functions/convertFileToBase64";
-export { default as createFormData } from "src/functions/createFormData";
-export { default as fillArray } from "src/functions/fillArray";
-export { default as formatDateAndTime } from "src/functions/formatDateAndTime";
-// ...
-export { default as myFunction } from "src/functions/myFunction";
-// ...
-
-export type { MyFunctionOptions } from "src/functions/myFunction";
-```
-
-#### Testing
-
-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.
-
-Tests are generally structured in the following way:
-
-```typescript
-import { describe, expect, test } from "vitest";
-
-import myFunction from "src/functions/myFunction";
-
-describe("myFunction", () => {
-  test("Does a thing", () => {
-    expect(myFunction("hello")).toBe("world");
-  });
-  test("Does another thing", () => {
-    expect(myFunction("one")).toBe("two");
-  });
-  // ...
-});
-```
-
-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.
-
-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.
-
-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.
-
-```typescript
-describe("removeDuplicates", () => {
-  describe("Mutation checks", () => {
-    test("Does not mutate the original array", () => {
-      const inputArray = Object.freeze([1, 1, 2, 3, 4]);
-      // since the array has been frozen, this will give a TypeError if it tries to mutate the inputArray.
-      removeDuplicates(inputArray);
-      expect(inputArray).toEqual([1, 1, 2, 3, 4]);
-    });
-  });
-});
-```
-
-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:
-
-```typescript
-describe("removeDuplicates", () => {
-  describe("Mutation checks", () => {
-    test("Returns an array with a new reference in memory", () => {
-      const inputArray = [1, 1, 2, 3, 4];
-      const outputArray = removeDuplicates(inputArray);
-      expect(outputArray).not.toBe(inputArray);
-    });
-  });
-});
-```
-
-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.
-
-### Creating a type
-
-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:
-
-```typescript
-import type { OptionalOnCondition } from "src/types";
-
-import { describe, expectTypeOf, test } from "vitest";
-
-describe("OptionalOnCondition", () => {
-  test("Resolves to the type of the second type argument if first type argument is true", () => {
-    expectTypeOf<OptionalOnCondition<true, string>>().toEqualTypeOf<string>();
-  });
-  test("Resolves to a union of the second type and undefined if first type argument is false", () => {
-    expectTypeOf<OptionalOnCondition<false, string>>().toEqualTypeOf<string | undefined>();
-  });
-});
-```
-
-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.
-
-### Publishing
-
-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.
-
-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

@@ -1117,6 +1117,31 @@ function determineVersionType(version) {
 }
 var determineVersionType_default = determineVersionType;
 
+//#endregion
+//#region src/functions/versioning/incrementVersion.ts
+/**
+* Increments the given input version depending on the given increment type.
+*
+* @param version - The version to increment
+* @param incrementType - The type of increment. Can be one of the following:
+* - `"major"`: Change the major version `v1.2.3` → `v2.0.0`
+* - `"minor"`: Change the minor version `v1.2.3` → `v1.3.0`
+* - `"patch"`: Change the patch version `v1.2.3` → `v1.2.4`
+* @param options - Extra options to apply.
+*
+* @returns A new string representing the version with the increment applied.
+*/
+function incrementVersion(version, incrementType, options) {
+	const [major, minor, patch] = getIndividualVersionNumbers_default(version);
+	const newVersion = {
+		major: `${major + 1}.0.0`,
+		minor: `${major}.${minor + 1}.0`,
+		patch: `${major}.${minor}.${patch + 1}`
+	}[incrementType];
+	return parseVersion_default(newVersion, { omitPrefix: options?.omitPrefix });
+}
+var incrementVersion_default = incrementVersion;
+
 //#endregion
 exports.APIError = APIError_default;
 exports.DataError = DataError_default;
@@ -1137,6 +1162,7 @@ exports.getIndividualVersionNumbers = getIndividualVersionNumbers_default;
 exports.getRandomNumber = getRandomNumber_default;
 exports.getRecordKeys = getRecordKeys_default;
 exports.httpErrorCodeLookup = httpErrorCodeLookup;
+exports.incrementVersion = incrementVersion_default;
 exports.interpolate = interpolate_default;
 exports.interpolateObjects = interpolateObjects_default;
 exports.isAnniversary = isAnniversary_default;

package/dist/index.d.cts

@@ -285,6 +285,9 @@ type OptionalOnCondition<Condition extends boolean, ResolvedTypeIfTrue> = Condit
 /** Represents the native Record's possible key type. */
 type RecordKey = string | number | symbol;
 //#endregion
+//#region src/types/VersionType.d.ts
+type VersionType = "major" | "minor" | "patch";
+//#endregion
 //#region src/functions/miscellaneous/createFormData.d.ts
 type FormDataNullableResolutionStrategy = "stringify" | "empty" | "omit";
 type FormDataArrayResolutionStrategy = "stringify" | "multiple";
@@ -702,7 +705,6 @@ declare function removeIndents(options: RemoveIndentsOptions): RemoveIndentsFunc
 declare function removeIndents(strings: TemplateStringsArray, ...interpolations: unknown[]): string;
 //#endregion
 //#region src/functions/versioning/determineVersionType.d.ts
-type VersionType = "major" | "minor" | "patch";
 /**
  * Determines whether the given version is a major, minor, or patch version.
  *
@@ -722,8 +724,28 @@ declare function determineVersionType(version: string): VersionType;
  */
 declare function getIndividualVersionNumbers(version: string): [number, number, number];
 //#endregion
+//#region src/functions/versioning/incrementVersion.d.ts
+interface IncrementVersionOptions {
+  /** Whether to omit the `v` prefix from the output version or not. */
+  omitPrefix?: boolean;
+}
+/**
+ * Increments the given input version depending on the given increment type.
+ *
+ * @param version - The version to increment
+ * @param incrementType - The type of increment. Can be one of the following:
+ * - `"major"`: Change the major version `v1.2.3` → `v2.0.0`
+ * - `"minor"`: Change the minor version `v1.2.3` → `v1.3.0`
+ * - `"patch"`: Change the patch version `v1.2.3` → `v1.2.4`
+ * @param options - Extra options to apply.
+ *
+ * @returns A new string representing the version with the increment applied.
+ */
+declare function incrementVersion(version: string, incrementType: VersionType, options?: IncrementVersionOptions): string;
+//#endregion
 //#region src/functions/versioning/parseVersion.d.ts
 interface ParseVersionOptions {
+  /** Whether to omit the `v` prefix from the output version or not. */
   omitPrefix?: boolean;
 }
 /**
@@ -740,4 +762,4 @@ interface ParseVersionOptions {
  */
 declare function parseVersion(input: string, options?: ParseVersionOptions): string;
 //#endregion
-export { APIError, ArrayElement, CreateFormDataOptions, CreateFormDataOptionsNullableResolution, CreateFormDataOptionsUndefinedOrNullResolution, DataError, DeepReadonly, DisallowUndefined, Email, Env, FormDataArrayResolutionStrategy, FormDataNullableResolutionStrategy, HTTPErrorCode, IgnoreCase, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, OptionalOnCondition, RecordKey, RemoveIndentsFunction, RemoveIndentsOptions, StringListToArrayOptions, UUID, VERSION_NUMBER_REGEX, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, determineVersionType, fillArray, formatDateAndTime, getIndividualVersionNumbers, getRandomNumber, getRecordKeys, httpErrorCodeLookup, 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 };
+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

@@ -285,6 +285,9 @@ type OptionalOnCondition<Condition extends boolean, ResolvedTypeIfTrue> = Condit
 /** Represents the native Record's possible key type. */
 type RecordKey = string | number | symbol;
 //#endregion
+//#region src/types/VersionType.d.ts
+type VersionType = "major" | "minor" | "patch";
+//#endregion
 //#region src/functions/miscellaneous/createFormData.d.ts
 type FormDataNullableResolutionStrategy = "stringify" | "empty" | "omit";
 type FormDataArrayResolutionStrategy = "stringify" | "multiple";
@@ -702,7 +705,6 @@ declare function removeIndents(options: RemoveIndentsOptions): RemoveIndentsFunc
 declare function removeIndents(strings: TemplateStringsArray, ...interpolations: unknown[]): string;
 //#endregion
 //#region src/functions/versioning/determineVersionType.d.ts
-type VersionType = "major" | "minor" | "patch";
 /**
  * Determines whether the given version is a major, minor, or patch version.
  *
@@ -722,8 +724,28 @@ declare function determineVersionType(version: string): VersionType;
  */
 declare function getIndividualVersionNumbers(version: string): [number, number, number];
 //#endregion
+//#region src/functions/versioning/incrementVersion.d.ts
+interface IncrementVersionOptions {
+  /** Whether to omit the `v` prefix from the output version or not. */
+  omitPrefix?: boolean;
+}
+/**
+ * Increments the given input version depending on the given increment type.
+ *
+ * @param version - The version to increment
+ * @param incrementType - The type of increment. Can be one of the following:
+ * - `"major"`: Change the major version `v1.2.3` → `v2.0.0`
+ * - `"minor"`: Change the minor version `v1.2.3` → `v1.3.0`
+ * - `"patch"`: Change the patch version `v1.2.3` → `v1.2.4`
+ * @param options - Extra options to apply.
+ *
+ * @returns A new string representing the version with the increment applied.
+ */
+declare function incrementVersion(version: string, incrementType: VersionType, options?: IncrementVersionOptions): string;
+//#endregion
 //#region src/functions/versioning/parseVersion.d.ts
 interface ParseVersionOptions {
+  /** Whether to omit the `v` prefix from the output version or not. */
   omitPrefix?: boolean;
 }
 /**
@@ -740,4 +762,4 @@ interface ParseVersionOptions {
  */
 declare function parseVersion(input: string, options?: ParseVersionOptions): string;
 //#endregion
-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, KebabToCamelOptions, NAMESPACE_EXPORT_REGEX, type NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, type OptionalOnCondition, type RecordKey, RemoveIndentsFunction, RemoveIndentsOptions, type StringListToArrayOptions, type UUID, VERSION_NUMBER_REGEX, VersionType, addDaysToDate, appendSemicolon, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, determineVersionType, fillArray, formatDateAndTime, getIndividualVersionNumbers, getRandomNumber, getRecordKeys, httpErrorCodeLookup, 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 };
+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

@@ -1089,4 +1089,29 @@ function determineVersionType(version) {
 var determineVersionType_default = determineVersionType;
 
 //#endregion
-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, 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 };
+//#region src/functions/versioning/incrementVersion.ts
+/**
+* Increments the given input version depending on the given increment type.
+*
+* @param version - The version to increment
+* @param incrementType - The type of increment. Can be one of the following:
+* - `"major"`: Change the major version `v1.2.3` → `v2.0.0`
+* - `"minor"`: Change the minor version `v1.2.3` → `v1.3.0`
+* - `"patch"`: Change the patch version `v1.2.3` → `v1.2.4`
+* @param options - Extra options to apply.
+*
+* @returns A new string representing the version with the increment applied.
+*/
+function incrementVersion(version, incrementType, options) {
+	const [major, minor, patch] = getIndividualVersionNumbers_default(version);
+	const newVersion = {
+		major: `${major + 1}.0.0`,
+		minor: `${major}.${minor + 1}.0`,
+		patch: `${major}.${minor}.${patch + 1}`
+	}[incrementType];
+	return parseVersion_default(newVersion, { omitPrefix: options?.omitPrefix });
+}
+var incrementVersion_default = incrementVersion;
+
+//#endregion
+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

@@ -1,6 +1,6 @@
 {
   "name": "@alextheman/utility",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "description": "Helpful utility functions",
   "repository": {
     "type": "git",