@type32/tasks 0.0.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,43 +1,278 @@
1
1
  # @type32/tasks
2
2
 
3
- One format for todos, calendar events and timelines. Each one is a **task**; its kind depends only on which time fields it has. The format lets apps define their own statuses, priorities, tags and fields while keeping a fixed meaning other apps can rely on. See [SPEC.md](./SPEC.md).
3
+ One file format for todos, calendar events and timelines, with a parser, validator, sync merge, recurrence expansion, iCalendar import/export and Markdown task files.
4
+
5
+ A todo, an event and a timeline bar are the same object, a **task**. Which one it is depends only on its time fields, so a todo app, a calendar and a timeline can all read the same data. Apps can define their own statuses, priorities, tags and fields, and each custom value maps to a fixed meaning (`done`, `high`, …) that other apps understand.
6
+
7
+ - **Format specification:** [SPEC.md](./SPEC.md), with every field and rule
8
+ - **Summary for AI coding assistants:** [llms.txt](./llms.txt)
9
+
10
+ ```sh
11
+ npm install @type32/tasks
12
+ ```
13
+
14
+ ESM only. Node ≥ 20.19, Bun, Deno, browsers.
15
+
16
+ ## The format in one minute
17
+
18
+ ```yaml
19
+ version: "1.0"
20
+ lists:
21
+ - { id: work, title: Work, color: "#3b82f6", updatedAt: 2026-11-09T10:00:00Z }
22
+ tasks:
23
+ - id: invoice # a todo: no start
24
+ title: Ship invoice
25
+ listId: work
26
+ due: 2026-11-12
27
+ values: { status: doing, priority: high, tags: [billing] }
28
+ updatedAt: 2026-11-09T10:00:00Z
29
+ - id: standup # an event: start + duration, repeating
30
+ title: Standup
31
+ start: 2026-11-10T09:30
32
+ duration: PT15M
33
+ timeZone: Europe/Berlin
34
+ recurrence: { freq: weekly, byDay: [{ day: mo }, { day: we }] }
35
+ updatedAt: 2026-11-09T10:00:00Z
36
+ - id: launch # a timeline bar: start + end, after the invoice
37
+ title: Launch
38
+ start: 2026-11-16
39
+ end: 2026-11-20
40
+ dependsOn: [invoice]
41
+ updatedAt: 2026-11-09T10:00:00Z
42
+ ```
43
+
44
+ | A task with | is a | shown as |
45
+ | -------------------------- | -------- | ---------------------------- |
46
+ | `start` + `end`/`duration` | `span` | calendar event, timeline bar |
47
+ | `start` only | `moment` | milestone |
48
+ | no `start` | `todo` | reminder, maybe with `due` |
49
+
50
+ - **Times:** dates (`2026-11-12`) mean all-day. Date-times (`2026-11-10T09:30`) are wall-clock times in the task's `timeZone`; with no zone they float, the same time everywhere. Bookkeeping times (`updatedAt`, `completedAt`) are UTC with `Z`.
51
+ - **`values`:** everything that describes a task lives here, keyed by field id. That covers the built-in `status`, `priority`, `tags`, `progress` and `location`, plus any custom field the document defines.
52
+
53
+ ## Read, validate, write
54
+
55
+ ```ts
56
+ import { parse, stringify, TasksFormatError } from "@type32/tasks";
57
+
58
+ try {
59
+ const doc = parse(text, "yaml"); // "json" | "yaml" | "toml"
60
+ const out = stringify(doc, "json"); // validates again, then writes; unknown keys are kept
61
+ } catch (error) {
62
+ if (!(error instanceof TasksFormatError)) throw error;
63
+ console.error(error.message); // one "path: message" line per problem, e.g.
64
+ // tasks.0.values.status: unknown option "shiped" for field "status"
65
+ for (const issue of error.issues) highlight(issue.path); // ["tasks", 0, "values", "status"]
66
+ }
67
+ ```
68
+
69
+ `validate(value)` checks an object you already have, for example from a database or after editing in code. Structural problems are reported first; rules that span fields (references, cycles, values) are checked once the structure is valid.
70
+
71
+ ## Create and edit tasks in code
72
+
73
+ Every change needs a new `updatedAt`, which sync relies on. Use UUIDs for ids.
4
74
 
