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

package/README.md

@@ -44,15 +44,15 @@ A set of helpers for working with URLs.
 | 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 |
+| date | [@helpers4/date](https://www.npmjs.com/package/@helpers4/date) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/date) | Date and time utility functions |
 | 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 |
+| math | [@helpers4/math](https://www.npmjs.com/package/@helpers4/math) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/math) | Mathematical utility functions and calculations |
+| number | [@helpers4/number](https://www.npmjs.com/package/@helpers4/number) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/number) | Number utility functions and validation |
 | 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 |
+| type | [@helpers4/type](https://www.npmjs.com/package/@helpers4/type) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/type) | Type checking and validation 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 -->

package/llms.txt

@@ -0,0 +1,462 @@
+# @helpers4/url
+
+> Tree-shakable TypeScript utility functions for the `url` domain.
+> Package: `@helpers4/url` — Version: 2.0.0-alpha.15
+> License: LGPL-3.0-or-later
+
+## Installation
+
+```sh
+npm install @helpers4/url
+# or
+pnpm add @helpers4/url
+```
+
+## Usage
+
+```typescript
+import { cleanPath, extractPureURI, onlyPath, ... } from '@helpers4/url';
+```
+
+## Functions
+
+| Function | Description |
+|---|---|
+| `cleanPath` | Clean an URL by removing duplicate slashes. The protocol part of the URL is not modified. |
+| `extractPureURI` | Extracts the pure URI from a URL by removing query parameters and fragments. |
+| `onlyPath` | Extract only the path from an URI with optional query and fragments.  For example, all these paramet |
+| `relativeURLToAbsolute` | Converts a relative URL to an absolute URL using the current document base URI. |
+| `withLeadingSlash` | Adds a leading slash `/` to the given URL if it is not already present.  This function is useful for |
+| `withoutLeadingSlash` | Removes the leading slash `/` from the given URL if it is present.  This function is useful for ensu |
+| `withoutTrailingSlash` | Removes the trailing slash `/` from the given URL if it is present.  This function is useful for ens |
+| `withTrailingSlash` | Adds a trailing slash `/` to the given URL if it is not already present.  This function is useful fo |
+
+---
+
+## API Reference
+
+### `cleanPath`
+
+Clean an URL by removing duplicate slashes.
+The protocol part of the URL is not modified.
+
+```typescript
+import { cleanPath } from '@helpers4/url';
+
+cleanPath(url: string | null | undefined): string | null | undefined
+```
+
+**Parameters:**
+
+- `url: string | null | undefined` — The URL string to be processed. Can be `string`, `undefined`, or `null`.
+
+**Returns:** `string | null | undefined` — The cleaned URL string, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+
+**Examples:**
+
+*Remove duplicate slashes*
+
+Cleans an URL by removing duplicate slashes while preserving the protocol.
+
+```typescript
+cleanPath('/path//to///resource')
+// => '/path/to/resource'
+```
+
+*Preserve protocol*
+
+The double slash after the protocol (http://) is not modified.
+
+```typescript
+cleanPath('http://example.com//path')
+// => 'http://example.com/path'
+```
+
+*Handle null and undefined*
+
+Returns null for null input and undefined for undefined input.
+
+```typescript
+cleanPath(null)      // => null
+cleanPath(undefined) // => undefined
+```
+
+---
+
+### `extractPureURI`
+
+Extracts the pure URI from a URL by removing query parameters and fragments.
+
+```typescript
+import { extractPureURI } from '@helpers4/url';
+
+extractPureURI(url: string): string
+```
+
+**Parameters:**
+
+- `url: string` — The URL string to process
+
+**Returns:** `string` — The URI without query parameters and fragments, or the original value if undefined/null
+
+```typescript
+import { extractPureURI } from '@helpers4/url';
+
+extractPureURI(url: undefined): undefined
+```
+
+**Parameters:**
+
+- `url: undefined` — The URL string to process
+
+**Returns:** `undefined` — The URI without query parameters and fragments, or the original value if undefined/null
+
+```typescript
+import { extractPureURI } from '@helpers4/url';
+
+extractPureURI(url: null): null
+```
+
+**Parameters:**
+
+- `url: null` — The URL string to process
+
+**Returns:** `null` — The URI without query parameters and fragments, or the original value if undefined/null
+
+**Examples:**
+
+*Remove query parameters and fragments*
+
+Strips everything after ? or # from the URL.
+
+```typescript
+extractPureURI('https://example.com/path?query=1#section')
+// => 'https://example.com/path'
+```
+
+---
+
+### `onlyPath`
+
+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`
+
+```typescript
+import { onlyPath } from '@helpers4/url';
+
+onlyPath(url: string): string
+```
+
+**Parameters:**
+
+- `url: string` — The URL string to be processed. Can be `string`, `undefined`, or `null`.
+
+**Returns:** `string` — The URL string without query and fragment, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+
+```typescript
+import { onlyPath } from '@helpers4/url';
+
+onlyPath(url: null): null
+```
+
+**Parameters:**
+
+- `url: null` — The URL string to be processed. Can be `string`, `undefined`, or `null`.
+
+**Returns:** `null` — The URL string without query and fragment, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+
+```typescript
+import { onlyPath } from '@helpers4/url';
+
+onlyPath(url: undefined): undefined
+```
+
+**Parameters:**
+
+- `url: undefined` — The URL string to be processed. Can be `string`, `undefined`, or `null`.
+
+**Returns:** `undefined` — The URL string without query and fragment, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+
+**Examples:**
+
+*Extract the path from a URL*
+
+Strips query parameters and fragments from a URL path.
+
+```typescript
+onlyPath('/path?query=thing#fragment')
+// => '/path'
+```
+
+---
+
+### `relativeURLToAbsolute`
+
+Converts a relative URL to an absolute URL using the current document base URI.
+
+```typescript
+import { relativeURLToAbsolute } from '@helpers4/url';
+
+relativeURLToAbsolute(relativeUrl: string): string
+```
+
+**Parameters:**
+
+- `relativeUrl: string` — The relative URL to convert
+
+**Returns:** `string` — The absolute URL
+
+**Examples:**
+
+*Convert a relative URL to absolute*
+
+Prepends the base URI to a relative path, cleaning duplicate slashes.
+
+```typescript
+relativeURLToAbsolute('/api/data')
+// => 'http://localhost/api/data' (depends on document.baseURI)
+```
+
+---
+
+### `withLeadingSlash`
+
+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.
+
+```typescript
+import { withLeadingSlash } from '@helpers4/url';
+
+withLeadingSlash(url: string): string
+```
+
+**Parameters:**
+
+- `url: string` — The URL string to be processed. Can be `string`, `undefined`, or `null`.
+
+**Returns:** `string` — The URL string with a leading slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+
+```typescript
+import { withLeadingSlash } from '@helpers4/url';
+
+withLeadingSlash(url: undefined): undefined
+```
+
+**Parameters:**
+
+- `url: undefined` — The URL string to be processed. Can be `string`, `undefined`, or `null`.
+
+**Returns:** `undefined` — The URL string with a leading slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+
+```typescript
+import { withLeadingSlash } from '@helpers4/url';
+
+withLeadingSlash(url: null): null
+```
+
+**Parameters:**
+
+- `url: null` — The URL string to be processed. Can be `string`, `undefined`, or `null`.
+
+**Returns:** `null` — The URL string with a leading slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+
+**Examples:**
+
+*Add a leading slash*
+
+Ensures the URL starts with a forward slash.
+
+```typescript
+withLeadingSlash('path/to/resource')
+// => '/path/to/resource'
+```
+
+*Already has leading slash*
+
+Does not add a duplicate slash.
+
+```typescript
+withLeadingSlash('/already/has/slash')
+// => '/already/has/slash'
+```
+
+---
+
+### `withoutLeadingSlash`
+
+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.
+
+```typescript
+import { withoutLeadingSlash } from '@helpers4/url';
+
+withoutLeadingSlash(url: string): string
+```
+
+**Parameters:**
+
+- `url: string` — The URL string to be processed. Can be `string`, `undefined`, or `null`.
+
+**Returns:** `string` — The URL string without a leading slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+
+```typescript
+import { withoutLeadingSlash } from '@helpers4/url';
+
+withoutLeadingSlash(url: undefined): undefined
+```
+
+**Parameters:**
+
+- `url: undefined` — The URL string to be processed. Can be `string`, `undefined`, or `null`.
+
+**Returns:** `undefined` — The URL string without a leading slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+
+```typescript
+import { withoutLeadingSlash } from '@helpers4/url';
+
+withoutLeadingSlash(url: null): null
+```
+
+**Parameters:**
+
+- `url: null` — The URL string to be processed. Can be `string`, `undefined`, or `null`.
+
+**Returns:** `null` — The URL string without a leading slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+
+**Examples:**
+
+*Remove leading slash*
+
+Strips the leading slash from a URL path.
+
+```typescript
+withoutLeadingSlash('/path/to/resource')
+// => 'path/to/resource'
+```
+
+---
+
+### `withoutTrailingSlash`
+
+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.
+
+```typescript
+import { withoutTrailingSlash } from '@helpers4/url';
+
+withoutTrailingSlash(url: string): string
+```
+
+**Parameters:**
+
+- `url: string` — The URL string to be processed. Can be `string`, `undefined`, or `null`.
+
+**Returns:** `string` — The URL string without a trailing slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+
+```typescript
+import { withoutTrailingSlash } from '@helpers4/url';
+
+withoutTrailingSlash(url: undefined): undefined
+```
+
+**Parameters:**
+
+- `url: undefined` — The URL string to be processed. Can be `string`, `undefined`, or `null`.
+
+**Returns:** `undefined` — The URL string without a trailing slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+
+```typescript
+import { withoutTrailingSlash } from '@helpers4/url';
+
+withoutTrailingSlash(url: null): null
+```
+
+**Parameters:**
+
+- `url: null` — The URL string to be processed. Can be `string`, `undefined`, or `null`.
+
+**Returns:** `null` — The URL string without a trailing slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+
+**Examples:**
+
+*Remove trailing slash*
+
+Strips the trailing slash from a URL path.
+
+```typescript
+withoutTrailingSlash('path/to/resource/')
+// => 'path/to/resource'
+```
+
+---
+
+### `withTrailingSlash`
+
+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.
+
+```typescript
+import { withTrailingSlash } from '@helpers4/url';
+
+withTrailingSlash(url: string): string
+```
+
+**Parameters:**
+
+- `url: string` — The URL string to be processed. Can be `string`, `undefined`, or `null`.
+
+**Returns:** `string` — The URL string with a trailing slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+
+```typescript
+import { withTrailingSlash } from '@helpers4/url';
+
+withTrailingSlash(url: undefined): undefined
+```
+
+**Parameters:**
+
+- `url: undefined` — The URL string to be processed. Can be `string`, `undefined`, or `null`.
+
+**Returns:** `undefined` — The URL string with a trailing slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+
+```typescript
+import { withTrailingSlash } from '@helpers4/url';
+
+withTrailingSlash(url: null): null
+```
+
+**Parameters:**
+
+- `url: null` — The URL string to be processed. Can be `string`, `undefined`, or `null`.
+
+**Returns:** `null` — The URL string with a trailing slash, or `undefined` if the input is `undefined`, or `null` if the input is `null`.
+
+**Examples:**
+
+*Add a trailing slash*
+
+Ensures the URL ends with a forward slash.
+
+```typescript
+withTrailingSlash('path/to/resource')
+// => 'path/to/resource/'
+```
+
+---

package/meta/api.json

@@ -1,6 +1,6 @@
 {
   "category": "url",
-  "version": "2.0.0-alpha.11",
+  "version": "2.0.0-alpha.15",
   "functions": [
     {
       "name": "cleanPath",

package/meta/category.json

@@ -0,0 +1,6 @@
+{
+  "category": "url",
+  "label": "URL",
+  "smallDescription": "URL parsing and manipulation utilities",
+  "description": "Utilities for working with URLs including path cleaning, slash management, and URL transformation"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helpers4/url",
-  "version": "2.0.0-alpha.11",
+  "version": "2.0.0-alpha.15",
   "description": "A set of helpers in TS/JS, compatible with tree-shaking, for url.",
   "author": "baxyz <baxy@etik.com>",
   "license": "LGPL-3.0",
@@ -21,6 +21,7 @@
     "./meta/api.json": "./meta/api.json",
     "./meta/examples.json": "./meta/examples.json",
     "./meta/licenses.json": "./meta/licenses.json",
+    "./llms.txt": "./llms.txt",
     "./package.json": "./package.json"
   },
   "keywords": [
@@ -40,6 +41,7 @@
     "lib/index.d.ts",
     "lib/index.js.map",
     "meta/",
+    "llms.txt",
     "LICENSE.md",
     "package.json",
     "README.md"