@helpers4/url 2.0.0-alpha.2 → 2.0.0-alpha.6

package/README.md

@@ -12,13 +12,13 @@ A set of helpers for working with URLs.
 [https://helpers4.js.org/url](https://helpers4.js.org/url)
 
 <!-- AUTOMATIC-METHODS -->
-- withTrailingSlash
-- withoutLeadingSlash
 - cleanPath
-- relativeURLToAbsolute
-- withLeadingSlash
 - 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/api.json

@@ -0,0 +1,135 @@
+{
+  "category": "url",
+  "members": [
+    {
+      "name": "cleanPath",
+      "kind": "function",
+      "description": "Clean an URL by removing duplicate slashes.\nThe protocol part of the URL is not modified.",
+      "signature": "cleanPath(url: string | null | undefined): string | null | undefined",
+      "params": [
+        {
+          "name": "url",
+          "type": "string | null | undefined",
+          "description": "The URL string to be processed. Can be `string`, `undefined`, or `null`."
+        }
+      ],
+      "returns": "string | null | undefined",
+      "examples": [
+        "```ts\ncleanPath('/path//to///resource') // => '/path/to/resource'\ncleanPath('http://example.com//path//to///resource') // => 'http://example.com/path/to/resource'\ncleanPath(undefined) // => undefined\ncleanPath(null) // => null\n```"
+      ]
+    },
+    {
+      "name": "extractPureURI",
+      "kind": "function",
+      "description": "Extracts the pure URI from a URL by removing query parameters and fragments.",
+      "signature": "extractPureURI(url: string): string",
+      "params": [
+        {
+          "name": "url",
+          "type": "string",
+          "description": "The URL string to process"
+        }
+      ],
+      "returns": "string"
+    },
+    {
+      "name": "onlyPath",
+      "kind": "function",
+      "description": "Extract only the path from an URI with optional query and fragments.\n\nFor example, all these parameters will return `/path`:\n - `/path`\n - `/path?query=thing`\n - `/path#fragment`\n - `/path?query=thing#fragment`",
+      "signature": "onlyPath(url: string): string",
+      "params": [
+        {
+          "name": "url",
+          "type": "string",
+          "description": "The URL string to be processed. Can be `string`, `undefined`, or `null`."
+        }
+      ],
+      "returns": "string",
+      "examples": [
+        "```ts\nonlyPath('/path') // => '/path'\nonlyPath('/path?query=thing') // => '/path'\nonlyPath('/path#fragment') // => '/path'\nonlyPath('/path?query=thing#fragment') // => '/path'\nonlyPath(undefined) // => undefined\nonlyPath(null) // => null\n```"
+      ]
+    },
+    {
+      "name": "relativeURLToAbsolute",
+      "kind": "function",
+      "description": "",
+      "signature": "relativeURLToAbsolute(relativeUrl: string): string",
+      "params": [
+        {
+          "name": "relativeUrl",
+          "type": "string",
+          "description": ""
+        }
+      ],
+      "returns": "string"
+    },
+    {
+      "name": "withLeadingSlash",
+      "kind": "function",
+      "description": "Adds a leading slash `/` to the given URL if it is not already present.\n\nThis function is useful for ensuring that URLs are properly formatted\nwith a leading slash, which is often required in web development for\nconsistency and to avoid issues with relative paths.",
+      "signature": "withLeadingSlash(url: string): string",
+      "params": [
+        {
+          "name": "url",
+          "type": "string",
+          "description": "The URL string to be processed. Can be `string`, `undefined`, or `null`."
+        }
+      ],
+      "returns": "string",
+      "examples": [
+        "```ts\nwithLeadingSlash('') // => '/'\nwithLeadingSlash('no/slash') // => '/no/slash'\nwithLeadingSlash('/already/has/slash') // => '/already/has/slash'\nwithLeadingSlash(undefined) // => undefined\nwithLeadingSlash(null) // => null\n```"
+      ]
+    },
+    {
+      "name": "withoutLeadingSlash",
+      "kind": "function",
+      "description": "Removes the leading slash `/` from the given URL if it is present.\n\nThis function is useful for ensuring that URLs are properly formatted\nwithout a leading slash, which is often required in web development for\nconsistency and to avoid issues with relative paths.",
+      "signature": "withoutLeadingSlash(url: string): string",
+      "params": [
+        {
+          "name": "url",
+          "type": "string",
+          "description": "The URL string to be processed. Can be `string`, `undefined`, or `null`."
+        }
+      ],
+      "returns": "string",
+      "examples": [
+        "```ts\nwithoutLeadingSlash('') // => ''\nwithoutLeadingSlash('/') // => ''\nwithoutLeadingSlash('/no/slash') // => 'no/slash'\nwithoutLeadingSlash('already/has/slash') // => 'already/has/slash'\nwithoutLeadingSlash(undefined) // => undefined\nwithoutLeadingSlash(null) // => null\n```"
+      ]
+    },
+    {
+      "name": "withoutTrailingSlash",
+      "kind": "function",
+      "description": "Removes the trailing slash `/` from the given URL if it is present.\n\nThis function is useful for ensuring that URLs are properly formatted\nwithout a trailing slash, which is often required in web development for\nconsistency and to avoid issues with relative paths.",
+      "signature": "withoutTrailingSlash(url: string): string",
+      "params": [
+        {
+          "name": "url",
+          "type": "string",
+          "description": "The URL string to be processed. Can be `string`, `undefined`, or `null`."
+        }
+      ],
+      "returns": "string",
+      "examples": [
+        "```ts\nwithoutTrailingSlash('') // => ''\nwithoutTrailingSlash('/') // => ''\nwithoutTrailingSlash('no/slash/') // => 'no/slash'\nwithoutTrailingSlash('already/has/slash') // => 'already/has/slash'\nwithoutTrailingSlash(undefined) // => undefined\nwithoutTrailingSlash(null) // => null\n```"
+      ]
+    },
+    {
+      "name": "withTrailingSlash",
+      "kind": "function",
+      "description": "Adds a trailing slash `/` to the given URL if it is not already present.\n\nThis function is useful for ensuring that URLs are properly formatted\nwith a trailing slash, which is often required in web development for\nconsistency and to avoid issues with relative paths.",
+      "signature": "withTrailingSlash(url: string): string",
+      "params": [
+        {
+          "name": "url",
+          "type": "string",
+          "description": "The URL string to be processed. Can be `string`, `undefined`, or `null`."
+        }
+      ],
+      "returns": "string",
+      "examples": [
+        "```ts\nwithTrailingSlash('') // => '/'\nwithTrailingSlash('no/slash') // => 'no/slash/'\nwithTrailingSlash('already/has/slash/') // => 'already/has/slash/'\nwithTrailingSlash(undefined) // => undefined\nwithTrailingSlash(null) // => null\n```"
+      ]
+    }
+  ]
+}

package/examples.json

@@ -0,0 +1,100 @@
+{
+  "category": "url",
+  "helpers": [
+    {
+      "helper": "cleanPath",
+      "examples": [
+        {
+          "title": "Remove duplicate slashes",
+          "description": "Cleans an URL by removing duplicate slashes while preserving the protocol.",
+          "code": "cleanPath('/path//to///resource')\n// => '/path/to/resource'"
+        },
+        {
+          "title": "Preserve protocol",
+          "description": "The double slash after the protocol (http://) is not modified.",
+          "code": "cleanPath('http://example.com//path')\n// => 'http://example.com/path'"
+        },
+        {
+          "title": "Handle null and undefined",
+          "description": "Returns null for null input and undefined for undefined input.",
+          "code": "cleanPath(null)      // => null\ncleanPath(undefined) // => undefined"
+        }
+      ]
+    },
+    {
+      "helper": "extractPureURI",
+      "examples": [
+        {
+          "title": "Remove query parameters and fragments",
+          "description": "Strips everything after ? or # from the URL.",
+          "code": "extractPureURI('https://example.com/path?query=1#section')\n// => 'https://example.com/path'"
+        }
+      ]
+    },
+    {
+      "helper": "onlyPath",
+      "examples": [
+        {
+          "title": "Extract the path from a URL",
+          "description": "Strips query parameters and fragments from a URL path.",
+          "code": "onlyPath('/path?query=thing#fragment')\n// => '/path'"
+        }
+      ]
+    },
+    {
+      "helper": "relativeURLToAbsolute",
+      "examples": [
+        {
+          "title": "Convert a relative URL to absolute",
+          "description": "Prepends the base URI to a relative path, cleaning duplicate slashes.",
+          "code": "relativeURLToAbsolute('/api/data')\n// => 'http://localhost/api/data' (depends on document.baseURI)"
+        }
+      ]
+    },
+    {
+      "helper": "withLeadingSlash",
+      "examples": [
+        {
+          "title": "Add a leading slash",
+          "description": "Ensures the URL starts with a forward slash.",
+          "code": "withLeadingSlash('path/to/resource')\n// => '/path/to/resource'"
+        },
+        {
+          "title": "Already has leading slash",
+          "description": "Does not add a duplicate slash.",
+          "code": "withLeadingSlash('/already/has/slash')\n// => '/already/has/slash'"
+        }
+      ]
+    },
+    {
+      "helper": "withTrailingSlash",
+      "examples": [
+        {
+          "title": "Add a trailing slash",
+          "description": "Ensures the URL ends with a forward slash.",
+          "code": "withTrailingSlash('path/to/resource')\n// => 'path/to/resource/'"
+        }
+      ]
+    },
+    {
+      "helper": "withoutLeadingSlash",
+      "examples": [
+        {
+          "title": "Remove leading slash",
+          "description": "Strips the leading slash from a URL path.",
+          "code": "withoutLeadingSlash('/path/to/resource')\n// => 'path/to/resource'"
+        }
+      ]
+    },
+    {
+      "helper": "withoutTrailingSlash",
+      "examples": [
+        {
+          "title": "Remove trailing slash",
+          "description": "Strips the trailing slash from a URL path.",
+          "code": "withoutTrailingSlash('path/to/resource/')\n// => 'path/to/resource'"
+        }
+      ]
+    }
+  ]
+}