@type32/tasks 0.1.0 β†’ 0.1.2

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.
@@ -0,0 +1,194 @@
1
+ # Unusual but valid inputs and exactly what reading them must produce. Shared by every implementation.
2
+ #
3
+ # Each case: `name`, `format` (json | yaml | toml | markdown | ics), `input` text, `expect` result:
4
+ # json | yaml | toml: the document
5
+ # markdown: { task, frontmatter, syntax }
6
+ # ics: the document; nothing may be dropped
7
+
8
+ - name: json with a byte-order mark and unicode escapes
9
+ format: json
10
+ input: "\uFEFF{\"version\":\"1.0\",\"tasks\":[{\"id\":\"caf\\u00e9\",\"title\":\"\\ud83d\\ude00 \\\"quoted\\\"\",\"updatedAt\":\"2026-11-09T10:00:00Z\"}]}"
11
+ expect:
12
+ version: "1.0"
13
+ tasks: [{ id: cafΓ©, title: 'πŸ˜€ "quoted"', updatedAt: "2026-11-09T10:00:00Z" }]
14
+
15
+ - name: empty task list and empty title
16
+ format: json
17
+ input: '{"version":"1.0","lists":[],"fields":[],"tasks":[{"id":"a","title":"","updatedAt":"2026-11-09T10:00:00Z"}]}'
18
+ expect:
19
+ version: "1.0"
20
+ lists: []
21
+ fields: []
22
+ tasks: [{ id: a, title: "", updatedAt: "2026-11-09T10:00:00Z" }]
23
+
24
+ - name: future minor version and unknown keys are kept
25
+ format: yaml
26
+ input: |
27
+ version: "1.9"
28
+ x-app: { theme: dark }
29
+ tasks:
30
+ - { id: a, title: A, x-sort: 3, updatedAt: 2026-11-09T10:00:00Z }
31
+ expect:
32
+ version: "1.9"
33
+ x-app: { theme: dark }
34
+ tasks: [{ id: a, title: A, x-sort: 3, updatedAt: "2026-11-09T10:00:00Z" }]
35
+
36
+ - name: yaml unquoted dates stay strings; comments, anchors and block scalars
37
+ format: yaml
38
+ input: |
39
+ # a hand-written file
40
+ version: "1.0"
41
+ tasks:
42
+ - id: a
43
+ title: Standup # trailing comment
44
+ start: 2026-11-10T09:30
45
+ duration: PT15M
46
+ updatedAt: 2026-11-09T10:00:00Z
47
+ notes: |
48
+ Line one
49
+ indented
50
+ values: { tags: &shared [team, daily] }
51
+ - id: b
52
+ title: >
53
+ Folded
54
+ title
55
+ due: 2028-02-29
56
+ updatedAt: 2026-11-09T10:00:00.123456789Z
57
+ values: { tags: *shared }
58
+ expect:
59
+ version: "1.0"
60
+ tasks:
61
+ - id: a
62
+ title: Standup
63
+ start: 2026-11-10T09:30
64
+ duration: PT15M
65
+ updatedAt: "2026-11-09T10:00:00Z"
66
+ notes: "Line one\n indented\n"
67
+ values: { tags: [team, daily] }
68
+ - id: b
69
+ title: "Folded title\n"
70
+ due: "2028-02-29"
71
+ updatedAt: "2026-11-09T10:00:00.123456789Z"
72
+ values: { tags: [team, daily] }
73
+
74
+ - name: yaml flow style on one line
75
+ format: yaml
76
+ input: '{ version: "1.0", tasks: [{ id: a, title: A, values: { progress: 0 }, updatedAt: 2026-11-09T10:00:00Z }] }'
77
+ expect:
78
+ version: "1.0"
79
+ tasks: [{ id: a, title: A, values: { progress: 0 }, updatedAt: "2026-11-09T10:00:00Z" }]
80
+
81
+ - name: toml native dates become strings; dotted keys, inline tables, literal and multi-line strings
82
+ format: toml
83
+ input: |
84
+ version = "1.0"
85
+
86
+ [[tasks]]
87
+ id = 'C:\literal'
88
+ title = """
89
+ Two
90
+ lines"""
91
+ start = 2026-11-10T09:30:00
92
+ due = 2026-11-12
93
+ timeZone = "Etc/GMT-14"
94
+ updatedAt = 2026-11-09T10:00:00Z
95
+ values.status = "doing"
96
+ recurrence = { freq = "weekly", byDay = [{ day = "tu" }] }
97
+ expect:
98
+ version: "1.0"
99
+ tasks:
100
+ - id: 'C:\literal'
101
+ title: "Two\nlines"
102
+ start: "2026-11-10T09:30:00.000"
103
+ due: "2026-11-12"
104
+ timeZone: Etc/GMT-14
105
+ updatedAt: "2026-11-09T10:00:00.000Z"
106
+ values: { status: doing }
107
+ recurrence: { freq: weekly, byDay: [{ day: tu }] }
108
+
109
+ - name: nine fraction digits and the last second of the day
110
+ format: yaml
111
+ input: |
112
+ version: "1.0"
113
+ tasks: [{ id: a, title: A, start: 2026-12-31T23:59:59.999999999, updatedAt: 2026-11-09T10:00:00Z }]
114
+ expect:
115
+ version: "1.0"
116
+ tasks:
117
+ [{ id: a, title: A, start: 2026-12-31T23:59:59.999999999, updatedAt: "2026-11-09T10:00:00Z" }]
118
+
119
+ - name: open selects, deleted options and deleted fields are valid targets
120
+ format: yaml
121
+ input: |
122
+ version: "1.0"
123
+ fields:
124
+ - { id: client, title: Client, type: select, open: true, updatedAt: 2026-11-09T10:00:00Z }
125
+ - id: stage
126
+ title: Stage
127
+ type: select
128
+ options: [{ id: old, title: Old, updatedAt: 2026-11-09T10:00:00Z, deletedAt: 2026-11-09T10:00:00Z }]
129
+ updatedAt: 2026-11-09T10:00:00Z
130
+ - { id: legacy, title: Legacy, type: text, updatedAt: 2026-11-09T10:00:00Z, deletedAt: 2026-11-09T10:00:00Z }
131
+ tasks: [{ id: a, title: A, values: { client: Anyone Inc., stage: old, legacy: kept }, updatedAt: 2026-11-09T10:00:00Z }]
132
+ expect:
133
+ version: "1.0"
134
+ fields:
135
+ - { id: client, title: Client, type: select, open: true, updatedAt: "2026-11-09T10:00:00Z" }
136
+ - id: stage
137
+ title: Stage
138
+ type: select
139
+ options:
140
+ [
141
+ {
142
+ id: old,
143
+ title: Old,
144
+ updatedAt: "2026-11-09T10:00:00Z",
145
+ deletedAt: "2026-11-09T10:00:00Z",
146
+ },
147
+ ]
148
+ updatedAt: "2026-11-09T10:00:00Z"
149
+ - {
150
+ id: legacy,
151
+ title: Legacy,
152
+ type: text,
153
+ updatedAt: "2026-11-09T10:00:00Z",
154
+ deletedAt: "2026-11-09T10:00:00Z",
155
+ }
156
+ tasks:
157
+ [
158
+ {
159
+ id: a,
160
+ title: A,
161
+ values: { client: Anyone Inc., stage: old, legacy: kept },
162
+ updatedAt: "2026-11-09T10:00:00Z",
163
+ },
164
+ ]
165
+
166
+ - name: markdown with BOM, CRLF and fence-like lines in the body
167
+ format: markdown
168
+ input: "\uFEFF---\r\ntask: { id: a, title: A, updatedAt: 2026-11-09T10:00:00Z }\r\n--- \r\nbody\r\n---\r\n+++\r\n"
169
+ expect:
170
+ task: { id: a, title: A, updatedAt: "2026-11-09T10:00:00Z", notes: "body\r\n---\r\n+++\r\n" }
171
+ frontmatter: {}
172
+ syntax: yaml
173
+
174
+ - name: markdown toml frontmatter with other keys and no body
175
+ format: markdown
176
+ input: "+++\ndraft = true\n[task]\nid = \"a\"\ntitle = \"A\"\nupdatedAt = 2026-11-09T10:00:00Z\n+++"
177
+ expect:
178
+ task: { id: a, title: A, updatedAt: "2026-11-09T10:00:00.000Z" }
179
+ frontmatter: { draft: true }
180
+ syntax: toml
181
+
182
+ - name: ics lowercase names, tab folding, quoted parameters, LF endings
183
+ format: ics
184
+ input: "begin:vcalendar\nbegin:vevent\nuid:a\ndtstart;tzid=\"Europe/Berlin\":20261110T090000\nsummary:Fol\n\tded\\, text\nlast-modified:20261101T080000Z\nend:vevent\nend:vcalendar\n"
185
+ expect:
186
+ version: "1.0"
187
+ tasks:
188
+ - {
189
+ id: a,
190
+ title: "Folded, text",
191
+ start: 2026-11-10T09:00,
192
+ timeZone: Europe/Berlin,
193
+ updatedAt: "2026-11-01T08:00:00Z",
194
+ }
package/dist/index.d.mts CHANGED
@@ -7,83 +7,130 @@ type LocalDateTime = string;
7
7
  type UTCDateTime = string;
