@1nkvi/utils 0.1.3 → 0.2.0

package/build/artifacts/src/array/createArray.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Creates array from `startIndex` to `length¨
+ *
+ * Useful for quickly creating skeleton placeholders
+ *
+ * @param length size of the array
+ * @param startIndex defaults to 0
+ */
+export declare function createArray(length: number, startIndex?: number): number[];

package/build/artifacts/src/array/createArray.js

@@ -0,0 +1,11 @@
+/**
+ * Creates array from `startIndex` to `length¨
+ *
+ * Useful for quickly creating skeleton placeholders
+ *
+ * @param length size of the array
+ * @param startIndex defaults to 0
+ */
+export function createArray(length, startIndex = 0) {
+    return Array.from({ length }, (_, i) => i + startIndex);
+}

package/build/artifacts/src/array/createRangeArray.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns array of numbers from interval `<min, max>`
+ * @param min min value (inclusive)
+ * @param max max value (inclusive)
+ * @example ```tsx
+ * createRangeArray(-2, 1) // [-2, -1, 0, 1]
+ * ```
+ */
+export declare function createRangeArray(min: number, max: number): number[];

package/build/artifacts/src/array/createRangeArray.js

@@ -0,0 +1,11 @@
+/**
+ * Returns array of numbers from interval `<min, max>`
+ * @param min min value (inclusive)
+ * @param max max value (inclusive)
+ * @example ```tsx
+ * createRangeArray(-2, 1) // [-2, -1, 0, 1]
+ * ```
+ */
+export function createRangeArray(min, max) {
+    return Array.from({ length: max - min + 1 }, (_, i) => min + i);
+}

package/build/artifacts/src/array/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./tuplify";
+export * from "./createArray";
+export * from "./createRangeArray";

package/build/artifacts/src/array/index.js

@@ -0,0 +1,3 @@
+export * from "./tuplify";
+export * from "./createArray";
+export * from "./createRangeArray";

package/build/artifacts/src/guard/index.d.ts

@@ -0,0 +1 @@
+export * from "./triggerExhaustiveSwitch";

package/build/artifacts/src/guard/index.js

@@ -0,0 +1 @@
+export * from "./triggerExhaustiveSwitch";

package/build/artifacts/src/guard/triggerExhaustiveSwitch.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Used for checking that all values are accounted for in a switch
+ * ```typescript
+ * type Test = "a"|"b"|"c"
+ * switch(test) {
+ *   case "a": ...
+ *   case "b": ...
+ *   default: triggerExhaustiveSwitch(test, "My component name")
+ * }
+ * ```
+ * @param value value in switch
+ * @param componentName name used for debugging purposes. Usually name of the component where switch lives
+ */
+export declare function triggerExhaustiveSwitch(value: never, componentName: string): never;

package/build/artifacts/src/guard/triggerExhaustiveSwitch.js

@@ -0,0 +1,17 @@
+/**
+ * Used for checking that all values are accounted for in a switch
+ * ```typescript
+ * type Test = "a"|"b"|"c"
+ * switch(test) {
+ *   case "a": ...
+ *   case "b": ...
+ *   default: triggerExhaustiveSwitch(test, "My component name")
+ * }
+ * ```
+ * @param value value in switch
+ * @param componentName name used for debugging purposes. Usually name of the component where switch lives
+ */
+export function triggerExhaustiveSwitch(value, componentName) {
+    // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+    throw new Error(`Unhandled ${componentName} type for value [${value}]`);
+}

package/build/artifacts/src/index.d.ts

@@ -1,5 +1,5 @@
-export * from "./merge/merge";
-export * from "./merge/mergeArrays";
-export * from "./merge/utils";
-export * from "./merge/filterValidPrimitiveArrayValues";
-export * from "./tuplify";
+export * from "./array";
+export * from "./merge";
+export * from "./guard";
+export * from "./map";
+export * from "./random";

package/build/artifacts/src/index.js

