@helpers4/all 2.0.0-alpha.17 → 2.0.0-alpha.19

package/llms.txt

@@ -1,7 +1,7 @@
 # @helpers4/all
 
 > Complete collection of tree-shakable TypeScript utility functions.
-> Version: 2.0.0-alpha.17 — License: LGPL-3.0-or-later
+> Version: 2.0.0-alpha.19 — License: LGPL-3.0-or-later
 
 ## About
 
@@ -60,7 +60,6 @@ pnpm add @helpers4/version
 | `@helpers4/date` | `addYears` | Adds years to a date.  Returns a **new** `Date` — the original is never mutated. Returns `null` if t |
 | `@helpers4/date` | `clampDate` | Clamps a date to a [min, max] range.  Returns a **new** `Date` — the original is never mutated. Retu |
 | `@helpers4/date` | `compare` | Comparison of two dates.  Accepts any DateLike input (Date, timestamp, or date string). |
-| `@helpers4/date` | `DateCompareOptions` | Options for date comparison |
 | `@helpers4/date` | `DateDifferenceOptions` | Options for date difference calculation |
 | `@helpers4/date` | `DateLike` | A value that can be converted to a Date.  - `Date` — used as-is (validated for Invalid Date) - `numb |
 | `@helpers4/date` | `DateRange` | A date range represented as a pair of date-like values. |
@@ -76,7 +75,6 @@ pnpm add @helpers4/version
 | `@helpers4/date` | `ensureDate` | Safely converts a date-like value to a valid `Date` object, or returns `null`.  Accepts `Date`, time |
 | `@helpers4/date` | `EpochMilliseconds` | An object that exposes an epoch timestamp in milliseconds.  This structural type is satisfied by `Te |
 | `@helpers4/date` | `formatDuration` | Formats a duration in milliseconds as a compact human-readable string.  Produces output like `"1h 23 |
-| `@helpers4/date` | `FormatDurationOptions` | Options for formatDuration. |
 | `@helpers4/date` | `formatInTimezone` | Formats a date in a specific IANA timezone using `Intl.DateTimeFormat`.  Returns `null` if the date  |
 | `@helpers4/date` | `FormatInTimezoneOptions` | Options for formatInTimezone. |
 | `@helpers4/date` | `fromMillis` | Creates a `Date` from a timestamp in **milliseconds**.  Use this when receiving a timestamp from a J |
@@ -97,7 +95,6 @@ pnpm add @helpers4/version
 | `@helpers4/date` | `safeDate` | Safely creates a Date object from various input types. |
 | `@helpers4/date` | `startOf` | Returns a new `Date` set to the **start** of the given unit.  - `'day'`   — 00:00:00.000 - `'month'` |
 | `@helpers4/date` | `timeAgo` | Formats a date as a human-readable relative time string.  Uses `Intl.RelativeTimeFormat` under the h |
-| `@helpers4/date` | `TimeAgoOptions` | Options for timeAgo. |
 | `@helpers4/date` | `toISO8601` | Converts a date to ISO 8601 format Format: YYYY-MM-DDTHH:mm:ss.sssZ |
 | `@helpers4/date` | `toMillis` | Converts a date to a timestamp in **milliseconds** (epoch millis).  Use this when you need a plain n |
 | `@helpers4/date` | `toRFC2822` | Converts a date to RFC 2822 format Format: Day, DD Mon YYYY HH:mm:ss +0000 Used in email headers (Da |
@@ -113,6 +110,7 @@ pnpm add @helpers4/version
 | `@helpers4/function` | `throttle` | Creates a throttled function that only invokes func at most once per every wait milliseconds |
 | `@helpers4/math` | `uuid7` | Generates a UUID v7 string (RFC 9562). UUID v7 embeds a Unix timestamp in milliseconds, making it ch |
 | `@helpers4/number` | `clamp` | Clamps a number between min and max values |
+| `@helpers4/number` | `formatSize` | Format a byte count into a human-readable string with the appropriate unit.  Each unit is 1024 of th |
 | `@helpers4/number` | `randomBetween` | Generates a random number between min and max (inclusive) |
 | `@helpers4/number` | `randomIntBetween` | Generates a random integer between min and max (inclusive) |
 | `@helpers4/number` | `roundTo` | Rounds a number to specified decimal places |
@@ -120,7 +118,6 @@ pnpm add @helpers4/version
 | `@helpers4/object` | `compact` | Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `""`, `NaN`) from an objec |
 | `@helpers4/object` | `deepClone` | Creates a deep copy of an object or array |
 | `@helpers4/object` | `deepCompare` | Deep comparison of two objects that returns detailed information about differences. |
-| `@helpers4/object` | `DeepCompareResult` | Result type for deep comparison when objects are not identical |
 | `@helpers4/object` | `deepMerge` | Merges two or more objects deeply |
 | `@helpers4/object` | `get` | Gets a value from an object using a dot-notated path |
 | `@helpers4/object` | `omit` | Creates a new object without the specified keys. |
@@ -136,7 +133,6 @@ pnpm add @helpers4/version
 | `@helpers4/promise` | `guard` | Wraps a function so that if it throws, a default value is returned instead of propagating the error. |
 | `@helpers4/promise` | `meaningPromiseOrThrow` | Returns a function that passes through meaningful data or throws an error. Data is considered meanin |
 | `@helpers4/promise` | `parallel` | Runs an array of async functions with a concurrency limit. At most `limit` functions will be running |
-| `@helpers4/promise` | `Result` | Result tuple representing either a successful value or an error. On success: `[undefined, T]`. On er |
 | `@helpers4/promise` | `retry` | Retries a promise-returning function up to maxAttempts times |
 | `@helpers4/promise` | `timeout` | Wraps a promise to reject with a `TimeoutError` if it does not resolve within the specified duration |
 | `@helpers4/promise` | `truthyPromiseOrThrow` | Returns a function that passes through truthy data or throws an error. |
@@ -149,16 +145,19 @@ pnpm add @helpers4/version
 | `@helpers4/string` | `slugify` | Converts a string into a URL-friendly slug. |
 | `@helpers4/string` | `snakeCase` | Converts a string to snake_case. Handles camelCase, PascalCase, kebab-case, spaces, and mixed format |
 | `@helpers4/string` | `titleCase` | Converts a string to Title Case. Handles camelCase, PascalCase, kebab-case, snake_case, spaces, and  |
-| `@helpers4/type` | `Falsy` | Union of all falsy types in JavaScript. Note: `NaN` cannot be represented as a type in TypeScript. |
 | `@helpers4/type` | `isArray` | Checks if a value is an array. |
+| `@helpers4/type` | `isArrayBuffer` | Checks if a value is an ArrayBuffer instance.  Useful for filtering or type-narrowing in a functiona |
 | `@helpers4/type` | `isAsyncFunction` | Checks if a value is an async function.  Returns `true` for any function declared with `async`. |
 | `@helpers4/type` | `isBigInt` | Checks if a value is a bigint. |
+| `@helpers4/type` | `isBlob` | Checks if a value is a Blob instance.  Useful for filtering or type-narrowing in a functional pipeli |
 | `@helpers4/type` | `isBoolean` | Checks if a value is a boolean. |
+| `@helpers4/type` | `isBuffer` | Checks if a value is a Node.js Buffer instance.  `Buffer` extends `Uint8Array` and is specific to No |
 | `@helpers4/type` | `isDate` | Checks if a value is a Date instance.  Note: this only checks the type, not whether the Date is vali |
 | `@helpers4/type` | `isDefined` | Checks if a value is defined (not undefined nor null). This is the inverse of isNullish.  Use as a t |
 | `@helpers4/type` | `isEmpty` | Checks if a value is empty.  Supported types: - `null` / `undefined` → empty - `string` → length === |
 | `@helpers4/type` | `isError` | Checks if a value is an Error instance. |
 | `@helpers4/type` | `isFalsy` | Checks if a value is falsy (`false`, `null`, `undefined`, `0`, `""`, `NaN`). |
+| `@helpers4/type` | `isFormData` | Checks if a value is a FormData instance.  Useful for filtering or type-narrowing in a functional pi |
 | `@helpers4/type` | `isFunction` | Checks if a value is a function. |
 | `@helpers4/type` | `isIterable` | Checks if a value is iterable (has a `Symbol.iterator` method).  Returns `true` for strings, arrays, |
 | `@helpers4/type` | `isMap` | Checks if a value is a Map instance. |
@@ -187,10 +186,10 @@ pnpm add @helpers4/version
 | `@helpers4/type` | `isUndefined` | Checks if a value is `undefined`. |
 | `@helpers4/type` | `isValidDate` | Checks if a value is a valid Date instance (not `Invalid Date`).  Unlike isDate, this also verifies  |
 | `@helpers4/type` | `isValidRegex` | Checks if a string is a valid regex pattern. |
-| `@helpers4/type` | `Primitive` | Union of all JavaScript primitive types. |
 | `@helpers4/url` | `cleanPath` | Clean an URL by removing duplicate slashes. The protocol part of the URL is not modified. |
 | `@helpers4/url` | `extractPureURI` | Extracts the pure URI from a URL by removing query parameters and fragments. |
 | `@helpers4/url` | `onlyPath` | Extract only the path from an URI with optional query and fragments.  For example, all these paramet |
+| `@helpers4/url` | `parsePackageRepository` | Parse the `repository` field from `package.json` into a structured object.  Supports all npm-specifi |
 | `@helpers4/url` | `relativeURLToAbsolute` | Converts a relative URL to an absolute URL using the current document base URI. |
 | `@helpers4/url` | `withLeadingSlash` | Adds a leading slash `/` to the given URL if it is not already present.  This function is useful for |
 | `@helpers4/url` | `withoutLeadingSlash` | Removes the leading slash `/` from the given URL if it is present.  This function is useful for ensu |
@@ -198,9 +197,10 @@ pnpm add @helpers4/version
 | `@helpers4/url` | `withTrailingSlash` | Adds a trailing slash `/` to the given URL if it is not already present.  This function is useful fo |
 | `@helpers4/version` | `compare` | Compares two semantic version strings according to SemVer 2.0.0 specification  Supports: - Core vers |
 | `@helpers4/version` | `increment` | Increments a semantic version |
+| `@helpers4/version` | `isPrerelease` | Returns `true` when the version string has a prerelease suffix (i.e. contains a `-` after the core ` |
 | `@helpers4/version` | `parse` | Parses a semantic version string into its components according to SemVer 2.0.0 specification  Suppor |
