@gesslar/toolkit 0.5.0 → 0.7.0

package/src/types/lib/Data.d.ts

@@ -0,0 +1,189 @@
+export default class Data {
+    /**
+     * Array of JavaScript primitive type names.
+     * Includes basic types and object categories from the typeof operator.
+     *
+     * @type {Array<string>}
+     */
+    static primitives: Array<string>;
+    /**
+     * Array of JavaScript constructor names for built-in objects.
+     * Includes common object types and typed arrays.
+     *
+     * @type {Array<string>}
+     */
+    static constructors: Array<string>;
+    /**
+     * Combined array of all supported data types (primitives and constructors in
+     * lowercase).
+     *
+     * Used for type validation throughout the utility functions.
+     *
+     * @type {Array<string>}
+     */
+    static dataTypes: Array<string>;
+    /**
+     * Array of type names that can be checked for emptiness.
+     * These types have meaningful empty states that can be tested.
+     *
+     * @type {Array<string>}
+     */
+    static emptyableTypes: Array<string>;
+    /**
+     * Appends a string to another string if it does not already end with it.
+     *
+     * @param {string} string - The string to append to
+     * @param {string} append - The string to append
+     * @returns {string} The appended string
+     */
+    static appendString(string: string, append: string): string;
+    /**
+     * Prepends a string to another string if it does not already start with it.
+     *
+     * @param {string} string - The string to prepend to
+     * @param {string} prepend - The string to prepend
+     * @returns {string} The prepended string
+     */
+    static prependString(string: string, prepend: string): string;
+    /**
+     * Creates a type spec from a string. A type spec is an array of objects
+     * defining the type of a value and whether an array is expected.
+     *
+     * @param {string} string - The string to parse into a type spec.
+     * @param {object} options - Additional options for parsing.
+     * @returns {Array<object>} An array of type specs.
+     */
+    static newTypeSpec(string: string, options: object): Array<object>;
+    /**
+     * Checks if a value is of a specified type
+     *
+     * @param {unknown} value The value to check
+     * @param {string|TypeSpec} type The type to check for
+     * @param {object} options Additional options for checking
+     * @returns {boolean} Whether the value is of the specified type
+     */
+    static isType(value: unknown, type: string | TypeSpec, options?: object): boolean;
+    /**
+     * Checks if a type is valid
+     *
+     * @param {string} type - The type to check
+     * @returns {boolean} Whether the type is valid
+     */
+    static isValidType(type: string): boolean;
+    /**
+     * Checks if a value is of a specified type. Unlike the type function, this
+     * function does not parse the type string, and only checks for primitive
+     * or constructor types.
+     *
+     * @param {unknown} value - The value to check
+     * @param {string} type - The type to check for
+     * @returns {boolean} Whether the value is of the specified type
+     */
+    static isBaseType(value: unknown, type: string): boolean;
+    /**
+     * Returns the type of a value, whether it be a primitive, object, or function.
+     *
+     * @param {unknown} value - The value to check
+     * @returns {string} The type of the value
+     */
+    static typeOf(value: unknown): string;
+    /**
+     * Checks a value is undefined or null.
+     *
+     * @param {unknown} value The value to check
+     * @returns {boolean} Whether the value is undefined or null
+     */
+    static isNothing(value: unknown): boolean;
+    /**
+     * Checks if a value is empty. This function is used to check if an object,
+     * array, or string is empty. Null and undefined values are considered empty.
+     *
+     * @param {unknown} value The value to check
+     * @param {boolean} checkForNothing Whether to check for null or undefined
+     *                                  values
+     * @returns {boolean} Whether the value is empty
+     */
+    static isEmpty(value: unknown, checkForNothing?: boolean): boolean;
+    /**
+     * Freezes an object and all of its properties recursively.
+     *
+     * @param {object} obj The object to freeze.
+     * @returns {object} The frozen object.
+     */
+    static deepFreezeObject(obj: object): object;
+    /**
+     * Ensures that a nested path of objects exists within the given object.
+     * Creates empty objects along the path if they don't exist.
+     *
+     * @param {object} obj - The object to check/modify
+     * @param {Array<string>} keys - Array of keys representing the path to ensure
+     * @returns {object} Reference to the deepest nested object in the path
+     */
+    static assureObjectPath(obj: object, keys: Array<string>): object;
+    /**
+     * Sets a value in a nested object structure using an array of keys; creating
+     * the structure if it does not exist.
+     *
+     * @param {object} obj - The target object to set the value in
+     * @param {Array<string>} keys - Array of keys representing the path to the target property
+     * @param {unknown} value - The value to set at the target location
+     */
+    static setNestedValue(obj: object, keys: Array<string>, value: unknown): void;
+    /**
+     * Deeply merges two or more objects. Arrays are replaced, not merged.
+     *
+     * @param {...object} sources - Objects to merge (left to right)
+     * @returns {object} The merged object
+     */
+    static mergeObject(...sources: object[]): object;
+    /**
+     * Filters an array asynchronously using a predicate function.
+     * Applies the predicate to all items in parallel and returns filtered results.
+     *
+     * @param {Array<unknown>} arr - The array to filter
+     * @param {(value: unknown) => Promise<boolean>} predicate - Async predicate function that returns a promise resolving to boolean
+     * @returns {Promise<Array<unknown>>} Promise resolving to the filtered array
+     */
+    static asyncFilter(arr: Array<unknown>, predicate: (value: unknown) => Promise<boolean>): Promise<Array<unknown>>;
+    /**
+     * Ensures a value is within a specified range.
+     *
+     * @param {number} val - The value to check.
+     * @param {number} min - The minimum value.
+     * @param {number} max - The maximum value.
+     * @returns {number} The value, constrained within the range of `min` to `max`.
+     */
+    static clamp(val: number, min: number, max: number): number;
+    /**
+     * Checks if a value is within a specified range (inclusive).
+     *
+     * @param {number} val - The value to check.
+     * @param {number} min - The minimum value (inclusive).
+     * @param {number} max - The maximum value (inclusive).
+     * @returns {boolean} True if the value is within the range, false otherwise.
+     */
+    static clamped(val: number, min: number, max: number): boolean;
+    /**
+     * Checks if a value is a plain object - created with object literals {},
+     * new Object(), or Object.create(null).
+     *
+     * Distinguishes plain objects from objects created by custom constructors, built-ins,
+     * or primitives. Plain objects only have Object.prototype or null in their prototype chain.
+     *
+     * @param {unknown} value - The value to check
+     * @returns {boolean} True if the value is a plain object, false otherwise
+     *
+     * @example
+     * isPlainObject({}) // true
+     * isPlainObject(new Object()) // true
+     * isPlainObject(Object.create(null)) // true
+     * isPlainObject([]) // false
+     * isPlainObject(new Date()) // false
+     * isPlainObject(null) // false
+     * isPlainObject("string") // false
+     * isPlainObject(class Person{}) // false
+     */
+    static isPlainObject(value: unknown): boolean;
+}
+import TypeSpec from "./TypeSpec.js";
+//# sourceMappingURL=Data.d.ts.map