@@ -1,5 +1,5 @@
-export * from "./merge/merge";
-export * from "./merge/mergeArrays";
-export * from "./merge/utils";
-export * from "./merge/filterValidPrimitiveArrayValues";
-export * from "./tuplify";
+export * from "./array";
+export * from "./merge";
+export * from "./guard";
+export * from "./map";
+export * from "./random";

package/build/artifacts/src/map/index.d.ts

@@ -0,0 +1 @@
+export * from "./upsert";

package/build/artifacts/src/map/index.js

@@ -0,0 +1 @@
+export * from "./upsert";

package/build/artifacts/src/map/upsert.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Upserts existing map by `value`, following the `fn` behavior
+ * @param map existing map
+ * @param key key to be upserted
+ * @param value value to be upserted
+ * @param fn function used when value exists in the map
+ * @example ```tsx
+ *   const map = new Map<string, string[]>()
+ *   map.set("a", ["1", "2"])
+ *   upsert(map, "a", ["3"], (prev, value) => [...prev, ...value])
+ *   // output: ["1", "2", "3"]
+ * ```
+ * @remarks if key does not exist, sets the value
+ */
+export declare function upsert<TKey, TValue>(map: Map<TKey, TValue>, key: TKey, value: TValue, fn: (prev: TValue, value: TValue) => TValue): TValue;

package/build/artifacts/src/map/upsert.js

@@ -0,0 +1,24 @@
+/**
+ * Upserts existing map by `value`, following the `fn` behavior
+ * @param map existing map
+ * @param key key to be upserted
+ * @param value value to be upserted
+ * @param fn function used when value exists in the map
+ * @example ```tsx
+ *   const map = new Map<string, string[]>()
+ *   map.set("a", ["1", "2"])
+ *   upsert(map, "a", ["3"], (prev, value) => [...prev, ...value])
+ *   // output: ["1", "2", "3"]
+ * ```
+ * @remarks if key does not exist, sets the value
+ */
+export function upsert(map, key, value, fn) {
+    if (map.has(key)) {
+        const prev = map.get(key);
+        const next = fn(prev, value);
+        map.set(key, next);
+        return next;
+    }
+    map.set(key, value);
+    return value;
+}

package/build/artifacts/src/merge/DeepPartial.d.ts

@@ -1,3 +1,6 @@
+/**
+ * Expects json object. Walks through the children and makes all keys optional
+ */
 export type DeepPartial<T> = T extends Array<infer U> ? Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends object ? {
     [K in keyof T]?: DeepPartial<T[K]>;
 } : T;

package/build/artifacts/src/merge/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./merge";
+export * from "./mergeArrays";
+export * from "./utils";
+export * from "./filterValidPrimitiveArrayValues";

package/build/artifacts/src/merge/index.js

@@ -0,0 +1,4 @@
+export * from "./merge";
+export * from "./mergeArrays";
+export * from "./utils";
+export * from "./filterValidPrimitiveArrayValues";

package/build/artifacts/src/merge/merge.js

@@ -1,6 +1,6 @@
 import { isInvalidPrimitive } from "../merge/isInvalidPrimitive";
 import { isPlainObject } from "../merge/utils";
