@oscarpalmer/atoms 0.218.0 → 0.219.0

package/dist/internal/string/case.mjs

@@ -7,6 +7,14 @@ import { STRING_CASE_CAMEL, STRING_CASE_KEBAB, STRING_CASE_PASCAL, STRING_CASE_S
 *
 * @param value String to convert
 * @returns Camel-cased string
+*
+* @example
+* ```typescript
+* camelCase('this is camel case'); // => 'thisIsCamelCase'
+* camelCase('ThisIsCamelCase');    // => 'thisIsCamelCase'
+* camelCase('this-is-camel-case'); // => 'thisIsCamelCase'
+* camelCase('this_is_camel_case'); // => 'thisIsCamelCase'
+* ```
 */
 function camelCase(value) {
 	return toCase(STRING_CASE_CAMEL, value, true, false);
@@ -16,6 +24,14 @@ function camelCase(value) {
 *
 * @param value String to capitalize
 * @returns Capitalized string
+*
+* @example
+* ```typescript
+* capitalize('this is a test'); // => 'This is a test'
+* capitalize('This Is A Test'); // => 'This is a test'
+* capitalize('t');              // => 'T'
+* capitalize('');               // => ''
+* ```
 */
 function capitalize(value) {
 	if (typeof value !== "string" || value.length === 0) return "";
@@ -27,6 +43,14 @@ function capitalize(value) {
 *
 * @param value String to convert
 * @returns Kebab-cased string
+*
+* @example
+* ```typescript
+* kebabCase('this is kebab case'); // => 'this-is-kebab-case'
+* kebabCase('ThisIsKebabCase');    // => 'this-is-kebab-case'
+* kebabCase('this-is-kebab-case'); // => 'this-is-kebab-case'
+* kebabCase('this_is_kebab_case'); // => 'this-is-kebab-case'
+* ```
 */
 function kebabCase(value) {
 	return toCase(STRING_CASE_KEBAB, value, false, false);
@@ -36,6 +60,13 @@ function kebabCase(value) {
 *
 * @param value String to convert
 * @returns Lower-cased string
+*
+* @example
+* ```typescript
+* lowerCase('THIS IS A TEST'); // => 'this is a test'
+* lowerCase('this is a test'); // => 'this is a test'
+* lowerCase('t');              // => 't'
+* ```
 */
 function lowerCase(value) {
 	if (typeof value !== "string") return "";
@@ -47,6 +78,14 @@ function lowerCase(value) {
 *
 * @param value String to convert
 * @returns Pascal-cased string
+*
+* @example
+* ```typescript
+* pascalCase('this is pascal case'); // => 'ThisIsPascalCase'
+* pascalCase('ThisIsPascalCase');    // => 'ThisIsPascalCase'
+* pascalCase('this-is-pascal-case'); // => 'ThisIsPascalCase'
+* pascalCase('this_is_pascal_case'); // => 'ThisIsPascalCase'
+* ```
 */
 function pascalCase(value) {
 	return toCase(STRING_CASE_PASCAL, value, true, true);
@@ -56,6 +95,14 @@ function pascalCase(value) {
 *
 * @param value String to convert
 * @returns Snake-cased string
+*
+* @example
+* ```typescript
+* snakeCase('this is snake case'); // => 'this_is_snake_case'
+* snakeCase('ThisIsSnakeCase');    // => 'this_is_snake_case'
+* snakeCase('this-is-snake-case'); // => 'this_is_snake_case'
+* snakeCase('this_is_snake_case'); // => 'this_is_snake_case'
+* ```
 */
 function snakeCase(value) {
 	return toCase(STRING_CASE_SNAKE, value, false, false);
@@ -65,6 +112,14 @@ function snakeCase(value) {
 *
 * @param value String to convert
 * @returns Title-cased string
+*
+* @example
+* ```typescript
+* titleCase('this is a test'); // => 'This Is A Test'
+* titleCase('This Is A Test'); // => 'This Is A Test'
+* titleCase('t');              // => 'T'
+* titleCase('');               // => ''
+* ```
 */
 function titleCase(value) {
 	if (typeof value !== "string" || value.length === 0) return "";
@@ -107,6 +162,14 @@ function toCaseCallback(value) {
 *
 * @param value String to convert
 * @returns Upper-cased string
+*
+* @example
+* ```typescript
+* upperCase('this is a test'); // => 'THIS IS A TEST'
+* upperCase('This Is A Test'); // => 'THIS IS A TEST'
+* upperCase('t');              // => 'T'
+* upperCase('');               // => ''
+* ```
 */
 function upperCase(value) {
 	if (typeof value !== "string" || value.length === 0) return "";

package/dist/internal/string/misc.d.mts

@@ -17,7 +17,13 @@
  * ```
  */
 export declare function getString(value: unknown): string;
+/**
+ * @internal
+ */
 export declare function ignoreKey(key: string): boolean;
+/**
+ * @internal
+ */
 export declare function interpolate(strings: TemplateStringsArray, values: unknown[]): string;
 /**
  * Join an array of values into a string _(while ignoring empty values)_
@@ -27,9 +33,23 @@ export declare function interpolate(strings: TemplateStringsArray, values: unkno
  * @param array Array of values
  * @param delimiter Delimiter to use between values
  * @returns Joined string
+ * @example
+ * ```typescript
+ * join(['a', 'b', 'c']);          // => 'abc'
+ * join(['a', 'b', 'c'], ', ');   // => 'a, b, c'
+ * join(['a', '', 'c']);           // => 'ac'
+ * join([null, 'b', undefined]);   // => 'b'
+ * join([]);                       // => ''
+ * ```
  */
 export declare function join(array: unknown[], delimiter?: string): string;
+/**
+ * @internal
+ */
 export declare function tryDecode(value: string): string;
+/**
+ * @internal
+ */
 export declare function tryEncode(value: boolean | number | string): unknown;
 /**
  * Split a string into words _(and other readable parts)_

package/dist/internal/string/misc.mjs

@@ -27,9 +27,15 @@ function getString(value) {
 	const asString = String(value.valueOf?.() ?? value);
 	return asString.startsWith("[object ") ? JSON.stringify(value) : asString;
 }
+/**
+* @internal
+*/
 function ignoreKey(key) {
 	return STRING_EXPRESSION_IGNORED.test(key);
 }
+/**
+* @internal
+*/
 function interpolate(strings, values) {
 	const { length } = strings;
 	let interpolated = "";
@@ -47,6 +53,14 @@ function interpolate(strings, values) {
 * @param array Array of values
 * @param delimiter Delimiter to use between values
 * @returns Joined string
+* @example
+* ```typescript
+* join(['a', 'b', 'c']);          // => 'abc'
+* join(['a', 'b', 'c'], ', ');   // => 'a, b, c'
+* join(['a', '', 'c']);           // => 'ac'
+* join([null, 'b', undefined]);   // => 'b'
+* join([]);                       // => ''
+* ```
 */
 function join(array, delimiter) {
 	if (!Array.isArray(array)) return "";
@@ -62,9 +76,15 @@ function join(array, delimiter) {
 function tryCallback(value, callback) {
 	return unwrap(attempt(() => callback(value)), value);
 }
+/**
+* @internal
+*/
 function tryDecode(value) {
 	return tryCallback(value, decodeURIComponent);
 }
+/**
+* @internal
+*/
 function tryEncode(value) {
 	return tryCallback(value, encodeURIComponent);
 }

package/dist/logger.d.mts

@@ -1,7 +1,19 @@
 import { Lumberjack, TimeLogger } from "./models/logger.model.mjs";
 //#region src/logger.d.ts
 declare function TimeLogger(this: any, label: string): void;
+/**
+ * Is the value a _Logger_?
+ *
+ * @param value Value to check
+ * @returns `true` if the value is a _Logger_, otherwise `false`
+ */
 declare function isLogger(value: unknown): value is Lumberjack;
+/**
+ * Is the value a _TimeLogger_?
+ *
+ * @param value Value to check
+ * @returns `true` if the value is a _TimeLogger_, otherwise `false`
+ */
 declare function isTimeLogger(value: unknown): value is TimeLogger;
 /**
  * A logger that can be used to log messages to the console

package/dist/logger.mjs

@@ -64,12 +64,24 @@ function getTimeLoggerStop() {
 	}
 	return noop;
 }
+/**
+* Is the value a _Logger_?
+*
+* @param value Value to check
+* @returns `true` if the value is a _Logger_, otherwise `false`
+*/
 function isLogger(value) {
 	return isLoggerInstance(LOGGER_NAME, value);
 }
 function isLoggerInstance(name, value) {
 	return typeof value === "object" && value !== null && "$logger" in value && value["$logger"] === name;
 }
+/**
+* Is the value a _TimeLogger_?
+*
+* @param value Value to check
+* @returns `true` if the value is a _TimeLogger_, otherwise `false`
+*/
 function isTimeLogger(value) {
 	return isLoggerInstance(LOGGER_NAME_TIMED, value);
 }

package/dist/math.d.mts

@@ -8,6 +8,16 @@ import { floor, round } from "./internal/math/misc.mjs";
  * @param items List of items
  * @param callback Callback to get an item's value
  * @returns Average value, or `Number.NaN` if no average can be calculated
+ *
+ * @example
+ * ```typescript
+ * average([
+ *   {value: 1},
+ *   {value: 2},
+ *   {value: 3},
+ * ], item => item.value); // => 2
+ * average([{value: 1}], item => item.nope); // => Number.NaN
+ * ```
  */
 export declare function average<Item>(items: Item[], callback: (item: Item, index: number, array: Item[]) => number): number;
 /**
@@ -16,6 +26,12 @@ export declare function average<Item>(items: Item[], callback: (item: Item, inde
  * @param items List of items
  * @param key Key to use for value
  * @returns Average value, or `Number.NaN` if no average can be calculated
+ *
+ * @example
+ * ```typescript
+ * average([{value: 1}, {value: 2}, {value: 3}], 'value'); // => 2
+ * average([{value: 1}], 'nope'); // => Number.NaN
+ * ```
  */
 export declare function average<Item extends PlainObject>(items: Item[], key: keyof NumericalValues<Item>): number;
 /**
@@ -23,6 +39,12 @@ export declare function average<Item extends PlainObject>(items: Item[], key: ke
  *
  * @param numbers List of numbers
  * @returns Average value, or `Number.NaN` if no average can be calculated
+ *
+ * @example
+ * ```typescript
+ * average([1, 2, 3, 4, 5]); // => 3
+ * average([]); // => Number.NaN
+ * ```
  */
 export declare function average(numbers: number[]): number;
 /**
@@ -31,6 +53,13 @@ export declare function average(numbers: number[]): number;
  * @param value Number to round up
  * @param decimals Number of decimal places to round to _(defaults to `0`)_
  * @returns Rounded number, or `Number.NaN` if the value if unable to be rounded
+ *
+ * @example
+ * ```typescript
+ * ceil(1.234, 2); // => 1.24
+ * ceil(1.234);    // => 2
+ * ceil('abc');    // => Number.NaN
+ * ```
  */
 export declare function ceil(value: number, decimals?: number): number;
 /**
@@ -40,6 +69,14 @@ export declare function ceil(value: number, decimals?: number): number;
  * @param callback Callback to get an item's value
  * @param value Value to match and count
  * @returns Number of items that match the condition, or `Number.NaN` if no count can be calculated
+ *
+ * @example
+ * ```typescript
+ * count([1, 2, 3, 2], (item) => item, 2); // => 2
+ * count([{value: 1}, {value: 2}, {value: 3}], 'value', 2); // => 1
+ * count([1, 2, 3], (item) => item, 4); // => 0
+ * count([], (item) => item, 1); // => Number.NaN
+ * ```
  */
 export declare function count<Item>(array: Item[], callback: (item: Item, index: number, array: Item[]) => unknown, value: unknown): number;
 /**
@@ -49,6 +86,12 @@ export declare function count<Item>(array: Item[], callback: (item: Item, index:
  * @param key Key to use for value
  * @param value Value to match and count
  * @returns Number of items with the specified key value, or `Number.NaN` if no count can be calculated
+ *
+ * @example
+ * ```typescript
+ * count([{value: 1}, {value: 2}, {value: 3}], 'value', 2); // => 1
+ * count([{value: 1}], 'nope', 1); // => Number.NaN
+ * ```
  */
 export declare function count<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): number;
 /**
@@ -56,6 +99,12 @@ export declare function count<Item extends PlainObject, ItemKey extends keyof It
  *
  * @param values Array to count for
  * @returns Number of items, or `Number.NaN` if no count can be calculated
+ *
+ * @example
+ * ```typescript
+ * count([1, 2, 3]); // => 3
+ * count([]);        // => Number.NaN
+ * ```
  */
 export declare function count(values: unknown[]): number;
 /**
@@ -64,6 +113,13 @@ export declare function count(values: unknown[]): number;
  * @param array List of items
  * @param callback Callback to get an item's value
  * @returns Median value, or `Number.NaN` if no median can be calculated
+ *
+ * @example
+ * ```typescript
+ * median([1, 2, 3, 4, 5]); // => 3
+ * median([1, 2, 3, 4]);    // => 2.5
+ * median([]);              // => Number.NaN
+ * ```
  */
 export declare function median<Item>(array: Item[], callback: (item: Item, index: number, array: Item[]) => number): number;
 /**
@@ -72,6 +128,13 @@ export declare function median<Item>(array: Item[], callback: (item: Item, index
  * @param array List of items
  * @param key Key to use for value
  * @returns Median value, or `Number.NaN` if no median can be calculated
+ *
+ * @example
+ * ```typescript
+ * median([{value: 1}, {value: 2}, {value: 3}], 'value'); // => 2
+ * median([{value: 1}, {value: 2}, {value: 3}, {value: 4}], 'value'); // => 2.5
+ * median([], 'value'); // => Number.NaN
+ * ```
  */
 export declare function median<Item extends PlainObject>(array: Item[], key: keyof NumericalValues<Item>): number;
 /**
@@ -79,6 +142,13 @@ export declare function median<Item extends PlainObject>(array: Item[], key: key
  *
  * @param array List of numbers
  * @returns Median value, or `Number.NaN` if no median can be calculated
+ *
+ * @example
+ * ```typescript
+ * median([1, 2, 3, 4, 5]); // => 3
+ * median([1, 2, 3, 4]);    // => 2.5
+ * median([]);              // => Number.NaN
+ * ```
  */
 export declare function median(array: number[]): number;
 /**
@@ -87,6 +157,13 @@ export declare function median(array: number[]): number;
  * @param items List of items
  * @param callback Callback to get an item's value
  * @returns Sum of the values, or `Number.NaN` if no sum can be calculated
+ *
+ * @example
+ * ```typescript
+ * sum([{value: 1}, {value: 2}, {value: 3}], 'value'); // => 6
+ * sum([{value: 1}, {value: 2}, {value: 3}], item => item.value); // => 6
+ * sum([]); // => Number.NaN
+ * ```
  */
 export declare function sum<Item>(items: Item[], callback: (item: Item, index: number, array: Item[]) => number): number;
 /**
@@ -95,6 +172,13 @@ export declare function sum<Item>(items: Item[], callback: (item: Item, index: n
  * @param items List of items
  * @param key Key to use for value
  * @returns Sum of the values, or `Number.NaN` if no sum can be calculated
+ *
+ * @example
+ * ```typescript
+ * sum([{value: 1}, {value: 2}, {value: 3}], 'value'); // => 6
+ * sum([{value: 1}, {value: 2}, {value: 3}], item => item.value); // => 6
+ * sum([]); // => Number.NaN
+ * ```
  */
 export declare function sum<Item extends PlainObject>(items: Item[], key: keyof NumericalValues<Item>): number;
 /**
@@ -102,6 +186,12 @@ export declare function sum<Item extends PlainObject>(items: Item[], key: keyof
  *
  * @param values List of numbers
  * @returns Sum of the numbers, or `Number.NaN` if no sum can be calculated
+ *
+ * @example
+ * ```typescript
+ * sum([1, 2, 3]); // => 6
+ * sum([]);        // => Number.NaN
+ * ```
  */
 export declare function sum(values: number[]): number;
 //#endregion

package/dist/math.mjs

@@ -13,6 +13,13 @@ function average(array, key) {
 * @param value Number to round up
 * @param decimals Number of decimal places to round to _(defaults to `0`)_
 * @returns Rounded number, or `Number.NaN` if the value if unable to be rounded
+*
+* @example
+* ```typescript
+* ceil(1.234, 2); // => 1.24
+* ceil(1.234);    // => 2
+* ceil('abc');    // => Number.NaN
+* ```
 */
 function ceil(value, decimals) {
 	return roundNumber(Math.ceil, value, decimals);

package/dist/models/array/array.find.model.d.mts

@@ -1,8 +1,34 @@
+import { GenericCallback } from "../index.mjs";
 //#region src/models/array/array.find.model.d.ts
+export type ArrayFindLimitOptions = {
+  limit?: number;
+  map?: never;
+};
+export type ArrayFindMapOptions = {
+  limit?: never;
+  map?: ArrayFindMapper;
+};
 export type ArrayFindMapper = {
   callback: unknown;
+  flat: boolean;
   reverse: boolean;
 };
+export type ArrayFindOptions = ArrayFindMapOptions | ArrayFindLimitOptions;
+export type ArrayFindParameters = {
+  array: unknown[];
+  arrayLength: number;
+  callback?: GenericCallback;
+  flat: boolean;
+  limit: number;
+  map?: ArrayFindParametersMap;
+  result: ArrayFindValuesResult;
+  type: ArrayFindValuesType;
+  value: unknown;
+};
+export type ArrayFindParametersMap = {
+  after?: GenericCallback;
+  before?: GenericCallback;
+};
 export type ArrayFindValueType = "index" | "item";
 export type ArrayFindValuesResult = {
   matched: unknown[];

package/dist/models/array/array.misc.model.d.mts

@@ -1,4 +1,4 @@
-import { GenericCallback, PlainObject } from "../index.mjs";
+import { GenericCallback } from "../index.mjs";
 //#region src/models/array/array.misc.model.d.ts
 export type ArrayCompareSetsType = "difference" | "intersection" | "union";
 /**
@@ -6,6 +6,7 @@ export type ArrayCompareSetsType = "difference" | "intersection" | "union";
  */
 export type ArrayComparison = "end" | "inside" | "invalid" | "outside" | "same" | "start";
 export type ArrayExtractType = "drop" | "take";
+export type ArrayFlattened<Value> = Value extends ReadonlyArray<infer Inner> ? Inner : Value;
 export type ArrayGetCallbacks = {
   bool?: GenericCallback;
   keyed?: GenericCallback;
@@ -16,9 +17,6 @@ export type ArrayOverlapItem = {
   array: unknown[];
   index: number;
 };
-export type ArrayMapKeyOrCallback<Item> = ((item: Item, index: number, array: Item[]) => unknown) | (Item extends PlainObject ? keyof Item : never);
-export type ArrayMapped<Item, Map extends ArrayMapKeyOrCallback<Item>> = Map extends ((item: Item, index: number, array: Item[]) => unknown) ? ReturnType<Map> : Map extends keyof Item ? Item[Map] : never;
-export type ArrayObjectKeysOf<Item> = { [Key in keyof Item]: Item[Key] extends PlainObject ? Key : never; }[keyof Item];
 export type ArrayOverlapResult = {
   first: ArrayOverlapItem;
   second: ArrayOverlapItem;

package/dist/models/index.d.mts

@@ -49,7 +49,7 @@ export type KeyOrCallbackValue<Item, Arg extends KeyOrCallback<Item>> = Arg exte
 /**
  * A nested array
  */
-export type NestedArray<Value> = Value extends Array<infer NestedValue> ? NestedArray<NestedValue> : Value;
+export type NestedArray<Value> = Value extends ReadonlyArray<infer NestedValue> ? NestedArray<NestedValue> : Value;
 /**
  * All nested keys of an object as dot notation strings _(up to 5 levels deep)_
  */

package/dist/models/value/value.merge.model.d.mts

@@ -8,7 +8,7 @@ type BaseOptions = {
   /**
    * Key _(or key epxressions)_ for values that should be replaced
    *
-   * ```ts
+   * ```typescript
    * merge([{items: [1, 2, 3]}, {items: [99]}]); // => {items: [99]}
    * ```
    */
@@ -16,7 +16,7 @@ type BaseOptions = {
   /**
    * Skip nullable values when merging objects?
    *
-   * ```ts
+   * ```typescript
    * merge({a: 1, b: 2}, {b: null, c: 3}, {d: null}); // => {a: 1, b: 2, c: 3}
    * ```
    */
@@ -24,7 +24,7 @@ type BaseOptions = {
   /**
    * Skip nullable values when merging arrays?
    *
-   * ```ts
+   * ```typescript
    * merge([1, 2, 3], [null, null, 99]); // => [1, 2, 99]
    * ```
    */

package/dist/promise/misc.d.mts

@@ -11,7 +11,13 @@ import { isFulfilled, isRejected } from "./helpers.mjs";
  * @returns Cancelable _Promise_
  */
 export declare function cancelable<Value>(executor: (resolve: (value: Value) => void, reject: (reason: unknown) => void) => void): CancelablePromise<Value>;
+/**
+ * @internal
+ */
 export declare function handleResult(status: string, parameters: PromiseParameters): void;
+/**
+ * @internal
+ */
 export declare function settlePromise(settler: (value: any) => void, value: unknown, aborter?: Aborter): void;
 /**
  * Converts a _Promise_ to a promised result

package/dist/promise/misc.mjs

@@ -12,6 +12,9 @@ import { isFulfilled, isRejected } from "./helpers.mjs";
 function cancelable(executor) {
 	return new CancelablePromise(executor);
 }
+/**
+* @internal
+*/
 function handleResult(status, parameters) {
 	const { aborter, complete, data, handlers, index, key, value } = parameters;
 	if (aborter?.signal.aborted ?? false) return;
@@ -35,6 +38,9 @@ function handleResult(status, parameters) {
 		handlers.resolve(data.result);
 	}
 }
+/**
+* @internal
+*/
 function settlePromise(settler, value, aborter) {
 	aborter?.cancel();
 	settler(value);

package/dist/promise/timed.d.mts

@@ -1,6 +1,9 @@
 import { RequiredKeys } from "../models/index.mjs";
 import { PromiseOptions } from "../models/promise.model.mjs";
 //#region src/promise/timed.d.ts
+/**
+ * @internal
+ */
 export declare function getTimedPromise<Value>(promise: Promise<Value>, time: number, signal?: AbortSignal): Promise<Value>;
 /**
  * Create a _Promise_ that should be settled within a certain amount of time

package/dist/promise/timed.mjs

@@ -5,6 +5,9 @@ import { PROMISE_MESSAGE_EXPECTATION_TIMED, PromiseTimeoutError } from "../model
 import { createPromiseOptions } from "./helpers.mjs";
 import { settlePromise } from "./misc.mjs";
 //#region src/promise/timed.ts
+/**
+* @internal
+*/
 async function getTimedPromise(promise, time, signal) {
 	const aborter = createAborter(signal, () => {
 		limiter.cancel();

package/dist/queue.d.mts

@@ -17,7 +17,6 @@ export declare function isKeyedQueue(value: unknown): value is KeyedQueue<Generi
  * @returns `true` if the value is a queue, otherwise `false`
  */
 export declare function isQueue(value: unknown): value is Queue<GenericCallback | GenericAsyncCallback>;
-export declare function isQueueInstance<Instance>(name: string, value: unknown): value is Instance;
 /**
  * Create a keyed queue for an asynchronous callback function, where each key has its own queue
  *

package/dist/queue.mjs

@@ -360,4 +360,4 @@ async function run(state) {
 }
 queue.keyed = keyedQueue;
 //#endregion
-export { isKeyedQueue, isQueue, isQueueInstance, keyedQueue, queue };
+export { isKeyedQueue, isQueue, keyedQueue, queue };

package/dist/string/index.d.mts

@@ -31,7 +31,7 @@ export declare function getUuid(): string;
  *
  * @param value JSON string to parse
  * @param reviver Reviver function to transform the parsed values
- * @returns Parsed value or `undefined` if parsing fails
+ * @returns Parsed value, or `undefined` if parsing fails
  */
 export declare function parse(value: string, reviver?: (this: unknown, key: string, value: unknown) => unknown): unknown;
 /**
@@ -39,6 +39,13 @@ export declare function parse(value: string, reviver?: (this: unknown, key: stri
  *
  * @param value String to trim
  * @returns Trimmed string
+ * @example
+ * ```typescript
+ * trim('  this is a test  '); // => 'this is a test'
+ * trim('this is a test');     // => 'this is a test'
+ * trim('   ');                // => ''
+ * trim('');                   // => ''
+ * ```
  */
 export declare function trim(value: string): string;
 /**
@@ -48,6 +55,13 @@ export declare function trim(value: string): string;
  * @param length Maximum length of the string after truncation
  * @param suffix Suffix to append to the truncated string
  * @returns Truncated string
+ * @example
+ * ```typescript
+ * truncate('this is a test', 7);          // => 'this is'
+ * truncate('this is a test', 7, '...');   // => 'this ...'
+ * truncate('this is a test', 20);         // => 'this is a test'
+ * truncate('this is a test', 0);          // => ''
+ * ```
  */
 export declare function truncate(value: string, length: number, suffix?: string): string;
 //#endregion