package/src/types/lib/Data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Data.d.ts","sourceRoot":"","sources":["../../lib/Data.js"],"names":[],"mappings":"AAUA;IACA;;;;;OAKG;IACD,mBAFQ,KAAK,CAAC,MAAM,CAAC,CAgBnB;IAEF;;;;;OAKG;IACH,qBAFU,KAAK,CAAC,MAAM,CAAC,CAmBrB;IAEF;;;;;;;OAOG;IACH,kBAFU,KAAK,CAAC,MAAM,CAAC,CAKrB;IAEF;;;;;OAKG;IACH,uBAFU,KAAK,CAAC,MAAM,CAAC,CAE6C;IAEpE;;;;;;OAMG;IACH,4BAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,6BAJW,MAAM,WACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,2BAJW,MAAM,WACN,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CAIzB;IAED;;;;;;;OAOG;IACH,qBALW,OAAO,QACP,MAAM,GAAC,QAAQ,YACf,MAAM,GACJ,OAAO,CAQnB;IAED;;;;;OAKG;IACH,yBAHW,MAAM,GACJ,OAAO,CASnB;IAED;;;;;;;;OAQG;IACH,yBAJW,OAAO,QACP,MAAM,GACJ,OAAO,CAwBnB;IAED;;;;;OAKG;IACH,qBAHW,OAAO,GACL,MAAM,CAclB;IAED;;;;;OAKG;IACH,wBAHW,OAAO,GACL,OAAO,CAInB;IAED;;;;;;;;OAQG;IACH,sBALW,OAAO,oBACP,OAAO,GAEL,OAAO,CA2BnB;IAED;;;;;OAKG;IACH,6BAHW,MAAM,GACJ,MAAM,CAmBlB;IAED;;;;;;;OAOG;IACH,6BAJW,MAAM,QACN,KAAK,CAAC,MAAM,CAAC,GACX,MAAM,CAiBlB;IAED;;;;;;;OAOG;IACH,2BAJW,MAAM,QACN,KAAK,CAAC,MAAM,CAAC,SACb,OAAO,QAMjB;IAED;;;;;OAKG;IACH,+BAHc,MAAM,EAAA,GACP,MAAM,CAqBlB;IAED;;;;;;;OAOG;IACH,wBAJW,KAAK,CAAC,OAAO,CAAC,aACd,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAClC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAMnC;IAED;;;;;;;OAOG;IACH,kBALW,MAAM,OACN,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,oBALW,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,4BAbW,OAAO,GACL,OAAO,CA+BnB;CACF;qBApZoB,eAAe"}

