progressive-zod 1.2.0 → 1.3.0

package/.claude/commands/instrument.md

@@ -27,8 +27,12 @@ Search for code patterns that handle data without runtime validation:
 For each boundary found, add a `progressive()` call. Use descriptive names that identify the boundary.
 
 ```typescript
+// Server-side code (Node.js, Express, etc.)
 import { progressive } from "progressive-zod";
 
+// Frontend code (Vite, Next.js client, etc.)
+import { progressive } from "progressive-zod/client";
+
 // Before: untyped
 const data = req.body;
 
@@ -44,11 +48,15 @@ const data = UserCreate.parse(req.body);
 
 ### 3. Ensure progressive-zod is configured
 
-If there's no existing setup, add this to the app's entry point:
+If there's no existing setup, add configuration to the app's entry point. Use the right import path based on the environment:
 
 ```typescript
+// Server-side (Node.js, Express, etc.)
 import { configure } from "progressive-zod";
 
+// Frontend (Vite, Next.js client, etc.) — avoids bundling ioredis
+import { configure } from "progressive-zod/client";
+
 // For localhost development — no Redis needed
 configure({
   storage: "memory",
@@ -56,6 +64,8 @@ configure({
 });
 ```
 
+**Important:** In frontend/browser code, always use `progressive-zod/client` to avoid bundler errors from server-only dependencies (ioredis). The client entry supports memory and Amplitude storage but not Redis.
+
 Add `.progressive-zod/` to `.gitignore` if not already there.
 
 ### 4. Show the user what you did
@@ -75,6 +85,7 @@ After instrumenting, summarize:
 - **progressive() never throws** — it always returns input unchanged, so it's safe to add anywhere
 - **Be conservative** — only instrument clear untyped boundaries, don't wrap already-typed internal code
 - **One progressive() per boundary** — don't double-wrap
+- **Use the right import path** — use `progressive-zod/client` in frontend/browser code (Vite, Next.js client components, etc.) and `progressive-zod` in server-side code. The client entry excludes Redis to avoid bundler errors.
 - If the user already has Zod schemas for some boundaries, pass them as the second argument:
   ```typescript
   const UserCreate = progressive("UserCreate", existingUserSchema);

package/README.md

@@ -28,6 +28,16 @@ app.post("/users", (req, res) => {
 });
 ```
 
+### Using in a frontend (Vite, Next.js, etc.)
+
+If you're bundling with Vite or another frontend bundler, import from the client entry point to avoid pulling in server-only dependencies like `ioredis`:
+
+```typescript
+import { progressive } from "progressive-zod/client";
+```
+
+The client entry supports memory and Amplitude storage. If you need Redis, use the server entry (`progressive-zod`).
+
 Run your app, hit some endpoints, then:
 
 ```bash
@@ -113,7 +123,7 @@ This package includes a `/instrument` skill for [Claude Code](https://docs.anthr
 
 | Option | Env var | Default | Description |
 |--------|---------|---------|-------------|
-| `storage` | `PROGRESSIVE_ZOD_STORAGE` | `"memory"` | `"memory"` or `"redis"` |
+| `storage` | `PROGRESSIVE_ZOD_STORAGE` | `"memory"` | `"memory"`, `"redis"`, or `"amplitude"` |
 | `redisUrl` | `PROGRESSIVE_ZOD_REDIS_URL` | `redis://localhost:6379` | Redis URL (only for redis storage) |
 | `keyPrefix` | `PROGRESSIVE_ZOD_KEY_PREFIX` | `pzod:` | Key namespace prefix |
 | `maxSamples` | `PROGRESSIVE_ZOD_MAX_SAMPLES` | `1000` | Max samples per type |

package/dist/cli/index.js

@@ -15,6 +15,13 @@ var amplitude_exports = {};
 __export(amplitude_exports, {
   AmplitudeStorage: () => AmplitudeStorage
 });
+function flattenToString(value) {
+  if (value === null || value === void 0) return String(value);
+  if (typeof value !== "object") return String(value);
+  if (Array.isArray(value)) return value.map(String).join(", ");
+  const entries = Object.entries(value);
+  return entries.map(([k, v]) => `${k}=${JSON.stringify(v)}`).join("; ");
+}
 var AmplitudeStorage;
 var init_amplitude = __esm({
   "src/storage/amplitude.ts"() {
@@ -32,17 +39,37 @@ var init_amplitude = __esm({
       }
       addViolation(_name, _violation) {
       }
-      incrConform(name) {
+      incrConform(name, _sample) {
         this.client.track(
           "pzod:type_checked",
           { type_name: name, result: "conform" },
           { device_id: this.deviceId }
         );
       }
-      incrViolate(name) {
+      incrViolate(name, sample, errors) {
+        const properties = {
+          type_name: name,
+          result: "violate"
+        };
+        if (sample) {
+          try {
+            const parsed = JSON.parse(sample);
+            properties.sample_type = typeof parsed;
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+              properties.field_count = Object.keys(parsed).length;
+            }
+            properties.sample_preview = flattenToString(parsed).slice(0, 256);
+          } catch {
+            properties.sample_type = "unknown";
+            properties.sample_preview = sample.slice(0, 256);
+          }
+        }
+        if (errors) {
+          properties.validation_errors = errors.slice(0, 1024);
+        }
         this.client.track(
           "pzod:type_checked",
-          { type_name: name, result: "violate" },
+          properties,
           { device_id: this.deviceId }
         );
       }
@@ -169,22 +196,14 @@ var init_redis = __esm({
 import { Command } from "commander";
 
 // src/storage/memory.ts
-import * as fs from "fs";
-import * as path from "path";
 var MemoryStorage = class {
   names = /* @__PURE__ */ new Set();
   data = /* @__PURE__ */ new Map();
   maxSamples;
   maxViolations;
-  dataDir;
-  flushTimer;
   constructor(config = {}) {
     this.maxSamples = config.maxSamples ?? 1e3;
     this.maxViolations = config.maxViolations ?? 1e3;
-    this.dataDir = config.dataDir;
-    if (this.dataDir) {
-      this.loadFromDisk();
-    }
   }
   getOrCreate(name) {
     let entry = this.data.get(name);
@@ -196,7 +215,6 @@ var MemoryStorage = class {
   }
   addName(name) {
     this.names.add(name);
-    this.schedulePersist();
   }
   addSample(name, sample) {
     const entry = this.getOrCreate(name);
@@ -204,7 +222,6 @@ var MemoryStorage = class {
     if (entry.samples.length > this.maxSamples) {
       entry.samples.length = this.maxSamples;
     }
-    this.schedulePersist();
   }
   addViolation(name, violation) {
     const entry = this.getOrCreate(name);
@@ -212,15 +229,12 @@ var MemoryStorage = class {
     if (entry.violations.length > this.maxViolations) {
       entry.violations.length = this.maxViolations;
     }
-    this.schedulePersist();
   }
   incrConform(name) {
     this.getOrCreate(name).conform++;
-    this.schedulePersist();
   }
   incrViolate(name) {
     this.getOrCreate(name).violate++;
-    this.schedulePersist();
   }
   getNames() {
     return [...this.names].sort();
@@ -235,6 +249,79 @@ var MemoryStorage = class {
     const entry = this.getOrCreate(name);
     return { conform: entry.conform, violate: entry.violate };
   }
+  disconnect() {
+  }
+};
+
+// src/storage/resolve.ts
+var currentConfig = {};
+var currentStorage = null;
+var storageFactory = async (config) => new MemoryStorage(config);
+function _setStorageFactory(factory) {
+  storageFactory = factory;
+}
+function env(key) {
+  if (typeof process !== "undefined" && process.env) {
+    return process.env[key];
+  }
+  return void 0;
+}
+function getConfig() {
+  return {
+    storage: currentConfig.storage ?? env("PROGRESSIVE_ZOD_STORAGE") ?? "memory",
+    redisUrl: currentConfig.redisUrl ?? env("PROGRESSIVE_ZOD_REDIS_URL"),
+    keyPrefix: currentConfig.keyPrefix ?? env("PROGRESSIVE_ZOD_KEY_PREFIX") ?? "pzod:",
+    maxViolations: currentConfig.maxViolations ?? parseInt(env("PROGRESSIVE_ZOD_MAX_VIOLATIONS") ?? "1000", 10),
+    maxSamples: currentConfig.maxSamples ?? parseInt(env("PROGRESSIVE_ZOD_MAX_SAMPLES") ?? "1000", 10),
+    dataDir: currentConfig.dataDir ?? env("PROGRESSIVE_ZOD_DATA_DIR")
+  };
+}
+async function getStorage() {
+  if (currentStorage) return currentStorage;
+  const config = getConfig();
+  currentStorage = await storageFactory(config, currentConfig);
+  return currentStorage;
+}
+async function disconnectStorage() {
+  if (currentStorage) {
+    await currentStorage.disconnect();
+    currentStorage = null;
+  }
+}
+
+// src/storage/memory-server.ts
+import * as fs from "fs";
+import * as path from "path";
+var PersistentMemoryStorage = class extends MemoryStorage {
+  dataDir;
+  flushTimer;
+  constructor(config = {}) {
+    super(config);
+    this.dataDir = config.dataDir;
+    if (this.dataDir) {
+      this.loadFromDisk();
+    }
+  }
+  addName(name) {
+    super.addName(name);
+    this.schedulePersist();
+  }
+  addSample(name, sample) {
+    super.addSample(name, sample);
+    this.schedulePersist();
+  }
+  addViolation(name, violation) {
+    super.addViolation(name, violation);
+    this.schedulePersist();
+  }
+  incrConform(name) {
+    super.incrConform(name);
+    this.schedulePersist();
+  }
+  incrViolate(name) {
+    super.incrViolate(name);
+    this.schedulePersist();
+  }
   disconnect() {
     if (this.flushTimer) {
       clearTimeout(this.flushTimer);
@@ -287,36 +374,6 @@ var MemoryStorage = class {
   }
 };
 
-// src/storage/resolve.ts
-var currentConfig = {};
-var currentStorage = null;
-var storageFactory = async (config) => new MemoryStorage(config);
-function _setStorageFactory(factory) {
-  storageFactory = factory;
-}
-function getConfig() {
-  return {
-    storage: currentConfig.storage ?? process.env.PROGRESSIVE_ZOD_STORAGE ?? "memory",
-    redisUrl: currentConfig.redisUrl ?? process.env.PROGRESSIVE_ZOD_REDIS_URL,
-    keyPrefix: currentConfig.keyPrefix ?? process.env.PROGRESSIVE_ZOD_KEY_PREFIX ?? "pzod:",
-    maxViolations: currentConfig.maxViolations ?? parseInt(process.env.PROGRESSIVE_ZOD_MAX_VIOLATIONS ?? "1000", 10),
-    maxSamples: currentConfig.maxSamples ?? parseInt(process.env.PROGRESSIVE_ZOD_MAX_SAMPLES ?? "1000", 10),
-    dataDir: currentConfig.dataDir ?? process.env.PROGRESSIVE_ZOD_DATA_DIR ?? ".progressive-zod"
-  };
-}
-async function getStorage() {
-  if (currentStorage) return currentStorage;
-  const config = getConfig();
-  currentStorage = await storageFactory(config, currentConfig);
-  return currentStorage;
-}
-async function disconnectStorage() {
-  if (currentStorage) {
-    await currentStorage.disconnect();
-    currentStorage = null;
-  }
-}
-
 // src/storage/index.ts
 _setStorageFactory(async (config, userConfig) => {
   if (config.storage === "amplitude") {
@@ -331,7 +388,8 @@ _setStorageFactory(async (config, userConfig) => {
     const { RedisStorage: RedisStorage2 } = await Promise.resolve().then(() => (init_redis(), redis_exports));
     return new RedisStorage2(config);
   }
-  return new MemoryStorage(config);
+  const serverConfig = { ...config, dataDir: config.dataDir ?? ".progressive-zod" };
+  return new PersistentMemoryStorage(serverConfig);
 });
 
 // src/cli/commands/list.ts

package/dist/client.cjs

@@ -1,9 +1,7 @@
 "use strict";
-var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
@@ -20,14 +18,6 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/storage/amplitude.ts
@@ -35,6 +25,13 @@ var amplitude_exports = {};
 __export(amplitude_exports, {
   AmplitudeStorage: () => AmplitudeStorage
 });
+function flattenToString(value) {
+  if (value === null || value === void 0) return String(value);
+  if (typeof value !== "object") return String(value);
+  if (Array.isArray(value)) return value.map(String).join(", ");
+  const entries = Object.entries(value);
+  return entries.map(([k, v]) => `${k}=${JSON.stringify(v)}`).join("; ");
+}
 var AmplitudeStorage;
 var init_amplitude = __esm({
   "src/storage/amplitude.ts"() {
@@ -52,17 +49,37 @@ var init_amplitude = __esm({
       }
       addViolation(_name, _violation) {
       }
-      incrConform(name) {
+      incrConform(name, _sample) {
         this.client.track(
           "pzod:type_checked",
           { type_name: name, result: "conform" },
           { device_id: this.deviceId }
         );
       }
-      incrViolate(name) {
+      incrViolate(name, sample, errors) {
+        const properties = {
+          type_name: name,
+          result: "violate"
+        };
+        if (sample) {
+          try {
+            const parsed = JSON.parse(sample);
+            properties.sample_type = typeof parsed;
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+              properties.field_count = Object.keys(parsed).length;
+            }
+            properties.sample_preview = flattenToString(parsed).slice(0, 256);
+          } catch {
+            properties.sample_type = "unknown";
+            properties.sample_preview = sample.slice(0, 256);
+          }
+        }
+        if (errors) {
+          properties.validation_errors = errors.slice(0, 1024);
+        }
         this.client.track(
           "pzod:type_checked",
-          { type_name: name, result: "violate" },
+          properties,
           { device_id: this.deviceId }
         );
       }
@@ -99,22 +116,14 @@ __export(client_exports, {
 module.exports = __toCommonJS(client_exports);
 
 // src/storage/memory.ts
-var fs = __toESM(require("fs"), 1);
-var path = __toESM(require("path"), 1);
 var MemoryStorage = class {
   names = /* @__PURE__ */ new Set();
   data = /* @__PURE__ */ new Map();
   maxSamples;
   maxViolations;
-  dataDir;
-  flushTimer;
   constructor(config = {}) {
     this.maxSamples = config.maxSamples ?? 1e3;
     this.maxViolations = config.maxViolations ?? 1e3;
-    this.dataDir = config.dataDir;
-    if (this.dataDir) {
-      this.loadFromDisk();
-    }
   }
   getOrCreate(name) {
     let entry = this.data.get(name);
@@ -126,7 +135,6 @@ var MemoryStorage = class {
   }
   addName(name) {
     this.names.add(name);
-    this.schedulePersist();
   }
   addSample(name, sample) {
     const entry = this.getOrCreate(name);
@@ -134,7 +142,6 @@ var MemoryStorage = class {
     if (entry.samples.length > this.maxSamples) {
       entry.samples.length = this.maxSamples;
     }
-    this.schedulePersist();
   }
   addViolation(name, violation) {
     const entry = this.getOrCreate(name);
@@ -142,15 +149,12 @@ var MemoryStorage = class {
     if (entry.violations.length > this.maxViolations) {
       entry.violations.length = this.maxViolations;
     }
-    this.schedulePersist();
   }
   incrConform(name) {
     this.getOrCreate(name).conform++;
-    this.schedulePersist();
   }
   incrViolate(name) {
     this.getOrCreate(name).violate++;
-    this.schedulePersist();
   }
   getNames() {
     return [...this.names].sort();
@@ -166,54 +170,6 @@ var MemoryStorage = class {
     return { conform: entry.conform, violate: entry.violate };
   }
   disconnect() {
-    if (this.flushTimer) {
-      clearTimeout(this.flushTimer);
-      this.flushTimer = void 0;
-    }
-    if (this.dataDir) {
-      this.persistToDisk();
-    }
-  }
-  schedulePersist() {
-    if (!this.dataDir || this.flushTimer) return;
-    this.flushTimer = setTimeout(() => {
-      this.flushTimer = void 0;
-      this.persistToDisk();
-    }, 500);
-  }
-  persistToDisk() {
-    if (!this.dataDir) return;
-    try {
-      fs.mkdirSync(this.dataDir, { recursive: true });
-      const snapshot = {
-        names: [...this.names],
-        types: Object.fromEntries(this.data)
-      };
-      fs.writeFileSync(
-        path.join(this.dataDir, "data.json"),
-        JSON.stringify(snapshot, null, 2)
-      );
-    } catch {
-    }
-  }
-  loadFromDisk() {
-    if (!this.dataDir) return;
-    try {
-      const raw = fs.readFileSync(
-        path.join(this.dataDir, "data.json"),
-        "utf-8"
-      );
-      const snapshot = JSON.parse(raw);
-      if (Array.isArray(snapshot.names)) {
-        for (const n of snapshot.names) this.names.add(n);
-      }
-      if (snapshot.types && typeof snapshot.types === "object") {
-        for (const [key, val] of Object.entries(snapshot.types)) {
-          this.data.set(key, val);
-        }
-      }
-    } catch {
-    }
   }
 };
 
@@ -231,14 +187,20 @@ function configure(config) {
     currentStorage = null;
   }
 }
+function env(key) {
+  if (typeof process !== "undefined" && process.env) {
+    return process.env[key];
+  }
+  return void 0;
+}
 function getConfig() {
   return {
-    storage: currentConfig.storage ?? process.env.PROGRESSIVE_ZOD_STORAGE ?? "memory",
-    redisUrl: currentConfig.redisUrl ?? process.env.PROGRESSIVE_ZOD_REDIS_URL,
-    keyPrefix: currentConfig.keyPrefix ?? process.env.PROGRESSIVE_ZOD_KEY_PREFIX ?? "pzod:",
-    maxViolations: currentConfig.maxViolations ?? parseInt(process.env.PROGRESSIVE_ZOD_MAX_VIOLATIONS ?? "1000", 10),
-    maxSamples: currentConfig.maxSamples ?? parseInt(process.env.PROGRESSIVE_ZOD_MAX_SAMPLES ?? "1000", 10),
-    dataDir: currentConfig.dataDir ?? process.env.PROGRESSIVE_ZOD_DATA_DIR ?? ".progressive-zod"
+    storage: currentConfig.storage ?? env("PROGRESSIVE_ZOD_STORAGE") ?? "memory",
+    redisUrl: currentConfig.redisUrl ?? env("PROGRESSIVE_ZOD_REDIS_URL"),
+    keyPrefix: currentConfig.keyPrefix ?? env("PROGRESSIVE_ZOD_KEY_PREFIX") ?? "pzod:",
+    maxViolations: currentConfig.maxViolations ?? parseInt(env("PROGRESSIVE_ZOD_MAX_VIOLATIONS") ?? "1000", 10),
+    maxSamples: currentConfig.maxSamples ?? parseInt(env("PROGRESSIVE_ZOD_MAX_SAMPLES") ?? "1000", 10),
+    dataDir: currentConfig.dataDir ?? env("PROGRESSIVE_ZOD_DATA_DIR")
   };
 }
 async function getStorage() {
@@ -360,13 +322,17 @@ var BatchProcessor = class {
     if (obs.schema) {
       const result = obs.schema.safeParse(JSON.parse(obs.serialized));
       if (result.success) {
-        await storage.incrConform(obs.name);
+        await storage.incrConform(obs.name, obs.serialized);
       } else {
-        await storage.incrViolate(obs.name);
+        const errors = result.error.issues.map((i) => {
+          const path = i.path.length > 0 ? i.path.join(".") : "(root)";
+          return `${path}: ${i.message}`;
+        }).join("; ");
+        await storage.incrViolate(obs.name, obs.serialized, errors);
         await storage.addViolation(obs.name, obs.serialized);
       }
     } else {
-      await storage.incrViolate(obs.name);
+      await storage.incrViolate(obs.name, obs.serialized, "no schema defined");
       await storage.addViolation(obs.name, obs.serialized);
     }
   }