{"id":10629,"library":"chrono-node","title":"Chrono Node","description":"Chrono Node (chrono-node) is a natural language date and time parser for JavaScript, currently at version 2.9.0. It allows developers to extract and interpret date and time information from arbitrary text, supporting a wide range of formats including relative phrases (\"tomorrow,\" \"5 days ago\"), absolute dates (\"17 August 2013\"), and date ranges (\"Sep 12-13\"). Since its v2 rewrite, the library is implemented in TypeScript, offering a more modular architecture with distinct parser and refiner interfaces. It differentiates itself by focusing on a performant, native JavaScript date/time core (having removed `dayjs` in v2.9.0) and providing robust control over parsing context, including explicit reference dates and timezones. While previous versions attempted to parse all known languages by default, v2.0.0 and later default to international English, requiring explicit configuration for other supported locales (e.g., Japanese, French, Dutch, Russian, Ukrainian).","status":"active","version":"2.9.0","language":"javascript","source_language":"en","source_url":"https://github.com/wanasit/chrono","tags":["javascript","typescript"],"install":[{"cmd":"npm install chrono-node","lang":"bash","label":"npm"},{"cmd":"yarn add chrono-node","lang":"bash","label":"yarn"},{"cmd":"pnpm add chrono-node","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Chrono is exported as a namespace object, so use `* as chrono` for all exports in ESM. Default import (`import chrono from 'chrono-node'`) will likely result in `undefined` or an empty object in many environments.","wrong":"import chrono from 'chrono-node';","symbol":"chrono","correct":"import * as chrono from 'chrono-node';"},{"note":"The `parseDate` function is a direct named export from the main package. Accessing internal paths like `dist/chrono.js` is not recommended and may break in future versions. You can also access it via the namespace import: `chrono.parseDate`.","wrong":"import { parseDate } from 'chrono-node/dist/chrono.js';","symbol":"parseDate","correct":"import { parseDate } from 'chrono-node';"},{"note":"These are TypeScript types and interfaces. Use `import type` for type-only imports to ensure they are stripped during compilation, preventing potential runtime errors or unnecessary bundle size increases.","wrong":"import { ParsedResult, ParsingReference, ParsingOption } from 'chrono-node';","symbol":"ParsedResult, ParsingReference, ParsingOption","correct":"import type { ParsedResult, ParsingReference, ParsingOption } from 'chrono-node';"},{"note":"For CommonJS environments, the entire library is exported, accessible through `chrono.parseDate()` and `chrono.parse()`.","symbol":"chrono (CommonJS)","correct":"const chrono = require('chrono-node');"}],"quickstart":{"code":"import * as chrono from 'chrono-node';\nimport type { ParsingReference, ParsingOption } from 'chrono-node';\n\nconst text1 = 'An appointment on Sep 12-13 from 2 PM to 4 PM next Friday';\nconst text2 = 'Tomorrow at noon in New York';\nconst text3 = 'In 3 days';\n\n// Basic parsing\nconst result1 = chrono.parseDate(text1);\nconsole.log('Result 1 (basic):', result1?.toISOString());\n\n// Parsing with a specific reference date and timezone\nconst referenceInstant = new Date('2025-02-27T10:00:00Z'); // UTC instant\nconst referenceOptions: ParsingReference = {\n  instant: referenceInstant,\n  timezone: 'America/Los_Angeles' // Reference timezone for interpretation\n};\nconst result2 = chrono.parseDate(text2, referenceOptions);\nconsole.log('Result 2 (ref + timezone):', result2?.toISOString());\n\n// Parsing with the 'forwardDate' option to ensure future dates\nconst today = new Date('2025-03-01T12:00:00Z'); // Saturday, March 1, 2025\nconst forwardOptions: ParsingOption = { forwardDate: true };\nconst result3 = chrono.parseDate(text3, today, forwardOptions);\nconsole.log('Result 3 (forwardDate):', result3?.toISOString());\n\n// Full parsed result (including text, index, start/end components)\nconst detailedResult = chrono.parse('Book a meeting for next Tuesday at 3pm', new Date('2025-03-01T00:00:00Z'), { forwardDate: true });\nif (detailedResult.length > 0) {\n  console.log('Detailed result:', JSON.stringify(detailedResult[0], null, 2));\n  console.log('  Extracted text:', detailedResult[0].text);\n  console.log('  Parsed date:', detailedResult[0].date().toISOString());\n}","lang":"typescript","description":"This quickstart demonstrates basic date parsing, advanced parsing with a reference date and timezone, and the use of the `forwardDate` option for future-only interpretations. It also shows how to get detailed parsing results."},"warnings":[{"fix":"For non-English text, explicitly import and use the desired locale parser, e.g., `import { ja } from 'chrono-node'; ja.parseDate('...')` or `chrono.ja.parseDate('...')`. You can also create a custom Chrono instance with specific locales.","message":"Chrono v2.0.0 changed its default behavior from attempting to parse all known languages to only international English. Code relying on auto-detection or parsing non-English text without explicit locale configuration will produce incorrect results or fail to parse.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Refactor custom components or code to use native JavaScript `Date` objects directly or other date utility libraries, as `chrono-node` now exclusively relies on native `Date` functionality.","message":"Version 2.9.0 removed the `dayjs` dependency and consequently deprecated and removed `ParsingComponent.dayjs()`. Any custom parsers or existing code relying on this function will break.","severity":"breaking","affected_versions":">=2.9.0"},{"fix":"Always provide a `ParsingReference` object with both `instant` (the current `Date` or a specific reference point) and `timezone` (e.g., 'America/New_York' or a minute offset) to ensure consistent and accurate parsing relative to a specific context.","message":"Incorrect date interpretation for relative terms (e.g., 'tomorrow', 'next Friday') can occur if the `ParsingReference` is not correctly set. The meaning of such terms is highly dependent on the `instant` and `timezone` provided in the reference.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"If you consistently need dates to be in the future, explicitly set `{ forwardDate: true }` in the `ParsingOption` object when calling `chrono.parseDate` or `chrono.parse`.","message":"The `forwardDate` parsing option, when `true`, forces Chrono to interpret relative dates (like 'Friday' or 'next month') as being in the future relative to the `reference` date. If not set, it may resolve to a past date if it's closer.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Review existing code that provides reference instants and relies on system timezone interpretations for relative dates. Ensure that the `timezone` property within `ParsingReference` accurately reflects the intended time context for your parsing operations.","message":"Version 2.8.0 introduced a fix where reference date calculations (e.g., for \"1 day ago\", \"tomorrow at 9am\") are now based on the *assigned timezone* of the reference instant/timestamp, rather than the system's local timezone. This change might subtly alter results for users relying on implicit system timezone behavior.","severity":"gotcha","affected_versions":">=2.8.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Remove any calls to `ParsingComponent.dayjs()` or other `dayjs`-specific logic from your custom parsers or integrations. Refactor to use native JavaScript `Date` methods.","cause":"Upgrading to chrono-node v2.9.0 without updating code that used the `dayjs` integration. The `dayjs` dependency and its related functions were removed in v2.9.0.","error":"TypeError: chrono.ParsingComponent.dayjs is not a function"},{"fix":"For ESM, use `import * as chrono from 'chrono-node';`. For CommonJS, use `const chrono = require('chrono-node');`. Ensure your build configuration (webpack, rollup, TypeScript `moduleResolution`) correctly handles module types.","cause":"Incorrect import statement for ESM or CommonJS modules, or trying to use named imports when the library uses a namespace export, especially in mixed environments.","error":"Error: Cannot find module 'chrono-node' or undefined is not a function/object for chrono"},{"fix":"Pass the `forwardDate: true` option in the `ParsingOption` object: `chrono.parseDate('Friday', referenceDate, { forwardDate: true });`","cause":"The parser defaults to the closest matching date. If 'Friday' has already passed in the current week relative to the reference date, it will pick the past Friday.","error":"Date results are in the past when expecting future dates (e.g., 'Friday' parses to last Friday)"},{"fix":"Always provide a comprehensive `ParsingReference` object with both `instant` (a `Date` object) and `timezone` (a string like 'America/Los_Angeles' or a minute offset) to ensure consistent timezone-aware parsing.","cause":"The reference date's timezone might not be correctly applied during interpretation, especially when the system timezone differs from the intended reference timezone. This was explicitly fixed in v2.8.0 for some scenarios.","error":"Parsing results for relative dates (e.g., 'today', 'tomorrow') are incorrect when timezones are involved."}],"ecosystem":"npm"}