feat: add .d.ts for jsutils

src/jsutils/devAssert.d.ts

@@ -0,0 +1 @@
+export function devAssert(condition: unknown, message: string): void;

src/jsutils/didYouMean.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Given [ A, B, C ] return ' Did you mean A, B, or C?'.
+ */
+export function didYouMean(suggestions: ReadonlyArray<string>): string;
+export function didYouMean(
+  subMessage: string,
+  suggestions: ReadonlyArray<string>,
+): string;

src/jsutils/identityFunc.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Returns the first argument it receives.
+ */
+export function identityFunc<T>(x: T): T;

src/jsutils/inspect.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Used to print values in error messages.
+ */
+export function inspect(value: unknown): string;

src/jsutils/instanceOf.d.ts

@@ -0,0 +1 @@
+export const instanceOf: (value: unknown, constructor: unknown) => boolean;

src/jsutils/invariant.d.ts

@@ -0,0 +1,4 @@
+export function invariant(
+  condition: unknown,
+  message?: string,
+): asserts condition;

src/jsutils/isAsyncIterable.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns true if the provided object implements the AsyncIterator protocol via
+ * either implementing a `Symbol.asyncIterator` or `"@@asyncIterator"` method.
+ */
+export function isAsyncIterable(
+  maybeAsyncIterable: unknown,
+): maybeAsyncIterable is AsyncIterable<unknown>;

src/jsutils/isIteratableObject.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Returns true if the provided object is an Object (i.e. not a string literal)
+ * and implements the Iterator protocol.
+ *
+ * This may be used in place of [Array.isArray()][isArray] to determine if
+ * an object should be iterated-over e.g. Array, Map, Set, Int8Array,
+ * TypedArray, etc. but excludes string literals.
+ *
+ * @example
+ *
+ * isIteratableObject([ 1, 2, 3 ]) // true
+ * isIteratableObject(new Map()) // true
+ * isIteratableObject('ABC') // false
+ * isIteratableObject({ key: 'value' }) // false
+ * isIteratableObject({ length: 1, 0: 'Alpha' }) // false
+ */
+export function isIteratableObject(
+  maybeIteratable: unknown,
+): maybeIteratable is Iterable<unknown>;

src/jsutils/isObjectLike.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Return true if `value` is object-like. A value is object-like if it's not
+ * `null` and has a `typeof` result of "object".
+ */
+export function isObjectLike(value: unknown): value is Record<string, unknown>;

src/jsutils/isPromise.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns true if the value acts like a Promise, i.e. has a "then" function,
+ * otherwise returns false.
+ */
+export function isPromise(value: unknown): value is Promise<unknown>;

src/jsutils/keyMap.d.ts

@@ -0,0 +1,28 @@
+import type { ObjMap } from './ObjMap';
+/**
+ * Creates a keyed JS object from an array, given a function to produce the keys
+ * for each value in the array.
+ *
+ * This provides a convenient lookup for the array items if the key function
+ * produces unique results.
+ *
+ *     const phoneBook = [
+ *       { name: 'Jon', num: '555-1234' },
+ *       { name: 'Jenny', num: '867-5309' }
+ *     ]
+ *
+ *     // { Jon: { name: 'Jon', num: '555-1234' },
+ *     //   Jenny: { name: 'Jenny', num: '867-5309' } }
+ *     const entriesByName = keyMap(
+ *       phoneBook,
+ *       entry => entry.name
+ *     )
+ *
+ *     // { name: 'Jenny', num: '857-6309' }
+ *     const jennyEntry = entriesByName['Jenny']
+ *
+ */
+export function keyMap<T>(
+  list: ReadonlyArray<T>,
+  keyFn: (item: T) => string,
+): ObjMap<T>;

src/jsutils/keyValMap.d.ts

