@math.gl/tasks 0.0.0-stage → 5.0.0-beta.11

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 (212) hide show
  1. package/LICENSE +147 -0
  2. package/LOADERS-GL-LICENSE.txt +52 -0
  3. package/README.md +26 -2
  4. package/THIRD-PARTY-NOTICES.md +5 -0
  5. package/dist/index.cjs +3454 -0
  6. package/dist/index.cjs.map +6 -0
  7. package/dist/index.d.ts +2 -0
  8. package/dist/index.d.ts.map +1 -0
  9. package/dist/index.js +5 -0
  10. package/dist/index.js.map +1 -0
  11. package/dist/tasks/index.d.ts +9 -0
  12. package/dist/tasks/index.d.ts.map +1 -0
  13. package/dist/tasks/index.js +9 -0
  14. package/dist/tasks/index.js.map +1 -0
  15. package/dist/tasks/task-channel.d.ts +48 -0
  16. package/dist/tasks/task-channel.d.ts.map +1 -0
  17. package/dist/tasks/task-channel.js +166 -0
  18. package/dist/tasks/task-channel.js.map +1 -0
  19. package/dist/tasks/task-operation-queue.d.ts +26 -0
  20. package/dist/tasks/task-operation-queue.d.ts.map +1 -0
  21. package/dist/tasks/task-operation-queue.js +106 -0
  22. package/dist/tasks/task-operation-queue.js.map +1 -0
  23. package/dist/tasks/task-preload.d.ts +13 -0
  24. package/dist/tasks/task-preload.d.ts.map +1 -0
  25. package/dist/tasks/task-preload.js +96 -0
  26. package/dist/tasks/task-preload.js.map +1 -0
  27. package/dist/tasks/task-runner.d.ts +74 -0
  28. package/dist/tasks/task-runner.d.ts.map +1 -0
  29. package/dist/tasks/task-runner.js +811 -0
  30. package/dist/tasks/task-runner.js.map +1 -0
  31. package/dist/tasks/task-runtime.d.ts +27 -0
  32. package/dist/tasks/task-runtime.d.ts.map +1 -0
  33. package/dist/tasks/task-runtime.js +216 -0
  34. package/dist/tasks/task-runtime.js.map +1 -0
  35. package/dist/tasks/task-sync.d.ts +4 -0
  36. package/dist/tasks/task-sync.d.ts.map +1 -0
  37. package/dist/tasks/task-sync.js +95 -0
  38. package/dist/tasks/task-sync.js.map +1 -0
  39. package/dist/tasks/task-worker-channel.d.ts +11 -0
  40. package/dist/tasks/task-worker-channel.d.ts.map +1 -0
  41. package/dist/tasks/task-worker-channel.js +34 -0
  42. package/dist/tasks/task-worker-channel.js.map +1 -0
  43. package/dist/tasks/task.d.ts +132 -0
  44. package/dist/tasks/task.d.ts.map +1 -0
  45. package/dist/tasks/task.js +5 -0
  46. package/dist/tasks/task.js.map +1 -0
  47. package/dist/tasks/typed-task-dispatch.d.ts +30 -0
  48. package/dist/tasks/typed-task-dispatch.d.ts.map +1 -0
  49. package/dist/tasks/typed-task-dispatch.js +12 -0
  50. package/dist/tasks/typed-task-dispatch.js.map +1 -0
  51. package/dist/worker-utils/index.d.ts +25 -0
  52. package/dist/worker-utils/index.d.ts.map +1 -0
  53. package/dist/worker-utils/index.js +46 -0
  54. package/dist/worker-utils/index.js.map +1 -0
  55. package/dist/worker-utils/lib/async-queue/async-queue.d.ts +32 -0
  56. package/dist/worker-utils/lib/async-queue/async-queue.d.ts.map +1 -0
  57. package/dist/worker-utils/lib/async-queue/async-queue.js +88 -0
  58. package/dist/worker-utils/lib/async-queue/async-queue.js.map +1 -0
  59. package/dist/worker-utils/lib/env-utils/assert.d.ts +3 -0
  60. package/dist/worker-utils/lib/env-utils/assert.d.ts.map +1 -0
  61. package/dist/worker-utils/lib/env-utils/assert.js +13 -0
  62. package/dist/worker-utils/lib/env-utils/assert.js.map +1 -0
  63. package/dist/worker-utils/lib/env-utils/globals.d.ts +22 -0
  64. package/dist/worker-utils/lib/env-utils/globals.d.ts.map +1 -0
  65. package/dist/worker-utils/lib/env-utils/globals.js +30 -0
  66. package/dist/worker-utils/lib/env-utils/globals.js.map +1 -0
  67. package/dist/worker-utils/lib/env-utils/version.d.ts +3 -0
  68. package/dist/worker-utils/lib/env-utils/version.d.ts.map +1 -0
  69. package/dist/worker-utils/lib/env-utils/version.js +11 -0
  70. package/dist/worker-utils/lib/env-utils/version.js.map +1 -0
  71. package/dist/worker-utils/lib/library-utils/library-utils.d.ts +42 -0
  72. package/dist/worker-utils/lib/library-utils/library-utils.d.ts.map +1 -0
  73. package/dist/worker-utils/lib/library-utils/library-utils.js +251 -0
  74. package/dist/worker-utils/lib/library-utils/library-utils.js.map +1 -0
  75. package/dist/worker-utils/lib/node/worker_threads-browser.d.ts +15 -0
  76. package/dist/worker-utils/lib/node/worker_threads-browser.d.ts.map +1 -0
  77. package/dist/worker-utils/lib/node/worker_threads-browser.js +23 -0
  78. package/dist/worker-utils/lib/node/worker_threads-browser.js.map +1 -0
  79. package/dist/worker-utils/lib/node/worker_threads.d.ts +16 -0
  80. package/dist/worker-utils/lib/node/worker_threads.d.ts.map +1 -0
  81. package/dist/worker-utils/lib/node/worker_threads.js +7 -0
  82. package/dist/worker-utils/lib/node/worker_threads.js.map +1 -0
  83. package/dist/worker-utils/lib/npm-tag.d.ts +2 -0
  84. package/dist/worker-utils/lib/npm-tag.d.ts.map +1 -0
  85. package/dist/worker-utils/lib/npm-tag.js +5 -0
  86. package/dist/worker-utils/lib/npm-tag.js.map +1 -0
  87. package/dist/worker-utils/lib/process-utils/child-process-proxy.browser.d.ts +8 -0
  88. package/dist/worker-utils/lib/process-utils/child-process-proxy.browser.d.ts.map +1 -0
  89. package/dist/worker-utils/lib/process-utils/child-process-proxy.browser.js +18 -0
  90. package/dist/worker-utils/lib/process-utils/child-process-proxy.browser.js.map +1 -0
  91. package/dist/worker-utils/lib/process-utils/child-process-proxy.d.ts +45 -0
  92. package/dist/worker-utils/lib/process-utils/child-process-proxy.d.ts.map +1 -0
  93. package/dist/worker-utils/lib/process-utils/child-process-proxy.js +128 -0
  94. package/dist/worker-utils/lib/process-utils/child-process-proxy.js.map +1 -0
  95. package/dist/worker-utils/lib/process-utils/process-utils.d.ts +2 -0
  96. package/dist/worker-utils/lib/process-utils/process-utils.d.ts.map +1 -0
  97. package/dist/worker-utils/lib/process-utils/process-utils.js +32 -0
  98. package/dist/worker-utils/lib/process-utils/process-utils.js.map +1 -0
  99. package/dist/worker-utils/lib/worker-api/create-worker.d.ts +9 -0
  100. package/dist/worker-utils/lib/worker-api/create-worker.d.ts.map +1 -0
  101. package/dist/worker-utils/lib/worker-api/create-worker.js +229 -0
  102. package/dist/worker-utils/lib/worker-api/create-worker.js.map +1 -0
  103. package/dist/worker-utils/lib/worker-api/get-worker-url.d.ts +29 -0
  104. package/dist/worker-utils/lib/worker-api/get-worker-url.d.ts.map +1 -0
  105. package/dist/worker-utils/lib/worker-api/get-worker-url.js +101 -0
  106. package/dist/worker-utils/lib/worker-api/get-worker-url.js.map +1 -0
  107. package/dist/worker-utils/lib/worker-api/process-on-worker.d.ts +67 -0
  108. package/dist/worker-utils/lib/worker-api/process-on-worker.d.ts.map +1 -0
  109. package/dist/worker-utils/lib/worker-api/process-on-worker.js +429 -0
  110. package/dist/worker-utils/lib/worker-api/process-on-worker.js.map +1 -0
  111. package/dist/worker-utils/lib/worker-api/shared-state.d.ts +34 -0
  112. package/dist/worker-utils/lib/worker-api/shared-state.d.ts.map +1 -0
  113. package/dist/worker-utils/lib/worker-api/shared-state.js +105 -0
  114. package/dist/worker-utils/lib/worker-api/shared-state.js.map +1 -0
  115. package/dist/worker-utils/lib/worker-api/validate-output-ownership.d.ts +3 -0
  116. package/dist/worker-utils/lib/worker-api/validate-output-ownership.d.ts.map +1 -0
  117. package/dist/worker-utils/lib/worker-api/validate-output-ownership.js +10 -0
  118. package/dist/worker-utils/lib/worker-api/validate-output-ownership.js.map +1 -0
  119. package/dist/worker-utils/lib/worker-api/validate-worker-version.d.ts +9 -0
  120. package/dist/worker-utils/lib/worker-api/validate-worker-version.d.ts.map +1 -0
  121. package/dist/worker-utils/lib/worker-api/validate-worker-version.js +35 -0
  122. package/dist/worker-utils/lib/worker-api/validate-worker-version.js.map +1 -0
  123. package/dist/worker-utils/lib/worker-api/worker-resource.d.ts +33 -0
  124. package/dist/worker-utils/lib/worker-api/worker-resource.d.ts.map +1 -0
  125. package/dist/worker-utils/lib/worker-api/worker-resource.js +156 -0
  126. package/dist/worker-utils/lib/worker-api/worker-resource.js.map +1 -0
  127. package/dist/worker-utils/lib/worker-farm/worker-body.d.ts +20 -0
  128. package/dist/worker-utils/lib/worker-farm/worker-body.d.ts.map +1 -0
  129. package/dist/worker-utils/lib/worker-farm/worker-body.js +134 -0
  130. package/dist/worker-utils/lib/worker-farm/worker-body.js.map +1 -0
  131. package/dist/worker-utils/lib/worker-farm/worker-farm.d.ts +73 -0
  132. package/dist/worker-utils/lib/worker-farm/worker-farm.d.ts.map +1 -0
  133. package/dist/worker-utils/lib/worker-farm/worker-farm.js +135 -0
  134. package/dist/worker-utils/lib/worker-farm/worker-farm.js.map +1 -0
  135. package/dist/worker-utils/lib/worker-farm/worker-job.d.ts +47 -0
  136. package/dist/worker-utils/lib/worker-farm/worker-job.d.ts.map +1 -0
  137. package/dist/worker-utils/lib/worker-farm/worker-job.js +124 -0
  138. package/dist/worker-utils/lib/worker-farm/worker-job.js.map +1 -0
  139. package/dist/worker-utils/lib/worker-farm/worker-pool.d.ts +152 -0
  140. package/dist/worker-utils/lib/worker-farm/worker-pool.d.ts.map +1 -0
  141. package/dist/worker-utils/lib/worker-farm/worker-pool.js +584 -0
  142. package/dist/worker-utils/lib/worker-farm/worker-pool.js.map +1 -0
  143. package/dist/worker-utils/lib/worker-farm/worker-thread.d.ts +77 -0
  144. package/dist/worker-utils/lib/worker-farm/worker-thread.d.ts.map +1 -0
  145. package/dist/worker-utils/lib/worker-farm/worker-thread.js +215 -0
  146. package/dist/worker-utils/lib/worker-farm/worker-thread.js.map +1 -0
  147. package/dist/worker-utils/lib/worker-utils/get-input-byte-length.d.ts +5 -0
  148. package/dist/worker-utils/lib/worker-utils/get-input-byte-length.d.ts.map +1 -0
  149. package/dist/worker-utils/lib/worker-utils/get-input-byte-length.js +39 -0
  150. package/dist/worker-utils/lib/worker-utils/get-input-byte-length.js.map +1 -0
  151. package/dist/worker-utils/lib/worker-utils/get-loadable-worker-url.d.ts +15 -0
  152. package/dist/worker-utils/lib/worker-utils/get-loadable-worker-url.d.ts.map +1 -0
  153. package/dist/worker-utils/lib/worker-utils/get-loadable-worker-url.js +84 -0
  154. package/dist/worker-utils/lib/worker-utils/get-loadable-worker-url.js.map +1 -0
  155. package/dist/worker-utils/lib/worker-utils/get-transfer-list.d.ts +16 -0
  156. package/dist/worker-utils/lib/worker-utils/get-transfer-list.d.ts.map +1 -0
  157. package/dist/worker-utils/lib/worker-utils/get-transfer-list.js +127 -0
  158. package/dist/worker-utils/lib/worker-utils/get-transfer-list.js.map +1 -0
  159. package/dist/worker-utils/lib/worker-utils/remove-nontransferable-options.d.ts +6 -0
  160. package/dist/worker-utils/lib/worker-utils/remove-nontransferable-options.d.ts.map +1 -0
  161. package/dist/worker-utils/lib/worker-utils/remove-nontransferable-options.js +27 -0
  162. package/dist/worker-utils/lib/worker-utils/remove-nontransferable-options.js.map +1 -0
  163. package/dist/worker-utils/types.d.ts +165 -0
  164. package/dist/worker-utils/types.d.ts.map +1 -0
  165. package/dist/worker-utils/types.js +5 -0
  166. package/dist/worker-utils/types.js.map +1 -0
  167. package/dist/worker-utils/workers/null-worker.d.ts +2 -0
  168. package/dist/worker-utils/workers/null-worker.d.ts.map +1 -0
  169. package/dist/worker-utils/workers/null-worker.js +17 -0
  170. package/dist/worker-utils/workers/null-worker.js.map +1 -0
  171. package/package.json +43 -4
  172. package/src/index.ts +5 -0
  173. package/src/tasks/index.ts +33 -0
  174. package/src/tasks/task-channel.ts +191 -0
  175. package/src/tasks/task-operation-queue.ts +109 -0
  176. package/src/tasks/task-preload.ts +107 -0
  177. package/src/tasks/task-runner.ts +933 -0
  178. package/src/tasks/task-runtime.ts +244 -0
  179. package/src/tasks/task-sync.ts +100 -0
  180. package/src/tasks/task-worker-channel.ts +44 -0
  181. package/src/tasks/task.ts +168 -0
  182. package/src/tasks/typed-task-dispatch.ts +44 -0
  183. package/src/worker-utils/index.ts +105 -0
  184. package/src/worker-utils/lib/async-queue/async-queue.ts +100 -0
  185. package/src/worker-utils/lib/env-utils/assert.ts +14 -0
  186. package/src/worker-utils/lib/env-utils/globals.ts +40 -0
  187. package/src/worker-utils/lib/env-utils/version.ts +15 -0
  188. package/src/worker-utils/lib/library-utils/library-utils.ts +305 -0
  189. package/src/worker-utils/lib/node/worker_threads-browser.ts +44 -0
  190. package/src/worker-utils/lib/node/worker_threads.ts +21 -0
  191. package/src/worker-utils/lib/npm-tag.ts +5 -0
  192. package/src/worker-utils/lib/process-utils/child-process-proxy.browser.ts +23 -0
  193. package/src/worker-utils/lib/process-utils/child-process-proxy.ts +172 -0
  194. package/src/worker-utils/lib/process-utils/process-utils.ts +34 -0
  195. package/src/worker-utils/lib/worker-api/create-worker.ts +271 -0
  196. package/src/worker-utils/lib/worker-api/get-worker-url.ts +130 -0
  197. package/src/worker-utils/lib/worker-api/process-on-worker.ts +596 -0
  198. package/src/worker-utils/lib/worker-api/shared-state.ts +135 -0
  199. package/src/worker-utils/lib/worker-api/validate-output-ownership.ts +10 -0
  200. package/src/worker-utils/lib/worker-api/validate-worker-version.ts +44 -0
  201. package/src/worker-utils/lib/worker-api/worker-resource.ts +203 -0
  202. package/src/worker-utils/lib/worker-farm/worker-body.ts +154 -0
  203. package/src/worker-utils/lib/worker-farm/worker-farm.ts +172 -0
  204. package/src/worker-utils/lib/worker-farm/worker-job.ts +148 -0
  205. package/src/worker-utils/lib/worker-farm/worker-pool.ts +719 -0
  206. package/src/worker-utils/lib/worker-farm/worker-thread.ts +260 -0
  207. package/src/worker-utils/lib/worker-utils/get-input-byte-length.ts +34 -0
  208. package/src/worker-utils/lib/worker-utils/get-loadable-worker-url.ts +96 -0
  209. package/src/worker-utils/lib/worker-utils/get-transfer-list.ts +125 -0
  210. package/src/worker-utils/lib/worker-utils/remove-nontransferable-options.ts +27 -0
  211. package/src/worker-utils/types.ts +224 -0
  212. package/src/worker-utils/workers/null-worker.ts +20 -0