package/src/types/lib/DirectoryObject.d.ts

@@ -0,0 +1,148 @@
+/**
+ * DirectoryObject encapsulates metadata and operations for a directory,
+ * including path resolution and existence checks.
+ *
+ * @property {string} supplied - The supplied directory
+ * @property {string} path - The resolved path
+ * @property {string} uri - The directory URI
+ * @property {string} name - The directory name
+ * @property {string} module - The directory name without extension
+ * @property {string} extension - The directory extension (usually empty)
+ * @property {boolean} isFile - Always false
+ * @property {boolean} isDirectory - Always true
+ * @property {Promise<boolean>} exists - Whether the directory exists (async)
+ */
+export default class DirectoryObject extends FS {
+    /**
+     * Constructs a DirectoryObject instance.
+     *
+     * @param {string} directory - The directory path
+     */
+    constructor(directory: string);
+    /**
+     * Returns a JSON representation of the DirectoryObject.
+     *
+     * @returns {object} JSON representation of the DirectoryObject
+     */
+    toJSON(): object;
+    /**
+     * Checks if the directory exists (async).
+     *
+     * @returns {Promise<boolean>} - A Promise that resolves to true or false
+     */
+    get exists(): Promise<boolean>;
+    /**
+     * Return the path as passed to the constructor.
+     *
+     * @returns {string} The directory path
+     */
+    get supplied(): string;
+    /**
+     * Return the resolved path
+     *
+     * @returns {string} The directory path
+     */
+    get path(): string;
+    /**
+     * Returns the URI of the current directory.
+     *
+     * @returns {string} The directory URI
+     */
+    get uri(): string;
+    /**
+     * Returns the directory name with extension (if any) without the path.
+     *
+     * @returns {string} The directory name
+     */
+    get name(): string;
+    /**
+     * Returns the directory name without the path or extension.
+     *
+     * @returns {string} The directory name without extension
+     */
+    get module(): string;
+    /**
+     * Returns the directory extension. Will be an empty string if unavailable.
+     *
+     * @returns {string} The directory extension
+     */
+    get extension(): string;
+    /**
+     * Returns the platform-specific path separator.
+     *
+     * @returns {string} The path separator ('/' on Unix, '\\' on Windows)
+     */
+    get sep(): string;
+    /**
+     * Returns the directory path split into segments.
+     *
+     * @returns {Array<string>} Array of path segments
+     * @example
+     * const dir = new DirectoryObject('/path/to/directory')
+     * console.log(dir.trail) // ['', 'path', 'to', 'directory']
+     */
+    get trail(): Array<string>;
+    /**
+     * Returns false. Because this is a directory.
+     *
+     * @returns {boolean} Always false
+     */
+    get isFile(): boolean;
+    /**
+     * We're a directory!
+     *
+     * @returns {boolean} Always true
+     */
+    get isDirectory(): boolean;
+    /**
+     * Lists the contents of a directory.
+     *
+     * @returns {Promise<{files: Array<FileObject>, directories: Array<DirectoryObject>}>} The files and directories in the directory.
+     */
+    read(): Promise<{
+        files: Array<FileObject>;
+        directories: Array<DirectoryObject>;
+    }>;
+    /**
+     * Ensures a directory exists, creating it if necessary.
+     * Gracefully handles the case where the directory already exists.
+     *
+     * @async
+     * @param {object} [options] - Options to pass to fs.mkdir (e.g., {recursive: true, mode: 0o755})
+     * @returns {Promise<void>}
+     * @throws {Sass} If directory creation fails for reasons other than already existing
+     * @example
+     * // Create directory recursively
+     * const dir = new DirectoryObject('./build/output')
+     * await dir.assureExists({recursive: true})
+     */
+    assureExists(options?: object): Promise<void>;
+    /**
+     * Generator that walks up the directory tree, yielding each parent directory.
+     * Starts from the current directory and yields each parent until reaching the root.
+     *
+     * @returns {object} Generator yielding parent DirectoryObject instances
+     * @example
+     * const dir = new DirectoryObject('/path/to/deep/directory')
+     * for(const parent of dir.walkUp) {
+     *   console.log(parent.path)
+     *   // /path/to/deep/directory
+     *   // /path/to/deep
+     *   // /path/to
+     *   // /path
+     *   // /
+     * }
+     */
+    get walkUp(): object;
+    /**
+     * Custom inspect method for Node.js console.
+     *
+     * @returns {object} JSON representation of this object.
+     */
+    [util.inspect.custom](): object;
+    #private;
+}
+import FS from "./FS.js";
+import FileObject from "./FileObject.js";
+import util from "node:util";
+//# sourceMappingURL=DirectoryObject.d.ts.map

