garch 1.2.0 → 1.2.2

package/README.md

@@ -556,13 +556,13 @@ where RV_t is Parkinson per-candle realized variance and sigma_t^2 is the model'
 
 ## Tests
 
-**923 tests** across **22 test files**. All passing.
+**932 tests** across **22 test files**. All passing.
 
 | Category | Files | Tests | What's covered |
 |----------|-------|-------|----------------|
 | Mathematical formulas | `math.test.ts` | 45 | GARCH/EGARCH variance recursion, log-likelihood, forecast formulas, AIC/BIC, QLIKE, Yang-Zhang, Garman-Klass, Ljung-Box, chi-squared |
 | Math coverage | `math-coverage.test.ts` | 79 | Parkinson formula verification, rv↔returns alignment, H=L fallback, Parkinson-based forecast, candle validation, reliable flag cascade, backtest validity, numerical precision, cross-model consistency, Realized GARCH/EGARCH/GJR-GARCH Candle[] vs number[], perCandleParkinson shared function |
-| Full pipeline coverage | `plan-coverage.test.ts` | 73 | End-to-end: fit, forecast, predict, predictRange, backtest, model selection |
+| Full pipeline coverage | `plan-coverage.test.ts` | 82 | End-to-end: fit, forecast, predict, predictRange, backtest, model selection |
 | GARCH unit | `garch.test.ts` | 10 | Parameter estimation, variance series, forecast convergence, candle vs price input |
 | EGARCH unit | `egarch.test.ts` | 11 | Leverage detection, asymmetric volatility, model comparison |
 | GJR-GARCH unit | `gjr-garch.test.ts` | 86 | Variance recursion (r² and Parkinson), indicator function I(r<0), forecast formula (one-step + multi-step), constraint barriers, computed fields, AIC/BIC numParams=5, estimation properties (perturbation, determinism), numerical stability, degenerate params, Realized path (Candle[] vs number[], flat candles, bad OHLC), options forwarding, immutability, instance isolation, cross-model consistency, scale invariance, property-based fuzz, predict/predictRange/backtest integration |

package/build/index.cjs