@@ -0,0 +1,23 @@
+import type { ObjMap } from './ObjMap';
+/**
+ * Creates a keyed JS object from an array, given a function to produce the keys
+ * and a function to produce the values from each item in the array.
+ *
+ *     const phoneBook = [
+ *       { name: 'Jon', num: '555-1234' },
+ *       { name: 'Jenny', num: '867-5309' }
+ *     ]
+ *
+ *     // { Jon: '555-1234', Jenny: '867-5309' }
+ *     const phonesByName = keyValMap(
+ *       phoneBook,
+ *       entry => entry.name,
+ *       entry => entry.num
+ *     )
+ *
+ */
+export function keyValMap<T, V>(
+  list: ReadonlyArray<T>,
+  keyFn: (item: T) => string,
+  valFn: (item: T) => V,
+): ObjMap<V>;

src/jsutils/mapValue.d.ts

@@ -0,0 +1,9 @@
+import type { ObjMap } from './ObjMap';
+/**
+ * Creates an object map with the same keys as `map` and values generated by
+ * running each value of `map` thru `fn`.
+ */
+export function mapValue<T, V>(
+  map: ObjMap<T>,
+  fn: (value: T, key: string) => V,
+): ObjMap<V>;

src/jsutils/memoize3.d.ts

@@ -0,0 +1,10 @@
+/* eslint-disable @typescript-eslint/ban-types */
+/**
+ * Memoizes the provided three-argument function.
+ */
+export function memoize3<
+  A1 extends object,
+  A2 extends object,
+  A3 extends object,
+  R
+>(fn: (a1: A1, a2: A2, a3: A3) => R): (a1: A1, a2: A2, a3: A3) => R;

src/jsutils/naturalCompare.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns a number indicating whether a reference string comes before, or after,
+ * or is the same as the given string in natural sort order.
+ *
+ * See: https://en.wikipedia.org/wiki/Natural_sort_order
+ *
+ */
+export function naturalCompare(aStr: string, bStr: string): number;

src/jsutils/printPathArray.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Build a string describing the path.
+ */
+export function printPathArray(path: ReadonlyArray<string | number>): string;

src/jsutils/promiseForObject.d.ts

@@ -0,0 +1,11 @@
+import type { ObjMap } from './ObjMap';
+/**
+ * This function transforms a JS object `ObjMap<Promise<T>>` into
+ * a `Promise<ObjMap<T>>`
+ *
+ * This is akin to bluebird's `Promise.props`, but implemented only using
+ * `Promise.all` so it will work with any implementation of ES6 promises.
+ */
+export function promiseForObject<T>(
+  object: ObjMap<Promise<T>>,
+): Promise<ObjMap<T>>;

src/jsutils/promiseReduce.d.ts

@@ -0,0 +1,13 @@
+import type { PromiseOrValue } from './PromiseOrValue';
+/**
+ * Similar to Array.prototype.reduce(), however the reducing callback may return
+ * a Promise, in which case reduction will continue after each promise resolves.
+ *
+ * If the callback does not return a Promise, then this function will also not
+ * return a Promise.
+ */
+export function promiseReduce<T, U>(
+  values: ReadonlyArray<T>,
+  callback: (U: any, T: any) => PromiseOrValue<U>,
+  initialValue: PromiseOrValue<U>,
+): PromiseOrValue<U>;

src/jsutils/suggestionList.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Given an invalid input string and a list of valid options, returns a filtered
+ * list of valid options sorted based on their similarity with the input.
+ */
+export function suggestionList(
+  input: string,
+  options: ReadonlyArray<string>,
+): Array<string>;

src/jsutils/toObjMap.d.ts

@@ -0,0 +1,9 @@
+import type {
+  ObjMap,
+  ObjMapLike,
+  ReadOnlyObjMap,
+  ReadOnlyObjMapLike,
+} from './ObjMap';
+
+export function toObjMap<T>(obj: ObjMapLike<T>): ObjMap<T>;
+export function toObjMap<T>(obj: ReadOnlyObjMapLike<T>): ReadOnlyObjMap<T>;