@goast/core 0.7.0 → 0.7.1

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

@@ -15,15 +15,37 @@ export function adjustCasing(a, b) {
         return { ...a, ...b };
     }
 }
+/**
+ * Converts all characters of a string to lower case.
+ * @param str The string to convert.
+ * @returns The lower case string.
+ */
 export function lowercase(str) {
     return str.toLowerCase();
 }
+/**
+ * Converts all characters of a string to upper case.
+ * @param str The string to convert.
+ * @returns The upper case string.
+ */
 export function uppercase(str) {
     return str.toUpperCase();
 }
+/**
+ * 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 function capitalize(str) {
     return (str.charAt(0).toUpperCase() + str.slice(1));
 }
+/**
+ * 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 function uncapitalize(str) {
     return (str.charAt(0).toLowerCase() + str.slice(1));
 }
@@ -92,6 +114,21 @@ export function wordToCasing(str, casing) {
                 .join('');
     }
 }
+/**
+ * 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 function toCasing(str, casing) {
     let options;
     let casingType;
@@ -311,6 +348,13 @@ function isNonLineBreakWhitespaceChar(char) {
         char === '\u3000' ||
         char === '\ufeff');
 }
+/**
+ * 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 function trimEnd(str, includeNewLine = true) {
     if (includeNewLine)
         return str.trimEnd();
@@ -319,6 +363,13 @@ export function trimEnd(str, includeNewLine = true) {
         ;
     return str.substring(0, i);
 }
+/**
+ * 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 function trimStart(str, includeNewLine = true) {
     if (includeNewLine)
         return str.trimStart();
@@ -327,6 +378,13 @@ export function trimStart(str, includeNewLine = true) {
         ;
     return str.substring(i);
 }
+/**
+ * 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 function trim(str, includeNewLine = true) {
     if (includeNewLine)
         return str.trim();
@@ -338,6 +396,12 @@ export function trim(str, includeNewLine = true) {
         ;
     return str.substring(s, e);
 }
+/**
+ * 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 function removeStr(str, rem) {
     let i = str.indexOf(rem);
     if (i === -1)

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

@@ -30,11 +30,30 @@ export type WordCasing = 'unchanged' | 'all-lower' | 'all-upper' | 'first-upper'
  * toCase('fooBar', 'snake') // => 'foo_bar'
  */
 export type StringCasing = WordCasing | 'camel' | 'pascal' | 'kebab' | 'snake' | 'custom';
+/**
+ * Represents a casing together with the options that apply to it.
+ * @template T The casing that determines which options are available.
+ */
 export type StringCasingWithOptions<T extends StringCasing = StringCasing> = {
+    /**
+     * The casing to apply.
+     */
     casing: T;
 } & CaseOptions<T>;
+/**
+ * Represents either a plain casing or a casing with options.
+ * @see StringCasing
+ * @see StringCasingWithOptions
+ */
 export type ExtendedStringCasing = StringCasing | StringCasingWithOptions;
+/**
+ * Resolves the options that a casing accepts. Casings without options resolve to `never`.
+ * @template T The casing to resolve the options for.
+ */
 export type CaseOptions<T extends StringCasing> = T extends 'camel' ? Partial<CamelCaseOptions> : T extends 'pascal' ? Partial<PascalCaseOptions> : T extends 'kebab' ? Partial<KebabCaseOptions> : T extends 'snake' ? Partial<SnakeCaseOptions> : T extends 'custom' ? CustomCaseOptions : never;
+/**
+ * Options that are shared by all casings and add text around the converted string.
+ */
 export type BaseCaseOptions = {
     /**
      * Specifies a prefix to add to the string.
@@ -51,6 +70,9 @@ export type BaseCaseOptions = {
      */
     suffix?: string;
 };
+/**
+ * Options for the camel casing.
+ */
 export type CamelCaseOptions = BaseCaseOptions & {
     /**
      * Controls the casing of all characters except the first one for each word.
@@ -65,6 +87,9 @@ export type CamelCaseOptions = BaseCaseOptions & {
      */
     keepOriginalCase: boolean;
 };
+/**
+ * Options for the pascal casing.
+ */
 export type PascalCaseOptions = BaseCaseOptions & {
     /**
      * Controls the casing of all characters except the first one for each word.
@@ -79,6 +104,9 @@ export type PascalCaseOptions = BaseCaseOptions & {
      */
     keepOriginalCase: boolean;
 };
+/**
+ * Options for the kebab casing, which joins the words with hyphens.
+ */
 export type KebabCaseOptions = BaseCaseOptions & {
     /**
      * Specifies the casing of words.
@@ -98,6 +126,9 @@ export type KebabCaseOptions = BaseCaseOptions & {
      */
     firstWordCasing?: WordCasing;
 };
