feat: add url/onlyPath

Author: baxyz

benchmarks/url/onlyPath.bench.ts

@@ -0,0 +1,22 @@
+import { onlyPath } from 'radashi'
+
+describe('onlyPath', () => {
+  bench('with no input', () => {
+    onlyPath(undefined)
+  })
+  bench('with empty string', () => {
+    onlyPath('')
+  })
+  bench('with path only', () => {
+    onlyPath('/some/path')
+  })
+  bench('with path and query', () => {
+    onlyPath('/some/path?query=thing')
+  })
+  bench('with path and fragment', () => {
+    onlyPath('/some/path#fragment')
+  })
+  bench('with path, query, and fragment', () => {
+    onlyPath('/some/path?query=thing#fragment')
+  })
+})

docs/url/onlyPath.mdx

@@ -0,0 +1,26 @@
+---
+title: onlyPath
+description: Extract only the path
+---
+
+### Usage
+
+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`
+
+```ts
+import { onlyPath } from 'radashi'
+
+onlyPath('/path') // => '/path'
+onlyPath('/path?query=thing') // => '/path'
+onlyPath('/path#fragment') // => '/path'
+onlyPath('/path?query=thing#fragment') // => '/path'
+onlyPath(undefined) // => undefined
+onlyPath(null) // => null
+```

src/mod.ts

@@ -142,6 +142,7 @@ export * from './typed/isUndefined.ts'
 export * from './typed/isWeakMap.ts'
 export * from './typed/isWeakSet.ts'
 
+export * from './url/onlyPath.ts'
 export * from './url/withLeadingSlash.ts'
 export * from './url/withoutLeadingSlash.ts'
 export * from './url/withoutTrailingSlash.ts'

src/url/onlyPath.ts

@@ -0,0 +1,103 @@
+/**
+ * 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
+ * ```
+ */
+export 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
+ * ```
+ */
+export 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
+ * ```
+ */
+export function onlyPath(url: undefined): undefined
+
+/**
+ * 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
+ * ```
+ */
+export function onlyPath(
+  url: string | undefined | null,
+): string | undefined | null {
+  if (url === undefined || url === null) {
+    return url
+  }
+  const [path] = url.split(/[?#]/)
+  return path
+}

tests/url/onlyPath.test.ts

@@ -0,0 +1,22 @@
+import { onlyPath } from 'radashi'
+
+describe('onlyPath', () => {
+  test('should return the path without query and fragment', () => {
+    expect(onlyPath('/path')).toBe('/path')
+  })
+  test('should return the path without query and fragment when query is present', () => {
+    expect(onlyPath('/path?query=thing')).toBe('/path')
+  })
+  test('should return the path without query and fragment when fragment is present', () => {
+    expect(onlyPath('/path#fragment')).toBe('/path')
+  })
+  test('should return the path without query and fragment when both query and fragment are present', () => {
+    expect(onlyPath('/path?query=thing#fragment')).toBe('/path')
+  })
+  test('should return undefined if input is undefined', () => {
+    expect(onlyPath(undefined)).toBe(undefined)
+  })
+  test('should return null if input is null', () => {
+    expect(onlyPath(null)).toBe(null)
+  })
+})