@gesslar/toolkit 0.2.7 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",

package/src/lib/FileObject.js

@@ -353,12 +353,12 @@ export default class FileObject extends FS {
   async read(encoding="utf8") {
     const filePath = this.path
 
-    if(!(await this.exists))
-      throw Sass.new(`No such file '${filePath}'`)
-
     if(!filePath)
       throw Sass.new("No absolute path in file map")
 
+    if(!(await this.exists))
+      throw Sass.new(`No such file '${filePath}'`)
+
     return await fs.readFile(filePath, encoding)
   }
 
@@ -409,4 +409,21 @@ export default class FileObject extends FS {
 
     throw Sass.new(`Content is neither valid JSON5 nor valid YAML:\n'${this.path}'`)
   }
+
+  /**
+   * Loads a file as a module and returns it.
+   *
+   * @returns {Promise<object>} The file contents as a module.
+   */
+  async import() {
+    const fileUri = this.uri
+
+    if(!fileUri)
+      throw Sass.new("No URI in file map")
+
+    if(!(await this.exists))
+      throw Sass.new(`No such file '${fileUri}'`)
+
+    return await import(fileUri)
+  }
 }

package/src/types/FileObject.d.ts

@@ -326,4 +326,27 @@ export default class FileObject extends FS {
 
   /** Load an object from JSON5 or YAML file with type specification */
   loadData(type?: 'json' | 'json5' | 'yaml' | 'any', encoding?: string): Promise<unknown>
+
+  /**
+   * Dynamically import the file using the resolved file URI.
+   *
+   * Uses Node.js' native dynamic `import()` under the hood, allowing consumers to load
+   * ESM modules from disk with full path resolution handled by FileObject. The method
+   * verifies the file exists before attempting the import to provide clearer error
+   * messaging and prevent low-level loader failures.
+   *
+   * @typeParam TModule - Expected module shape. Defaults to a loose record to help with
+   * module namespace typing.
+   *
+   * @returns The imported module namespace object.
+   *
+   * @throws {Error} When the file does not exist or the path cannot be converted to a URI.
+   *
+   * @example
+   * ```typescript
+   * const configModule = await file.import<{ default: Config }>()
+   * const config = configModule.default
+   * ```
+   */
+  import<TModule = Record<string, unknown>>(): Promise<TModule>
 }