@tasknotes/model

@tasknotes/model

Portable TaskNotes model semantics for JavaScript and TypeScript consumers. This package is the shared, host-independent implementation of the TaskNotes data model.

It intentionally contains no Obsidian API usage, no vault IO, no process exits, and no UI code. Hosts such as the Obsidian plugin, mdbase-tasknotes, companion plugins, or automation tools should use this package for deterministic TaskNotes behavior, then perform their own persistence and presentation.

Responsibilities

@tasknotes/model owns:

• TaskNotes task, config, field mapping, status, priority, recurrence, and time-entry types
• default model configuration
• TaskNotes frontmatter mapping and normalization
• date parsing, date comparison, and storage-date semantics
• recurrence evaluation and schedule advancement
• materialized occurrence identity, creation, completion, skip, and parent reconciliation plans
• time tracking entry planning and duration calculation
• validation helpers
• host-independent operation plans for common task mutations
• spec-normalized adapter helpers for CLI and mdbase-style consumers
• tasknotes-spec conformance operation helpers

Hosts own:

• file, vault, database, or network IO
• Obsidian app APIs and metadata cache reads
• command registration and UI state
• notifications, logging, process exits, and error presentation
• sync provider lifecycles
• path resolution against host-specific collection or vault rules

Module Map

The package exports both the root module and focused subpath modules:

Module	Purpose
@tasknotes/model	Main barrel export for all public APIs
@tasknotes/model/types	Shared TaskNotes model and operation types
@tasknotes/model/defaults	Default field mapping, statuses, priorities, and model config
@tasknotes/model/config	Model config resolution and tasknotes-spec field mapping helpers
@tasknotes/model/date	Date parsing, validation, comparison, and storage formatting
@tasknotes/model/mapping	TaskNotes frontmatter mapping, dependency mapping, and value normalization
@tasknotes/model/schema	Zod schemas for model validation
@tasknotes/model/recurrence	Recurrence evaluation, DTSTART handling, and schedule recalculation
@tasknotes/model/time	Time-entry sanitizing, timer plans, and duration totals
@tasknotes/model/validation	Task and time-entry validation
@tasknotes/model/operations	Host-independent task mutation planning, including materialized occurrence plans
@tasknotes/model/frontmatter	Markdown task document parse/serialize helpers
@tasknotes/model/conformance	tasknotes-spec conformance operation dispatcher

Examples

Map TaskNotes frontmatter into normalized task data:

import { DEFAULT_FIELD_MAPPING, mapTaskFromFrontmatter } from "@tasknotes/model";

const task = mapTaskFromFrontmatter(
	DEFAULT_FIELD_MAPPING,
	{
		title: "Ship package",
		status: "open",
		priority: "normal",
		scheduled: "2026-06-01",
	},
	"Tasks/Ship package.md",
	false,
	[]
);

Advance a recurring task without doing any host IO:

import { completeRecurringTask } from "@tasknotes/model/recurrence";

const result = completeRecurringTask({
	recurrence: "FREQ=DAILY",
	scheduled: "2026-06-01",
	completionDate: "2026-06-01",
	completeInstances: [],
	skippedInstances: [],
});

// Host decides how to persist result.updatedRecurrence,
// result.nextScheduled, result.completeInstances, and result.skippedInstances.

Build a spec-normalized adapter update for a CLI or mdbase-style surface:

import { buildSpecCompleteTaskUpdate } from "@tasknotes/model/operations";

const plan = buildSpecCompleteTaskUpdate({
	frontmatter: {
		title: "Daily check",
		status: "open",
		priority: "normal",
		recurrence: "FREQ=DAILY",
		scheduled: "2026-06-01",
		completeInstances: [],
		skippedInstances: [],
	},
	targetDate: "2026-06-01",
	completedStatus: "done",
	currentTimestamp: new Date().toISOString(),
});

// plan.fields is spec-normalized. A host can denormalize it to its own field names
// before writing to a file, database, or collection.

Materialize and reconcile a recurring occurrence:

import {
	buildMaterializeOccurrencePlan,
	buildMaterializedOccurrenceCompletePlan,
} from "@tasknotes/model/operations";

const materialized = buildMaterializeOccurrencePlan({
	parentTask: {
		title: "Weekly review",
		status: "open",
		priority: "normal",
		path: "Tasks/Weekly review.md",
		archived: false,
		recurrence: "DTSTART:20260601;FREQ=WEEKLY;BYDAY=MO",
		occurrence_materialization: "on_completion",
		scheduled: "2026-06-01T09:30:00",
		timeEstimate: 45,
	},
	targetDate: "2026-06-01",
	currentTimestamp: "2026-05-31T12:00:00Z",
	templateTask: {
		contexts: ["work"],
	},
});

// Host creates materialized.occurrenceTask if materialized.created is true.
// Occurrence tasks inherit parent planning fields such as scheduled time,
// tags/projects/contexts, reminders, details, and time estimate, but not
// parent recurrence, complete/skipped instance history, or time entries.

const complete = buildMaterializedOccurrenceCompletePlan({
	occurrenceTask: {
		...materialized.occurrenceTask,
		path: "Tasks/Weekly review 2026-06-01.md",
		archived: false,
	},
	parentTask: materialized.parentTask,
	completedStatus: "done",
	currentTimestamp: "2026-06-01T17:00:00Z",
	maintainDueDateOffsetInRecurring: true,
});

// Host applies complete.occurrenceUpdates to the occurrence note and
// complete.parentUpdates to the recurring parent. If complete.materializeNextDate
// is present, the host can call buildMaterializeOccurrencePlan again for that date.

Start and stop time tracking:

import {
	buildStartTimeTrackingPlan,
	buildStopTimeTrackingPlan,
	getActiveTimeEntry,
} from "@tasknotes/model/time";

const start = buildStartTimeTrackingPlan(task, "2026-06-01T09:00:00Z");
const active = getActiveTimeEntry(start.updatedTask);

if (active) {
	const stop = buildStopTimeTrackingPlan(
		start.updatedTask,
		active,
		"2026-06-01T09:30:00Z"
	);
}

Development

From this package repository:

npm run build
npm test

The package build emits ESM, CommonJS, and TypeScript declaration output under dist. Release tooling should build it before packing or publishing.

The Obsidian plugin uses this package through its service layer and keeps runtime-only behavior, such as Obsidian vault writes, metadata-cache link resolution, notices, and plugin-specific clock hooks, outside the model package.