/** A path string, or anything with a `path`. Returned by reference, untouched. */
export type PathItem = string | { path: string }

export interface SearchOptions {
  /** Only paths starting with this prefix. */
  root?: string | null
  /** Only paths passing through these folders, wherever they sit. */
  path?: string | null
  /** Only these file types: one extension or several, leading dot optional. */
  extension?: string | string[] | null
  /** Your own predicate, only called for items that matched everything else. */
  filter?: ((item: any) => boolean) | null
  /** Cap on results, applied after sorting. */
  limit?: number | null
  /** Also match folder names, ranked after name matches. On by default; false matches names only. */
  folders?: boolean
  /** Case matters, except for the extension filter. Ignored for RegExp queries. */
  caseSensitive?: boolean
  /** What a typed space becomes, e.g. "_". Ignored for RegExp queries. */
  spaces?: string | null
}

/**
 * Filter and rank paths for a query: exact names first, then starts-with, then
 * contains, whole words ahead of parts of words, each tier in natural order. A
 * directory in the query constrains the match ("block/stone"). A RegExp query
 * runs globally over the path, ranked by where its best hit lands.
 */
export function pathSearch<T extends PathItem>(items: Iterable<T>, query: string | RegExp | null | undefined, options?: SearchOptions): T[]

/** Natural comparison: digit runs by numeric value, everything else by code unit. */
export function naturalCompare(a: string, b: string): number

export default pathSearch