Node.js/TypeScript reimplementation of Google Research's TimesFM — a decoder-only foundation model for zero-shot time-series forecasting.
timesfm-ts brings Google's TimesFM 2.5 (200M parameters, decoder-only transformer) to the Node.js ecosystem. It provides zero-shot time series forecasting — feed it any univariate time series and get point forecasts with calibrated prediction intervals, no training required.
Raw Time Series → [Preprocessor] → [ONNX Runtime] → [Postprocessor] → Forecasts
(NaN cleaning, (Trained (Flip invariance,
patch splitting, TimesFM 2.5 quantile calibration,
RevIN normalize) model) crossing fix, etc.)
- Zero-shot forecasting — no training needed
- Point forecasts + 10 quantile bands (mean, q10–q90)
- Variable-length inputs — different series lengths in one batch
- Automatic NaN handling — leading NaN stripped, internal NaN interpolated
- Covariate support — dynamic/static numerical & categorical exogenous variables (XReg)
- Production-grade — built on ONNX Runtime's native C++ backend (CPU, CUDA, DirectML)
- Verified accuracy — Scaled MAE < 1.0 (better than naive baseline), see latest benchmark
| Package | npm | Description |
|---|---|---|
@agentix-e/timesfm-core |
 |
Pure TypeScript core: IInferenceEngine abstraction, decode loop, pre/post-processing |
@agentix-e/timesfm-node |
 |
Node.js ONNX Runtime inference engine (onnxruntime-node) |
@agentix-e/timesfm-xreg |
 |
Covariate regression extension (Ridge + OneHot) |
@agentix-e/timesfm-cli |
 |
CLI tool (includes timesfm setup auto model download) |
@agentix-e/timesfm-web |
 |
Browser inference engine (onnxruntime-web: WASM / WebGPU / WebGL) |
@agentix-e/timesfm-hierarchical |
 |
