@oscarpalmer/atoms 0.186.2 → 0.187.0

package/src/result/work/pipe.ts

@@ -17,9 +17,10 @@ type WrapValue<Value> = Result<UnwrapValue<Value>>;
 /**
  * Attempt to pipe a value through a function
  *
- * Available as `attemptAsyncPipe` and `attemptPipe.async`
+ * _Available as `attemptAsyncPipe` and `attemptPipe.async`_
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export async function attemptAsyncPipe<Initial, Piped>(
 	initial: GenericCallback | Initial | Promise<Initial> | Result<Initial>,
@@ -29,9 +30,10 @@ export async function attemptAsyncPipe<Initial, Piped>(
 /**
  * Attempt to pipe a value through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attemptPipe.async`
+ * _Available as `attemptAsyncPipe` and `attemptPipe.async`_
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export async function attemptAsyncPipe<Initial, First, Second>(
 	initial: GenericCallback | Initial | Promise<Initial> | Result<Initial>,
@@ -42,9 +44,10 @@ export async function attemptAsyncPipe<Initial, First, Second>(
 /**
  * Attempt to pipe a value through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attemptPipe.async`
+ * _Available as `attemptAsyncPipe` and `attemptPipe.async`_
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export async function attemptAsyncPipe<Initial, First, Second, Third>(
 	initial: GenericCallback | Initial | Promise<Initial> | Result<Initial>,
@@ -56,9 +59,10 @@ export async function attemptAsyncPipe<Initial, First, Second, Third>(
 /**
  * Attempt to pipe a value through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attemptPipe.async`
+ * _Available as `attemptAsyncPipe` and `attemptPipe.async`_
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export async function attemptAsyncPipe<Initial, First, Second, Third, Fourth>(
 	initial: GenericCallback | Initial | Promise<Initial> | Result<Initial>,
@@ -71,9 +75,10 @@ export async function attemptAsyncPipe<Initial, First, Second, Third, Fourth>(
 /**
  * Attempt to pipe a value through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attemptPipe.async`
+ * _Available as `attemptAsyncPipe` and `attemptPipe.async`_
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export async function attemptAsyncPipe<Initial, First, Second, Third, Fourth, Fifth>(
 	initial: GenericCallback | Initial | Promise<Initial> | Result<Initial>,
@@ -87,9 +92,10 @@ export async function attemptAsyncPipe<Initial, First, Second, Third, Fourth, Fi
 /**
  * Attempt to pipe a value through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attemptPipe.async`
+ * _Available as `attemptAsyncPipe` and `attemptPipe.async`_
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export async function attemptAsyncPipe<Initial, First, Second, Third, Fourth, Fifth, Sixth>(
 	initial: GenericCallback | Initial | Promise<Initial> | Result<Initial>,
@@ -104,9 +110,10 @@ export async function attemptAsyncPipe<Initial, First, Second, Third, Fourth, Fi
 /**
  * Attempt to pipe a value through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attemptPipe.async`
+ * _Available as `attemptAsyncPipe` and `attemptPipe.async`_
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export async function attemptAsyncPipe<
 	Initial,
@@ -131,9 +138,10 @@ export async function attemptAsyncPipe<
 /**
  * Attempt to pipe a value through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attemptPipe.async`
+ * _Available as `attemptAsyncPipe` and `attemptPipe.async`_
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export async function attemptAsyncPipe<
 	Initial,
@@ -160,9 +168,10 @@ export async function attemptAsyncPipe<
 /**
  * Attempt to pipe a value through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attemptPipe.async`
+ * _Available as `attemptAsyncPipe` and `attemptPipe.async`_
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export async function attemptAsyncPipe<
 	Initial,
@@ -191,9 +200,10 @@ export async function attemptAsyncPipe<
 /**
  * Attempt to pipe a value through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attemptPipe.async`
+ * _Available as `attemptAsyncPipe` and `attemptPipe.async`_
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export async function attemptAsyncPipe<
 	Initial,
@@ -224,9 +234,10 @@ export async function attemptAsyncPipe<
 /**
  * Attempt to pipe a result through a series of functions
  *
- * Available as `attemptAsyncPipe` and `attemptPipe.async`
+ * _Available as `attemptAsyncPipe` and `attemptPipe.async`_
+ *
  * @param initial Initial result
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export async function attemptAsyncPipe<Initial>(
 	initial: GenericCallback | Initial | Promise<Initial> | Result<Initial>,
@@ -265,8 +276,9 @@ export async function attemptAsyncPipe(
 
 /**
  * Attempt to pipe a value through a function
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export function attemptPipe<Initial, Pipe>(
 	initial: GenericCallback | Initial | Result<Initial>,
@@ -275,8 +287,9 @@ export function attemptPipe<Initial, Pipe>(
 
 /**
  * Attempt to pipe a value through a series of functions
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export function attemptPipe<Initial, First, Second>(
 	initial: GenericCallback | Initial | Result<Initial>,
@@ -286,8 +299,9 @@ export function attemptPipe<Initial, First, Second>(
 
 /**
  * Attempt to pipe a value through a series of functions
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export function attemptPipe<Initial, First, Second, Third>(
 	initial: GenericCallback | Initial | Result<Initial>,
@@ -298,8 +312,9 @@ export function attemptPipe<Initial, First, Second, Third>(
 
 /**
  * Attempt to pipe a value through a series of functions
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export function attemptPipe<Initial, First, Second, Third, Fourth>(
 	initial: GenericCallback | Initial | Result<Initial>,
@@ -311,8 +326,9 @@ export function attemptPipe<Initial, First, Second, Third, Fourth>(
 
 /**
  * Attempt to pipe a value through a series of functions
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export function attemptPipe<Initial, First, Second, Third, Fourth, Fifth>(
 	initial: GenericCallback | Initial | Result<Initial>,
@@ -325,8 +341,9 @@ export function attemptPipe<Initial, First, Second, Third, Fourth, Fifth>(
 
 /**
  * Attempt to pipe a value through a series of functions
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export function attemptPipe<Initial, First, Second, Third, Fourth, Fifth, Sixth>(
 	initial: GenericCallback | Initial | Result<Initial>,
@@ -340,8 +357,9 @@ export function attemptPipe<Initial, First, Second, Third, Fourth, Fifth, Sixth>
 
 /**
  * Attempt to pipe a value through a series of functions
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export function attemptPipe<Initial, First, Second, Third, Fourth, Fifth, Sixth, Seventh>(
 	initial: GenericCallback | Initial | Result<Initial>,
@@ -356,8 +374,9 @@ export function attemptPipe<Initial, First, Second, Third, Fourth, Fifth, Sixth,
 
 /**
  * Attempt to pipe a value through a series of functions
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export function attemptPipe<Initial, First, Second, Third, Fourth, Fifth, Sixth, Seventh, Eighth>(
 	initial: GenericCallback | Initial | Result<Initial>,
@@ -373,8 +392,9 @@ export function attemptPipe<Initial, First, Second, Third, Fourth, Fifth, Sixth,
 
 /**
  * Attempt to pipe a value through a series of functions
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export function attemptPipe<
 	Initial,
@@ -402,8 +422,9 @@ export function attemptPipe<
 
 /**
  * Attempt to pipe a value through a series of functions
+ *
  * @param initial Initial value
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export function attemptPipe<
 	Initial,
@@ -433,8 +454,9 @@ export function attemptPipe<
 
 /**
  * Attempt to pipe a result through a series of functions
+ *
  * @param initial Initial result
- * @returns Piped result
+ * @returns _Piped_ result
  */
 export function attemptPipe<Initial>(
 	initial: GenericCallback | Initial | Result<Initial>,

package/src/sized/map.ts

@@ -3,18 +3,18 @@ import {getSizedMaximum} from '../internal/sized';
 // #region Types and classes
 
 /**
- * A Map with a maximum size
+ * A _Map_ with a maximum size
  *
- * Behavior is similar to a _LRU_-cache, where the least recently used entries are removed
+ * Behavior is similar to a _LRU_ cache, where the least recently used entries are removed
  */
 export class SizedMap<SizedKey = unknown, SizedValue = unknown> extends Map<SizedKey, SizedValue> {
 	/**
-	 * The maximum size of the Map
+	 * The maximum size of the _Map_
 	 */
 	readonly #maximumSize: number;
 
 	/**
-	 * Is the Map full?
+	 * Is the _Map_ full?
 	 */
 	get full(): boolean {
 		return super.size >= this.#maximumSize;
@@ -25,27 +25,30 @@ export class SizedMap<SizedKey = unknown, SizedValue = unknown> extends Map<Size
 	}
 
 	/**
-	 * Create a new SizedMap with entries and a maximum size _(2^20)_
-	 * @param entries Array of key-value pairs to initialize the SizedMap with
-	 * @template SizedKey Type of the keys in the SizedMap
-	 * @template SizedValue Type of the values in the SizedMap
+	 * Create a new _SizedMap_ with entries and a maximum size _(2^20)_
+	 *
+	 * @param entries Array of key-value pairs to initialize the _SizedMap_ with
+	 * @template SizedKey Type of the keys in the _SizedMap_
+	 * @template SizedValue Type of the values in the _SizedMap_
 	 */
 	constructor(entries: [SizedKey, SizedValue][]);
 
 	/**
-	 * Create a new SizedMap with a maximum size _(but clamped at 2^24)_
-	 * @param maximum Maximum size of the SizedMap
-	 * @template SizedKey Type of the keys in the SizedMap
-	 * @template SizedValue Type of the values in the SizedMap
+	 * Create a new _SizedMap_ with a maximum size _(but clamped at 2^24)_
+	 *
+	 * @param maximum Maximum size of the _SizedMap_
+	 * @template SizedKey Type of the keys in the _SizedMap_
+	 * @template SizedValue Type of the values in the _SizedMap_
 	 */
 	constructor(maximum: number);
 
 	/**
-	 * Create a new SizedMap with _(optional)_ entries and a maximum size _(defaults to 2^20; clamped at 2^24)_
-	 * @param entries Array of key-value pairs to initialize the SizedMap with
-	 * @param maximum Maximum size of the SizedMap
-	 * @template SizedKey Type of the keys in the SizedMap
-	 * @template SizedValue Type of the values in the SizedMap
+	 * Create a new _SizedMap_ with _(optional)_ entries and a maximum size
+	 *
+	 * @param entries Array of key-value pairs to initialize the _SizedMap_ with
+	 * @param maximum Maximum size of the _SizedMap_ _(defaults to 2^20; clamped at 2^24)_
+	 * @template SizedKey Type of the keys in the _SizedMap_
+	 * @template SizedValue Type of the values in the _SizedMap_
 	 */
 	constructor(entries?: [SizedKey, SizedValue][], maximum?: number);
 

package/src/sized/set.ts

@@ -3,18 +3,18 @@ import {getSizedMaximum} from '../internal/sized';
 // #region Types
 
 /**
- * A Set with a maximum size
+ * A _Set_ with a maximum size
  *
- * Behavior is similar to a _LRU_-cache, where the oldest values are removed
+ * Behavior is similar to a _LRU_ cache, where the oldest values are removed
  */
 export class SizedSet<Value = unknown> extends Set<Value> {
 	/**
-	 * The maximum size of the Set
+	 * The maximum size of the _Set_
 	 */
 	readonly #maximumSize: number;
 
 	/**
-	 * Is the Set full?
+	 * Is the _Set_ full?
 	 */
 	get full(): boolean {
 		return this.size >= this.#maximumSize;
@@ -25,24 +25,27 @@ export class SizedSet<Value = unknown> extends Set<Value> {
 	}
 
 	/**
-	 * Create a new SizedSet with values and a maximum size _(2^20)_
-	 * @param values Array of values to initialize the SizedSet with
-	 * @template Value Type of the values in the SizedSet
+	 * Create a new _SizedSet_ with values and a maximum size _(2^20)_
+	 *
+	 * @param values Array of values to initialize the _SizedSet_ with
+	 * @template Value Type of the values in the _SizedSet_
 	 */
 	constructor(values: Value[]);
 
 	/**
-	 * Create a new SizedSet with a maximum size _(but clamped at 2^24)_
-	 * @param maximum Maximum size of the SizedSet
-	 * @template Value Type of the values in the SizedSet
+	 * Create a new _SizedSet_ with a maximum size _(but clamped at 2^24)_
+	 *
+	 * @param maximum Maximum size of the _SizedSet_ _(defaults to 2^20; clamped at 2^24)_
+	 * @template Value Type of the values in the _SizedSet_
 	 */
 	constructor(maximum: number);
 
 	/**
-	 * Create a new SizedSet with _(optional)_ values and a maximum size _(defaults to 2^20; clamped at 2^24)_
-	 * @param values Array of values to initialize the SizedSet with
-	 * @param maximum Maximum size of the SizedSet
-	 * @template Value Type of the values in the SizedSet
+	 * Create a new _SizedSet_ with _(optional)_ values and a maximum size
+	 *
+	 * @param values Array of values to initialize the _SizedSet_ with
+	 * @param maximum Maximum size of the _SizedSet_ _(defaults to 2^20; clamped at 2^24)_
+	 * @template Value Type of the values in the _SizedSet_
 	 */
 	constructor(values?: Value[], maximum?: number);
 
@@ -82,9 +85,10 @@ export class SizedSet<Value = unknown> extends Set<Value> {
 	}
 
 	/**
-	 * Get a value from the SizedSet, if it exists _(and move it to the end)_
-	 * @param value Value to get from the SizedSet
-	 * @param update Update the value's position in the SizedSet? _(defaults to `false`)_
+	 * Get a value from the _SizedSet_, if it exists _(and optionally move it to the end)_
+	 *
+	 * @param value Value to get from the _SizedSet_
+	 * @param update Update the value's position in the _SizedSet_? _(defaults to `false`)_
 	 * @returns Found value if it exists, otherwise `undefined`
 	 */
 	get(value: Value, update?: boolean): Value | undefined {

package/src/string/case.ts

@@ -17,6 +17,7 @@ type Options = {
 
 /**
  * Convert a string to camel case _(thisIsCamelCase)_
+ *
  * @param value String to convert
  * @returns Camel-cased string
  */
@@ -26,6 +27,7 @@ export function camelCase(value: string): string {
 
 /**
  * Capitalize the first letter of a string _(and lowercase the rest)_
+ *
  * @param value String to capitalize
  * @returns Capitalized string
  */
@@ -45,6 +47,7 @@ export function capitalize(value: string): string {
 
 /**
  * Convert a string to kebab case _(this-is-kebab-case)_
+ *
  * @param value String to convert
  * @returns Kebab-cased string
  */
@@ -54,6 +57,7 @@ export function kebabCase(value: string): string {
 
 /**
  * Convert a string to lower case
+ *
  * @param value String to convert
  * @returns Lower-cased string
  */
@@ -69,6 +73,7 @@ export function lowerCase(value: string): string {
 
 /**
  * Convert a string to pascal case _(ThisIsPascalCase)_
+ *
  * @param value String to convert
  * @returns Pascal-cased string
  */
@@ -78,6 +83,7 @@ export function pascalCase(value: string): string {
 
 /**
  * Convert a string to snake case _(this_is_snake_case)_
+ *
  * @param value String to convert
  * @returns Snake-cased string
  */
@@ -87,6 +93,7 @@ export function snakeCase(value: string): string {
 
 /**
  * Convert a string to title case _(Capitalizing Every Word)_
+ *
  * @param value String to convert
  * @returns Title-cased string
  */
@@ -169,6 +176,7 @@ function toCaseCallback(this: Options, value: string): string {
 
 /**
  * Convert a string to upper case
+ *
  * @param value String to convert
  * @returns Upper-cased string
  */

package/src/string/fuzzy.ts

@@ -14,6 +14,8 @@ class Fuzzy<Item> {
 
 	/**
 	 * Get items currently being searched through
+	 *
+	 * @returns Original items
 	 */
 	get items(): Item[] {
 		return this.#state.items.slice();
@@ -21,6 +23,8 @@ class Fuzzy<Item> {
 
 	/**
 	 * Set new items to search through
+	 *
+	 * @param items New items to search through
 	 */
 	set items(items: Item[]) {
 		if (Array.isArray(items)) {
@@ -31,6 +35,8 @@ class Fuzzy<Item> {
 
 	/**
 	 * Get strings currently being searched through _(the stringified version of `items`)_
+	 *
+	 * @returns Stringified items
 	 */
 	get strings(): string[] {
 		return this.#state.strings.slice();
@@ -42,6 +48,7 @@ class Fuzzy<Item> {
 
 	/**
 	 * Search for items matching the given value
+	 *
 	 * @param value Value to search for
 	 * @param options Search options
 	 * @returns Search results, with exact matches _(ordered)_ and similar matches _(ordered by relevance)_
@@ -50,6 +57,7 @@ class Fuzzy<Item> {
 
 	/**
 	 * Search for items matching the given value
+	 *
 	 * @param value Value to search for
 	 * @param limit Maximum number of combined items to return in `exact` and `similar`
 	 * @returns Search results, with exact matches _(ordered)_ and similar matches _(ordered by relevance)_
@@ -70,9 +78,8 @@ export type FuzzyConfiguration<Item> = {
 	/**
 	 * Handler to stringify items
 	 *
-	 * May be a function that takes an item and returns a string, or if items are plain objects, a key of the item to use to grab a string value from
-	 *
-	 * Defaults to `getString`
+	 * - May be a function that takes an item and returns a string, or if items are plain objects, a key of the item to use to grab a string value from
+	 * - Defaults to `getString`
 	 */
 	handler?: (item: Item) => string;
 } & (Item extends PlainObject
@@ -80,7 +87,7 @@ export type FuzzyConfiguration<Item> = {
 			/**
 			 * Key to use to stringify items
 			 *
-			 * Prioritized over `handler`
+			 * _Prioritized over `handler`_
 			 */
 			key?: keyof Item;
 		}
@@ -98,7 +105,10 @@ export type FuzzyOptions = {
 	 */
 	limit?: number;
 	/**
-	 * Maximum score difference between the best and worst similar matches included in results; higher values cast a wider net _(defaults to 5)_
+	 * Maximum score difference between the best and worst similar matches included in results
+	 *
+	 * - Higher values cast a wider net
+	 * - Defaults to `5`
 	 */
 	tolerance?: number;
 };
@@ -207,6 +217,7 @@ function getTolerance<Item>(input: unknown, state?: FuzzyState<Item>): number {
 
 /**
  * Create a fuzzy searcher for an array of items
+ *
  * @param items Items to search through
  * @param key Key to use to stringify items
  * @returns Fuzzy searcher
@@ -218,6 +229,7 @@ export function fuzzy<Item extends PlainObject, ItemKey extends keyof Item>(
 
 /**
  * Create a fuzzy searcher for an array of items
+ *
  * @param items Items to search through
  * @param handler Handler to stringify items
  * @returns Fuzzy searcher
@@ -226,6 +238,7 @@ export function fuzzy<Item>(items: Item[], handler?: (item: Item) => string): Fu
 
 /**
  * Create a fuzzy searcher for an array of items
+ *
  * @param items Items to search through
  * @param configuration Fuzzy configuration
  * @returns Fuzzy searcher
@@ -244,6 +257,7 @@ fuzzy.match = fuzzyMatch;
 
 /**
  * Does the needle match the haystack in a fuzzy way?
+ *
  * @param haystack Haystack to search through
  * @param needle Needle to search for
  * @returns `true` if the needle matches the haystack in a fuzzy way, `false` otherwise

package/src/string/index.ts

@@ -1,10 +1,21 @@
 import {isTemplateStringsArray} from '../internal/is';
-import {getString} from '../internal/string';
+import {interpolate} from '../internal/string';
 
 // #region Functions
 
+/**
+ * Dedent a string template, removing common leading whitespace from each line
+ *
+ * @returns Dedented string
+ */
 export function dedent(strings: TemplateStringsArray, ...values: unknown[]): string;
 
+/**
+ * Dedent a string, removing common leading whitespace from each line
+ *
+ * @param value String to dedent
+ * @returns Dedented string
+ */
 export function dedent(value: string): string;
 
 export function dedent(value: string | TemplateStringsArray, ...values: unknown[]): string {
@@ -59,7 +70,8 @@ export function dedent(value: string | TemplateStringsArray, ...values: unknown[
 }
 
 /**
- * Get a new UUID-string _(version 4)_
+ * Get a new UUID string _(version 4)_
+ *
  * @returns UUID string
  */
 export function getUuid(): string {
@@ -82,20 +94,9 @@ export function getUuid(): string {
 	].join('-');
 }
 
-function interpolate(strings: TemplateStringsArray, values: unknown[]): string {
-	const {length} = strings;
-
-	let interpolated = '';
-
-	for (let index = 0; index < length; index += 1) {
-		interpolated += `${strings[index]}${getString(values[index])}`;
-	}
-
-	return interpolated;
-}
-
 /**
  * Parse a JSON string into its proper value _(or `undefined` if it fails)_
+ *
  * @param value JSON string to parse
  * @param reviver Reviver function to transform the parsed values
  * @returns Parsed value or `undefined` if parsing fails
@@ -113,6 +114,7 @@ export function parse(
 
 /**
  * Trim a string _(removing whitespace from both ends)_
+ *
  * @param value String to trim
  * @returns Trimmed string
  */
@@ -121,7 +123,8 @@ export function trim(value: string): string {
 }
 
 /**
- * Truncate a string to a specified length, when possible
+ * Truncate a string to a specified length
+ *
  * @param value String to truncate
  * @param length Maximum length of the string after truncation
  * @param suffix Suffix to append to the truncated string

package/src/string/match.ts

@@ -10,6 +10,7 @@ type Match = 'endsWith' | 'includes' | 'startsWith';
 
 /**
  * Check if a string ends with a specified substring
+ *
  * @param haystack String to look in
  * @param needle String to look for
  * @param ignoreCase Ignore case when matching? _(defaults to `false`)_
@@ -21,6 +22,7 @@ export function endsWith(haystack: string, needle: string, ignoreCase?: boolean)
 
 /**
  * Check if a string includes a specified substring
+ *
  * @param haystack String to look in
  * @param needle String to look for
  * @param ignoreCase Ignore case when matching? _(defaults to `false`)_
@@ -53,6 +55,7 @@ function matchCallback(
 
 /**
  * Check if a string starts with a specified substring
+ *
  * @param haystack String to look in
  * @param needle String to look for
  * @param ignoreCase Ignore case when matching? _(defaults to `false`)_