+/**
+ * Options for the snake casing, which joins the words with underscores.
+ */
 export type SnakeCaseOptions = BaseCaseOptions & {
     /**
      * Specifies the casing of words.
@@ -117,6 +148,9 @@ export type SnakeCaseOptions = BaseCaseOptions & {
      */
     firstWordCasing?: WordCasing;
 };
+/**
+ * Options for the custom casing, which applies the word casing and joins the words with an optional separator.
+ */
 export type CustomCaseOptions = BaseCaseOptions & {
     /**
      * Specifies the separator between words.

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

@@ -1,27 +1,138 @@
+/**
+ * Intersects all types of a tuple, e.g. `Merge<[A, B]>` resolves to `A & B`.
+ * @template U The tuple of types to intersect.
+ * @example
+ * ```ts
+ * type AB = Merge<[{ a: string }, { b: number }]>; // { a: string } & { b: number }
+ * ```
+ */
 export type Merge<U extends unknown[]> = U extends [infer A, ...infer R] ? A & Merge<R> : {};
+/**
+ * Makes the properties `K` of `T` optional, leaving all other properties unchanged.
+ * @template T The object type.
+ * @template K The keys of `T` to make optional.
+ */
 export type OptionalProperties<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/**
+ * Makes the properties `K` of `T` required, leaving all other properties unchanged.
+ * @template T The object type.
+ * @template K The keys of `T` to make required.
+ */
 export type RequiredProperties<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+/**
+ * Gets the item type of an array type, or `never` if `T` is not an array.
+ * @template T The type to inspect.
+ */
 export type ArrayItem<T> = T extends (infer U)[] ? U : never;
+/**
+ * A value of type `T` or an array of `T`.
+ * @template T The item type.
+ */
 export type SingleOrMultiple<T> = T | T[];
+/**
+ * Gets the single item type of `T`: the item type if `T` is an array, otherwise `T` itself. Distributes over unions.
+ * @template T The type to unwrap.
+ * @see SingleOrMultiple
+ */
 export type Single<T> = T extends (infer U)[] ? U : T;
+/**
+ * Gets the array type of `T`: `T[]` if `T` is not an array, otherwise an array with the same item type.
+ * Distributes over unions.
+ * @template T The type to convert to an array.
+ * @see SingleOrMultiple
+ */
 export type Multiple<T> = T extends (infer U)[] ? U[] : T[];
+/**
+ * A value of type `T` that may also be `null` or `undefined`.
+ * @template T The non-nullable type.
+ */
 export type Nullable<T> = T | null | undefined;
+/**
+ * Describes a class constructor that creates an instance of `T` from arguments of types `TArgs`.
+ * @template T The type of the created instance.
+ * @template TArgs The types of the constructor parameters.
+ */
 export interface Constructor<T, TArgs extends any[] = any[]> extends Function {
     new (...args: TArgs): T;
 }
+/**
+ * Describes a class constructor that takes no arguments and creates an instance of `T`.
+ * @template T The type of the created instance.
+ */
 export type EmptyConstructor<T> = Constructor<T, []>;
+/**
+ * Gets the union of the keys of `T` whose values are functions.
+ * @template T The object type to inspect.
+ */
 export type FunctionNames<T> = {
     [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never;
 }[keyof T];
+/**
+ * Flattens an intersection type (e.g. `Omit<A, K> & B`) into a single object type, so that editor tooltips show
+ * the resulting properties directly.
+ * @template T The type to flatten.
+ */
 export type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
+/**
+ * Gets the union of all property value types of `T`.
+ * @template T The object type.
+ */
 export type ValueOf<T> = T[keyof T];
+/**
+ * An array type with at least one element.
+ * @template T The element type.
+ */
 export type NonEmptyArray<T> = [T, ...T[]];
+/**
+ * Resolves to `U` only if `U` contains every member of `T`, otherwise to `never`. Used by `stringUnionToArray`.
+ * @template T The union type whose members must all be included.
+ * @template U The tuple of listed members.
+ */
 type MustInclude<T, U extends T[]> = [T] extends [ValueOf<U>] ? U : never;
+/**
+ * Creates a function that returns the members of the string union type `T` as an array. The compiler checks that
+ * every member of `T` is listed.
+ * @template T The string union type whose members must all be listed.
+ * @returns A function that takes the members as arguments and returns them as an array.
+ * @example
+ * ```ts
+ * type Color = 'red' | 'green' | 'blue';
+ * const colors = stringUnionToArray<Color>()('red', 'green', 'blue'); // ['red', 'green', 'blue']
+ * // stringUnionToArray<Color>()('red', 'green'); // Compile error: a member is missing.
+ * ```
+ */
 export declare function stringUnionToArray<T>(): <U extends NonEmptyArray<T>>(...elements: MustInclude<T, U>) => MustInclude<T, U>;
+/**
+ * Either one of the suggested string values `T`, or any other string. Editors offer `T` as completions while
+ * arbitrary strings remain allowed.
+ * @template T The suggested string values.
+ * @example
+ * ```ts
+ * type Access = StringSuggestions<'public' | 'private'>;
+ * const access: Access = 'protected'; // allowed, while 'public' and 'private' are suggested
+ * ```
+ */
 export type StringSuggestions<T extends string> = T | Omit<string, T>;
+/**
+ * Returns `value` unchanged at runtime. At the type level, a `StringSuggestions` type is widened to `string`, so the
+ * suggested literals no longer narrow it. Other types are returned as they are.
+ * @template T The type of the value.
+ * @param value The value to return.
+ * @returns The same value, typed as `string` where `T` is a string suggestion.
+ */
 export declare function suggestionsAsString<T>(value: T): T extends StringSuggestions<infer U> ? Exclude<T, StringSuggestions<U>> | string : T;
+/**
+ * Gets the union of the parameter tuples of all overloads of the function type `T`. Considers up to six overloads.
+ * @template T The function type to inspect.
+ * @example
+ * ```ts
+ * declare function parse(input: string): number;
+ * declare function parse(input: string, radix: number): number;
+ * type ParseArgs = ParametersWithOverloads<typeof parse>; // [input: string] | [input: string, radix: number]
+ * ```
+ */
 export type ParametersWithOverloads<T extends (...args: any[]) => any> = T extends {
     (...args: infer A1): any;
     (...args: infer A2): any;
@@ -50,7 +161,28 @@ export type ParametersWithOverloads<T extends (...args: any[]) => any> = T exten
 } ? A1 | A2 : T extends {
     (...args: infer A1): any;
 } ? A1 : never;
+/**
+ * Helper for `TupleWithCount`: prepends `T` to `R` until `R` has `N` elements.
+ * @template T The element type.
+ * @template N The target length of the tuple.
+ * @template R The tuple built so far.
+ */
 type _TupleOf<T, N extends number, R extends unknown[]> = R['length'] extends N ? R : _TupleOf<T, N, [T, ...R]>;
+/**
+ * Creates a tuple type of `T` with a fixed length. A non-literal `number` or `number[]` gives `T[]`, a literal number
+ * gives a tuple of that length, and a union of numbers or a number array gives a union of tuples.
+ * @template T The element type.
+ * @template N The tuple length, or the array of allowed lengths.
+ * @example
+ * ```ts
+ * type Pair = TupleWithCount<string, 2>; // [string, string]
+ * type Odd = TupleWithCount<string, [1, 3]>; // [string] | [string, string, string]
+ * ```
+ */
 export type TupleWithCount<T, N extends number | number[]> = N extends number ? number extends N ? T[] : _TupleOf<T, N, []> : N extends [infer A, ...infer R] ? A extends number ? R extends number[] ? TupleWithCount<T, A> | TupleWithCount<T, R> : never : never : N extends [] ? never : T[];
+/**
+ * A value of type `T` or a `Promise` of it, for functions that may complete synchronously or asynchronously.
+ * @template T The resolved value type.
+ */
 export type MaybePromise<T> = T | Promise<T>;
 export {};

package/dist/src/utils/type.utils.js

@@ -1,6 +1,25 @@
+/**
+ * Creates a function that returns the members of the string union type `T` as an array. The compiler checks that
+ * every member of `T` is listed.
+ * @template T The string union type whose members must all be listed.
+ * @returns A function that takes the members as arguments and returns them as an array.
+ * @example
+ * ```ts
+ * type Color = 'red' | 'green' | 'blue';
+ * const colors = stringUnionToArray<Color>()('red', 'green', 'blue'); // ['red', 'green', 'blue']
+ * // stringUnionToArray<Color>()('red', 'green'); // Compile error: a member is missing.
+ * ```
+ */
 export function stringUnionToArray() {
     return (...elements) => elements;
 }
+/**
+ * Returns `value` unchanged at runtime. At the type level, a `StringSuggestions` type is widened to `string`, so the
+ * suggested literals no longer narrow it. Other types are returned as they are.
+ * @template T The type of the value.
+ * @param value The value to return.
+ * @returns The same value, typed as `string` where `T` is a string suggestion.
+ */
 export function suggestionsAsString(value) {
     return value;
 }

package/dist/src/utils/yaml-info.d.ts

@@ -1,12 +1,47 @@
 import * as YAML from 'yaml';
+/**
+ * Symbol under which `parseYamlWithInfo` stores the `YamlInfo` of the parsed value.
+ * @see parseYamlWithInfo
+ */
 export declare const yamlInfoSymbol: unique symbol;
+/**
+ * The parsed YAML document and line counter that `parseYamlWithInfo` attaches to a parsed value.
+ * @see parseYamlWithInfo
+ */
 export type YamlInfo = {
+    /**
+     * The parsed YAML document, used to look up nodes by their path.
+     */
     document: YAML.Document.Parsed;
+    /**
+     * The line counter, used to convert the character offset of a node into a line and column.
+     */
     lineCounter: YAML.LineCounter;
 };
+/**
+ * Gets the YAML information that `parseYamlWithInfo` attached to the specified object. Throws an error if the object
+ * has no such information.
+ * @param obj The object to get the YAML information from.
+ * @returns The YAML information of the object.
+ */
 export declare function getYamlInfo(obj: unknown): YamlInfo;
+/**
+ * Gets the line and column of the node at the specified path within the YAML document that the object was parsed from.
+ * Logs a warning and returns `{ line: 0, col: 0 }` if the node cannot be found or has no source range. Throws if the
+ * object has no YAML information.
+ * @param obj The object that was returned by `parseYamlWithInfo`.
+ * @param path The path of the node, as keys and array indices. Numeric strings are also matched against array indices.
+ * @returns The line and column of the node.
+ */
 export declare function getLineInfo(obj: unknown, path: unknown[]): {
     line: number;
     col: number;
 };
+/**
+ * Parses a YAML or JSON string into a value and attaches its YAML information under `yamlInfoSymbol`. The attached
+ * property is non-enumerable, so it does not appear in keys or serialized output. Throws if the document is a scalar
+ * value such as a string or `null`, because only objects can carry the information.
+ * @param yamlString The YAML or JSON string to parse.
+ * @returns The parsed value, with the YAML information attached.
+ */
 export declare function parseYamlWithInfo(yamlString: string): unknown;

package/dist/src/utils/yaml-info.js

@@ -1,5 +1,15 @@
 import * as YAML from 'yaml';
+/**
+ * Symbol under which `parseYamlWithInfo` stores the `YamlInfo` of the parsed value.
+ * @see parseYamlWithInfo
+ */
 export const yamlInfoSymbol = Symbol('yamlInfo');
+/**
+ * Gets the YAML information that `parseYamlWithInfo` attached to the specified object. Throws an error if the object
+ * has no such information.
+ * @param obj The object to get the YAML information from.
+ * @returns The YAML information of the object.
+ */
 export function getYamlInfo(obj) {
     const yamlInfo = obj[yamlInfoSymbol];
     if (!yamlInfo) {
@@ -7,6 +17,14 @@ export function getYamlInfo(obj) {
     }
     return yamlInfo;
 }
+/**
+ * Gets the line and column of the node at the specified path within the YAML document that the object was parsed from.
+ * Logs a warning and returns `{ line: 0, col: 0 }` if the node cannot be found or has no source range. Throws if the
+ * object has no YAML information.
+ * @param obj The object that was returned by `parseYamlWithInfo`.
+ * @param path The path of the node, as keys and array indices. Numeric strings are also matched against array indices.
+ * @returns The line and column of the node.
+ */
 export function getLineInfo(obj, path) {
     const yamlInfo = getYamlInfo(obj);
     const node = yamlInfo.document.getIn(path, true) ??
@@ -24,6 +42,13 @@ export function getLineInfo(obj, path) {
     }
     return yamlInfo.lineCounter.linePos(node.range[0]);
 }
+/**
+ * Parses a YAML or JSON string into a value and attaches its YAML information under `yamlInfoSymbol`. The attached
+ * property is non-enumerable, so it does not appear in keys or serialized output. Throws if the document is a scalar
+ * value such as a string or `null`, because only objects can carry the information.
+ * @param yamlString The YAML or JSON string to parse.
+ * @returns The parsed value, with the YAML information attached.
+ */
 export function parseYamlWithInfo(yamlString) {
     const lineCounter = new YAML.LineCounter();
     const document = YAML.parseDocument(yamlString, { lineCounter });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goast/core",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "A tool designed to transform OpenAPI specifications into various forms with flexibility and extensibility at its core.",
   "bugs": {
     "url": "https://github.com/MaSch0212/goast/issues"