5
75
  ```ts
6
- import { kindOf, parse, resolveFields, stringify } from "@type32/tasks";
76
+ import { validate, type Task, type TaskDocument } from "@type32/tasks";
77
+
78
+ const now = new Date().toISOString(); // "2026-11-09T10:00:00.000Z"
79
+ const task: Task = {
80
+ id: crypto.randomUUID(),
81
+ title: "Call the bank",
82
+ due: "2026-11-12",
83
+ updatedAt: now,
84
+ };
85
+ const doc: TaskDocument = validate({ version: "1.0", tasks: [task] });
7
86
 
8
- const doc = parse(text, "json"); // throws TasksFormatError with each problem's path
9
- const fields = resolveFields(doc); // built-in fields merged with the document's own
87
+ // Deleting: keep the record and mark it, so references and sync still work.
88
+ Object.assign(doc.tasks[0]!, { deletedAt: now, updatedAt: now });
89
+ ```
90
+
91
+ ## Statuses, priorities and custom fields
92
+
93
+ `resolveFields(doc)` returns every field, built-in and custom, with its options and their meanings. Use it to render pickers. Resolve it once and pass it to the query helpers below, which read meanings for you, custom statuses included:
94
+
95
+ ```ts
96
+ import {
97
+ blockers,
98
+ isComplete,
99
+ isOpen,
100
+ isOverdue,
101
+ priorityOf,
102
+ resolveFields,
103
+ statusOf,
104
+ } from "@type32/tasks";
105
+
106
+ const fields = resolveFields(doc); // once per document, not per task
107
+
108
+ statusOf(task, fields); // "todo" | "doing" | "done" | "cancelled"; a custom "shipped" mapped to done is "done"
109
+ priorityOf(task, fields); // "low" | "medium" | "high" | undefined
110
+ isComplete(task, fields); // status means done (cancelled isn't complete)
111
+ isOpen(task, fields); // not deleted, status todo or doing
112
+ isOverdue(task, fields, { timeZone: "America/New_York" }); // open and past due; all-day dues expire after their day
113
+ blockers(task, doc.tasks, fields); // unfinished tasks in dependsOn, for timelines
114
+
115
+ const inbox = doc.tasks.filter((t) => isOpen(t, fields));
116
+ ```
117
+
118
+ For `isOverdue`, `now` defaults to the current time and `timeZone` to the runtime's zone. The viewer's zone decides when an all-day or floating due date has passed. A timed due on a task with a `timeZone` is read in that zone.
119
+
120
+ A document adds its own statuses, or any field, under `fields`. Each custom option maps to a built-in category, so other apps still know what it means:
121
+
122
+ ```yaml
123
+ fields:
124
+ - id: status
125
+ options: [{ id: shipped, title: "Shipped 🚀", category: done, updatedAt: 2026-11-09T10:00:00Z }]
126
+ - { id: estimate, title: Estimate (h), type: number, min: 0, updatedAt: 2026-11-09T10:00:00Z }
127
+ ```
128
+
129
+ ## Calendar views: occurrences in a range
130
+
131
+ ```ts
132
+ import { occurrences } from "@type32/tasks";
133
+
134
+ // Every occurrence overlapping November, recurrence expanded, DST handled. `to` is exclusive.
10
135
  for (const task of doc.tasks) {
11
- const status = fields.status!.options.find((o) => o.id === task.values?.status);
12
- console.log(kindOf(task), task.title, status?.category ?? "todo");
136
+ for (const o of occurrences(task, {
137
+ from: "2026-11-01",
138
+ to: "2026-12-01",
139
+ timeZone: "America/New_York",
140
+ })) {
141
+ draw(task, o.start, o.end, o.due); // strings in the task's own form; `end` is inclusive for all-day tasks
142
+ }
13
143
  }
14
- const out = stringify(doc, "json"); // validates first; unknown keys survive
15
144
  ```
16
145
 
