@cspell/url 8.9.1 → 8.10.0

package/dist/FileUrlBuilder.d.mts

@@ -0,0 +1,88 @@
+import Path from 'node:path';
+export declare const isWindows: boolean;
+export declare const isWindowsPathRegEx: RegExp;
+export declare const percentRegEx: RegExp;
+export declare const backslashRegEx: RegExp;
+export declare const newlineRegEx: RegExp;
+export declare const carriageReturnRegEx: RegExp;
+export declare const tabRegEx: RegExp;
+export declare const questionRegex: RegExp;
+export declare const hashRegex: RegExp;
+export interface PathInterface {
+    sep: string;
+    resolve(...paths: string[]): string;
+    parse(path: string): Path.ParsedPath;
+    normalize(path: string): string;
+    relative(from: string, to: string): string;
+    isAbsolute(path: string): boolean;
+}
+export interface BuilderOptions {
+    windows?: boolean | undefined;
+    path?: PathInterface | undefined;
+    cwd?: URL | undefined;
+}
+export declare class FileUrlBuilder {
+    #private;
+    private windows;
+    readonly path: PathInterface;
+    readonly cwd: URL;
+    constructor(options?: BuilderOptions);
+    /**
+     * Encode special characters in a file path to use in a URL.
+     * @param filepath
+     * @returns
+     */
+    encodePathChars(filepath: string): string;
+    /**
+     * Normalize a file path for use in a URL.
+     * ```js
+     * const url = new URL(normalizeFilePathForUrl('path\\to\\file.txt'), 'file:///Users/user/');
+     * // Result: file:///Users/user/path/to/file.txt
+     * ```
+     * @param filePath
+     * @returns a normalized file path for use as a relative path in a URL.
+     */
+    normalizeFilePathForUrl(filePath: string): string;
+    /**
+     * Try to make a file URL.
+     * - if filenameOrUrl is already a URL, it is returned as is.
+     * @param filenameOrUrl
+     * @param relativeTo - optional URL, if given, filenameOrUrl will be parsed as relative.
+     * @returns a URL
+     */
+    toFileURL(filenameOrUrl: string | URL, relativeTo?: string | URL): URL;
+    /**
+     * Try to make a URL for a directory.
+     * - if dirOrUrl is already a URL, a slash is appended to the pathname.
+     * @param dirOrUrl - directory path to convert to a file URL.
+     * @param relativeTo - optional URL, if given, filenameOrUrl will be parsed as relative.
+     * @returns a URL
+     */
+    toFileDirURL(dirOrUrl: string | URL, relativeTo?: string | URL): URL;
+    urlToFilePathOrHref(url: URL | string): string;
+    /**
+     * Calculate the relative path to go from `urlFrom` to `urlTo`.
+     * The protocol is not evaluated. Only the `url.pathname` is used.
+     * The result: `new URL(relative(urlFrom, urlTo), urlFrom).pathname === urlTo.pathname`
+     * @param urlFrom
+     * @param urlTo
+     * @returns the relative path
+     */
+    relative(urlFrom: URL, urlTo: URL): string;
+    /**
+     * Get the parent directory of a URL.
+     * @param url
+     */
+    urlDirname(url: URL | string): URL;
+    pathToFileURL(pathname: string, relativeToURL?: URL | string): URL;
+    rootFileURL(filePath?: string): URL;
+    /**
+     * Determine if a filePath is absolute.
+     *
+     * @param filePath
+     * @returns true if `URL` or `path.isAbsolute(filePath)`
+     */
+    isAbsolute(filePath: string): boolean;
+    isUrlLike(url: string | URL): boolean;
+}
+//# sourceMappingURL=FileUrlBuilder.d.mts.map

package/dist/FileUrlBuilder.mjs

