@cspell/url 8.9.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Jason Dent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# `@cspell/url`
+
+A URL parsing and manipulation library for cspell.
+
+## Install
+
+```sh
+npm install -S @cspell/url
+```
+
+<!--- @@inject: ../../static/footer.md --->
+
+<br/>
+
+---
+
+<p align="center">Brought to you by<a href="https://streetsidesoftware.com" title="Street Side Software"><img width="16" alt="Street Side Software Logo" src="https://i.imgur.com/CyduuVY.png" /> Street Side Software</a></p>
+
+<!--- @@inject-end: ../../static/footer.md --->
+
+<!--- cspell:dictionaries typescript --->

package/dist/dataUrl.d.mts

@@ -0,0 +1,8 @@
+/**
+ * Try to determine the base name of a URL.
+ * @param url
+ * @returns the base name of a URL, including the trailing `/` if present.
+ */
+export declare function urlBasename(url: string | URL): string;
+export declare function isDataURL(url: string | URL): boolean;
+//# sourceMappingURL=dataUrl.d.mts.map

package/dist/dataUrl.mjs

@@ -0,0 +1,25 @@
+import { basenameOfUrlPathname, hasProtocol, toURL } from './url.mjs';
+const regMatchFilename = /filename=([^;,]*)/;
+/**
+ * Try to determine the base name of a URL.
+ * @param url
+ * @returns the base name of a URL, including the trailing `/` if present.
+ */
+export function urlBasename(url) {
+    function guessDataUrlName(header) {
+        const filenameMatch = header.match(regMatchFilename);
+        if (filenameMatch)
+            return filenameMatch[1];
+        const mime = header.split(';', 1)[0];
+        return mime.replaceAll(/\W/g, '.');
+    }
+    url = toURL(url);
+    if (url.protocol === 'data:') {
+        return guessDataUrlName(url.pathname.split(',', 1)[0]);
+    }
+    return basenameOfUrlPathname(url.pathname);
+}
+export function isDataURL(url) {
+    return hasProtocol(url, 'data:');
+}
+//# sourceMappingURL=dataUrl.mjs.map

package/dist/fileUrl.d.mts

