@twin.org/background-task-models 0.0.3-next.3 → 0.0.3-next.5

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.
Files changed (10) hide show
  1. package/README.md +1 -1
  2. package/docs/changelog.md +15 -1
  3. package/docs/examples.md +179 -1
  4. package/docs/reference/interfaces/IBackgroundTask.md +22 -22
  5. package/docs/reference/interfaces/IBackgroundTaskComponent.md +10 -10
  6. package/docs/reference/interfaces/IScheduledTaskInfo.md +1 -1
  7. package/docs/reference/interfaces/IScheduledTaskTime.md +8 -8
  8. package/docs/reference/interfaces/ITaskSchedulerComponent.md +3 -3
  9. package/docs/reference/variables/TaskStatus.md +5 -5
  10. package/package.json +2 -2
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # TWIN Background Task Models
2
2
 
3
- Models which define the structure of the background task contracts.
3
+ This package is part of the background task toolkit and helps build reliable asynchronous workflows in TWIN applications.
4
4
 
5
5
  ## Installation
6
6
 
package/docs/changelog.md CHANGED
@@ -1,4 +1,18 @@
1
- # @twin.org/background-task-models - Changelog
1
+ # Changelog
2
+
3
+ ## [0.0.3-next.5](https://github.com/twinfoundation/background-task/compare/background-task-models-v0.0.3-next.4...background-task-models-v0.0.3-next.5) (2026-04-10)
4
+
5
+
6
+ ### Miscellaneous Chores
7
+
8
+ * **background-task-models:** Synchronize repo versions
9
+
10
+ ## [0.0.3-next.4](https://github.com/twinfoundation/background-task/compare/background-task-models-v0.0.3-next.3...background-task-models-v0.0.3-next.4) (2026-02-23)
11
+
12
+
13
+ ### Miscellaneous Chores
14
+
15
+ * **background-task-models:** Synchronize repo versions
2
16
 
3
17
  ## [0.0.3-next.3](https://github.com/twinfoundation/background-task/compare/background-task-models-v0.0.3-next.2...background-task-models-v0.0.3-next.3) (2026-01-07)
4
18
 