@@ -1780,8 +1780,9 @@ function checkReliable(fit) {
  * @param confidence — two-sided probability in (0,1). Default ≈0.6827 (±1σ).
  *   Common values: 0.90 → z=1.645, 0.95 → z=1.96, 0.99 → z=2.576.
  */
-function predict(candles, interval, currentPrice = candles[candles.length - 1].close, confidence = 0.6827) {
+function predict(candles, interval, currentPrice, confidence = 0.6827) {
     assertMinCandles(candles, interval);
+    currentPrice = currentPrice || candles[candles.length - 1].close;
     const z = probit(confidence);
     const fit = fitModel(candles, INTERVALS_PER_YEAR[interval], 1);
     const sigma = fit.forecast.volatility[0];
@@ -1804,10 +1805,11 @@ function predict(candles, interval, currentPrice = candles[candles.length - 1].c
  * Uses log-normal price bands: P·exp(±z·σ), where z = probit(confidence).
  * @param confidence — two-sided probability in (0,1). Default ≈0.6827 (±1σ).
  */
-function predictRange(candles, interval, steps, currentPrice = candles[candles.length - 1].close, confidence = 0.6827) {
+function predictRange(candles, interval, steps, currentPrice, confidence = 0.6827) {
     assertMinCandles(candles, interval);
     const z = probit(confidence);
     const fit = fitModel(candles, INTERVALS_PER_YEAR[interval], steps);
+    currentPrice = currentPrice || candles[candles.length - 1].close;
     const cumulativeVariance = fit.forecast.variance.reduce((sum, v) => sum + v, 0);
     const sigma = Math.sqrt(cumulativeVariance);
     const upperPrice = currentPrice * Math.exp(z * sigma);
@@ -1879,6 +1881,7 @@ exports.nelderMeadMultiStart = nelderMeadMultiStart;
 exports.perCandleParkinson = perCandleParkinson;
 exports.predict = predict;
 exports.predictRange = predictRange;
+exports.probit = probit;
 exports.profileStudentTDf = profileStudentTDf;
 exports.qlike = qlike;
 exports.sampleVariance = sampleVariance;

package/build/index.mjs

@@ -1778,8 +1778,9 @@ function checkReliable(fit) {
  * @param confidence — two-sided probability in (0,1). Default ≈0.6827 (±1σ).
  *   Common values: 0.90 → z=1.645, 0.95 → z=1.96, 0.99 → z=2.576.
  */
-function predict(candles, interval, currentPrice = candles[candles.length - 1].close, confidence = 0.6827) {
+function predict(candles, interval, currentPrice, confidence = 0.6827) {
     assertMinCandles(candles, interval);
+    currentPrice = currentPrice || candles[candles.length - 1].close;
     const z = probit(confidence);
     const fit = fitModel(candles, INTERVALS_PER_YEAR[interval], 1);
     const sigma = fit.forecast.volatility[0];
@@ -1802,10 +1803,11 @@ function predict(candles, interval, currentPrice = candles[candles.length - 1].c
  * Uses log-normal price bands: P·exp(±z·σ), where z = probit(confidence).
  * @param confidence — two-sided probability in (0,1). Default ≈0.6827 (±1σ).
  */
-function predictRange(candles, interval, steps, currentPrice = candles[candles.length - 1].close, confidence = 0.6827) {
+function predictRange(candles, interval, steps, currentPrice, confidence = 0.6827) {
     assertMinCandles(candles, interval);
     const z = probit(confidence);
     const fit = fitModel(candles, INTERVALS_PER_YEAR[interval], steps);
+    currentPrice = currentPrice || candles[candles.length - 1].close;
     const cumulativeVariance = fit.forecast.variance.reduce((sum, v) => sum + v, 0);
     const sigma = Math.sqrt(cumulativeVariance);
     const upperPrice = currentPrice * Math.exp(z * sigma);
@@ -1853,4 +1855,4 @@ function backtest(candles, interval, confidence = 0.6827, requiredPercent = 68)
     return (hits / total) * 100 >= requiredPercent;
 }
 
-export { EXPECTED_ABS_NORMAL, Egarch, Garch, GjrGarch, HarRv, NoVaS, backtest, calculateReturns, calculateReturnsFromPrices, calibrateEgarch, calibrateGarch, calibrateGjrGarch, calibrateHarRv, calibrateNoVaS, checkLeverageEffect, expectedAbsStudentT, garmanKlassVariance, ljungBox, logGamma, nelderMead, nelderMeadMultiStart, perCandleParkinson, predict, predictRange, profileStudentTDf, qlike, sampleVariance, sampleVarianceWithMean, studentTNegLL, yangZhangVariance };
+export { EXPECTED_ABS_NORMAL, Egarch, Garch, GjrGarch, HarRv, NoVaS, backtest, calculateReturns, calculateReturnsFromPrices, calibrateEgarch, calibrateGarch, calibrateGjrGarch, calibrateHarRv, calibrateNoVaS, checkLeverageEffect, expectedAbsStudentT, garmanKlassVariance, ljungBox, logGamma, nelderMead, nelderMeadMultiStart, perCandleParkinson, predict, predictRange, probit, profileStudentTDf, qlike, sampleVariance, sampleVarianceWithMean, studentTNegLL, yangZhangVariance };

package/package.json

@@ -1,48 +1,48 @@
-{
-  "name": "garch",
-  "version": "1.2.0",
-  "description": "GARCH and EGARCH volatility models for TypeScript",
-  "type": "module",
-  "main": "./build/index.cjs",
-  "module": "./build/index.mjs",
-  "types": "./types.d.ts",
-  "exports": {
-    ".": {
-      "types": "./types.d.ts",
-      "import": "./build/index.mjs",
-      "require": "./build/index.cjs"
-    }
-  },
-  "files": [
-    "build",
-    "types.d.ts",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "rollup -c",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "garch",
-    "egarch",
-    "volatility",
-    "finance",
-    "econometrics",
-    "time-series"
-  ],
-  "author": "",
-  "license": "MIT",
-  "devDependencies": {
-    "@rollup/plugin-typescript": "^12.3.0",
-    "@types/node": "^20.10.0",
-    "@vitest/coverage-v8": "^1.6.1",
-    "rollup": "^4.57.1",
-    "rollup-plugin-dts": "^6.3.0",
-    "rollup-plugin-peer-deps-external": "^2.2.4",
-    "tslib": "^2.8.1",
-    "typescript": "^5.3.0",
-    "vitest": "^1.0.0"
-  }
-}
+{
+  "name": "garch",
+  "version": "1.2.2",
+  "description": "GARCH and EGARCH volatility models for TypeScript",
+  "type": "module",
+  "main": "./build/index.cjs",
+  "module": "./build/index.mjs",
+  "types": "./types.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types.d.ts",
+      "import": "./build/index.mjs",
+      "require": "./build/index.cjs"
+    }
+  },
+  "files": [
+    "build",
+    "types.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rollup -c",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "garch",
+    "egarch",
+    "volatility",
+    "finance",
+    "econometrics",
+    "time-series"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/node": "^20.10.0",
+    "@vitest/coverage-v8": "^1.6.1",
+    "rollup": "^4.57.1",
+    "rollup-plugin-dts": "^6.3.0",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "tslib": "^2.8.1",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  }
+}

package/types.d.ts

@@ -487,6 +487,14 @@ declare function profileStudentTDf(returns: number[], varianceSeries: number[]):
  * of how the model was calibrated (MLE, OLS, D², etc.).
  */
 declare function qlike(varianceSeries: number[], rv: number[]): number;
+/**
+ * Inverse standard normal CDF (probit function).
+ * Converts a two-sided confidence level (e.g. 0.95) to the corresponding
+ * z-score (e.g. 1.96).
+ *
+ * Uses Acklam's rational approximation (max relative error < 1.15e-9).
+ */
+declare function probit(confidence: number): number;
 
 type CandleInterval = '1m' | '3m' | '5m' | '15m' | '30m' | '1h' | '2h' | '4h' | '6h' | '8h';
 interface PredictionResult {
@@ -506,7 +514,7 @@ interface PredictionResult {
  * @param confidence — two-sided probability in (0,1). Default ≈0.6827 (±1σ).
  *   Common values: 0.90 → z=1.645, 0.95 → z=1.96, 0.99 → z=2.576.
  */
-declare function predict(candles: Candle[], interval: CandleInterval, currentPrice?: number, confidence?: number): PredictionResult;
+declare function predict(candles: Candle[], interval: CandleInterval, currentPrice?: number | null, confidence?: number): PredictionResult;
 /**
  * Forecast expected price range over multiple candles.
  *
@@ -514,7 +522,7 @@ declare function predict(candles: Candle[], interval: CandleInterval, currentPri
  * Uses log-normal price bands: P·exp(±z·σ), where z = probit(confidence).
  * @param confidence — two-sided probability in (0,1). Default ≈0.6827 (±1σ).
  */
-declare function predictRange(candles: Candle[], interval: CandleInterval, steps: number, currentPrice?: number, confidence?: number): PredictionResult;
+declare function predictRange(candles: Candle[], interval: CandleInterval, steps: number, currentPrice?: number | null, confidence?: number): PredictionResult;
 /**
  * Walk-forward backtest of predict.
  *
@@ -541,5 +549,5 @@ declare function nelderMeadMultiStart(fn: (x: number[]) => number, x0: number[],
     restarts?: number;
 }): OptimizerResult;
 
-export { EXPECTED_ABS_NORMAL, Egarch, Garch, GjrGarch, HarRv, NoVaS, backtest, calculateReturns, calculateReturnsFromPrices, calibrateEgarch, calibrateGarch, calibrateGjrGarch, calibrateHarRv, calibrateNoVaS, checkLeverageEffect, expectedAbsStudentT, garmanKlassVariance, ljungBox, logGamma, nelderMead, nelderMeadMultiStart, perCandleParkinson, predict, predictRange, profileStudentTDf, qlike, sampleVariance, sampleVarianceWithMean, studentTNegLL, yangZhangVariance };
+export { EXPECTED_ABS_NORMAL, Egarch, Garch, GjrGarch, HarRv, NoVaS, backtest, calculateReturns, calculateReturnsFromPrices, calibrateEgarch, calibrateGarch, calibrateGjrGarch, calibrateHarRv, calibrateNoVaS, checkLeverageEffect, expectedAbsStudentT, garmanKlassVariance, ljungBox, logGamma, nelderMead, nelderMeadMultiStart, perCandleParkinson, predict, predictRange, probit, profileStudentTDf, qlike, sampleVariance, sampleVarianceWithMean, studentTNegLL, yangZhangVariance };
 export type { CalibrationResult, Candle, CandleInterval, EgarchOptions, EgarchParams, GarchOptions, GarchParams, GjrGarchOptions, GjrGarchParams, HarRvOptions, HarRvParams, LeverageStats, NoVaSOptions, NoVaSParams, OptimizerResult, PredictionResult, VolatilityForecast };