-| `@helpers4/version` | `ParsedVersion` | Represents a parsed semantic version according to SemVer 2.0.0 specification |
 | `@helpers4/version` | `satisfiesRange` | Checks if a version satisfies a range (simple implementation) |
+| `@helpers4/version` | `stringify` | Reconstruct a semantic version string from a ParsedVersion object.  This is the inverse of parse: `s |
 | `@helpers4/version` | `stripV` | Strip the leading "v" from a version string if it exists. |
 
 ---
@@ -1158,12 +1158,6 @@ compare(
 
 ---
 
-### `DateCompareOptions`
-
-Options for date comparison
-
----
-
 ### `DateDifferenceOptions`
 
 Options for date difference calculation
@@ -1526,12 +1520,6 @@ formatDuration(-5025000)          // => "-1h 23m 45s"
 
 ---
 
-### `FormatDurationOptions`
-
-Options for formatDuration.
-
----
-
 ### `formatInTimezone`
 
 Formats a date in a specific IANA timezone using `Intl.DateTimeFormat`.
@@ -2191,12 +2179,6 @@ timeAgo('2025-01-19T00:00:00Z', { now: '2025-01-19T00:00:05Z' })
 
 ---
 
-### `TimeAgoOptions`
-
-Options for timeAgo.
-
----
-
 ### `toISO8601`
 
 Converts a date to ISO 8601 format
@@ -2683,6 +2665,41 @@ clamp(5, 0, 10)   // => 5
 
 ---
 
+### `formatSize`
+
+Format a byte count into a human-readable string with the appropriate unit.
+
+Each unit is 1024 of the previous (binary prefix). The result is formatted
+with one decimal place.
+
+```typescript
+import { formatSize } from '@helpers4/number';
+
+formatSize(bytes: number): string
+```
+
+**Parameters:**
+
+- `bytes: number` — A non-negative integer representing a byte count.
+
+**Returns:** `string` — A human-readable string such as `'0.0B'`, `'1.5KB'`, `'3.2MB'`.
+
+**Examples:**
+
+*Format bytes to human-readable size*
+
+Converts a raw byte count to a human-readable string using binary prefixes.
+
+```typescript
+formatSize(0)             // '0.0B'
+formatSize(512)           // '512.0B'
+formatSize(1024)          // '1.0KB'
+formatSize(1_048_576)     // '1.0MB'
+formatSize(1_073_741_824) // '1.0GB'
+```
+
+---
+
 ### `randomBetween`
 
 Generates a random number between min and max (inclusive)
@@ -2954,12 +2971,6 @@ deepCompare({ a: { b: 1 } }, { a: { b: 2 } })
 
 ---
 
-### `DeepCompareResult`
-
-Result type for deep comparison when objects are not identical
-
----
-
 ### `deepMerge`
 
 Merges two or more objects deeply
@@ -3644,13 +3655,6 @@ await parallel([fnA, fnB, fnC], 1)
 
 ---
 
-### `Result`
-
-Result tuple representing either a successful value or an error.
-On success: `[undefined, T]`. On error: `[Error, undefined]`.
-
----
-
 ### `retry`
 
 Retries a promise-returning function up to maxAttempts times
@@ -4293,13 +4297,6 @@ titleCase('queryItems')
 
 Package: `@helpers4/type`
 
-### `Falsy`
-
-Union of all falsy types in JavaScript.
-Note: `NaN` cannot be represented as a type in TypeScript.
-
----
-
 ### `isArray`
 
 Checks if a value is an array.
@@ -4307,14 +4304,14 @@ Checks if a value is an array.
 ```typescript
 import { isArray } from '@helpers4/type';
 
