@fullstackcraftllc/floe 0.0.1

package/dist/volatility/smoothing.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * Volatility surface smoothing algorithms
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.smoothTotalVarianceSmile = smoothTotalVarianceSmile;
+/**
+ * Smooth total variance smile using cubic spline interpolation and convexity enforcement
+ *
+ * @param strikes - Sorted array of strike prices
+ * @param ivs - Array of IVs as percentages (e.g., 20 = 20%)
+ * @param T - Time to expiration in years
+ * @returns Smoothed IVs as percentages
+ *
+ * @example
+ * ```typescript
+ * const smoothed = smoothTotalVarianceSmile([90, 95, 100, 105, 110], [22, 20, 18, 20, 22], 0.25);
+ * ```
+ */
+function smoothTotalVarianceSmile(strikes, ivs, T) {
+    const n = strikes.length;
+    if (n <= 2) {
+        return ivs; // Not enough points to smooth meaningfully
+    }
+    // Convert IV% → decimal and total variance
+    const w = new Array(n);
+    for (let i = 0; i < n; i++) {
+        const vol = ivs[i] / 100.0; // percent → decimal
+        w[i] = vol * vol * T;
+    }
+    // Step 1: cubic spline interpolation on w(K)
+    const spline = new CubicSpline(strikes, w);
+    // Step 2: evaluate spline at existing strikes (already sorted)
+    const smoothedW = new Array(n);
+    for (let i = 0; i < n; i++) {
+        smoothedW[i] = spline.eval(strikes[i]);
+    }
+    // Step 3: enforce convexity of total variance (simple projection)
+    enforceConvexity(strikes, smoothedW);
+    // Step 4: convert total variance back to IV (percent)
+    const smoothedIV = new Array(n);
+    for (let i = 0; i < n; i++) {
+        if (smoothedW[i] <= 0) {
+            smoothedIV[i] = ivs[i]; // fallback
+        }
+        else {
+            smoothedIV[i] = Math.sqrt(smoothedW[i] / T) * 100.0;
+        }
+    }
+    return smoothedIV;
+}
+/**
+ * Cubic spline interpolation
+ */
+class CubicSpline {
+    constructor(x, y) {
+        const n = x.length;
+        this.x = x;
+        this.a = [...y];
+        this.b = new Array(n).fill(0);
+        this.c = new Array(n).fill(0);
+        this.d = new Array(n).fill(0);
+        const h = new Array(n - 1);
+        for (let i = 0; i < n - 1; i++) {
+            h[i] = x[i + 1] - x[i];
+        }
+        const alpha = new Array(n - 1).fill(0);
+        for (let i = 1; i < n - 1; i++) {
+            alpha[i] = (3 * (this.a[i + 1] - this.a[i])) / h[i] - (3 * (this.a[i] - this.a[i - 1])) / h[i - 1];
+        }
+        const l = new Array(n).fill(0);
+        const mu = new Array(n).fill(0);
+        const z = new Array(n).fill(0);
+        l[0] = 1;
+        mu[0] = 0;
+        z[0] = 0;
+        for (let i = 1; i < n - 1; i++) {
+            l[i] = 2 * (x[i + 1] - x[i - 1]) - h[i - 1] * mu[i - 1];
+            mu[i] = h[i] / l[i];
+            z[i] = (alpha[i] - h[i - 1] * z[i - 1]) / l[i];
+        }
+        l[n - 1] = 1;
+        z[n - 1] = 0;
+        this.c[n - 1] = 0;
+        for (let j = n - 2; j >= 0; j--) {
+            this.c[j] = z[j] - mu[j] * this.c[j + 1];
+            this.b[j] = (this.a[j + 1] - this.a[j]) / h[j] - (h[j] * (this.c[j + 1] + 2 * this.c[j])) / 3;
+            this.d[j] = (this.c[j + 1] - this.c[j]) / (3 * h[j]);
+        }
+    }
+    eval(x) {
+        // Find interval
+        const n = this.x.length;
+        let i = this.findInterval(x, n);
+        if (i > 0 && i >= n - 1) {
+            i = n - 2;
+        }
+        const dx = x - this.x[i];
+        return this.a[i] + this.b[i] * dx + this.c[i] * dx * dx + this.d[i] * dx * dx * dx;
+    }
+    findInterval(x, n) {
+        // Binary search
+        let left = 0;
+        let right = n - 1;
+        while (left < right - 1) {
+            const mid = Math.floor((left + right) / 2);
+            if (this.x[mid] <= x) {
+                left = mid;
+            }
+            else {
+                right = mid;
+            }
+        }
+        return left;
+    }
+}
+/**
+ * Enforce convexity of total variance using convex hull approach
+ *
+ * @param x - Strike prices
+ * @param w - Total variance values (modified in place)
+ */
+function enforceConvexity(x, w) {
+    const n = w.length;
+    if (n < 3) {
+        return;
+    }
+    // Build the lower convex hull of (x, w) points
+    // This guarantees convexity and runs in O(n)
+    const hull = [];
+    for (let i = 0; i < n; i++) {
+        const p = { x: x[i], w: w[i] };
+        // Remove points that would break convexity
+        while (hull.length >= 2) {
+            const h1 = hull[hull.length - 1];
+            const h2 = hull[hull.length - 2];
+            // Cross product to check if we make a left turn (convex)
+            // (h1 - h2) x (p - h2) should be >= 0 for convexity
+            const cross = (h1.x - h2.x) * (p.w - h2.w) - (h1.w - h2.w) * (p.x - h2.x);
+            if (cross >= 0) {
+                break; // convex, keep h1
+            }
+            hull.pop(); // remove h1, it breaks convexity
+        }
+        hull.push(p);
+    }
+    // Now interpolate the hull values back to original x positions
+    let hullIdx = 0;
+    for (let i = 0; i < n; i++) {
+        // Find the hull segment containing x[i]
+        while (hullIdx < hull.length - 1 && hull[hullIdx + 1].x < x[i]) {
+            hullIdx++;
+        }
+        if (hullIdx >= hull.length - 1) {
+            hullIdx = hull.length - 2;
+        }
+        if (hullIdx < 0) {
+            hullIdx = 0;
+        }
+        // Linear interpolation on the hull
+        const h1 = hull[hullIdx];
+        const h2 = hull[hullIdx + 1];
+        if (h2.x === h1.x) {
+            w[i] = h1.w;
+        }
+        else {
+            const t = (x[i] - h1.x) / (h2.x - h1.x);
+            w[i] = h1.w + t * (h2.w - h1.w);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@fullstackcraftllc/floe",
+  "version": "0.0.1",
+  "description": "Production-ready options analytics toolkit. Normalize broker data structures and calculate Black-Scholes, Greeks, and GEX with a clean, type-safe API. Built for trading platforms and fintech applications.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "prepublishOnly": "npm run build",
+    "type-check": "tsc --noEmit"
+  },
+  "keywords": [
+    "options",
+    "black-scholes",
+    "greeks",
+    "gamma",
+    "delta",
+    "vanna",
+    "charm",
+    "dealer-exposure",
+    "gex",
+    "trading",
+    "finance",
+    "typescript"
+  ],
+  "author": {
+    "name": "Full Stack Craft LLC",
+    "email": "hi@fullstackcraft.com",
+    "url": "https://fullstackcraft.com"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FullStackCraft/floe.git"
+  },
+  "bugs": {
+    "url": "https://github.com/FullStackCraft/floe/issues"
+  },
+  "homepage": "https://github.com/FullStackCraft/floe#readme",
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md",
+    "LICENSE-MIT",
+    "LICENSE-COMMERCIAL"
+  ]
+}