Initial JSDoc impl; fixed toKeys() incorrect typing

README.md

@@ -22,6 +22,8 @@ enumUtil.getValues(Bar); //["b", "d", "f"]
 enumUtil.isKey(Bar, "B"); //true
 enumUtil.isValue(Bar, "b"); //true
 enumUtil.extractValues(Bar, ["B", "b", "D", "d", "F", "f"]); //["b", "d", "f"]
+enumUtil.toKey(Bar, "b"); //"B"
+enumUtil.getKeyCount(Bar); //3
 
 enum Foo {
     A = 0,

dist/src/main/util.d.ts

@@ -1,39 +1,320 @@
+/**
+ * The base enum type.
+ * Every other enum-like type should extend this type.
+ */
 export declare enum Enum {
 }
+/**
+ * The keys of a type may be `string|number|symbol`.
+ * This gives us only the `string` keys as `enum` keys
+ * should all be `string`.
+ *
+ * ```ts
+ * enum Foo {
+ *      A = 0,
+ *      B = 1,
+ *      C = 2,
+ * }
+ * enum Bar {
+ *      X = "eks",
+ *      Y = "wai",
+ *      Z = "zee",
+ * }
+ * //"A"|"B"|"C"
+ * type FooStringKey = StringKeyOf<Foo>;
+ * //"X"|"Y"|"Z"
+ * type BarStringKey = StringKeyOf<Bar>;
+ * ```
+ */
 export declare type StringKeyOf<T> = Extract<keyof T, string>;
+/**
+ * Converts an `enum` of type `key => value` into
+ * an `enum` of type `key => key`.
+ *
+ * ```ts
+ * enum Foo {
+ *      A = 0,
+ *      B = 1,
+ *      C = 2,
+ * }
+ * enum Bar {
+ *      X = "eks",
+ *      Y = "wai",
+ *      Z = "zee",
+ * }
+ * //{ A="A", B="B", C="C" }
+ * type FooStringEnum = StringEnum<Foo>;
+ * //{ X="X", Y="Y", Z="Z" }
+ * type BarStringEnum = StringEnum<Bar>;
+ * ```
+ *
+ * @todo Rename to `KeyEnum<>`?
+ */
 export declare type StringEnum<E extends typeof Enum> = {
     [key in StringKeyOf<E>]: key;
 };
+/**
+ * Gets the keys of an `enum`.
+ *
+ * ```ts
+ * enum Foo {
+ *      A = 0,
+ *      B = 1,
+ *      C = 2,
+ * }
+ * enum Bar {
+ *      X = "eks",
+ *      Y = "wai",
+ *      Z = "zee",
+ * }
+ * //("A"|"B"|"C")[]
+ * getKeys(Foo);
+ * //("X"|"Y"|"Z")[]
+ * getKeys(Bar);
+ * ```
+ *
+ * @param e - The `enum` to get the keys of
+ * @returns An array of keys
+ */
 export declare function getKeys<E extends typeof Enum>(e: E): (StringKeyOf<E>)[];
+/**
+ * Gets the values of an `enum`.
+ *
+ * ```ts
+ * enum Foo {
+ *      A = 0,
+ *      B = 1,
+ *      C = 2,
+ * }
+ * enum Bar {
+ *      X = "eks",
+ *      Y = "wai",
+ *      Z = "zee",
+ * }
+ * //(0|1|2)[]
+ * getValues(Foo);
+ * //("eks"|"wai"|"zee")[]
+ * getValues(Bar);
+ * ```
+ *
+ * @param e - The `enum` to get the values of
+ * @returns An array of values
+ */
 export declare function getValues<E extends typeof Enum>(e: E): (E[StringKeyOf<E>])[];
+/**
+ * Tells you if the `string` is a key of the `enum`.
+ *
+ * ```ts
+ * enum Bar {
+ *      X = "eks",
+ *      Y = "wai",
+ *      Z = "zee",
+ * }
+ * isKey(Bar, "X"); //true
+ * isKey(Bar, "Y"); //true
+ * isKey(Bar, "Z"); //true
+ * isKey(Bar, "x"); //false
+ * isKey(Bar, "y"); //false
+ * isKey(Bar, "z"); //false
+ * isKey(Bar, "eks"); //false
+ * isKey(Bar, "wai"); //false
+ * isKey(Bar, "zee"); //false
+ * ```
+ *
+ * @param e - The `enum` we are checking against
+ * @param str - The `string` that may or may not be a key of the `enum`
+ * @returns A type guard boolean that tells you if `str` is a key of `enum`
+ */
 export declare function isKey<E extends typeof Enum>(e: E, str: string): str is StringKeyOf<E>;
+/**
+ * Converts an `enum` of type `key => value` into
+ * an `enum` of type `key => key`.
+ *
+ * ```ts
+ * enum Foo {
+ *      A = 0,
+ *      B = 1,
+ *      C = 2,
+ * }
+ * enum Bar {
+ *      X = "eks",
+ *      Y = "wai",
+ *      Z = "zee",
+ * }
+ * //{ A="A", B="B", C="C" }
+ * toStringEnum(Foo);
+ * //{ X="X", Y="Y", Z="Z" }
+ * toStringEnum(Bar);
+ * ```
+ *
+ * @param e - The `enum` to convert
+ * @todo Rename to `toKeyEnum<>()`?
+ */
 export declare function toStringEnum<E extends typeof Enum>(e: E): StringEnum<E>;
+/**
+ * Tells you if `mixed` is a value of the `enum`.
+ *
+ * ```ts
+ * enum Foo {
+ *      A = 0,
+ *      B = 1,
+ *      C = 2,
+ * }
+ * isValue(Foo, "A"); //false
+ * isValue(Foo, "B"); //false
+ * isValue(Foo, "C"); //false
+ * isValue(Foo, "a"); //false
+ * isValue(Foo, "b"); //false
+ * isValue(Foo, "c"); //false
+ * isValue(Foo, 0); //true
+ * isValue(Foo, 1); //true
+ * isValue(Foo, 2); //true
+ *
+ * enum Bar {
+ *      X = "eks",
+ *      Y = "wai",
+ *      Z = "zee",
+ * }
+ * isValue(Bar, "X"); //false
+ * isValue(Bar, "Y"); //false
+ * isValue(Bar, "Z"); //false
+ * isValue(Bar, "x"); //false
+ * isValue(Bar, "y"); //false
+ * isValue(Bar, "z"); //false
+ * isValue(Bar, "eks"); //true
+ * isValue(Bar, "wai"); //true
+ * isValue(Bar, "zee"); //true
+ * ```
+ *
+ * @param e - The `enum` we are checking against
+ * @param mixed - The `mixed` value that may or may not be a value of the `enum`
+ * @returns A type guard boolean that tells you if `mixed` is a value of `enum`
+ */
 export declare function isValue<E extends typeof Enum>(e: E, mixed: any): mixed is E[StringKeyOf<E>];
+/**
+ * The same effect as the following code snippet,
+ *
+ * ```ts
+ * arr.filter(mixed => isValue(MyEnum, mixed))
+ * ```
+ *
+ * For example,
+ *
+ * ```ts
+ * enum Bar {
+ *      X = "eks",
+ *      Y = "wai",
+ *      Z = "zee",
+ * }
+ * //["eks", "wai", "zee", "zee", "wai", "eks"]
+ * extractValues(Bar, ["X", "Y", "Z", "x", "y", "z", "eks", "wai", "zee", "zee", "wai", "eks"]);
+ * ```
+ *
+ * @param e - The `enum` we are checking against
+ * @param arr - The array of mixed values we want to filter against
+ * @returns An array of values that are elements of `arr` and values of `e`
+ */
 export declare function extractValues<E extends typeof Enum>(e: E, arr: any[]): (E[StringKeyOf<E>])[];
-export declare function toKey<E extends typeof Enum, V extends number | string>(e: E, value: V): ({
-    [key in StringKeyOf<E>]: (E[key] extends V ? key : never);
-}[StringKeyOf<E>]);
-export declare function toKey<E extends typeof Enum, K extends StringKeyOf<E>>(e: E, value: E[K]): K;
+/**
+ * Gets a key of a value.
+ *
+ * ```ts
+ * enum Bar {
+ *      X = "eks",
+ *      Y = "wai",
+ *      Z = "zee",
+ * }
+ * //"Y"
+ * toKey(Bar, "wai");
+ * ```
+ *
+ * @param e - The `enum` we are checking against
+ * @param value - The value to convert to a key
+ * @returns The key of the value
+ */
 export declare function toKey<E extends typeof Enum>(e: E, value: E[StringKeyOf<E>]): StringKeyOf<E>;
 export declare function toKey<E extends typeof Enum>(e: E, mixed: any): (StringKeyOf<E>) | undefined;
+/**
+ * Counts the number of elements of an `enum`.
+ *
+ * ```ts
+ * enum Bar {
+ *      X = "eks",
+ *      Y = "wai",
+ *      Z = "zee",
+ * }
+ * //3
+ * getKeyCount(Bar);
+ * ```
+ *
+ * @param e - The `enum` we are checking against
+ * @returns The number of elements in the `enum`
+ */
 export declare function getKeyCount<E extends typeof Enum>(e: E): number;
 export declare class WrappedEnum<E extends typeof Enum> {
     private readonly e;
     private readonly keys;
     private readonly values;
+    /**
+     * @param e - The `enum` to wrap
+     */
     constructor(e: E);
+    /**
+     * Returns the original, unwrapped `enum`.
+     */
     getEnum(): E;
+    /**
+     * Gets the keys of the `enum`.
+     */
     getKeys(): Extract<keyof E, string>[];
+    /**
+     * Gets the values of the `enum`.
+     */
     getValues(): E[Extract<keyof E, string>][];
+    /**
+     * Tells you if the `string` is a key of the `enum`.
+     *
+     * @param str - The `string` that may or may not be a key of the `enum`
+     * @returns A type guard boolean that tells you if `str` is a key of `enum`
+     */
     isKey(str: string): str is StringKeyOf<E>;
+    /**
+     * Converts an `enum` of type `key => value` into
+     * an `enum` of type `key => key`.
+     *
+     * @todo Rename to `toKeyEnum<>()`?
+     */
     toStringEnum(): StringEnum<E>;
+    /**
+     * Tells you if `mixed` is a value of the `enum`.
+     *
+     * @param mixed - The `mixed` value that may or may not be a value of the `enum`
+     * @returns A type guard boolean that tells you if `mixed` is a value of `enum`
+     */
     isValue(mixed: any): mixed is E[StringKeyOf<E>];
+    /**
+     * The same effect as the following code snippet,
+     *
+     * ```ts
+     * arr.filter(mixed => isValue(MyEnum, mixed))
+     * ```
+     *
+     * @param arr - The array of mixed values we want to filter against
+     * @returns An array of values that are elements of `arr` and values of the `enum`
+     */
     extractValues(arr: any[]): (E[StringKeyOf<E>])[];
-    toKey<V extends number | string>(mixed: V): ({
-        [key in StringKeyOf<E>]: (E[key] extends V ? key : never);
-    }[StringKeyOf<E>]);
-    toKey<K extends StringKeyOf<E>>(mixed: E[K]): K;
-    toKey(mixed: E[StringKeyOf<E>]): StringKeyOf<E>;
+    /**
+     * Gets a key of a value.
+     *
+     * @param value - The value to convert to a key
+     * @returns The key of the value
+     */
+    toKey(value: E[StringKeyOf<E>]): StringKeyOf<E>;
     toKey(mixed: any): (StringKeyOf<E>) | undefined;
+    /**
+     * Counts the number of elements of an `enum`.
+     *
+     * @returns The number of elements in the `enum`
+     */
     getKeyCount(): number;
 }