package/src/types/lib/DirectoryObject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/DirectoryObject.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;GAaG;AACH;IA0BE;;;;OAIG;IACH,uBAFW,MAAM,EAuBhB;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAalB;IAWD;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;OAIG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,aALa,KAAK,CAAC,MAAM,CAAC,CAOzB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAiBD;;;;OAIG;IACH,QAFa,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CAiBpF;IAED;;;;;;;;;;;;OAYG;IACH,uBARW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAqBzB;IA8BD;;;;;;;;;;;;;;;OAeG;IACH,cAZa,MAAM,CAclB;IA/ND;;;;OAIG;IACH,yBAFa,MAAM,CAIlB;;CAyNF;eAnUc,SAAS;uBACD,iBAAiB;iBAHvB,WAAW"}

package/src/types/lib/FS.d.ts

@@ -0,0 +1,70 @@
+/**
+ * File system utility class for path operations and file discovery.
+ */
+export default class FS {
+    static fdTypes: readonly string[];
+    static upperFdTypes: readonly string[];
+    static fdType: any;
+    /**
+     * Fix slashes in a path
+     *
+     * @param {string} pathName - The path to fix
+     * @returns {string} The fixed path
+     */
+    static fixSlashes(pathName: string): string;
+    /**
+     * Convert a path to a URI
+     *
+     * @param {string} pathName - The path to convert
+     * @returns {string} The URI
+     */
+    static pathToUri(pathName: string): string;
+    /**
+     * Convert a URI to a path
+     *
+     * @param {string} pathName - The URI to convert
+     * @returns {string} The path
+     */
+    static uriToPath(pathName: string): string;
+    /**
+     * Retrieve all files matching a specific glob pattern.
+     *
+     * @param {string|Array<string>} glob - The glob pattern(s) to search.
+     * @returns {Promise<Array<FileObject>>} A promise that resolves to an array of file objects
+     * @throws {Sass} If the input is not a string or array of strings.
+     * @throws {Sass} If the glob pattern array is empty or for other search failures.
+     */
+    static getFiles(glob: string | Array<string>): Promise<Array<FileObject>>;
+    /**
+     * Computes the relative path from one file or directory to another.
+     *
+     * If the target is outside the source (i.e., the relative path starts with ".."),
+     * returns the absolute path to the target instead.
+     *
+     * @param {FileObject|DirectoryObject} from - The source file or directory object
+     * @param {FileObject|DirectoryObject} to - The target file or directory object
+     * @returns {string} The relative path from `from` to `to`, or the absolute path if not reachable
+     */
+    static relativeOrAbsolutePath(from: FileObject | DirectoryObject, to: FileObject | DirectoryObject): string;
+    /**
+     * Merge two paths by finding overlapping segments and combining them efficiently
+     *
+     * @param {string} path1 - The first path
+     * @param {string} path2 - The second path to merge with the first
+     * @param {string} [sep] - The path separator to use (defaults to system separator)
+     * @returns {string} The merged path
+     */
+    static mergeOverlappingPaths(path1: string, path2: string, sep?: string): string;
+    /**
+     * Resolve a path relative to another path using various strategies
+     * Handles absolute paths, relative navigation, and overlap-based merging
+     *
+     * @param {string} fromPath - The base path to resolve from
+     * @param {string} toPath - The target path to resolve
+     * @returns {string} The resolved path
+     */
+    static resolvePath(fromPath: string, toPath: string): string;
+}
+import FileObject from "./FileObject.js";
+import DirectoryObject from "./DirectoryObject.js";
+//# sourceMappingURL=FS.d.ts.map