@@ -0,0 +1,77 @@
+/**
+ * @param url - URL or string to check if it is a file URL.
+ * @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

@@ -0,0 +1,138 @@
+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;
+/**
+ * @param url - URL or string to check if it is a file URL.
+ * @returns true if the URL is a file URL.
+ */
+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
+ * @returns path or href
+ */
+export function toFilePathOrHref(url) {
+    return isFileURL(url) ? toFilePath(url) : url.toString();
+}
+function toFilePath(url) {
+    return windowsDriveLetterToUpper(fileURLToPath(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

@@ -0,0 +1,5 @@
+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';
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,4 @@
+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';
+//# sourceMappingURL=index.mjs.map

package/dist/url.d.mts

@@ -0,0 +1,48 @@
+/**
+ * Try to make a URL.
+ * @param url
+ * @param relativeTo - optional URL, if given, url will be parsed as relative.
+ * @returns a URL
+ */
+export declare function toURL(url: string | URL, relativeTo?: string | URL): URL;
+/**
+ * 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 function urlParent(url: string | URL): URL;
+/**
+ * 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.
+ */
+export declare function basenameOfUrlPathname(path: string): string;
+/**
+ * @param filename - filename to check if it is a string containing a URL.
+ */
+export declare function isUrlLike(filename: string): boolean;
+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;
+/**
+ * Check if `url` is a URL instance.
+ * @returns
+ */
+export declare function isURL(url: unknown): url is URL;
+/**
+ *
+ * @param url - url to check
+ * @param protocol - protocol to check against - e.g. 'file:', 'http:', 'https:'
+ * @returns
+ */
+export declare function hasProtocol(url: string | URL, protocol: string): boolean;
+/**
+ * Attempts to add a trailing slash to the URL pathname if it does not already have one.
+ * Some If the pathname doesn't start with a `/`, a trailing slash is not added.
+ * @param url - a URL
+ * @returns
+ */
+export declare function addTrailingSlash(url: URL): URL;
+//# sourceMappingURL=url.d.mts.map

package/dist/url.mjs

@@ -0,0 +1,73 @@
+const isURLRegEx = /^(\w[\w-]{1,63}:\/|data:|stdin:)/i;
+/**
+ * Try to make a URL.
+ * @param url
+ * @param relativeTo - optional URL, if given, url will be parsed as relative.
+ * @returns a URL
+ */
+export function toURL(url, relativeTo) {
+    return url instanceof URL ? url : new URL(url, relativeTo);
+}
+/**
+ * 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 function urlParent(url) {
+    url = toURL(url);
+    if (url.protocol === 'data:') {
+        return url;
+    }
+    const hasTrailingSlash = url.pathname.endsWith('/');
+    if (!url.pathname.startsWith('/')) {
+        const parts = url.pathname.split('/').slice(0, hasTrailingSlash ? -2 : -1);
+        let pathname = parts.join('/');
+        pathname = (pathname && pathname + '/') || '';
+        return new URL(url.protocol + (url.host ? '//' + url.host : '') + pathname + url.search + url.hash);
+    }
+    return new URL(hasTrailingSlash ? '..' : '.', url);
+}
+/**
+ * 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.
+ */
+export function basenameOfUrlPathname(path) {
+    const adj = path.endsWith('/') ? 2 : 0;
+    const idx = path.lastIndexOf('/', path.length - adj);
+    return idx >= 0 ? path.slice(idx + 1) : path;
+}
+export function isUrlLike(filename) {
+    return filename instanceof URL || isURLRegEx.test(filename);
+}
+/**
+ * Check if `url` is a URL instance.
+ * @returns
+ */
+export function isURL(url) {
+    return url instanceof URL;
+}
+/**
+ *
+ * @param url - url to check
+ * @param protocol - protocol to check against - e.g. 'file:', 'http:', 'https:'
+ * @returns
+ */
+export function hasProtocol(url, protocol) {
+    protocol = protocol.endsWith(':') ? protocol : protocol + ':';
+    return typeof url === 'string' ? url.startsWith(protocol) : url.protocol === protocol;
+}
+/**
+ * Attempts to add a trailing slash to the URL pathname if it does not already have one.
+ * Some If the pathname doesn't start with a `/`, a trailing slash is not added.
+ * @param url - a URL
+ * @returns
+ */
+export function addTrailingSlash(url) {
+    if (url.pathname.endsWith('/'))
+        return url;
+    const urlWithSlash = new URL(url.href);
+    urlWithSlash.pathname += '/';
+    return urlWithSlash;
+}
+//# sourceMappingURL=url.mjs.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@cspell/url",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "8.9.0-alpha.0",
+  "description": "URL parsing and manipulation utilities for cspell",
+  "keywords": [
+    "cspell",
+    "url"
+  ],
+  "author": "Jason Dent <jason@streetsidesoftware.nl>",
+  "homepage": "https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell-url#readme",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildInfo",
+    "!**/__mocks__",
+    "!**/*.spec.*",
+    "!**/*.test.*",
+    "!**/test/**",
+    "!**/*.map"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "build:clean": "pnpm clean && pnpm build",
+    "clean": "shx rm -rf dist coverage",
+    "clean-build": "pnpm build:clean",
+    "coverage": "vitest run --coverage",
+    "test-watch": "vitest",
+    "test": "vitest run",
+    "watch": "tsc -p . --watch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/streetsidesoftware/cspell.git",
+    "directory": "packages/dynamic-import"
+  },
+  "bugs": {
+    "url": "https://github.com/streetsidesoftware/cspell"
+  },
+  "engines": {
+    "node": ">=18.0"
+  },
+  "gitHead": "700ed688420d2f3e784c05e2709ad33953aadadc"
+}