tersejson 0.2.0 → 0.2.1

package/README.md

@@ -135,6 +135,61 @@ console.log(users[0].emailAddress); // Works transparently!
 
 *At $0.09/GB egress, 10M requests/day = ~$1,000/month saved.*
 
+## Why Gzip Isn't Enough
+
+**"Just use gzip"** is the most common response to compression libraries. But here's the reality:
+
+### Gzip Often Isn't Enabled
+
+- **11%** of websites have zero compression (W3Techs)
+- **60%** of HTTP responses have no text-based compression (HTTP Archive)
+
+### Proxy Defaults Are Hostile
+
+Most deployments put a reverse proxy (nginx, Traefik, etc.) in front of Node.js. The defaults actively work against you:
+
+**NGINX:**
+- `gzip_proxied` defaults to `off` — won't compress proxied requests
+- `gzip_http_version` defaults to `1.1`, but `proxy_http_version` defaults to `1.0` — mismatch causes silent failures
+- Official Docker nginx image ships with `#gzip on;` (commented out)
+
+**Traefik (Dokploy, Coolify, etc.):**
+- Compress middleware is NOT enabled by default
+- Must explicitly add labels to every service:
+```yaml
+traefik.http.middlewares.compress.compress=true
+traefik.http.routers.myrouter.middlewares=compress
+```
+
+**Kubernetes ingress-nginx:**
+- `use-gzip: false` by default in ConfigMap
+- Must explicitly configure in ingress-nginx-controller
+
+### The Fix Requires DevOps
+
+Enabling gzip properly requires:
+```nginx
+gzip on;
+gzip_proxied any;
+gzip_http_version 1.0;
+gzip_types text/plain application/json application/javascript text/css;
+```
+
+That means DevOps coordination, nginx access, and deployment. In most orgs, the proxy is managed by a different team.
+
+### TerseJSON Just Works
+
+```typescript
+app.use(terse())
+```
+
+One line. Ships with your code. No proxy config. No DevOps ticket. Works whether gzip is enabled or not.
+
+**If gzip is working:** You get 15-25% additional savings on top.
+**If gzip isn't working:** You get 70-80% savings instantly.
+
+Either way, you're covered.
+
 ## API Reference
 
 ### Express Middleware

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tersejson",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Transparent JSON key compression for Express APIs. Reduce bandwidth by up to 80% with zero code changes.",
   "keywords": [
     "json",