-isArray(value: unknown): value
+isArray(value: unknown): value is unknown[]
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is an array
+**Returns:** `value is unknown[]` — True if value is an array
 
 **Examples:**
 
@@ -4330,6 +4327,49 @@ isArray({})        // => false
 
 ---
 
+### `isArrayBuffer`
+
+Checks if a value is an ArrayBuffer instance.
+
+Useful for filtering or type-narrowing in a functional pipeline:
+`values.filter(isArrayBuffer)`
+
+```typescript
+import { isArrayBuffer } from '@helpers4/type';
+
+isArrayBuffer(value: unknown): value is ArrayBuffer
+```
+
+**Parameters:**
+
+- `value: unknown` — The value to check
+
+**Returns:** `value is ArrayBuffer` — True if value is an ArrayBuffer
+
+**Examples:**
+
+*Detect an ArrayBuffer*
+
+Returns true only for ArrayBuffer instances, not TypedArray views.
+
+```typescript
+isArrayBuffer(new ArrayBuffer(8)) // => true
+isArrayBuffer(new Uint8Array(8))  // => false
+isArrayBuffer('hello')            // => false
+```
+
+*Filter ArrayBuffers from a mixed array*
+
+Use as a predicate in .filter() to extract ArrayBuffer values.
+
+```typescript
+const values = [new ArrayBuffer(4), 'text', new ArrayBuffer(8), 42];
+values.filter(isArrayBuffer)
+// => [ArrayBuffer(4), ArrayBuffer(8)]
+```
+
+---
+
 ### `isAsyncFunction`
 
 Checks if a value is an async function.
@@ -4339,14 +4379,14 @@ Returns `true` for any function declared with `async`.
 ```typescript
 import { isAsyncFunction } from '@helpers4/type';
 
-isAsyncFunction(value: unknown): value
+isAsyncFunction(value: unknown): value is function
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is an async function
+**Returns:** `value is function` — True if value is an async function
 
 **Examples:**
 
@@ -4370,14 +4410,14 @@ Checks if a value is a bigint.
 ```typescript
 import { isBigInt } from '@helpers4/type';
 
-isBigInt(value: unknown): value
+isBigInt(value: unknown): value is bigint
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a bigint
+**Returns:** `value is bigint` — True if value is a bigint
 
 **Examples:**
 
@@ -4393,6 +4433,49 @@ isBigInt('42') // => false
 
 ---
 