package/docs/examples.md CHANGED
@@ -1 +1,179 @@
1
- # @twin.org/background-task-models - Examples
1
+ # Background Task Models Examples
2
+
3
+ Use these snippets to model task payloads, status transitions and scheduler contracts in a strongly typed way.
4
+
5
+ ## IBackgroundTask
6
+
7
+ ```typescript
8
+ import type { IBackgroundTask } from '@twin.org/background-task-models';
9
+ import { TaskStatus } from '@twin.org/background-task-models';
10
+
11
+ type ImportPayload = {
12
+ source: string;
13
+ batchSize: number;
14
+ };
15
+
16
+ type ImportResult = {
17
+ inserted: number;
18
+ skipped: number;
19
+ };
20
+
21
+ const queuedTask: IBackgroundTask<ImportPayload, ImportResult> = {
22
+ id: '7f4b2c18a4f44f1f9ff7348e260ca4c2',
23
+ type: 'catalogue-import',
24
+ threadId: '0',
25
+ dateCreated: '2026-03-09T10:30:00.000Z',
26
+ dateModified: '2026-03-09T10:30:00.000Z',
27
+ status: TaskStatus.Pending,
28
+ payload: {
29
+ source: 'tenant-a',
30
+ batchSize: 250
31
+ },
32
+ retriesRemaining: 3,
33
+ retryInterval: 5000
34
+ };
35
+
36
+ console.log(queuedTask.status); // pending
37
+ ```
38
+
39
+ ```typescript
40
+ import type { IBackgroundTask } from '@twin.org/background-task-models';
41
+ import { TaskStatus } from '@twin.org/background-task-models';
42
+
43
+ type ImportResult = {
44
+ inserted: number;
45
+ skipped: number;
46
+ };
47
+
48
+ const completedTask: IBackgroundTask<unknown, ImportResult> = {
49
+ id: '7f4b2c18a4f44f1f9ff7348e260ca4c2',
50
+ type: 'catalogue-import',
51
+ threadId: '3',
52
+ dateCreated: '2026-03-09T10:30:00.000Z',
53
+ dateModified: '2026-03-09T10:31:22.000Z',
54
+ dateCompleted: '2026-03-09T10:31:22.000Z',
55
+ status: TaskStatus.Success,
56
+ result: {
57
+ inserted: 248,
58
+ skipped: 2
59
+ }
60
+ };
61
+
62
+ console.log(completedTask.result?.inserted); // 248
63
+ ```
64
+
65
+ ## IBackgroundTaskComponent
66
+
67
+ ```typescript
68
+ import type { IBackgroundTask, IBackgroundTaskComponent } from '@twin.org/background-task-models';
69
+ import { TaskStatus } from '@twin.org/background-task-models';
70
+
71
+ type ResizePayload = {
72
+ imageId: string;
73
+ width: number;
74
+ height: number;
75
+ };
76
+
77
+ type ResizeResult = {
78
+ imageId: string;
79
+ location: string;
80
+ };
81
+
82
+ export async function configureImageHandler(
83
+ taskComponent: IBackgroundTaskComponent
84
+ ): Promise<void> {
85
+ await taskComponent.registerHandler<ResizePayload, ResizeResult>(
86
+ 'image-resize',
87
+ './workers/imageWorker',
88
+ 'resize',
89
+ async (task: IBackgroundTask<ResizePayload, ResizeResult>) => {
90
+ if (task.status === TaskStatus.Success) {
91
+ console.log(task.result?.location); // s3://tenant-a/images/hero-1920x1080.webp
92
+ }
93
+ },
94
+ {
95
+ maxWorkerCount: 4,
96
+ idleShutdownTimeout: 60000,
97
+ initialiseMethod: 'initialise',
98
+ shutdownMethod: 'shutdown'
99
+ }
100
+ );
101
+
102
+ const taskId = await taskComponent.create<ResizePayload>(
103
+ 'image-resize',
104
+ {
105
+ imageId: 'hero',
106
+ width: 1920,
107
+ height: 1080
108
+ },
109
+ {
110
+ retryCount: 2,
111
+ retryInterval: 3000,
112
+ retainFor: 120000
113
+ }
114
+ );
115
+
116
+ const task = await taskComponent.get<ResizePayload, ResizeResult>(taskId);
117
+ console.log(task?.status); // pending
118
+ }
119
+ ```
120
+
121
+ ## ITaskSchedulerComponent
122
+
123
+ ```typescript
124
+ import type { ITaskSchedulerComponent } from '@twin.org/background-task-models';
125
+
126
+ export async function registerDailySync(
127
+ scheduler: ITaskSchedulerComponent,
128
+ syncTaskId: string
129
+ ): Promise<void> {
130
+ await scheduler.addTask(
131
+ syncTaskId,
132
+ [
133
+ {
134
+ nextTriggerTime: Date.now() + 15 * 60 * 1000,
135
+ intervalDays: 1
136
+ }
137
+ ],
138
+ async () => {
139
+ console.log('sync running at', new Date().toISOString()); // sync running at 2026-03-09T10:45:00.000Z
140
+ }
141
+ );
142
+
143
+ const info = await scheduler.tasksInfo();
144
+ console.log(info.tasks[syncTaskId].length); // 1
145
+ }
146
+ ```
147
+
148
+ ## IScheduledTaskInfo and IScheduledTaskTime
149
+
150
+ ```typescript
151
+ import type { IScheduledTaskInfo, IScheduledTaskTime } from '@twin.org/background-task-models';
152
+
153
+ const everyQuarterHour: IScheduledTaskTime = {
154
+ intervalMinutes: 15
155
+ };
156
+
157
+ const schedule: IScheduledTaskInfo = {
158
+ tasks: {
159
+ 'cleanup-cache': [everyQuarterHour]
160
+ }
161
+ };
162
+
163
+ console.log(schedule.tasks['cleanup-cache'][0].intervalMinutes); // 15
164
+ ```
165
+
166
+ ## TaskStatus
167
+
168
+ ```typescript
169
+ import type { TaskStatus } from '@twin.org/background-task-models';
170
+ import { TaskStatus as TaskStatuses } from '@twin.org/background-task-models';
171
+
172
+ const terminalStatuses: TaskStatus[] = [
173
+ TaskStatuses.Success,
174
+ TaskStatuses.Failed,
175
+ TaskStatuses.Cancelled
176
+ ];
177
+
178
+ console.log(terminalStatuses.join(', ')); // success, failed, cancelled
179
+ ```
package/docs/reference/interfaces/IBackgroundTask.md CHANGED
@@ -14,7 +14,7 @@ Interface describing a background task.
14
14
 