@@ -0,0 +1,176 @@
+import assert from 'node:assert';
+import Path from 'node:path';
+import { toFilePathOrHref } from './fileUrl.mjs';
+import { addTrailingSlash, isUrlLike, urlParent, urlToUrlRelative } from './url.mjs';
+export const isWindows = process.platform === 'win32';
+export const isWindowsPathRegEx = /^[a-z]:[\\/]/i;
+const isWindowsPathname = /^[\\/]([a-z]:[\\/])/i;
+export const percentRegEx = /%/g;
+export const backslashRegEx = /\\/g;
+export const newlineRegEx = /\n/g;
+export const carriageReturnRegEx = /\r/g;
+export const tabRegEx = /\t/g;
+export const questionRegex = /\?/g;
+export const hashRegex = /#/g;
+const ProtocolFile = 'file:';
+const RootFileURL = 'file:///';
+export class FileUrlBuilder {
+    windows;
+    path;
+    cwd;
+    constructor(options = {}) {
+        const sep = options.path?.sep;
+        this.windows = options.windows ?? (sep ? sep === '\\' : undefined) ?? isWindows;
+        this.path = options.path ?? (this.windows ? Path.win32 : Path.posix);
+        // note: `this.path.resolve() + '/'` is used on purpose instead of `'./'`
+        this.cwd = options.cwd ?? this.pathToFileURL(this.path.resolve() + '/', this.rootFileURL());
+        assert(this.path.sep === (this.windows ? '\\' : '/'), `Path separator should match OS type Windows: ${this.windows === true ? 'true' : (this.windows ?? 'undefined') || 'false'}, ` +
+            `sep: ${this.path.sep}, ` +
+            `options: ` +
+            JSON.stringify({
+                isWindows,
+                sep: `${sep}`,
+                windows: options.windows,
+                pathSep: options.path?.sep,
+                n: options.path?.normalize('path/file.txt'),
+                cwd: options.cwd?.href,
+                win32: this.path === Path.win32,
+                posix: this.path === Path.posix,
+                'win32.normalize': this.path.normalize === Path.win32.normalize,
+                'posix.normalize': this.path.normalize === Path.posix.normalize,
+            }) +
+            ``);
+    }
+    /**
+     * Encode special characters in a file path to use in a URL.
+     * @param filepath
+     * @returns
+     */
+    encodePathChars(filepath) {
+        filepath = filepath.replaceAll(percentRegEx, '%25');
+        // In posix, backslash is a valid character in paths:
+        if (!this.windows && !isWindows && filepath.includes('\\')) {
+            filepath = filepath.replaceAll(backslashRegEx, '%5C');
+        }
+        filepath = filepath.replaceAll(newlineRegEx, '%0A');
+        filepath = filepath.replaceAll(carriageReturnRegEx, '%0D');
+        filepath = filepath.replaceAll(tabRegEx, '%09');
+        return filepath;
+    }
+    /**
+     * Normalize a file path for use in a URL.
+     * ```js
+     * const url = new URL(normalizeFilePathForUrl('path\\to\\file.txt'), 'file:///Users/user/');
+     * // Result: file:///Users/user/path/to/file.txt
+     * ```
+     * @param filePath
+     * @returns a normalized file path for use as a relative path in a URL.
+     */
+    normalizeFilePathForUrl(filePath) {
+        filePath = this.encodePathChars(filePath);
+        filePath = filePath.replaceAll(questionRegex, '%3F');
+        filePath = filePath.replaceAll(hashRegex, '%23');
+        const pathname = filePath.replaceAll('\\', '/');
+        return pathname.replace(isWindowsPathRegEx, (drive) => `/${drive}`.toUpperCase());
+    }
+    /**
+     * Try to make a file URL.
+     * - if filenameOrUrl is already a URL, it is returned as is.
+     * @param filenameOrUrl
+     * @param relativeTo - optional URL, if given, filenameOrUrl will be parsed as relative.
+     * @returns a URL
+     */
+    toFileURL(filenameOrUrl, relativeTo) {
+        if (typeof filenameOrUrl !== 'string')
+            return filenameOrUrl;
+        if (isUrlLike(filenameOrUrl))
+            return new URL(filenameOrUrl);
+        relativeTo ??= this.cwd;
+        isWindows && (filenameOrUrl = filenameOrUrl.replaceAll('\\', '/'));
+        if (isUrlLike(relativeTo)) {
+            const pathname = this.normalizeFilePathForUrl(filenameOrUrl);
+            return new URL(pathname, relativeTo);
+        }
+        // Resolve removes the trailing slash, so we need to add it back.
+        const appendSlash = filenameOrUrl.endsWith('/') ? '/' : '';
+        const pathname = this.normalizeFilePathForUrl(this.path.resolve(relativeTo.toString(), filenameOrUrl)) + appendSlash;
+        return this.pathToFileURL(pathname, this.cwd);
+    }
+    /**
+     * Try to make a URL for a directory.
+     * - if dirOrUrl is already a URL, a slash is appended to the pathname.
+     * @param dirOrUrl - directory path to convert to a file URL.
+     * @param relativeTo - optional URL, if given, filenameOrUrl will be parsed as relative.
+     * @returns a URL
+     */
+    toFileDirURL(dirOrUrl, relativeTo) {
+        return addTrailingSlash(this.toFileURL(dirOrUrl, relativeTo));
+    }
+    urlToFilePathOrHref(url) {
+        url = this.toFileURL(url);
+        return this.#urlToFilePathOrHref(url);
+    }
+    #urlToFilePathOrHref(url) {
+        if (url.protocol !== ProtocolFile)
+            return url.href;
+        const p = this.path === Path
+            ? toFilePathOrHref(url)
+            : decodeURIComponent(url.pathname.split('/').join(this.path.sep));
+        return p.replace(isWindowsPathRegEx, (drive) => drive.toUpperCase()).replace(isWindowsPathname, '$1');
+    }
+    /**
+     * Calculate the relative path to go from `urlFrom` to `urlTo`.
+     * The protocol is not evaluated. Only the `url.pathname` is used.
+     * The result: `new URL(relative(urlFrom, urlTo), urlFrom).pathname === urlTo.pathname`
+     * @param urlFrom
+     * @param urlTo
+     * @returns the relative path
+     */
+    relative(urlFrom, urlTo) {
+        if (urlFrom.protocol === urlTo.protocol && urlFrom.protocol === ProtocolFile) {
+            if (urlFrom.href === urlTo.href)
+                return '';
+            urlFrom = urlFrom.pathname.endsWith('/') ? urlFrom : new URL('./', urlFrom);
+            const fromPath = urlFrom.pathname;
+            const toPath = urlTo.pathname;
+            if (toPath.startsWith(fromPath))
+                return decodeURIComponent(toPath.slice(fromPath.length));
+            const pFrom = this.#urlToFilePathOrHref(urlFrom);
+            const pTo = this.#urlToFilePathOrHref(urlTo);
+            const toIsDir = urlTo.pathname.endsWith('/');
+            let pathname = this.normalizeFilePathForUrl(this.path.relative(pFrom, pTo));
+            if (toIsDir && !pathname.endsWith('/'))
+                pathname += '/';
+            return decodeURIComponent(pathname);
+        }
+        return decodeURIComponent(urlToUrlRelative(urlFrom, urlTo));
+    }
+    /**
+     * Get the parent directory of a URL.
+     * @param url
+     */
+    urlDirname(url) {
+        return urlParent(this.toFileURL(url));
+    }
+    pathToFileURL(pathname, relativeToURL) {
+        return new URL(this.normalizeFilePathForUrl(pathname), relativeToURL || this.cwd);
+    }
+    rootFileURL(filePath) {
+        const path = this.path;
+        const p = path.parse(path.normalize(path.resolve(filePath ?? '.')));
+        return new URL(this.normalizeFilePathForUrl(p.root), RootFileURL);
+    }
+    /**
+     * Determine if a filePath is absolute.
+     *
+     * @param filePath
+     * @returns true if `URL` or `path.isAbsolute(filePath)`
+     */
+    isAbsolute(filePath) {
+        return isUrlLike(filePath) || this.path.isAbsolute(filePath);
+    }
+    isUrlLike(url) {
+        return isUrlLike(url);
+    }
+}
+//# sourceMappingURL=FileUrlBuilder.mjs.map