+### `isBlob`
+
+Checks if a value is a Blob instance.
+
+Useful for filtering or type-narrowing in a functional pipeline:
+`values.filter(isBlob)`
+
+```typescript
+import { isBlob } from '@helpers4/type';
+
+isBlob(value: unknown): value is Blob
+```
+
+**Parameters:**
+
+- `value: unknown` — The value to check
+
+**Returns:** `value is Blob` — True if value is a Blob
+
+**Examples:**
+
+*Detect a Blob*
+
+Returns true only for Blob instances.
+
+```typescript
+isBlob(new Blob(['hello'])) // => true
+isBlob(new Blob([], { type: 'application/json' })) // => true
+isBlob('hello')             // => false
+```
+
+*Filter Blobs from a mixed array*
+
+Use as a predicate in .filter() to extract Blob values.
+
+```typescript
+const values = [new Blob(['a']), 'text', new Blob(['b']), 42];
+values.filter(isBlob)
+// => [Blob, Blob]
+```
+
+---
+
 ### `isBoolean`
 
 Checks if a value is a boolean.
@@ -4400,14 +4483,14 @@ Checks if a value is a boolean.
 ```typescript
 import { isBoolean } from '@helpers4/type';
 
-isBoolean(value: unknown): value
+isBoolean(value: unknown): value is boolean
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a boolean
+**Returns:** `value is boolean` — True if value is a boolean
 
 **Examples:**
 
@@ -4423,6 +4506,53 @@ isBoolean(1)     // => false
 
 ---
 
+### `isBuffer`
+
+Checks if a value is a Node.js Buffer instance.
+
+`Buffer` extends `Uint8Array` and is specific to Node.js, Bun, and Deno.
+In browser-only environments where `Buffer` is not defined, this function
+always returns `false`.
+
+Useful for filtering or type-narrowing in a functional pipeline:
+`values.filter(isBuffer)`
+
+```typescript
+import { isBuffer } from '@helpers4/type';
+
+isBuffer(value: unknown): value is Buffer<ArrayBufferLike>
+```
+
+**Parameters:**
+
+- `value: unknown` — The value to check
+
+**Returns:** `value is Buffer<ArrayBufferLike>` — True if value is a Buffer
+
+**Examples:**
+
+*Detect a Node.js Buffer*
+
+Returns true only for Buffer instances. Uint8Array is not a Buffer.
+
+```typescript
+isBuffer(Buffer.from('hello')) // => true
+isBuffer(new Uint8Array(8))    // => false
+isBuffer('hello')              // => false
+```
+
+*Filter Buffers from a mixed array*
+
+Use as a predicate in .filter() to extract Buffer values.
+
+```typescript
+const values = [Buffer.from('a'), 'text', Buffer.alloc(4), 42];
+values.filter(isBuffer)
+// => [Buffer, Buffer]
+```
+
+---
+
 ### `isDate`
 
 Checks if a value is a Date instance.
@@ -4433,14 +4563,14 @@ Use isValidDate to also validate that the Date is not `Invalid Date`.
 ```typescript
 import { isDate } from '@helpers4/type';
 
-isDate(value: unknown): value
+isDate(value: unknown): value is Date
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a Date instance
+**Returns:** `value is Date` — True if value is a Date instance
 
 **Examples:**
 
@@ -4467,14 +4597,14 @@ Use as a type-safe filter callback to remove `null`/`undefined` from arrays.
 ```typescript
 import { isDefined } from '@helpers4/type';
 
-isDefined<T>(value: Maybe<T>): value
+isDefined<T>(value: Maybe<T>): value is T
 ```
 
 **Parameters:**
 
 - `value: Maybe<T>` — The value to check
 
-**Returns:** `value` — True if value is not undefined nor null
+**Returns:** `value is T` — True if value is not undefined nor null
 
 **Examples:**
 
@@ -4557,14 +4687,14 @@ Checks if a value is an Error instance.
 ```typescript
 import { isError } from '@helpers4/type';
 
-isError(value: unknown): value
+isError(value: unknown): value is Error
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is an Error (or subclass like TypeError, RangeError, etc.)
+**Returns:** `value is Error` — True if value is an Error (or subclass like TypeError, RangeError, etc.)
 
 **Examples:**
 
@@ -4587,14 +4717,14 @@ Checks if a value is falsy (`false`, `null`, `undefined`, `0`, `""`, `NaN`).
 ```typescript
 import { isFalsy } from '@helpers4/type';
 
-isFalsy(value: unknown): value
+isFalsy(value: unknown): value is Falsy
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if the value is falsy
+**Returns:** `value is Falsy` — True if the value is falsy
 
 **Examples:**
 
@@ -4611,6 +4741,51 @@ isFalsy('hello')   // => false
 
 ---
 
+### `isFormData`
+
+Checks if a value is a FormData instance.
+
+Useful for filtering or type-narrowing in a functional pipeline:
+`values.filter(isFormData)`
+
+```typescript
+import { isFormData } from '@helpers4/type';
+
+isFormData(value: unknown): value is FormData
+```
+
+**Parameters:**
+
+- `value: unknown` — The value to check
+
+**Returns:** `value is FormData` — True if value is a FormData
+
+**Examples:**
+
+*Detect a FormData*
+
+Returns true only for FormData instances.
+
+```typescript
+isFormData(new FormData()) // => true
+isFormData({})             // => false
+isFormData(null)           // => false
+```
+
+*Filter FormData from a mixed array*
+
+Use as a predicate in .filter() to extract FormData values.
+
+```typescript
+const fd = new FormData();
+fd.append('name', 'Alice');
+const values = [fd, {}, new FormData(), 'text'];
+values.filter(isFormData)
+// => [FormData, FormData]
+```
+
+---
+
 ### `isFunction`
 
 Checks if a value is a function.
