progressive-zod 1.3.0 → 1.4.1

package/README.md

@@ -71,7 +71,7 @@ configure({
 });
 ```
 
-For production, you can optionally use Redis:
+For production, you can use Redis or Amplitude:
 
 ```bash
 npm install ioredis
@@ -84,6 +84,46 @@ configure({
 });
 ```
 
+### Amplitude adapter
+
+The Amplitude adapter streams type-check results as analytics events instead of storing raw samples locally. This is useful when you want to track conformance rates in a dashboard without managing storage infrastructure.
+
+**How it works:** each call to `.parse()` fires a single Amplitude event (default name: `progressive-zod: results`). Conform checks send `{ type_name, result: "conforms" }`. Violations include extra properties: `sample_type`, `field_count`, `sample_preview` (first 256 chars, flattened to a `key=value` string), and `validation_errors`.
+
+Read methods (`list`, `infer`, `stats`, `violations`) are no-ops — use the Amplitude dashboard to query your data.
+
+```bash
+npm install @amplitude/analytics-node
+```
+
+```typescript
+import * as amplitude from "@amplitude/analytics-node";
+import { configure } from "progressive-zod";
+
+// Use a separate Amplitude project for observability, not your main product analytics
+const pzodAmplitude = amplitude.createInstance();
+pzodAmplitude.init("YOUR_OBSERVABILITY_PROJECT_API_KEY");
+
+configure({
+  storage: "amplitude",
+  amplitudeClient: pzodAmplitude,
+});
+```
+
+Works in the browser too — import from `progressive-zod/client` and use `@amplitude/analytics-browser` instead.
+
+You can customize the event name:
+
+```typescript
+configure({
+  storage: "amplitude",
+  amplitudeClient: pzodAmplitude,
+  amplitudeEventName: "my-app: type results",
+});
+```
+
+Events use whatever `user_id` and `device_id` you configured on your Amplitude client instance.
+
 ## Track conformance against existing schemas
 
 Already have a partial schema? Pass it as the second argument to track how much real data conforms:
@@ -129,3 +169,5 @@ This package includes a `/instrument` skill for [Claude Code](https://docs.anthr
 | `maxSamples` | `PROGRESSIVE_ZOD_MAX_SAMPLES` | `1000` | Max samples per type |
 | `maxViolations` | `PROGRESSIVE_ZOD_MAX_VIOLATIONS` | `1000` | Max violations per type |
 | `dataDir` | `PROGRESSIVE_ZOD_DATA_DIR` | `.progressive-zod` | File persistence path (memory mode) |
+| `amplitudeClient` | — | — | Amplitude SDK instance (required for amplitude storage) |
+| `amplitudeEventName` | — | `"progressive-zod: results"` | Custom event name (amplitude storage only) |

package/dist/cli/index.js

@@ -28,10 +28,10 @@ var init_amplitude = __esm({
     "use strict";
     AmplitudeStorage = class {
       client;
-      deviceId;
+      eventName;
       constructor(client, config) {
         this.client = client;
-        this.deviceId = `pzod:${config.keyPrefix ?? "default"}`;
+        this.eventName = config.amplitudeEventName ?? "progressive-zod: results";
       }
       addName(_name) {
       }
@@ -40,16 +40,12 @@ var init_amplitude = __esm({
       addViolation(_name, _violation) {
       }
       incrConform(name, _sample) {
-        this.client.track(
-          "pzod:type_checked",
-          { type_name: name, result: "conform" },
-          { device_id: this.deviceId }
-        );
+        this.client.track(this.eventName, { type_name: name, result: "conforms" });
       }
       incrViolate(name, sample, errors) {
         const properties = {
           type_name: name,
-          result: "violate"
+          result: "violation"
         };
         if (sample) {
           try {
@@ -67,11 +63,7 @@ var init_amplitude = __esm({
         if (errors) {
           properties.validation_errors = errors.slice(0, 1024);
         }
-        this.client.track(
-          "pzod:type_checked",
-          properties,
-          { device_id: this.deviceId }
-        );
+        this.client.track(this.eventName, properties);
       }
       // --- Read methods: no-ops (use Amplitude dashboard) ---
       async getNames() {
@@ -195,6 +187,9 @@ var init_redis = __esm({
 // src/cli/index.ts
 import { Command } from "commander";
 
+// src/storage/resolve.ts
+import { z } from "zod";
+
 // src/storage/memory.ts
 var MemoryStorage = class {
   names = /* @__PURE__ */ new Set();
@@ -254,6 +249,31 @@ var MemoryStorage = class {
 };
 
 // src/storage/resolve.ts
+var progressiveConfigSchema = z.object({
+  storage: z.enum(["memory", "redis", "amplitude"]).optional(),
+  redisUrl: z.string().optional(),
+  keyPrefix: z.string().optional(),
+  maxViolations: z.number().optional(),
+  maxSamples: z.number().optional(),
+  dataDir: z.string().optional(),
+  amplitudeClient: z.any().optional(),
+  amplitudeEventName: z.string().optional()
+}).superRefine((data, ctx) => {
+  if (data.amplitudeEventName && data.storage !== "amplitude") {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'amplitudeEventName can only be used when storage is "amplitude"',
+      path: ["amplitudeEventName"]
+    });
+  }
+  if (data.amplitudeClient && data.storage !== "amplitude") {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'amplitudeClient can only be used when storage is "amplitude"',
+      path: ["amplitudeClient"]
+    });
+  }
+});
 var currentConfig = {};
 var currentStorage = null;
 var storageFactory = async (config) => new MemoryStorage(config);
@@ -445,7 +465,7 @@ async function violationsCommand(name, opts) {
 }
 
 // src/infer-schema.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 function inferSchema(samples) {
   const objects = samples.filter(
     (s) => typeof s === "object" && s !== null && !Array.isArray(s)
@@ -459,14 +479,14 @@ function inferSchema(samples) {
   }
   const discriminator = findDiscriminator(groups);
   if (discriminator) {
-    return z.discriminatedUnion(
+    return z2.discriminatedUnion(
       discriminator,
       groups.map(
         (group) => buildObjectSchema(group)
       )
     );
   }
-  return z.union(
+  return z2.union(
     groups.map((group) => buildObjectSchema(group))
   );
 }
@@ -525,21 +545,21 @@ function buildObjectSchema(samples) {
     const values = samples.map((s) => s[key]);
     const unique = new Set(values);
     if (unique.size === 1 && typeof values[0] === "string") {
-      shape[key] = z.literal(values[0]);
+      shape[key] = z2.literal(values[0]);
     } else {
       shape[key] = inferFieldType(values);
     }
   }
-  return z.object(shape).strict();
+  return z2.object(shape).strict();
 }
 function inferFieldType(values) {
   const types = new Set(values.map(classifyValue));
   if (types.size === 1) {
     const type = [...types][0];
-    if (type === "string") return z.string();
-    if (type === "number") return z.number();
-    if (type === "boolean") return z.boolean();
-    if (type === "null") return z.null();
+    if (type === "string") return z2.string();
+    if (type === "number") return z2.number();
+    if (type === "boolean") return z2.boolean();
+    if (type === "null") return z2.null();
     if (type === "object") {
       return inferSchema(values);
     }
@@ -547,21 +567,21 @@ function inferFieldType(values) {
       const allItems = values.flatMap(
         (v) => Array.isArray(v) ? v : []
       );
-      if (allItems.length === 0) return z.array(z.unknown());
-      return z.array(inferFieldType(allItems));
+      if (allItems.length === 0) return z2.array(z2.unknown());
+      return z2.array(inferFieldType(allItems));
     }
   }
   if (types.size === 1 && types.has("string")) {
     const unique = new Set(values);
     if (unique.size === 1) {
-      return z.literal(values[0]);
+      return z2.literal(values[0]);
     }
   }
   const members = [];
-  if (types.has("string")) members.push(z.string());
-  if (types.has("number")) members.push(z.number());
-  if (types.has("boolean")) members.push(z.boolean());
-  if (types.has("null")) members.push(z.null());
+  if (types.has("string")) members.push(z2.string());
+  if (types.has("number")) members.push(z2.number());
+  if (types.has("boolean")) members.push(z2.boolean());
+  if (types.has("null")) members.push(z2.null());
   if (types.has("object")) {
     const objs = values.filter(
       (v) => typeof v === "object" && v !== null && !Array.isArray(v)
@@ -572,12 +592,12 @@ function inferFieldType(values) {
     const arrs = values.filter(Array.isArray);
     const allItems = arrs.flat();
     members.push(
-      z.array(allItems.length > 0 ? inferFieldType(allItems) : z.unknown())
+      z2.array(allItems.length > 0 ? inferFieldType(allItems) : z2.unknown())
     );
   }
   if (members.length === 1) return members[0];
-  if (members.length === 2) return z.union([members[0], members[1]]);
-  return z.union(members);
+  if (members.length === 2) return z2.union([members[0], members[1]]);
+  return z2.union(members);
 }
 function classifyValue(v) {
   if (v === null) return "null";
@@ -587,33 +607,33 @@ function classifyValue(v) {
 function inferPrimitiveUnion(samples) {
   const types = new Set(samples.map(classifyValue));
   const members = [];
-  if (types.has("string")) members.push(z.string());
-  if (types.has("number")) members.push(z.number());
-  if (types.has("boolean")) members.push(z.boolean());
-  if (types.has("null")) members.push(z.null());
-  if (members.length === 0) return z.unknown();
+  if (types.has("string")) members.push(z2.string());
+  if (types.has("number")) members.push(z2.number());
+  if (types.has("boolean")) members.push(z2.boolean());
+  if (types.has("null")) members.push(z2.null());
+  if (members.length === 0) return z2.unknown();
   if (members.length === 1) return members[0];
-  return z.union(members);
+  return z2.union(members);
 }
 
 // src/schema-to-code.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 function schemaToCode(schema, indent = 0) {
   const pad = "  ".repeat(indent);
-  if (schema instanceof z2.ZodString) return "z.string()";
-  if (schema instanceof z2.ZodNumber) return "z.number()";
-  if (schema instanceof z2.ZodBoolean) return "z.boolean()";
-  if (schema instanceof z2.ZodNull) return "z.null()";
-  if (schema instanceof z2.ZodUnknown) return "z.unknown()";
-  if (schema instanceof z2.ZodLiteral) {
+  if (schema instanceof z3.ZodString) return "z.string()";
+  if (schema instanceof z3.ZodNumber) return "z.number()";
+  if (schema instanceof z3.ZodBoolean) return "z.boolean()";
+  if (schema instanceof z3.ZodNull) return "z.null()";
+  if (schema instanceof z3.ZodUnknown) return "z.unknown()";
+  if (schema instanceof z3.ZodLiteral) {
     const val = schema.value;
     return typeof val === "string" ? `z.literal("${val}")` : `z.literal(${val})`;
   }
-  if (schema instanceof z2.ZodArray) {
+  if (schema instanceof z3.ZodArray) {
     const inner = schemaToCode(schema.element, indent);
     return `z.array(${inner})`;
   }
-  if (schema instanceof z2.ZodObject) {
+  if (schema instanceof z3.ZodObject) {
     const shape = schema.shape;
     const keys = Object.keys(shape);
     if (keys.length === 0) return "z.object({})";
@@ -626,7 +646,7 @@ function schemaToCode(schema, indent = 0) {
 ${fields.join("\n")}
 ${pad}})${strict}`;
   }