package/dist/defaultFileUrlBuilder.d.mts

@@ -0,0 +1,27 @@
+export declare function encodePathChars(filepath: string): string;
+/**
+ * Normalize a file path for use in a URL.
+ * ```js
+ * const url = new URL(normalizeFilePathForUrl('path\\to\\file.txt'), 'file:///Users/user/');
+ * // Result: file:///Users/user/path/to/file.txt
+ * ```
+ * @param filePath
+ * @returns a normalized file path for use as a relative path in a URL.
+ */
+export declare function normalizeFilePathForUrl(filePath: string): string;
+/**
+ * Try to make a file URL.
+ * - if filenameOrUrl is already a URL, it is returned as is.
+ * -
+ * @param filenameOrUrl
+ * @param relativeTo - optional URL, if given, filenameOrUrl will be parsed as relative.
+ * @returns a URL
+ */
+export declare function toFileURL(filenameOrUrl: string | URL, relativeTo?: string | URL): URL;
+/**
+ * Converts a file path to a URL and adds a trailing slash.
+ * @param dir - url to a directory
+ * @returns a URL
+ */
+export declare function toFileDirURL(dir: string | URL): URL;
+//# sourceMappingURL=defaultFileUrlBuilder.d.mts.map

package/dist/defaultFileUrlBuilder.mjs