@@ -4618,14 +4793,14 @@ Checks if a value is a function.
 ```typescript
 import { isFunction } from '@helpers4/type';
 
-isFunction(value: unknown): value
+isFunction(value: unknown): value is Function
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a function
+**Returns:** `value is Function` — True if value is a function
 
 **Examples:**
 
@@ -4651,14 +4826,14 @@ implementing the iterable protocol.
 ```typescript
 import { isIterable } from '@helpers4/type';
 
-isIterable(value: unknown): value
+isIterable(value: unknown): value is Iterable<unknown, any, any>
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is iterable
+**Returns:** `value is Iterable<unknown, any, any>` — True if value is iterable
 
 **Examples:**
 
@@ -4684,14 +4859,14 @@ Checks if a value is a Map instance.
 ```typescript
 import { isMap } from '@helpers4/type';
 
-isMap(value: unknown): value
+isMap(value: unknown): value is Map<unknown, unknown>
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a Map
+**Returns:** `value is Map<unknown, unknown>` — True if value is a Map
 
 **Examples:**
 
@@ -4716,14 +4891,14 @@ Returns `false` for `NaN`, `0`, positive numbers, and non-number types.
 ```typescript
 import { isNegativeNumber } from '@helpers4/type';
 
-isNegativeNumber(value: unknown): value
+isNegativeNumber(value: unknown): value is number
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a negative number
+**Returns:** `value is number` — True if value is a negative number
 
 **Examples:**
 
@@ -4748,14 +4923,14 @@ Checks if a value is a non-empty array (length > 0).
 ```typescript
 import { isNonEmptyArray } from '@helpers4/type';
 
-isNonEmptyArray(value: unknown): value
+isNonEmptyArray(value: unknown): value is [unknown, rest]
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is an array with at least one element
+**Returns:** `value is [unknown, rest]` — True if value is an array with at least one element
 
 **Examples:**
 
@@ -4779,14 +4954,14 @@ Checks if a value is a non-empty string (length > 0).
 ```typescript
 import { isNonEmptyString } from '@helpers4/type';
 
-isNonEmptyString(value: unknown): value
+isNonEmptyString(value: unknown): value is string
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a string with at least one character
+**Returns:** `value is string` — True if value is a string with at least one character
 
 **Examples:**
 
@@ -4810,14 +4985,14 @@ Checks if a value is `null`.
 ```typescript
 import { isNull } from '@helpers4/type';
 
-isNull(value: unknown): value
+isNull(value: unknown): value is null
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is null
+**Returns:** `value is null` — True if value is null
 
 **Examples:**
 
@@ -4840,14 +5015,14 @@ Checks if a value is null or undefined (nullish).
 ```typescript
 import { isNullish } from '@helpers4/type';
 
-isNullish(value: unknown): value
+isNullish(value: unknown): value is null | undefined
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is null or undefined
+**Returns:** `value is null | undefined` — True if value is null or undefined
 
 **Examples:**
 
@@ -4886,14 +5061,14 @@ to increase user-friendliness.
 ```typescript
 import { isNumber } from '@helpers4/type';
 
-isNumber(value: unknown): value
+isNumber(value: unknown): value is number
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a number (excludes NaN)
+**Returns:** `value is number` — True if value is a number (excludes NaN)
 
 **Examples:**
 
@@ -4920,14 +5095,14 @@ Returns `false` for arrays, Date, Map, Set, RegExp, class instances, etc.
 ```typescript
 import { isPlainObject } from '@helpers4/type';
 
-isPlainObject(value: unknown): value
+isPlainObject(value: unknown): value is Record<string, unknown>
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a plain object
+**Returns:** `value is Record<string, unknown>` — True if value is a plain object
 
 **Examples:**
 
@@ -4954,14 +5129,14 @@ Returns `false` for `NaN`, `0`, negative numbers, and non-number types.
 ```typescript
 import { isPositiveNumber } from '@helpers4/type';
 
-isPositiveNumber(value: unknown): value
+isPositiveNumber(value: unknown): value is number
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a positive number
+**Returns:** `value is number` — True if value is a positive number
 
 **Examples:**
 
@@ -4988,14 +5163,14 @@ Primitive types: `string`, `number`, `boolean`, `bigint`, `symbol`, `null`, `und
 ```typescript
 import { isPrimitive } from '@helpers4/type';
 
-isPrimitive(value: unknown): value
+isPrimitive(value: unknown): value is Primitive
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a primitive
+**Returns:** `value is Primitive` — True if value is a primitive
 
 **Examples:**
 
@@ -5023,14 +5198,14 @@ including native Promises and userland implementations.
 ```typescript
 import { isPromise } from '@helpers4/type';
 
-isPromise(value: unknown): value
+isPromise(value: unknown): value is PromiseLike<unknown>
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a Promise-like object
+**Returns:** `value is PromiseLike<unknown>` — True if value is a Promise-like object
 
 **Examples:**
 
@@ -5054,14 +5229,14 @@ Checks if a value is a RegExp instance.
 ```typescript
 import { isRegExp } from '@helpers4/type';
 
-isRegExp(value: unknown): value
+isRegExp(value: unknown): value is RegExp
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a RegExp
+**Returns:** `value is RegExp` — True if value is a RegExp
 
 **Examples:**
 
@@ -5124,14 +5299,14 @@ Checks if a value is a string.
 ```typescript
 import { isString } from '@helpers4/type';
 
-isString(value: unknown): value
+isString(value: unknown): value is string
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a string
+**Returns:** `value is string` — True if value is a string
 
 **Examples:**
 