15
15
  ## Properties
16
16
 
17
- ### id
17
+ ### id {#id}
18
18
 
19
19
  > **id**: `string`
20
20
 
@@ -22,7 +22,7 @@ The id.
22
22
 
23
23
  ***
24
24
 
25
- ### type
25
+ ### type {#type}
26
26
 
27
27
  > **type**: `string`
28
28
 
@@ -30,7 +30,7 @@ The type of the task.
30
30
 
31
31
  ***
32
32
 
33
- ### threadId
33
+ ### threadId {#threadid}
34
34
 
35
35
  > **threadId**: `string`
36
36
 
@@ -38,23 +38,23 @@ The thread id for the task.
38
38
 
39
39
  ***
40
40
 
41
- ### retryInterval?
41
+ ### retryInterval? {#retryinterval}
42
42
 
43
- > `optional` **retryInterval**: `number`
43
+ > `optional` **retryInterval?**: `number`
44
44
 
45
45
  The retry interval in milliseconds, undefined if default scheduling.
46
46
 
47
47
  ***
48
48
 
49
- ### retriesRemaining?
49
+ ### retriesRemaining? {#retriesremaining}
50
50
 
51
- > `optional` **retriesRemaining**: `number`
51
+ > `optional` **retriesRemaining?**: `number`
52
52
 
53
53
  The number of retries remaining, undefined if infinite retries.
54
54
 
55
55
  ***
56
56
 
57
- ### dateCreated
57
+ ### dateCreated {#datecreated}
58
58
 
59
59
  > **dateCreated**: `string`
60
60
 
@@ -62,7 +62,7 @@ The date the task was created.
62
62
 
63
63
  ***
64
64
 
65
- ### dateModified
65
+ ### dateModified {#datemodified}
66
66
 
67
67
  > **dateModified**: `string`
68
68
 
@@ -70,31 +70,31 @@ The date the task was last modified.
70
70
 
71
71
  ***
72
72
 
73
- ### dateCompleted?
73
+ ### dateCompleted? {#datecompleted}
74
74
 
75
- > `optional` **dateCompleted**: `string`
75
+ > `optional` **dateCompleted?**: `string`
76
76
 
77
77
  The date the task was complete.
78
78
 
79
79
  ***
80
80
 
81
- ### dateCancelled?
81
+ ### dateCancelled? {#datecancelled}
82
82
 
83
- > `optional` **dateCancelled**: `string`
83
+ > `optional` **dateCancelled?**: `string`
84
84
 
85
85
  The date the task was cancelled.
86
86
 
87
87
  ***
88
88
 
89
- ### dateRetainUntil?
89
+ ### dateRetainUntil? {#dateretainuntil}
90
90
 
91
- > `optional` **dateRetainUntil**: `string`
91
+ > `optional` **dateRetainUntil?**: `string`
92
92
 
93
93
  The date until when to retain.
94
94
 
95
95
  ***
96
96
 
97
- ### status
97
+ ### status {#status}
98
98
 
99
99
  > **status**: [`TaskStatus`](../type-aliases/TaskStatus.md)
100
100
 
@@ -102,24 +102,24 @@ The status of the task.
102
102
 
103
103
  ***
104
104
 
105
- ### payload?
105
+ ### payload? {#payload}
106
106
 
107
- > `optional` **payload**: `T`
107
+ > `optional` **payload?**: `T`
108
108
 
109
109
  The payload to execute the task with.
110
110
 
111
111
  ***
112
112
 
113
- ### result?
113
+ ### result? {#result}
114
114
 
115
- > `optional` **result**: `U`
115
+ > `optional` **result?**: `U`
116
116
 