@@ -0,0 +1,37 @@
+import { FileUrlBuilder } from './FileUrlBuilder.mjs';
+const fileUrlBuilder = new FileUrlBuilder();
+export function encodePathChars(filepath) {
+    return fileUrlBuilder.encodePathChars(filepath);
+}
+/**
+ * Normalize a file path for use in a URL.
+ * ```js
+ * const url = new URL(normalizeFilePathForUrl('path\\to\\file.txt'), 'file:///Users/user/');
+ * // Result: file:///Users/user/path/to/file.txt
+ * ```
+ * @param filePath
+ * @returns a normalized file path for use as a relative path in a URL.
+ */
+export function normalizeFilePathForUrl(filePath) {
+    return fileUrlBuilder.normalizeFilePathForUrl(filePath);
+}
+/**
+ * Try to make a file URL.
+ * - if filenameOrUrl is already a URL, it is returned as is.
+ * -
+ * @param filenameOrUrl
+ * @param relativeTo - optional URL, if given, filenameOrUrl will be parsed as relative.
+ * @returns a URL
+ */
+export function toFileURL(filenameOrUrl, relativeTo) {
+    return fileUrlBuilder.toFileURL(filenameOrUrl, relativeTo);
+}
+/**
+ * Converts a file path to a URL and adds a trailing slash.
+ * @param dir - url to a directory
+ * @returns a URL
+ */
+export function toFileDirURL(dir) {
+    return fileUrlBuilder.toFileDirURL(dir);
+}
+//# sourceMappingURL=defaultFileUrlBuilder.mjs.map

package/dist/fileUrl.d.mts

@@ -3,75 +3,10 @@
  * @returns true if the URL is a file URL.
  */
 export declare function isFileURL(url: URL | string): boolean;
-export interface PathInterface {
-    sep: string;
-    resolve(...paths: string[]): string;
-}
-export interface BuilderOptions {
-    windows?: boolean | undefined;
-    path?: PathInterface | undefined;
-    cwd?: URL | undefined;
-}
-export declare class FileUrlBuilder {
-    private windows;
-    private path;
-    private cwd;
-    constructor(options?: BuilderOptions);
-    /**
-     * Encode special characters in a file path to use in a URL.
-     * @param filepath
-     * @returns
-     */
-    encodePathChars(filepath: string): string;
-    /**
-     * Normalize a file path for use in a URL.
-     * ```js
-     * const url = new URL(normalizeFilePathForUrl('path\\to\\file.txt'), 'file:///Users/user/');
-     * // Result: file:///Users/user/path/to/file.txt
-     * ```
-     * @param filePath
-     * @returns a normalized file path for use as a relative path in a URL.
-     */
-    normalizeFilePathForUrl(filePath: string): string;
-    /**
-     * Try to make a file URL.
-     * - if filenameOrUrl is already a URL, it is returned as is.
-     * @param filenameOrUrl
-     * @param relativeTo - optional URL, if given, filenameOrUrl will be parsed as relative.
-     * @returns a URL
-     */
-    toFileURL(filenameOrUrl: string | URL, relativeTo?: string | URL): URL;
-}
-export declare function encodePathChars(filepath: string): string;
-/**
- * Normalize a file path for use in a URL.
- * ```js
- * const url = new URL(normalizeFilePathForUrl('path\\to\\file.txt'), 'file:///Users/user/');
- * // Result: file:///Users/user/path/to/file.txt
- * ```
- * @param filePath
- * @returns a normalized file path for use as a relative path in a URL.
- */
-export declare function normalizeFilePathForUrl(filePath: string): string;
-/**
- * Try to make a file URL.
- * - if filenameOrUrl is already a URL, it is returned as is.
- * -
- * @param filenameOrUrl
- * @param relativeTo - optional URL, if given, filenameOrUrl will be parsed as relative.
- * @returns a URL
- */
-export declare function toFileURL(filenameOrUrl: string | URL, relativeTo?: string | URL): URL;
 /**
  * Convert a URL into a string. If it is a file URL, convert it to a path.
  * @param url - URL
  * @returns path or href
  */
 export declare function toFilePathOrHref(url: URL | string): string;
