@augment-vir/common 4.6.0 → 5.0.0

package/dist/types/augments/date.d.ts

@@ -0,0 +1,26 @@
+export declare const englishFullMonthNames: readonly ["january", "february", "march", "april", "may", "june", "july", "august", "september", "october", "november", "december"];
+export declare const englishShortMonthNames: string[];
+export declare class InvalidDateError extends Error {
+    readonly name = "InvalidDateError";
+}
+/**
+ * @param slashFormatString String that should be of format "MM/DD/YY", "MM/DD/YYYY". When the year
+ *   portion only contains 2 numbers ("MM/DD/YY") the century must be provided in the form of the
+ *   yearPrefix input.
+ * @param yearPrefix String or number that is used to prefix slash format strings that only contain
+ *   2 digits ("MM/DD/YY"). If the year is entirely missing form the given slash format string, the
+ *   year will default to year 00 of the given century. See test file for examples.
+ */
+export declare function createDateFromSlashFormat(slashFormatString: string, yearPrefix?: number | string): Date;
+/**
+ * @param commaFormatString Should be at string of the form "monthName dayNumber, fullYear" Example:
+ *   "May 19, 2005"
+ * @param ignoreInvalidMonth Set to true to ignore invalid months and just use the current UTC month
+ */
+export declare function createDateFromNamedCommaFormat(commaFormatString: string, ignoreInvalidMonth?: boolean): Date;
+/**
+ * Converts an iso-formatted string to a UTC date object. The time is nulled out to all zeros.
+ *
+ * @param isoFormatString Should be a date in the format YYYY-MM-DD.
+ */
+export declare function createDateFromUtcIsoFormat(isoFormatString: string): Date;

package/dist/types/augments/environment.d.ts

@@ -0,0 +1 @@
+export declare function isBrowser(): boolean;

package/dist/types/augments/error.d.ts

@@ -0,0 +1,8 @@
+import { AtLeastTuple } from './tuple';
+export declare function combineErrors(errors: AtLeastTuple<Error, 1>): Error;
+export declare function combineErrors(errors: ReadonlyArray<never>): undefined;
+export declare function combineErrors(errors: ReadonlyArray<Error>): Error | undefined;
+export declare function combineErrors(errors?: undefined): undefined;
+export declare function combineErrorMessages(errors?: ReadonlyArray<Error | string | undefined> | undefined): string;
+export declare function extractErrorMessage(error: unknown): string;
+export declare function ensureError(input: unknown): Error;

package/dist/types/augments/function.d.ts

@@ -0,0 +1 @@
+export declare function isTruthy<T>(input: T): input is NonNullable<T>;

package/dist/types/augments/object.d.ts

