Class StructuredData<T, R>

Privateconstructor

• new StructuredData<T = any, R = MetricRaw>(
      data: T[],
      key: keyof T,
  ): StructuredData<T, R>

  Creates a new StructuredData instance.

  Type Parameters

  • T = any

    The type of objects in the data array

  • R = MetricRaw

    The type of the metric raw result

  Parameters

  • data: T[]

    The array of objects to process

  • key: keyof T

    The property key to extract for comparison

  Returns StructuredData<T, R>

Private Readonlydata

Private Readonlykey

Privateextract

• extract(): string[]

  Extracts string values from the data array using the configured key.

  Returns string[]

  • Array of extracted strings

PrivateextractFrom

• extractFrom<A>(arr: readonly A[], key: keyof A): string[]

  Extracts properties from another array.

  Type Parameters

  • A

    The type of objects in the array

  Parameters

  • arr: readonly A[]

    The array to extract from

  • key: keyof A

    The property key

  Returns string[]

  • Array of extracted strings

PrivatefinalizeLookup

• finalizeLookup(
      results: CmpFnResult<R>,
      extractedStrings: string[],
      opt?: StructuredDataOptions,
  ): T[] | StructuredDataBatchResult<T, R>

  Finalizes the lookup process by normalizing, sorting, and rebuilding results.

  Parameters

  • results: CmpFnResult<R>

    The raw metric results

  • extractedStrings: string[]

    The extracted strings for index mapping

  • Optionalopt: StructuredDataOptions

    Additional options

  Returns T[] | StructuredDataBatchResult<T, R>

  • The finalized lookup results

PrivateisCmpStrResult

• isCmpStrResult(v: unknown): v is CmpStrResult & { raw?: R }

  Type guard to check if a value is CmpStrResult & { raw?: R }.

  Parameters

  • v: unknown

    The value to check

  Returns v is CmpStrResult & { raw?: R }

PrivateisMetricResult

• isMetricResult(v: unknown): v is MetricResultSingle<R>

  Type guard to check if a value is MetricResultSingle.

  Parameters

  • v: unknown

    The value to check

  Returns v is MetricResultSingle<R>

  • True if v is MetricResultSingle

PrivatenormalizeResults

• normalizeResults(results: CmpFnResult<R>): IndexedResult<R>[]

  Normalizes metric results to a consistent format. Attaches original indices for correct mapping after sorting. Handles both CmpStrResult[] and MetricResultBatch formats.

  Parameters

  • results: CmpFnResult<R>

    The raw metric results

  Returns IndexedResult<R>[]

  • Normalized results with indices

  Throws

  • If results format is unsupported

PrivateperformLookup

• performLookup(
      fn: () => CmpFnResult<R>,
      extractedStrings: string[],
      opt?: StructuredDataOptions,
  ): T[] | StructuredDataBatchResult<T, R>

  Performs a lookup with a synchronous comparison function.

  Parameters

  • fn: () => CmpFnResult<R>

    The comparison function

  • extractedStrings: string[]

    The extracted strings for index mapping

  • Optionalopt: StructuredDataOptions

    Additional options

  Returns T[] | StructuredDataBatchResult<T, R>

  • The lookup results

PrivateperformLookupAsync

• performLookupAsync(
      fn: () => Promise<CmpFnResult<R>>,
      extractedStrings: string[],
      opt?: StructuredDataOptions,
  ): Promise<T[] | StructuredDataBatchResult<T, R>>

  Performs a lookup with an asynchronous comparison function.

  Parameters

  • fn: () => Promise<CmpFnResult<R>>

    The async comparison function

  • extractedStrings: string[]

    The extracted strings for index mapping

  • Optionalopt: StructuredDataOptions

    Additional options

  Returns Promise<T[] | StructuredDataBatchResult<T, R>>

  • The async lookup results

Privaterebuild

• rebuild(
      results: IndexedResult<R>[],
      sourceData: T[],
      extractedStrings: string[],
      removeZero?: boolean,
      objectsOnly?: boolean,
  ): T[] | StructuredDataResult<T, R>[]

  Rebuilds results with original objects attached. Maps results to source objects using target string matching with duplicate handling. Works correctly even when results are filtered or subset (e.g., from closest/furthest).

  Parameters

  • results: IndexedResult<R>[]

    The normalized metric results

  • sourceData: T[]

    The source data array for object attachment

  • extractedStrings: string[]

    The extracted strings array for index mapping

  • OptionalremoveZero: boolean

    Whether to remove zero similarity results

  • OptionalobjectsOnly: boolean

    Return only objects without metadata

  Returns T[] | StructuredDataResult<T, R>[]

  • Results with objects (or just objects if objectsOnly=true)

Privatesort

• sort(results: IndexedResult<R>[], sort?: string | boolean): IndexedResult<R>[]

  Sorts results in-place by match score. Preserves __idx for tracking original positions.

  Parameters

  • results: IndexedResult<R>[]

    The results to sort

  • Optionalsort: string | boolean

    Sort direction (asc, desc, or boolean true=desc)

  Returns IndexedResult<R>[]

  • Sorted results