-/**
- * Converts a file path to a URL and adds a trailing slash.
- * @param dir - url to a directory
- * @returns a URL
- */
-export declare function toFileDirURL(dir: string | URL): URL;
 //# sourceMappingURL=fileUrl.d.mts.map

package/dist/fileUrl.mjs

@@ -1,16 +1,5 @@
-import assert from 'node:assert';
-import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { addTrailingSlash, hasProtocol, isUrlLike } from './url.mjs';
-const isWindows = process.platform === 'win32';
-const isWindowsPathRegEx = /^[a-z]:[\\/]/i;
-const percentRegEx = /%/g;
-const backslashRegEx = /\\/g;
-const newlineRegEx = /\n/g;
-const carriageReturnRegEx = /\r/g;
-const tabRegEx = /\t/g;
-const questionRegex = /\?/g;
-const hashRegex = /#/g;
+import { fileURLToPath } from 'node:url';
+import { hasProtocol } from './url.mjs';
 /**
  * @param url - URL or string to check if it is a file URL.
  * @returns true if the URL is a file URL.
@@ -18,100 +7,6 @@ const hashRegex = /#/g;
 export function isFileURL(url) {
     return hasProtocol(url, 'file:');
 }
-export class FileUrlBuilder {
-    windows;
-    path;
-    cwd;
-    constructor(options = {}) {
-        const sep = options.path?.sep;
-        this.windows = options.windows ?? (sep ? sep === '\\' : undefined) ?? isWindows;
-        this.path = options.path ?? this.windows ? path.win32 : path.posix;
-        this.cwd = options.cwd ?? pathToFileURL(this.path.resolve() + '/');
-        assert(this.path.sep === (this.windows ? '\\' : '/'));
-    }
-    /**
-     * Encode special characters in a file path to use in a URL.
-     * @param filepath
-     * @returns
-     */
-    encodePathChars(filepath) {
-        filepath = filepath.replaceAll(percentRegEx, '%25');
-        // In posix, backslash is a valid character in paths:
-        if (!this.windows && filepath.includes('\\'))
-            filepath = filepath.replaceAll(backslashRegEx, '%5C');
-        filepath = filepath.replaceAll(newlineRegEx, '%0A');
-        filepath = filepath.replaceAll(carriageReturnRegEx, '%0D');
-        filepath = filepath.replaceAll(tabRegEx, '%09');
-        return filepath;
-    }
-    /**
-     * Normalize a file path for use in a URL.
-     * ```js
-     * const url = new URL(normalizeFilePathForUrl('path\\to\\file.txt'), 'file:///Users/user/');
-     * // Result: file:///Users/user/path/to/file.txt
-     * ```
-     * @param filePath
-     * @returns a normalized file path for use as a relative path in a URL.
-     */
-    normalizeFilePathForUrl(filePath) {
-        filePath = this.encodePathChars(filePath);
-        filePath = filePath.replaceAll(questionRegex, '%3F');
-        filePath = filePath.replaceAll(hashRegex, '%23');
-        const pathname = filePath.replaceAll('\\', '/');
-        return pathname.replace(isWindowsPathRegEx, (drive) => `/${drive}`.toUpperCase());
-    }
-    /**
-     * Try to make a file URL.
-     * - if filenameOrUrl is already a URL, it is returned as is.
-     * @param filenameOrUrl
-     * @param relativeTo - optional URL, if given, filenameOrUrl will be parsed as relative.
-     * @returns a URL
-     */
-    toFileURL(filenameOrUrl, relativeTo) {
-        if (typeof filenameOrUrl !== 'string')
-            return filenameOrUrl;
-        if (isUrlLike(filenameOrUrl))
-            return new URL(filenameOrUrl);
-        relativeTo ??= this.cwd;
-        if (isUrlLike(relativeTo)) {
-            return new URL(this.normalizeFilePathForUrl(filenameOrUrl), relativeTo);
-        }
-        // Resolve removes the trailing slash, so we need to add it back.
-        const appendSlash = filenameOrUrl.endsWith('/')
-            ? '/'
-            : this.windows && filenameOrUrl.endsWith('\\')
-                ? '\\'
-                : '';
-        return pathToFileURL(this.path.resolve(relativeTo.toString(), filenameOrUrl) + appendSlash);
-    }
-}
-const fileUrlBuilder = new FileUrlBuilder();
-export function encodePathChars(filepath) {
-    return fileUrlBuilder.encodePathChars(filepath);
-}
-/**
- * Normalize a file path for use in a URL.
- * ```js
- * const url = new URL(normalizeFilePathForUrl('path\\to\\file.txt'), 'file:///Users/user/');
- * // Result: file:///Users/user/path/to/file.txt
- * ```
- * @param filePath
- * @returns a normalized file path for use as a relative path in a URL.
- */
-export function normalizeFilePathForUrl(filePath) {
-    return fileUrlBuilder.normalizeFilePathForUrl(filePath);
-}
-/**
- * Try to make a file URL.
- * - if filenameOrUrl is already a URL, it is returned as is.
- * -
- * @param filenameOrUrl
- * @param relativeTo - optional URL, if given, filenameOrUrl will be parsed as relative.
- * @returns a URL
- */
-export function toFileURL(filenameOrUrl, relativeTo) {
-    return fileUrlBuilder.toFileURL(filenameOrUrl, relativeTo);
-}
 /**
  * Convert a URL into a string. If it is a file URL, convert it to a path.
  * @param url - URL
@@ -126,13 +21,4 @@ function toFilePath(url) {
 function windowsDriveLetterToUpper(absoluteFilePath) {
     return absoluteFilePath.replace(/^([a-z]):\\/, (s) => s.toUpperCase());
 }
-/**
- * Converts a file path to a URL and adds a trailing slash.
- * @param dir - url to a directory
- * @returns a URL
- */
-export function toFileDirURL(dir) {
-    const url = toFileURL(dir);
-    return addTrailingSlash(url);
-}
 //# sourceMappingURL=fileUrl.mjs.map