@@ -0,0 +1,63 @@
+import { AtLeastOneEntryArray } from './array';
+import { NoInfer, RequiredBy, UnPromise } from './type';
+export declare function getEnumTypedKeys<T extends object>(input: T): (keyof T)[];
+export declare function getEnumTypedValues<T extends object>(input: T): T[keyof T][];
+export declare function isEnumValue<T extends object>(input: unknown, checkEnum: T): input is T[keyof T];
+export declare function isKeyof<ObjectGeneric>(key: PropertyKey, object: ObjectGeneric): key is keyof object;
+export declare function filterToEnumValues<T extends object>(inputs: ReadonlyArray<unknown>, checkEnum: T, caseInsensitive?: boolean): T[keyof T][];
+export declare function getObjectTypedKeys<ObjectGeneric extends unknown>(input: ObjectGeneric): ReadonlyArray<keyof ObjectGeneric>;
+export declare function getObjectTypedValues<ObjectGeneric extends unknown>(input: ObjectGeneric): ObjectGeneric[keyof ObjectGeneric][];
+declare type ExtractValue<KeyGeneric extends PropertyKey, ParentGeneric> = KeyGeneric extends keyof ParentGeneric ? RequiredBy<ParentGeneric, KeyGeneric>[KeyGeneric] : KeyGeneric extends keyof Extract<ParentGeneric, Record<KeyGeneric, any>> ? RequiredBy<Extract<ParentGeneric, Record<KeyGeneric, any>>, KeyGeneric>[KeyGeneric] : never;
+declare type CombinedParentValue<KeyGeneric extends PropertyKey, ParentGeneric> = ExtractValue<KeyGeneric, ParentGeneric> extends never ? unknown : ExtractValue<KeyGeneric, ParentGeneric>;
+declare type CombineTypeWithKey<KeyGeneric extends PropertyKey, ParentGeneric> = ParentGeneric & Record<KeyGeneric, CombinedParentValue<KeyGeneric, ParentGeneric>>;
+export declare function typedHasProperty<KeyGeneric extends PropertyKey, ParentGeneric>(inputObject: ParentGeneric, inputKey: KeyGeneric): inputObject is CombineTypeWithKey<KeyGeneric, ParentGeneric>;
+export declare function typedHasProperties<KeyGeneric extends PropertyKey, ParentGeneric>(inputObject: ParentGeneric, inputKeys: ReadonlyArray<KeyGeneric>): inputObject is CombineTypeWithKey<KeyGeneric, ParentGeneric>;
+export declare function isObject(input: any): input is NonNullable<object>;
+export declare function getEntriesSortedByKey(input: object): [string, unknown][];
+export declare function areJsonEqual(a: object, b: object): boolean;
+export declare type InnerMappedValues<EntireInputGeneric extends object, MappedValueGeneric> = {
+    [MappedProp in keyof EntireInputGeneric]: MappedValueGeneric;
+};
+export declare type MappedValues<EntireInputGeneric extends object, MappedValueGeneric> = MappedValueGeneric extends PromiseLike<unknown> ? Promise<InnerMappedValues<EntireInputGeneric, UnPromise<MappedValueGeneric>>> : InnerMappedValues<EntireInputGeneric, UnPromise<MappedValueGeneric>>;
+/**
+ * Creates a new object with the same properties as the input object, but with values set to the
+ * result of mapCallback for each property.
+ */
+export declare function mapObjectValues<EntireInputGeneric extends object, MappedValueGeneric>(inputObject: EntireInputGeneric, mapCallback: (inputKey: keyof EntireInputGeneric, keyValue: EntireInputGeneric[typeof inputKey], fullObject: EntireInputGeneric) => MappedValueGeneric): MappedValues<EntireInputGeneric, MappedValueGeneric>;
+export declare function filterObject<ObjectGeneric extends object>(inputObject: ObjectGeneric, callback: (key: keyof ObjectGeneric, value: ObjectValueType<ObjectGeneric>, fullObject: ObjectGeneric) => boolean): Partial<ObjectGeneric>;
+/** The input here must be serializable otherwise JSON parsing errors will be thrown */
+export declare function copyThroughJson<T>(input: T): T;
+export declare type ObjectValueType<T extends object> = T[keyof T];
+/**
+ * Checks that the first input, testThisOne, matches the object shape of the second input,
+ * compareToThisOne. Does not compare exact values of properties, only types.
+ *
+ * To allow the test input, the first input, to have additional keys that the compare input, the
+ * second input, does not have, pass in a third argument set to true.
+ *
+ * This function REQUIRES a generic to be assigned to it: it cannot infer it from the inputs.
+ *
+ * The compare input, the second input, is required to have at least one entry in every array value
+ * that exists. If more array values are present, they will be considered other possible types for
+ * entries in that array.
+ */
+export declare function matchesObjectShape<MatchThisGeneric extends object>(testThisOne: unknown, compareToThisOne: NoInfer<ObjectWithAtLeastSingleEntryArrays<MatchThisGeneric>>, allowExtraProps?: boolean, shouldLogWhy?: boolean): testThisOne is MatchThisGeneric;
+export declare type ObjectWithAtLeastSingleEntryArrays<BaseObject extends object> = {
+    [Prop in keyof BaseObject]: BaseObject[Prop] extends ReadonlyArray<any> ? AtLeastOneEntryArray<BaseObject[Prop]> : BaseObject[Prop] extends object ? ObjectWithAtLeastSingleEntryArrays<BaseObject[Prop]> : BaseObject[Prop];
+};
+/**
+ * Asserts that the first input, testThisOne, matches the object shape of the second input,
+ * compareToThisOne. Does not compare exact values of properties, only types.
+ *
+ * To allow the test input, the first input, to have additional keys that the compare input, the
+ * second input, does not have, pass in a third argument set to true.
+ *
+ * This function REQUIRES a generic to be assigned to it: it cannot infer it from the inputs.
+ *
+ * The compare input, the second input, is required to have at least one entry in every array value
+ * that exists. If more array values are present, they will be considered other possible types for
+ * entries in that array.
+ */
+export declare function assertMatchesObjectShape<MatchThisGeneric extends object = never>(testThisOne: unknown, compareToThisOne: NoInfer<ObjectWithAtLeastSingleEntryArrays<MatchThisGeneric>>, allowExtraProps?: boolean): asserts testThisOne is MatchThisGeneric;
+export declare function typedObjectFromEntries<KeyType extends PropertyKey, ValueType>(entries: ReadonlyArray<Readonly<[KeyType, ValueType]>>): Record<KeyType, ValueType>;
+export {};

