@whenis/core

Engine for whenis — a TypeScript natural-language date parser.

This package contains the tokenizer, rule engine, resolver, and the public Locale / Plugin / Rule interfaces. It has no locale data of its own — pair it with @whenis/locale-uk, @whenis/locale-en, or your own locale.

Install

pnpm add @whenis/core @whenis/locale-uk

Usage

import { createParser } from '@whenis/core';
import { uk } from '@whenis/locale-uk';

const parser = createParser({ locales: [uk], options: { preferFuture: true } });

const result = parser.parse("наступної п'ятниці", { reference: new Date('2026-05-28') });
console.log(result.matches[0].candidates[0]);
// { confidence: 1, type: 'date', date: '2026-06-05', granularity: 'day' }

API

createParser({
  locales: Locale[];
  plugins?: Plugin[];
  options?: { preferFuture?: boolean };
}): Parser;

parser.parse(input: string, opts: { reference: Date; timezone?: string }): ParseResult;

Exported types: Locale, Plugin, Rule, PatternItem, ResolverCtx, IRTypeExt, Enricher, Tag, Token, IRNode, IRSpan, ParseOptions, ParseResult, Match, ResolvedDate.

Re-exported helpers: tokenize, runRules, resolve, baseRules.

See the root README for the full output shape, the multi-candidate model, and the architecture diagram.

License

MIT © Nazar Fedyshyn