package/dist/index.d.mts

@@ -1,5 +1,7 @@
 export { isDataURL, urlBasename } from './dataUrl.mjs';
-export type { BuilderOptions, PathInterface } from './fileUrl.mjs';
-export { encodePathChars, FileUrlBuilder, isFileURL, normalizeFilePathForUrl, toFileDirURL, toFilePathOrHref, toFileURL, } from './fileUrl.mjs';
-export { addTrailingSlash, basenameOfUrlPathname, hasProtocol, isURL, isUrlLike, toURL, urlParent } from './url.mjs';
+export { encodePathChars, normalizeFilePathForUrl, toFileDirURL, toFileURL } from './defaultFileUrlBuilder.mjs';
+export { isFileURL, toFilePathOrHref } from './fileUrl.mjs';
+export type { BuilderOptions, PathInterface } from './FileUrlBuilder.mjs';
+export { FileUrlBuilder } from './FileUrlBuilder.mjs';
+export { addTrailingSlash, basenameOfUrlPathname, hasProtocol, isNotUrlLike, isURL, isUrlLike, toURL, urlDirname, urlParent, urlRelative, } from './url.mjs';
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,4 +1,6 @@
 export { isDataURL, urlBasename } from './dataUrl.mjs';
-export { encodePathChars, FileUrlBuilder, isFileURL, normalizeFilePathForUrl, toFileDirURL, toFilePathOrHref, toFileURL, } from './fileUrl.mjs';
-export { addTrailingSlash, basenameOfUrlPathname, hasProtocol, isURL, isUrlLike, toURL, urlParent } from './url.mjs';
+export { encodePathChars, normalizeFilePathForUrl, toFileDirURL, toFileURL } from './defaultFileUrlBuilder.mjs';
+export { isFileURL, toFilePathOrHref } from './fileUrl.mjs';
+export { FileUrlBuilder } from './FileUrlBuilder.mjs';
+export { addTrailingSlash, basenameOfUrlPathname, hasProtocol, isNotUrlLike, isURL, isUrlLike, toURL, urlDirname, urlParent, urlRelative, } from './url.mjs';
 //# sourceMappingURL=index.mjs.map

