feat: PathRef - support creating via import.meta and file url str…

…ings (#113)

README.md

@@ -514,6 +514,16 @@ const srcDir = $.path("src").resolve();
 await $`echo ${srcDir}`;
 ```
 
+`PathRef`s can be created in the following ways:
+
+```ts
+const pathRelative = $.path("./relative");
+const pathAbsolute = $.path("/tmp");
+const pathFileUrl = $.path(new URL("file:///tmp")); // converts to /tmp
+const pathStringFileUrl = $.path("file:///tmp"); // converts to /tmp
+const pathImportMeta = $.path(import.meta); // the path for the current module
+```
+
 There are a lot of helper methods here, so check the [documentation on PathRef](https://deno.land/x/dax/src/path.ts?s=PathRef) for more details.
 
 ## Helper functions

mod.ts

@@ -221,7 +221,10 @@ export interface $BuiltInProperties<TExtras extends ExtrasObject = {}> {
   fs: typeof fs;
   /** Helper function for creating path references, which provide an easier way for
    * working with paths, directories, and files on the file system. Also, a re-export
-   * of deno_std's `path` module as properties on this object. */
+   * of deno_std's `path` module as properties on this object.
+   *
+   * The function creates a new `PathRef` from a path or URL string, file URL, or for the current module.
+   */
   path: typeof createPathRef & typeof stdPath;
   /**
    * Logs with potential indentation (`$.logIndent`)

src/path.test.ts

@@ -579,3 +579,9 @@ Deno.test("instanceof check", () => {
   assert(new OtherPathRef() instanceof PathRef);
   assert(createPathRef("test") instanceof OtherPathRef);
 });
+
+Deno.test("toFileUrl", () => {
+  const path = createPathRef(import.meta);
+  assertEquals(path.toString(), stdPath.fromFileUrl(import.meta.url));
+  assertEquals(path.toFileUrl(), new URL(import.meta.url));
+});

src/path.ts

@@ -2,7 +2,7 @@ import { fs, path as stdPath, writeAll, writeAllSync } from "./deps.ts";
 
 const PERIOD_CHAR_CODE = ".".charCodeAt(0);
 
-export function createPathRef(path: string | URL): PathRef {
+export function createPathRef(path: string | URL | ImportMeta): PathRef {
   return new PathRef(path);
 }
 
@@ -27,8 +27,18 @@ export class PathRef {
    */
   private static instanceofSymbol = Symbol.for("dax.PathRef");
 
-  constructor(path: string | URL) {
-    this.#path = path instanceof URL ? stdPath.fromFileUrl(path) : path;
+  constructor(path: string | URL | ImportMeta) {
+    if (path instanceof URL) {
+      this.#path = stdPath.fromFileUrl(path);
+    } else if (typeof path === "string") {
+      if (path.startsWith("file://")) {
+        this.#path = stdPath.fromFileUrl(path);
+      } else {
+        this.#path = path;
+      }
+    } else {
+      this.#path = stdPath.fromFileUrl(path.url);
+    }
   }
 
   /** @internal */
@@ -42,6 +52,12 @@ export class PathRef {
     return this.#path;
   }
 
+  /** Resolves the path and gets the file URL. */
+  toFileUrl(): URL {
+    const resolvedPath = this.resolve();
+    return stdPath.toFileUrl(resolvedPath.toString());
+  }
+
   /** Joins the provided path segments onto this path. */
   join(...pathSegments: string[]): PathRef {
     return new PathRef(stdPath.join(this.#path, ...pathSegments));