@@ -5153,14 +5328,14 @@ Checks if a value is a symbol.
 ```typescript
 import { isSymbol } from '@helpers4/type';
 
-isSymbol(value: unknown): value
+isSymbol(value: unknown): value is symbol
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a symbol
+**Returns:** `value is symbol` — True if value is a symbol
 
 **Examples:**
 
@@ -5186,14 +5361,14 @@ to `Symbol.toStringTag` for environments without Temporal (e.g. browsers).
 ```typescript
 import { isTemporalDuration } from '@helpers4/type';
 
-isTemporalDuration(value: unknown): value
+isTemporalDuration(value: unknown): value is Duration
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a `Temporal.Duration`
+**Returns:** `value is Duration` — True if value is a `Temporal.Duration`
 
 **Examples:**
 
@@ -5219,14 +5394,14 @@ to `Symbol.toStringTag` for environments without Temporal (e.g. browsers).
 ```typescript
 import { isTemporalInstant } from '@helpers4/type';
 
-isTemporalInstant(value: unknown): value
+isTemporalInstant(value: unknown): value is Instant
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a `Temporal.Instant`
+**Returns:** `value is Instant` — True if value is a `Temporal.Instant`
 
 **Examples:**
 
@@ -5252,14 +5427,14 @@ to `Symbol.toStringTag` for environments without Temporal (e.g. browsers).
 ```typescript
 import { isTemporalPlainDate } from '@helpers4/type';
 
-isTemporalPlainDate(value: unknown): value
+isTemporalPlainDate(value: unknown): value is PlainDate
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a `Temporal.PlainDate`
+**Returns:** `value is PlainDate` — True if value is a `Temporal.PlainDate`
 
 **Examples:**
 
@@ -5285,14 +5460,14 @@ to `Symbol.toStringTag` for environments without Temporal (e.g. browsers).
 ```typescript
 import { isTemporalPlainDateTime } from '@helpers4/type';
 
-isTemporalPlainDateTime(value: unknown): value
+isTemporalPlainDateTime(value: unknown): value is PlainDateTime
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a `Temporal.PlainDateTime`
+**Returns:** `value is PlainDateTime` — True if value is a `Temporal.PlainDateTime`
 
 **Examples:**
 
@@ -5318,14 +5493,14 @@ to `Symbol.toStringTag` for environments without Temporal (e.g. browsers).
 ```typescript
 import { isTemporalPlainTime } from '@helpers4/type';
 
-isTemporalPlainTime(value: unknown): value
+isTemporalPlainTime(value: unknown): value is PlainTime
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a `Temporal.PlainTime`
+**Returns:** `value is PlainTime` — True if value is a `Temporal.PlainTime`
 
 **Examples:**
 
@@ -5351,14 +5526,14 @@ to `Symbol.toStringTag` for environments without Temporal (e.g. browsers).
 ```typescript
 import { isTemporalZonedDateTime } from '@helpers4/type';
 
-isTemporalZonedDateTime(value: unknown): value
+isTemporalZonedDateTime(value: unknown): value is ZonedDateTime
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a `Temporal.ZonedDateTime`
+**Returns:** `value is ZonedDateTime` — True if value is a `Temporal.ZonedDateTime`
 
 **Examples:**
 
@@ -5388,14 +5563,14 @@ numbers ≤ ~7.26 billion are treated as seconds, larger as milliseconds.
 ```typescript
 import { isTimestamp } from '@helpers4/type';
 
-isTimestamp(value: unknown): value
+isTimestamp(value: unknown): value is number
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a number that represents a valid timestamp
+**Returns:** `value is number` — True if value is a number that represents a valid timestamp
 
 **Examples:**
 
@@ -5424,14 +5599,14 @@ resulting array type by excluding falsy values.
 ```typescript
 import { isTruthy } from '@helpers4/type';
 
-isTruthy<T>(value: Falsy | T): value
+isTruthy<T>(value: Falsy | T): value is T
 ```
 
 **Parameters:**
 
 - `value: Falsy | T` — The value to check
 
-**Returns:** `value` — True if the value is truthy
+**Returns:** `value is T` — True if the value is truthy
 
 **Examples:**
 
@@ -5465,14 +5640,14 @@ Checks if a value is `undefined`.
 ```typescript
 import { isUndefined } from '@helpers4/type';
 
-isUndefined(value: unknown): value
+isUndefined(value: unknown): value is undefined
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is undefined
+**Returns:** `value is undefined` — True if value is undefined
 
 **Examples:**
 
@@ -5497,14 +5672,14 @@ Unlike isDate, this also verifies that the internal timestamp is not `NaN`.
 ```typescript
 import { isValidDate } from '@helpers4/type';
 
