@helpers4/url 1.0.1 → 2.0.0-alpha.10

package/README.md

@@ -9,9 +9,64 @@ A set of helpers for working with URLs.
 
 ## Documentation
 
-[https://helpers4.github.io/url](https://helpers4.github.io/url)
+[https://helpers4.dev/typescript/categories/url/](https://helpers4.dev/typescript/categories/url/)
+
+<!-- AUTOMATIC-METHODS -->
+- cleanPath
+- extractPureURI
+- onlyPath
+- relativeURLToAbsolute
+- withLeadingSlash
+- withTrailingSlash
+- withoutLeadingSlash
+- withoutTrailingSlash
+<!-- /AUTOMATIC-METHODS -->
 
 ## See
 
-- [@helpers4/string](https://www.npmjs.com/package/@helpers4/string)
-- [@helpers4/url](https://www.npmjs.com/package/@helpers4/url)
+<!-- AUTOMATIC-SIBLINGS -->
+- [array](../array)
+- [date](../date)
+- [function](../function)
+- [math](../math)
+- [number](../number)
+- [object](../object)
+- [observable](../observable)
+- [promise](../promise)
+- [string](../string)
+- [type](../type)
+- [version](../version)
+<!-- /AUTOMATIC-SIBLINGS -->
+
+## All Available Packages
+
+<!-- AUTOMATIC-CATEGORIES-TABLE -->
+| Name | Package | Source Code | Description |
+|------|---------|-------------|-------------|
+| array | [@helpers4/array](https://www.npmjs.com/package/@helpers4/array) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/array) | Array manipulation utilities |
+| date | [@helpers4/date](https://www.npmjs.com/package/@helpers4/date) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/date) | date utilities |
+| function | [@helpers4/function](https://www.npmjs.com/package/@helpers4/function) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/function) | Function utilities and type guards |
+| math | [@helpers4/math](https://www.npmjs.com/package/@helpers4/math) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/math) | math utilities |
+| number | [@helpers4/number](https://www.npmjs.com/package/@helpers4/number) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/number) | number utilities |
+| object | [@helpers4/object](https://www.npmjs.com/package/@helpers4/object) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/object) | Object manipulation utilities |
+| observable | [@helpers4/observable](https://www.npmjs.com/package/@helpers4/observable) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/observable) | Observable utilities and combinators |
+| promise | [@helpers4/promise](https://www.npmjs.com/package/@helpers4/promise) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/promise) | Promise utilities and error handling |
+| string | [@helpers4/string](https://www.npmjs.com/package/@helpers4/string) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/string) | String manipulation and formatting utilities |
+| type | [@helpers4/type](https://www.npmjs.com/package/@helpers4/type) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/type) | type utilities |
+| url | [@helpers4/url](https://www.npmjs.com/package/@helpers4/url) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/url) | URL parsing and manipulation utilities |
+| version | [@helpers4/version](https://www.npmjs.com/package/@helpers4/version) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/version) | Version string manipulation utilities |
+<!-- /AUTOMATIC-CATEGORIES-TABLE -->
+
+## Contributors
+
+<table>
+<tr>
+    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
+        <a href=https://github.com/baxyz>
+            <img src=https://avatars.githubusercontent.com/u/7852177?v=4 width="100;" alt=baxyz/>
+            <br />
+            <sub style="font-size:14px"><b>baxyz</b></sub>
+        </a>
+    </td>
+</tr>
+</table>

package/lib/index.d.ts

@@ -0,0 +1,437 @@
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Clean an URL by removing duplicate slashes.
+ * The protocol part of the URL is not modified.
+ *
+ * @param url - The URL string to be processed. Can be `string`, `undefined`, or `null`.
+ * @returns The cleaned URL string, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+ *
+ * @example
+ * ```ts
+ * cleanPath('/path//to///resource') // => '/path/to/resource'
+ * cleanPath('http://example.com//path//to///resource') // => 'http://example.com/path/to/resource'
+ * cleanPath(undefined) // => undefined
+ * cleanPath(null) // => null
+ * ```
+ * @since 1.0.0
+ */
+declare function cleanPath(url: string | undefined | null): string | undefined | null;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Extracts the pure URI from a URL by removing query parameters and fragments.
+ *
+ * @param url - The URL string to process
+ * @returns The URI without query parameters and fragments, or the original value if undefined/null
+ * @since 1.9.0
+ */
+declare function extractPureURI(url: string): string;
+declare function extractPureURI(url: undefined): undefined;
+declare function extractPureURI(url: null): null;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Extract only the path from an URI with optional query and fragments.
+ *
+ * For example, all these parameters will return `/path`:
+ *  - `/path`
+ *  - `/path?query=thing`
+ *  - `/path#fragment`
+ *  - `/path?query=thing#fragment`
+ *
+ * @param url - The URL string to be processed. Can be `string`, `undefined`, or `null`.
+ * @returns The URL string without query and fragment, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+ *
+ * @example
+ * ```ts
+ * onlyPath('/path') // => '/path'
+ * onlyPath('/path?query=thing') // => '/path'
+ * onlyPath('/path#fragment') // => '/path'
+ * onlyPath('/path?query=thing#fragment') // => '/path'
+ * onlyPath(undefined) // => undefined
+ * onlyPath(null) // => null
+ * ```
+ * @since 1.0.0
+ */
+declare function onlyPath(url: string): string;
+/**
+ * Extract only the path from an URI with optional query and fragments.
+ *
+ * For example, all these parameters will return `/path`:
+ *  - `/path`
+ *  - `/path?query=thing`
+ *  - `/path#fragment`
+ *  - `/path?query=thing#fragment`
+ *
+ * @param url - The URL string to be processed. Can be `string`, `undefined`, or `null`.
+ * @returns The URL string without query and fragment, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+ *
+ * @example
+ * ```ts
+ * onlyPath('/path') // => '/path'
+ * onlyPath('/path?query=thing') // => '/path'
+ * onlyPath('/path#fragment') // => '/path'
+ * onlyPath('/path?query=thing#fragment') // => '/path'
+ * onlyPath(undefined) // => undefined
+ * onlyPath(null) // => null
+ * ```
+ * @since 1.0.0
+ */
+declare function onlyPath(url: null): null;
+/**
+ * Extract only the path from an URI with optional query and fragments.
+ *
+ * For example, all these parameters will return `/path`:
+ *  - `/path`
+ *  - `/path?query=thing`
+ *  - `/path#fragment`
+ *  - `/path?query=thing#fragment`
+ *
+ * @param url - The URL string to be processed. Can be `string`, `undefined`, or `null`.
+ * @returns The URL string without query and fragment, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+ *
+ * @example
+ * ```ts
+ * onlyPath('/path') // => '/path'
+ * onlyPath('/path?query=thing') // => '/path'
+ * onlyPath('/path#fragment') // => '/path'
+ * onlyPath('/path?query=thing#fragment') // => '/path'
+ * onlyPath(undefined) // => undefined
+ * onlyPath(null) // => null
+ * ```
+ * @since 1.0.0
+ */
+declare function onlyPath(url: undefined): undefined;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Converts a relative URL to an absolute URL using the current document base URI.
+ * @param relativeUrl - The relative URL to convert
+ * @returns The absolute URL
+ * @since 1.0.0
+ */
+declare function relativeURLToAbsolute(relativeUrl: string): string;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Adds a leading slash `/` to the given URL if it is not already present.
+ *
+ * This function is useful for ensuring that URLs are properly formatted
+ * with a leading slash, which is often required in web development for
+ * consistency and to avoid issues with relative paths.
+ *
+ * @param url - The URL string to be processed. Can be `string`, `undefined`, or `null`.
+ * @returns The URL string with a leading slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+ *
+ * @see https://radashi.js.org/reference/url/withLeadingSlash
+ *
+ * @example
+ * ```ts
+ * withLeadingSlash('') // => '/'
+ * withLeadingSlash('no/slash') // => '/no/slash'
+ * withLeadingSlash('/already/has/slash') // => '/already/has/slash'
+ * withLeadingSlash(undefined) // => undefined
+ * withLeadingSlash(null) // => null
+ * ```
+ * @since 1.0.0
+ */
+declare function withLeadingSlash(url: string): string;
+/**
+ * Adds a leading slash `/` to the given URL if it is not already present.
+ *
+ * This function is useful for ensuring that URLs are properly formatted
+ * with a leading slash, which is often required in web development for
+ * consistency and to avoid issues with relative paths.
+ *
+ * @param url - The URL string to be processed. Can be `string`, `undefined`, or `null`.
+ * @returns The URL string with a leading slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+ *
+ * @see https://radashi.js.org/reference/url/withLeadingSlash
+ *
+ * @example
+ * ```ts
+ * withLeadingSlash('') // => '/'
+ * withLeadingSlash('no/slash') // => '/no/slash'
+ * withLeadingSlash('/already/has/slash') // => '/already/has/slash'
+ * withLeadingSlash(undefined) // => undefined
+ * withLeadingSlash(null) // => null
+ * ```
+ * @since 1.0.0
+ */
+declare function withLeadingSlash(url: undefined): undefined;
+/**
+ * Adds a leading slash `/` to the given URL if it is not already present.
+ *
+ * This function is useful for ensuring that URLs are properly formatted
+ * with a leading slash, which is often required in web development for
+ * consistency and to avoid issues with relative paths.
+ *
+ * @param url - The URL string to be processed. Can be `string`, `undefined`, or `null`.
+ * @returns The URL string with a leading slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+ *
+ * @see https://radashi.js.org/reference/url/withLeadingSlash
+ *
+ * @example
+ * ```ts
+ * withLeadingSlash('') // => '/'
+ * withLeadingSlash('no/slash') // => '/no/slash'
+ * withLeadingSlash('/already/has/slash') // => '/already/has/slash'
+ * withLeadingSlash(undefined) // => undefined
+ * withLeadingSlash(null) // => null
+ * ```
+ * @since 1.0.0
+ */
+declare function withLeadingSlash(url: null): null;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Adds a trailing slash `/` to the given URL if it is not already present.
+ *
+ * This function is useful for ensuring that URLs are properly formatted
+ * with a trailing slash, which is often required in web development for
+ * consistency and to avoid issues with relative paths.
+ *
+ * @param url - The URL string to be processed. Can be `string`, `undefined`, or `null`.
+ * @returns The URL string with a trailing slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+ *
+ * @see https://radashi.js.org/reference/url/withTrailingSlash
+ *
+ * @example
+ * ```ts
+ * withTrailingSlash('') // => '/'
+ * withTrailingSlash('no/slash') // => 'no/slash/'
+ * withTrailingSlash('already/has/slash/') // => 'already/has/slash/'
+ * withTrailingSlash(undefined) // => undefined
+ * withTrailingSlash(null) // => null
+ * ```
+ * @since 1.0.0
+ */
+declare function withTrailingSlash(url: string): string;
+/**
+ * Adds a trailing slash `/` to the given URL if it is not already present.
+ *
+ * This function is useful for ensuring that URLs are properly formatted
+ * with a trailing slash, which is often required in web development for
+ * consistency and to avoid issues with relative paths.
+ *
+ * @param url - The URL string to be processed. Can be `string`, `undefined`, or `null`.
+ * @returns The URL string with a trailing slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+ *
+ * @see https://radashi.js.org/reference/url/withTrailingSlash
+ *
+ * @example
+ * ```ts
+ * withTrailingSlash('') // => '/'
+ * withTrailingSlash('no/slash') // => 'no/slash/'
+ * withTrailingSlash('already/has/slash/') // => 'already/has/slash/'
+ * withTrailingSlash(undefined) // => undefined
+ * withTrailingSlash(null) // => null
+ * ```
+ * @since 1.0.0
+ */
+declare function withTrailingSlash(url: undefined): undefined;
+/**
+ * Adds a trailing slash `/` to the given URL if it is not already present.
+ *
+ * This function is useful for ensuring that URLs are properly formatted
+ * with a trailing slash, which is often required in web development for
+ * consistency and to avoid issues with relative paths.
+ *
+ * @param url - The URL string to be processed. Can be `string`, `undefined`, or `null`.
+ * @returns The URL string with a trailing slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+ *
+ * @see https://radashi.js.org/reference/url/withTrailingSlash
+ *
+ * @example
+ * ```ts
+ * withTrailingSlash('') // => '/'
+ * withTrailingSlash('no/slash') // => 'no/slash/'
+ * withTrailingSlash('already/has/slash/') // => 'already/has/slash/'
+ * withTrailingSlash(undefined) // => undefined
+ * withTrailingSlash(null) // => null
+ * ```
+ * @since 1.0.0
+ */
+declare function withTrailingSlash(url: null): null;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Removes the leading slash `/` from the given URL if it is present.
+ *
+ * This function is useful for ensuring that URLs are properly formatted
+ * without a leading slash, which is often required in web development for
+ * consistency and to avoid issues with relative paths.
+ *
+ * @param url - The URL string to be processed. Can be `string`, `undefined`, or `null`.
+ * @returns The URL string without a leading slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+ *
+ * @see https://radashi.js.org/reference/url/withoutLeadingSlash
+ *
+ * @example
+ * ```ts
+ * withoutLeadingSlash('') // => ''
+ * withoutLeadingSlash('/') // => ''
+ * withoutLeadingSlash('/no/slash') // => 'no/slash'
+ * withoutLeadingSlash('already/has/slash') // => 'already/has/slash'
+ * withoutLeadingSlash(undefined) // => undefined
+ * withoutLeadingSlash(null) // => null
+ * ```
+ * @since 1.0.0
+ */
+declare function withoutLeadingSlash(url: string): string;
+/**
+ * Removes the leading slash `/` from the given URL if it is present.
+ *
+ * This function is useful for ensuring that URLs are properly formatted
+ * without a leading slash, which is often required in web development for
+ * consistency and to avoid issues with relative paths.
+ *
+ * @param url - The URL string to be processed. Can be `string`, `undefined`, or `null`.
+ * @returns The URL string without a leading slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+ *
+ * @see https://radashi.js.org/reference/url/withoutLeadingSlash
+ *
+ * @example
+ * ```ts
+ * withoutLeadingSlash('') // => ''
+ * withoutLeadingSlash('/') // => ''
+ * withoutLeadingSlash('/no/slash') // => 'no/slash'
+ * withoutLeadingSlash('already/has/slash') // => 'already/has/slash'
+ * withoutLeadingSlash(undefined) // => undefined
+ * withoutLeadingSlash(null) // => null
+ * ```
+ * @since 1.0.0
+ */
+declare function withoutLeadingSlash(url: undefined): undefined;
+/**
+ * Removes the leading slash `/` from the given URL if it is present.
+ *
+ * This function is useful for ensuring that URLs are properly formatted
+ * without a leading slash, which is often required in web development for
+ * consistency and to avoid issues with relative paths.
+ *
+ * @param url - The URL string to be processed. Can be `string`, `undefined`, or `null`.
+ * @returns The URL string without a leading slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+ *
+ * @see https://radashi.js.org/reference/url/withoutLeadingSlash
+ *
+ * @example
+ * ```ts
+ * withoutLeadingSlash('') // => ''
+ * withoutLeadingSlash('/') // => ''
+ * withoutLeadingSlash('/no/slash') // => 'no/slash'
+ * withoutLeadingSlash('already/has/slash') // => 'already/has/slash'
+ * withoutLeadingSlash(undefined) // => undefined
+ * withoutLeadingSlash(null) // => null
+ * ```
+ * @since 1.0.0
+ */
+declare function withoutLeadingSlash(url: null): null;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Removes the trailing slash `/` from the given URL if it is present.
+ *
+ * This function is useful for ensuring that URLs are properly formatted
+ * without a trailing slash, which is often required in web development for
+ * consistency and to avoid issues with relative paths.
+ *
+ * @param url - The URL string to be processed. Can be `string`, `undefined`, or `null`.
+ * @returns The URL string without a trailing slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+ *
+ * @see https://radashi.js.org/reference/url/withoutTrailingSlash
+ *
+ * @example
+ * ```ts
+ * withoutTrailingSlash('') // => ''
+ * withoutTrailingSlash('/') // => ''
+ * withoutTrailingSlash('no/slash/') // => 'no/slash'
+ * withoutTrailingSlash('already/has/slash') // => 'already/has/slash'
+ * withoutTrailingSlash(undefined) // => undefined
+ * withoutTrailingSlash(null) // => null
+ * ```
+ * @since 1.0.0
+ */
+declare function withoutTrailingSlash(url: string): string;
+/**
+ * Removes the trailing slash `/` from the given URL if it is present.
+ *
+ * This function is useful for ensuring that URLs are properly formatted
+ * without a trailing slash, which is often required in web development for
+ * consistency and to avoid issues with relative paths.
+ *
+ * @param url - The URL string to be processed. Can be `string`, `undefined`, or `null`.
+ * @returns The URL string without a trailing slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+ *
+ * @see https://radashi.js.org/reference/url/withoutTrailingSlash
+ *
+ * @example
+ * ```ts
+ * withoutTrailingSlash('') // => ''
+ * withoutTrailingSlash('/') // => ''
+ * withoutTrailingSlash('no/slash/') // => 'no/slash'
+ * withoutTrailingSlash('already/has/slash') // => 'already/has/slash'
+ * withoutTrailingSlash(undefined) // => undefined
+ * withoutTrailingSlash(null) // => null
+ * ```
+ * @since 1.0.0
+ */
+declare function withoutTrailingSlash(url: undefined): undefined;
+/**
+ * Removes the trailing slash `/` from the given URL if it is present.
+ *
+ * This function is useful for ensuring that URLs are properly formatted
+ * without a trailing slash, which is often required in web development for
+ * consistency and to avoid issues with relative paths.
+ *
+ * @param url - The URL string to be processed. Can be `string`, `undefined`, or `null`.
+ * @returns The URL string without a trailing slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+ *
+ * @see https://radashi.js.org/reference/url/withoutTrailingSlash
+ *
+ * @example
+ * ```ts
+ * withoutTrailingSlash('') // => ''
+ * withoutTrailingSlash('/') // => ''
+ * withoutTrailingSlash('no/slash/') // => 'no/slash'
+ * withoutTrailingSlash('already/has/slash') // => 'already/has/slash'
+ * withoutTrailingSlash(undefined) // => undefined
+ * withoutTrailingSlash(null) // => null
+ * ```
+ * @since 1.0.0
+ */
+declare function withoutTrailingSlash(url: null): null;
+
+export { cleanPath, extractPureURI, onlyPath, relativeURLToAbsolute, withLeadingSlash, withTrailingSlash, withoutLeadingSlash, withoutTrailingSlash };