17
- | Export | Does |
18
- | ----------------------------- | ------------------------------------------------------------------------------------------------- |
19
- | `parse(text, format)` | `"json"`, `"yaml"` or `"toml"` text → validated `TaskDocument` |
20
- | `stringify(doc, format)` | Validated `TaskDocument` → text. YAML is quoted so YAML 1.1 readers agree |
21
- | `validate(value)` | Checks an already-parsed object |
22
- | `resolveFields(doc)` | Built-in and custom fields with their options |
23
- | `kindOf(task)` | `"span"`, `"moment"` or `"todo"` |
24
- | `merge(a, b)` | Combines two copies for sync: `{ document, repairs }`. See SPEC "Merging" |
25
- | `occurrences(task, range)` | A task's occurrences overlapping `[from, to)`, with recurrence expanded and DST handled |
26
- | `toICS(doc)`, `fromICS(text)` | iCalendar export and import. Import returns `{ document, dropped }`. See SPEC "iCalendar mapping" |
27
- | `documentSchema` | The Zod schema (cross-field rules included) |
28
- | `@type32/tasks/schema.json` | JSON Schema for editor completion (structure only) |
146
+ `timeZone` is the viewer's zone. It decides which day a zoned event falls on; floating and all-day tasks ignore it. It works for any task: one without `recurrence` has at most one occurrence. A task with no `start` and no `due` has none.
29
147
 
30
- For YAML editor completion, add `# yaml-language-server: $schema=https://unpkg.com/@type32/tasks/dist/schema.json` to the top of the file.
148
+ ## Completing tasks
31
149
 
32
- Requires Node ≥ 20.19 or any modern runtime. ESM only.
150
+ ```ts
151
+ import { completeTask } from "@type32/tasks";
152
+
153
+ doc.tasks[i] = completeTask(doc.tasks[i]!, new Date().toISOString());
154
+ ```
155
+
156
+ - **One-off task, or the last occurrence of a series:** `status` becomes `done` and `completedAt` is set.
157
+ - **Repeating task:** `start`, `end` and `due` move to the next occurrence, skipping excluded dates. `count` drops by the occurrences used up, and `status` and `progress` reset for the new occurrence. The series keeps its time of day through DST changes.
158
+
159
+ It returns a new task and leaves the input unchanged. `updatedAt` becomes the completion time.
160
+
161
+ ## Sync between devices
162
+
163
+ ```ts
164
+ import { merge } from "@type32/tasks";
165
+
166
+ const { document, repairs } = merge(local, remote); // same result on every device, whichever side runs it
167
+ save(document);
168
+ for (const r of repairs) notify(r.message); // e.g. a value dropped because its field changed type
169
+ ```
170
+
171
+ - **Matching:** records (lists, tasks, custom fields, each option) match by `id`, and the later `updatedAt` wins.
172
+ - **Repairs:** two edits that are each valid can still conflict, like two devices moving tasks under each other. `merge` repairs the result so it stays valid, and lists every change in `repairs`, including what was removed.
173
+ - **Order:** record order is not synced.
174
+
175
+ ## Markdown task files (Obsidian-style vaults)
176
+
177
+ A Markdown file can hold one task under `task:` in its frontmatter. The body becomes `notes`, and other frontmatter keys are kept.
178
+
179
+ ```markdown
180
+ ---
181
+ aliases: [invoice]
182
+ task:
183
+ id: invoice
184
+ title: Ship invoice
185
+ due: 2026-11-12
186
+ updatedAt: 2026-11-09T10:00:00Z
187
+ ---
188
+
189
+ # Ship invoice
190
+
191
+ - [ ] attach PDF
192
+ ```
193
+
194
+ ```ts
195
+ import { isTaskFile, parseMarkdown, stringifyMarkdown, validate } from "@type32/tasks";
196
+
197
+ if (isTaskFile(text)) {
198
+ // cheap and never throws: fine for indexing thousands of files
199
+ const file = parseMarkdown(text); // { task, frontmatter, syntax: "yaml" | "toml" }
200
+ file.task.title = "Ship invoice v2";
201
+ file.task.updatedAt = new Date().toISOString();
202
+ write(path, stringifyMarkdown(file)); // body unchanged byte for byte
203
+ }
204
+
205
+ // One file can't check references to other files; validate the vault as a whole document.
206
+ const tasks = texts.filter(isTaskFile).map((t) => parseMarkdown(t).task);
207
+ const vault = validate({ version: "1.0", lists, fields, tasks });
208
+ ```
209
+
210
+ ## iCalendar (.ics)
211
+
212
+ ```ts
213
+ import { fromICS, toICS } from "@type32/tasks";
214
+
215
+ const { document, dropped } = fromICS(icsText); // from Google, Apple, Outlook…
216
+ for (const d of dropped) console.warn(d.path.join("."), d.message); // what couldn't be imported, and why
217
+
218
+ const ics = toICS(doc); // tasks with start and no due → VEVENT, the rest → VTODO
219
+ ```
220
+
221
+ Import never guesses. Anything the format can't represent is dropped and listed, for example `BYSETPOS` rules, single changed occurrences, or Windows time zone names. Export loses lists, custom fields and unknown keys. The full mapping is in [SPEC.md](./SPEC.md#icalendar-mapping).
222
+
223
+ ## Editor completion
224
+
225
+ `@type32/tasks/schema.json` is a JSON Schema for the document's structure; the cross-field rules are only checked by `validate`. In YAML files:
226
+
227
+ ```yaml
228
+ # yaml-language-server: $schema=https://unpkg.com/@type32/tasks/dist/schema.json
229
+ ```
230
+
231
+ ## Common mistakes
232
+
233
+ - **Dates are strings.** The library never returns `Date` objects. Compare dates of the same form as strings, or use `occurrences`.
234
+ - **Forgetting `updatedAt`.** Without a newer `updatedAt`, `merge` may keep the other device's version.
235
+ - **Deleting records outright.** Set `deletedAt` instead, so references stay valid and other devices learn about the deletion.
236
+ - **A `values` key with no field definition.** That's an error, which catches typos. Define custom fields under `fields` first.
237
+ - **Off-by-one all-day ends.** A date `end` is inclusive: `start: 2026-11-10, end: 2026-11-12` is three days. iCalendar's exclusive end is handled for you.
238
+ - **`end` and `duration` together.** Use one or the other.
239
+ - **Validating one Markdown file at a time.** `parseMarkdown` only checks that file. References and values need `validate` on the combined document.
240
+ - **Writing `null` to TOML.** TOML has no `null`, so `stringify(doc, "toml")` throws if an unknown key holds one.
241
+ - **Expecting key order to survive.** Written files use a fixed key order (`id`, `updatedAt`, then the rest), so expect one-time reordering diffs.
242
+
243
+ ## API
244
+
245
+ | Export | Does |
246
+ | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
247
+ | `parse(text, format): TaskDocument` | Read and validate JSON, YAML or TOML. Throws `TasksFormatError` |
248
+ | `stringify(doc, format): string` | Validate, then write |
249
+ | `validate(value): TaskDocument` | Validate an object |
250
+ | `resolveFields(doc): Record<string, ResolvedField>` | Built-in and custom fields with their options and categories |
251
+ | `kindOf(task): "span" \| "moment" \| "todo"` | How to draw a task |
252
+ | `statusOf`, `priorityOf`, `isComplete`, `isOpen`, `isOverdue`, `blockers` | What a task's values mean, given `resolveFields(doc)`. See "Statuses, priorities and custom fields" |
253
+ | `occurrences(task, { from, to, timeZone? }): Occurrence[]` | Occurrences overlapping `[from, to)` |
254
+ | `completeTask(task, completedAt): Task` | Mark done, or move a repeating task to its next occurrence |
255
+ | `merge(a, b): { document, repairs }` | Combine two copies for sync |
256
+ | `toICS(doc): string`, `fromICS(text): { document, dropped }` | iCalendar export and import |
257
+ | `parseMarkdown(text): MarkdownTask`, `stringifyMarkdown(file): string` | Markdown task files |
258
+ | `isTaskFile(text): boolean` | Whether a Markdown file holds a task. Never throws |
259
+ | `TasksFormatError` | `.issues: { path, message }[]`; `.message` is ready to show |
260
+ | `documentSchema` | The Zod schema behind `validate` |
261
+ | `@type32/tasks/schema.json` | JSON Schema of the structure |
262
+
263
+ Every exported type and function is documented in its type declarations, so editors show the rules on hover.
33
264
 
