{"id":17148445,"url":"https://github.com/aholstenson/ecolect-js","last_synced_at":"2025-04-13T09:33:05.888Z","repository":{"id":16085043,"uuid":"79258562","full_name":"aholstenson/ecolect-js","owner":"aholstenson","description":"Natural language handling for commands and intents","archived":false,"fork":false,"pushed_at":"2023-01-08T00:54:13.000Z","size":1665,"stargazers_count":28,"open_issues_count":15,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-04-14T13:15:47.240Z","etag":null,"topics":["date-parser","intent-parser","natural-language-processing"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aholstenson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-17T18:34:20.000Z","updated_at":"2023-03-18T20:00:14.000Z","dependencies_parsed_at":"2023-01-13T20:30:21.969Z","dependency_job_id":null,"html_url":"https://github.com/aholstenson/ecolect-js","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aholstenson%2Fecolect-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aholstenson%2Fecolect-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aholstenson%2Fecolect-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aholstenson%2Fecolect-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aholstenson","download_url":"https://codeload.github.com/aholstenson/ecolect-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223581935,"owners_count":17168655,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["date-parser","intent-parser","natural-language-processing"],"created_at":"2024-10-14T21:28:38.116Z","updated_at":"2024-11-07T20:05:25.014Z","avatar_url":"https://github.com/aholstenson.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ecolect\n\n[![npm version](https://badge.fury.io/js/ecolect.svg)](https://badge.fury.io/js/ecolect)\n[![Build Status](https://travis-ci.org/aholstenson/ecolect-js.svg?branch=master)](https://travis-ci.org/aholstenson/ecolect-js)\n[![Coverage Status](https://coveralls.io/repos/aholstenson/ecolect-js/badge.svg)](https://coveralls.io/github/aholstenson/ecolect-js)\n[![Dependencies](https://david-dm.org/aholstenson/ecolect-js.svg)](https://david-dm.org/aholstenson/ecolect-js)\n\nEcolect is a library for JavaScript and TypeScript that helps with matching\nnatural language phrases and values. This can be used as a part in building a\nnatural language interface for things such as bots, voice or search interfaces.\n\n## Installation\n\n```\n$ npm install --save ecolect\n```\n\n# Features\n\n* Natural language parsing of different values, such as:\n  * Dates and times (via `dateValue`, `timeValue` and `dateTimeValue`)\n  * Date intervals (via `dateIntervalValue`)\n  * Durations (via `dateDurationValue`, `timeDurationValue` and `dateTimeDurationValue`)\n  * Numbers (via `ordinalValue`, `numberValue` and `integerValue`)\n* Matching of phrases, including value extraction\n* Partial matching of phrases, for auto-complete uses such as action launches\n\n### Examples\n\nUsing a value:\n\n```javascript\nimport { en } from '@ecolect/language-en';\nimport { dateValue } from 'ecolect';\n\nconst matcher = dateValue().toMatcher(en);\nconst bestMatch = await matcher.match('first Monday of 2021');\n```\n\nMatching phrases:\n\n```javascript\nimport { en } from '@ecolect/language-en';\nimport { newPhrases, dateIntervalValue } from 'ecolect';\n\nconst matcher = newPhrases()\n  .value('when', dateIntervalValue())\n  .phrase('Show todos due {when}')\n  .phrase('Todos due {when}')\n  .toMatcher(en);\n\nconst bestMatch = await matcher.match('todo due today');\n```\n\nCombining phrases:\n\n```javascript\nimport { en } from '@ecolect/language-en';\nimport { intentsBuilder, newPhrases, dateIntervalValue } from 'ecolect';\n\nconst matcher = intentsBuilder(en)\n  .add('orders', newPhrases()\n    .phrase('Orders')\n    .phrase('Show orders')\n    .build()\n  )\n  .add('orders:active', newPhrases()\n    .phrase('Orders that are active')\n    .phrase('Show orders that are active')\n    .build()\n  )\n  .build();\n\nconst bestMatch = await matcher.match('orders');\n\n// Or partially match\nconst matches = await matcher.matchPartial('orders);\n```\n\n## Options\n\nOption                  | Default      | Description\n------------------------|--------------|-------------\n`now`                   | `new Date()` | Date to use as a base for times and dates parsed\n`weekStartsOn`          | `0` (Sunday) | The day the week starts on\n`firstWeekContainsDate` | `1`          | The day of January which is always in the first week of the year.\n\n### A note about weeks\n\nIt's important to set `weekStartsOn` and `firstWeekContainsDate` to something\nexpected by the user. The default value for `weekStartsOn` is `0` which\nindicates that weeks start on Sunday.\n\n`firstWeekContainsDate` defaults to `1` which is commonly used in North America\nand Islamic date systems. Countries that use this week numbering include\nCanada, United States, India, Japan, Taiwan, Hong Kong, Macau, Israel,\nEgypt, South Africa, the Phillippines and most of Latin America.\n\nFor EU countries most of them use Mondays as the start of the week and the ISO\nweek system. Settings `weekStartsOn` to `1` and `firstWeekContainsDate` to `4`\nwill set weeks to a style used in EU and most other European countries, most\nof Acia and Oceania.\n\nMiddle Eastern countries commonly use Saturday as their first day of week and\na week numbering system where the first week of the year contains January 1st.\nSet `weekStartsOn` to `6` and `firstWeekContainsDate` to `1` to use this\nstyle of week.\n\nFor more information about week numbering see the [Week article on Wikipedia](https://en.wikipedia.org/wiki/Week#Week_numbering).\n\n## Value types\n\n### Integer\n\n```javascript\nimport { integerValue } from 'ecolect';\n\nconst value = integerValue();\n```\n\nCapture any positive integer number.\n\nLanguage         | Examples\n-----------------|-------------\nEnglish          | `20`, `zero`, `one million`, `4 000`, `1 dozen`, `100k`\n\n#### Returned value\n\nThe returned value is a `BigInteger` from [numeric-types](https://github.com/aholstenson/numeric-types).\n\n### Number\n\n```javascript\nimport { numberValue } from 'ecolect';\n\nconst value = numberValue();\n```\n\nCapture any number, including numbers with a fractional element.\n\nLanguage         | Examples\n-----------------|-------------\nEnglish          | `20`, `2.4 million`, `8.0`, `-12`\n\n#### Returned value\n\nThe returned value is a `BigDecimal` from [numeric-types](https://github.com/aholstenson/numeric-types).\n\n### Ordinal\n\n```javascript\nimport { ordinalValue } from 'ecolect';\n\nconst value = ordinalValue();\n```\n\nCapture an ordinal, such as `1st`, indicating a position.\n\nLanguage         | Examples\n-----------------|-------------\nEnglish          | `1st`, `third`, `3`, `the fifth`\n\n#### Returned value\n\nThe returned value is a `BigInteger` from [numeric-types](https://github.com/aholstenson/numeric-types).\n\n### Date\n\n```javascript\nimport { dateValue } from 'ecolect';\n\nconst value = dateValue();\n```\n\nCapture a date representing a single day.\n\nLanguage         | Examples\n-----------------|-------------\nEnglish          | `today`, `in 2 days`, `january 12th`, `2010-02-22`, `02/22/2010`, `first friday in 2020`\n\n#### Returned value\n\nThe returned value is a `LocalDate` from [datetime-types](https://github.com/aholstenson/datetime-types).\n\n### Time\n\n```javascript\nimport { timeValue } from 'ecolect';\n\nconst value = timeValue();\n```\n\nCapture a time of day.\n\nLanguage         | Examples\n-----------------|-------------\nEnglish          | `09:00`, `3 pm`, `at 3:30 am`, `noon`, `quarter to twelve`, `in 2 hours`, `in 45 minutes`\n\n#### Returned value\n\nThe returned value is a `LocalTime` from [datetime-types](https://github.com/aholstenson/datetime-types).\n\n### Date \u0026 Time\n\n```javascript\nimport { dateTimeValue } from 'ecolect';\n\nconst value = dateTimeValue();\n```\n\nCapture both a date and a time.\n\nLanguage         | Examples\n-----------------|-------------\nEnglish          | `3pm on Jan 12th`, `in 2 days and 2 hours`, `14:00`\n\n#### Returned value\n\nThe returned value is a `LocalDateTime` from [datetime-types](https://github.com/aholstenson/datetime-types).\n\n### Date Interval\n\n```javascript\nimport { dateIntervalValue } from 'ecolect';\n\nconst value = dateIntervalValue();\n```\n\nCapture an interval between two dates.\n\nLanguage         | Examples\n-----------------|-------------\nEnglish          | `today`, `this month`, `February to March`, `2018-01-01 to 2018-04-05`, `January 15th - 18th`\n\n#### Returned value\n\nThe returned value is a `DateInterval` from [datetime-types](https://github.com/aholstenson/datetime-types).\n\n### Date Duration\n\n```javascript\nimport { dateDurationValue } from 'ecolect';\n\nconst value = dateDurationValue();\n```\n\nCapture a duration.\n\nLanguage         | Examples\n-----------------|-------------\nEnglish          | `2 days`, `2m, 1d`, `1 year and 2 days`, `4y 2m`, `1 week`\n\n#### Returned value\n\n### Time Duration\n\n```javascript\nimport { timeDurationValue } from 'ecolect';\n\nconst value = timeDurationValue();\n```\n\nCapture a duration of hours, minutes, seconds and miliseconds.\n\nLanguage         | Examples\n-----------------|-------------\nEnglish          | `2 hours`, `1s`, `2h, 45m`, `4 minutes and 10 seconds`\n\n#### Returned value\n\n### Date \u0026 Time Duration\n\n```javascript\nimport { dateTimeDurationValue } from 'ecolect';\n\nconst value = dateTimedurationValue();\n```\n\nCapture a duration of both days, hours, minutes, seconds and miliseconds.\n\nLanguage         | Examples\n-----------------|-------------\nEnglish          | `2 hours`, `2 d 20 m`, `4 weeks and 10 minutes`\n\n#### Returned value\n\n### Enumeration\n\n```javascript\nimport { enumerationValue } from 'ecolect';\n\nconst value = enumerationValue([\n  'Option 1',\n  'Other option'\n]);\n```\n\nCapture one of the specified values. Used to specify one or more values that\nshould match.\n\n### Text\n\n```javascript\nimport { anyTextValue } from 'ecolect';\n\nconst value = anyTextValue();\n```\n\nText can be captured with the type `anyTextValue`. You can use `anyTextValue`\nfor things such as search queries, todo items and calendar events. Values of\ntype `anyTextValue` will always try to capture as much as they can and will not\nvalidate the result.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faholstenson%2Fecolect-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faholstenson%2Fecolect-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faholstenson%2Fecolect-js/lists"}