npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

tasknotes-nlp-core

v0.1.3

Published

Shared natural language parsing core for TaskNotes

Readme

tasknotes-nlp-core

Framework-agnostic natural-language task parsing for TaskNotes-style workflows.

tasknotes-nlp-core turns free text like:

Pay rent tomorrow 9am #finance @home +admin every month

into structured task data (title, dates, tags, contexts, projects, recurrence, estimates, and custom fields).

Install

npm install tasknotes-nlp-core

What This Package Provides

  • NaturalLanguageParserCore: main parser engine
  • TriggerConfigService: helper for trigger/property mapping
  • Built-in defaults via DEFAULT_NLP_TRIGGERS
  • Language registry and helpers (getAvailableLanguages, getLanguageConfig, detectSystemLanguage)
  • Shared types for status/priority/trigger/user-field config

Quick Start

import {
  NaturalLanguageParserCore,
  DEFAULT_NLP_TRIGGERS,
  type StatusConfig,
  type PriorityConfig,
} from "tasknotes-nlp-core";

const statusConfigs: StatusConfig[] = [
  {
    id: "open",
    value: "open",
    label: "Open",
    color: "#64748b",
    isCompleted: false,
    order: 0,
    autoArchive: false,
    autoArchiveDelay: 0,
  },
  {
    id: "done",
    value: "done",
    label: "Done",
    color: "#22c55e",
    isCompleted: true,
    order: 1,
    autoArchive: true,
    autoArchiveDelay: 7,
  },
];

const priorityConfigs: PriorityConfig[] = [
  { id: "urgent", value: "urgent", label: "Urgent", color: "#ef4444", weight: 100 },
  { id: "normal", value: "normal", label: "Normal", color: "#3b82f6", weight: 50 },
];

const parser = new NaturalLanguageParserCore(
  statusConfigs,
  priorityConfigs,
  true,                  // defaultToScheduled
  "en",                 // language code
  DEFAULT_NLP_TRIGGERS   // optional trigger config
);

const parsed = parser.parseInput(
  "Pay rent tomorrow 9am #finance @home +admin every month 30m"
);

console.log(parsed);

Parsed Output Shape

parseInput() returns:

interface ParsedTaskData {
  title: string;
  details?: string;
  dueDate?: string;        // yyyy-MM-dd
  scheduledDate?: string;  // yyyy-MM-dd
  dueTime?: string;        // HH:mm
  scheduledTime?: string;  // HH:mm
  priority?: string;
  status?: string;
  tags: string[];
  contexts: string[];
  projects: string[];
  recurrence?: string;     // rrule string
  estimate?: number;       // minutes
  isCompleted?: boolean;
  userFields?: Record<string, string | string[]>;
}

Constructor Options

new NaturalLanguageParserCore(
  statusConfigs?,
  priorityConfigs?,
  defaultToScheduled?,
  languageCode?,
  nlpTriggers?,
  userFields?
)
  • statusConfigs: optional custom status list. If omitted, language fallback matching is used.
  • priorityConfigs: optional custom priority list. If omitted, language fallback matching is used.
  • defaultToScheduled:
    • true: ambiguous date text (for example tomorrow) goes to scheduledDate
    • false: ambiguous date text goes to dueDate
  • languageCode: one of supported codes (defaults to en).
  • nlpTriggers: trigger map for tags/contexts/projects/status/priority.
  • userFields: custom field definitions with trigger support.

Trigger Configuration

Default triggers:

  • # -> tags
  • @ -> contexts
  • + -> projects
  • * -> status
  • ! -> priority (disabled by default)

Example custom trigger config:

const customTriggers = {
  triggers: [
    { propertyId: "tags", trigger: "#", enabled: true },
    { propertyId: "contexts", trigger: "@", enabled: true },
    { propertyId: "projects", trigger: ">", enabled: true },
    { propertyId: "status", trigger: "~", enabled: true },
    { propertyId: "priority", trigger: "!", enabled: true },
  ],
};

User-Defined Fields

userFields supports these types:

  • text
  • number
  • date
  • boolean
  • list

List and text-like values support quoted multi-word input (for example ~client "Acme Corp").

Language Support

Built-in languages:

  • en, es, fr, de, ru, zh, ja, it, nl, pt, sv, uk

Helpers:

import { getAvailableLanguages, detectSystemLanguage } from "tasknotes-nlp-core";

Note: detectSystemLanguage() uses navigator.language when available; in non-browser runtimes it falls back to en.

Recurrence Output

Recurrence phrases are parsed into RRULE strings (for example FREQ=WEEKLY;BYDAY=MO).

For display, you can convert RRULE text with rrule or use parser preview helpers:

const previewItems = parser.getPreviewData(parsed);
const previewText = parser.getPreviewText(parsed);

Integration Pattern

This package is intentionally UI/framework agnostic. A common setup is:

  1. Keep app-specific config/state in your host app.
  2. Instantiate NaturalLanguageParserCore in an adapter service.
  3. Map parsed fields to your storage schema.
  4. Keep UI behavior (suggesters, editor state, persistence) outside this package.

Development

npm install
npm run build

Release

npm run release:patch   # x.y.z -> x.y.(z+1)
npm run release:minor   # x.y.z -> x.(y+1).0
npm run release:major   # x.y.z -> (x+1).0.0

These commands run npm version, create a git tag, push main with tags, and publish to npm.

License

MIT