@goast/core 0.7.0 → 0.7.1

package/dist/src/utils/source-builder.d.ts

@@ -3,6 +3,10 @@ import { type StringBuilderOptions } from './string-builder/options.ts';
 import { type AppendParam, type BuilderFn, StringBuilder } from './string-builder/string-builder.ts';
 import type { AppendValue } from './string-builder/utils.ts';
 import type { Nullable } from './type.utils.ts';
+/**
+ * Describes one level of indentation. `{ type: 'tabs' }` indents with a tab character, and `{ type: 'spaces', count }`
+ * indents with `count` space characters.
+ */
 export type IndentOptions = {
     readonly type: 'tabs';
 } | {
@@ -24,8 +28,31 @@ export type SourceBuilderOptions = StringBuilderOptions & {
  */
 export declare const defaultSourceBuilderOptions: SourceBuilderOptions;
 type KnownParatheses = '()' | '[]' | '{}' | '<>';
+/**
+ * The brackets that `parenthesize` adds around content. A string is split into its characters, where the first
+ * character is the opening and the second character is the closing bracket. A tuple specifies the opening and closing
+ * values explicitly, and nullish values are appended as nothing.
+ * @template TBuilder The builder type that the brackets are appended to.
+ */
 export type Paratheses<TBuilder extends StringBuilder> = KnownParatheses | Omit<string, KnownParatheses> | [open: Nullable<AppendValue<TBuilder>>, close: Nullable<AppendValue<TBuilder>>];
+/**
+ * A callback that appends a separator between two items of a `forEach` loop.
+ * @template TBuilder The builder type that the separator is appended to.
+ * @template TItem The type of the items.
+ * @param builder The builder to append the separator to.
+ * @param previousItem The item before the separator.
+ * @param nextItem The item after the separator.
+ * @param previousItemIndex The index of the item before the separator.
+ * @param nextItemIndex The index of the item after the separator.
+ */
 export type SeparatorBuidlerFn<TBuilder, TItem> = (builder: TBuilder, previousItem: TItem, nextItem: TItem, previousItemIndex: number, nextItemIndex: number) => void;
+/**
+ * A separator between two items of a `forEach` loop: either a string that is appended as is, or a callback that appends
+ * the separator.
+ * @template TBuilder The builder type that the separator is appended to.
+ * @template TItem The type of the items.
+ * @see SeparatorBuidlerFn
+ */
 export type Separator<TBuilder, TItem> = string | SeparatorBuidlerFn<TBuilder, TItem>;
 /**
  * Options for the `parenthesize` methods of the `SourceBuilder`.
@@ -69,6 +96,11 @@ type SwitchCase<TValue, TBuilder extends StringBuilder> = {
     case: TValue;
     value: AppendValue<TBuilder>;
 };
+/**
+ * Gets the string that represents one level of indentation.
+ * @param options The indentation to get the string for.
+ * @returns A tab character for tabs, or the number of spaces specified by `count`.
+ */
 export declare function getIndentString(options: IndentOptions): string;
 /**
  * Represents an in-memory source file.
@@ -84,6 +116,10 @@ export declare class SourceBuilder<TAdditionalAppends = never> extends StringBui
      * Gets the options used by this instance.
      */
     get options(): SourceBuilderOptions;
+    /**
+     * Gets a value indicating whether the current line is empty or consists only of whitespace characters.
+     * The `pretend...LineEmpty` methods affect this value.
+     */
     get isCurrentLineEmpty(): boolean;
     /**
      * Initializes a new instance of the SourceBuilder class.
@@ -181,7 +217,25 @@ export declare class SourceBuilder<TAdditionalAppends = never> extends StringBui
      * @returns A reference to this instance.
      */
     if(condition: Condition, builderFn: AppendParam<this, TAdditionalAppends>, elseBuilderFn?: AppendParam<this, TAdditionalAppends>): this;
+    /**
+     * Appends the content of the case that has the specified key, or the default content if there is no such case.
+     * The content of a case that is nullish is replaced by the default content.
+     * @param value The value to switch on. Only strings and numbers are used as keys.
+     * @param cases The content of each case, keyed by the case value.
+     * @param defaultBuilderFn The content to append if no case matches.
+     * @returns A reference to this instance.
+     */
     switch<T extends string | number>(value: T, cases: Record<T, AppendParam<this, TAdditionalAppends>>, defaultBuilderFn?: AppendParam<this, TAdditionalAppends>): this;
+    /**
+     * Appends the content of the first case whose value matches the switch value, or the default content if none matches.
+     * This overload works with any value type and supports a custom comparison.
+     * @template T The type of the switch value and the case values.
+     * @param value The value to switch on.
+     * @param cases The cases to compare the value with, in order.
+     * @param defaultBuilderFn The content to append if no case matches.
+     * @param equals The function that compares the switch value with a case value. Defaults to strict equality.
+     * @returns A reference to this instance.
+     */
     switch<T>(value: T, cases: SwitchCase<T, this>[], defaultBuilderFn?: AppendParam<this, TAdditionalAppends>, equals?: (a: T, b: T) => boolean): this;
     /**
      * Adds one indentation level. If the current line already contains characters, only subsequent lines are affected.
@@ -222,14 +276,63 @@ export declare class SourceBuilder<TAdditionalAppends = never> extends StringBui
      * @returns A reference to this instance.
      */
     forEach<T>(items: Iterable<T>, builderFn: (builder: this, item: T, index: number) => void, options?: ForEachOptions<this, T>): this;
+    /**
+     * Adds content for each item in the specified items if the specified condition is true.
+     * @template T The type of the items.
+     * @param condition The condition to check before adding content for the items.
+     * @param items The items to add content for.
+     * @param builderFn The function to add content for each item.
+     * @param options The options for the loop.
+     * @returns A reference to this instance.
+     */
     forEachIf<T>(condition: Condition, items: Iterable<T>, builderFn: (builder: this, item: T, index: number) => void, options?: ForEachOptions<this, T>): this;
+    /**
+     * Appends the items with the specified separator between them. The separator is also appended before an item that
+     * appends nothing, such as `null`, so that item leaves an empty slot.
+     * @param items The items to append.
+     * @param separator The string to append between two items.
+     * @returns A reference to this instance.
+     * @example
+     * ```ts
+     * new SourceBuilder().appendSeparated(['a', 'b', 'c'], ', '); // => 'a, b, c'
+     * ```
+     */
     appendSeparated(items: Iterable<AppendParam<this, TAdditionalAppends>>, separator: string): this;
+    /**
+     * Appends the items with the specified separator between them if the specified condition is true.
+     * @param condition The condition to check before appending the items.
+     * @param items The items to append.
+     * @param separator The string to append between two items.
+     * @returns A reference to this instance.
+     * @see SourceBuilder.appendSeparated
+     */
     appendSeparatedIf(condition: Condition, items: Iterable<AppendParam<this, TAdditionalAppends>>, separator: string): this;
     private appendIndent;
 }
 declare function _builderTemplate<T extends SourceBuilder>(template: readonly string[] | ArrayLike<string>, ...substitutions: AppendValue<T>[]): BuilderFn<T>;
 declare const _builderTemplateExtensions: {
+    /**
+     * Creates a builder function from a template, like `builderTemplate`, and indents its content by one level.
+     * @template T The type of the builder.
+     * @param template The strings of the template literal.
+     * @param substitutions The values that are substituted into the template.
+     * @returns A builder function that appends the indented content.
+     */
     readonly indent: <T extends SourceBuilder>(template: readonly string[] | ArrayLike<string>, ...substitutions: AppendValue<T>[]) => BuilderFn<T>;
 };
+/**
+ * Creates a builder function from a template literal, which can be passed to `append`. Each substitution is appended as
+ * an append value. The indentation of the last line of the template is removed from the lines of the template, so the
+ * template can be indented to match the surrounding code. Use `builderTemplate.indent` to also indent the content by
+ * one level.
+ * @example
+ * ```ts
+ * const sb = new SourceBuilder({ newLine: '\n' });
+ * sb.append(builderTemplate`
+ *     const ${name} = ${value};
+ *   `);
+ * // => "\n  const foo = 1;\n"
+ * ```
+ */
 export declare const builderTemplate: typeof _builderTemplate & typeof _builderTemplateExtensions;
 export {};

package/dist/src/utils/source-builder.js

@@ -10,6 +10,11 @@ export const defaultSourceBuilderOptions = {
     ...defaultStringBuilderOptions,
     indent: { type: 'spaces', count: 2 },
 };
+/**
+ * Gets the string that represents one level of indentation.
+ * @param options The indentation to get the string for.
+ * @returns A tab character for tabs, or the number of spaces specified by `count`.
+ */
 export function getIndentString(options) {
     return options.type === 'tabs' ? '\t' : ' '.repeat(options.count);
 }
@@ -29,6 +34,10 @@ export class SourceBuilder extends StringBuilder {
     get options() {
         return this.__options;
     }
+    /**
+     * Gets a value indicating whether the current line is empty or consists only of whitespace characters.
+     * The `pretend...LineEmpty` methods affect this value.
+     */
     get isCurrentLineEmpty() {
         return this._isCurrentLineEmpty;
     }
@@ -373,15 +382,43 @@ export class SourceBuilder extends StringBuilder {
         }
         return this;
     }
+    /**
+     * Adds content for each item in the specified items if the specified condition is true.
+     * @template T The type of the items.
+     * @param condition The condition to check before adding content for the items.
+     * @param items The items to add content for.
+     * @param builderFn The function to add content for each item.
+     * @param options The options for the loop.
+     * @returns A reference to this instance.
+     */
     forEachIf(condition, items, builderFn, options) {
         if (evalCondition(condition)) {
             return this.forEach(items, builderFn, options);
         }
         return this;
     }
+    /**
+     * Appends the items with the specified separator between them. The separator is also appended before an item that
+     * appends nothing, such as `null`, so that item leaves an empty slot.
+     * @param items The items to append.
+     * @param separator The string to append between two items.
+     * @returns A reference to this instance.
+     * @example
+     * ```ts
+     * new SourceBuilder().appendSeparated(['a', 'b', 'c'], ', '); // => 'a, b, c'
+     * ```
+     */
     appendSeparated(items, separator) {
         return this.forEach(items, (builder, item) => builder.append(item), { separator });
     }
+    /**
+     * Appends the items with the specified separator between them if the specified condition is true.
+     * @param condition The condition to check before appending the items.
+     * @param items The items to append.
+     * @param separator The string to append between two items.
+     * @returns A reference to this instance.
+     * @see SourceBuilder.appendSeparated
+     */
     appendSeparatedIf(condition, items, separator) {
         if (evalCondition(condition)) {
             return this.appendSeparated(items, separator);
@@ -411,8 +448,29 @@ function _builderTemplate(template, ...substitutions) {
     };
 }
 const _builderTemplateExtensions = {
+    /**
+     * Creates a builder function from a template, like `builderTemplate`, and indents its content by one level.
+     * @template T The type of the builder.
+     * @param template The strings of the template literal.
+     * @param substitutions The values that are substituted into the template.
+     * @returns A builder function that appends the indented content.
+     */
     indent: (template, ...substitutions) => {
         return (b) => b.indent(_builderTemplate(template, ...substitutions));
     },
 };
+/**
+ * Creates a builder function from a template literal, which can be passed to `append`. Each substitution is appended as
+ * an append value. The indentation of the last line of the template is removed from the lines of the template, so the
+ * template can be indented to match the surrounding code. Use `builderTemplate.indent` to also indent the content by
+ * one level.
+ * @example
+ * ```ts
+ * const sb = new SourceBuilder({ newLine: '\n' });
+ * sb.append(builderTemplate`
+ *     const ${name} = ${value};
+ *   `);
+ * // => "\n  const foo = 1;\n"
+ * ```
+ */
 export const builderTemplate = Object.assign(_builderTemplate, _builderTemplateExtensions);

package/dist/src/utils/string-builder/string-builder.d.ts

@@ -1,12 +1,29 @@
 import type { Nullable, SingleOrMultiple } from '../type.utils.ts';
 import { type StringBuilderOptions } from './options.ts';
+/**
+ * A callback that receives a builder and appends content to it.
+ * @template TBuilder The builder type that is passed to the callback.
+ */
 export type BuilderFn<TBuilder extends StringBuilder> = (builder: TBuilder) => void;
+/**
+ * A primitive value that can be appended to a `StringBuilder`. Numbers and booleans are converted with `toString`.
+ */
 export type Primitive = string | number | boolean;
+/**
+ * A value, or an array of values, that can be appended to a `StringBuilder`. Nullish values are ignored, arrays are
+ * flattened, and functions are invoked with the builder.
+ * @template TBuilder The builder type that the value is appended to.
+ * @template TAdditionalAppends Additional value types that the builder accepts.
+ */
 export type AppendParam<TBuilder extends StringBuilder, TAdditionalAppends> = SingleOrMultiple<Primitive | null | undefined | BuilderFn<TBuilder> | TAdditionalAppends | {
     __type: 'append-value-group';
     values: AppendParam<TBuilder, TAdditionalAppends>[];
     separator: string | null;
 }>;
+/**
+ * The key of the method that carries the additional append types of a `StringBuilder` subclass in the type system.
+ * The method is never called at runtime.
+ */
 export declare const AdditionalAppendsSymbol: unique symbol;
 /**
  * Represents a mutable string of characters.
@@ -14,7 +31,14 @@ export declare const AdditionalAppendsSymbol: unique symbol;
 export declare class StringBuilder<TAdditionalAppends = never> {
     private readonly _options;
     protected str: string;
+    /**
+     * Type-only marker for the additional append types. Calling it throws, because it must never be called at runtime.
+     * @param _ The additional append value. Not used.
+     */
     [AdditionalAppendsSymbol](_: TAdditionalAppends): void;
+    /**
+     * Gets the options used by this instance.
+     */
     get options(): StringBuilderOptions;
     /**
      * Initializes a new instance of the StringBuilder class.

package/dist/src/utils/string-builder/string-builder.js

@@ -1,5 +1,9 @@
 import { isNullish } from '../common.utils.js';
 import { defaultStringBuilderOptions } from './options.js';
+/**
+ * The key of the method that carries the additional append types of a `StringBuilder` subclass in the type system.
+ * The method is never called at runtime.
+ */
 export const AdditionalAppendsSymbol = Symbol('AdditionalAppends');
 /**
  * Represents a mutable string of characters.
@@ -7,9 +11,16 @@ export const AdditionalAppendsSymbol = Symbol('AdditionalAppends');
 export class StringBuilder {
     _options;
     str = '';
+    /**
+     * Type-only marker for the additional append types. Calling it throws, because it must never be called at runtime.
+     * @param _ The additional append value. Not used.
+     */
     [AdditionalAppendsSymbol](_) {
         throw new Error('This method should never be called.');
     }
+    /**
+     * Gets the options used by this instance.
+     */
     get options() {
         return this._options;
     }

package/dist/src/utils/string-builder/utils.d.ts

@@ -1,21 +1,89 @@
 import type { Nullable } from '../type.utils.ts';
 import type { AdditionalAppendsSymbol, AppendParam, BuilderFn, Primitive, StringBuilder } from './string-builder.ts';
+/**
+ * A value that can be appended to a `StringBuilder` without any additional append types: a primitive, a build function
+ * or an append value group.
+ * @template TBuilder The builder type that build functions receive.
+ */
 export type BasicAppendValue<TBuilder extends StringBuilder = StringBuilder> = Primitive | BuilderFn<TBuilder> | BasicAppendValueGroup<TBuilder>;
+/**
+ * A group of basic append values that are appended one after another, optionally with a separator in between.
+ * @template TBuilder The builder type that build functions receive.
+ */
 export type BasicAppendValueGroup<TBuilder extends StringBuilder = StringBuilder> = {
+    /**
+     * The type marker that identifies the object as an append value group.
+     */
     __type: 'append-value-group';
+    /**
+     * The values to append in order.
+     */
     values: BasicAppendValue<TBuilder>[];
+    /**
+     * The string to append between two values, or `null` for no separator.
+     */
     separator: string | null;
 };
+/**
+ * A value that can be appended to a `StringBuilder`, including the additional append types of the builder.
+ * @template TBuilder The builder type that determines the additional append types.
+ */
 export type AppendValue<TBuilder extends StringBuilder = StringBuilder> = NonNullable<AppendParam<TBuilder, Parameters<TBuilder[typeof AdditionalAppendsSymbol]>[0]>>;
+/**
+ * A group of append values that are appended one after another, optionally with a separator in between.
+ * @template TBuilder The builder type that determines the additional append types.
+ */
 export type AppendValueGroup<TBuilder extends StringBuilder = StringBuilder> = {
+    /**
+     * The type marker that identifies the object as an append value group.
+     */
     __type: 'append-value-group';
+    /**
+     * The values to append in order.
+     */
     values: AppendValue<TBuilder>[];
+    /**
+     * The string to append between two values, or `null` for no separator.
+     */
     separator: string | null;
 };
 /** @deprecated Use AppendValue<TBuilder> instead */
 export type TextOrBuilderFn<TBuilder> = string | ((builder: TBuilder) => void);
+/**
+ * Creates a group of basic append values. Nullish values are removed from the group.
+ * @template TBuilder The builder type that build functions receive.
+ * @param values The values to group. `null` and `undefined` yield an empty group.
+ * @param separator The string to append between two values. Defaults to no separator.
+ * @returns The append value group.
+ */
 export declare function basicAppendValueGroup<TBuilder extends StringBuilder = StringBuilder>(values: Nullable<Nullable<BasicAppendValue<TBuilder>>[]>, separator?: Nullable<string>): BasicAppendValueGroup<TBuilder>;
+/**
+ * Creates a group of append values. Nullish values are removed from the group.
+ * @template TBuilder The builder type that determines the additional append types.
+ * @param values The values to group. `null` and `undefined` yield an empty group.
+ * @param separator The string to append between two values. Defaults to no separator.
+ * @returns The append value group.
+ */
 export declare function appendValueGroup<TBuilder extends StringBuilder = StringBuilder>(values: Nullable<Nullable<AppendValue<TBuilder>>[]>, separator?: Nullable<string>): AppendValueGroup<TBuilder>;
+/**
+ * Checks whether a value is a basic append value: a string, number, boolean, function or append value group.
+ * Nullish values, arrays and other objects are not append values.
+ * @param value The value to check.
+ * @returns `true` if the value is an append value; otherwise, `false`.
+ */
 export declare function isAppendValue(value: unknown): value is AppendValue<never>;
+/**
+ * Checks whether a value is an append value group, that is an object with the `append-value-group` type marker.
+ * @template TBuilder The builder type of the group.
+ * @param value The value to check.
+ * @returns `true` if the value is an append value group; otherwise, `false`.
+ */
 export declare function isAppendValueGroup<TBuilder extends StringBuilder = StringBuilder>(value: unknown): value is AppendValueGroup<TBuilder>;
+/**
+ * Combines multiple append values into one. A single value is returned as is. Otherwise, the values are returned as an
+ * array in which array arguments are flattened by one level. Without any values, an empty array is returned.
+ * @template TBuilder The builder type that determines the additional append types.
+ * @param values The append values to combine.
+ * @returns The combined append value.
+ */
 export declare function concatAppendValues<TBuilder extends StringBuilder = StringBuilder>(...values: AppendValue<TBuilder>[]): AppendValue<TBuilder>;

package/dist/src/utils/string-builder/utils.js

@@ -1,4 +1,11 @@
 import { concatSingleOrMultiple, notNullish } from '../common.utils.js';
+/**
+ * Creates a group of basic append values. Nullish values are removed from the group.
+ * @template TBuilder The builder type that build functions receive.
+ * @param values The values to group. `null` and `undefined` yield an empty group.
+ * @param separator The string to append between two values. Defaults to no separator.
+ * @returns The append value group.
+ */
 export function basicAppendValueGroup(values, separator) {
     return {
         __type: 'append-value-group',
@@ -6,6 +13,13 @@ export function basicAppendValueGroup(values, separator) {
         separator: separator ?? null,
     };
 }
+/**
+ * Creates a group of append values. Nullish values are removed from the group.
+ * @template TBuilder The builder type that determines the additional append types.
+ * @param values The values to group. `null` and `undefined` yield an empty group.
+ * @param separator The string to append between two values. Defaults to no separator.
+ * @returns The append value group.
+ */
 export function appendValueGroup(values, separator) {
     return {
         __type: 'append-value-group',
@@ -13,6 +27,12 @@ export function appendValueGroup(values, separator) {
         separator: separator ?? null,
     };
 }
+/**
+ * Checks whether a value is a basic append value: a string, number, boolean, function or append value group.
+ * Nullish values, arrays and other objects are not append values.
+ * @param value The value to check.
+ * @returns `true` if the value is an append value; otherwise, `false`.
+ */
 export function isAppendValue(value) {
     return (typeof value === 'string' ||
         typeof value === 'number' ||
@@ -20,9 +40,22 @@ export function isAppendValue(value) {
         typeof value === 'function' ||
         isAppendValueGroup(value));
 }
+/**
+ * Checks whether a value is an append value group, that is an object with the `append-value-group` type marker.
+ * @template TBuilder The builder type of the group.
+ * @param value The value to check.
+ * @returns `true` if the value is an append value group; otherwise, `false`.
+ */
 export function isAppendValueGroup(value) {
     return typeof value === 'object' && value !== null && '__type' in value && value.__type === 'append-value-group';
 }
+/**
+ * Combines multiple append values into one. A single value is returned as is. Otherwise, the values are returned as an
+ * array in which array arguments are flattened by one level. Without any values, an empty array is returned.
+ * @template TBuilder The builder type that determines the additional append types.
+ * @param values The append values to combine.
+ * @returns The combined append value.
+ */
 export function concatAppendValues(...values) {
     return concatSingleOrMultiple(...values);
 }

package/dist/src/utils/string.utils.d.ts

@@ -1,10 +1,46 @@
 import type { CamelCaseOptions, CustomCaseOptions, KebabCaseOptions, PascalCaseOptions, SnakeCaseOptions, StringCasing, StringCasingWithOptions, WordCasing } from './string.utils.types.ts';
 import type { Nullable } from './type.utils.ts';
+/**
+ * Applies overrides to a casing. If both arguments are plain casings, `b` is returned. Otherwise the result is an
+ * object that combines the options of both arguments, where the properties of `b` take precedence.
+ * @param a The base casing, either a plain casing or a casing with options.
+ * @param b The casing or the options that override `a`.
+ * @returns The adjusted casing.
+ * @example
+ * ```ts
+ * adjustCasing('camel', 'pascal'); // => 'pascal'
+ * adjustCasing('camel', { prefix: '_' }); // => { casing: 'camel', prefix: '_' }
+ * adjustCasing({ casing: 'camel', prefix: '_' }, 'pascal'); // => { casing: 'pascal', prefix: '_' }
+ * adjustCasing({ casing: 'camel', prefix: '_' }, { suffix: '_' }); // => { casing: 'camel', prefix: '_', suffix: '_' }
+ * ```
+ */
 export declare function adjustCasing(a: StringCasing, b: StringCasing): StringCasing;
 export declare function adjustCasing(a: StringCasing | StringCasingWithOptions, b: StringCasing | Partial<StringCasingWithOptions>): StringCasingWithOptions;
+/**
+ * Converts all characters of a string to lower case.
+ * @param str The string to convert.
+ * @returns The lower case string.
+ */
 export declare function lowercase<T extends string>(str: T): Lowercase<T>;
+/**
+ * Converts all characters of a string to upper case.
+ * @param str The string to convert.
+ * @returns The upper case string.
+ */
 export declare function uppercase<T extends string>(str: T): Uppercase<T>;
+/**
+ * Converts the first character of a string to upper case and leaves the remaining characters unchanged.
+ * An empty string is returned as is.
+ * @param str The string to capitalize.
+ * @returns The capitalized string.
+ */
 export declare function capitalize<T extends string>(str: T): Capitalize<T>;
+/**
+ * Converts the first character of a string to lower case and leaves the remaining characters unchanged.
+ * An empty string is returned as is.
+ * @param str The string to uncapitalize.
+ * @returns The uncapitalized string.
+ */
 export declare function uncapitalize<T extends string>(str: T): Uncapitalize<T>;
 /**
  * Gets the words from a string. Words are separated by capital letters. Leading numbers are removed. Non-alphanumerical characters are removed and interpreted as word seperators. Multiple uppercase letters are interpreted as one word.
@@ -35,6 +71,21 @@ export declare function getWords(str: Nullable<string>): string[];
  * toCasing('FooBar', 'first-lower-alternating') // => 'fOoBaR'
  */
 export declare function wordToCasing(str: Nullable<string>, casing: WordCasing): string;
+/**
+ * Converts a string to the specified casing. The `camel`, `pascal`, `kebab`, `snake` and `custom` casings are
+ * delegated to their dedicated functions. All other casings are applied to the words of the string joined together,
+ * so non-alphanumerical characters are removed.
+ * @param str The string to convert. `null` and `undefined` are treated as an empty string. The `first-*` word casings
+ * throw a `TypeError` for an empty string.
+ * @param casing The casing to convert to, optionally with options for that casing.
+ * @returns The converted string.
+ * @example
+ * ```ts
+ * toCasing('foo bar', 'pascal'); // => 'FooBar'
+ * toCasing('foo bar', 'first-upper'); // => 'Foobar'
+ * toCasing('foo_bar', { casing: 'kebab', wordCasing: 'all-upper' }); // => 'FOO-BAR'
+ * ```
+ */
 export declare function toCasing<T extends StringCasing>(str: Nullable<string>, casing: T | StringCasingWithOptions<T>): string;
 /**
  * Converts a string to camel case.
@@ -142,7 +193,34 @@ export declare function spliceString(str: string, start: number, deleteCount: nu
  * @param str The string to trim.
  */
 export declare function trimIndent(str: string): string;
+/**
+ * Removes trailing whitespace from a string.
+ * @param str The string to trim.
+ * @param includeNewLine Whether to also remove trailing line breaks. Defaults to `true`. If `false`, only whitespace
+ * characters other than line breaks are removed.
+ * @returns The trimmed string.
+ */
 export declare function trimEnd(str: string, includeNewLine?: boolean): string;
+/**
+ * Removes leading whitespace from a string.
+ * @param str The string to trim.
+ * @param includeNewLine Whether to also remove leading line breaks. Defaults to `true`. If `false`, only whitespace
+ * characters other than line breaks are removed.
+ * @returns The trimmed string.
+ */
 export declare function trimStart(str: string, includeNewLine?: boolean): string;
+/**
+ * Removes leading and trailing whitespace from a string.
+ * @param str The string to trim.
+ * @param includeNewLine Whether to also remove leading and trailing line breaks. Defaults to `true`. If `false`, only
+ * whitespace characters other than line breaks are removed.
+ * @returns The trimmed string.
+ */
 export declare function trim(str: string, includeNewLine?: boolean): string;
+/**
+ * Removes all occurrences of a substring from a string. The substring is matched literally, not as a regex.
+ * @param str The string to remove the substring from.
+ * @param rem The substring to remove. Must not be empty, because the search would never advance.
+ * @returns The string without the occurrences of `rem`, or `str` itself if `rem` does not occur in it.
+ */
 export declare function removeStr(str: string, rem: string): string;