effect-prophet
v1.0.0
Published
Effect-based time-series forecasting with a Rust/WASM numerical backend
Maintainers
Readme
Effect Prophet
Time-series forecasting for TypeScript. Give it your history; get back a forecast with the trend, weekly and yearly patterns, and holidays each broken out.
Effect Prophet uses the same model as Prophet, Meta's forecasting library. It covers everything Python Prophet 1.4.0 does except plotting, and is checked against it case by case. What's different lists every difference.
- One peer dependency.
effect(^4.0.0) is the only package it needs, and you install it yourself so your app and this library share one copy. - No Stan install. Prophet's fitting runs on Stan. The parts Prophet
uses are ported to Rust and compiled to WebAssembly, which ships inside the package.
Attribution is in
NOTICE.txt.
Install
npm install effect-prophet effectRuns on Node.js 22.19 or newer, and in browsers through Vite, webpack, Rspack or esbuild. See Browsers and bundlers.
Quick start
import { Effect } from "effect";
import { fit, makeFutureTimestamps, predict, prophetFittingBackendLayer } from "effect-prophet";
// One row per day: a UTC timestamp and a value.
const history = Array.from({ length: 90 }, (_, day) => ({
timestamp: new Date(Date.UTC(2025, 0, 1 + day)).toISOString(),
value: 100 + day * 0.5 + 10 * Math.sin((2 * Math.PI * day) / 7),
}));
const forecast = await Effect.runPromise(
Effect.gen(function* () {
const model = yield* fit(history);
// The seven days after the history, like Python's `make_future_dataframe`.
const nextWeek = yield* makeFutureTimestamps(history, { periods: 7, includeHistory: false });
return yield* predict(model, nextWeek);
}).pipe(Effect.provide(prophetFittingBackendLayer)),
);
console.log(forecast.map((row) => row.value));New to Effect? The docs have a five-minute introduction.
What it can do
- Linear, flat and capped (logistic) trends with automatic changepoints
- Weekly, yearly and daily patterns, plus your own custom ones
- Holidays and events, and extra factors such as temperature or ad spend, which can be forecast by their own models
- Fitting and forecasting in one call, with the future dates listed for you
- Uncertainty ranges, on their own or alongside each forecast
- Full Bayesian fitting, like Python's
mcmc_samples, with ranges for every component - Finding anomalies, in new measurements or across a history
- Residuals, to check how well a model fits
- Saving and loading fitted models, and warm-starting a refit from an earlier one
- Cross-validation, accuracy metrics by period or calendar month, scaled errors (MASE) and your own metrics
- Choosing between settings, including every combination from a grid
- Tracing built in: every fit and forecast is traced, ready for any OpenTelemetry backend
See the examples for each one.
Tracing built in
Every fit, forecast and evaluation creates Effect spans automatically, with no changes to how you call the library. Send them to Jaeger, Honeycomb, Grafana Tempo or any OpenTelemetry backend using Effect's built-in exporter:
// Continues the quick start: `fit`, `predict`, `history` and `nextWeek` are defined there.
import { Effect, Layer } from "effect";
import { FetchHttpClient } from "effect/http";
import { OtlpSerialization, OtlpTracer } from "effect/observability";
const tracing = OtlpTracer.layer({
url: "http://localhost:4318/v1/traces",
resource: { serviceName: "sales-forecast" },
}).pipe(Layer.provide([OtlpSerialization.layerJson, FetchHttpClient.layer]));
const forecast = await Effect.runPromise(
Effect.gen(function* () {
const model = yield* fit(history);
return yield* predict(model, nextWeek);
}).pipe(Effect.provide(prophetFittingBackendLayer), Effect.provide(tracing)),
);Each fit records what the forecasting engine did (rows, changepoints, parameters, solver steps),
so a slow fit explains itself. The attributes Effect Prophet sets contain only counts and labels,
never your data. A failed span still carries its error, and exporters such as OtlpTracer send
error messages and stack traces, which can name your fields. See
Tracing for what's recorded.
Coming from Python Prophet?
Start with Coming from Python, then see how close the results are.
AI disclosure
Effect Prophet is a TypeScript port of Meta's Python Prophet, and most of the code was written with AI assistance. The forecasting math is easy to get subtly wrong, so the project doesn't ask you to take correctness on trust. Results are checked against Python Prophet itself, and you can see how closely they match in the benchmarks and the accuracy comparison.
If you find a case where the results differ from Python Prophet, please open an issue.
Contributing
npm install
npm test # unit tests (builds the WebAssembly first)
npm run check # everything CI runs, and more
npm run docs:dev # documentation site at http://localhost:5173/effect-prophet/Building the WebAssembly requires Rust and wasm-pack.
Type checking reads the generated bindings, so run npm run build:wasm (or npm test) once
before npm run typecheck.
Comparing against Python requires Docker.
License
MIT. Effect Prophet reimplements Prophet (MIT)
and ports parts of Stan, Eigen, nalgebra and Arm optimized-routines; their notices and license
terms are in rust/prophet-wasm/third-party/ and ship
in the package under wasm/third-party/.