-isValidDate(value: unknown): value
+isValidDate(value: unknown): value is Date
 ```
 
 **Parameters:**
 
 - `value: unknown` — The value to check
 
-**Returns:** `value` — True if value is a Date instance with a valid time value
+**Returns:** `value is Date` — True if value is a Date instance with a valid time value
 
 **Examples:**
 
@@ -5550,12 +5725,6 @@ isValidRegex('[')      // => false
 
 ---
 
-### `Primitive`
-
-Union of all JavaScript primitive types.
-
----
-
 ## url
 
 Package: `@helpers4/url`
@@ -5720,6 +5889,62 @@ onlyPath('/path?query=thing#fragment')
 
 ---
 
+### `parsePackageRepository`
+
+Parse the `repository` field from `package.json` into a structured object.
+
+Supports all npm-specified formats:
+- **Object form**: `{ "type": "git", "url": "...", "directory": "..." }`
+- **GitHub shorthand**: `"owner/repo"` or `"github:owner/repo"`
+- **Platform shorthands**: `"gitlab:owner/repo"`, `"bitbucket:owner/repo"`
+- **Gist shorthand**: `"gist:<id>"`
+- **URL forms**: `git+https://`, `https://`, `git://`, `git@` SSH, `git+ssh://`
+
+Returns `undefined` for `null`, `undefined`, arrays, or values that cannot
+be matched to any recognised format.
+
+```typescript
+import { parsePackageRepository } from '@helpers4/url';
+
+parsePackageRepository(repository: unknown): PackageRepository | undefined
+```
+
+**Parameters:**
+
+- `repository: unknown` — The `repository` field value from `package.json`.
+
+**Returns:** `PackageRepository | undefined` — A parsed PackageRepository object, or `undefined` if the
+  input cannot be parsed.
+
+**Examples:**
+
+*Parse the npm canonical object form*
+
+Parses the full object form written by npm publish.
+
+```typescript
+parsePackageRepository({ type: 'git', url: 'git+https://github.com/helpers4/typescript.git' })
+// => { type: 'git', host: 'github', slug: 'helpers4/typescript',
+//      owner: 'helpers4', repo: 'typescript', gistId: undefined, directory: undefined }
+```
+
+*Parse npm shorthand forms*
+
+npm accepts "owner/repo", "github:owner/repo", "gitlab:owner/repo" etc. as shorthand.
+
+```typescript
+parsePackageRepository('helpers4/typescript')
+// => { host: 'github', slug: 'helpers4/typescript', owner: 'helpers4', repo: 'typescript', ... }
+
+parsePackageRepository('gitlab:myorg/myproject')
+// => { host: 'gitlab', slug: 'myorg/myproject', owner: 'myorg', repo: 'myproject', ... }
+
+parsePackageRepository('gist:11081aaa281')
+// => { host: 'gist', gistId: '11081aaa281', slug: undefined, owner: undefined, ... }
+```
+
+---
+
 ### `relativeURLToAbsolute`
 
 Converts a relative URL to an absolute URL using the current document base URI.
@@ -6110,6 +6335,90 @@ increment('v1.0.0', 'major')
 
 ---
 
+### `isPrerelease`
+
+Returns `true` when the version string has a prerelease suffix
+(i.e. contains a `-` after the core `MAJOR.MINOR.PATCH`).
+
+```typescript
+import { isPrerelease } from '@helpers4/version';
+
+isPrerelease(version: string): boolean
+```
+
+**Parameters:**
+
+- `version: string` — A semantic version string (e.g. `'2.0.0-alpha.1'`, `'1.0.0'`).
+
+**Returns:** `boolean` — `true` if the version is a prerelease, `false` otherwise.
+
+```typescript
+import { isPrerelease } from '@helpers4/version';
+
+isPrerelease(version: ParsedVersion): boolean
+```
+
+**Parameters:**
+
+- `version: ParsedVersion` — A ParsedVersion object (as returned by parse).
+
+**Returns:** `boolean` — `true` if `version.prerelease` is non-empty, `false` otherwise.
+
+```typescript
+import { isPrerelease } from '@helpers4/version';
+
+isPrerelease(version: undefined): undefined
+```
+
+**Parameters:**
+
+- `version: undefined` — A semantic version string (e.g. `'2.0.0-alpha.1'`, `'1.0.0'`).
+
+**Returns:** `undefined` — `true` if the version is a prerelease, `false` otherwise.
+
+```typescript
+import { isPrerelease } from '@helpers4/version';
+
+isPrerelease(version: null): null
+```
+
+**Parameters:**
+
+- `version: null` — A semantic version string (e.g. `'2.0.0-alpha.1'`, `'1.0.0'`).
+
+**Returns:** `null` — `true` if the version is a prerelease, `false` otherwise.
+
+**Examples:**
+
+*Detect a prerelease version*
+
+Returns true for any version string that contains a prerelease suffix.
+
+```typescript
+isPrerelease('2.0.0-alpha.1') // true
+isPrerelease('1.0.0-rc.0')   // true
+```
+
+*Stable versions return false*
+
+Returns false when the version has no prerelease suffix.
+
+```typescript
+isPrerelease('1.0.0') // false
+isPrerelease('2.1.3') // false
+```
+
+*Accept a ParsedVersion object*
+
+Works with the result of parse() — checks the prerelease array instead of string matching.
+
+```typescript
+isPrerelease(parse('2.0.0-alpha.1')) // true
+isPrerelease(parse('1.0.0'))         // false
+```
+
+---
+
 ### `parse`
 
 Parses a semantic version string into its components according to SemVer 2.0.0 specification
@@ -6178,12 +6487,6 @@ parse('v2.0.0-alpha.1')
 
 ---
 
-### `ParsedVersion`
-
-Represents a parsed semantic version according to SemVer 2.0.0 specification
-
----
-
 ### `satisfiesRange`
 
 Checks if a version satisfies a range (simple implementation)
@@ -6232,6 +6535,74 @@ satisfiesRange('0.9.0', '>=1.0.0')
 
 ---
 