8
8
  /** ISO 8601 duration without years or months: `PT1H30M`, `P1D`, `P2W`. */
9
9
  type Duration = string;
10
+ /** Value type of a field. `select`/`multiSelect` values are option ids. */
10
11
  type FieldType = "text" | "number" | "boolean" | "date" | "url" | "select" | "multiSelect";
12
+ /** A value in `Task.values`: text, a finite number, a boolean, or a list of option ids (multiSelect). */
11
13
  type FieldValue = string | number | boolean | string[];
12
14
  type Frequency = "daily" | "weekly" | "monthly" | "yearly";
15
+ /** Weeks start on Monday. */
13
16
  type Weekday = "mo" | "tu" | "we" | "th" | "fr" | "sa" | "su";
14
- /** Derived from which time fields a task has; never stored. */
17
+ /**
18
+ * Derived from which time fields a task has; never stored (see `kindOf`).
19
+ * - `span`: `start` plus `end` or `duration` (calendar event, timeline bar)
20
+ * - `moment`: `start` only (milestone)
21
+ * - `todo`: no `start` (reminder, optionally with `due`)
22
+ */
15
23
  type Kind = "span" | "moment" | "todo";
16
24
  /** Anything `merge()` can reconcile: identified, timestamped, soft-deleted. */
17
25
  interface Synced {
26
+ /** Unique within its collection. Use UUIDs for anything that syncs. */
18
27
  id: string;
28
+ /** Set to the current UTC time on every change; `merge()` keeps the later one. */
19
29
  updatedAt: UTCDateTime;
30
+ /** Soft delete: the record stays so references to it remain valid. Hide or archive it in UIs. */
20
31
  deletedAt?: UTCDateTime;
21
32
  /** Unknown keys are kept and written back. */
22
33
  [key: string]: unknown;
23
34
  }