-import { tuplify } from "../tuplify";
+import { tuplify } from "../array/tuplify";
 import { mergeArrays } from "../merge/mergeArrays";
 /**
  * Deeply merges inputs into new object. Generally goes through the following steps:

package/build/artifacts/src/random/index.d.ts

@@ -0,0 +1 @@
+export * from "../random/random";

package/build/artifacts/src/random/index.js

@@ -0,0 +1 @@
+export * from "../random/random";

package/build/artifacts/src/random/random.d.ts

@@ -0,0 +1,63 @@
+export interface RandomOptions {
+    excludeMin?: true;
+    excludeMax?: true;
+}
+/**
+ * Returns random integer number between `min` and `max` based on the `options`
+ * @param min min value (inclusive by default). Must be less than `max`
+ * @param max max value (inclusive by default). Must be greater than `min`
+ * @param options further options for modifying generator behavior
+ *
+ * @example ```tsx
+ * random(1, 10)
+ * // returns single value from  inclusive interval <1, 10>
+ * ```
+ */
+export declare function random(min: number, max: number, options?: RandomOptions): number;
+export interface RandomMarginalChangeOptions {
+    /**
+     * Value added to the `min` in the random function
+     * @default 0
+     */
+    minFixed?: number;
+    /**
+     * Value added to the `max` in the random function
+     * @default 0
+     */
+    maxFixed?: number;
+    /**
+     * Percentage value (as decimal) multiplied the resulting `min` in the random function
+     * @default 1.00
+     */
+    minPercentage?: number;
+    /**
+     * Percentage value (as decimal) multiplied the resulting `max` in the random function
+     * @default 1.00
+     */
+    maxPercentage?: number;
+    /**
+     * Return this number if computed result is less than absolute minimum
+     */
+    absoluteMin?: number;
+    /**
+     * Return this number if computed result is greater than absolute maximum
+     */
+    absoluteMax?: number;
+}
+/**
+ * Takes initial value and creates marginal change based on options values.
+ *
+ * Insert percentages as decimals - 100% = 1.00; 1% = 0.01 calculated from initial value.
+ * @example
+ * ```typescript
+ *  randomMarginalChange(100, {minFixed: -10, maxFixed: 10, minPercentage: 0.9, maxPercentage: 1.1})
+ *  // results in interval  min: (100 - 10) * 0.9; max: (100 + 10) * 1.1
+ *  // where result will be <89; 121>
+ *
+ * ```
+ * @remark Returns floored random value
+ *
+ * @param value initial value to be derived
+ * @param options fixed values default to 0, percentage values defaults to 1
+ */
+export declare function randomMarginalChange(value: number, options: RandomMarginalChangeOptions): number;

package/build/artifacts/src/random/random.js

@@ -0,0 +1,57 @@
+/**
+ * Returns random integer number between `min` and `max` based on the `options`
+ * @param min min value (inclusive by default). Must be less than `max`
+ * @param max max value (inclusive by default). Must be greater than `min`
+ * @param options further options for modifying generator behavior
+ *
+ * @example ```tsx
+ * random(1, 10)
+ * // returns single value from  inclusive interval <1, 10>
+ * ```
+ */
+export function random(min, max, options) {
+    if (min === max) {
+        return Math.floor(min);
+    }
+    if (min > max || max < min) {
+        throw new Error(`Min must be greater than max. Got min: ${min}, max: ${max}`);
+    }
+    if (Math.abs(Math.floor(min) - Math.floor(max)) === 1 && options?.excludeMin && options?.excludeMax) {
+        throw new Error(`Cannot generate random non-inclusive value from interval (${min}; ${max})`);
+    }
+    if (options?.excludeMin) {
+        return Math.floor(Math.random() * (max - min)) + min + 1;
+    }
+    if (options?.excludeMax) {
+        return Math.floor(Math.random() * (max - min)) + min;
+    }
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+/**
+ * Takes initial value and creates marginal change based on options values.
+ *
+ * Insert percentages as decimals - 100% = 1.00; 1% = 0.01 calculated from initial value.
+ * @example
+ * ```typescript
+ *  randomMarginalChange(100, {minFixed: -10, maxFixed: 10, minPercentage: 0.9, maxPercentage: 1.1})
+ *  // results in interval  min: (100 - 10) * 0.9; max: (100 + 10) * 1.1
+ *  // where result will be <89; 121>
+ *
+ * ```
+ * @remark Returns floored random value
+ *
+ * @param value initial value to be derived
+ * @param options fixed values default to 0, percentage values defaults to 1
+ */
+export function randomMarginalChange(value, options) {
+    const min = (value + (options.minFixed ?? 0)) * (options.minPercentage ?? 1);
+    const max = (value + (options.maxFixed ?? 0)) * (options.maxPercentage ?? 1);
+    const computedResult = Math.round(random(min, max));
+    if (options.absoluteMin && computedResult < options.absoluteMin) {
+        return options.absoluteMin;
+    }
+    if (options.absoluteMax && computedResult > options.absoluteMax) {
+        return options.absoluteMax;
+    }
+    return computedResult;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1nkvi/utils",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Helper functions",
   "keywords": [
     "merge"