+### `stringify`
+
+Reconstruct a semantic version string from a ParsedVersion object.
+
+This is the inverse of parse:
+`stringify(parse(v)) === stripV(v)` for any valid SemVer string `v`.
+
+```typescript
+import { stringify } from '@helpers4/version';
+
+stringify(parsed: ParsedVersion): string
+```
+
+**Parameters:**
+
+- `parsed: ParsedVersion` — A parsed semantic version object.
+
+**Returns:** `string` — The reconstructed version string (without leading `v`).
+
+```typescript
+import { stringify } from '@helpers4/version';
+
+stringify(parsed: undefined): undefined
+```
+
+**Parameters:**
+
+- `parsed: undefined` — A parsed semantic version object.
+
+**Returns:** `undefined` — The reconstructed version string (without leading `v`).
+
+```typescript
+import { stringify } from '@helpers4/version';
+
+stringify(parsed: null): null
+```
+
+**Parameters:**
+
+- `parsed: null` — A parsed semantic version object.
+
+**Returns:** `null` — The reconstructed version string (without leading `v`).
+
+**Examples:**
+
+*Reconstruct a stable version*
+
+Converts a ParsedVersion object back to a version string.
+
+```typescript
+stringify({ major: 1, minor: 2, patch: 3, prerelease: [], build: [] })
+// => '1.2.3'
+```
+
+*Round-trip with parse*
+
+stringify(parse(v)) returns the original version string (without leading v).
+
+```typescript
+stringify(parse('2.0.0-alpha.1'))
+// => '2.0.0-alpha.1'
+
+stringify(parse('1.0.0-beta+exp.sha.5114f85'))
+// => '1.0.0-beta+exp.sha.5114f85'
+```
+
+---
+
 ### `stripV`
 
 Strip the leading "v" from a version string if it exists.

package/meta/build.json

@@ -1,6 +1,13 @@
 {
-  "buildDate": "2026-04-19T20:44:59.079Z",
-  "version": "2.0.0-alpha.17",
+  "buildDate": "2026-04-25T20:00:39.683Z",
+  "version": "2.0.0-alpha.19",
+  "mutationDashboardUrl": "https://dashboard.stryker-mutator.io/reports/github.com/helpers4/typescript/v2.0.0-alpha.19",
+  "runtimes": {
+    "node": ">=24.0.0",
+    "deno": "compatible",
+    "bun": "compatible",
+    "browser": "ES2022+"
+  },
   "categories": [
     "array",
     "date",

package/meta/packages.json

@@ -1,15 +1,15 @@
 {
-  "@helpers4/all": "2.0.0-alpha.17",
-  "@helpers4/array": "2.0.0-alpha.17",
-  "@helpers4/date": "2.0.0-alpha.17",
-  "@helpers4/function": "2.0.0-alpha.17",
-  "@helpers4/math": "2.0.0-alpha.17",
-  "@helpers4/number": "2.0.0-alpha.17",
-  "@helpers4/object": "2.0.0-alpha.17",
-  "@helpers4/observable": "2.0.0-alpha.17",
-  "@helpers4/promise": "2.0.0-alpha.17",
-  "@helpers4/string": "2.0.0-alpha.17",
-  "@helpers4/type": "2.0.0-alpha.17",
-  "@helpers4/url": "2.0.0-alpha.17",
-  "@helpers4/version": "2.0.0-alpha.17"
+  "@helpers4/all": "2.0.0-alpha.19",
+  "@helpers4/array": "2.0.0-alpha.19",
+  "@helpers4/date": "2.0.0-alpha.19",
+  "@helpers4/function": "2.0.0-alpha.19",
+  "@helpers4/math": "2.0.0-alpha.19",
+  "@helpers4/number": "2.0.0-alpha.19",
+  "@helpers4/object": "2.0.0-alpha.19",
+  "@helpers4/observable": "2.0.0-alpha.19",
+  "@helpers4/promise": "2.0.0-alpha.19",
+  "@helpers4/string": "2.0.0-alpha.19",
+  "@helpers4/type": "2.0.0-alpha.19",
+  "@helpers4/url": "2.0.0-alpha.19",
+  "@helpers4/version": "2.0.0-alpha.19"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helpers4/all",
-  "version": "2.0.0-alpha.17",
+  "version": "2.0.0-alpha.19",
   "description": "Complete collection of helpers4 utilities - all categories in one convenient package.",
   "author": "baxyz <baxy@etik.com>",
   "license": "LGPL-3.0",
@@ -27,17 +27,17 @@
     "llms.txt"
   ],
   "peerDependencies": {
-    "@helpers4/array": "2.0.0-alpha.17",
-    "@helpers4/date": "2.0.0-alpha.17",
-    "@helpers4/function": "2.0.0-alpha.17",
-    "@helpers4/math": "2.0.0-alpha.17",
-    "@helpers4/number": "2.0.0-alpha.17",
-    "@helpers4/object": "2.0.0-alpha.17",
-    "@helpers4/observable": "2.0.0-alpha.17",
-    "@helpers4/promise": "2.0.0-alpha.17",
-    "@helpers4/string": "2.0.0-alpha.17",
-    "@helpers4/type": "2.0.0-alpha.17",
-    "@helpers4/url": "2.0.0-alpha.17",
-    "@helpers4/version": "2.0.0-alpha.17"
+    "@helpers4/array": "2.0.0-alpha.19",
+    "@helpers4/date": "2.0.0-alpha.19",
+    "@helpers4/function": "2.0.0-alpha.19",
+    "@helpers4/math": "2.0.0-alpha.19",
+    "@helpers4/number": "2.0.0-alpha.19",
+    "@helpers4/object": "2.0.0-alpha.19",
+    "@helpers4/observable": "2.0.0-alpha.19",
+    "@helpers4/promise": "2.0.0-alpha.19",
+    "@helpers4/string": "2.0.0-alpha.19",
+    "@helpers4/type": "2.0.0-alpha.19",
+    "@helpers4/url": "2.0.0-alpha.19",
+    "@helpers4/version": "2.0.0-alpha.19"
   }
 }