Universal time series search
Search through your time series data with javascript. Find a value or its closest match through a list of dates or data frames. Dates can be represented as date string or number format that dateJS can parse.
For advanced use cases, you can provide a custom comparison function for non-standard formats.
For detailed documentation: https://date-search.netlify.app
npm i date-search
import { dateSearch } from 'date-search'; // or use require
const bigSortedDatesArray = [Date('2000-1-1'), Date(), Date(), ...];
const targetDate = '2000-1-1';
const {index, value} = dateSearch(bigSortedDatesArray, targetDate);
targetDate === value; // true
index; // 0
The search algo accepts these parameters:
A typed array of dates or nested objects containing dates. These should be sorted by oldest to most recent.
The value the algo is searching for. This should be the date that is being searched for. Valid inputs include string
, number
, Date
, and Dayjs
objects. null
can be supplied but the module will throw an error.
Uses the builtin defaultTimeComparator
by default if no value is provided. It returns a positive or negative number that indicates which side of the array to search next.
dayjs.extend(customParseFormat)
dateSearch(
array: [{id: 123, child: {date: '12-25-1995'}}, ...],
target: '12-25-1995',
comparator: (a, b) => dayJS(a, "MM-DD-YYYY").unix() - dayJS(b, "MM-DD-YYYY").unix(),
)
Points to a nested key of an object containing the date value. It uses the same comparison logic as the defaultTimeComparator
once the values are parsed.
dateSearch(
array: [{id: 123, child: {date: '2020-1-1'}}, ...],
target: '2020-1-1',
comparator: 'child.date',
dateSearchMode: DateSearchModes.EXACT
)
Find the exact value. Returns null
if not found.
dateSearch(
array: [{id: 123, child: {date: '2020-1-1'}}, ...],
target: '1995-1-1',
comparator: defaultTimeComparator,
dateSearchMode: DateSearchModes.EXACT
) // not found, null is returned
Find the closest index, rounding down. The first element is used if the target
value is lower than the first array
element.
dateSearch(
array: ['2020-1-1', '2020-2-1', '2020-5-1', ...],
target: '1995-3-1',
comparator: defaultTimeComparator,
dateSearchMode: DateSearchModes.CLOSEST_FLOOR
) // returns index 1, value of 2020-2-1
Find the closest index, rounding up. The last element is used if the target
value is greater than the last array
element.
dateSearch(
array: ['2020-1-1', '2020-2-1', '2020-5-1', ...],
target: '1995-3-1',
comparator: defaultTimeComparator,
dateSearchMode: DateSearchModes.CLOSEST_CEIL
) // returns index 2, value of 2020-2-1
Generated using TypeDoc