117
117
  The result of the execution.
118
118
 
119
119
  ***
120
120
 
121
- ### error?
121
+ ### error? {#error}
122
122
 
123
- > `optional` **error**: `IError`
123
+ > `optional` **error?**: `IError`
124
124
 
125
125
  The error at last execution.
package/docs/reference/interfaces/IBackgroundTaskComponent.md CHANGED
@@ -8,7 +8,7 @@ Interface describing a background task component.
8
8
 
9
9
  ## Methods
10
10
 
11
- ### registerHandler()
11
+ ### registerHandler() {#registerhandler}
12
12
 
13
13
  > **registerHandler**\<`T`, `U`\>(`taskType`, `module`, `method`, `stateChangeCallback?`, `options?`): `Promise`\<`void`\>
14
14
 
@@ -86,7 +86,7 @@ Nothing.
86
86
 
87
87
  ***
88
88
 
89
- ### unregisterHandler()
89
+ ### unregisterHandler() {#unregisterhandler}
90
90
 
91
91
  > **unregisterHandler**(`taskType`): `Promise`\<`void`\>
92
92
 
@@ -108,7 +108,7 @@ Nothing.
108
108
 
109
109
  ***
110
110
 
111
- ### create()
111
+ ### create() {#create}
112
112
 
113
113
  > **create**\<`T`\>(`taskType`, `payload?`, `options?`): `Promise`\<`string`\>
114
114
 
@@ -164,7 +164,7 @@ The id of the created task.
164
164
 
165
165
  ***
166
166
 
167
- ### get()
167
+ ### get() {#get}
168
168
 
169
169
  > **get**\<`T`, `U`\>(`taskId`): `Promise`\<[`IBackgroundTask`](IBackgroundTask.md)\<`T`, `U`\> \| `undefined`\>
170
170
 
@@ -196,7 +196,7 @@ The details of the task.
196
196
 
197
197
  ***
198
198
 
199
- ### retry()
199
+ ### retry() {#retry}
200
200
 
201
201
  > **retry**(`taskId`): `Promise`\<`void`\>
202
202
 
@@ -218,7 +218,7 @@ Nothing.
218
218
 
219
219
  ***
220
220
 
221
- ### remove()
221
+ ### remove() {#remove}
222
222
 
223
223
  > **remove**(`taskId`): `Promise`\<`void`\>
224
224
 
@@ -240,7 +240,7 @@ Nothing.
240
240
 
241
241
  ***
242
242
 
243
- ### cancel()
243
+ ### cancel() {#cancel}
244
244
 
245
245
  > **cancel**(`taskId`): `Promise`\<`void`\>
246
246
 
@@ -262,7 +262,7 @@ Nothing.
262
262
 
263
263
  ***
264
264
 
265
- ### query()
265
+ ### query() {#query}
266
266
 
267
267
  > **query**(`taskType?`, `taskStatus?`, `sortProperty?`, `sortDirection?`, `cursor?`, `limit?`): `Promise`\<\{ `entities`: [`IBackgroundTask`](IBackgroundTask.md)\<`any`, `any`\>[]; `cursor?`: `string`; \}\>
268
268
 
@@ -284,9 +284,9 @@ The status of the task to get.
284
284
 
285
285
  ##### sortProperty?
286
286
 
287
- The property to sort by, defaults to dateCreated.
287
+ `"dateCreated"` \| `"dateModified"` \| `"dateCompleted"` \| `"status"`
288
288
 
289
- `"dateCreated"` | `"dateModified"` | `"dateCompleted"` | `"status"`
289
+ The property to sort by, defaults to dateCreated.
290
290
 
291
291
  ##### sortDirection?
292
292
 
package/docs/reference/interfaces/IScheduledTaskInfo.md CHANGED
@@ -4,7 +4,7 @@ Interface describing a scheduled task information.
4
4
 
5
5
  ## Properties
6
6
 
7
- ### tasks
7
+ ### tasks {#tasks}
8
8
 
9
9
  > **tasks**: `object`
10
10
 
package/docs/reference/interfaces/IScheduledTaskTime.md CHANGED
@@ -4,32 +4,32 @@ Interface describing a scheduled task time.
4
4
 