35
+ /** A container: todo list, calendar, or timeline project. */
24
36
  interface List extends Synced {
25
37
  title: string;
38
+ /** `#rrggbb`. */
26
39
  color?: string;
40
+ /** Parent list; lists nest. No cycles. */
27
41
  parentId?: string;
28
42
  }
43
+ /** A choice of a select field. Each option is its own synced record. */
29
44
  interface FieldOption extends Synced {
45
+ /** Required, except when only recoloring or renaming a built-in option. */
30
46
  title?: string;
47
+ /** `#rrggbb`. */
31
48
  color?: string;
49
+ /** The fixed meaning this option maps to; one of the field's `categories` (e.g. `done` for status). */
32
50
  category?: string;
33
51
  }
34
52
  /**
53
+ * A custom field, or options added to a built-in one.
35
54
  * Built-in ids (`status`, `priority`, `tags`, `progress`, `location`) only take `options`;
36
- * everything else needs `title`, `type`, `updatedAt`.
55
+ * custom fields need `title`, `type`, `updatedAt`.
37
56
  */
38
57
  interface FieldDefinition {
58
+ /** The key used in `Task.values`. */
39
59
  id: string;
40
60
  title?: string;
41
61
  type?: FieldType;
62
+ /** Select types only: the fixed meanings options must map to. */
42
63
  categories?: string[];
64
+ /** Select types only: allow values that aren't option ids (free-text tags). */
43
65
  open?: boolean;
66
+ /** Number type only. */
44
67
  min?: number;
68
+ /** Number type only. */
45
69
  max?: number;
70
+ /** Select types only. */
46
71
  options?: FieldOption[];
47
72
  updatedAt?: UTCDateTime;
48
73
  deletedAt?: UTCDateTime;
49
74
  [key: string]: unknown;
50
75
  }