Hierarchical time series reconciliation engine (bottom-up, OLS, WLS, MinT) |
Layered strategy: npm packages contain only code (~150 KB), models (885 MB zip / ~928 MB ONNX) are downloaded on-demand via GitHub Releases.
npm install @agentix-e/timesfm-cli
# Auto download model ~885 MB (first time only)
npx timesfm setup
# Forecast
npx timesfm forecast --horizon 24 data.csvimport { TimesFMModel, downloadModel, createForecastConfig } from '@agentix-e/timesfm-core';
// Auto download model (first time only, cached thereafter)
const modelPath = await downloadModel();
const model = await TimesFMModel.fromPretrained({ modelPath });
model.compile(createForecastConfig({ maxContext: 1024, maxHorizon: 256 }));
const { pointForecast, quantileForecast } = await model.forecast(24, [
new Float32Array([1, 2, 3 /* ... */]),
]);git clone https://github.com/AgentiX-E/timesfm-ts.git
cd timesfm-ts && pnpm install && pnpm build
# One-click pipeline
pnpm run pipelineDetailed docs: docs/GETTING-STARTED.md | docs/MODEL-UPDATE.md
| Parameter | Type | Default | Description |
|---|---|---|---|
maxContext |
number | 1024 | Maximum context window (rounded to 32x) |
maxHorizon |
number | 256 | Maximum forecast horizon (rounded to 128x) |
normalizeInputs |
boolean | true | Z-score normalize inputs |
useContinuousQuantileHead |
boolean | true | Better prediction intervals |
forceFlipInvariance |
boolean | true | Ensure f(-x) = -f(x) |
inferIsPositive |
boolean | true | Clamp forecasts ≥ 0 for positive inputs |
fixQuantileCrossing |
boolean | true | Ensure monotonic quantiles |
returnBackcast |
boolean | false | Return input reconstruction |
perCoreBatchSize |
number | 1 | Number of series processed per batch (higher = more throughput, more memory) |
| Output | Shape | Description |
|---|---|---|
pointForecast |
(B, H) |
Median forecast |
quantileForecast |
(B, H, 10) |
Full distribution |
quantileForecast[0] |
(B, H) |
Mean |
quantileForecast[1] |
(B, H) |
10th percentile |
quantileForecast[5] |
(B, H) |
50th percentile (= pointForecast) |
quantileForecast[9] |
(B, H) |
90th percentile |
timesfm-ts/
├── packages/
│ ├── timesfm-core/ # Core inference engine
│ │ ├── src/
│ │ │ ├── index.ts # Public API
│ │ │ ├── model.ts # TimesFMModel class
│ │ │ ├── config.ts # Configuration management
│ │ │ ├── types.ts # Type definitions
│ │ │ ├── preprocessor.ts # Data preprocessing
│ │ │ ├── postprocessor.ts# Output postprocessing
│ │ │ ├── inference/
│ │ │ │ └── decode-loop.ts # Autoregressive decode
│ │ │ └── utils/
│ │ │ ├── nan-handler.ts # NaN stripping/interpolation
│ │ │ ├── stats.ts # Welford running statistics
│ │ │ ├── revin.ts # RevIN normalization
│ │ │ └── tensor-utils.ts # Low-level tensor ops
│ │ └── test/ # Unit + integration test suites
│ ├── timesfm-node/ # Node.js ONNX Runtime engine
│ │ ├── src/
│ │ │ ├── index.ts # Factory + exports
│ │ │ └── node-engine.ts # TimesFMNodeEngine (onnxruntime-node)
│ │ └── test/
│ ├── timesfm-xreg/ # Covariate regression
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ ├── xreg-engine.ts # Ridge regression engine
│ │ │ └── one-hot-encoder.ts # Scikit-learn compatible OHE
│ │ └── test/
│ └── timesfm-cli/ # CLI tool
│ ├── src/
│ │ ├── cli.ts # Commander-based CLI
│ │ └── csv-forecast.ts # CSV I/O forecasting
│ └── test/
│ └── timesfm-web/ # Browser inference engine
│ ├── src/
│ │ ├── web-engine.ts # onnxruntime-web engine (WASM/WebGPU)
│ │ └── model-loader.ts # fetch() model downloader
│ └── test/
│ └── timesfm-hierarchical/ # Hierarchical reconciliation engine
│ ├── src/
│ │ ├── index.ts
│ │ ├── hierarchical.ts
│ │ ├── reconciliation.ts
│ │ ├── summing-matrix.ts
│ │ └── types.ts
│ └── test/
├── scripts/
│ ├── pipeline.js # Node.js fully automated pipeline
│ └── export-onnx.py # PyTorch → ONNX exporter
├── .github/
│ └── workflows/ # CI/CD automation
│ ├── ci.yml # PR checks + integration tests + benchmark + deploy
│ ├── release.yml # npm publish + model GitHub Release
│ ├── model-release.yml # HuggingFace model update checker
│ └── nightly.yml # Daily model version monitoring
├── models/ # ONNX models (gitignored)
└── vitest.config.ts
# Install
pnpm install && pnpm build
# One-click full pipeline (model export + tests + benchmarks)
pnpm run pipeline
# Run tests only
pnpm test
pnpm run test:watch
# Lint + benchmarks
pnpm run lint
pnpm run benchmark
# Check HF latest version
pnpm run check:latest- Paper: A Decoder-Only Foundation Model for Time-Series Forecasting (ICML 2024)
- Original Project: google-research/timesfm
- ONNX Runtime: onnxruntime.ai
- HuggingFace Models: google/timesfm-2.5-200m-pytorch
- Univariate only: Each series is forecast independently. Multi-variate (cross-series) forecasting is not yet supported.
- Model version: Currently supports TimesFM 2.5 200M. Support for TimesFM 1.0 / 2.0 and other checkpoint variants is not yet available.
- No fine-tuning API: The model runs in zero-shot mode. On-device fine-tuning or adapter-based adaptation is planned but not yet implemented.
- Browser memory: The 885 MB model must fit in browser WASM memory (~4 GB limit). WebGPU improves throughput but requires Chrome 113+ / Edge 113+.
| Resource | Description | URL |
|---|---|---|
| 📚 API Docs | Full TypeDoc reference for all packages | agentix-e.github.io/timesfm-ts/api/ |
| 📊 Benchmark | Inference latency, throughput & accuracy reports (Node.js + WASM) | agentix-e.github.io/timesfm-ts/benchmark/ |
| 📈 Coverage | Line, branch, function & statement coverage (≥95% on all covered source modules) | agentix-e.github.io/timesfm-ts/coverage/ |
| 📦 npm (core) | @agentix-e/timesfm-core |
npmjs.com/package/@agentix-e/timesfm-core |
| 📦 npm (node) | @agentix-e/timesfm-node |
npmjs.com/package/@agentix-e/timesfm-node |
| 📦 npm (xreg) | @agentix-e/timesfm-xreg |
npmjs.com/package/@agentix-e/timesfm-xreg |
| 📦 npm (cli) | @agentix-e/timesfm-cli |
npmjs.com/package/@agentix-e/timesfm-cli |
| 📦 npm (web) | @agentix-e/timesfm-web |
npmjs.com/package/@agentix-e/timesfm-web |
| 📦 npm (hierarchical) | @agentix-e/timesfm-hierarchical |
npmjs.com/package/@agentix-e/timesfm-hierarchical |
| Component | Minimum | Recommended |
|---|---|---|
| OS | Linux / macOS / Windows | Linux (production) |
| Node.js | ≥ 22.x | ≥ 22.x |
| RAM | 4 GB | 8 GB+ |
| Disk (code) | 10 MB | — |
| Disk (model) | 2 GB | SSD |
| GPU (optional) | 2 GB VRAM | 4 GB+ VRAM (CUDA) |
| Python (optional) | ≥ 3.10 | Only needed for HuggingFace export |
| Usage method | Requires pre-install |
|---|---|
| npm install + auto model download | Node.js ≥ 22 only |
| Export model from HuggingFace | Python ≥ 3.10 + pip install "timesfm[torch]" onnx onnxruntime torch |
| Build from source | Node.js ≥ 22 + pnpm |
onnxruntime-nodeincludes prebuilt C++ native modules, supports Linux x64 / arm64, macOS x64 / arm64 (Apple Silicon), Windows x64. No additional system packages required.
# Download model
timesfm setup # Default: ~/.cache/timesfm-ts/
timesfm setup -o ./models/my-model.onnx # Custom path
timesfm setup -f # Force re-download
timesfm setup --precision int8 # Download INT8 quantized model
# Model info
timesfm info # Show model metadata + system info
timesfm info -m ./custom.onnx # Custom model path
# Download with proxy (corporate / restricted networks)
# Option A: Standard environment variables (auto-detected)
export HTTPS_PROXY=http://proxy.company.com:8080
timesfm setup
# Option B: Explicit proxy with authentication
timesfm setup --proxy-url http://proxy.company.com:8080
timesfm setup --proxy-url http://proxy.company.com:8080 --proxy-username user
timesfm setup --proxy-url http://proxy:8080 --proxy-username user --proxy-password pass
# Password is also available from environment variable (more secure):
TIMESFM_PROXY_PASSWORD=pass timesfm setup --proxy-url http://proxy:8080 --proxy-username user
# Or via file for Docker/Kubernetes secrets:
TIMESFM_PROXY_PASSWORD_FILE=/run/secrets/proxy-password timesfm setup --proxy-url http://proxy:8080 --proxy-username user
# Option C: TIMESFM-specific environment variables
TIMESFM_PROXY_URL=http://proxy:8080 TIMESFM_PROXY_USERNAME=user TIMESFM_PROXY_PASSWORD=pass timesfm setup
# Forecast (model path priority)
timesfm forecast --horizon 24 data.csv # Auto: cache → download
timesfm forecast -m ./custom.onnx --horizon 24 data.csv # Explicit path
TIMESFM_MODEL_PATH=./prod.onnx timesfm forecast --horizon 24 data.csv # Environment variable
# Model path resolution priority: ① --model ② $TIMESFM_MODEL_PATH ③ default cache ④ auto downloadThis project is open source under Apache 2.0.
- Google TimesFM (google-research/timesfm) is licensed under Apache 2.0
- The TypeScript/Node.js code in this project is an original implementation, also released under Apache 2.0
- TimesFM pretrained model weights (downloaded from HuggingFace) follow Google's model license terms
- This project's
scripts/export-onnx.pyis used to help users export models, does not directly distribute model weights - ONNX files in GitHub Releases are derivative works exported by users from HuggingFace
| Component | License | Description |
|---|---|---|
| timesfm-ts code | Apache 2.0 | Fully original |
| TimesFM model weights | Apache 2.0 (Google) | HuggingFace hosted |
| ONNX Runtime | MIT (Microsoft) | npm dependency |
| ml-matrix | MIT | npm dependency |