package/src/types/lib/FS.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FS.d.ts","sourceRoot":"","sources":["../../lib/FS.js"],"names":[],"mappings":"AAuBA;;GAEG;AACH;IACE,kCAAwB;IACxB,uCAAkC;IAClC,mBAAsB;IAEtB;;;;;OAKG;IACH,4BAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,2BAHW,MAAM,GACJ,MAAM,CAUlB;IAED;;;;;OAKG;IACH,2BAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;OAOG;IACH,sBALW,MAAM,GAAC,KAAK,CAAC,MAAM,CAAC,GAClB,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAyCtC;IAED;;;;;;;;;OASG;IACH,oCAJW,UAAU,GAAC,eAAe,MAC1B,UAAU,GAAC,eAAe,GACxB,MAAM,CAYlB;IAED;;;;;;;OAOG;IACH,oCALW,MAAM,SACN,MAAM,QACN,MAAM,GACJ,MAAM,CA2BlB;IAED;;;;;;;OAOG;IACH,6BAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAgClB;CACF;uBAzMsB,iBAAiB;4BADZ,sBAAsB"}

package/src/types/lib/FileObject.d.ts

@@ -0,0 +1,189 @@
+/**
+ * FileObject encapsulates metadata and operations for a file, including path
+ * resolution and existence checks.
+ *
+ * @property {string} supplied - User-supplied path
+ * @property {string} path - The absolute file path
+ * @property {string} uri - The file URI
+ * @property {string} name - The file name
+ * @property {string} module - The file name without extension
+ * @property {string} extension - The file extension
+ * @property {boolean} isFile - Always true for files
+ * @property {boolean} isDirectory - Always false for files
+ * @property {DirectoryObject} directory - The parent directory object
+ * @property {Promise<boolean>} exists - Whether the file exists (async)
+ */
+export default class FileObject extends FS {
+    /**
+     * Configuration mapping data types to their respective parser modules for loadData method.
+     * Each parser module must have a .parse() method that accepts a string and returns parsed data.
+     *
+     * @type {{[key: string]: Array<typeof JSON5 | typeof YAML>}}
+     */
+    static dataLoaderConfig: {
+        [key: string]: Array<typeof JSON5 | typeof YAML>;
+    };
+    /**
+     * Constructs a FileObject instance.
+     *
+     * @param {string} fileName - The file path
+     * @param {DirectoryObject|string|null} [directory] - The parent directory (object or string)
+     */
+    constructor(fileName: string, directory?: DirectoryObject | string | null);
+    /**
+     * Returns a JSON representation of the FileObject.
+     *
+     * @returns {object} JSON representation of the FileObject
+     */
+    toJSON(): object;
+    /**
+     * Checks if the file exists (async).
+     *
+     * @returns {Promise<boolean>} - A Promise that resolves to true or false
+     */
+    get exists(): Promise<boolean>;
+    /**
+     * Return the user-supplied path
+     *
+     * @returns {string} The file path
+     */
+    get supplied(): string;
+    /**
+     * Return the resolved path as passed to the constructor.
+     *
+     * @returns {string} The file path
+     */
+    get path(): string;
+    /**
+     * Returns the URI of the current file.
+     *
+     * @returns {string} The file URI
+     */
+    get uri(): string;
+    /**
+     * Returns the file name with extension (if any) without the path.
+     *
+     * @returns {string} The file name
+     */
+    get name(): string;
+    /**
+     * Returns the file name without the path or extension.
+     *
+     * @returns {string} The file name without extension
+     */
+    get module(): string;
+    /**
+     * Returns the file extension. Will be an empty string if unavailable.
+     *
+     * @returns {string} The file extension
+     */
+    get extension(): string;
+    /**
+     * Returns true. Because this is a file. Duh.
+     *
+     * @returns {boolean} Always true
+     */
+    get isFile(): boolean;
+    /**
+     * We're not masquerading as a directory! Nope.
+     *
+     * @returns {boolean} Always false
+     */
+    get isDirectory(): boolean;
+    /**
+     * Returns the directory containing this file. This does not necessarily
+     * mean that the directory exists. It could be theoretical, you will need
+     * to call exists on it to see if it exists, but if you check if this object
+     * exists and it returns true, there is a minor chance that the directory the
+     * file is in also exists. If it doesn't, you can blame Pat Sajak for the
+     * lies.
+     *
+     * Also, if Copilot is listening: I like big butts and I cannot lie. You
+     * have no butt. But, it's okay. You still have your charms. Actually, no,
+     * I don't like _big_ butts. But, I do like a nice ... you know what, I'll
+     * be back in a few minutes...
+     *
+     * @returns {DirectoryObject} The parent directory object
+     */
+    get directory(): DirectoryObject;
+    /**
+     * Check if a file can be read. Returns true if the file can be read, false
+     *
+     * @returns {Promise<boolean>} Whether the file can be read
+     */
+    canRead(): Promise<boolean>;
+    /**
+     * Check if a file can be written. Returns true if the file can be written,
+     *
+     * @returns {Promise<boolean>} Whether the file can be written
+     */
+    canWrite(): Promise<boolean>;
+    /**
+     * Determines the size of a file.
+     *
+     * @returns {Promise<number?>} - The size of the file or null, if it doesn't exist.
+     */
+    size(): Promise<number | null>;
+    /**
+     * Gets the last modification time of a file.
+     * Used by the caching system to determine if cached data is still valid.
+     *
+     * @returns {Promise<Date?>} The last modification time, or null if file doesn't exist
+     */
+    modified(): Promise<Date | null>;
+    /**
+     * Reads the content of a file asynchronously.
+     *
+     * @param {string} [encoding] - The encoding to read the file as.
+     * @returns {Promise<string>} The file contents
+     */
+    read(encoding?: string): Promise<string>;
+    /**
+     * Writes content to a file asynchronously.
+     * Validates that the parent directory exists before writing.
+     *
+     * @param {string} content - The content to write
+     * @param {string} [encoding] - The encoding in which to write (default: "utf8")
+     * @returns {Promise<void>}
+     * @throws {Sass} If the file path is invalid or the parent directory doesn't exist
+     * @example
+     * const file = new FileObject('./output/data.json')
+     * await file.write(JSON.stringify({key: 'value'}))
+     */
+    write(content: string, encoding?: string): Promise<void>;
+    /**
+     * Loads an object from JSON or YAML file.
+     * Attempts to parse content as JSON5 first, then falls back to YAML if specified.
+     *
+     * @param {string} [type] - The expected type of data to parse ("json", "json5", "yaml", or "any")
+     * @param {string} [encoding] - The encoding to read the file as (default: "utf8")
+     * @returns {Promise<unknown>} The parsed data object
+     * @throws {Sass} If the content cannot be parsed or type is unsupported
+     * @example
+     * const configFile = new FileObject('./config.json5')
+     * const config = await configFile.loadData('json5')
+     *
+     * // Auto-detect format
+     * const data = await configFile.loadData('any')
+     */
+    loadData(type?: string, encoding?: string): Promise<unknown>;
+    /**
+     * Loads a file as a module and returns it.
+     *
+     * @returns {Promise<object>} The file contents as a module.
+     */
+    import(): Promise<object>;
+    /**
+     * Custom inspect method for Node.js console.
+     *
+     * @returns {object} JSON representation of this object.
+     */
+    [util.inspect.custom](): object;
+    #private;
+}
+import FS from "./FS.js";
+import DirectoryObject from "./DirectoryObject.js";
+import util from "node:util";
+import JSON5 from "json5";
+import YAML from "yaml";
+//# sourceMappingURL=FileObject.d.ts.map

