@isdk/util 0.1.1 → 0.1.3

package/dist/index.d.mts

@@ -1,11 +1,344 @@
-export { ConfigFile } from './config-file.mjs';
-export { glob } from './glob.mjs';
-export { isStringIn } from './is-string-in.mjs';
-export { DefaultAllTextFiles, IncludeFiles, normalizeIncludeFiles } from './include-files.mjs';
-export { parseFrontMatter } from './front-matter.mjs';
-export { getMultiLevelExtname } from './get-multi-level-extname.mjs';
-export { removeLeadingEmptyLines } from './remove-leading-empty-lines.mjs';
-export { TraverseFolderHandler, TraverseFolderSyncHandler, traverseFolder, traverseFolderSync } from './traverse-folder.mjs';
-export { parseYaml, registerYamlTag, stringifyYaml } from './yaml.mjs';
-import 'fs';
-import 'yaml';
+import { Dirent } from 'fs';
+import { ParseOptions, DocumentOptions, SchemaOptions, ToJSOptions, CreateNodeOptions, ToStringOptions } from 'yaml';
+
+type StringifyFunc = (content: any) => string;
+interface LoadConfigFileOptions {
+    extLevel?: number;
+    externalFile?: string;
+}
+/**
+ * Represents a configuration file utility class that provides methods to load and save configuration files.
+ * It supports multiple file formats such as YAML, JSON, etc., by registering corresponding parsers and stringifiers.
+ *
+ * @example
+ * ```typescript
+ * // Register a custom file type handler
+ * ConfigFile.register('.custom', (content) => {
+ *   return { data: content.toUpperCase() }; // Example parser
+ * }, (obj) => {
+ *   return obj.data.toLowerCase(); // Example stringifier
+ * });
+ *
+ * // Save a configuration file
+ * ConfigFile.save('config.custom', { key: 'value' });
+ *
+ * // Load a configuration file
+ * const config = ConfigFile.load('config.custom');
+ * console.log(config); // Output: { key: 'value' }
+ * ```
+ */
+declare class ConfigFile {
+    /**
+     * A record of registered stringify functions for different file extensions.
+     */
+    static stringifys: Record<string, StringifyFunc>;
+    /**
+     * Registers a parser and stringifier for specific file extensions.
+     *
+     * @param extname - The file extension(s) to register the parser and stringifier for.
+     * @param parser - A function that parses the file content into an object.
+     * @param stringify - A function that converts an object back into file content.
+     *
+     * @example
+     * ```typescript
+     * ConfigFile.register(['.json'], JSON.parse, (obj) => JSON.stringify(obj, null, 2));
+     * ```
+     */
+    static register(extname: string | string[], parser: (content: string) => any, stringify: StringifyFunc): void;
+    /**
+     * Loads a configuration file based on the provided filename and options.
+     *
+     * @param filename - The path to the configuration file.
+     * @param options - Additional options for loading the configuration file.
+     * @returns The parsed configuration object.
+     *
+     * @example
+     * ```typescript
+     * const config = ConfigFile.load('config.yaml');
+     * console.log(config); // Output: { key: 'value' }
+     * ```
+     */
+    static load(filename: string, options?: LoadConfigFileOptions): any;
+    /**
+     * Saves a configuration object to a file with the specified filename and options.
+     *
+     * @param filename - The path where the configuration file should be saved.
+     * @param config - The configuration object to save.
+     * @param options - Additional options for saving the configuration file.
+     * @returns The final filename where the configuration was saved.
+     *
+     * @example
+     * ```typescript
+     * ConfigFile.save('config.json', { key: 'value' });
+     * ```
+     */
+    static save(filename: string, config: any, options?: LoadConfigFileOptions): string;
+}
+
+/**
+ * Matches a file path against a list of glob patterns.
+ *
+ * This function checks if the given `filepath` matches any of the provided glob `pattern`s.
+ * If a `rootDir` is specified, the `filepath` will first be converted to a relative path
+ * based on the `rootDir`.
+ *
+ * @param filepath - The file path to match.
+ * @param pattern - An array of glob patterns to match against.
+ * @param rootDir - (Optional) The root directory used to calculate the relative path of `filepath`.
+ *
+ * @returns Returns `true` if the `filepath` matches any of the patterns, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * import { glob } from './glob';
+ *
+ * const filepath = '/home/user/project/src/index.ts';
+ * const patterns = ['src/*.ts', '!src/test.ts'];
+ * const rootDir = '/home/user/project';
+ *
+ * const result = glob(filepath, patterns, rootDir);
+ * console.log(result); // true
+ * ```
+ */
+declare function glob(filepath: string, pattern: string[], rootDir?: string): boolean | undefined;
+
+/**
+ * Checks if a given string exists within an array of strings or a single string.
+ *
+ * @param str - The string to search for.
+ * @param arr - An array of strings or a single string to search within.
+ * @returns Returns `true` if the string is found, otherwise `false`.
+ *
+ * @example
+* ```typescript
+* const result = isStringIn("apple", ["banana", "apple", "cherry"]);
+* console.log(result); // true
+*
+* const singleResult = isStringIn("hello", "hello");
+* console.log(singleResult); // true
+* ```
+*/
+declare function isStringIn(str: string, arr: string[] | string): boolean;
+
+declare const DefaultAllTextFiles: string[];
+interface IncludeFiles {
+    include?: string[];
+    exclude?: string[];
+}
+/**
+ * Normalizes a list of file patterns for glob matching.
+ *
+ * This function takes either an array of file patterns or an object containing `include` and `exclude` arrays,
+ * and returns a normalized array of file patterns. If no patterns are provided, it defaults to including
+ * all text-based files as defined in `DefaultAllTextFiles`.
+ *
+ * @param files - Either an array of file patterns or an object with `include` and `exclude` properties.
+ * @param defaultFiles - An optional array of default file patterns to use if no include patterns are specified.
+ *                       Defaults to `DefaultAllTextFiles`.
+ * @returns A normalized array of file patterns, with excluded patterns prefixed by `!`.
+ *
+ * @example
+ *
+ * ```typescript
+ * const result = normalizeIncludeFiles({
+ *   include: ['*.ts', '*.js'],
+ *   exclude: ['node_modules/**']
+ * });
+ * console.log(result);
+ * // Output: ['*.ts', '*.js', '!node_modules/**']
+ * ```
+ */
+declare function normalizeIncludeFiles(files?: string[] | IncludeFiles, defaultFiles?: string[]): string[];
+
+declare function parseFrontMatter(value: string, delimiter?: string): {
+    data: any;
+    content: string;
+};
+
+/**
+ * Retrieves multi-level file extension
+ * @param filename The file name
+ * @param level The level, default is 1, indicating the number of extension levels to retrieve
+ * @returns Returns a concatenated string of multiple extensions, or an empty string if no extension is found
+ */
+declare function getMultiLevelExtname(filename: string, level?: number): string;
+
+/**
+ * Removes all leading empty lines or "#" comments line from the given string.
+ *
+ * This function trims any sequence of empty lines that appear at the beginning
+ * of the input string. It accounts for different newline characters including
+ * '\n', '\r\n', and also considers lines that contain only whitespace characters.
+ *
+ * @param text - The string from which to remove leading empty lines.
+ * @returns The string with leading empty lines removed.
+ *
+ * @example
+ * const sampleText = '# This is a comment\n\nHello, world!\n';
+ * const cleanedText = removeLeadingEmptyLines(sampleText);
+ * // cleanedText is now 'Hello, world!\n'
+ */
+declare function removeLeadingEmptyLines(text: string): string;
+
+/**
+ * A handler function for asynchronous folder traversal.
+ * @param filePath - The full path of the file or directory.
+ * @param entry - The directory entry (file or folder).
+ * @returns Returns `true` to stop further traversal, or `false`/`void` to continue.
+ */
+type TraverseFolderHandler = (filePath: string, entry: Dirent) => boolean | void | Promise<boolean | void>;
+/**
+ * A handler function for synchronous folder traversal.
+ * @param filePath - The full path of the file or directory.
+ * @param entry - The directory entry (file or folder).
+ * @returns Returns `true` to stop further traversal, or `false` to continue.
+ */
+type TraverseFolderSyncHandler = (filePath: string, entry: Dirent) => boolean | void;
+/**
+ * Traverses a folder asynchronously and applies a handler to each file or directory.
+ *
+ * @param directoryPath - The root directory to start traversal.
+ * @param fileHandler - A handler function called for each file/directory.
+ *
+ * @example
+ * ```typescript
+ * await traverseFolder('/path/to/folder', async (filePath, entry) => {
+ *   console.log(`Found: ${filePath}`);
+ *   if (entry.name === 'stopfile.txt') {
+ *     console.log('Stopping traversal...');
+ *     return true; // Stops further traversal
+ *   }
+ *   return false; // Continues traversal
+ * });
+ * ```
+ */
+declare function traverseFolder(directoryPath: string, fileHandler: TraverseFolderHandler): Promise<void>;
+/**
+ * Traverses a folder synchronously and applies a handler to each file or directory.
+ *
+ * @param directoryPath - The root directory to start traversal.
+ * @param fileHandler - A handler function called for each file/directory.
+ *
+ * @example
+ * ```typescript
+ * traverseFolderSync('/path/to/folder', (filePath, entry) => {
+ *   console.log(`Found: ${filePath}`);
+ *   if (entry.name === 'stopfile.txt') {
+ *     console.log('Stopping traversal...');
+ *     return true; // Stops further traversal
+ *   }
+ *   return false; // Continues traversal
+ * });
+ * ```
+ */
+declare function traverseFolderSync(directoryPath: string, fileHandler: TraverseFolderSyncHandler): void;
+
+/**
+ * Registers custom YAML tags to be used in parsing and stringifying YAML content.
+ *
+ * @param tags - A single tag or an array of tags to register.
+ *
+ * @example
+ * ```typescript
+ * import { registerYamlTag } from './yaml';
+ *
+ * const customTag = {
+ *   tag: '!custom',
+ *   resolve: (value) => `resolved-${value}`,
+ * };
+ * registerYamlTag(customTag);
+ * ```
+ */
+declare function registerYamlTag(tags: any): void;
+/**
+ * Parses a YAML string into a JavaScript object with optional custom tags.
+ *
+ * @param content - The YAML string to parse.
+ * @param options - Optional parsing options, including custom tags.
+ * @returns The parsed JavaScript object.
+ *
+ * @example
+ * ```typescript
+ * import { parseYaml } from './yaml';
+ *
+ * const yamlContent = `
+ *   example: !custom value
+ * `;
+ * const result = parseYaml(yamlContent);
+ * console.log(result); // { example: 'resolved-value' }
+ * ```
+ */
+declare function parseYaml(content: string, options?: ParseOptions & DocumentOptions & SchemaOptions & ToJSOptions): any;
+/**
+ * Converts a JavaScript object into a YAML string with optional custom tags.
+ *
+ * @param content - The JavaScript object to convert to YAML.
+ * @param options - Optional stringification options, including custom tags.
+ * @returns The YAML string representation of the input object.
+ *
+ * @example
+ * ```typescript
+ * import { stringifyYaml } from './yaml';
+ *
+ * const data = {
+ *   example: 'value',
+ * };
+ * const yamlString = stringifyYaml(data);
+ * console.log(yamlString); // "example: value\n"
+ * ```
+ */
+declare function stringifyYaml(content: any, options?: DocumentOptions & SchemaOptions & ParseOptions & CreateNodeOptions & ToStringOptions): string;
+
+/**
+ * Converts a string to PascalCase.
+ *
+ * @param str - The string to convert.
+ * @returns The PascalCase version of the string.
+ *
+ * @example
+ * ```typescript
+ * console.log(toPascalCase("some-word")); // Output: "SomeWord"
+ * console.log(toPascalCase("some_Word")); // Output: "SomeWord"
+ * console.log(toPascalCase("someWord"));  // Output: "SomeWord"
+ * console.log(toPascalCase("some word")); // Output: "SomeWord"
+ * console.log(toPascalCase("SOME_WORD")); // Output: "SomeWord"
+ * ```
+ */
+declare function toPascalCase(str: string): string;
+
+/**
+ * Converts a string to camelCase.
+ *
+ * @param str - The string to convert.
+ * @returns The camelCase version of the string.
+ *
+ * @example
+ * ```typescript
+ * console.log(toCamelCase("some-word")); // Output: "someWord"
+ * console.log(toCamelCase("some_Word")); // Output: "someWord"
+ * console.log(toCamelCase("Some Word")); // Output: "someWord"
+ * console.log(toCamelCase("SomeWord"));  // Output: "someWord"
+ * console.log(toCamelCase(""));          // Output: ""
+ * ```
+ */
+declare function toCamelCase(str: string): string;
+
+/**
+ * Converts a string to capital case, where the first letter of each word is capitalized
+ * and the rest are in lowercase. Words are separated by spaces, hyphens, or underscores.
+ *
+ * @param str - The input string to convert.
+ * @returns The converted string in capital case.
+ *
+ * @example
+ * ```typescript
+ * toCapitalCase('hello world'); // Returns 'Hello World'
+ * toCapitalCase('HELLO-WORLD'); // Returns 'Hello World'
+ * toCapitalCase('hello_world'); // Returns 'Hello World'
+ * toCapitalCase('hElLo_wOrLd-TeSt cAsE'); // Returns 'H El Lo W Or Ld Te St C As E'
+ * toCapitalCase(''); // Returns ''
+ * ```
+ */
+declare function toCapitalCase(str: string): string;
+
+export { ConfigFile, DefaultAllTextFiles, type IncludeFiles, type LoadConfigFileOptions, type StringifyFunc, type TraverseFolderHandler, type TraverseFolderSyncHandler, getMultiLevelExtname, glob, isStringIn, normalizeIncludeFiles, parseFrontMatter, parseYaml, registerYamlTag, removeLeadingEmptyLines, stringifyYaml, toCamelCase, toCapitalCase, toPascalCase, traverseFolder, traverseFolderSync };