spark.SparkWorkerApi
export interface SparkWorkerApi {
/**
* Persist state across hot reloads.
*
* On first call, initializer() is executed and result is stored.
* On subsequent calls (after hot reload), the stored value is returned.
*
* @template T - Type of persisted value
* @param key - Unique key for this state
* @param initializer - Function to create initial value
* @returns The persisted value
*/
persist<T>(key: string, initializer: () => T): T;
/**
* Cooperative yield point for pause/resume/stop and hot reload.
*
* Call at regular intervals in your training loop to allow:
* - UI to pause/resume/stop training
* - Hot reload of code
* - UI updates to be processed
*
* @throws {SparkStopError} If execution was stopped
* @throws {SparkReloadError} If hot reload is pending
*/
checkpoint(): Promise<void>;
/**
* Create a controller for pause/resume/stop.
*
* Returns a controller that can be exposed to the UI and called
* or queried from the UI.
*
* @returns SparkController instance
*/
controller(): SparkController;
/**
* Expose values and functions to the UI.
*
* Call once in torch() to expose state and functions:
* - Values become reactive (assignments update UI)
* - Functions become callable via RPC
*
* @param bindings - Object with values and functions to expose
*/
expose(bindings: Record<string, unknown>): void;
/**
* Load a file from torchjs.org as ArrayBuffer.
*
* Path format: "username/project/filename"
*
* @param path - File path
* @returns File contents as ArrayBuffer
* @throws If file not found or network error
*/
load(path: string): Promise<ArrayBuffer>;
/**
* Load a JSON file from torchjs.org.
*
* Path format: "username/project/filename"
*
* @template T - Type of parsed JSON
* @param path - File path
* @returns Parsed JSON data
* @throws If file not found or invalid JSON
*/
loadJSON<T = unknown>(path: string): Promise<T>;
/**
* Load a text file from torchjs.org.
*
* Path format: "username/project/filename"
*
* @param path - File path
* @returns File contents as string
* @throws If file not found or network error
*/
loadText(path: string): Promise<string>;
/**
* Save a file to torchjs.org.
*
* Path format: "username/project/filename"
* Requires authentication (proxied through parent window).
*
* @param path - File path
* @param data - Data to save (ArrayBuffer, Blob, or string)
* @param options - Save options (progress callback, etc.)
* @throws If not authenticated or save fails
*/
save(path: string, data: ArrayBuffer | Blob | string, options?: SparkSaveOptions): Promise<void>;
/**
* Save JSON data to a file on torchjs.org.
*
* Path format: "username/project/filename"
* Requires authentication.
*
* @param path - File path (should end with .json)
* @param data - Object to serialize as JSON
* @throws If not authenticated or save fails
*/
saveJSON(path: string, data: unknown): Promise<void>;
/**
* Load a dataset from torchjs.org.
*
* Path format: "username/project" (loads torch.json from that path)
*
* @param path - Project path
* @returns Dataset with train/test/val splits
* @throws If manifest not found or invalid
*/
dataset(path: string): Promise<SparkDataset>;
/**
* Check if a file exists on torchjs.org.
*
* Path format: "username/project/filename"
*
* @param path - File path
* @returns True if file exists
*/
exists(path: string): Promise<boolean>;
/**
* Delete a file from torchjs.org.
*
* Path format: "username/project/filename"
* Requires authentication.
*
* @param path - File path
* @throws If not authenticated or delete fails
*/
delete(path: string): Promise<void>;
}persist((key: string, initializer: () => T) => T)- – Persist state across hot reloads. On first call, initializer() is executed and result is stored. On subsequent calls (after hot reload), the stored value is returned.
checkpoint(() => Promise<void>)- – Cooperative yield point for pause/resume/stop and hot reload. Call at regular intervals in your training loop to allow: - UI to pause/resume/stop training - Hot reload of code - UI updates to be processed
controller(() => SparkController)- – Create a controller for pause/resume/stop. Returns a controller that can be exposed to the UI and called or queried from the UI.
expose((bindings: Record<string, unknown>) => void)- – Expose values and functions to the UI. Call once in torch() to expose state and functions: - Values become reactive (assignments update UI) - Functions become callable via RPC
load((path: string) => Promise<ArrayBuffer>)- – Load a file from torchjs.org as ArrayBuffer. Path format: "username/project/filename"
loadJSON((path: string) => Promise<T>)- – Load a JSON file from torchjs.org. Path format: "username/project/filename"
loadText((path: string) => Promise<string>)- – Load a text file from torchjs.org. Path format: "username/project/filename"
save((path: string, data: ArrayBuffer | Blob | string, options?: SparkSaveOptions) => Promise<void>)- – Save a file to torchjs.org. Path format: "username/project/filename" Requires authentication (proxied through parent window).
saveJSON((path: string, data: unknown) => Promise<void>)- – Save JSON data to a file on torchjs.org. Path format: "username/project/filename" Requires authentication.
dataset((path: string) => Promise<SparkDataset>)- – Load a dataset from torchjs.org. Path format: "username/project" (loads torch.json from that path)
exists((path: string) => Promise<boolean>)- – Check if a file exists on torchjs.org. Path format: "username/project/filename"
delete((path: string) => Promise<void>)- – Delete a file from torchjs.org. Path format: "username/project/filename" Requires authentication.
Spark API available inside the worker.
These functions are available as spark.* inside the torch() function
that runs in a web worker. They provide state persistence, checkpoint control,
reactive bindings, and file I/O.
Examples
function torch() {
// Persist across hot reloads
const model = spark.persist('model', () => nn.Sequential(...));
const state = spark.persist('state', () => ({ epoch: 0, loss: 0 }));
// Create controller
const ctrl = spark.controller();
// Training loop
async function train() {
for (const batch of data) {
await ctrl.checkpoint(); // Allow pause/stop/reload
// ... training step
state.loss = loss; // Automatic update to UI
}
}
// Expose to UI
spark.expose({ train, state, ctrl });
}