34
265
  ## Development
35
266
 
36
- | Script | Does |
37
- | ------------------- | -------------------------------------------------- |
38
- | `bun run build` | Bundle to `dist/`, with `.d.mts` and `schema.json` |
39
- | `bun run test` | Vitest once (`test:watch` to watch) |
40
- | `bun run check` | lint + format:check + typecheck + test |
41
- | `bun run changeset` | Record a change for the next release |
267
+ | Script | Does |
268
+ | ------------------- | ----------------------------------------------------------------------- |
269
+ | `bun run build` | Bundle to `dist/`, with `.d.mts` and `schema.json` |
270
+ | `bun run test` | Vitest once (`test:watch` to watch) |
271
+ | `bun run check` | lint + format:check + typecheck + test |
272
+ | `bun run bench` | Benchmarks the built package; add `--json` for machine-readable results |
273
+ | `bun run changeset` | Record a change for the next release |
274
+
275
+ - **`conformance/`** holds cases written as data, not code, so any implementation of the format can run them. `errors.yaml` has broken inputs and the issue paths they must report; `valid.yaml` has unusual inputs and their exact result. `src/conformance.test.ts` runs them here.
276
+ - **`bench/baseline.json`** is a reference benchmark run (Node 26, Apple silicon) to compare other implementations against.
42
277
 