package/dist/url.d.mts

@@ -12,6 +12,14 @@ export declare function toURL(url: string | URL, relativeTo?: string | URL): URL
  * @returns a URL
  */
 export declare function urlParent(url: string | URL): URL;
+/**
+ * Alias of {@link urlParent}
+ * Try to determine the parent directory URL of the uri.
+ * If it is not a hierarchical URL, then it will return the URL.
+ * @param url - url to extract the dirname from.
+ * @returns a URL
+ */
+export declare const urlDirname: typeof urlParent;
 /**
  * return the basename (last portion of the URL pathname) of a path. It does NOT remove the trailing slash.
  * @param path - URL pathname to extract the basename from.
@@ -26,6 +34,15 @@ export declare function isUrlLike(filename: URL): true;
  * @param filename - filename to check if it is a string containing a URL or a URL object.
  */
 export declare function isUrlLike(filename: string | URL): boolean;
+/**
+ * @param filename - filename to check if it is a string containing a URL.
+ */
+export declare function isNotUrlLike(filename: string): boolean;
+export declare function isNotUrlLike(filename: URL): false;
+/**
+ * @param filename - filename to check if it is a string containing a URL or a URL object.
+ */
+export declare function isNotUrlLike(filename: string | URL): filename is string;
 /**
  * Check if `url` is a URL instance.
  * @returns
@@ -45,4 +62,38 @@ export declare function hasProtocol(url: string | URL, protocol: string): boolea
  * @returns
  */
 export declare function addTrailingSlash(url: URL): URL;
+/**
+ * Remove the filename at the end of the URL pathname.
+ * If the URL pathname ends with a `/`, it is considered a directory and the URL is returned as is.
+ * If the URL pathname does not start with a `/`, it is considered an non-regular URL and the URL is returned as is.
+ * @param url
+ * @returns
+ */
+export declare function urlRemoveFilename(url: URL): URL;
+/**
+ * Extract the filename from the URL pathname.
+ *
+ * ```ts
+ * url.href === new URL(urlFilename(url), urlRemoveFilename(url)).href
+ * ```
+ * @param url - URL to extract the filename from.
+ * @returns the filename or empty string if the URL pathname ends with a `/`.
+ */
+export declare function urlFilename(url: URL): string;
+/**
+ * Calculate the relative path to go from `urlFrom` to `urlTo`.
+ * The protocol is not evaluated. Only the `url.pathname` is used.
+ * @param urlFrom
+ * @param urlTo
+ * @returns the relative path
+ */
+export declare function urlRelative(urlFrom: string | URL, urlTo: string | URL): string;
+/**
+ * Calculate the relative path to go from `urlFrom` to `urlTo`.
+ * The protocol is not evaluated. Only the `url.pathname` is used.
+ * @param urlFrom
+ * @param urlTo
+ * @returns the relative path
+ */
+export declare function urlToUrlRelative(urlFrom: URL, urlTo: URL): string;
 //# sourceMappingURL=url.d.mts.map

package/dist/url.mjs

@@ -28,6 +28,14 @@ export function urlParent(url) {
     }
     return new URL(hasTrailingSlash ? '..' : '.', url);
 }
