@helpers4/url 2.0.0-alpha.1 → 2.0.0-alpha.11

package/README.md

@@ -9,16 +9,16 @@ A set of helpers for working with URLs.
 
 ## Documentation
 
-[https://helpers4.js.org/url](https://helpers4.js.org/url)
+[https://helpers4.dev/typescript/categories/url/](https://helpers4.dev/typescript/categories/url/)
 
 <!-- AUTOMATIC-METHODS -->
-- withoutLeadingSlash
-- withTrailingSlash
-- onlyPath
 - cleanPath
-- withLeadingSlash
-- relativeURLToAbsolute
 - extractPureURI
+- onlyPath
+- relativeURLToAbsolute
+- withLeadingSlash
+- withTrailingSlash
+- withoutLeadingSlash
 - withoutTrailingSlash
 <!-- /AUTOMATIC-METHODS -->
 
@@ -28,6 +28,7 @@ A set of helpers for working with URLs.
 - [array](../array)
 - [date](../date)
 - [function](../function)
+- [math](../math)
 - [number](../number)
 - [object](../object)
 - [observable](../observable)
@@ -45,6 +46,7 @@ A set of helpers for working with URLs.
 | 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 |

package/lib/index.d.ts

@@ -1,8 +1,437 @@
-export * from './withoutLeadingSlash';
-export * from './withTrailingSlash';
-export * from './onlyPath';
-export * from './cleanPath';
-export * from './withLeadingSlash';
-export * from './relativeURLToAbsolute';
-export * from './extractPureURI';
-export * from './withoutTrailingSlash';
+/**
+ * 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 };