-  if (schema instanceof z2.ZodUnion) {
+  if (schema instanceof z3.ZodUnion) {
     const opts = schema.options;
     const members = opts.map((o) => schemaToCode(o, indent));
     if (members.every((m) => !m.includes("\n"))) {
@@ -637,7 +657,7 @@ ${pad}})${strict}`;
 ${members.map((m) => `${inner}${m},`).join("\n")}
 ${pad}])`;
   }
-  if (schema instanceof z2.ZodDiscriminatedUnion) {
+  if (schema instanceof z3.ZodDiscriminatedUnion) {
     const disc = schema._def.discriminator;
     const opts = schema._def.options;
     const members = opts.map((o) => schemaToCode(o, indent + 1));

package/dist/client.cjs

@@ -38,10 +38,10 @@ var init_amplitude = __esm({
     "use strict";
     AmplitudeStorage = class {
       client;
-      deviceId;
+      eventName;
       constructor(client, config) {
         this.client = client;
-        this.deviceId = `pzod:${config.keyPrefix ?? "default"}`;
+        this.eventName = config.amplitudeEventName ?? "progressive-zod: results";
       }
       addName(_name) {
       }
@@ -50,16 +50,12 @@ var init_amplitude = __esm({
       addViolation(_name, _violation) {
       }
       incrConform(name, _sample) {
-        this.client.track(
-          "pzod:type_checked",
-          { type_name: name, result: "conform" },
-          { device_id: this.deviceId }
-        );
+        this.client.track(this.eventName, { type_name: name, result: "conforms" });
       }
       incrViolate(name, sample, errors) {
         const properties = {
           type_name: name,
-          result: "violate"
+          result: "violation"
         };
         if (sample) {
           try {
@@ -77,11 +73,7 @@ var init_amplitude = __esm({
         if (errors) {
           properties.validation_errors = errors.slice(0, 1024);
         }
-        this.client.track(
-          "pzod:type_checked",
-          properties,
-          { device_id: this.deviceId }
-        );
+        this.client.track(this.eventName, properties);
       }
       // --- Read methods: no-ops (use Amplitude dashboard) ---
       async getNames() {
@@ -115,6 +107,9 @@ __export(client_exports, {
 });
 module.exports = __toCommonJS(client_exports);
 
+// src/storage/resolve.ts
+var import_zod = require("zod");
+
 // src/storage/memory.ts
 var MemoryStorage = class {
   names = /* @__PURE__ */ new Set();
@@ -174,6 +169,31 @@ var MemoryStorage = class {
 };
 
 // src/storage/resolve.ts
+var progressiveConfigSchema = import_zod.z.object({
+  storage: import_zod.z.enum(["memory", "redis", "amplitude"]).optional(),
+  redisUrl: import_zod.z.string().optional(),
+  keyPrefix: import_zod.z.string().optional(),
+  maxViolations: import_zod.z.number().optional(),
+  maxSamples: import_zod.z.number().optional(),
+  dataDir: import_zod.z.string().optional(),
+  amplitudeClient: import_zod.z.any().optional(),
+  amplitudeEventName: import_zod.z.string().optional()
+}).superRefine((data, ctx) => {
+  if (data.amplitudeEventName && data.storage !== "amplitude") {
+    ctx.addIssue({
+      code: import_zod.z.ZodIssueCode.custom,
+      message: 'amplitudeEventName can only be used when storage is "amplitude"',
+      path: ["amplitudeEventName"]
+    });
+  }
+  if (data.amplitudeClient && data.storage !== "amplitude") {
+    ctx.addIssue({
+      code: import_zod.z.ZodIssueCode.custom,
+      message: 'amplitudeClient can only be used when storage is "amplitude"',
+      path: ["amplitudeClient"]
+    });
+  }
+});
 var currentConfig = {};
 var currentStorage = null;
 var storageFactory = async (config) => new MemoryStorage(config);
@@ -181,7 +201,9 @@ function _setStorageFactory(factory) {
   storageFactory = factory;
 }
 function configure(config) {
-  currentConfig = { ...currentConfig, ...config };
+  const merged = { ...currentConfig, ...config };
+  progressiveConfigSchema.parse(merged);
+  currentConfig = merged;
   if (currentStorage) {
     currentStorage.disconnect();
     currentStorage = null;
@@ -392,7 +414,7 @@ _setStorageFactory(async (config, userConfig) => {
 });
 
 // src/infer-schema.ts
-var import_zod = require("zod");
+var import_zod2 = require("zod");
 function inferSchema(samples) {
   const objects = samples.filter(
     (s) => typeof s === "object" && s !== null && !Array.isArray(s)
@@ -406,14 +428,14 @@ function inferSchema(samples) {
   }
   const discriminator = findDiscriminator(groups);
   if (discriminator) {
-    return import_zod.z.discriminatedUnion(
+    return import_zod2.z.discriminatedUnion(
       discriminator,
       groups.map(
         (group) => buildObjectSchema(group)
       )
     );
   }
-  return import_zod.z.union(
+  return import_zod2.z.union(
     groups.map((group) => buildObjectSchema(group))
   );
 }
@@ -472,21 +494,21 @@ function buildObjectSchema(samples) {
     const values = samples.map((s) => s[key]);
     const unique = new Set(values);
     if (unique.size === 1 && typeof values[0] === "string") {
-      shape[key] = import_zod.z.literal(values[0]);
+      shape[key] = import_zod2.z.literal(values[0]);
     } else {
       shape[key] = inferFieldType(values);
     }
   }
-  return import_zod.z.object(shape).strict();
+  return import_zod2.z.object(shape).strict();
 }
 function inferFieldType(values) {
   const types = new Set(values.map(classifyValue));
   if (types.size === 1) {
     const type = [...types][0];
-    if (type === "string") return import_zod.z.string();
-    if (type === "number") return import_zod.z.number();
-    if (type === "boolean") return import_zod.z.boolean();
-    if (type === "null") return import_zod.z.null();
+    if (type === "string") return import_zod2.z.string();
+    if (type === "number") return import_zod2.z.number();
+    if (type === "boolean") return import_zod2.z.boolean();
+    if (type === "null") return import_zod2.z.null();
     if (type === "object") {
       return inferSchema(values);
     }
@@ -494,21 +516,21 @@ function inferFieldType(values) {
       const allItems = values.flatMap(
         (v) => Array.isArray(v) ? v : []
       );
-      if (allItems.length === 0) return import_zod.z.array(import_zod.z.unknown());
-      return import_zod.z.array(inferFieldType(allItems));
+      if (allItems.length === 0) return import_zod2.z.array(import_zod2.z.unknown());
+      return import_zod2.z.array(inferFieldType(allItems));
     }
   }
   if (types.size === 1 && types.has("string")) {
     const unique = new Set(values);
     if (unique.size === 1) {
-      return import_zod.z.literal(values[0]);
+      return import_zod2.z.literal(values[0]);
     }
   }
   const members = [];
-  if (types.has("string")) members.push(import_zod.z.string());
-  if (types.has("number")) members.push(import_zod.z.number());
-  if (types.has("boolean")) members.push(import_zod.z.boolean());
-  if (types.has("null")) members.push(import_zod.z.null());
+  if (types.has("string")) members.push(import_zod2.z.string());
+  if (types.has("number")) members.push(import_zod2.z.number());
+  if (types.has("boolean")) members.push(import_zod2.z.boolean());
+  if (types.has("null")) members.push(import_zod2.z.null());
   if (types.has("object")) {
     const objs = values.filter(
       (v) => typeof v === "object" && v !== null && !Array.isArray(v)
@@ -519,12 +541,12 @@ function inferFieldType(values) {
     const arrs = values.filter(Array.isArray);
     const allItems = arrs.flat();
     members.push(
-      import_zod.z.array(allItems.length > 0 ? inferFieldType(allItems) : import_zod.z.unknown())
+      import_zod2.z.array(allItems.length > 0 ? inferFieldType(allItems) : import_zod2.z.unknown())
     );
   }
   if (members.length === 1) return members[0];
-  if (members.length === 2) return import_zod.z.union([members[0], members[1]]);
-  return import_zod.z.union(members);
+  if (members.length === 2) return import_zod2.z.union([members[0], members[1]]);
+  return import_zod2.z.union(members);
 }
 function classifyValue(v) {
   if (v === null) return "null";
@@ -534,33 +556,33 @@ function classifyValue(v) {
 function inferPrimitiveUnion(samples) {
   const types = new Set(samples.map(classifyValue));
   const members = [];
-  if (types.has("string")) members.push(import_zod.z.string());
-  if (types.has("number")) members.push(import_zod.z.number());
-  if (types.has("boolean")) members.push(import_zod.z.boolean());
-  if (types.has("null")) members.push(import_zod.z.null());
-  if (members.length === 0) return import_zod.z.unknown();
+  if (types.has("string")) members.push(import_zod2.z.string());
+  if (types.has("number")) members.push(import_zod2.z.number());
+  if (types.has("boolean")) members.push(import_zod2.z.boolean());
+  if (types.has("null")) members.push(import_zod2.z.null());
+  if (members.length === 0) return import_zod2.z.unknown();
   if (members.length === 1) return members[0];
-  return import_zod.z.union(members);
+  return import_zod2.z.union(members);
 }
 
 // src/schema-to-code.ts
-var import_zod2 = require("zod");
+var import_zod3 = require("zod");
 function schemaToCode(schema, indent = 0) {
   const pad = "  ".repeat(indent);
-  if (schema instanceof import_zod2.z.ZodString) return "z.string()";
-  if (schema instanceof import_zod2.z.ZodNumber) return "z.number()";
-  if (schema instanceof import_zod2.z.ZodBoolean) return "z.boolean()";
-  if (schema instanceof import_zod2.z.ZodNull) return "z.null()";
-  if (schema instanceof import_zod2.z.ZodUnknown) return "z.unknown()";
-  if (schema instanceof import_zod2.z.ZodLiteral) {
+  if (schema instanceof import_zod3.z.ZodString) return "z.string()";
+  if (schema instanceof import_zod3.z.ZodNumber) return "z.number()";
+  if (schema instanceof import_zod3.z.ZodBoolean) return "z.boolean()";
+  if (schema instanceof import_zod3.z.ZodNull) return "z.null()";
+  if (schema instanceof import_zod3.z.ZodUnknown) return "z.unknown()";
+  if (schema instanceof import_zod3.z.ZodLiteral) {
     const val = schema.value;
     return typeof val === "string" ? `z.literal("${val}")` : `z.literal(${val})`;
   }
-  if (schema instanceof import_zod2.z.ZodArray) {
+  if (schema instanceof import_zod3.z.ZodArray) {
     const inner = schemaToCode(schema.element, indent);
     return `z.array(${inner})`;
   }
-  if (schema instanceof import_zod2.z.ZodObject) {
+  if (schema instanceof import_zod3.z.ZodObject) {
     const shape = schema.shape;
     const keys = Object.keys(shape);
     if (keys.length === 0) return "z.object({})";
@@ -573,7 +595,7 @@ function schemaToCode(schema, indent = 0) {
 ${fields.join("\n")}
 ${pad}})${strict}`;
   }
-  if (schema instanceof import_zod2.z.ZodUnion) {
+  if (schema instanceof import_zod3.z.ZodUnion) {
     const opts = schema.options;
     const members = opts.map((o) => schemaToCode(o, indent));
     if (members.every((m) => !m.includes("\n"))) {
@@ -584,7 +606,7 @@ ${pad}})${strict}`;
 ${members.map((m) => `${inner}${m},`).join("\n")}
 ${pad}])`;
   }
-  if (schema instanceof import_zod2.z.ZodDiscriminatedUnion) {
+  if (schema instanceof import_zod3.z.ZodDiscriminatedUnion) {
     const disc = schema._def.discriminator;
     const opts = schema._def.options;
     const members = opts.map((o) => schemaToCode(o, indent + 1));