package/dist/types/augments/promise.d.ts

@@ -0,0 +1,23 @@
+export declare function wait(delayMs: number): Promise<void>;
+export declare function isPromiseLike<T>(input: T | unknown): input is T extends PromiseLike<infer ValueType> ? PromiseLike<ValueType> : PromiseLike<unknown>;
+export declare class PromiseTimeoutError extends Error {
+    readonly durationMs: number;
+    readonly message: string;
+    readonly name = "PromiseTimeoutError";
+    constructor(durationMs: number, message?: string);
+}
+export declare function wrapPromiseInTimeout<PromiseValueType>(durationMs: number, originalPromise: PromiseLike<PromiseValueType>): Promise<PromiseValueType>;
+/** A promise which can be resolved or rejected by external code. */
+export declare type DeferredPromiseWrapper<T> = {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: any) => void;
+};
+export declare function createDeferredPromiseWrapper<T = void>(): DeferredPromiseWrapper<T>;
+export declare type WaitForConditionInputs = {
+    conditionCallback: () => boolean | Promise<boolean>;
+    timeoutMs?: number;
+    intervalMs?: number;
+    timeoutMessage?: string;
+};
+export declare function waitForCondition({ conditionCallback, timeoutMs, intervalMs, timeoutMessage, }: WaitForConditionInputs): Promise<void>;

package/dist/types/augments/regexp.d.ts

@@ -0,0 +1,3 @@
+export declare function deDupeRegExFlags(flags: string): string;
+export declare function addRegExpFlags(originalRegExp: RegExp, flags: string): RegExp;
+export declare function safeMatch(input: string, regExp: RegExp): string[];

package/dist/types/augments/tuple.d.ts

@@ -0,0 +1,8 @@
+export declare type Tuple<ArrayElementGeneric, LengthGeneric extends number> = LengthGeneric extends LengthGeneric ? number extends LengthGeneric ? ArrayElementGeneric[] : _TupleOf<ArrayElementGeneric, LengthGeneric, []> : never;
+declare type _TupleOf<ArrayElementGeneric, LengthGeneric extends number, FullArrayGeneric extends unknown[]> = FullArrayGeneric['length'] extends LengthGeneric ? FullArrayGeneric : _TupleOf<ArrayElementGeneric, LengthGeneric, [ArrayElementGeneric, ...FullArrayGeneric]>;
+export declare type AtLeastTuple<ArrayElementGeneric, LengthGeneric extends number> = readonly [
+    ...Tuple<ArrayElementGeneric, LengthGeneric>,
+    ...ArrayElementGeneric[]
+];
+export declare function isLengthAtLeast<ArrayElementGeneric, LengthGeneric extends number>(array: ReadonlyArray<ArrayElementGeneric>, length: LengthGeneric): array is AtLeastTuple<ArrayElementGeneric, LengthGeneric>;
+export {};

package/dist/types/augments/type-of.d.ts

