date-search / Exports
date-search
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.
Documentation
For detailed documentation: https://date-search.netlify.app
Installation
npm i date-search
Usage
Use the dateSearch
function to quickly find if your target date is present.
import { dateSearch } from 'date-search'; // or use require
const bigSortedDatesArray = [Date('2000-1-1'), Date('2000-1-2'), Date('2000-1-3')];
const targetDate = '2000-1-1';
const {index, value} = dateSearch(
bigSortedDatesArray,
targetDate
);
targetDate === value; // true
index; // 0
The dateSearchBetween
will return the closest matching results inclusive of the target start and end search dates.
import { dateSearchBetween } from 'date-search'; // or use require
const bigSortedDatesArray = [Date('2000-1-1'), Date(), Date(), ...];
const startDate = '2000-1-13';
const endDate = '2000-1-23';
const {startValue, endValue, array} = dateSearchBetween(
bigSortedDatesArray,
targetDate
);
array.length; // 11
Features
- Date, timestamp string, and unix date numbers excepted.
- Custom comparators:
- String referencing a value within an object or nested object.
- Custom comparison function and date parsing.
- Get segment of array that matches between two dates.
- Built with DayJS for MomentJS regression and more reliable date parsing.
- Fuzzy search: find the exact or closest item.
- Written in typescript with type documentation.
Advanced Usage
The search algo accepts these parameters:
array
A typed array of dates or nested objects containing dates. These should be sorted by oldest to most recent.
target
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.
comparator (optional)
ComparatorFn
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(),
)
string
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
)
dateSearchMode
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
CLOSEST_FLOOR
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
CLOSEST_CEIL
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