tasknotes-nlp-core

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?,
  options?
)

• 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.
• options.dateLocale: locale used for ambiguous numeric dates, for example en-GB parses 11/06/2026 as 2026-06-11.
• options.dateOrder: explicit numeric date order override, either day-first or month-first.

Quoted spans and backslash-prefixed literals are preserved as plain title text instead of being parsed as NLP syntax. For example, "Today" and \tomorrow remain literal text, and \@ABC remains @ABC instead of becoming a context.

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:

• Keep app-specific config/state in your host app.
• Instantiate NaturalLanguageParserCore in an adapter service.
• Map parsed fields to your storage schema.
• 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