76
+ /** Repeats the task's anchor: `start`, or `due` without a `start`. Expand with `occurrences()`. */
51
77
  interface Recurrence {
52
78
  freq: Frequency;
79
+ /** Every n-th period; default 1. */
53
80
  interval?: number;
54
- /** `nth` (e.g. 2 = second, -1 = last) only with monthly/yearly. */
81
+ /** Weekdays; `nth` (2 = second, -1 = last) only with monthly/yearly. */
55
82
  byDay?: {
56
83
  day: Weekday;
57
84
  nth?: number;
58
85
  }[];
86
+ /** Days of the month, Β±1…31; negative counts from the end. Missing dates (the 31st in April) are skipped. */
59
87
  byMonthDay?: number[];
88
+ /** Months 1…12. */
60
89
  byMonth?: number[];
90
+ /** Total occurrences including the anchor and excluded ones. Not with `until`. */
61
91
  count?: number;
92
+ /** Last possible occurrence, inclusive; same form (date or date-time) as the anchor. Not with `count`. */
62
93
  until?: LocalDate | LocalDateTime;
63
94
  }
95
+ /** A todo, event, or timeline item: which one depends only on its time fields (see `Kind`). */
64
96
  interface Task extends Synced {
65
97
  title: string;
98
+ /** Free text; the Markdown body for task files. */
66
99
  notes?: string;
67
100
  listId?: string;
101
+ /** Parent task (subtask). No cycles. */
68
102
  parentId?: string;
103
+ /** Tasks that must finish before this one. No cycles. */
69
104
  dependsOn?: string[];
105
+ /** Date means all-day; date-time is wall-clock time in `timeZone`. */
70
106
  start?: LocalDate | LocalDateTime;
107
+ /** Needs `start`, same form, not before it. A date `end` is inclusive (10th–12th is three days). Not with `duration`. */
71
108
  end?: LocalDate | LocalDateTime;
109
+ /** Needs `start`. All-day tasks take whole days or weeks. Not with `end`. */
72
110
  duration?: Duration;
73
111
  due?: LocalDate | LocalDateTime;
112
+ /** IANA zone (`Europe/Berlin`) for every local time on the task. Absent: floating (same wall clock everywhere). */
74
113
  timeZone?: string;
75
114
  recurrence?: Recurrence;
115
+ /** Occurrences to skip, same form as the anchor. Needs `recurrence`. */
76
116
  excludedDates?: (LocalDate | LocalDateTime)[];
77
117
  completedAt?: UTCDateTime;
118
+ /**
119
+ * Field id β†’ value, built-in (`status`, `priority`, `tags`, `progress`, `location`) and custom alike.
120
+ * A key must name a field; a select value must be an option id. Read meanings with `resolveFields()`.
121
+ */
78
122
  values?: Record<string, FieldValue>;
79
123
  }
