docs(core): add @example blocks to core module exports (#170)

* feat(paths): add fromUnixPath to convert MSYS paths to native Windows format

* docs(utils): add @example blocks to utility module exports

* docs(core): add @example blocks to core module exports

Author: jdalton

src/abort.ts

@@ -4,6 +4,13 @@
 
 /**
  * Create a composite AbortSignal from multiple signals.
+ *
+ * @example
+ * ```typescript
+ * const ac1 = new AbortController()
+ * const ac2 = new AbortController()
+ * const signal = createCompositeAbortSignal(ac1.signal, ac2.signal)
+ * ```
  */
 export function createCompositeAbortSignal(
   ...signals: Array<AbortSignal | null | undefined>
@@ -33,6 +40,12 @@ export function createCompositeAbortSignal(
 
 /**
  * Create an AbortSignal that triggers after a timeout.
+ *
+ * @example
+ * ```typescript
+ * const signal = createTimeoutSignal(5000) // aborts after 5 seconds
+ * fetch('https://example.com', { signal })
+ * ```
  */
 export function createTimeoutSignal(ms: number): AbortSignal {
   if (typeof ms !== 'number' || Number.isNaN(ms)) {

src/ansi.ts

@@ -22,6 +22,13 @@ const ANSI_REGEX = /\x1b\[[0-9;]*m/g
  * https://socket.dev/npm/package/ansi-regexp/overview/6.2.2
  * MIT License
  * Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+ *
+ * @example
+ * ```typescript
+ * const regex = ansiRegex()
+ * '\u001b[31mHello\u001b[0m'.match(regex)  // ['\u001b[31m', '\u001b[0m']
+ * ansiRegex({ onlyFirst: true })           // matches only the first code
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function ansiRegex(options?: { onlyFirst?: boolean }): RegExp {
@@ -40,6 +47,12 @@ export function ansiRegex(options?: { onlyFirst?: boolean }): RegExp {
 /**
  * Strip ANSI escape codes from text.
  * Uses the inlined ansi-regex for matching.
+ *
+ * @example
+ * ```typescript
+ * stripAnsi('\u001b[31mError\u001b[0m')  // 'Error'
+ * stripAnsi('\u001b[1mBold\u001b[0m')    // 'Bold'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function stripAnsi(text: string): string {

src/cache-with-ttl.ts

@@ -158,6 +158,13 @@ const DEFAULT_PREFIX = 'ttl-cache'
 
 /**
  * Create a TTL-based cache instance.
+ *
+ * @example
+ * ```typescript
+ * const cache = createTtlCache({ ttl: 60_000, prefix: 'my-app' })
+ * await cache.set('key', { value: 42 })
+ * const data = await cache.get('key') // { value: 42 }
+ * ```
  */
 export function createTtlCache(options?: TtlCacheOptions): TtlCache {
   const opts = {

src/colors.ts

@@ -68,6 +68,12 @@ const colorToRgb: Record<ColorName, ColorRgb> = {
  * Type guard to check if a color value is an RGB tuple.
  * @param value - Color value to check
  * @returns `true` if value is an RGB tuple, `false` if it's a color name
+ *
+ * @example
+ * ```typescript
+ * isRgbTuple([255, 0, 0]) // true
+ * isRgbTuple('red')       // false
+ * ```
  */
 export function isRgbTuple(value: ColorValue): value is ColorRgb {
   return Array.isArray(value)
@@ -78,6 +84,12 @@ export function isRgbTuple(value: ColorValue): value is ColorRgb {
  * Named colors are looked up in the `colorToRgb` map, RGB tuples are returned as-is.
  * @param color - Color name or RGB tuple
  * @returns RGB tuple with values 0-255
+ *
+ * @example
+ * ```typescript
+ * toRgb('red')       // [255, 0, 0]
+ * toRgb([0, 128, 0]) // [0, 128, 0]
+ * ```
  */
 export function toRgb(color: ColorValue): ColorRgb {
   if (isRgbTuple(color)) {

src/functions.ts

@@ -11,12 +11,25 @@ export type AnyFunction = (...args: unknown[]) => unknown
 
 /**
  * A no-op function that does nothing.
+ *
+ * @example
+ * ```typescript
+ * const callback = noop
+ * callback()  // does nothing
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function noop(): void {}
 
 /**
  * Create a function that only executes once.
+ *
+ * @example
+ * ```typescript
+ * const init = once(() => Math.random())
+ * init()  // 0.456 (random value)
+ * init()  // 0.456 (same value, not recalculated)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function once<T extends AnyFunction>(fn: T): T {
@@ -36,6 +49,15 @@ export function once<T extends AnyFunction>(fn: T): T {
 
 /**
  * Wrap an async function to silently catch and ignore errors.
+ *
+ * @example
+ * ```typescript
+ * const safeFetch = silentWrapAsync(async (url: string) => {
+ *   const res = await fetch(url)
+ *   return res.json()
+ * })
+ * await safeFetch('https://example.com')  // result or undefined on error
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function silentWrapAsync<TArgs extends unknown[], TResult>(
@@ -52,6 +74,14 @@ export function silentWrapAsync<TArgs extends unknown[], TResult>(
 
 /**
  * Execute a function with tail call optimization via trampoline.
+ *
+ * @example
+ * ```typescript
+ * const factorial = trampoline((n: number, acc = 1): any =>
+ *   n <= 1 ? acc : () => factorial(n - 1, n * acc)
+ * )
+ * factorial(5)  // 120
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function trampoline<T extends AnyFunction>(fn: T): T {

src/regexps.ts

@@ -10,6 +10,13 @@
 
 /**
  * Escape special characters in a string for use in a regular expression.
+ *
+ * @example
+ * ```typescript
+ * escapeRegExp('foo.bar')     // 'foo\\.bar'
+ * escapeRegExp('a+b*c?')     // 'a\\+b\\*c\\?'
+ * new RegExp(escapeRegExp('[test]'))  // /\[test\]/
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function escapeRegExp(str: string): string {

src/sorts.ts

@@ -24,6 +24,13 @@ function getFastSort() {
 
 /**
  * Compare semantic versions.
+ *
+ * @example
+ * ```typescript
+ * compareSemver('1.0.0', '2.0.0')  // -1
+ * compareSemver('2.0.0', '1.0.0')  // 1
+ * compareSemver('1.0.0', '1.0.0')  // 0
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function compareSemver(a: string, b: string): number {
@@ -47,6 +54,13 @@ export function compareSemver(a: string, b: string): number {
 
 /**
  * Simple string comparison.
+ *
+ * @example
+ * ```typescript
+ * compareStr('a', 'b')  // -1
+ * compareStr('b', 'a')  // 1
+ * compareStr('a', 'a')  // 0
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function compareStr(a: string, b: string): number {
@@ -56,6 +70,13 @@ export function compareStr(a: string, b: string): number {
 let _localeCompare: ((x: string, y: string) => number) | undefined
 /**
  * Compare two strings using locale-aware comparison.
+ *
+ * @example
+ * ```typescript
+ * localeCompare('a', 'b')  // -1
+ * localeCompare('b', 'a')  // 1
+ * localeCompare('a', 'a')  // 0
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function localeCompare(x: string, y: string): number {
@@ -69,6 +90,12 @@ export function localeCompare(x: string, y: string): number {
 let _naturalCompare: ((x: string, y: string) => number) | undefined
 /**
  * Compare two strings using natural sorting (numeric-aware, case-insensitive).
+ *
+ * @example
+ * ```typescript
+ * naturalCompare('file2', 'file10')  // negative (file2 before file10)
+ * naturalCompare('img10', 'img2')    // positive (img10 after img2)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function naturalCompare(x: string, y: string): number {
@@ -100,6 +127,12 @@ type FastSortFunction = ReturnType<
 let _naturalSorter: FastSortFunction | undefined
 /**
  * Sort an array using natural comparison.
+ *
+ * @example
+ * ```typescript
+ * naturalSorter(['file10', 'file2', 'file1']).asc()
+ * // ['file1', 'file2', 'file10']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function naturalSorter<T>(

src/url.ts

@@ -8,6 +8,13 @@ const UrlCtor = URL
 
 /**
  * Check if a value is a valid URL.
+ *
+ * @example
+ * ```typescript
+ * isUrl('https://example.com') // true
+ * isUrl('not a url')           // false
+ * isUrl(null)                  // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function isUrl(value: string | URL | null | undefined): boolean {
@@ -20,6 +27,12 @@ export function isUrl(value: string | URL | null | undefined): boolean {
 
 /**
  * Parse a value as a URL.
+ *
+ * @example
+ * ```typescript
+ * parseUrl('https://example.com')  // URL { href: 'https://example.com/' }
+ * parseUrl('invalid')              // undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function parseUrl(value: string | URL): URL | undefined {
@@ -31,6 +44,12 @@ export function parseUrl(value: string | URL): URL | undefined {
 
 /**
  * Convert a URL search parameter to an array.
+ *
+ * @example
+ * ```typescript
+ * urlSearchParamAsArray('a, b, c') // ['a', 'b', 'c']
+ * urlSearchParamAsArray(null)      // []
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function urlSearchParamAsArray(
@@ -51,6 +70,13 @@ export interface UrlSearchParamAsBooleanOptions {
 
 /**
  * Convert a URL search parameter to a boolean.
+ *
+ * @example
+ * ```typescript
+ * urlSearchParamAsBoolean('true') // true
+ * urlSearchParamAsBoolean('0')    // false
+ * urlSearchParamAsBoolean(null)   // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function urlSearchParamAsBoolean(
@@ -73,6 +99,12 @@ export function urlSearchParamAsBoolean(
 
 /**
  * Helper to get array from URLSearchParams.
+ *
+ * @example
+ * ```typescript
+ * const params = new URLSearchParams('tags=a,b,c')
+ * urlSearchParamsGetArray(params, 'tags') // ['a', 'b', 'c']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function urlSearchParamsGetArray(
@@ -97,6 +129,13 @@ export interface UrlSearchParamsGetBooleanOptions {
 
 /**
  * Helper to get boolean from URLSearchParams.
+ *
+ * @example
+ * ```typescript
+ * const params = new URLSearchParams('debug=true')
+ * urlSearchParamsGetBoolean(params, 'debug') // true
+ * urlSearchParamsGetBoolean(params, 'other') // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function urlSearchParamsGetBoolean(
@@ -123,6 +162,12 @@ export interface CreateRelativeUrlOptions {
 
 /**
  * Create a relative URL for testing.
+ *
+ * @example
+ * ```typescript
+ * createRelativeUrl('/api/test')                                    // 'api/test'
+ * createRelativeUrl('/api/test', { base: 'https://example.com' })  // 'https://example.com/api/test'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function createRelativeUrl(
@@ -153,6 +198,13 @@ export interface UrlSearchParamAsStringOptions {
 
 /**
  * Get string value from URLSearchParams with a default.
+ *
+ * @example
+ * ```typescript
+ * const params = new URLSearchParams('name=socket')
+ * urlSearchParamAsString(params, 'name')  // 'socket'
+ * urlSearchParamAsString(params, 'other') // ''
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function urlSearchParamAsString(
@@ -177,6 +229,13 @@ export interface UrlSearchParamAsNumberOptions {
 
 /**
  * Get number value from URLSearchParams with a default.
+ *
+ * @example
+ * ```typescript
+ * const params = new URLSearchParams('limit=10')
+ * urlSearchParamAsNumber(params, 'limit') // 10
+ * urlSearchParamAsNumber(params, 'other') // 0
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function urlSearchParamAsNumber(