+/**
+ * Alias of {@link urlParent}
+ * Try to determine the parent directory URL of the uri.
+ * If it is not a hierarchical URL, then it will return the URL.
+ * @param url - url to extract the dirname from.
+ * @returns a URL
+ */
+export const urlDirname = urlParent;
 /**
  * return the basename (last portion of the URL pathname) of a path. It does NOT remove the trailing slash.
  * @param path - URL pathname to extract the basename from.
@@ -40,6 +48,9 @@ export function basenameOfUrlPathname(path) {
 export function isUrlLike(filename) {
     return filename instanceof URL || isURLRegEx.test(filename);
 }
+export function isNotUrlLike(filename) {
+    return !isUrlLike(filename);
+}
 /**
  * Check if `url` is a URL instance.
  * @returns
@@ -70,4 +81,71 @@ export function addTrailingSlash(url) {
     urlWithSlash.pathname += '/';
     return urlWithSlash;
 }
+/**
+ * Remove the filename at the end of the URL pathname.
+ * If the URL pathname ends with a `/`, it is considered a directory and the URL is returned as is.
+ * If the URL pathname does not start with a `/`, it is considered an non-regular URL and the URL is returned as is.
+ * @param url
+ * @returns
+ */
+export function urlRemoveFilename(url) {
+    // Test if it is already a directory or it is not possible to remove the filename.
+    if (url.pathname.endsWith('/') || !url.pathname.startsWith('/'))
+        return url;
+    return new URL('./', url);
+}
+/**
+ * Extract the filename from the URL pathname.
+ *
+ * ```ts
+ * url.href === new URL(urlFilename(url), urlRemoveFilename(url)).href
+ * ```
+ * @param url - URL to extract the filename from.
+ * @returns the filename or empty string if the URL pathname ends with a `/`.
+ */
+export function urlFilename(url) {
+    if (!url.pathname.startsWith('/'))
+        return '';
+    const lastSlash = url.pathname.lastIndexOf('/');
+    return url.pathname.slice(lastSlash + 1);
+}
+/**
+ * Calculate the relative path to go from `urlFrom` to `urlTo`.
+ * The protocol is not evaluated. Only the `url.pathname` is used.
+ * @param urlFrom
+ * @param urlTo
+ * @returns the relative path
+ */
+export function urlRelative(urlFrom, urlTo) {
+    return urlToUrlRelative(toURL(urlFrom), toURL(urlTo));
+}
+/**
+ * Calculate the relative path to go from `urlFrom` to `urlTo`.
+ * The protocol is not evaluated. Only the `url.pathname` is used.
+ * @param urlFrom
+ * @param urlTo
+ * @returns the relative path
+ */
+export function urlToUrlRelative(urlFrom, urlTo) {
+    let pFrom = urlFrom.pathname;
+    const pTo = urlTo.pathname;
+    if (pFrom === pTo)
+        return '';
+    pFrom = pFrom.endsWith('/') ? pFrom : new URL('./', urlFrom).pathname;
+    if (pTo.startsWith(pFrom))
+        return decodeURIComponent(pTo.slice(pFrom.length));
+    const p0 = pFrom;
+    const p1 = pTo;
+    if (p1.startsWith(p0)) {
+        return decodeURIComponent(p0 === p1 ? '' : p1.slice(p0.lastIndexOf('/') + 1));
+    }
+    const p0Parts = p0.split('/').slice(0, -1); // drop the last segment.
+    const p1Parts = p1.split('/');
+    let i = 0;
+    for (i = 0; i < p0Parts.length && i < p1Parts.length - 1 && p0Parts[i] === p1Parts[i]; ++i) {
+        // empty
+    }
+    const rel = '../'.repeat(p0Parts.length - i) + p1Parts.slice(i).join('/');
+    return decodeURIComponent(rel.length < p1.length ? rel : p1);
+}
 //# sourceMappingURL=url.mjs.map

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "8.9.1",
+  "version": "8.10.0",
   "description": "URL parsing and manipulation utilities for cspell",
   "keywords": [
     "cspell",
@@ -28,6 +28,8 @@
     "!**/*.spec.*",
     "!**/*.test.*",
     "!**/test/**",
+    "!**/*.perf.*",
+    "!**/perf/**",
     "!**/*.map"
   ],
   "scripts": {
@@ -38,6 +40,9 @@
     "coverage": "vitest run --coverage",
     "test-watch": "vitest",
     "test": "vitest run",
+    "test:perf": "insight --file \"dist/perf/**/*.perf.{mjs,js}\" -t 1000",
+    "test:perf:ts": "insight --register ts-node/esm --file \"src/perf/**/*.perf.{mts,ts}\" -t 1000",
+    "test:perf:prof": "NODE_ENV=production node --cpu-prof ../../node_modules/perf-insight/bin.mjs --file \"dist/perf/**/*.perf.{mjs,js}\" -t 1000",
     "watch": "tsc -p . --watch"
   },
   "repository": {
@@ -51,5 +56,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "f532c77cca4bfae380293c586f02f377354c850b"
+  "gitHead": "a5dde6ae7e2ac86ac956220d4b8c39a0e58e1bc6"
 }