5
5
  ## Properties
6
6
 
7
- ### nextTriggerTime?
7
+ ### nextTriggerTime? {#nexttriggertime}
8
8
 
9
- > `optional` **nextTriggerTime**: `number`
9
+ > `optional` **nextTriggerTime?**: `number`
10
10
 
11
11
  The date/time to start the task, if not provided defaults to first interval from now.
12
12
 
13
13
  ***
14
14
 
15
- ### intervalDays?
15
+ ### intervalDays? {#intervaldays}
16
16
 
17
- > `optional` **intervalDays**: `number`
17
+ > `optional` **intervalDays?**: `number`
18
18
 
19
19
  The interval in days to repeat the task, if no intervals are set the task will not repeat.
20
20
 
21
21
  ***
22
22
 
23
- ### intervalHours?
23
+ ### intervalHours? {#intervalhours}
24
24
 
25
- > `optional` **intervalHours**: `number`
25
+ > `optional` **intervalHours?**: `number`
26
26
 
27
27
  The interval in hours to repeat the task, if no intervals are set the task will not repeat.
28
28
 
29
29
  ***
30
30
 
31
- ### intervalMinutes?
31
+ ### intervalMinutes? {#intervalminutes}
32
32
 
33
- > `optional` **intervalMinutes**: `number`
33
+ > `optional` **intervalMinutes?**: `number`
34
34
 
35
35
  The interval in minutes to repeat the task, if no intervals are set the task will not repeat.
package/docs/reference/interfaces/ITaskSchedulerComponent.md CHANGED
@@ -8,7 +8,7 @@ Interface describing a task scheduler.
8
8
 
9
9
  ## Methods
10
10
 
11
- ### addTask()
11
+ ### addTask() {#addtask}
12
12
 
13
13
  > **addTask**(`taskId`, `times`, `taskCallback`): `Promise`\<`void`\>
14
14
 
@@ -42,7 +42,7 @@ Nothing.
42
42
 
43
43
  ***
44
44
 
45
- ### removeTask()
45
+ ### removeTask() {#removetask}
46
46
 
47
47
  > **removeTask**(`taskId`): `Promise`\<`void`\>
48
48
 
@@ -64,7 +64,7 @@ Nothing.
64
64
 
65
65
  ***
66
66
 
67
- ### tasksInfo()
67
+ ### tasksInfo() {#tasksinfo}
68
68
 
69
69
  > **tasksInfo**(): `Promise`\<[`IScheduledTaskInfo`](IScheduledTaskInfo.md)\>
70
70
 
package/docs/reference/variables/TaskStatus.md CHANGED
@@ -6,31 +6,31 @@ Task statuses.
6
6
 
7
7
  ## Type Declaration
8
8
 
9
- ### Pending
9
+ ### Pending {#pending}
10
10
 
11
11
  > `readonly` **Pending**: `"pending"` = `"pending"`
12
12
 
13
13
  Pending.
14
14
 
15
- ### Processing
15
+ ### Processing {#processing}
16
16
 
17
17
  > `readonly` **Processing**: `"processing"` = `"processing"`
18
18
 
19
19
  Processing.
20
20
 
21
- ### Success
21
+ ### Success {#success}
22
22
 
23
23
  > `readonly` **Success**: `"success"` = `"success"`
24
24
 
25
25
  Success.
26
26
 
27
- ### Failed
27
+ ### Failed {#failed}
28
28
 
29
29
  > `readonly` **Failed**: `"failed"` = `"failed"`
30
30
 
31
31
  Failed.
32
32
 
33
- ### Cancelled
33
+ ### Cancelled {#cancelled}
34
34
 
35
35
  > `readonly` **Cancelled**: `"cancelled"` = `"cancelled"`
36
36
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@twin.org/background-task-models",
3
- "version": "0.0.3-next.3",
4
- "description": "Models which define the structure of the background task contracts",
3
+ "version": "0.0.3-next.5",
4
+ "description": "Defines shared contracts and status models for background task workflows",
5
5
  "repository": {
6
6
  "type": "git",
7
7
  "url": "git+https://github.com/twinfoundation/background-task.git",