43
278
  Run `bun run changeset` in your PR. On merge to `main`, the Release workflow opens a "Version Packages" PR; merging it publishes to npm. The lowest TypeScript version supported for consumers is 6.0.3, and CI typechecks against it.
package/SPEC.md ADDED
@@ -0,0 +1,269 @@
1
+ # Tasks format 1.0
2
+
3
+ One document format for todos, calendar events and timelines. A todo, an event and a timeline bar are the same object, a **task**; which one it is depends only on which time fields it has. Field names and meanings follow [JSCalendar (RFC 8984)](https://www.rfc-editor.org/rfc/rfc8984) where they overlap, so conversion stays mechanical.
4
+
5
+ A document can be written as JSON, YAML or TOML; the data model is identical. Every date and time is a string in the data model: unquoted YAML dates and native TOML date/time values are read as the equivalent string (TOML `2026-11-10T09:30:00` → `"2026-11-10T09:30:00.000"`). TOML has no `null`, so a document holding one can't be written as TOML.
6
+
7
+ ## Document
8
+
9
+ ```yaml
10
+ version: "1.0"
11
+ lists: [] # optional
12
+ fields: [] # optional
13
+ tasks: []
14
+ ```
15
+
16
+ | Key | Type | Required | Notes |
17
+ | --------- | ------------------ | -------- | ----------------------------------------------------- |
18
+ | `version` | string | yes | `"1.<minor>"`. Readers reject other majors. |
19
+ | `lists` | [List](#list)[] | no | Containers: todo lists, calendars, timeline projects. |
20
+ | `fields` | [Field](#fields)[] | no | Custom fields, and options added to built-in ones. |
21
+ | `tasks` | [Task](#task)[] | yes | |
22
+
23
+ Every object in the format keeps keys it doesn't define. Readers must write unknown keys back unchanged.
24
+
25
+ ## Value types
26
+
27
+ | Name | Example | Rules |
28
+ | ------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
29
+ | Id | `"7f3a2c…"` | Non-empty string, unique within its collection. UUIDs recommended for anything synced. |
30
+ | LocalDate | `"2026-11-09"` | A real calendar date. As a task time it means all-day. |
31
+ | LocalDateTime | `"2026-11-09T10:00"`, `"…T10:00:30.5"` | No offset, no `Z`. Read in the task's `timeZone`; without one it floats (same wall-clock time everywhere). |
32
+ | UTCDateTime | `"2026-11-09T10:00:00Z"` | Always UTC with `Z`. Used for bookkeeping times. |
33
+ | Duration | `"PT1H30M"`, `"P1D"`, `"P2W"` | ISO 8601 without years or months (they have no fixed length). |
34
+ | TimeZone | `"Europe/Berlin"` | IANA name. Offsets like `+01:00` are not time zones. |
35
+ | Color | `"#3b82f6"` | `#rrggbb` only, so every platform can read it. |
36
+
37
+ ## Sync bookkeeping
38
+
39
+ Lists, custom fields, field options and tasks are **synced records**:
40
+
41
+ | Key | Type | Required | Notes |
42
+ | ----------- | ----------- | -------- | ---------------------------------------------------------------------- |
43
+ | `id` | Id | yes | |
44
+ | `updatedAt` | UTCDateTime | yes | Set on every change. Merging keeps the record with the later value. |
45
+ | `deletedAt` | UTCDateTime | no | Marks the record deleted. It stays in the document so references hold. |
46
+
47
+ A deleted record is still a valid reference target. Apps show it as archived or hide it.
48
+
49
+ ### Merging
50
+
51
+ Two copies of a document merge record by record, so any implementation reaches the same content:
52
+
53
+ 1. Records match by `id` within lists, tasks, custom fields, and each field's options. A record only one side has is kept.
54
+ 2. The record with the later `updatedAt` instant wins whole. Compare instants, not text: `…:00Z` equals `…:00.000Z`.
55
+ 3. On equal instants, a record with `deletedAt` wins; otherwise the one whose JSON with keys sorted is larger, comparing UTF-16 code units.
56
+ 4. A field definition's options merge one by one, independently of which definition won. Built-in field entries have no `updatedAt`, so only their options matter.
57
+ 5. Unknown top-level keys follow rule 3's JSON comparison. `version` takes the higher minor.
58
+
59
+ Two valid copies can still combine into an invalid document. Repair it like this and tell the user what was removed:
60
+
61
+ - **Cycles** in `parentId` or `dependsOn` (tasks) or `parentId` (lists): within the loop, find the record that wins by rules 2–3 and remove its link to the next record. This undoes the later move.
62
+ - **Options** that don't fit the winning field definition: drop every option when the field is no longer a select; mark deleted an option whose category the field no longer has (values using it stay valid); remove `category` from options when the field has no categories anymore.
63
+ - **Values** that no longer fit their field (type or range): remove them from `values`.
64
+
65
+ Every record a repair changes gets `updatedAt` one millisecond later than its own. The repaired version then wins against both copies it came from, so merging a stale copy again doesn't undo the repair, and every device still computes the same result.
66
+
67
+ Order is not synced: a merged collection keeps the first copy's order and appends records only the second copy has.
68
+
69
+ ## List
70
+
71
+ | Key | Type | Required | Notes |
72
+ | ---------- | ------ | -------- | ------------------------------------ |
73
+ | `title` | string | yes | |
74
+ | `color` | Color | no | |
75
+ | `parentId` | Id | no | Another list; lists nest. No cycles. |
76
+
77
+ ## Task
78
+
79
+ | Key | Type | Notes |
80
+ | --------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
81
+ | `title` | string | Required. |
82
+ | `notes` | string | |
83
+ | `listId` | Id | Must name a list. |
84
+ | `parentId` | Id | Parent task (subtask). No cycles. |
85
+ | `dependsOn` | Id[] | Tasks that must finish first. No cycles. |
86
+ | `start` | LocalDate \| LocalDateTime | |
87
+ | `end` | LocalDate \| LocalDateTime | Needs `start`, same form as `start`, not before it. Excludes `duration`. A date `end` is inclusive (`start: 2026-11-10, end: 2026-11-12` is three days); a date-time `end` is the exact end. |
88
+ | `duration` | Duration | Needs `start`. All-day starts take whole days or weeks only. Days are calendar days, hours are elapsed time (a DST change can shift the end's wall-clock time). |
89
+ | `due` | LocalDate \| LocalDateTime | |
90
+ | `timeZone` | TimeZone | Applies to every local time on the task. Absent: floating. |
91
+ | `recurrence` | [Recurrence](#recurrence) | Needs `start` or `due`. |
92
+ | `excludedDates` | (LocalDate \| LocalDateTime)[] | Occurrences to skip. Needs `recurrence`; same form as the anchor. |
93
+ | `completedAt` | UTCDateTime | |
94
+ | `values` | object | Field id → value. See [Fields](#fields). |
95
+
96
+ ### Kind
97
+
98
+ A task's kind is never stored. Apps derive it:
99
+
100
+ | Time fields | Kind | Typically shown as |
101
+ | --------------------------------- | -------- | ------------------------------- |
102
+ | `start` and (`end` or `duration`) | `span` | Calendar event, timeline bar |
103
+ | `start` only | `moment` | Milestone |
104
+ | no `start` | `todo` | Reminder, optionally with `due` |
105
+
106
+ Any app can show any task. A todo app can list events; a calendar can place todos on their `due` date.
107
+
108
+ ### Recurrence
109
+
110
+ The rule repeats the task's anchor: `start`, or `due` when there is no `start`. Unknown keys are an error here, because silently ignoring one would change which dates recur.
111
+
112
+ | Key | Type | Notes |
113
+ | ------------ | -------------------------------------- | -------------------------------------------------------------------------------------- |
114
+ | `freq` | `daily \| weekly \| monthly \| yearly` | Required. |
115
+ | `interval` | integer ≥ 1 | Every n-th period. Default 1. |
116
+ | `byDay` | `{ day, nth? }[]` | `day`: `mo tu we th fr sa su`. `nth` (±1…53, `-1` = last) only with monthly or yearly. |
117
+ | `byMonthDay` | integer[] | ±1…31; negative counts from the month's end. |
118
+ | `byMonth` | integer[] | 1…12. |
119
+ | `count` | integer ≥ 1 | Total occurrences. Excludes `until`. |
120
+ | `until` | LocalDate \| LocalDateTime | Last possible occurrence, inclusive. Same form as the anchor. |
121
+
122
+ Expanding a rule:
123
+
124
+ - The anchor is always the first occurrence, even if the rule wouldn't produce it.
125
+ - Weeks start on Monday.
126
+ - Dates that don't exist are skipped, not moved: the 31st in a 30-day month, 29 February outside leap years.
127
+ - Occurrences keep the anchor's wall-clock time in `timeZone`. A time skipped by a DST change moves forward by the gap (02:30 → 03:30).
128
+ - `count` includes occurrences removed by `excludedDates`.
129
+ - `end` and `due` move with each occurrence by their offset from `start`.
130
+
131
+ Completing a recurring todo moves it to the next occurrence instead of marking it done:
132
+
133
+ - `start`, `end` and `due` move to the next occurrence after the anchor, keeping their offsets from it. The anchor moves to the rule's wall-clock time, not a DST-adjusted one, so the series keeps its time of day.
134
+ - `count` drops by the number of occurrences used up, excluded ones included, so the remaining series is unchanged.
135
+ - `status` and `progress`, if set, reset to `todo` and 0. `completedAt` is left alone.
136
+ - With no occurrence left, the task is completed like a one-off task: `status: done` and `completedAt` set.
137
+
138
+ ## Fields
139
+
140
+ Everything that describes a task lives in `values`, keyed by field id. Statuses, priorities and tags are fields like any custom one; they just come predefined.
141
+
142
+ ```yaml
143
+ fields:
144
+ - id: status # built-in: add options or rename existing ones
145
+ options:
146
+ - { id: shipped, title: "Shipped 🚀", color: "#22c55e", category: done, updatedAt: … }
147
+ - id: stage # custom
148
+ title: Pipeline stage
149
+ type: select
150
+ categories: [lead, active, closed]
151
+ options:
152
+ - { id: proposal, title: Proposal sent, category: lead, updatedAt: … }
153
+ updatedAt: …
154
+ tasks:
155
+ - id: …
156
+ title: Ship invoice
157
+ values: { status: shipped, priority: high, tags: [billing], stage: proposal }
158
+ updatedAt: …
159
+ ```
160
+
161
+ ### Field definition
162
+
163
+ A custom field is a synced record.
164
+
165
+ | Key | Type | Notes |
166
+ | ------------ | --------- | ---------------------------------------------------------------- |
167
+ | `title` | string | Required for custom fields. |
168
+ | `type` | FieldType | Required for custom fields. |
169
+ | `options` | Option[] | Select types only. |
170
+ | `categories` | string[] | Select types only. A fixed meaning every option maps to. Unique. |
171
+ | `open` | boolean | Select types only. Values outside `options` are allowed. |
172
+ | `min`, `max` | number | Number type only. |
173
+
174
+ | FieldType | Value |
175
+ | ------------- | -------------------------------- |
176
+ | `text` | string |
177
+ | `number` | finite number within `min`/`max` |
178
+ | `boolean` | `true` / `false` |
179
+ | `date` | LocalDate or LocalDateTime |
180
+ | `url` | absolute URL string |
181
+ | `select` | one option id |
182
+ | `multiSelect` | option ids, no duplicates |
183
+
184
+ ### Option
185
+
186
+ An option is a synced record.
187
+
188
+ | Key | Type | Notes |
189
+ | ---------- | ------ | ---------------------------------------------------------------------------------------------- |
190
+ | `title` | string | Required, except when renaming a built-in option. |
191
+ | `color` | Color | |
192
+ | `category` | string | Required when the field has `categories`; must be one of them. Deleted options aren't checked. |
193
+
194
+ Every option merges on its own, so two devices adding options at the same time both keep theirs.
195
+
196
+ ### Built-in fields
197
+
198
+ Always present. A document may list a built-in field only to add options to it, or to change a built-in option's `title` and `color` by reusing its id. Its type, categories and other settings are locked, built-in options keep their category and can't be deleted.
199
+
200
+ | Id | Type | Categories | Options |
201
+ | ---------- | ----------- | --------------------------- | -------------------------- |
202
+ | `status` | select | `todo doing done cancelled` | one per category, same ids |
203
+ | `priority` | select | `low medium high` | one per category, same ids |
204
+ | `tags` | multiSelect | none, `open` | none |
205
+ | `progress` | number | 0–100 | |
206
+ | `location` | text | | |
207
+
208
+ Built-in categories are what other apps rely on: any app knows a task with status `shipped` is done because `shipped` maps to `done`. A task without a status counts as `todo`.
209
+
210
+ ## Markdown task files
211
+
212
+ A Markdown file can hold one task. Its frontmatter, YAML between `---` lines or TOML between `+++` lines starting on the first line, has a `task` object; the body after the closing fence is the task's `notes`, byte for byte. Other frontmatter keys belong to the note and are kept.
213
+
214
+ ```markdown
215
+ ---
216
+ aliases: [invoice]
217
+ task:
218
+ id: invoice
219
+ title: Ship invoice
220
+ due: 2026-11-12
221
+ values: { status: todo }
222
+ updatedAt: 2026-11-09T10:00:00Z
223
+ ---
224
+
225
+ # Ship invoice
226
+
227
+ - [ ] attach PDF
228
+ ```
229
+
230
+ - `task.notes` must not appear in the frontmatter; the body is the notes.
231
+ - A file is a task file exactly when its frontmatter has a `task` object; an invalid task is still a task file.
232
+ - A file on its own is checked for the task's shape and time rules. References and `values` need the other tasks and the field definitions, so they're checked once the tasks form a document.
233
+
234
+ ## iCalendar mapping
235
+
236
+ Informative. How `toICS`/`fromICS` map to RFC 5545; other implementations should map the same way.
237
+
238
+ A task exports as a **VEVENT** when it has `start`, no `due`, and no status other than `cancelled`; otherwise as a **VTODO**. Deleted tasks are skipped.
239
+
240
+ | Task | iCalendar |
241
+ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------ |
242
+ | `id` | `UID` |
243
+ | `updatedAt` | `LAST-MODIFIED` and `DTSTAMP`. Import prefers `LAST-MODIFIED`; neither → `1970-01-01T00:00:00Z` |
244
+ | `title`, `notes`, `values.location` | `SUMMARY`, `DESCRIPTION`, `LOCATION` |
245
+ | `start`, `due` | `DTSTART`, `DUE`, with `VALUE=DATE` for dates and `TZID=<IANA>` from `timeZone`. `timeZone: UTC` writes `…Z` |
246
+ | `end` | VEVENT `DTEND`, one day later for dates (iCalendar ends are exclusive). VTODO: `DURATION` |
247
+ | `duration` | `DURATION` |
248
+ | status category | `STATUS`: todo `NEEDS-ACTION`, doing `IN-PROCESS`, done `COMPLETED`, cancelled `CANCELLED` |
249
+ | priority category | `PRIORITY`: high 1, medium 5, low 9. Import: 1–4 high, 5 medium, 6–9 low |
250
+ | `values.progress`, `completedAt` | VTODO `PERCENT-COMPLETE`, `COMPLETED` |
251
+ | `values.tags` | `CATEGORIES` |
252
+ | `parentId` | `RELATED-TO;RELTYPE=PARENT` (the default `RELTYPE`) |
253
+ | `dependsOn` | `RELATED-TO;RELTYPE=DEPENDS-ON` (RFC 9253). Import also reads `FINISHTOSTART` from the predecessor |
254
+ | `recurrence`, `excludedDates` | `RRULE`, `EXDATE`. `UNTIL` is written in UTC when the task has a time zone |
255
+
256
+ Time zones are referenced by IANA name without `VTIMEZONE` blocks (RFC 7809). On import, every time is converted to the zone of `DTSTART` (or `DUE`).
257
+
258
+ **Lost on export:** lists, custom fields, custom status and priority options (exported as their category), unknown keys, deleted tasks.
259
+
260
+ **Dropped on import, and reported:**
261
+
262
+ - whole components: `RRULE` parts other than `FREQ` (daily to yearly), `INTERVAL`, `COUNT`, `UNTIL`, `BYDAY`, `BYMONTHDAY`, `BYMONTH`, and `WKST` (`WKST` is dropped only where it changes results); changed occurrences (`RECURRENCE-ID`); TZIDs that aren't IANA names; components that break a rule of this spec
263
+ - single properties: `RDATE`, and relations to tasks not in the file
264
+
265
+ Ignored on import: alarms, attendees, and other properties without a counterpart.
266
+
267
+ ## Validity
268
+
269
+ A reader must reject a document that breaks any rule above and should report each problem with its path (e.g. `tasks.3.values.status`). A value in `values` whose key names no field is an error.