@@ -0,0 +1,17 @@
+declare function getTypeOf(x: any): "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function";
+export declare type TypeOf = ReturnType<typeof getTypeOf>;
+export declare type TypeOfWithArray = TypeOf | 'array';
+export declare type TypeOfMapping = {
+    array: any[];
+    bigint: bigint;
+    boolean: boolean;
+    function: (...args: any[]) => any;
+    number: number;
+    object: object;
+    string: string;
+    symbol: symbol;
+    undefined: undefined;
+};
+export declare function typeOfWithArray(input: unknown): TypeOfWithArray;
+export declare function isTypeOfWithArray<T extends TypeOfWithArray>(input: unknown, testType: T): input is TypeOfMapping[T];
+export {};

package/dist/types/augments/type.d.ts

@@ -0,0 +1,54 @@
+/** Makes all properties in an object writable. This is the opposite of Readonly<> */
+export declare type Writeable<T> = {
+    -readonly [P in keyof T]: T[P];
+};
+/** Makes all property values in an object also readonly. Can cause issues on primitive. */
+export declare type DeepWriteable<T> = {
+    -readonly [P in keyof T]: DeepWriteable<T[P]>;
+};
+/** Replace properties in T with properties in U. */
+export declare type Overwrite<T, U> = Pick<T, Exclude<keyof T, keyof U>> & U;
+/** Extract the element type out of an array type. */
+export declare type ArrayElement<ArrayType extends ReadonlyArray<any>> = ArrayType[number];
+/**
+ * Same as the Required<> built-in type helper but this requires that each property be present and
+ * be not null.
+ */
+export declare type RequiredAndNotNull<T> = {
+    [P in keyof T]-?: NonNullable<T[P]>;
+};
+/** Require only a subset of object properties. */
+export declare type RequiredBy<T, K extends keyof T> = Overwrite<T, Required<Pick<T, K>>>;
+/**
+ * Require only a subset of object properties and require that they be not null. This is
+ * particularly useful in conjunction with the "exactOptionalPropertyTypes" tsconfig flag.
+ */
+export declare type RequiredAndNotNullBy<T, K extends keyof T> = Omit<T, K> & Required<{
+    [PropertyName in K]: NonNullable<T[PropertyName]>;
+}>;
+/** If type T = type U, then type Y. Else type N. */
+export declare type IfEquals<T, U, Y = unknown, N = never> = (<G>() => G extends T ? 1 : 2) extends <G>() => G extends U ? 1 : 2 ? Y : N;
+export declare type UnPromise<T> = T extends PromiseLike<infer PromiseType> ? Awaited<PromiseType> : T;
+/**
+ * This function returns another function that simply returns whatever input it's given. However, it
+ * also checks that the input matches the original wrapNarrowTypeWithTypeCheck's generic, while
+ * maintaining strict "const" like typing.
+ *
+ * Use like this: wrapNarrowTypeWithTypeCheck<EnforcedTypeHere>()(valueToEnforceTypeOn as const)
+ *
+ * Sometimes "as const" isn't required, usually it is for any object or array though.
+ */
+export declare function wrapNarrowTypeWithTypeCheck<P>(): <T extends P>(input: T) => Readonly<T>;
+/**
+ * This type helper is useful for forcing function generics to be explicitly provided, rather than
+ * inferring them from the given inputs. See the test file for examples.
+ */
+export declare type NoInfer<T> = [T][T extends any ? 0 : never];
+/**
+ * This is a type helper that ensures the given input matches the given generic type. The generic is
+ * setup in such a way that if it is omitted (which is typically allowed in TypeScript, resulting in
+ * the generic being inferred from the inputs), there will actually be a type error. This forces
+ * each usage of this function to explicitly specify the generic, thus giving us type safety for the
+ * input.
+ */
+export declare function ensureType<ExpectedType = never>(input: NoInfer<ExpectedType>): NoInfer<ExpectedType>;

package/dist/types/index.d.ts

@@ -0,0 +1,15 @@
+export * from './augments/ansi';
+export * from './augments/array';
+export * from './augments/async';
+export * from './augments/common-number';
+export * from './augments/common-string';
+export * from './augments/date';
+export * from './augments/environment';
+export * from './augments/error';
+export * from './augments/function';
+export * from './augments/object';
+export * from './augments/promise';
+export * from './augments/regexp';
+export * from './augments/tuple';
+export * from './augments/type';
+export * from './augments/type-of';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/common",
-    "version": "4.6.0",
+    "version": "5.0.0",
     "homepage": "https://github.com/electrovir/augment-vir/tree/main/packages/common",
     "bugs": {
         "url": "https://github.com/electrovir/augment-vir/issues"
@@ -14,18 +14,19 @@
         "name": "electrovir",
         "url": "https://github.com/electrovir"
     },