124
+ /** A whole file: lists, field definitions and tasks. */
80
125
  interface TaskDocument {
126
+ /** `"1.0"`; readers accept any `1.x`. */
81
127
  version: string;
82
128
  lists?: List[];
83
129
  fields?: FieldDefinition[];
84
130
  tasks: Task[];
85
131
  [key: string]: unknown;
86
132
  }
133
+ /** An option after built-in defaults and document overrides are applied. */
87
134
  interface ResolvedOption {
88
135
  id: string;
89
136
  title: string;
@@ -106,14 +153,21 @@ interface ResolvedField {
106
153
  }
107
154
  /** Built-in fields merged with the document's `fields`. Deleted fields and options stay, flagged `deleted`. */
108
155
  export declare function resolveFields(doc: Pick<TaskDocument, "fields">): Record<string, ResolvedField>;
156
+ /** `span`, `moment` or `todo`, from the task's time fields. Use it to pick how to draw a task. */
109
157
  export declare function kindOf(task: Pick<Task, "start" | "end" | "duration">): Kind;
110
158
  /** The whole format. Use `validate()`/`parse()` for errors as `TasksFormatError`. */
111
159
  export declare const documentSchema: z.ZodType<TaskDocument>;
160
+ /** Text formats for whole documents. Markdown task files and iCalendar have their own functions. */
112
161
  type Format = "json" | "yaml" | "toml";
162
+ /** One problem: where (`["tasks", 3, "values", "status"]`; `[]` is the root) and what, in plain English. */
113
163
  interface Issue {
114
164
  path: (string | number)[];
115
165
  message: string;
116
166
  }
167
+ /**
168
+ * Thrown for any input the format rejects: syntax errors, wrong shapes, broken rules. `message` lists every
169
+ * issue as `path: message` lines, ready to show to a user; `issues` has them structured.
170
+ */
117
171
  export declare class TasksFormatError extends Error {
118
172
  readonly issues: Issue[];
119
173
  constructor(issues: Issue[]);
@@ -123,6 +177,7 @@ export declare class TasksFormatError extends Error {
123
177
  * Cross-field rules (references, cycles, values) only run once the structure is valid.
124
178
  */
125
179
  export declare function validate(value: unknown): TaskDocument;
180
+ /** Reads and validates a whole document. Throws `TasksFormatError`. Dates and times come back as strings. */
126
181
  export declare function parse(text: string, format: Format): TaskDocument;
127
182
  /** Validates, then serializes. Unknown keys are written back unchanged. */
128
183
  export declare function stringify(doc: TaskDocument, format: Format): string;
@@ -165,6 +220,14 @@ interface OccurrenceRange {
165
220
  * task stores `duration`. Assumes a validated task.
166
221
  */
167
222
  export declare function occurrences(task: Task, range: OccurrenceRange): Occurrence[];
223
+ /**
224
+ * Completes a task, returning a new one (the input is unchanged); `updatedAt` becomes `completedAt`.
225
+ * - Recurring with occurrences left: `start`, `end` and `due` move to the next occurrence (by their offsets
226
+ * from the anchor), `count` drops by the occurrences used up, `status` and `progress` (if set) reset to
227
+ * `todo` and 0. `completedAt` is left alone: the series isn't done.
228
+ * - Otherwise, including the last occurrence: `status` becomes `done` and `completedAt` is set.
229
+ */
230
+ export declare function completeTask(task: Task, completedAt: UTCDateTime): Task;
168
231
  /** `dropped` lists what couldn't be carried over: whole components, single properties, or broken references. */
169
232
  interface ImportResult {
170
233
  document: TaskDocument;
@@ -182,4 +245,51 @@ export declare function toICS(doc: TaskDocument): string;
182
245
  * and TZIDs that aren't IANA names. Throws `TasksFormatError` when the text isn't iCalendar.
183
246
  */
184
247
  export declare function fromICS(text: string): ImportResult;
185
- export type { Duration, FieldDefinition, FieldOption, FieldType, FieldValue, Format, Frequency, ImportResult, Issue, Kind, List, LocalDate, LocalDateTime, MergeResult, Occurrence, OccurrenceRange, Recurrence, Repair, ResolvedField, ResolvedOption, Synced, Task, TaskDocument, UTCDateTime, Weekday };
248
+ /** A Markdown file holding one task: frontmatter `task:` object, body as `task.notes`. */
249
+ interface MarkdownTask {
250
+ /** The body is `notes`, byte for byte. */
251
+ task: Task;
252
+ /** Every other frontmatter key, kept as-is. */
253
+ frontmatter: Record<string, unknown>;
254
+ /** `---` fences YAML, `+++` fences TOML. */
255
+ syntax: "yaml" | "toml";
256
+ }
257
+ /**
258
+ * True when `text` opens with YAML or TOML frontmatter holding a `task` object. Reads only the frontmatter
259
+ * and never throws; it doesn't validate the task (use `parseMarkdown` for that). Meant for indexing.
260
+ */
261
+ export declare function isTaskFile(text: string): boolean;
262
+ /**
263
+ * Reads a task file. Checks the task's shape and time rules; references (`listId`, `parentId`, `dependsOn`)
264
+ * and `values` are checked once tasks are combined into a document with `validate()`.
265
+ */
266
+ export declare function parseMarkdown(text: string): MarkdownTask;
267
+ /** Writes frontmatter (other keys first, then `task`) and `task.notes` as the body. Fences use `\n`. */
268
+ export declare function stringifyMarkdown(file: MarkdownTask): string;
269
+ /** What a task's status means, whatever its option is called. */
270
+ type TaskStatus = "todo" | "doing" | "done" | "cancelled";
271
+ type TaskPriority = "low" | "medium" | "high";
272
+ /** Output of `resolveFields(doc)`; resolve once and reuse it across tasks. */
273
+ type Fields = Record<string, ResolvedField>;
274
+ /** The status category: `shipped` β†’ `done` if the document maps it so. No status means `todo`. */
275
+ export declare function statusOf(task: Task, fields: Fields): TaskStatus;
276
+ /** The priority category, or undefined when the task has none. */
277
+ export declare function priorityOf(task: Task, fields: Fields): TaskPriority | undefined;
278
+ /** Status means done. Cancelled tasks aren't complete. */
279
+ export declare function isComplete(task: Task, fields: Fields): boolean;
280
+ /** Still to do: not deleted, and status `todo` or `doing`. */
281
+ export declare function isOpen(task: Task, fields: Fields): boolean;
282
+ interface OverdueOptions {
283
+ /** Default: the current time. */
284
+ now?: Date | UTCDateTime;
285
+ /** The viewer's zone, for all-day and floating due times. Default: the runtime's zone. */
286
+ timeZone?: string;
287
+ }
288
+ /**
289
+ * The task is open and its `due` has passed. An all-day due date is overdue once its day is over in the
290
+ * viewer's zone; a timed one once that moment passes, in the task's `timeZone` if it has one.
291
+ */
292
+ export declare function isOverdue(task: Task, fields: Fields, options?: OverdueOptions): boolean;
293
+ /** The tasks in `dependsOn` still in the way: not done, not cancelled, not deleted. Empty when unblocked. */
294
+ export declare function blockers(task: Task, tasks: readonly Task[], fields: Fields): Task[];
295
+ 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, Weekday };