deepbox/core
Utilities, Serialization & Parallelism
Utility helpers for validation, persistence, worker pools, and runtime-safe data handling.
Serialization
Worker pool
Overview
- Serialization helpers let you persist tensors, estimator state, and module payloads in JSON-friendly forms.
- WorkerPool provides a structured API for bounded parallel execution and status inspection.
- check_array, check_X_y, and check_is_fitted support scikit-learn-style validation flows in custom estimators.
type PoolStatus
export type PoolStatus = { readonly maxWorkers: number; readonly activeWorkers: number; readonly pendingTasks: number; readonly completedTasks: number; readonly isTerminated: boolean; };
Status information about the worker pool.
type TaskResult
export type TaskResult<T> = { readonly value: T; readonly workerId: number; readonly durationMs: number; };
Web Workers / worker_threads parallelism for Deepbox.
type WorkerPoolOptions
export type WorkerPoolOptions = { /** Number of worker threads. Defaults to navigator.hardwareConcurrency or 4. */ readonly maxWorkers?: number; /** Task timeout in milliseconds. Default: 30000 (30s). */ readonly taskTi…
Options for creating a WorkerPool.
type SerializedEstimator
export type SerializedEstimator = { readonly __type: "Estimator"; readonly className: string; readonly params: Record<string, unknown>; readonly state: Record<string, unknown>; };
Serialized ML estimator — hyperparams + fitted arrays.
type SerializedModuleState
export type SerializedModuleState = { readonly __type: "ModuleState"; readonly parameters: Record<string, { data: Array<number | string | bigint>; dtype: string; shape: number[]; }>; readonly buffers: Record<string, { d…
Serialized nn.Module state — parameters + buffers.
type SerializedPayload
export type SerializedPayload = SerializedTensor | SerializedModuleState | SerializedEstimator;
Union of all serializable payloads.
type SerializedTensor
export type SerializedTensor = { readonly __type: "Tensor"; readonly data: ReadonlyArray<number | string | bigint>; readonly shape: readonly number[]; readonly dtype: string; };
Serialized representation of a tensor — flat data + metadata.
WorkerPool
A pool of worker threads for parallel task execution.
availableCores
export declare function availableCores(): number;
Get the number of available CPU cores.
createWorkerPool
export declare function createWorkerPool(maxWorkers?: number): WorkerPool;
Create a WorkerPool with sensible defaults.
fromJSON
export declare function fromJSON(json: string): SerializedPayload;
Deserialize a JSON string back to a payload object.
load
export declare function load(path: string): Promise<SerializedPayload>;
Load a serialized payload from a file (Node.js only).
save
export declare function save(path: string, payload: SerializedPayload): Promise<void>;
Save a serialized payload to a file (Node.js only).
toJSON
export declare function toJSON(payload: SerializedPayload): string;
Serialize a payload to a JSON string.
check_array
export declare function check_array(array: unknown, options?: { dtype?: DType; ensureNdim?: number; allowEmpty?: boolean; }): unknown;
Input validation on an array-like (Tensor).
check_is_fitted
export declare function check_is_fitted(estimator: Record<string, unknown>, attributes?: string[], msgOverride?: string): void;
Check that an estimator has been fitted.
check_X_y
export declare function check_X_y(X: unknown, y: unknown, options?: { allowEmpty?: boolean; dtype?: DType; multiOutput?: boolean; }): [unknown, unknown];
Input validation for standard estimators (X and y).
dtypeToTypedArrayCtor
export declare function dtypeToTypedArrayCtor(dtype: DType): Float32ArrayConstructor | Float64ArrayConstructor | Int32ArrayConstructor | BigInt64ArrayConstructor | Uint8ArrayConstructor;
Get TypedArray constructor for a given DType.
ensureNumericDType
export declare function ensureNumericDType(dtype: DType, context?: string): NumericDType;
Ensure a dtype is numeric (non-string).
normalizeAxes
export declare function normalizeAxes(axis: Axis | Axis[], ndim: number): number[];
Normalize a list of axes to valid dimension indices.
normalizeAxis
export declare function normalizeAxis(axis: Axis, ndim: number): number;
Normalize an axis argument to a valid dimension index.
shapeToSize
export declare function shapeToSize(shape: unknown, name?: string): number;
shapeToSize is exported by deepbox/core.
validateArray
export declare function validateArray(arr: unknown, name: string): asserts arr is unknown[];
Validate that a value is an array.
validateDevice
export declare function validateDevice(device: unknown, name?: string): Device;
validateDevice is exported by deepbox/core.
validateDtype
export declare function validateDtype(dtype: unknown, name?: string): DType;
validateDtype is exported by deepbox/core.
validateInteger
export declare function validateInteger(value: number, name: string): void;
Validate that a value is a safe integer.
validateNonNegative
export declare function validateNonNegative(value: number, name: string): void;
Validate that a value is non-negative (>= 0).
validateOneOf
export declare function validateOneOf<T extends string>(value: unknown, options: readonly T[], name: string): asserts value is T;
Validate that a value is one of the allowed options.
validatePositive
export declare function validatePositive(value: number, name: string): void;
Validate that a value is positive (> 0).
validateRange
export declare function validateRange(value: number, min: number, max: number, name: string): void;
Validate that a value is within a specified range [min, max].
validateShape
export declare function validateShape(shape: unknown, name?: string): Shape;
validateShape is exported by deepbox/core.
core-utils.ts
import { availableCores, createWorkerPool, save, toJSON,} from "deepbox/core";const payload = { __type: "Tensor", data: [1, 2, 3, 4], shape: [2, 2], dtype: "float32",} as const;console.log(toJSON(payload));await save("tensor.json", payload);const pool = createWorkerPool(Math.min(availableCores(), 4));console.log(pool.status());