@myparcel-dev/ts-utils 1.15.0

package/README.md

@@ -0,0 +1,128 @@
+# TypeScript Utilities
+
+This is a collection of TypeScript utilities that we reuse across all TS projects.
+
+[![npm](https://img.shields.io/npm/v/@myparcel-dev/ts-utils?labelColor=27272A&logoColor=FFFFFF&style=for-the-badge&color=CC3534&logo=npm)](https://www.npmjs.com/package/@myparcel-dev/ts-utils/)
+[![Coverage Status](https://img.shields.io/codecov/c/github/myparcelnl/ts-utils?logo=codecov&style=for-the-badge)](https://codecov.io/gh/myparcelnl/ts-utils)
+
+## Installation
+
+**Using Yarn**
+
+```bash
+yarn add @myparcel-dev/ts-utils
+```
+
+**Using pnpm**
+
+```bash
+pnpm add @myparcel-dev/ts-utils
+```
+
+**Using npm**
+
+```bash
+npm install @myparcel-dev/ts-utils
+```
+
+> ⚠️ Note: You can install this package as a dev dependency if you only use the types.
+
+## Contents
+
+### [Type guards](src/type-guards)
+
+#### [isEnumValue](src/type-guards/isEnumValue.ts)
+
+Type guard for checking if a value is a key of the given enum.
+
+```ts
+import {isEnumValue} from '@myparcel-dev/ts-utils';
+
+enum MyEnum {
+  A = 'A',
+  B = 'B',
+}
+
+const value = 'A';
+
+if (isEnumValue(MyEnum, value)) {
+  // value is of type MyEnum.A
+}
+```
+
+#### [isInArray](src/type-guards/isInArray.ts)
+
+Type guard which checks if given value is inside an array.
+
+```ts
+import {isInArray} from '@myparcel-dev/ts-utils';
+
+const value = 'A'; // value is of type 'A'
+
+isInArray(value, ['A', 'B']) // true
+```
+
+#### [isOfType](src/type-guards/isOfType.ts)
+
+Type guard for checking if an object value is of a specific type by checking if a given K exists.
+
+```ts
+import {isOfType} from '@myparcel-dev/ts-utils';
+
+interface BaseObject {
+  a: string;
+  b: number;
+}
+
+interface ObjectWithC extends BaseObject {
+  c: string;
+}
+
+const value = {
+  a: 'a',
+  b: 1,
+  c: 'c',
+};
+
+if (isOfType<ObjectWithC>(value, 'c')) {
+  // value is of type ObjectWithC
+}
+```
+
+### [Types](src/types)
+
+### [Utils](src/utils)
+
+#### [asyncEvery](src/utils/asyncEvery.ts)
+
+Returns true if every element in the array satisfies the provided predicate.
+
+```ts
+import {asyncEvery} from '@myparcel-dev/ts-utils';
+
+await asyncEvery([1, 2, 3, 4, 5], async (value) => value > 0); // true
+await asyncEvery([1, 2, 3, 4, 5], async (value) => value > 1); // false
+```
+
+#### [asyncSome](src/utils/asyncSome.ts)
+
+Returns true if some element in the array satisfies the provided predicate.
+
+```ts
+import {asyncSome} from '@myparcel-dev/ts-utils';
+
+await asyncSome([1, 2, 3, 4, 5], async (value) => value > 4); // true
+await asyncSome([1, 2, 3, 4, 5], async (value) => value > 5); // false
+```
+
+#### [toArray](src/utils/toArray.ts)
+
+Converts a value to an array. If the value is already an array, it will be returned as is.
+
+```ts
+import {toArray} from '@myparcel-dev/ts-utils';
+
+toArray('plain value'); // ['plain value']
+
+toArray(['already an array']); // ['already an array']
+```

package/dist/index.cjs

@@ -0,0 +1,118 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  asyncEvery: () => asyncEvery,
+  asyncSome: () => asyncSome,
+  isEnumValue: () => isEnumValue,
+  isInArray: () => isInArray,
+  isOfType: () => isOfType,
+  isUndefined: () => isUndefined,
+  objectIsEqual: () => objectIsEqual,
+  partitionArray: () => partitionArray,
+  removePropertiesWith: () => removePropertiesWith,
+  toArray: () => toArray
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/type-guards/isEnumValue.ts
+function isEnumValue(key, enumObject) {
+  return Object.values(enumObject).includes(key);
+}
+
+// src/type-guards/isInArray.ts
+var isInArray = (value, array) => array.includes(value);
+
+// src/type-guards/isOfType.ts
+function isOfType(value, property) {
+  return value?.[property] !== void 0;
+}
+
+// src/utils/asyncEvery.ts
+var asyncEvery = async (arr, predicate) => {
+  for (let i = 0; i < arr.length; i++) {
+    if (!await predicate(arr[i], i, arr)) {
+      return false;
+    }
+  }
+  return true;
+};
+
+// src/utils/asyncSome.ts
+var asyncSome = async (arr, predicate) => {
+  for (let i = 0; i < arr.length; i++) {
+    if (await predicate(arr[i], i, arr)) {
+      return true;
+    }
+  }
+  return false;
+};
+
+// src/utils/isUndefined.ts
+var isUndefined = (value) => value === void 0;
+
+// src/utils/objectIsEqual.ts
+var objectIsEqual = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+// src/utils/partitionArray.ts
+var partitionArray = (array, predicate) => {
+  return (array ?? []).reduce(
+    (acc, value) => {
+      acc[predicate(value) ? 0 : 1].push(value);
+      return acc;
+    },
+    [[], []]
+  );
+};
+
+// src/utils/removePropertiesWith.ts
+var removePropertiesWith = (object, predicate) => {
+  return Object.entries(object).reduce((acc, [key, value]) => {
+    if (!predicate(value)) {
+      acc[key] = value;
+    }
+    return acc;
+  }, {});
+};
+
+// src/utils/toArray.ts
+var toArray = (itemOrItems, separator) => {
+  if (itemOrItems === null || itemOrItems === void 0) {
+    return [];
+  }
+  if (separator && typeof itemOrItems === "string") {
+    return itemOrItems.split(separator);
+  }
+  return Array.isArray(itemOrItems) ? itemOrItems : [itemOrItems];
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  asyncEvery,
+  asyncSome,
+  isEnumValue,
+  isInArray,
+  isOfType,
+  isUndefined,
+  objectIsEqual,
+  partitionArray,
+  removePropertiesWith,
+  toArray
+});

package/dist/index.d.cts

@@ -0,0 +1,135 @@
+/**
+ * Type guard for checking if a value is a key of the given enum.
+ */
+declare function isEnumValue<T extends Record<string, unknown>>(key: unknown, enumObject: T): key is T[keyof T];
+
+/**
+ * Type guard which checks if given value is inside an array.
+ */
+declare const isInArray: <T extends readonly any[]>(value: any, array: T) => value is T[number];
+
+/**
+ * Type guard for checking if an object value is of a specific type by checking if a given property exists.
+ */
+declare function isOfType<T>(value: any, property: keyof T): value is T;
+
+/**
+ * Forcibly type an array to have at least one element.
+ */
+type ArrayWithOneOrMore<T> = {
+    0: T;
+} & T[];
+
+/**
+ * Return a new record only with the keys whose values are assignable to the given type. If no keys are assignable to the given type, the resulting record must be empty.
+ */
+type ExtractRecord<T, U> = {
+    [K in keyof T as T[K] extends U ? K : never]: T[K];
+};
+
+/**
+ * Extracts the keys of a record whose values are assignable to the given type.
+ */
+type ExtractRecordKeys<T extends Record<any, any>, U> = keyof ExtractRecord<T, U>;
+
+type MakeOptional<T, K extends string | keyof T> = K extends keyof T ? Omit<T, K> & Partial<Pick<T, K>> : T;
+
+/**
+ * Makes a type nullable or be undefined.
+ */
+type Maybe<T> = T | null | undefined;
+
+/**
+ * A type for an instantiable class.
+ */
+type Newable<T> = new (...args: any[]) => T;
+
+/**
+ * Allow a single value or an array of values.
+ */
+type OneOrMore<T> = T | T[];
+
+type PromiseOr<T> = T | Promise<T>;
+
+/**
+ * Allows
+ */
+type ReadonlyOr<T> = T | Readonly<T>;
+
+/**
+ * Recursively makes all properties of an object optional.
+ */
+type RecursivePartial<T> = {
+    [P in keyof T]?: T[P] extends (infer U)[] ? RecursivePartial<U>[] : T[P] extends object | undefined ? RecursivePartial<T[P]> : T[P];
+};
+
+/**
+ * Recursively makes all properties of an object required.
+ */
+type RecursiveRequired<T> = {
+    [P in keyof T]-?: T[P] extends (infer U)[] ? RecursiveRequired<U>[] : T[P] extends object | undefined ? RecursiveRequired<T[P]> : T[P];
+};
+
+type Replace<T, K extends keyof T, TReplace> = Pick<T, Exclude<keyof T, K>> & {
+    [P in K]: TReplace;
+};
+
+/**
+ * Makes all properties of an object optional except the ones specified.
+ */
+type RequireOnly<K, T extends keyof K> = Required<Pick<K, T>> & Partial<Omit<K, T>>;
+
+/**
+ * Resolves the type of given promise.
+ */
+type ResolvePromise<T extends Promise<any>> = T extends Promise<infer U> ? U : never;
+
+/**
+ * Inverts a map type so that the values become the keys and the keys become the values.
+ */
+type ReverseMap<T extends Record<keyof T, keyof any>> = {
+    [P in T[keyof T]]: {
+        [K in keyof T]: T[K] extends P ? K : never;
+    }[keyof T];
+};
+
+/**
+ * Get the values of a type
+ */
+type ValueOf<T extends Record<string, unknown>> = T[keyof T];
+
+type MakeRequired<Type, Keys extends keyof Type> = Omit<Type, Keys> & Required<Pick<Type, Keys>>;
+
+/**
+ * Returns true if every element in the array satisfies the provided predicate.
+ */
+declare const asyncEvery: <A>(arr: A[], predicate: (value: A, index: number, array: A[]) => PromiseOr<boolean>) => Promise<boolean>;
+
+/**
+ * Returns true if some element in the array satisfies the provided predicate.
+ */
+declare const asyncSome: <A>(arr: A[], predicate: (value: A, index: number, array: A[]) => PromiseOr<boolean>) => Promise<boolean>;
+
+/**
+ * Returns true if given value is undefined.
+ */
+declare const isUndefined: (value: unknown) => value is undefined;
+
+/**
+ * Compares two objects and returns true if they are equal
+ */
+declare const objectIsEqual: (a: unknown, b: unknown) => boolean;
+
+declare const partitionArray: <I>(array: I[] | null | undefined, predicate: (item: I) => boolean) => I[][];
+
+/**
+ * Removes keys and values from an object if predicate(value) returns true
+ */
+declare const removePropertiesWith: <T extends Record<string, unknown>>(object: T, predicate: (value: unknown) => boolean | Promise<boolean>) => Omit<T, keyof T>;
+
+/**
+ * Convert input to an array, if it's not already an array.
+ */
+declare const toArray: <T>(itemOrItems: OneOrMore<T>, separator?: string) => T[];
+
+export { type ArrayWithOneOrMore, type ExtractRecord, type ExtractRecordKeys, type MakeOptional, type MakeRequired, type Maybe, type Newable, type OneOrMore, type PromiseOr, type ReadonlyOr, type RecursivePartial, type RecursiveRequired, type Replace, type RequireOnly, type ResolvePromise, type ReverseMap, type ValueOf, asyncEvery, asyncSome, isEnumValue, isInArray, isOfType, isUndefined, objectIsEqual, partitionArray, removePropertiesWith, toArray };

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Type guard for checking if a value is a key of the given enum.
+ */
+declare function isEnumValue<T extends Record<string, unknown>>(key: unknown, enumObject: T): key is T[keyof T];
+
+/**
+ * Type guard which checks if given value is inside an array.
+ */
+declare const isInArray: <T extends readonly any[]>(value: any, array: T) => value is T[number];
+
+/**
+ * Type guard for checking if an object value is of a specific type by checking if a given property exists.
+ */
+declare function isOfType<T>(value: any, property: keyof T): value is T;
+
+/**
+ * Forcibly type an array to have at least one element.
+ */
+type ArrayWithOneOrMore<T> = {
+    0: T;
+} & T[];
+
+/**
+ * Return a new record only with the keys whose values are assignable to the given type. If no keys are assignable to the given type, the resulting record must be empty.
+ */
+type ExtractRecord<T, U> = {
+    [K in keyof T as T[K] extends U ? K : never]: T[K];
+};
+
+/**
+ * Extracts the keys of a record whose values are assignable to the given type.
+ */
+type ExtractRecordKeys<T extends Record<any, any>, U> = keyof ExtractRecord<T, U>;
+
+type MakeOptional<T, K extends string | keyof T> = K extends keyof T ? Omit<T, K> & Partial<Pick<T, K>> : T;
+
+/**
+ * Makes a type nullable or be undefined.
+ */
+type Maybe<T> = T | null | undefined;
+
+/**
+ * A type for an instantiable class.
+ */
+type Newable<T> = new (...args: any[]) => T;
+
+/**
+ * Allow a single value or an array of values.
+ */
+type OneOrMore<T> = T | T[];
+
+type PromiseOr<T> = T | Promise<T>;
+
+/**
+ * Allows
+ */
+type ReadonlyOr<T> = T | Readonly<T>;
+
+/**
+ * Recursively makes all properties of an object optional.
+ */
+type RecursivePartial<T> = {
+    [P in keyof T]?: T[P] extends (infer U)[] ? RecursivePartial<U>[] : T[P] extends object | undefined ? RecursivePartial<T[P]> : T[P];
+};
+
+/**
+ * Recursively makes all properties of an object required.
+ */
+type RecursiveRequired<T> = {
+    [P in keyof T]-?: T[P] extends (infer U)[] ? RecursiveRequired<U>[] : T[P] extends object | undefined ? RecursiveRequired<T[P]> : T[P];
+};
+
+type Replace<T, K extends keyof T, TReplace> = Pick<T, Exclude<keyof T, K>> & {
+    [P in K]: TReplace;
+};
+
+/**
+ * Makes all properties of an object optional except the ones specified.
+ */
+type RequireOnly<K, T extends keyof K> = Required<Pick<K, T>> & Partial<Omit<K, T>>;
+
+/**
+ * Resolves the type of given promise.
+ */
+type ResolvePromise<T extends Promise<any>> = T extends Promise<infer U> ? U : never;
+
+/**
+ * Inverts a map type so that the values become the keys and the keys become the values.
+ */
+type ReverseMap<T extends Record<keyof T, keyof any>> = {
+    [P in T[keyof T]]: {
+        [K in keyof T]: T[K] extends P ? K : never;
+    }[keyof T];
+};
+
+/**
+ * Get the values of a type
+ */
+type ValueOf<T extends Record<string, unknown>> = T[keyof T];
+
+type MakeRequired<Type, Keys extends keyof Type> = Omit<Type, Keys> & Required<Pick<Type, Keys>>;
+
+/**
+ * Returns true if every element in the array satisfies the provided predicate.
+ */
+declare const asyncEvery: <A>(arr: A[], predicate: (value: A, index: number, array: A[]) => PromiseOr<boolean>) => Promise<boolean>;
+
+/**
+ * Returns true if some element in the array satisfies the provided predicate.
+ */
+declare const asyncSome: <A>(arr: A[], predicate: (value: A, index: number, array: A[]) => PromiseOr<boolean>) => Promise<boolean>;
+
+/**
+ * Returns true if given value is undefined.
+ */
+declare const isUndefined: (value: unknown) => value is undefined;
+
+/**
+ * Compares two objects and returns true if they are equal
+ */
+declare const objectIsEqual: (a: unknown, b: unknown) => boolean;
+
+declare const partitionArray: <I>(array: I[] | null | undefined, predicate: (item: I) => boolean) => I[][];
+
+/**
+ * Removes keys and values from an object if predicate(value) returns true
+ */
+declare const removePropertiesWith: <T extends Record<string, unknown>>(object: T, predicate: (value: unknown) => boolean | Promise<boolean>) => Omit<T, keyof T>;
+
+/**
+ * Convert input to an array, if it's not already an array.
+ */
+declare const toArray: <T>(itemOrItems: OneOrMore<T>, separator?: string) => T[];
+
+export { type ArrayWithOneOrMore, type ExtractRecord, type ExtractRecordKeys, type MakeOptional, type MakeRequired, type Maybe, type Newable, type OneOrMore, type PromiseOr, type ReadonlyOr, type RecursivePartial, type RecursiveRequired, type Replace, type RequireOnly, type ResolvePromise, type ReverseMap, type ValueOf, asyncEvery, asyncSome, isEnumValue, isInArray, isOfType, isUndefined, objectIsEqual, partitionArray, removePropertiesWith, toArray };

package/dist/index.js

@@ -0,0 +1,82 @@
+// src/type-guards/isEnumValue.ts
+function isEnumValue(key, enumObject) {
+  return Object.values(enumObject).includes(key);
+}
+
+// src/type-guards/isInArray.ts
+var isInArray = (value, array) => array.includes(value);
+
+// src/type-guards/isOfType.ts
+function isOfType(value, property) {
+  return value?.[property] !== void 0;
+}
+
+// src/utils/asyncEvery.ts
+var asyncEvery = async (arr, predicate) => {
+  for (let i = 0; i < arr.length; i++) {
+    if (!await predicate(arr[i], i, arr)) {
+      return false;
+    }
+  }
+  return true;
+};
+
+// src/utils/asyncSome.ts
+var asyncSome = async (arr, predicate) => {
+  for (let i = 0; i < arr.length; i++) {
+    if (await predicate(arr[i], i, arr)) {
+      return true;
+    }
+  }
+  return false;
+};
+
+// src/utils/isUndefined.ts
+var isUndefined = (value) => value === void 0;
+
+// src/utils/objectIsEqual.ts
+var objectIsEqual = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+// src/utils/partitionArray.ts
+var partitionArray = (array, predicate) => {
+  return (array ?? []).reduce(
+    (acc, value) => {
+      acc[predicate(value) ? 0 : 1].push(value);
+      return acc;
+    },
+    [[], []]
+  );
+};
+
+// src/utils/removePropertiesWith.ts
+var removePropertiesWith = (object, predicate) => {
+  return Object.entries(object).reduce((acc, [key, value]) => {
+    if (!predicate(value)) {
+      acc[key] = value;
+    }
+    return acc;
+  }, {});
+};
+
+// src/utils/toArray.ts
+var toArray = (itemOrItems, separator) => {
+  if (itemOrItems === null || itemOrItems === void 0) {
+    return [];
+  }
+  if (separator && typeof itemOrItems === "string") {
+    return itemOrItems.split(separator);
+  }
+  return Array.isArray(itemOrItems) ? itemOrItems : [itemOrItems];
+};
+export {
+  asyncEvery,
+  asyncSome,
+  isEnumValue,
+  isInArray,
+  isOfType,
+  isUndefined,
+  objectIsEqual,
+  partitionArray,
+  removePropertiesWith,
+  toArray
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@myparcel-dev/ts-utils",
+  "version": "1.15.0",
+  "description": "TypeScript utilities",
+  "keywords": [
+    "typescript",
+    "utility",
+    "utils",
+    "type-guard"
+  ],
+  "license": "MIT",
+  "author": "Edie Lemoine <edie@myparcel.nl>",
+  "type": "module",
+  "exports": {
+    "require": "./dist/index.cjs",
+    "import": "./dist/index.js"
+  },
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --dts --format esm,cjs",
+    "prepare": "is-ci || husky install",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:types": "tsc -p src/__tests__/types/tsconfig.test.json"
+  },
+  "lint-staged": {
+    "*.{js,ts}": "eslint --fix",
+    "*.{json,md,yml}": "prettier --write",
+    "package.json": "sort-package-json"
+  },
+  "prettier": "@myparcel-dev/prettier-config",
+  "release": {
+    "extends": "@myparcel-dev/semantic-release-config/github-npm"
+  },
+  "devDependencies": {
+    "@myparcel-dev/semantic-release-config": "^6.0.0",
+    "@myparcel-eslint/eslint-config-prettier-typescript": "^1.2.0",
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^1.0.0",
+    "eslint": "^8.33.0",
+    "husky": "^8.0.3",
+    "is-ci": "^3.0.1",
+    "lint-staged": "^15.0.0",
+    "prettier": "^2.8.4",
+    "sort-package-json": "^2.4.1",
+    "ts-node": "^10.9.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "packageManager": "yarn@4.0.2",
+  "publishConfig": {
+    "access": "public"
+  }
+}