-    "main": "dist/index.js",
-    "types": "dist/index.d.ts",
+    "main": "dist/cjs/index.js",
+    "module": "dist/esm/index.js",
+    "types": "dist/types/index.d.ts",
     "scripts": {
-        "compile": "tsc --pretty",
+        "compile": "tsc --project tsconfig.json && tsc --project tsconfig.cjs.json && tsc --project tsconfig.esm.json",
         "docs:update": "virmator code-in-markdown",
         "test": "echo \"use common-test to run tests\" && exit 0"
     },
     "dependencies": {
-        "@type-challenges/utils": "^0.1.1",
         "type-fest": "^3.2.0"
     },
     "devDependencies": {
+        "istanbul-smart-text-reporter": "^1.0.0",
         "prettier": "^2.7.1",
         "prettier-plugin-jsdoc": "^0.4.2",
         "prettier-plugin-multiline-arrays": "^1.1.1",
@@ -33,7 +34,6 @@
         "prettier-plugin-packagejson": "^2.3.0",
         "prettier-plugin-sort-json": "^0.0.3",
         "prettier-plugin-toml": "^0.3.1",
-        "ts-node": "^10.9.1",
         "typescript": "^4.8.4"
     },
     "publishConfig": {

package/dist/augments/array.js

@@ -1,44 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.typedMap = exports.isInTypedArray = exports.awaitedBlockingMap = exports.awaitedForEach = exports.trimArrayStrings = exports.flatten2dArray = exports.filterOutIndexes = void 0;
-function filterOutIndexes(array, indexes) {
-    return array.filter((_, index) => !indexes.includes(index));
-}
-exports.filterOutIndexes = filterOutIndexes;
-function flatten2dArray(array2d) {
-    const flattened = array2d.reduce((accum, row) => accum.concat(row), []);
-    return flattened;
-}
-exports.flatten2dArray = flatten2dArray;
-function trimArrayStrings(input) {
-    return input.map((line) => line.trim()).filter((line) => line !== '');
-}
-exports.trimArrayStrings = trimArrayStrings;
-/**
- * Acts like calling Array.prototype.forEach in that all elements are executed upon in order, and
- * each execution is blocking. Meaning, the callback won't be called on element 2 until the callback
- * has finished its call on element 1.
- */
-async function awaitedForEach(input, callback) {
-    await awaitedBlockingMap(input, callback);
-}
-exports.awaitedForEach = awaitedForEach;
-async function awaitedBlockingMap(input, callback) {
-    const mappedValues = await input.reduce(async (accumPromise, currentElement, index, wholeArray) => {
-        const accum = await accumPromise;
-        const mappedValue = await callback(currentElement, index, wholeArray);
-        accum.push(mappedValue);
-        return accum;
-    }, Promise.resolve([]));
-    return mappedValues;
-}
-exports.awaitedBlockingMap = awaitedBlockingMap;
-function isInTypedArray(array, input) {
-    return array.includes(input);
-}
-exports.isInTypedArray = isInTypedArray;
-/** Preserves tuple types. */
-function typedMap(arrayToMap, mapCallback) {
-    return arrayToMap.map(mapCallback);
-}
-exports.typedMap = typedMap;

package/dist/augments/type-test.d.ts

@@ -1,3 +0,0 @@
-import { Equal } from '@type-challenges/utils';
-export type { Alike, Debug, Equal, ExpectExtends as DoesExtend, ExpectFalse, ExpectTrue, ExpectValidArgs as HasValidArgs, IsAny, IsFalse, IsTrue, MergeInsertions, NotAny, NotEqual, UnionToIntersection, } from '@type-challenges/utils';
-export declare type CouldBeNullish<VALUE> = Equal<VALUE, NonNullable<VALUE>> extends true ? false : true;

package/dist/augments/type-test.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });