@helpers4/url 2.0.0-alpha.10 → 2.0.0-alpha.14

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.14
+> 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.10",
+  "version": "2.0.0-alpha.14",
   "functions": [
     {
       "name": "cleanPath",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helpers4/url",
-  "version": "2.0.0-alpha.10",
+  "version": "2.0.0-alpha.14",
   "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"