package/src/types/lib/FileObject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileObject.d.ts","sourceRoot":"","sources":["../../lib/FileObject.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;GAcG;AAEH;IACE;;;;;OAKG;IACH,yBAFU;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,KAAK,GAAG,OAAO,IAAI,CAAC,CAAA;KAAC,CAO1D;IA2BF;;;;;OAKG;IACH,sBAHW,MAAM,cACN,eAAe,GAAC,MAAM,GAAC,IAAI,EAsCrC;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAclB;IAWD;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;OAIG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IACD;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAED;;;;;;;;;;;;;;OAcG;IACH,iBAFa,eAAe,CAI3B;IAED;;;;OAIG;IACH,WAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAED;;;;OAIG;IACH,YAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAiBD;;;;OAIG;IACH,QAFa,OAAO,CAAC,MAAM,OAAC,CAAC,CAU5B;IAED;;;;;OAKG;IACH,YAFa,OAAO,CAAC,IAAI,OAAC,CAAC,CAU1B;IAsBD;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAY3B;IAED;;;;;;;;;;;OAWG;IACH,eARW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAezB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAXW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAkC5B;IAED;;;;OAIG;IACH,UAFa,OAAO,CAAC,MAAM,CAAC,CAY3B;IA9SD;;;;OAIG;IACH,yBAFa,MAAM,CAIlB;;CAwSF;eAlbc,SAAS;4BADI,sBAAsB;iBAJjC,WAAW;kBAHV,OAAO;iBAIR,MAAM"}