@type32/tasks 0.1.2 → 0.3.0
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 +28 -3
- package/SPEC.md +61 -28
- package/conformance/errors.yaml +48 -0
- package/conformance/valid.yaml +42 -0
- package/dist/index.d.mts +39 -6
- package/dist/index.mjs +199 -17
- package/dist/schema.json +69 -0
- package/llms.txt +6 -2
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -16,14 +16,23 @@ ESM only. Node ≥ 20.19, Bun, Deno, browsers.
|
|
|
16
16
|
## The format in one minute
|
|
17
17
|
|
|
18
18
|
```yaml
|
|
19
|
-
version: "1.
|
|
19
|
+
version: "1.1"
|
|
20
20
|
lists:
|
|
21
21
|
- { id: work, title: Work, color: "#3b82f6", updatedAt: 2026-11-09T10:00:00Z }
|
|
22
|
+
views:
|
|
23
|
+
- {
|
|
24
|
+
id: board,
|
|
25
|
+
title: Board,
|
|
26
|
+
type: board,
|
|
27
|
+
groupBy: values.status,
|
|
28
|
+
updatedAt: 2026-11-09T10:00:00Z,
|
|
29
|
+
}
|
|
22
30
|
tasks:
|
|
23
31
|
- id: invoice # a todo: no start
|
|
24
32
|
title: Ship invoice
|
|
25
33
|
listId: work
|
|
26
34
|
due: 2026-11-12
|
|
35
|
+
starred: true
|
|
27
36
|
values: { status: doing, priority: high, tags: [billing] }
|
|
28
37
|
updatedAt: 2026-11-09T10:00:00Z
|
|
29
38
|
- id: standup # an event: start + duration, repeating
|
|
@@ -82,7 +91,7 @@ const task: Task = {
|
|
|
82
91
|
due: "2026-11-12",
|
|
83
92
|
updatedAt: now,
|
|
84
93
|
};
|
|
85
|
-
const doc: TaskDocument = validate({ version: "1.
|
|
94
|
+
const doc: TaskDocument = validate({ version: "1.1", tasks: [task] });
|
|
86
95
|
|
|
87
96
|
// Deleting: keep the record and mark it, so references and sync still work.
|
|
88
97
|
Object.assign(doc.tasks[0]!, { deletedAt: now, updatedAt: now });
|
|
@@ -126,6 +135,21 @@ fields:
|
|
|
126
135
|
- { id: estimate, title: Estimate (h), type: number, min: 0, updatedAt: 2026-11-09T10:00:00Z }
|
|
127
136
|
```
|
|
128
137
|
|
|
138
|
+
## Views: boards, lists and calendars saved in the file
|
|
139
|
+
|
|
140
|
+
A document can keep its views, so every app that opens it shows the same board. A view has a `type` (`list`, `board`, `calendar`, `timeline`, `table`), and optionally `groupBy`, `sortBy`, `sortDescending`, `listIds`, `openOnly`, `scale` and `zoom` (a timeline's pixels a day). Group and sort keys are task keys (`listId`, `due`, `starred`…) or `values.<field id>`. An app keeps its own settings for a view on it as extra keys.
|
|
141
|
+
|
|
142
|
+
A task can carry its own `color`, and the built-in `assignees` field lists the people it's for: the document names them as the field's options (`{ id, title, color }`), and `values.assignees` holds their ids. iCalendar maps them to `ATTENDEE`.
|
|
143
|
+
|
|
144
|
+
```ts
|
|
145
|
+
import { resolveFields, viewTasks } from "@type32/tasks";
|
|
146
|
+
|
|
147
|
+
const fields = resolveFields(doc);
|
|
148
|
+
for (const view of doc.views ?? []) {
|
|
149
|
+
const tasks = viewTasks(doc, view, fields); // filtered and sorted as the view says; grouping is yours to draw
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
129
153
|
## Calendar views: occurrences in a range
|
|
130
154
|
|
|
131
155
|
```ts
|
|
@@ -168,7 +192,7 @@ save(document);
|
|
|
168
192
|
for (const r of repairs) notify(r.message); // e.g. a value dropped because its field changed type
|
|
169
193
|
```
|
|
170
194
|
|
|
171
|
-
- **Matching:** records (lists, tasks, custom fields, each option) match by `id`, and the later `updatedAt` wins.
|
|
195
|
+
- **Matching:** records (lists, views, tasks, custom fields, each option) match by `id`, and the later `updatedAt` wins.
|
|
172
196
|
- **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
197
|
- **Order:** record order is not synced.
|
|
174
198
|
|
|
@@ -250,6 +274,7 @@ Import never guesses. Anything the format can't represent is dropped and listed,
|
|
|
250
274
|
| `resolveFields(doc): Record<string, ResolvedField>` | Built-in and custom fields with their options and categories |
|
|
251
275
|
| `kindOf(task): "span" \| "moment" \| "todo"` | How to draw a task |
|
|
252
276
|
| `statusOf`, `priorityOf`, `isComplete`, `isOpen`, `isOverdue`, `blockers` | What a task's values mean, given `resolveFields(doc)`. See "Statuses, priorities and custom fields" |
|
|
277
|
+
| `viewTasks(doc, view, fields): Task[]` | A view's tasks, filtered and sorted |
|
|
253
278
|
| `occurrences(task, { from, to, timeZone? }): Occurrence[]` | Occurrences overlapping `[from, to)` |
|
|
254
279
|
| `completeTask(task, completedAt): Task` | Mark done, or move a repeating task to its next occurrence |
|
|
255
280
|
| `merge(a, b): { document, repairs }` | Combine two copies for sync |
|
package/SPEC.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Tasks format 1.
|
|
1
|
+
# Tasks format 1.2
|
|
2
2
|
|
|
3
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
4
|
|
|
@@ -7,9 +7,10 @@ A document can be written as JSON, YAML or TOML; the data model is identical. Ev
|
|
|
7
7
|
## Document
|
|
8
8
|
|
|
9
9
|
```yaml
|
|
10
|
-
version: "1.
|
|
10
|
+
version: "1.2"
|
|
11
11
|
lists: [] # optional
|
|
12
12
|
fields: [] # optional
|
|
13
|
+
views: [] # optional
|
|
13
14
|
tasks: []
|
|
14
15
|
```
|
|
15
16
|
|
|
@@ -18,8 +19,11 @@ tasks: []
|
|
|
18
19
|
| `version` | string | yes | `"1.<minor>"`. Readers reject other majors. |
|
|
19
20
|
| `lists` | [List](#list)[] | no | Containers: todo lists, calendars, timeline projects. |
|
|
20
21
|
| `fields` | [Field](#fields)[] | no | Custom fields, and options added to built-in ones. |
|
|
22
|
+
| `views` | [View](#view)[] | no | Saved ways of showing the tasks: boards, calendars… |
|
|
21
23
|
| `tasks` | [Task](#task)[] | yes | |
|
|
22
24
|
|
|
25
|
+
Version 1.1 added `views` and a task's `starred`. A 1.0 reader keeps both as unknown keys.
|
|
26
|
+
|
|
23
27
|
Every object in the format keeps keys it doesn't define. Readers must write unknown keys back unchanged.
|
|
24
28
|
|
|
25
29
|
## Value types
|
|
@@ -36,7 +40,7 @@ Every object in the format keeps keys it doesn't define. Readers must write unkn
|
|
|
36
40
|
|
|
37
41
|
## Sync bookkeeping
|
|
38
42
|
|
|
39
|
-
Lists, custom fields, field options and tasks are **synced records**:
|
|
43
|
+
Lists, views, custom fields, field options and tasks are **synced records**:
|
|
40
44
|
|
|
41
45
|
| Key | Type | Required | Notes |
|
|
42
46
|
| ----------- | ----------- | -------- | ---------------------------------------------------------------------- |
|
|
@@ -50,7 +54,7 @@ A deleted record is still a valid reference target. Apps show it as archived or
|
|
|
50
54
|
|
|
51
55
|
Two copies of a document merge record by record, so any implementation reaches the same content:
|
|
52
56
|
|
|
53
|
-
1. Records match by `id` within lists, tasks, custom fields, and each field's options. A record only one side has is kept.
|
|
57
|
+
1. Records match by `id` within lists, views, tasks, custom fields, and each field's options. A record only one side has is kept.
|
|
54
58
|
2. The record with the later `updatedAt` instant wins whole. Compare instants, not text: `…:00Z` equals `…:00.000Z`.
|
|
55
59
|
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
60
|
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.
|
|
@@ -61,6 +65,7 @@ Two valid copies can still combine into an invalid document. Repair it like this
|
|
|
61
65
|
- **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
66
|
- **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
67
|
- **Values** that no longer fit their field (type or range): remove them from `values`.
|
|
68
|
+
- **Views** grouped or sorted by a field that no longer can be (its type changed): remove `groupBy` or `sortBy`.
|
|
64
69
|
|
|
65
70
|
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
71
|
|
|
@@ -74,6 +79,28 @@ Order is not synced: a merged collection keeps the first copy's order and append
|
|
|
74
79
|
| `color` | Color | no | |
|
|
75
80
|
| `parentId` | Id | no | Another list; lists nest. No cycles. |
|
|
76
81
|
|
|
82
|
+
## View
|
|
83
|
+
|
|
84
|
+
A saved way of showing the tasks, so every app that opens the document shows the same board or calendar. Apps keep their own settings for a view on it, as extra keys.
|
|
85
|
+
|
|
86
|
+
| Key | Type | Notes |
|
|
87
|
+
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
88
|
+
| `title` | string | Required. |
|
|
89
|
+
| `type` | string | Required, non-empty. `list`, `board`, `calendar`, `timeline` or `table`. Apps skip a view of a type they don't draw, and keep it. |
|
|
90
|
+
| `groupBy` | string | Sections, columns or rows: `listId`, `starred`, or `values.<field id>` of a `select`, `multiSelect` or `boolean` field. A task with several tags is in each tag's group. |
|
|
91
|
+
| `sortBy` | string | `title`, `start`, `end`, `due`, `completedAt`, `updatedAt`, `starred`, or `values.<field id>` of any field but a `multiSelect`. Absent: document order. |
|
|
92
|
+
| `sortDescending` | boolean | |
|
|
93
|
+
| `listIds` | Id[] | Only tasks in these lists or lists nested in them. Each must name a list. Absent: every task. |
|
|
94
|
+
| `openOnly` | boolean | Only open tasks: status `todo` or `doing`. |
|
|
95
|
+
| `scale` | string | Calendar: the period a page shows. Timeline: the period a column stands for. `day`, `week` or `month`; an app uses its default for a value it doesn't know. |
|
|
96
|
+
| `zoom` | number | Timeline: pixels a day, positive, for an app that zooms freely (1.2). It keeps `scale` at the preset nearest it, for apps that only know those. |
|
|
97
|
+
|
|
98
|
+
A view never shows deleted tasks. Sorting:
|
|
99
|
+
|
|
100
|
+
- Times sort as written, ignoring time zones: by the padded local value, so a date comes before the times on its day. UTC times sort by instant.
|
|
101
|
+
- A `select` sorts by its options' order (built-in options first, then the document's), a value outside the options after them; `boolean` false before true, and `starred` too, absent counting as false; text in the reader's locale.
|
|
102
|
+
- Tasks without the value come last in either direction. Ties keep document order.
|
|
103
|
+
|
|
77
104
|
## Task
|
|
78
105
|
|
|
79
106
|
| Key | Type | Notes |
|
|
@@ -91,6 +118,8 @@ Order is not synced: a merged collection keeps the first copy's order and append
|
|
|
91
118
|
| `recurrence` | [Recurrence](#recurrence) | Needs `start` or `due`. |
|
|
92
119
|
| `excludedDates` | (LocalDate \| LocalDateTime)[] | Occurrences to skip. Needs `recurrence`; same form as the anchor. |
|
|
93
120
|
| `completedAt` | UTCDateTime | |
|
|
121
|
+
| `starred` | boolean | Marked to stand out (a star or a flag). |
|
|
122
|
+
| `color` | Color | How apps draw the task (1.2). Absent: its list's `color`, then the app's own. |
|
|
94
123
|
| `values` | object | Field id → value. See [Fields](#fields). |
|
|
95
124
|
|
|
96
125
|
### Kind
|
|
@@ -197,13 +226,16 @@ Every option merges on its own, so two devices adding options at the same time b
|
|
|
197
226
|
|
|
198
227
|
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
228
|
|
|
200
|
-
| Id
|
|
201
|
-
|
|
|
202
|
-
| `status`
|
|
203
|
-
| `priority`
|
|
204
|
-
| `tags`
|
|
205
|
-
| `progress`
|
|
206
|
-
| `location`
|
|
229
|
+
| Id | Type | Categories | Options |
|
|
230
|
+
| ----------- | ----------- | --------------------------- | -------------------------- |
|
|
231
|
+
| `status` | select | `todo doing done cancelled` | one per category, same ids |
|
|
232
|
+
| `priority` | select | `low medium high` | one per category, same ids |
|
|
233
|
+
| `tags` | multiSelect | none, `open` | none |
|
|
234
|
+
| `progress` | number | 0–100 | |
|
|
235
|
+
| `location` | text | | |
|
|
236
|
+
| `assignees` | multiSelect | none | none: the people (1.2) |
|
|
237
|
+
|
|
238
|
+
`assignees` (1.2) lists the people a task is for. Its options are the people: `title` their name, `color` the colour apps draw them in, and any extra keys an app keeps (an `email`, for iCalendar). Values must be option ids, so a person is renamed once for every task. A 1.0 or 1.1 document that has a custom field named `assignees` must rename it before it's read as 1.2.
|
|
207
239
|
|
|
208
240
|
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
241
|
|
|
@@ -237,32 +269,33 @@ Informative. How `toICS`/`fromICS` map to RFC 5545; other implementations should
|
|
|
237
269
|
|
|
238
270
|
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
271
|
|
|
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
|
-
| `
|
|
253
|
-
| `
|
|
254
|
-
| `
|
|
272
|
+
| Task | iCalendar |
|
|
273
|
+
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
274
|
+
| `id` | `UID` |
|
|
275
|
+
| `updatedAt` | `LAST-MODIFIED` and `DTSTAMP`. Import prefers `LAST-MODIFIED`; neither → `1970-01-01T00:00:00Z` |
|
|
276
|
+
| `title`, `notes`, `values.location` | `SUMMARY`, `DESCRIPTION`, `LOCATION` |
|
|
277
|
+
| `start`, `due` | `DTSTART`, `DUE`, with `VALUE=DATE` for dates and `TZID=<IANA>` from `timeZone`. `timeZone: UTC` writes `…Z` |
|
|
278
|
+
| `end` | VEVENT `DTEND`, one day later for dates (iCalendar ends are exclusive). VTODO: `DURATION` |
|
|
279
|
+
| `duration` | `DURATION` |
|
|
280
|
+
| status category | `STATUS`: todo `NEEDS-ACTION`, doing `IN-PROCESS`, done `COMPLETED`, cancelled `CANCELLED` |
|
|
281
|
+
| priority category | `PRIORITY`: high 1, medium 5, low 9. Import: 1–4 high, 5 medium, 6–9 low |
|
|
282
|
+
| `values.progress`, `completedAt` | VTODO `PERCENT-COMPLETE`, `COMPLETED` |
|
|
283
|
+
| `values.tags` | `CATEGORIES` |
|
|
284
|
+
| `values.assignees` | `ATTENDEE;CN=<title>;X-TASKS-ID=<id>`, at `mailto:<email>` when the option has an `email`, else at `urn:x-tasks:assignee:<id>`. Import: the option is `X-TASKS-ID`, else the id in that URI, else the email, else `CN`; options are added to the document's `assignees` field |
|
|
285
|
+
| `parentId` | `RELATED-TO;RELTYPE=PARENT` (the default `RELTYPE`) |
|
|
286
|
+
| `dependsOn` | `RELATED-TO;RELTYPE=DEPENDS-ON` (RFC 9253). Import also reads `FINISHTOSTART` from the predecessor |
|
|
287
|
+
| `recurrence`, `excludedDates` | `RRULE`, `EXDATE`. `UNTIL` is written in UTC when the task has a time zone |
|
|
255
288
|
|
|
256
289
|
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
290
|
|
|
258
|
-
**Lost on export:** lists, custom fields, custom status and priority options (exported as their category), unknown keys, deleted tasks.
|
|
291
|
+
**Lost on export:** lists, views, custom fields, custom status and priority options (exported as their category), `starred`, `color`, unknown keys, deleted tasks.
|
|
259
292
|
|
|
260
293
|
**Dropped on import, and reported:**
|
|
261
294
|
|
|
262
295
|
- 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
296
|
- single properties: `RDATE`, and relations to tasks not in the file
|
|
264
297
|
|
|
265
|
-
Ignored on import: alarms, attendees, and other properties without a counterpart.
|
|
298
|
+
Ignored on import: alarms, attendees' roles and replies, and other properties without a counterpart.
|
|
266
299
|
|
|
267
300
|
## Validity
|
|
268
301
|
|
package/conformance/errors.yaml
CHANGED
|
@@ -529,6 +529,54 @@
|
|
|
529
529
|
tasks: []
|
|
530
530
|
issues: [[fields, 0, options, 1, id]]
|
|
531
531
|
|
|
532
|
+
# --- Views ---
|
|
533
|
+
- name: view without type and title
|
|
534
|
+
format: yaml
|
|
535
|
+
input: |
|
|
536
|
+
version: "1.1"
|
|
537
|
+
views: [{ id: v, updatedAt: 2026-11-09T10:00:00Z }]
|
|
538
|
+
tasks: []
|
|
539
|
+
issues: [[views, 0, title], [views, 0, type]]
|
|
540
|
+
- name: duplicate view id
|
|
541
|
+
format: yaml
|
|
542
|
+
input: |
|
|
543
|
+
version: "1.1"
|
|
544
|
+
views:
|
|
545
|
+
- { id: v, title: A, type: list, updatedAt: 2026-11-09T10:00:00Z }
|
|
546
|
+
- { id: v, title: B, type: board, updatedAt: 2026-11-09T10:00:00Z }
|
|
547
|
+
tasks: []
|
|
548
|
+
issues: [[views, 1, id]]
|
|
549
|
+
- name: view grouped by a text field, sorted by a multiSelect
|
|
550
|
+
format: yaml
|
|
551
|
+
input: |
|
|
552
|
+
version: "1.1"
|
|
553
|
+
views:
|
|
554
|
+
- { id: v, title: V, type: board, groupBy: values.location, sortBy: values.tags, updatedAt: 2026-11-09T10:00:00Z }
|
|
555
|
+
tasks: []
|
|
556
|
+
issues: [[views, 0, groupBy], [views, 0, sortBy]]
|
|
557
|
+
- name: view keys that aren't task keys or values paths
|
|
558
|
+
format: yaml
|
|
559
|
+
input: |
|
|
560
|
+
version: "1.1"
|
|
561
|
+
views:
|
|
562
|
+
- { id: v, title: V, type: board, groupBy: status, sortBy: notes, updatedAt: 2026-11-09T10:00:00Z }
|
|
563
|
+
tasks: []
|
|
564
|
+
issues: [[views, 0, groupBy], [views, 0, sortBy]]
|
|
565
|
+
- name: view of an undefined field and an unknown list
|
|
566
|
+
format: yaml
|
|
567
|
+
input: |
|
|
568
|
+
version: "1.1"
|
|
569
|
+
views:
|
|
570
|
+
- { id: v, title: V, type: list, sortBy: values.stage, listIds: [nope], updatedAt: 2026-11-09T10:00:00Z }
|
|
571
|
+
tasks: []
|
|
572
|
+
issues: [[views, 0, sortBy], [views, 0, listIds, 0]]
|
|
573
|
+
- name: starred that isn't a boolean
|
|
574
|
+
format: yaml
|
|
575
|
+
input: |
|
|
576
|
+
version: "1.1"
|
|
577
|
+
tasks: [{ id: a, title: A, starred: "yes", updatedAt: 2026-11-09T10:00:00Z }]
|
|
578
|
+
issues: [[tasks, 0, starred]]
|
|
579
|
+
|
|
532
580
|
# --- Markdown task files ---
|
|
533
581
|
- name: markdown without frontmatter
|
|
534
582
|
format: markdown
|
package/conformance/valid.yaml
CHANGED
|
@@ -163,6 +163,48 @@
|
|
|
163
163
|
},
|
|
164
164
|
]
|
|
165
165
|
|
|
166
|
+
- name: views of a type and scale no reader draws, an app's keys, a deleted field to group by, and a starred task
|
|
167
|
+
format: yaml
|
|
168
|
+
input: |
|
|
169
|
+
version: "1.1"
|
|
170
|
+
lists: [{ id: work, title: Work, updatedAt: 2026-11-09T10:00:00Z }]
|
|
171
|
+
fields:
|
|
172
|
+
- { id: done, title: Done, type: boolean, updatedAt: 2026-11-09T10:00:00Z, deletedAt: 2026-11-09T10:00:00Z }
|
|
173
|
+
views:
|
|
174
|
+
- { id: m, title: Map, type: map, scale: quarter, x-app: { zoom: 3 }, updatedAt: 2026-11-09T10:00:00Z }
|
|
175
|
+
- { id: b, title: Board, type: board, groupBy: values.done, sortBy: completedAt, listIds: [work], updatedAt: 2026-11-09T10:00:00Z }
|
|
176
|
+
tasks: [{ id: a, title: A, starred: true, updatedAt: 2026-11-09T10:00:00Z }]
|
|
177
|
+
expect:
|
|
178
|
+
version: "1.1"
|
|
179
|
+
lists: [{ id: work, title: Work, updatedAt: "2026-11-09T10:00:00Z" }]
|
|
180
|
+
fields:
|
|
181
|
+
- {
|
|
182
|
+
id: done,
|
|
183
|
+
title: Done,
|
|
184
|
+
type: boolean,
|
|
185
|
+
updatedAt: "2026-11-09T10:00:00Z",
|
|
186
|
+
deletedAt: "2026-11-09T10:00:00Z",
|
|
187
|
+
}
|
|
188
|
+
views:
|
|
189
|
+
- {
|
|
190
|
+
id: m,
|
|
191
|
+
title: Map,
|
|
192
|
+
type: map,
|
|
193
|
+
scale: quarter,
|
|
194
|
+
x-app: { zoom: 3 },
|
|
195
|
+
updatedAt: "2026-11-09T10:00:00Z",
|
|
196
|
+
}
|
|
197
|
+
- {
|
|
198
|
+
id: b,
|
|
199
|
+
title: Board,
|
|
200
|
+
type: board,
|
|
201
|
+
groupBy: values.done,
|
|
202
|
+
sortBy: completedAt,
|
|
203
|
+
listIds: [work],
|
|
204
|
+
updatedAt: "2026-11-09T10:00:00Z",
|
|
205
|
+
}
|
|
206
|
+
tasks: [{ id: a, title: A, starred: true, updatedAt: "2026-11-09T10:00:00Z" }]
|
|
207
|
+
|
|
166
208
|
- name: markdown with BOM, CRLF and fence-like lines in the body
|
|
167
209
|
format: markdown
|
|
168
210
|
input: "\uFEFF---\r\ntask: { id: a, title: A, updatedAt: 2026-11-09T10:00:00Z }\r\n--- \r\nbody\r\n---\r\n+++\r\n"
|
package/dist/index.d.mts
CHANGED
|
@@ -40,6 +40,28 @@ interface List extends Synced {
|
|
|
40
40
|
/** Parent list; lists nest. No cycles. */
|
|
41
41
|
parentId?: string;
|
|
42
42
|
}
|
|
43
|
+
/**
|
|
44
|
+
* A saved way of showing the document's tasks, shared by every app that reads the document. Apps keep their own
|
|
45
|
+
* settings on it as extra keys. Pick its tasks with `viewTasks()`.
|
|
46
|
+
*/
|
|
47
|
+
interface View extends Synced {
|
|
48
|
+
title: string;
|
|
49
|
+
/** `list`, `board`, `calendar`, `timeline` or `table`. Apps skip, and keep, views of a type they don't draw. */
|
|
50
|
+
type: string;
|
|
51
|
+
/** Sections, columns or rows: `listId`, `starred`, or `values.<field id>` of a select, multiSelect or boolean field. */
|
|
52
|
+
groupBy?: string;
|
|
53
|
+
/** `title`, `start`, `end`, `due`, `completedAt`, `updatedAt`, `starred`, or `values.<field id>` of any field but a multiSelect. Absent: document order. */
|
|
54
|
+
sortBy?: string;
|
|
55
|
+
sortDescending?: boolean;
|
|
56
|
+
/** Only tasks in these lists or lists nested in them. Absent: every task. */
|
|
57
|
+
listIds?: string[];
|
|
58
|
+
/** Only open tasks (`isOpen`): done and cancelled ones hidden. */
|
|
59
|
+
openOnly?: boolean;
|
|
60
|
+
/** Calendar: the period a page shows. Timeline: the period a column stands for. `day`, `week` or `month`; apps use their default for one they don't know. */
|
|
61
|
+
scale?: string;
|
|
62
|
+
/** Timeline: pixels a day, for an app that zooms freely; `scale` is then the preset nearest it. Positive. */
|
|
63
|
+
zoom?: number;
|
|
64
|
+
}
|
|
43
65
|
/** A choice of a select field. Each option is its own synced record. */
|
|
44
66
|
interface FieldOption extends Synced {
|
|
45
67
|
/** Required, except when only recoloring or renaming a built-in option. */
|
|
@@ -51,7 +73,7 @@ interface FieldOption extends Synced {
|
|
|
51
73
|
}
|
|
52
74
|
/**
|
|
53
75
|
* A custom field, or options added to a built-in one.
|
|
54
|
-
* Built-in ids (`status`, `priority`, `tags`, `progress`, `location`) only take `options`;
|
|
76
|
+
* Built-in ids (`status`, `priority`, `tags`, `progress`, `location`, `assignees`) only take `options`;
|
|
55
77
|
* custom fields need `title`, `type`, `updatedAt`.
|
|
56
78
|
*/
|
|
57
79
|
interface FieldDefinition {
|
|
@@ -115,18 +137,23 @@ interface Task extends Synced {
|
|
|
115
137
|
/** Occurrences to skip, same form as the anchor. Needs `recurrence`. */
|
|
116
138
|
excludedDates?: (LocalDate | LocalDateTime)[];
|
|
117
139
|
completedAt?: UTCDateTime;
|
|
140
|
+
/** Marked to stand out (a star or a flag). */
|
|
141
|
+
starred?: boolean;
|
|
142
|
+
/** `#rrggbb`: how apps draw the task. Absent: its list's colour, then the app's. */
|
|
143
|
+
color?: string;
|
|
118
144
|
/**
|
|
119
|
-
* Field id → value, built-in (`status`, `priority`, `tags`, `progress`, `location`) and custom alike.
|
|
145
|
+
* Field id → value, built-in (`status`, `priority`, `tags`, `progress`, `location`, `assignees`) and custom alike.
|
|
120
146
|
* A key must name a field; a select value must be an option id. Read meanings with `resolveFields()`.
|
|
121
147
|
*/
|
|
122
148
|
values?: Record<string, FieldValue>;
|
|
123
149
|
}
|
|
124
|
-
/** A whole file: lists, field definitions and tasks. */
|
|
150
|
+
/** A whole file: lists, field definitions, views and tasks. */
|
|
125
151
|
interface TaskDocument {
|
|
126
|
-
/** `"1.
|
|
152
|
+
/** `"1.2"`; readers accept any `1.x`. */
|
|
127
153
|
version: string;
|
|
128
154
|
lists?: List[];
|
|
129
155
|
fields?: FieldDefinition[];
|
|
156
|
+
views?: View[];
|
|
130
157
|
tasks: Task[];
|
|
131
158
|
[key: string]: unknown;
|
|
132
159
|
}
|
|
@@ -192,7 +219,7 @@ interface MergeResult {
|
|
|
192
219
|
repairs: Repair[];
|
|
193
220
|
}
|
|
194
221
|
/**
|
|
195
|
-
* Merges two copies of a document record by record: lists, tasks, custom fields and each field option.
|
|
222
|
+
* Merges two copies of a document record by record: lists, tasks, views, custom fields and each field option.
|
|
196
223
|
* The later `updatedAt` wins; on a tie the deleted record wins, then the larger canonical JSON, so the
|
|
197
224
|
* content is the same whichever side runs the merge. Record order follows `a`, with records new in `b` appended.
|
|
198
225
|
*
|
|
@@ -292,4 +319,10 @@ interface OverdueOptions {
|
|
|
292
319
|
export declare function isOverdue(task: Task, fields: Fields, options?: OverdueOptions): boolean;
|
|
293
320
|
/** The tasks in `dependsOn` still in the way: not done, not cancelled, not deleted. Empty when unblocked. */
|
|
294
321
|
export declare function blockers(task: Task, tasks: readonly Task[], fields: Fields): Task[];
|
|
295
|
-
|
|
322
|
+
/**
|
|
323
|
+
* The tasks a view shows, in its order: not deleted, in its `listIds` or lists nested in them, open ones only
|
|
324
|
+
* with `openOnly`, sorted by `sortBy`. Tasks without the value come last either way; ties keep document order.
|
|
325
|
+
* Grouping (`groupBy`) is the app's to draw.
|
|
326
|
+
*/
|
|
327
|
+
export declare function viewTasks(doc: TaskDocument, view: View, fields: Fields): Task[];
|
|
328
|
+
export type { Duration, FieldDefinition, FieldOption, FieldType, FieldValue, Fields, Format, Frequency, ImportResult, Issue, Kind, List, LocalDate, LocalDateTime, MarkdownTask, MergeResult, Occurrence, OccurrenceRange, OverdueOptions, Recurrence, Repair, ResolvedField, ResolvedOption, Synced, Task, TaskDocument, TaskPriority, TaskStatus, UTCDateTime, View, Weekday };
|
package/dist/index.mjs
CHANGED
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
import * as z from "zod";
|
|
2
2
|
import { TomlDate, parse as parse$1, stringify as stringify$1 } from "smol-toml";
|
|
3
|
-
import { load } from "js-yaml";
|
|
4
|
-
import { stringify as stringify$2 } from "yaml";
|
|
3
|
+
import { dump, load } from "js-yaml";
|
|
5
4
|
import { Temporal } from "temporal-polyfill";
|
|
6
5
|
// src/cycle.ts
|
|
7
6
|
/**
|
|
@@ -77,7 +76,8 @@ const BUILT_IN_FIELDS = Object.assign(Object.create(null), {
|
|
|
77
76
|
min: 0,
|
|
78
77
|
max: 100
|
|
79
78
|
}),
|
|
80
|
-
location: builtIn("location", "Location", "text")
|
|
79
|
+
location: builtIn("location", "Location", "text"),
|
|
80
|
+
assignees: builtIn("assignees", "Assignees", "multiSelect")
|
|
81
81
|
});
|
|
82
82
|
/** Built-in fields merged with the document's `fields`. Deleted fields and options stay, flagged `deleted`. */
|
|
83
83
|
function resolveFields(doc) {
|
|
@@ -196,6 +196,18 @@ const optionSchema = z.looseObject({
|
|
|
196
196
|
color: color.exactOptional(),
|
|
197
197
|
category: z.string().min(1).exactOptional()
|
|
198
198
|
});
|
|
199
|
+
const viewSchema = z.looseObject({
|
|
200
|
+
...synced,
|
|
201
|
+
title: z.string(),
|
|
202
|
+
type: z.string().min(1, "expected a view type like board"),
|
|
203
|
+
groupBy: z.string().exactOptional(),
|
|
204
|
+
sortBy: z.string().exactOptional(),
|
|
205
|
+
sortDescending: z.boolean().exactOptional(),
|
|
206
|
+
listIds: z.array(id).exactOptional(),
|
|
207
|
+
openOnly: z.boolean().exactOptional(),
|
|
208
|
+
scale: z.string().exactOptional(),
|
|
209
|
+
zoom: z.number().positive("expected a positive number of pixels a day").exactOptional()
|
|
210
|
+
});
|
|
199
211
|
const fieldSchema = z.looseObject({
|
|
200
212
|
id,
|
|
201
213
|
title: z.string().exactOptional(),
|
|
@@ -256,6 +268,8 @@ const taskSchema = z.looseObject({
|
|
|
256
268
|
recurrence: recurrenceSchema.exactOptional(),
|
|
257
269
|
excludedDates: z.array(local).exactOptional(),
|
|
258
270
|
completedAt: utc$1.exactOptional(),
|
|
271
|
+
starred: z.boolean().exactOptional(),
|
|
272
|
+
color: color.exactOptional(),
|
|
259
273
|
values: z.record(z.string(), z.union([
|
|
260
274
|
z.string(),
|
|
261
275
|
z.number(),
|
|
@@ -268,6 +282,7 @@ const documentSchema = z.looseObject({
|
|
|
268
282
|
version: z.string().regex(/^1\.\d+$/, "unsupported version; this library reads 1.x"),
|
|
269
283
|
lists: z.array(listSchema).exactOptional(),
|
|
270
284
|
fields: z.array(fieldSchema).exactOptional(),
|
|
285
|
+
views: z.array(viewSchema).exactOptional(),
|
|
271
286
|
tasks: z.array(taskSchema)
|
|
272
287
|
}).superRefine((doc, ctx) => checkDocument(doc, (path, message) => ctx.addIssue({
|
|
273
288
|
code: "custom",
|
|
@@ -323,6 +338,54 @@ function checkDocument(doc, issue) {
|
|
|
323
338
|
});
|
|
324
339
|
checkAcyclic(tasks, (t) => t.parentId === void 0 ? [] : [t.parentId], ["tasks"], "parentId", issue);
|
|
325
340
|
checkAcyclic(tasks, (t) => t.dependsOn ?? [], ["tasks"], "dependsOn", issue);
|
|
341
|
+
const views = doc.views ?? [];
|
|
342
|
+
checkUnique(views, ["views"], issue);
|
|
343
|
+
views.forEach((v, i) => {
|
|
344
|
+
for (const use of VIEW_KEYS) {
|
|
345
|
+
const key = v[use];
|
|
346
|
+
const error = key === void 0 ? void 0 : viewKeyError(key, use, fields);
|
|
347
|
+
if (error) issue([
|
|
348
|
+
"views",
|
|
349
|
+
i,
|
|
350
|
+
use
|
|
351
|
+
], error);
|
|
352
|
+
}
|
|
353
|
+
v.listIds?.forEach((l, j) => {
|
|
354
|
+
if (!listIds.has(l)) issue([
|
|
355
|
+
"views",
|
|
356
|
+
i,
|
|
357
|
+
"listIds",
|
|
358
|
+
j
|
|
359
|
+
], `unknown list "${l}"`);
|
|
360
|
+
});
|
|
361
|
+
});
|
|
362
|
+
}
|
|
363
|
+
const VIEW_KEYS = ["groupBy", "sortBy"];
|
|
364
|
+
const SORT_KEYS = [
|
|
365
|
+
"title",
|
|
366
|
+
"start",
|
|
367
|
+
"end",
|
|
368
|
+
"due",
|
|
369
|
+
"completedAt",
|
|
370
|
+
"updatedAt",
|
|
371
|
+
"starred"
|
|
372
|
+
];
|
|
373
|
+
/** Why `key` can't be a view's `groupBy` or `sortBy`, or undefined when it can. */
|
|
374
|
+
function viewKeyError(key, use, fields) {
|
|
375
|
+
if (key.startsWith("values.")) {
|
|
376
|
+
const fieldId = key.slice(7);
|
|
377
|
+
const field = fields[fieldId];
|
|
378
|
+
if (!field) return `unknown field "${fieldId}"; define it in "fields"`;
|
|
379
|
+
if (use === "groupBy" && ![
|
|
380
|
+
"select",
|
|
381
|
+
"multiSelect",
|
|
382
|
+
"boolean"
|
|
383
|
+
].includes(field.type)) return `can't group by a ${field.type} field; use a select, multiSelect or boolean one`;
|
|
384
|
+
if (use === "sortBy" && field.type === "multiSelect") return "can't sort by a multiSelect field";
|
|
385
|
+
return;
|
|
386
|
+
}
|
|
387
|
+
if (use === "groupBy") return key === "listId" || key === "starred" ? void 0 : "expected listId, starred or values.<field id>";
|
|
388
|
+
return SORT_KEYS.includes(key) ? void 0 : `expected one of: ${SORT_KEYS.join(", ")}, or values.<field id>`;
|
|
326
389
|
}
|
|
327
390
|
function checkUnique(items, path, issue) {
|
|
328
391
|
const seen = /* @__PURE__ */ new Set();
|
|
@@ -536,16 +599,10 @@ function checkExpansion(value, sourceLength) {
|
|
|
536
599
|
function encode(data, format) {
|
|
537
600
|
switch (format) {
|
|
538
601
|
case "json": return `${JSON.stringify(data, null, 2)}\n`;
|
|
539
|
-
case "yaml": return
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
"intHex",
|
|
544
|
-
"int",
|
|
545
|
-
"floatExp",
|
|
546
|
-
"floatNaN",
|
|
547
|
-
"float"
|
|
548
|
-
]
|
|
602
|
+
case "yaml": return dump(data, {
|
|
603
|
+
lineWidth: -1,
|
|
604
|
+
noRefs: true,
|
|
605
|
+
quoteStyle: "double"
|
|
549
606
|
});
|
|
550
607
|
case "toml": {
|
|
551
608
|
const path = findNull(data, []);
|
|
@@ -577,10 +634,11 @@ const CORE_KEYS = /* @__PURE__ */ new Set([
|
|
|
577
634
|
"version",
|
|
578
635
|
"lists",
|
|
579
636
|
"fields",
|
|
637
|
+
"views",
|
|
580
638
|
"tasks"
|
|
581
639
|
]);
|
|
582
640
|
/**
|
|
583
|
-
* Merges two copies of a document record by record: lists, tasks, custom fields and each field option.
|
|
641
|
+
* Merges two copies of a document record by record: lists, tasks, views, custom fields and each field option.
|
|
584
642
|
* The later `updatedAt` wins; on a tie the deleted record wins, then the larger canonical JSON, so the
|
|
585
643
|
* content is the same whichever side runs the merge. Record order follows `a`, with records new in `b` appended.
|
|
586
644
|
*
|
|
@@ -600,6 +658,7 @@ function merge(a, b) {
|
|
|
600
658
|
}
|
|
601
659
|
if (x.lists || y.lists) doc.lists = mergeRecords(x.lists, y.lists);
|
|
602
660
|
if (x.fields || y.fields) doc.fields = mergeRecords(x.fields, y.fields).map((f) => withOptions(f, x, y));
|
|
661
|
+
if (x.views || y.views) doc.views = mergeRecords(x.views, y.views);
|
|
603
662
|
doc.tasks = mergeRecords(x.tasks, y.tasks);
|
|
604
663
|
const repairs = [];
|
|
605
664
|
breakCycles(doc.lists ?? [], "lists", "parentId", repairs);
|
|
@@ -607,6 +666,7 @@ function merge(a, b) {
|
|
|
607
666
|
breakCycles(doc.tasks, "tasks", "dependsOn", repairs);
|
|
608
667
|
repairOptions(doc, repairs);
|
|
609
668
|
repairValues(doc, repairs);
|
|
669
|
+
repairViews(doc, repairs);
|
|
610
670
|
return {
|
|
611
671
|
document: validate(doc),
|
|
612
672
|
repairs
|
|
@@ -743,6 +803,30 @@ function repairValues(doc, repairs) {
|
|
|
743
803
|
if (Object.keys(t.values).length === 0) delete t.values;
|
|
744
804
|
});
|
|
745
805
|
}
|
|
806
|
+
/** A view grouped or sorted by a field whose definition changed type. */
|
|
807
|
+
function repairViews(doc, repairs) {
|
|
808
|
+
const fields = resolveFields(doc);
|
|
809
|
+
doc.views?.forEach((v, i) => {
|
|
810
|
+
let changed = false;
|
|
811
|
+
for (const use of VIEW_KEYS) {
|
|
812
|
+
const key = v[use];
|
|
813
|
+
const error = key === void 0 ? void 0 : viewKeyError(key, use, fields);
|
|
814
|
+
if (error === void 0) continue;
|
|
815
|
+
repairs.push({
|
|
816
|
+
path: [
|
|
817
|
+
"views",
|
|
818
|
+
i,
|
|
819
|
+
use
|
|
820
|
+
],
|
|
821
|
+
message: error,
|
|
822
|
+
removed: key
|
|
823
|
+
});
|
|
824
|
+
delete v[use];
|
|
825
|
+
changed = true;
|
|
826
|
+
}
|
|
827
|
+
if (changed) bump(v);
|
|
828
|
+
});
|
|
829
|
+
}
|
|
746
830
|
// src/recurrence.ts
|
|
747
831
|
const { PlainDate, PlainDateTime } = Temporal;
|
|
748
832
|
const WEEKDAYS = [
|
|
@@ -974,6 +1058,13 @@ function toICS(doc) {
|
|
|
974
1058
|
const valid = validate(doc);
|
|
975
1059
|
const fields = resolveFields(valid);
|
|
976
1060
|
const category = (fieldId, value) => fields[fieldId].options.find((o) => o.id === value)?.category;
|
|
1061
|
+
const people = new Map((valid.fields?.find((f) => f.id === "assignees")?.options ?? []).map((o) => [o.id, o]));
|
|
1062
|
+
const attendee = (id) => {
|
|
1063
|
+
const name = fields["assignees"].options.find((o) => o.id === id)?.title ?? id;
|
|
1064
|
+
const email = people.get(id)?.["email"];
|
|
1065
|
+
const address = typeof email === "string" ? `mailto:${email}` : `${ASSIGNEE_URI}${encodeURIComponent(id)}`;
|
|
1066
|
+
return `ATTENDEE;CN="${name.replace(/["\r\n]/g, "'")}";X-TASKS-ID="${id.replace(/["\r\n]/g, "")}":${address}`;
|
|
1067
|
+
};
|
|
977
1068
|
const lines = [
|
|
978
1069
|
"BEGIN:VCALENDAR",
|
|
979
1070
|
"VERSION:2.0",
|
|
@@ -1008,6 +1099,8 @@ function toICS(doc) {
|
|
|
1008
1099
|
}
|
|
1009
1100
|
const tags = values["tags"];
|
|
1010
1101
|
if (Array.isArray(tags) && tags.length > 0) lines.push(`CATEGORIES:${tags.map(escape).join(",")}`);
|
|
1102
|
+
const assignees = values["assignees"];
|
|
1103
|
+
if (Array.isArray(assignees)) for (const id of assignees) lines.push(attendee(id));
|
|
1011
1104
|
if (t.parentId !== void 0) lines.push(`RELATED-TO;RELTYPE=PARENT:${escape(t.parentId)}`);
|
|
1012
1105
|
for (const id of t.dependsOn ?? []) lines.push(`RELATED-TO;RELTYPE=DEPENDS-ON:${escape(id)}`);
|
|
1013
1106
|
if (t.recurrence) lines.push(`RRULE:${rrule(t.recurrence, zone)}`);
|
|
@@ -1074,12 +1167,13 @@ function fromICS(text) {
|
|
|
1074
1167
|
const dropped = [];
|
|
1075
1168
|
const tasks = [];
|
|
1076
1169
|
const successors = [];
|
|
1170
|
+
const people = /* @__PURE__ */ new Map();
|
|
1077
1171
|
readComponents(text).forEach((c, n) => {
|
|
1078
1172
|
const uid = c.props.find((p) => p.name === "UID")?.value;
|
|
1079
1173
|
try {
|
|
1080
1174
|
if (uid === void 0) throw new Skip(`${c.type} without UID`);
|
|
1081
1175
|
if (tasks.some((t) => t.id === uid)) throw new Skip("duplicate UID");
|
|
1082
|
-
tasks.push(toTask(c, uid, dropped, successors));
|
|
1176
|
+
tasks.push(toTask(c, uid, dropped, successors, people));
|
|
1083
1177
|
} catch (error) {
|
|
1084
1178
|
if (!(error instanceof Skip || error instanceof RangeError)) throw error;
|
|
1085
1179
|
dropped.push({
|
|
@@ -1092,9 +1186,18 @@ function fromICS(text) {
|
|
|
1092
1186
|
const task = tasks.find((t) => t.id === after);
|
|
1093
1187
|
if (task) task.dependsOn = [.../* @__PURE__ */ new Set([...task.dependsOn ?? [], before])];
|
|
1094
1188
|
}
|
|
1189
|
+
const fields = people.size ? [{
|
|
1190
|
+
id: "assignees",
|
|
1191
|
+
options: [...people].map(([id, p]) => ({
|
|
1192
|
+
id,
|
|
1193
|
+
updatedAt: EPOCH,
|
|
1194
|
+
...p
|
|
1195
|
+
}))
|
|
1196
|
+
}] : [];
|
|
1095
1197
|
return {
|
|
1096
1198
|
document: settle({
|
|
1097
1199
|
version: "1.0",
|
|
1200
|
+
...fields.length > 0 && { fields },
|
|
1098
1201
|
tasks
|
|
1099
1202
|
}, dropped),
|
|
1100
1203
|
dropped
|
|
@@ -1136,7 +1239,21 @@ function settle(doc, dropped) {
|
|
|
1136
1239
|
}
|
|
1137
1240
|
}
|
|
1138
1241
|
}
|
|
1139
|
-
|
|
1242
|
+
/** An attendee's address for an assignee without an email, so it comes back as the same option. */
|
|
1243
|
+
const ASSIGNEE_URI = "urn:x-tasks:assignee:";
|
|
1244
|
+
/** The option for an attendee: the id we wrote (`X-TASKS-ID`, or in our URI), else its email, else its name. */
|
|
1245
|
+
function personOf(p) {
|
|
1246
|
+
const title = p.params["CN"]?.trim();
|
|
1247
|
+
const address = p.value.trim();
|
|
1248
|
+
const ours = address.toLowerCase().startsWith(ASSIGNEE_URI) ? decodeURIComponent(address.slice(21)) : void 0;
|
|
1249
|
+
const email = /^mailto:/i.test(address) ? address.slice(7).toLowerCase() : void 0;
|
|
1250
|
+
const id = p.params["X-TASKS-ID"] || ours || email || title;
|
|
1251
|
+
return id ? [id, {
|
|
1252
|
+
title: title || id,
|
|
1253
|
+
...email && { email }
|
|
1254
|
+
}] : void 0;
|
|
1255
|
+
}
|
|
1256
|
+
function toTask(c, uid, dropped, successors, people) {
|
|
1140
1257
|
const all = (name) => c.props.filter((p) => p.name === name);
|
|
1141
1258
|
const one = (name) => c.props.find((p) => p.name === name);
|
|
1142
1259
|
if (one("RECURRENCE-ID")) throw new Skip("changed occurrences of a recurring item aren't supported");
|
|
@@ -1180,6 +1297,14 @@ function toTask(c, uid, dropped, successors) {
|
|
|
1180
1297
|
if (completed) task.completedAt = instant(completed.value);
|
|
1181
1298
|
const tags = [...new Set(all("CATEGORIES").flatMap((p) => unescape(p.value, true)).map((s) => s.trim()))].filter(Boolean);
|
|
1182
1299
|
if (tags.length > 0) values["tags"] = tags;
|
|
1300
|
+
const assignees = /* @__PURE__ */ new Set();
|
|
1301
|
+
for (const p of all("ATTENDEE")) {
|
|
1302
|
+
const found = personOf(p);
|
|
1303
|
+
if (!found) continue;
|
|
1304
|
+
if (!people.has(found[0])) people.set(...found);
|
|
1305
|
+
assignees.add(found[0]);
|
|
1306
|
+
}
|
|
1307
|
+
if (assignees.size > 0) values["assignees"] = [...assignees];
|
|
1183
1308
|
if (Object.keys(values).length > 0) task.values = values;
|
|
1184
1309
|
for (const p of all("RELATED-TO")) {
|
|
1185
1310
|
const target = unescape(p.value)[0];
|
|
@@ -1466,4 +1591,61 @@ function blockers(task, tasks, fields) {
|
|
|
1466
1591
|
const ids = new Set(task.dependsOn);
|
|
1467
1592
|
return ids.size === 0 ? [] : tasks.filter((t) => ids.has(t.id) && isOpen(t, fields));
|
|
1468
1593
|
}
|
|
1469
|
-
|
|
1594
|
+
// src/views.ts
|
|
1595
|
+
/**
|
|
1596
|
+
* The tasks a view shows, in its order: not deleted, in its `listIds` or lists nested in them, open ones only
|
|
1597
|
+
* with `openOnly`, sorted by `sortBy`. Tasks without the value come last either way; ties keep document order.
|
|
1598
|
+
* Grouping (`groupBy`) is the app's to draw.
|
|
1599
|
+
*/
|
|
1600
|
+
function viewTasks(doc, view, fields) {
|
|
1601
|
+
const lists = view.listIds && nested(doc, view.listIds);
|
|
1602
|
+
const shown = doc.tasks.filter((t) => t.deletedAt === void 0 && (!lists || t.listId !== void 0 && lists.has(t.listId)) && (!view.openOnly || isOpen(t, fields)));
|
|
1603
|
+
if (view.sortBy === void 0) return shown;
|
|
1604
|
+
const [get, compare] = sorter(view.sortBy, fields);
|
|
1605
|
+
const sign = view.sortDescending ? -1 : 1;
|
|
1606
|
+
const keyed = shown.map((task) => ({
|
|
1607
|
+
task,
|
|
1608
|
+
key: get(task)
|
|
1609
|
+
}));
|
|
1610
|
+
keyed.sort((p, q) => p.key === void 0 || q.key === void 0 ? Number(p.key === void 0) - Number(q.key === void 0) : sign * compare(p.key, q.key));
|
|
1611
|
+
return keyed.map((k) => k.task);
|
|
1612
|
+
}
|
|
1613
|
+
const words = new Intl.Collator(void 0, { numeric: true });
|
|
1614
|
+
const byWords = (a, b) => words.compare(a, b);
|
|
1615
|
+
const byNumber = (a, b) => a - b;
|
|
1616
|
+
const byCode = (a, b) => a < b ? -1 : a > b ? 1 : 0;
|
|
1617
|
+
/** Local and UTC times as comparable text: padded, `Z` dropped. */
|
|
1618
|
+
const time = (v) => typeof v === "string" ? sortKey(v.replace(/Z$/, "")) : void 0;
|
|
1619
|
+
const text = (v) => typeof v === "string" ? v : void 0;
|
|
1620
|
+
function sorter(key, fields) {
|
|
1621
|
+
if (key === "title") return [(t) => t.title, byWords];
|
|
1622
|
+
if (key === "starred") return [(t) => Number(t.starred === true), byNumber];
|
|
1623
|
+
if (!key.startsWith("values.")) return [(t) => time(t[key]), byCode];
|
|
1624
|
+
const id = key.slice(7);
|
|
1625
|
+
const field = fields[id];
|
|
1626
|
+
const value = (t) => t.values?.[id];
|
|
1627
|
+
switch (field.type) {
|
|
1628
|
+
case "number": return [(t) => value(t), byNumber];
|
|
1629
|
+
case "boolean": return [(t) => value(t) === void 0 ? void 0 : Number(value(t)), byNumber];
|
|
1630
|
+
case "date": return [(t) => time(value(t)), byCode];
|
|
1631
|
+
case "select": {
|
|
1632
|
+
const rank = new Map(field.options.map((o, i) => [o.id, i]));
|
|
1633
|
+
return [(t) => value(t) === void 0 ? void 0 : rank.get(value(t)) ?? rank.size, byNumber];
|
|
1634
|
+
}
|
|
1635
|
+
default: return [(t) => text(value(t)), byWords];
|
|
1636
|
+
}
|
|
1637
|
+
}
|
|
1638
|
+
/** `ids` and every list nested under one of them. */
|
|
1639
|
+
function nested(doc, ids) {
|
|
1640
|
+
const out = new Set(ids);
|
|
1641
|
+
let grew = true;
|
|
1642
|
+
while (grew) {
|
|
1643
|
+
grew = false;
|
|
1644
|
+
for (const l of doc.lists ?? []) if (l.parentId !== void 0 && out.has(l.parentId) && !out.has(l.id)) {
|
|
1645
|
+
out.add(l.id);
|
|
1646
|
+
grew = true;
|
|
1647
|
+
}
|
|
1648
|
+
}
|
|
1649
|
+
return out;
|
|
1650
|
+
}
|
|
1651
|
+
export { TasksFormatError, blockers, completeTask, documentSchema, fromICS, isComplete, isOpen, isOverdue, isTaskFile, kindOf, merge, occurrences, parse, parseMarkdown, priorityOf, resolveFields, statusOf, stringify, stringifyMarkdown, toICS, validate, viewTasks };
|
package/dist/schema.json
CHANGED
|
@@ -141,6 +141,68 @@
|
|
|
141
141
|
"additionalProperties": {}
|
|
142
142
|
}
|
|
143
143
|
},
|
|
144
|
+
"views": {
|
|
145
|
+
"type": "array",
|
|
146
|
+
"items": {
|
|
147
|
+
"type": "object",
|
|
148
|
+
"properties": {
|
|
149
|
+
"id": {
|
|
150
|
+
"type": "string",
|
|
151
|
+
"minLength": 1
|
|
152
|
+
},
|
|
153
|
+
"updatedAt": {
|
|
154
|
+
"type": "string",
|
|
155
|
+
"format": "date-time",
|
|
156
|
+
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
|
|
157
|
+
},
|
|
158
|
+
"deletedAt": {
|
|
159
|
+
"type": "string",
|
|
160
|
+
"format": "date-time",
|
|
161
|
+
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
|
|
162
|
+
},
|
|
163
|
+
"title": {
|
|
164
|
+
"type": "string"
|
|
165
|
+
},
|
|
166
|
+
"type": {
|
|
167
|
+
"type": "string",
|
|
168
|
+
"minLength": 1
|
|
169
|
+
},
|
|
170
|
+
"groupBy": {
|
|
171
|
+
"type": "string"
|
|
172
|
+
},
|
|
173
|
+
"sortBy": {
|
|
174
|
+
"type": "string"
|
|
175
|
+
},
|
|
176
|
+
"sortDescending": {
|
|
177
|
+
"type": "boolean"
|
|
178
|
+
},
|
|
179
|
+
"listIds": {
|
|
180
|
+
"type": "array",
|
|
181
|
+
"items": {
|
|
182
|
+
"type": "string",
|
|
183
|
+
"minLength": 1
|
|
184
|
+
}
|
|
185
|
+
},
|
|
186
|
+
"openOnly": {
|
|
187
|
+
"type": "boolean"
|
|
188
|
+
},
|
|
189
|
+
"scale": {
|
|
190
|
+
"type": "string"
|
|
191
|
+
},
|
|
192
|
+
"zoom": {
|
|
193
|
+
"type": "number",
|
|
194
|
+
"exclusiveMinimum": 0
|
|
195
|
+
}
|
|
196
|
+
},
|
|
197
|
+
"required": [
|
|
198
|
+
"id",
|
|
199
|
+
"updatedAt",
|
|
200
|
+
"title",
|
|
201
|
+
"type"
|
|
202
|
+
],
|
|
203
|
+
"additionalProperties": {}
|
|
204
|
+
}
|
|
205
|
+
},
|
|
144
206
|
"tasks": {
|
|
145
207
|
"type": "array",
|
|
146
208
|
"items": {
|
|
@@ -287,6 +349,13 @@
|
|
|
287
349
|
"format": "date-time",
|
|
288
350
|
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
|
|
289
351
|
},
|
|
352
|
+
"starred": {
|
|
353
|
+
"type": "boolean"
|
|
354
|
+
},
|
|
355
|
+
"color": {
|
|
356
|
+
"type": "string",
|
|
357
|
+
"pattern": "^#[0-9a-fA-F]{6}$"
|
|
358
|
+
},
|
|
290
359
|
"values": {
|
|
291
360
|
"type": "object",
|
|
292
361
|
"propertyNames": {
|
package/llms.txt
CHANGED
|
@@ -6,8 +6,8 @@ A task's kind comes from its time fields, never a type field: `start` plus `end`
|
|
|
6
6
|
|
|
7
7
|
## Rules for writing documents
|
|
8
8
|
|
|
9
|
-
- Top level: `{ version: "1.
|
|
10
|
-
- Every task, list, custom field and field option needs `id` (UUID recommended) and `updatedAt`. Set `updatedAt` to the current UTC time on every change.
|
|
9
|
+
- Top level: `{ version: "1.1", lists?: List[], fields?: FieldDefinition[], views?: View[], tasks: Task[] }`.
|
|
10
|
+
- Every task, list, view, custom field and field option needs `id` (UUID recommended) and `updatedAt`. Set `updatedAt` to the current UTC time on every change.
|
|
11
11
|
- Delete by setting `deletedAt` (UTC); never remove a record that others may reference.
|
|
12
12
|
- Time formats:
|
|
13
13
|
- `start`, `end`, `due`, `until` and `excludedDates` are local: `2026-11-12` (all-day) or `2026-11-12T09:30` (wall clock in `timeZone`; floating without one). Never put an offset or `Z` on these.
|
|
@@ -22,6 +22,9 @@ A task's kind comes from its time fields, never a type field: `start` plus `end`
|
|
|
22
22
|
- Built-ins: `status: todo|doing|done|cancelled`, `priority: low|medium|high`, `tags: string[]`, `progress: 0–100`, `location: string`.
|
|
23
23
|
- A custom field or custom option must be defined under `fields` before use. A custom status option maps to a built-in category: `{ id: shipped, title: Shipped, category: done, updatedAt }`.
|
|
24
24
|
- Colors are `#rrggbb`.
|
|
25
|
+
- `task.starred: boolean` marks a task to stand out (a star or flag). `task.color: "#rrggbb"` is how apps draw it (absent: its list's colour).
|
|
26
|
+
- `values.assignees` (built-in multiSelect) holds option ids: the people are the field's options (`fields: [{ id: assignees, options: [{ id, title, color?, updatedAt }] }]`).
|
|
27
|
+
- Views (synced records like tasks): `{ id, title, type: list|board|calendar|timeline|table, groupBy?, sortBy?, sortDescending?, listIds?, openOnly?, scale?: day|week|month, zoom?: number (timeline px a day), updatedAt }`. `groupBy` is `listId`, `starred` or `values.<id>` of a select, multiSelect or boolean field; `sortBy` is `title`, `start`, `end`, `due`, `completedAt`, `updatedAt`, `starred` or `values.<id>` of any non-multiSelect field. Put app-specific view settings on the view as extra keys.
|
|
25
28
|
- Unknown keys anywhere are kept, except inside `recurrence`, where they're an error.
|
|
26
29
|
|
|
27
30
|
## Rules for writing code
|
|
@@ -29,6 +32,7 @@ A task's kind comes from its time fields, never a type field: `start` plus `end`
|
|
|
29
32
|
- Dates are strings throughout; the library never returns `Date` objects.
|
|
30
33
|
- `parse`, `stringify`, `validate`, `parseMarkdown`, `stringifyMarkdown`, `toICS` and `fromICS` throw `TasksFormatError` (`.issues: { path, message }[]`; `.message` is ready to show). `isTaskFile` never throws.
|
|
31
34
|
- Resolve `const fields = resolveFields(doc)` once, then use the helpers instead of comparing ids, because custom options like `shipped` mean `done`. The helpers: `statusOf(task, fields)` (todo|doing|done|cancelled), `priorityOf`, `isComplete`, `isOpen` (not deleted, todo or doing), `isOverdue(task, fields, { now?, timeZone? })` and `blockers(task, doc.tasks, fields)`. For other fields, read `fields[id].options` and each option's `.category`.
|
|
35
|
+
- To show a view, `viewTasks(doc, view, fields)` returns its tasks filtered and sorted; draw the groups yourself.
|
|
32
36
|
- To draw a calendar or timeline, call `occurrences(task, { from, to, timeZone? })` for each task (`to` is exclusive). Don't expand recurrence by hand.
|
|
33
37
|
- To complete a task, use `completeTask(task, new Date().toISOString())`. It returns a new task: repeating tasks move to their next occurrence, everything else becomes `status: done`. Don't move recurring dates by hand.
|
|
34
38
|
- For sync, call `merge(local, remote)`. It returns `{ document, repairs }`; show `repairs` to the user.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@type32/tasks",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "One format for todos, events and timelines: schema, validation and parsing",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"files": [
|
|
@@ -36,7 +36,6 @@
|
|
|
36
36
|
"js-yaml": "^5.5.0",
|
|
37
37
|
"smol-toml": "^1.9.1",
|
|
38
38
|
"temporal-polyfill": "^1.0.8",
|
|
39
|
-
"yaml": "^2.9.1",
|
|
40
39
|
"zod": "^4.6.7"
|
|
41
40
|
},
|
|
42
41
|
"devDependencies": {
|
|
@@ -47,7 +46,8 @@
|
|
|
47
46
|
"tinybench": "^6.2.3",
|
|
48
47
|
"tsdown": "^0.23.7",
|
|
49
48
|
"typescript": "^7.0.2",
|
|
50
|
-
"vitest": "^5.1.0"
|
|
49
|
+
"vitest": "^5.1.0",
|
|
50
|
+
"yaml": "^2.9.1"
|
|
51
51
|
},
|
|
52
52
|
"peerDependencies": {
|
|
53
53
|
"typescript": ">=6.0.3"
|