@@ -0,0 +1,244 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ import {createWorker, WorkerBody, getTransferList, type WorkerContext} from '../worker-utils/index';
6
+ import {preloadTaskCode} from './task-preload';
7
+ import type {AnyTask, TaskContext, TaskRunControls} from './task';
8
+ import {TaskChannel, type TaskChannelMessage} from './task-channel';
9
+
10
+ /** Optional host services available to either execution backend. */
11
+ type RuntimeContext = WorkerContext & Partial<Pick<TaskContext, 'requestHost' | 'emitHost'>>;
12
+
13
+ /** Validate the record boundary for JavaScript callers as well as TypeScript. */
14
+ export function assertPayload(value: unknown): asserts value is Record<string, unknown> {
15
+ if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) {
16
+ throw new TypeError('Task payloads must be plain objects with named fields');
17
+ }
18
+ }
19
+
20
+ export function clonePayload(value: any, ownership: 'copy' | 'transfer' | 'share' = 'copy'): any {
21
+ assertPayload(value);
22
+ if (!['copy', 'transfer', 'share'].includes(ownership))
23
+ throw new TypeError('Invalid input ownership');
24
+ const transfer = getTransferList(value);
25
+ if (ownership === 'share' && transfer.length)
26
+ throw new TypeError('Share requires shared storage');
27
+ return structuredClone(value, {
28
+ transfer: ownership === 'transfer' ? transfer : []
29
+ });
30
+ }
31
+
32
+ export function taskContext(state: any, context: RuntimeContext = {}): TaskContext<any> {
33
+ const signal = context.signal ?? new AbortController().signal;
34
+ return {
35
+ state,
36
+ signal,
37
+ requestHost: async (operation, payload, controls) => {
38
+ signal.throwIfAborted();
39
+ if (!context.requestHost) throw new Error('No host request handler configured');
40
+ return context.requestHost(operation, payload, controls);
41
+ },
42
+ emitHost: (operation, payload) => {
43
+ signal.throwIfAborted();
44
+ context.emitHost?.(operation, payload);
45
+ },
46
+ throwIfAborted: () => {
47
+ signal.throwIfAborted();
48
+ context.throwIfAborted?.();
49
+ },
50
+ reportProgress: progress =>
51
+ context.reportProgress?.({
52
+ ...progress,
53
+ phase: progress.phase ?? 'process',
54
+ unit: progress.unit ?? 'items'
55
+ })
56
+ };
57
+ }
58
+
59
+ /** Shared lifecycle implementation used by both local and worker execution. */
60
+ export class TaskRuntime {
61
+ private state: any;
62
+ private initialized = false;
63
+ constructor(private task: AnyTask) {}
64
+
65
+ async initialize(input: object, context: RuntimeContext = {}): Promise<object> {
66
+ if (this.initialized) throw new Error('Task is already initialized');
67
+ assertPayload(input);
68
+ await preloadTaskCode(this.task, context.signal);
69
+ context.signal?.throwIfAborted();
70
+ this.state = await this.task.initialize?.(input, taskContext(undefined, context));
71
+ this.initialized = true;
72
+ return {};
73
+ }
74
+
75
+ async destroy(): Promise<object> {
76
+ if (this.initialized) {
77
+ this.initialized = false;
78
+ const state = this.state;
79
+ this.state = undefined;
80
+ if (this.task.initialize) await this.task.destroy?.(state);
81
+ }
82
+ return {};
83
+ }
84
+
85
+ async process(input: object, options: object, context: RuntimeContext = {}): Promise<object> {
86
+ if (!this.initialized) throw new Error('Task is not initialized');
87
+ if (!this.task.process) throw new Error('Task has no atomic processor');
88
+ assertPayload(input);
89
+ const result = await this.task.process(input, options, taskContext(this.state, context));
90
+ assertPayload(result);
91
+ return result;
92
+ }
93
+
94
+ async *stream(
95
+ inputs: AsyncIterable<object>,
96
+ options: object,
97
+ context: RuntimeContext = {}
98
+ ): AsyncIterable<object> {
99
+ if (!this.initialized) throw new Error('Task is not initialized');
100
+ if (!this.task.processInBatches) throw new Error('Task has no streaming processor');
101
+ for await (const output of this.task.processInBatches(
102
+ inputs,
103
+ options,
104
+ taskContext(this.state, context)
105
+ )) {
106
+ assertPayload(output);
107
+ yield output;
108
+ }
109
+ }
110
+ }
111
+
112
+ /**
113
+ * Install one task's protocol inside an existing worker and announce readiness.
114
+ * Does not create a Worker, register an ID, or invoke the task's initialize hook.
115
+ */
116
+ export async function initializeTaskWorker(task: AnyTask): Promise<void> {
117
+ if (!(await WorkerBody.inWorkerThread()))
118
+ throw new Error('initializeTaskWorker must run inside a worker');
119
+ if (installed) throw new Error('A task is already installed in this worker');
120
+ installed = true;
121
+ const runtime = new TaskRuntime(task);
122
+ let channelStream: AsyncIterator<object> | undefined;
123
+ // The dedicated channel shares this runtime with the legacy serialized path.
124
+ // An initialized task chooses one transport for its entire lifetime.
125
+ const channel = new TaskChannel({
126
+ getResultTransferList: (value, request) =>
127
+ (request as {outputOwnership?: string}).outputOwnership === 'transfer'
128
+ ? getTransferList(value)
129
+ : [],
130
+ send: (message, transfer) => {
131
+ // Snapshot before WorkerBody awaits its platform port. This both preserves
132
+ // notification values and detaches only the explicitly owned buffers.
133
+ const snapshot = structuredClone(message, {transfer});
134
+ void WorkerBody.postMessage('task-channel' as never, snapshot as never).catch(reason =>
135
+ channel.fail(reason)
136
+ );
137
+ },
138
+ handleRequest: async (operation, value, signal) => {
139
+ const request = value as {
140
+ input: object;
141
+ options: object;
142
+ outputOwnership?: 'copy' | 'transfer';
143
+ progressId: number;
144
+ };
145
+ const context: RuntimeContext = {
146
+ signal,
147
+ reportProgress: progress =>
148
+ channel.emit('task:progress', {id: request.progressId, progress}),
149
+ requestHost: (operation, payload, controls = {}) => {
150
+ const request = {
151
+ operation,
152
+ payload: clonePayload(payload, controls.inputOwnership),
153
+ outputOwnership: controls.outputOwnership ?? 'copy'
154
+ };
155
+ return channel.request('task:host-request', request, signal, getTransferList(request));
156
+ },
157
+ emitHost: (operation, payload) =>
158
+ channel.emit('task:host-event', {operation, payload, id: request.progressId})
159
+ };
160
+ switch (operation) {
161
+ case 'initialize':
162
+ return runtime.initialize(request.input, context);
163
+ case 'process':
164
+ return runtime.process(request.input, request.options, context);
165
+ case 'stream-open': {
166
+ if (channelStream) throw new Error('A task stream is already open');
167
+ async function* inputs() {
168
+ while (true) {
169
+ const result = (await channel.request(
170
+ 'task:next-input',
171
+ {outputOwnership: 'transfer'},
172
+ signal
173
+ )) as IteratorResult<object>;
174
+ if (result.done) return;
175
+ yield result.value;
176
+ }
177
+ }
178
+ channelStream = runtime
179
+ .stream(inputs(), request.options, context)
180
+ [Symbol.asyncIterator]();
181
+ return {};
182
+ }
183
+ case 'stream-next':
184
+ if (!channelStream) throw new Error('No active task stream');
185
+ return channelStream.next();
186
+ case 'stream-close':
187
+ try {
188
+ await channelStream?.return?.();
189
+ } finally {
190
+ channelStream = undefined;
191
+ }
192
+ return {};
193
+ case 'destroy':
194
+ return runtime.destroy();
195
+ default:
196
+ throw new Error('Unknown task channel operation');
197
+ }
198
+ }
199
+ });
200
+ await WorkerBody.addEventListener((type, payload) => {
201
+ if (type === ('task-channel' as never))
202
+ channel.receive(payload as unknown as TaskChannelMessage);
203
+ });
204
+ let streamOptions: object = {};
205
+ return createWorker(
206
+ async (request, _options, context) => {
207
+ switch (request.operation) {
208
+ case 'initialize':
209
+ return runtime.initialize(request.input, context);
210
+ case 'destroy':
211
+ return runtime.destroy();
212
+ case 'stream-options':
213
+ streamOptions = request.options;
214
+ return {};
215
+ case 'process':
216
+ return runtime.process(request.input, request.options, context);
217
+ default:
218
+ throw new Error('Unknown task operation');
219
+ }
220
+ },
221
+ async function* (inputs, _options, context) {
222
+ async function* batches() {
223
+ for await (const input of inputs) {
224
+ assertPayload(input);
225
+ yield input;
226
+ }
227
+ }
228
+ try {
229
+ yield* runtime.stream(batches(), streamOptions, context);
230
+ } finally {
231
+ streamOptions = {};
232
+ }
233
+ },
234
+ () => preloadTaskCode(task)
235
+ );
236
+ }
237
+ let installed = false;
238
+
239
+ export function localContext(controls: TaskRunControls): WorkerContext {
240
+ return {
241
+ signal: controls.signal,
242
+ reportProgress: progress => controls.onProgress?.(progress)
243
+ };
244
+ }
@@ -0,0 +1,100 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ import {isTaskCodeLoaded} from './task-preload';
6
+ import {getTransferList} from '../worker-utils/index';
7
+ import {assertPayload, clonePayload, taskContext, localContext} from './task-runtime';
8
+ import type {AnyTask, TaskInput, TaskOutput, TaskSyncRunOptions} from './task';
9
+
10
+ /** Internal synchronous lifecycle; never creates a worker or waits for capacity. */
11
+ export function runTaskSync<D extends AnyTask>(
12
+ task: D,
13
+ input: TaskInput<D>,
14
+ request: TaskSyncRunOptions<D> = {} as TaskSyncRunOptions<D>
15
+ ): TaskOutput<D> {
16
+ if (!isTaskCodeLoaded(task))
17
+ throw new Error('Preload task on the main thread before runTaskSync');
18
+ if ('execution' in request) throw new TypeError('runTaskSync always runs on the calling thread');
19
+ if (!task.process) throw new TypeError('Task has no atomic processor');
20
+ for (const hook of [task.initialize, task.process, task.destroy]) {
21
+ if (hook && Object.prototype.toString.call(hook) === '[object AsyncFunction]')
22
+ throw new TypeError('runTaskSync requires synchronous lifecycle hooks');
23
+ }
24
+ if (request.outputOwnership && !['copy', 'transfer'].includes(request.outputOwnership))
25
+ throw new TypeError('Invalid output ownership');
26
+ const context = taskContext(undefined, localContext(request));
27
+ context.throwIfAborted();
28
+ const options = request.options ?? {};
29
+ if (request.inputOwnership === 'transfer') {
30
+ const metadata = new Set(getTransferList(options));
31
+ if (getTransferList(input).some(buffer => metadata.has(buffer)))
32
+ throw new Error('Transferred input aliases reusable options; use inputOwnership: copy');
33
+ }
34
+ const copiedOptions = clonePayload(options);
35
+ const initialization = clonePayload(
36
+ request.initialization ?? {},
37
+ request.initializationOwnership
38
+ );
39
+ let initialized = false;
40
+ let failure: unknown;
41
+ let failed = false;
42
+ let output: TaskOutput<D> | undefined;
43
+ try {
44
+ const state = task.initialize?.(initialization, context);
45
+ if (isThenable(state)) {
46
+ // Invalid JS callers can hide promises behind ordinary functions. Observe the
47
+ // rejection and release a late state rather than leaking it after throwing.
48
+ void Promise.resolve(state)
49
+ .then(value => task.destroy?.(value))
50
+ .catch(() => {});
51
+ throw new TypeError('runTaskSync initialize returned a promise');
52
+ }
53
+ context.state = state;
54
+ initialized = true;
55
+ context.throwIfAborted();
56
+ const copiedInput = clonePayload(input, request.inputOwnership);
57
+ const result = task.process(copiedInput, copiedOptions, context);
58
+ if (isThenable(result)) {
59
+ // Wait for invalid asynchronous processing before destroying its state.
60
+ initialized = false;
61
+ void Promise.resolve(result)
62
+ .catch(() => {})
63
+ .then(() => {
64
+ if (task.initialize) return task.destroy?.(context.state);
65
+ })
66
+ .catch(() => {});
67
+ throw new TypeError('runTaskSync process returned a promise');
68
+ }
69
+ assertPayload(result);
70
+ context.throwIfAborted();
71
+ output = clonePayload(result, request.outputOwnership ?? 'transfer');
72
+ } catch (error) {
73
+ failed = true;
74
+ failure = error;
75
+ } finally {
76
+ if (initialized && task.initialize) {
77
+ try {
78
+ const cleanup = task.destroy?.(context.state);
79
+ if (isThenable(cleanup)) {
80
+ void Promise.resolve(cleanup).catch(() => {});
81
+ throw new TypeError('runTaskSync destroy returned a promise');
82
+ }
83
+ } catch (error) {
84
+ if (failed)
85
+ throw new AggregateError([failure, error], 'Task processing and destruction failed');
86
+ throw error;
87
+ }
88
+ }
89
+ }
90
+ if (failed) throw failure;
91
+ return output!;
92
+ }
93
+
94
+ function isThenable(value: unknown): value is PromiseLike<unknown> {
95
+ return Boolean(
96
+ value &&
97
+ (typeof value === 'object' || typeof value === 'function') &&
98
+ typeof (value as {then?: unknown}).then === 'function'
99
+ );
100
+ }
@@ -0,0 +1,44 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ import WorkerThread from '../worker-utils/lib/worker-farm/worker-thread';
6
+ import {TaskChannel, type TaskChannelOptions, type TaskChannelMessage} from './task-channel';
7
+ import type {TaskWorker} from './task';
8
+
9
+ /** Owns a multiplexed task channel and its single physical worker. @internal */
10
+ export class TaskWorkerChannel {
11
+ readonly channel: TaskChannel;
12
+ private readonly thread: WorkerThread;
13
+
14
+ constructor(name: string, target: TaskWorker, options: Omit<TaskChannelOptions, 'send'>) {
15
+ this.thread = new WorkerThread({
16
+ name,
17
+ url: target.url?.toString(),
18
+ loadWorker: target.create,
19
+ workerType: 'module'
20
+ });
21
+ this.channel = new TaskChannel({
22
+ ...options,
23
+ send: (message, transfer) =>
24
+ this.thread.postMessage(
25
+ {source: 'loaders.gl/tasks', type: 'task-channel', payload: message},
26
+ transfer
27
+ )
28
+ });
29
+ this.thread.onMessage = message => {
30
+ if (message?.type === 'task-channel')
31
+ this.channel.receive(message.payload as TaskChannelMessage);
32
+ };
33
+ this.thread.onError = reason => {
34
+ this.channel.close(reason);
35
+ options.onFailure?.(reason);
36
+ };
37
+ }
38
+
39
+ /** Settle pending calls and terminate the worker without replacing its state. */
40
+ async destroy(reason?: unknown): Promise<void> {
41
+ this.channel.close(reason);
42
+ await this.thread.destroy();
43
+ }
44
+ }
@@ -0,0 +1,168 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ /** Named payload types for a task. Batch types default to the atomic types. */
6
+ export type TaskTypes = {
7
+ input: object;
8
+ output: object;
9
+ options?: object;
10
+ initialization?: object;
11
+ state?: unknown;
12
+ batchInput?: object;
13
+ batchOutput?: object;
14
+ };
15
+ type Field<T, K extends PropertyKey, Default> = K extends keyof T ? T[K] : Default;
16
+ type Payload<T> = T extends readonly unknown[] | ArrayBufferView | ArrayBuffer | Function
17
+ ? never
18
+ : T;
19
+
20
+ /** Services supplied for each invocation; application parameters belong in options. */
21
+ export type TaskContext<State = undefined> = {
22
+ state: State;
23
+ signal: AbortSignal;
24
+ throwIfAborted(): void;
25
+ reportProgress(progress: TaskProgress): void;
26
+ /** Request host services; payloads and responses cross a copy boundary. */
27
+ requestHost(
28
+ operation: string,
29
+ payload: object,
30
+ controls?: Pick<TaskRunControls, 'inputOwnership' | 'outputOwnership'>
31
+ ): Promise<unknown>;
32
+ /** Send a copied notification to the host. */
33
+ emitHost(operation: string, payload: object): void;
34
+ };
35
+ export type TaskProgress = {
36
+ completed: number;
37
+ total?: number;
38
+ phase?: string;
39
+ unit?: string;
40
+ };
41
+ export type TaskInitializationContext = Omit<TaskContext, 'state'>;
42
+
43
+ /** A module-worker target, not a registry entry. Factories must return fresh workers. */
44
+ export type TaskWorker = {
45
+ url?: URL | string;
46
+ create?: () => Worker;
47
+ capabilities: {atomic: boolean; streaming: boolean};
48
+ };
49
+
50
+ /**
51
+ * A plain task definition. Use `satisfies Task<MyTypes>` for contextual typing.
52
+ * State is private to an initialized instance and may be any application value.
53
+ */
54
+ export type Task<T extends TaskTypes> = {
55
+ id: string;
56
+ /** Opt-in scheduling for atomic calls sharing one initialized state. */
57
+ concurrency?: {
58
+ /** Maximum simultaneous calls allowed by this task. */
59
+ maxConcurrency: number;
60
+ /** Exclusive calls run as barriers; omitted means exclusive. */
61
+ getSchedulingMode?: (input: Payload<T['input']>) => 'parallel' | 'exclusive';
62
+ };
63
+ /** Load code dependencies without creating instance state. Cached per definition/realm. */
64
+ preload?: () => void | Promise<void>;
65
+ initialize?: (
66
+ input: Payload<Field<T, 'initialization', object>>,
67
+ context: TaskInitializationContext
68
+ ) => Field<T, 'state', undefined> | Promise<Field<T, 'state', undefined>>;
69
+ destroy?: (state: Field<T, 'state', undefined>) => void | Promise<void>;
70
+ process?: (
71
+ input: Payload<T['input']>,
72
+ options: Field<T, 'options', object>,
73
+ context: TaskContext<Field<T, 'state', undefined>>
74
+ ) => Payload<T['output']> | Promise<Payload<T['output']>>;
75
+ processInBatches?: (
76
+ inputs: AsyncIterable<Payload<Field<T, 'batchInput', T['input']>>>,
77
+ options: Field<T, 'options', object>,
78
+ context: TaskContext<Field<T, 'state', undefined>>
79
+ ) => AsyncIterable<Payload<Field<T, 'batchOutput', T['output']>>>;
80
+ worker?: TaskWorker;
81
+ };
82
+
83
+ // Infer from concrete hooks so `satisfies` preserves inference without a factory.
84
+ export type AnyTask = Task<any>;
85
+ type Processor<D extends AnyTask> = NonNullable<D['process']>;
86
+ type StreamProcessor<D extends AnyTask> = NonNullable<D['processInBatches']>;
87
+ type Argument<
88
+ F extends (...args: any[]) => any,
89
+ N extends number
90
+ > = Parameters<F>[N] extends undefined ? object : NonNullable<Parameters<F>[N]>;
91
+ export type TaskInput<D extends AnyTask> = Argument<Processor<D>, 0>;
92
+ export type TaskOutput<D extends AnyTask> = Awaited<ReturnType<Processor<D>>>;
93
+ export type TaskBatchInput<D extends AnyTask> =
94
+ Parameters<StreamProcessor<D>>[0] extends AsyncIterable<infer I> ? I : never;
95
+ export type TaskBatchOutput<D extends AnyTask> =
96
+ ReturnType<StreamProcessor<D>> extends AsyncIterable<infer O> ? O : never;
97
+ type ProcessorOptions<F extends (...args: any[]) => any> = Argument<F, 1>;
98
+ export type Initialization<D extends AnyTask> = Argument<NonNullable<D['initialize']>, 0>;
99
+ type OptionsField<O> = {} extends O ? {options?: O} : {options: O};
100
+ type InitializationField<D extends AnyTask> = 'initialize' extends keyof D
101
+ ? {} extends Initialization<D>
102
+ ? {initialization?: Initialization<D>}
103
+ : {initialization: Initialization<D>}
104
+ : {initialization?: never};
105
+
106
+ /** Per-invocation controls. Application options are never mixed into this object. */
107
+ export type TaskRunControls = {
108
+ execution?: 'auto' | 'main-thread' | 'worker';
109
+ signal?: AbortSignal;
110
+ inputOwnership?: 'copy' | 'transfer' | 'share';
111
+ outputOwnership?: 'copy' | 'transfer';
112
+ onProgress?: (progress: TaskProgress) => void;
113
+ };
114
+ /** Controls for initializing a retained task instance. */
115
+ export type TaskInitializeControls = TaskRunControls & {
116
+ /** Opt in to overlapping calls, capped by the task's declared capability. */
117
+ operationConcurrency?: number;
118
+ /** Handle requests from the task, with cancellation scoped to that request. */
119
+ onRequest?: (operation: string, payload: unknown, signal: AbortSignal) => Promise<unknown>;
120
+ /** Handle one-way task notifications. */
121
+ onEvent?: (operation: string, payload: unknown) => void;
122
+ };
123
+ /** Controls setup resources independently from per-operation payload ownership. */
124
+ export type TaskInitializationControls = {
125
+ /** Ownership of automatic initialization data; defaults to copying. */
126
+ initializationOwnership?: 'copy' | 'transfer' | 'share';
127
+ };
128
+ export type TaskRunOptions<D extends AnyTask> = TaskRunControls &
129
+ TaskInitializationControls &
130
+ OptionsField<ProcessorOptions<Processor<D>>> &
131
+ InitializationField<D>;
132
+ export type TaskBatchRunOptions<D extends AnyTask> = TaskRunControls &
133
+ TaskInitializationControls &
134
+ OptionsField<ProcessorOptions<StreamProcessor<D>>> &
135
+ InitializationField<D>;
136
+ export type TaskRunsOptions<D extends AnyTask> = Omit<
137
+ TaskRunOptions<D>,
138
+ 'initializationOwnership'
139
+ > & {
140
+ /** Reusable initialization templates may copy or share, but cannot transfer into multiple slots. */
141
+ initializationOwnership?: 'copy' | 'share';
142
+ concurrency?: number;
143
+ };
144
+ export type InitializedTaskOptions<D extends AnyTask> = Omit<TaskRunControls, 'execution'> &
145
+ OptionsField<ProcessorOptions<Processor<D>>>;
146
+ /** Atomic call controls, including time spent waiting for an execution slot. */
147
+ export type InitializedTaskCallOptions<D extends AnyTask> = InitializedTaskOptions<D> & {
148
+ /** Deadline in milliseconds. */
149
+ timeout?: number;
150
+ };
151
+ export type InitializedTaskBatchOptions<D extends AnyTask> = Omit<TaskRunControls, 'execution'> &
152
+ OptionsField<ProcessorOptions<StreamProcessor<D>>>;
153
+ export type RequestArgs<O> = {} extends O ? [options?: O] : [options: O];
154
+ /** Synchronous calls never select a worker. */
155
+ export type TaskSyncRunOptions<D extends AnyTask> = Omit<TaskRunOptions<D>, 'execution'>;
156
+ type SyncHook<D, K extends PropertyKey> = K extends keyof D
157
+ ? NonNullable<D[K]> extends (...args: any[]) => infer R
158
+ ? Extract<R, PromiseLike<unknown>> extends never
159
+ ? unknown
160
+ : never
161
+ : never
162
+ : unknown;
163
+ /** Preserve concrete hook inference with `satisfies Task<Types>`. */
164
+ export type SynchronousTask<D extends AnyTask> = D extends {process: (...args: any[]) => any}
165
+ ? SyncHook<D, 'process'> & SyncHook<D, 'initialize'> & SyncHook<D, 'destroy'>
166
+ : never;
167
+ export type TaskPreloadOptions = Pick<TaskRunControls, 'execution' | 'signal'>;
168
+ export type TaskRunnerOptions = {maxConcurrency?: number};
@@ -0,0 +1,44 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ /** An operation's request payload and corresponding result. */
6
+ export type TaskOperation<Input, Output> = {input: Input; output: Output};
7
+
8
+ /** A discriminated union of requests described by an operation map. */
9
+ export type TaskOperationRequest<Operations> = {
10
+ [Name in keyof Operations]: Operations[Name] extends TaskOperation<infer Input, unknown>
11
+ ? {operation: Name; input: Input}
12
+ : never;
13
+ }[keyof Operations];
14
+
15
+ /** The union of results described by an operation map. */
16
+ export type TaskOperationResult<Operations> = {
17
+ [Name in keyof Operations]: Operations[Name] extends TaskOperation<unknown, infer Output>
18
+ ? Output
19
+ : never;
20
+ }[keyof Operations];
21
+
22
+ /** Dispatch requests with the result type associated with each operation. */
23
+ export type TypedTaskDispatcher<Operations, Options = undefined> = <Name extends keyof Operations>(
24
+ request: {
25
+ [Key in Name]: Operations[Key] extends TaskOperation<infer Input, unknown>
26
+ ? {operation: Key; input: Input}
27
+ : never;
28
+ }[Name],
29
+ options?: Options
30
+ ) => Promise<Operations[Name] extends TaskOperation<unknown, infer Output> ? Output : never>;
31
+
32
+ /**
33
+ * Wrap a transport whose request/result unions follow an operation map.
34
+ * The transport is responsible for returning the result corresponding to each request.
35
+ * This adapter does not change scheduling, ownership, errors, or cancellation.
36
+ */
37
+ export function createTypedTaskDispatcher<Operations, Options = undefined>(
38
+ transport: (
39
+ request: TaskOperationRequest<Operations>,
40
+ options?: Options
41
+ ) => Promise<TaskOperationResult<Operations>>
42
+ ): TypedTaskDispatcher<Operations, Options> {
43
+ return transport as TypedTaskDispatcher<Operations, Options>;
44
+ }