Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

chore: add @kepler.gl/tasks-core as a dual CJS/ESM workspace package (#3691)

Igor Dykhta13226dfbba64
diff --git a/package.json b/package.json
index ac5e44484..a000b9c5e 100644
--- a/package.json
+++ b/package.json
@@ -29,6 +29,7 @@
"./src/schemas",
"./src/cloud-providers",
"./src/processors",
+ "./src/tasks-core",
"./src/tasks",
"./src/actions",
"./src/effects",
diff --git a/src/tasks-core/babel.config.js b/src/tasks-core/babel.config.js
new file mode 100644
index 000000000..3b4d402a3
--- /dev/null
+++ b/src/tasks-core/babel.config.js
@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: MIT
+// Copyright contributors to the kepler.gl project
+
+const KeplerPackage = require('./package');
+
+// Plugins shared by both CJS and ESM builds.
+const SHARED_PLUGINS = [
+ ['@babel/plugin-transform-typescript', {isTSX: true, allowDeclareFields: true}],
+ '@babel/plugin-transform-class-properties',
+ '@babel/plugin-transform-optional-chaining',
+ '@babel/plugin-transform-logical-assignment-operators',
+ '@babel/plugin-transform-nullish-coalescing-operator',
+ '@babel/plugin-transform-export-namespace-from',
+ [
+ 'search-and-replace',
+ {
+ rules: [
+ {
+ search: '__PACKAGE_VERSION__',
+ replace: KeplerPackage.version
+ }
+ ]
+ }
+ ]
+];
+
+module.exports = function babel(api) {
+ // Cache per BABEL_ENV so that CJS and ESM builds get separate cached results.
+ api.cache.using(() => process.env.BABEL_ENV || process.env.NODE_ENV || 'development');
+
+ const isEsm = api.env('esm');
+ const isTest = api.env('test');
+ const isDebug = api.env('debug');
+
+ // ESM build: modules:false preserves import/export so Vite/esbuild can tree-shake.
+ // CJS build (default / test): transforms import/export to require/module.exports.
+ const presets = [
+ ['@babel/preset-env', isEsm ? {modules: false} : {}],
+ '@babel/preset-react',
+ '@babel/preset-typescript'
+ ];
+
+ const plugins = [
+ ...SHARED_PLUGINS,
+ // CJS and test builds need the CommonJS transform; ESM must omit it.
+ ...(isEsm ? [] : ['@babel/plugin-transform-modules-commonjs']),
+ // Runtime helpers: ESM variant uses ESM imports, no require() calls.
+ ['@babel/transform-runtime', {regenerator: true, ...(isEsm ? {useESModules: true} : {})}],
+ ...(isTest ? ['istanbul'] : [])
+ ];
+
+ return {
+ presets,
+ plugins,
+ ...(isDebug ? {sourceMaps: 'inline', retainLines: true} : {})
+ };
+};
diff --git a/src/tasks-core/package.json b/src/tasks-core/package.json
new file mode 100644
index 000000000..07581a8da
--- /dev/null
+++ b/src/tasks-core/package.json
@@ -0,0 +1,57 @@
+{
+ "name": "@kepler.gl/tasks-core",
+ "author": "Shan He <[email protected]>",
+ "version": "3.3.0-alpha.9",
+ "description": "Lightweight built-in task runtime for kepler.gl async side effects",
+ "license": "MIT",
+ "main": "dist/cjs/index.js",
+ "types": "dist/index.d.ts",
+ "keywords": [
+ "babel",
+ "es6",
+ "react",
+ "webgl",
+ "visualization",
+ "deck.gl"
+ ],
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/keplergl/kepler.gl.git"
+ },
+ "scripts": {
+ "build": "rm -fr dist && babel src --out-dir dist/cjs --source-maps inline --extensions '.ts,.tsx,.js,.jsx' --ignore '**/*.d.ts' && BABEL_ENV=esm babel src --out-dir dist/esm --source-maps inline --extensions '.ts,.tsx,.js,.jsx' --ignore '**/*.d.ts'",
+ "build:types": "tsc --project ./tsconfig.production.json",
+ "prepublishOnly": "babel-node ../../scripts/license-header/bin --license ../../FILE-HEADER && yarn build && yarn build:types",
+ "stab": "mkdir -p dist/cjs dist/esm && touch dist/cjs/index.js dist/esm/index.js"
+ },
+ "files": [
+ "dist"
+ ],
+ "nyc": {
+ "sourceMap": false,
+ "instrument": false
+ },
+ "maintainers": [
+ "Shan He <[email protected]>",
+ "Giuseppe Macri <[email protected]>",
+ "Igor Dykhta <[email protected]>",
+ "Xun Li <[email protected]>"
+ ],
+ "engines": {
+ "node": ">=20"
+ },
+ "volta": {
+ "node": "20.19.3",
+ "yarn": "4.4.0"
+ },
+ "packageManager": "[email protected]",
+ "module": "dist/esm/index.js",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "import": "./dist/esm/index.js",
+ "require": "./dist/cjs/index.js",
+ "default": "./dist/cjs/index.js"
+ }
+ }
+}
diff --git a/src/tasks-core/src/index.ts b/src/tasks-core/src/index.ts
new file mode 100644
index 000000000..4ecdd5fa6
--- /dev/null
+++ b/src/tasks-core/src/index.ts
@@ -0,0 +1,453 @@
+// SPDX-License-Identifier: MIT
+// Copyright contributors to the kepler.gl project
+
+/**
+ * Lightweight framework-neutral task runtime for kepler.gl reducers.
+ *
+ * Tasks are plain descriptors that encode async side effects. They are
+ * collected by `withTask()` inside reducer updaters and drained by
+ * `taskMiddleware` after each Redux dispatch, keeping reducers pure.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type ResolveFn = (value: any) => any;
+type RejectFn = (reason: any) => any;
+type ProgressCtx = {onProgress: ResolveFn};
+
+/**
+ * The function that actually performs an effect when a task is executed.
+ * Called by the middleware with resolve/reject continuations.
+ */
+type EffectFn = (resolve: ResolveFn, reject: RejectFn, ctx?: ProgressCtx) => any;
+
+type RunnerFn = (
+ effect: EffectFn & {payload?: any; label?: string},
+ resolve: ResolveFn,
+ reject: RejectFn,
+ ctx?: ProgressCtx
+) => any;
+
+export type TaskDescriptor = {
+ /** Human-readable name used in error messages and devtools */
+ label: string;
+ /** Mirrors the `type` field — kept for backwards compatibility with existing task consumers */
+ type: string;
+ payload: any;
+ run: (runner: RunnerFn, resolve: ResolveFn, reject: RejectFn, ctx?: ProgressCtx) => any;
+ /** Transform the success value */
+ map: (fn: ResolveFn) => TaskDescriptor;
+ /** Transform both success and failure branches */
+ bimap: (onResolve: ResolveFn, onReject: RejectFn) => TaskDescriptor;
+ /** Chain another task on success */
+ chain: (fn: (value: any) => TaskDescriptor) => TaskDescriptor;
+};
+
+/** A factory function that creates a TaskDescriptor from an optional argument */
+export type TaskFactory = ((arg?: any) => TaskDescriptor) & {label?: string; type?: string};
+
+type InstrumentHook = (
+ event: 'start' | 'success' | 'error',
+ task: TaskDescriptor,
+ value: any
+) => void;
+
+// ---------------------------------------------------------------------------
+// Instrumentation (test hook)
+// ---------------------------------------------------------------------------
+
+let instrumentHook: InstrumentHook = (_event, _task, _value) => undefined;
+
+/**
+ * Override the instrumentation hook — used in tests to observe task
+ * lifecycle events without running the middleware.
+ */
+export function reportTasksForTesting(hook: InstrumentHook): void {
+ instrumentHook = hook;
+}
+
+// ---------------------------------------------------------------------------
+// Core task construction
+// ---------------------------------------------------------------------------
+
+function buildTask(payload: any, runFn: TaskDescriptor['run'], label: string): TaskDescriptor {
+ const descriptor: TaskDescriptor = {
+ label,
+ type: label,
+ payload,
+ run: runFn,
+ map(transform) {
+ return buildTask(
+ payload,
+ (runner, resolve, reject, ctx) =>
+ runFn(runner, value => resolve(transform(value)), reject, ctx),
+ label
+ );
+ },
+ bimap(onResolve, onReject) {
+ return buildTask(
+ payload,
+ (runner, resolve, reject, ctx) =>
+ runFn(
+ runner,
+ value => resolve(onResolve(value)),
+ reason => reject(onReject(reason)),
+ ctx
+ ),
+ label
+ );
+ },
+ chain(next) {
+ return buildTask(
+ payload,
+ (runner, resolve, reject, ctx) =>
+ runFn(runner, value => next(value).run(runner, resolve, reject, ctx), reject, ctx),
+ `Chain(${label})`
+ );
+ }
+ };
+ return descriptor;
+}
+
+/**
+ * Wrap an EffectFn so calls are routed through the instrumentation hook.
+ */
+function wrapWithInstrumentation(effect: EffectFn, payload: any, label: string): TaskDescriptor {
+ // `self` is const; the closures below only run after buildTask() returns,
+ // so the binding is fully initialised before any closure body executes.
+ const self: TaskDescriptor = buildTask(
+ payload,
+ (runner, resolve, reject, ctx) => {
+ instrumentHook('start', self, payload);
+ return runner(
+ effect,
+ value => {
+ instrumentHook('success', self, value);
+ return resolve(value);
+ },
+ reason => {
+ instrumentHook('error', self, reason);
+ return reject(reason);
+ },
+ ctx
+ );
+ },
+ label
+ );
+ return self;
+}
+
+// ---------------------------------------------------------------------------
+// Public task factory helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a task factory from a function that returns a Promise.
+ *
+ * @example
+ * const FETCH_DATA = fromPromise(url => fetch(url).then(r => r.json()), 'FETCH_DATA');
+ * // in a reducer:
+ * return withTask(newState, FETCH_DATA(url).bimap(onSuccess, onError));
+ */
+export function fromPromise(fn: (arg?: any) => Promise<any>, label: string): TaskFactory {
+ return Object.assign(
+ (arg?: any) =>
+ wrapWithInstrumentation((resolve, reject) => fn(arg).then(resolve, reject), arg, label),
+ {type: label, label}
+ );
+}
+
+/**
+ * Create a task factory for Promise-based effects that report progress.
+ *
+ * The task argument contains the effect argument and a mapper that turns each
+ * progress value into an action. The middleware dispatches those actions.
+ */
+export function fromPromiseWithProgress(
+ fn: (input: {arg: any; onProgress: (progress: any) => void}) => Promise<any>,
+ label: string
+): TaskFactory {
+ return Object.assign(
+ (payload?: {arg: any; onProgress?: (progress: any) => any}) =>
+ wrapWithInstrumentation(
+ (resolve, reject, ctx) => {
+ // Without a dispatch context (test runners, simulateTask) progress is
+ // dropped and the mapper is never invoked.
+ const emitProgress = ctx
+ ? (progress: any): void =>
+ ctx.onProgress(payload?.onProgress ? payload.onProgress(progress) : progress)
+ : (): void => undefined;
+ return fn({arg: payload?.arg, onProgress: emitProgress}).then(resolve, reject);
+ },
+ payload,
+ label
+ ),
+ {type: label, label}
+ );
+}
+
+/**
+ * Create a task factory from a Node-style callback function.
+ * The callback receives `(error, result)`.
+ */
+export function fromCallback(
+ fn: (arg: any, done: (err?: any, result?: any) => void) => any,
+ label: string
+): TaskFactory {
+ return Object.assign(
+ (arg?: any) =>
+ wrapWithInstrumentation(
+ (resolve, reject) => fn(arg, (err, result) => (err ? reject(err) : resolve(result))),
+ arg,
+ label
+ ),
+ {type: label, label}
+ );
+}
+
+/**
+ * Create a task factory from a function that accepts explicit
+ * `(arg, resolve, reject)` parameters.
+ */
+export function taskCreator(
+ fn: (arg: any, resolve: ResolveFn, reject: RejectFn) => any,
+ label: string
+): TaskFactory {
+ return Object.assign(
+ (arg?: any) =>
+ wrapWithInstrumentation((resolve, reject) => fn(arg, resolve, reject), arg, label),
+ {type: label, label}
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Parallel task combinators
+// ---------------------------------------------------------------------------
+
+function combineParallel(tasks: TaskDescriptor[], settled: boolean): TaskDescriptor {
+ const label = `Task.${settled ? 'allSettled' : 'all'}(${tasks.map(t => t.label).join(', ')})`;
+ return buildTask(
+ tasks.map(t => t.payload),
+ (runner, resolve, reject, ctx) => {
+ if (tasks.length === 0) {
+ return resolve([]);
+ }
+ const results = new Array(tasks.length);
+ let remaining = tasks.length;
+ let aborted = false;
+
+ const onResolved = (idx: number) => (value: any) => {
+ if (aborted) return;
+ results[idx] = settled ? {status: 'fulfilled', value} : value;
+ remaining -= 1;
+ if (remaining === 0) resolve(results);
+ };
+
+ const onRejected = (idx: number) => (reason: any) => {
+ if (aborted) return;
+ if (!settled) {
+ aborted = true;
+ return reject(reason);
+ }
+ results[idx] = {status: 'rejected', value: reason};
+ remaining -= 1;
+ if (remaining === 0) resolve(results);
+ };
+
+ tasks.forEach((task, i) => task.run(runner, onResolved(i), onRejected(i), ctx));
+ },
+ label
+ );
+}
+
+/** Run all tasks in parallel; reject as soon as any one fails */
+export const all = (tasks: TaskDescriptor[]): TaskDescriptor => combineParallel(tasks, false);
+
+/** Run all tasks in parallel; always resolve with `{status, value}` records */
+export const allSettled = (tasks: TaskDescriptor[]): TaskDescriptor => combineParallel(tasks, true);
+
+// ---------------------------------------------------------------------------
+// Global task queue
+// ---------------------------------------------------------------------------
+
+// Stored on globalThis so the same queue is shared even when multiple
+// bundled copies of this module coexist (e.g. app + library both bundle kepler).
+const QUEUE_KEY = '___KEPLER_TASK_QUEUE_3a4f9c1d';
+const g = globalThis as typeof globalThis & Record<string, any>;
+g[QUEUE_KEY] ??= {pending: [] as TaskDescriptor[], lastOrigin: null as Error | null};
+
+const getQueue = (): TaskDescriptor[] => g[QUEUE_KEY].pending;
+const setQueue = (tasks: TaskDescriptor[]) => {
+ g[QUEUE_KEY].pending = tasks;
+};
+
+// ---------------------------------------------------------------------------
+// Stack capture (dev ergonomic — helps locate misplaced withTask() calls)
+// ---------------------------------------------------------------------------
+
+let captureEnabled = true;
+
+/**
+ * Disable the stack-trace guard that detects `withTask()` calls outside
+ * of reducers. Safe to call in production builds for a minor perf gain.
+ */
+export const disableStackCapturing = (): void => {
+ captureEnabled = false;
+};
+
+// ---------------------------------------------------------------------------
+// withTask — attach tasks to reducer state
+// ---------------------------------------------------------------------------
+
+/**
+ * Attach one or more tasks to a reducer state snapshot.
+ * The tasks are queued and executed by `taskMiddleware` after the dispatch
+ * completes, keeping the reducer itself synchronous.
+ *
+ * @example
+ * function myUpdater(state, action) {
+ * const nextState = { ...state, loading: true };
+ * const task = LOAD_DATA(action.payload).bimap(loadSuccess, loadError);
+ * return withTask(nextState, task);
+ * }
+ */
+export function withTask<S>(state: S, tasks: TaskDescriptor | TaskDescriptor[]): S {
+ if (captureEnabled && !g[QUEUE_KEY].lastOrigin) {
+ g[QUEUE_KEY].lastOrigin = new Error(
+ '[kepler.gl] withTask() was called outside of a reducer. ' +
+ 'Tasks must be attached inside reducer updater functions.'
+ );
+ }
+ const incoming = Array.isArray(tasks) ? tasks : [tasks];
+ setQueue(getQueue().concat(incoming));
+ return state;
+}
+
+/** Alias — accepts an array of tasks directly (same as withTask with an array) */
+export const withTasks = withTask;
+
+// ---------------------------------------------------------------------------
+// Redux middleware
+// ---------------------------------------------------------------------------
+
+const microtask = Promise.resolve();
+
+/**
+ * Redux middleware that drains the task queue after every dispatched action.
+ * Add this to your store's middleware chain.
+ *
+ * @example
+ * import { taskMiddleware } from '@kepler.gl/tasks';
+ * const store = createStore(reducer, applyMiddleware(taskMiddleware));
+ */
+export const taskMiddleware =
+ (store: any) =>
+ (next: any) =>
+ (action: any): any => {
+ if (captureEnabled && getQueue().length) {
+ const err = g[QUEUE_KEY].lastOrigin;
+ g[QUEUE_KEY].lastOrigin = null;
+ throw err;
+ }
+
+ next(action);
+
+ const tasks = getQueue();
+ if (tasks.length === 0) return microtask;
+
+ setQueue([]);
+ g[QUEUE_KEY].lastOrigin = null;
+
+ // Dispatch task results asynchronously to avoid re-entrancy issues.
+ const dispatch = (nextAction: any) => microtask.then(() => store.dispatch(nextAction));
+
+ const runEffect: RunnerFn = (effect, resolve, reject, ctx) => effect(resolve, reject, ctx);
+
+ return Promise.all(
+ tasks.map(task => task.run(runEffect, dispatch, dispatch, {onProgress: dispatch}))
+ );
+ };
+
+// ---------------------------------------------------------------------------
+// Test utilities
+// ---------------------------------------------------------------------------
+
+/**
+ * @internal
+ * Execute a task synchronously using a simulator function.
+ * Throws if neither the resolve nor reject branch is called.
+ */
+function runSync(task: TaskDescriptor, simulator: RunnerFn): any {
+ let outcome: any;
+ let settled = false;
+ task.run(
+ simulator,
+ value => {
+ outcome = value;
+ settled = true;
+ },
+ reason => {
+ outcome = reason;
+ settled = true;
+ }
+ );
+ if (!settled) {
+ throw new Error(
+ `[kepler.gl] Task "${task.label}" did not call resolve or reject synchronously. ` +
+ 'Use drainTasksForTesting() for async tasks.'
+ );
+ }
+ return outcome;
+}
+
+/** Simulate a task succeeding with a given value */
+export const succeedTaskInTest = (task: TaskDescriptor, value: any): any =>
+ runSync(task, (_effect, resolve) => resolve(value));
+
+/** Simulate a task failing with a given reason */
+export const errorTaskInTest = (task: TaskDescriptor, reason: any): any =>
+ runSync(task, (_effect, _resolve, reject) => reject(reason));
+
+/** Simulate a task with a custom runner (for complex scenarios) */
+export const simulateTask = (task: TaskDescriptor, runner: RunnerFn): any => runSync(task, runner);
+
+/**
+ * Simulate a task that resolves multiple times (e.g. a chained sequence),
+ * consuming values from the provided array in order.
+ */
+export const succeedTaskWithValues = (task: TaskDescriptor, values: any[]): any => {
+ let cursor = 0;
+ return runSync(task, (_effect, resolve) => {
+ if (cursor >= values.length) {
+ throw new Error(`[kepler.gl] succeedTaskWithValues: ran out of values at index ${cursor}`);
+ }
+ return resolve(values[cursor++]);
+ });
+};
+
+/**
+ * Drain the task queue and return all pending tasks.
+ * Call this in tests instead of running the full middleware.
+ */
+export const drainTasksForTesting = (): TaskDescriptor[] => {
+ const tasks = getQueue();
+ setQueue([]);
+ g[QUEUE_KEY].lastOrigin = null;
+ return tasks;
+};
+
+/**
+ * Return the current task queue without clearing it.
+ * Used by merger-handler to detect tasks scheduled during a merge step.
+ */
+export const getGlobalTaskQueue = getQueue;
+
+// ---------------------------------------------------------------------------
+// Default export — Task static API surface
+// ---------------------------------------------------------------------------
+
+const Task = {all, allSettled, fromCallback, fromPromise, fromPromiseWithProgress};
+export {Task};
+export default Task;
diff --git a/src/tasks-core/tsconfig.production.json b/src/tasks-core/tsconfig.production.json
new file mode 100644
index 000000000..cc2c36c7d
--- /dev/null
+++ b/src/tasks-core/tsconfig.production.json
@@ -0,0 +1,28 @@
+{
+ "compilerOptions": {
+ "target": "es2020",
+ "allowJs": false,
+ "checkJs": false,
+ "jsx": "react",
+ "module": "esnext",
+ "moduleResolution": "node",
+ "declaration": true,
+ "emitDeclarationOnly": true,
+ "noImplicitAny": false,
+ "noImplicitReturns": true,
+ "noImplicitThis": true,
+ "noUnusedLocals": false, //TODO change once all dependencies are isolated
+ "outDir": "dist",
+ "sourceMap": true,
+ "strictNullChecks": true,
+ "suppressImplicitAnyIndexErrors": false,
+ "esModuleInterop": true,
+ "allowSyntheticDefaultImports": true,
+ "skipLibCheck": true,
+ "strict": true,
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "baseUrl": "./src"
+ },
+ "include": ["src"]
+}
diff --git a/yarn.lock b/yarn.lock
index b0fda4985..45cd707a6 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -4201,6 +4201,12 @@ __metadata:
languageName: unknown
linkType: soft
+"@kepler.gl/tasks-core@workspace:src/tasks-core":
+ version: 0.0.0-use.local
+ resolution: "@kepler.gl/tasks-core@workspace:src/tasks-core"
+ languageName: unknown
+ linkType: soft
+
"@kepler.gl/tasks@npm:3.3.0-alpha.9, @kepler.gl/tasks@workspace:src/tasks":
version: 0.0.0-use.local
resolution: "@kepler.gl/tasks@workspace:src/tasks"