progressive-zod 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ferruccio Balestreri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/__tests__/infer-schema.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/infer-schema.test.js

@@ -0,0 +1,121 @@
+import { describe, it, expect } from "vitest";
+import { inferSchema } from "../index";
+describe("inferSchema", () => {
+    describe("1. Single shape", () => {
+        it("produces a plain z.object when all samples share the same keys and types", () => {
+            const samples = [
+                { name: "Alice", age: 30 },
+                { name: "Bob", age: 25 },
+            ];
+            const schema = inferSchema(samples);
+            // Should parse valid samples
+            for (const s of samples) {
+                expect(schema.parse(s)).toEqual(s);
+            }
+            // Should reject structurally incorrect data
+            expect(() => schema.parse({ name: "X" })).toThrow();
+            expect(() => schema.parse({ name: 1, age: 2 })).toThrow();
+            // Should be a ZodObject, not a union
+            expect(schema._zod.def.type).toBe("object");
+        });
+    });
+    describe("2. Discriminated union (string literal discriminator)", () => {
+        it("produces z.discriminatedUnion when samples share a key with different string literals per variant", () => {
+            const samples = [
+                { type: "user", name: "Alice", age: 30 },
+                { type: "org", name: "Acme", members: 5 },
+            ];
+            const schema = inferSchema(samples);
+            // Should parse valid samples
+            for (const s of samples) {
+                expect(schema.parse(s)).toEqual(s);
+            }
+            // Should reject data that doesn't match any variant
+            expect(() => schema.parse({ type: "user", name: "X", members: 3 })).toThrow();
+            expect(() => schema.parse({ type: "org", name: "X", age: 10 })).toThrow();
+            expect(() => schema.parse({ type: "unknown", name: "X" })).toThrow();
+            // Should be a ZodDiscriminatedUnion (zod v4 uses def.type "union" with a discriminator field)
+            expect(schema._zod.def.type).toBe("union");
+            expect(schema._zod.def.discriminator).toBe("type");
+        });
+    });
+    describe("3. Simple union (no discriminator)", () => {
+        it("produces z.union when samples have structurally different shapes with no common literal key", () => {
+            const samples = [
+                { x: 1, y: 2 },
+                { a: "hello", b: "world" },
+            ];
+            const schema = inferSchema(samples);
+            for (const s of samples) {
+                expect(schema.parse(s)).toEqual(s);
+            }
+            expect(() => schema.parse({ x: "wrong", y: 2 })).toThrow();
+            expect(() => schema.parse({ a: 1, b: 2 })).toThrow();
+            // Should be a ZodUnion, not a ZodObject
+            expect(schema._zod.def.type).toBe("union");
+        });
+    });
+    describe("4. Nested objects", () => {
+        it("infers nested object shapes correctly per variant", () => {
+            const samples = [
+                { type: "point2d", coords: { x: 1, y: 2 } },
+                { type: "point3d", coords: { x: 1, y: 2, z: 3 } },
+            ];
+            const schema = inferSchema(samples);
+            for (const s of samples) {
+                expect(schema.parse(s)).toEqual(s);
+            }
+            // Should reject wrong nested shape for a variant
+            expect(() => schema.parse({ type: "point2d", coords: { x: 1, y: 2, z: 3 } })).toThrow();
+            expect(() => schema.parse({ type: "point3d", coords: { x: 1, y: 2 } })).toThrow();
+        });
+    });
+    describe("5. Arrays", () => {
+        it("infers array element types", () => {
+            const samples = [
+                { tags: ["a", "b"], count: 2 },
+                { tags: ["c"], count: 1 },
+            ];
+            const schema = inferSchema(samples);
+            for (const s of samples) {
+                expect(schema.parse(s)).toEqual(s);
+            }
+            // Should reject wrong element types
+            expect(() => schema.parse({ tags: [1, 2], count: 1 })).toThrow();
+        });
+    });
+    describe("6. Mixed primitive types", () => {
+        it("produces z.union of primitives when a field has different types across samples of the same shape", () => {
+            const samples = [
+                { id: 1, value: "hello" },
+                { id: 2, value: 42 },
+            ];
+            const schema = inferSchema(samples);
+            for (const s of samples) {
+                expect(schema.parse(s)).toEqual(s);
+            }
+            // Both string and number should be accepted for value
+            expect(schema.parse({ id: 3, value: "world" })).toEqual({ id: 3, value: "world" });
+            expect(schema.parse({ id: 4, value: 99 })).toEqual({ id: 4, value: 99 });
+            // But boolean should not
+            expect(() => schema.parse({ id: 5, value: true })).toThrow();
+        });
+    });
+    describe("7. Minimality — no optional fields", () => {
+        it("produces a union of exact objects rather than one object with optional fields", () => {
+            const samples = [
+                { a: 1, b: 2 },
+                { a: 1, c: 3 },
+            ];
+            const schema = inferSchema(samples);
+            for (const s of samples) {
+                expect(schema.parse(s)).toEqual(s);
+            }
+            // Should reject data with wrong structure
+            expect(() => schema.parse({ a: 1 })).toThrow();
+            expect(() => schema.parse({ a: 1, b: 2, c: 3 })).toThrow();
+            // Should be a union, not a single object with optionals
+            expect(schema._zod.def.type).not.toBe("object");
+        });
+    });
+});

package/dist/__tests__/progressive.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/progressive.test.js

@@ -0,0 +1,67 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { z } from "zod/v4";
+// Mock ioredis before importing progressive
+const mockPipeline = {
+    lpush: vi.fn().mockReturnThis(),
+    ltrim: vi.fn().mockReturnThis(),
+    exec: vi.fn().mockResolvedValue([]),
+};
+const mockRedis = {
+    sadd: vi.fn().mockResolvedValue(1),
+    incr: vi.fn().mockResolvedValue(1),
+    pipeline: vi.fn().mockReturnValue(mockPipeline),
+    on: vi.fn().mockReturnThis(),
+    connect: vi.fn().mockResolvedValue(undefined),
+    disconnect: vi.fn(),
+    quit: vi.fn().mockResolvedValue("OK"),
+};
+vi.mock("ioredis", () => {
+    return {
+        default: function Redis() {
+            return mockRedis;
+        },
+    };
+});
+import { progressive } from "../progressive";
+beforeEach(() => {
+    vi.clearAllMocks();
+});
+describe("progressive", () => {
+    it("always returns the input unchanged", () => {
+        const schema = progressive("Test");
+        const input = { foo: "bar", n: 42 };
+        expect(schema.parse(input)).toBe(input);
+    });
+    it("never throws, even with invalid data", () => {
+        const schema = progressive("Test", z.object({ id: z.string() }));
+        expect(() => schema.parse(123)).not.toThrow();
+        expect(schema.parse(123)).toBe(123);
+    });
+    it("registers the name in Redis", () => {
+        const schema = progressive("UserPayload");
+        schema.parse({ x: 1 });
+        expect(mockRedis.sadd).toHaveBeenCalledWith("pzod:names", "UserPayload");
+    });
+    it("records samples via pipeline", () => {
+        const schema = progressive("Test");
+        schema.parse({ hello: "world" });
+        expect(mockPipeline.lpush).toHaveBeenCalledWith("pzod:Test:samples", JSON.stringify({ hello: "world" }));
+        expect(mockPipeline.ltrim).toHaveBeenCalledWith("pzod:Test:samples", 0, 999);
+    });
+    it("increments conform count when schema matches", () => {
+        const schema = progressive("Order", z.object({ id: z.string() }));
+        schema.parse({ id: "abc" });
+        expect(mockRedis.incr).toHaveBeenCalledWith("pzod:Order:conform");
+    });
+    it("increments violate count and records violation when schema fails", () => {
+        const schema = progressive("Order", z.object({ id: z.string() }));
+        schema.parse({ id: 123 });
+        expect(mockRedis.incr).toHaveBeenCalledWith("pzod:Order:violate");
+        expect(mockPipeline.lpush).toHaveBeenCalledWith("pzod:Order:violations", JSON.stringify({ id: 123 }));
+    });
+    it("treats no-schema as violate", () => {
+        const schema = progressive("Unknown");
+        schema.parse({ a: 1 });
+        expect(mockRedis.incr).toHaveBeenCalledWith("pzod:Unknown:violate");
+    });
+});

package/dist/cli/commands/infer.d.ts

@@ -0,0 +1 @@
+export declare function inferCommand(name: string): Promise<void>;

package/dist/cli/commands/infer.js

@@ -0,0 +1,26 @@
+import { getRedis, getConfig, disconnectRedis } from "../../redis-client";
+import { inferSchema } from "../../infer-schema";
+import { schemaToCode } from "../../schema-to-code";
+export async function inferCommand(name) {
+    const redis = getRedis();
+    const { keyPrefix } = getConfig();
+    const items = await redis.lrange(`${keyPrefix}${name}:samples`, 0, -1);
+    if (items.length === 0) {
+        console.log(`No samples recorded for "${name}".`);
+        await disconnectRedis();
+        return;
+    }
+    const samples = items.map((item) => {
+        try {
+            return JSON.parse(item);
+        }
+        catch {
+            return item;
+        }
+    });
+    const schema = inferSchema(samples);
+    const code = schemaToCode(schema);
+    console.log(`Inferred schema for "${name}" (from ${samples.length} samples):\n`);
+    console.log(`const ${name} = ${code};`);
+    await disconnectRedis();
+}

package/dist/cli/commands/list.d.ts

@@ -0,0 +1 @@
+export declare function listCommand(): Promise<void>;

package/dist/cli/commands/list.js

@@ -0,0 +1,16 @@
+import { getRedis, getConfig, disconnectRedis } from "../../redis-client";
+export async function listCommand() {
+    const redis = getRedis();
+    const { keyPrefix } = getConfig();
+    const names = await redis.smembers(`${keyPrefix}names`);
+    if (names.length === 0) {
+        console.log("No monitored types found.");
+    }
+    else {
+        console.log("Monitored types:\n");
+        for (const name of names.sort()) {
+            console.log(`  - ${name}`);
+        }
+    }
+    await disconnectRedis();
+}

package/dist/cli/commands/stats.d.ts

@@ -0,0 +1 @@
+export declare function statsCommand(name: string): Promise<void>;

package/dist/cli/commands/stats.js

@@ -0,0 +1,19 @@
+import { getRedis, getConfig, disconnectRedis } from "../../redis-client";
+export async function statsCommand(name) {
+    const redis = getRedis();
+    const { keyPrefix } = getConfig();
+    const prefix = `${keyPrefix}${name}`;
+    const [conform, violate] = await Promise.all([
+        redis.get(`${prefix}:conform`),
+        redis.get(`${prefix}:violate`),
+    ]);
+    console.log(`Stats for "${name}":\n`);
+    console.log(`  Conform:  ${conform ?? 0}`);
+    console.log(`  Violate:  ${violate ?? 0}`);
+    const total = Number(conform ?? 0) + Number(violate ?? 0);
+    if (total > 0) {
+        const pct = ((Number(conform ?? 0) / total) * 100).toFixed(1);
+        console.log(`  Rate:     ${pct}% conforming`);
+    }
+    await disconnectRedis();
+}

package/dist/cli/commands/violations.d.ts

@@ -0,0 +1,3 @@
+export declare function violationsCommand(name: string, options: {
+    limit?: string;
+}): Promise<void>;

package/dist/cli/commands/violations.js

@@ -0,0 +1,23 @@
+import { getRedis, getConfig, disconnectRedis } from "../../redis-client";
+export async function violationsCommand(name, options) {
+    const redis = getRedis();
+    const { keyPrefix } = getConfig();
+    const limit = Number(options.limit) || 10;
+    const items = await redis.lrange(`${keyPrefix}${name}:violations`, 0, limit - 1);
+    if (items.length === 0) {
+        console.log(`No violations recorded for "${name}".`);
+    }
+    else {
+        console.log(`Recent violations for "${name}" (${items.length}):\n`);
+        for (const item of items) {
+            try {
+                console.log(JSON.stringify(JSON.parse(item), null, 2));
+            }
+            catch {
+                console.log(item);
+            }
+            console.log();
+        }
+    }
+    await disconnectRedis();
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { listCommand } from "./commands/list";
+import { statsCommand } from "./commands/stats";
+import { violationsCommand } from "./commands/violations";
+import { inferCommand } from "./commands/infer";
+const program = new Command();
+program
+    .name("progressive-zod")
+    .description("Runtime type observability for TypeScript")
+    .version("1.0.0");
+program
+    .command("list")
+    .description("List all monitored types")
+    .action(listCommand);
+program
+    .command("stats <name>")
+    .description("Show conform/violate counts for a type")
+    .action(statsCommand);
+program
+    .command("violations <name>")
+    .description("Show non-conforming payloads for a type")
+    .option("-l, --limit <n>", "Number of violations to show", "10")
+    .action(violationsCommand);
+program
+    .command("infer <name>")
+    .description("Suggest a zod schema from observed data")
+    .action(inferCommand);
+program.parse();

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { inferSchema } from "./infer-schema";
+export { progressive } from "./progressive";
+export { configure } from "./redis-client";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { inferSchema } from "./infer-schema";
+export { progressive } from "./progressive";
+export { configure } from "./redis-client";

package/dist/infer-schema.d.ts

@@ -0,0 +1,5 @@
+import { z } from "zod/v4";
+/**
+ * Infer a zod schema from observed sample objects.
+ */
+export declare function inferSchema(samples: unknown[]): z.ZodTypeAny;

package/dist/infer-schema.js

@@ -0,0 +1,176 @@
+import { z } from "zod/v4";
+/**
+ * Compute a deep shape signature that includes nested object structures.
+ */
+function shapeSignature(obj) {
+    const keys = Object.keys(obj).sort();
+    return keys
+        .map((k) => {
+        const v = obj[k];
+        if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+            return `${k}:{${shapeSignature(v)}}`;
+        }
+        return k;
+    })
+        .join(",");
+}
+/**
+ * Infer a zod type for a single field from observed values.
+ */
+function inferFieldType(values) {
+    const types = new Set();
+    const nestedObjects = [];
+    const arrayElements = [];
+    for (const v of values) {
+        if (v === null) {
+            types.add("null");
+        }
+        else if (Array.isArray(v)) {
+            types.add("array");
+            arrayElements.push(...v);
+        }
+        else if (typeof v === "object") {
+            types.add("object");
+            nestedObjects.push(v);
+        }
+        else {
+            types.add(typeof v);
+        }
+    }
+    const schemas = [];
+    if (types.has("string"))
+        schemas.push(z.string());
+    if (types.has("number"))
+        schemas.push(z.number());
+    if (types.has("boolean"))
+        schemas.push(z.boolean());
+    if (types.has("null"))
+        schemas.push(z.null());
+    if (types.has("object"))
+        schemas.push(inferSchema(nestedObjects));
+    if (types.has("array")) {
+        if (arrayElements.length > 0) {
+            schemas.push(z.array(inferFieldType(arrayElements)));
+        }
+        else {
+            schemas.push(z.array(z.unknown()));
+        }
+    }
+    if (schemas.length === 1)
+        return schemas[0];
+    return z.union(schemas);
+}
+/**
+ * Build a strict z.object from a group of samples that share the same shape.
+ */
+function buildObjectSchema(samples) {
+    if (samples.length === 0)
+        return z.strictObject({});
+    const keys = Object.keys(samples[0]).sort();
+    const shape = {};
+    for (const key of keys) {
+        const values = samples.map((s) => s[key]);
+        shape[key] = inferFieldType(values);
+    }
+    return z.strictObject(shape);
+}
+/**
+ * Find a discriminator key across all samples: a key present in every sample
+ * where each unique string value maps to a distinct variant.
+ */
+function findDiscriminatorAcrossSamples(objects) {
+    if (objects.length < 2)
+        return null;
+    const candidateKeys = Object.keys(objects[0]);
+    for (const key of candidateKeys) {
+        // All samples must have this key with a string value
+        let valid = true;
+        const valueToSamples = new Map();
+        for (const obj of objects) {
+            const val = obj[key];
+            if (typeof val !== "string") {
+                valid = false;
+                break;
+            }
+            const group = valueToSamples.get(val);
+            if (group) {
+                group.push(obj);
+            }
+            else {
+                valueToSamples.set(val, [obj]);
+            }
+        }
+        if (!valid)
+            continue;
+        // Need at least 2 distinct values to be a discriminator
+        if (valueToSamples.size < 2)
+            continue;
+        // Each value must be constant within its group (it is by construction)
+        // and values must be distinct across groups (they are by Map keys)
+        return key;
+    }
+    return null;
+}
+/**
+ * Build a discriminated union from samples grouped by discriminator value.
+ */
+function buildDiscriminatedUnion(discriminator, objects) {
+    const valueToSamples = new Map();
+    for (const obj of objects) {
+        const val = obj[discriminator];
+        const group = valueToSamples.get(val);
+        if (group) {
+            group.push(obj);
+        }
+        else {
+            valueToSamples.set(val, [obj]);
+        }
+    }
+    const options = [...valueToSamples.entries()].map(([discValue, groupSamples]) => {
+        const keys = Object.keys(groupSamples[0]).sort();
+        const shape = {};
+        for (const key of keys) {
+            if (key === discriminator) {
+                shape[key] = z.literal(discValue);
+            }
+            else {
+                const values = groupSamples.map((s) => s[key]);
+                shape[key] = inferFieldType(values);
+            }
+        }
+        return z.strictObject(shape);
+    });
+    return z.discriminatedUnion(discriminator, options);
+}
+/**
+ * Infer a zod schema from observed sample objects.
+ */
+export function inferSchema(samples) {
+    const objects = samples.filter((s) => s !== null && typeof s === "object" && !Array.isArray(s));
+    if (objects.length === 0)
+        return z.unknown();
+    // Group by shape signature (deep, including nested object structures)
+    const groups = new Map();
+    for (const obj of objects) {
+        const sig = shapeSignature(obj);
+        const group = groups.get(sig);
+        if (group) {
+            group.push(obj);
+        }
+        else {
+            groups.set(sig, [obj]);
+        }
+    }
+    // Single group → single object schema
+    if (groups.size === 1) {
+        return buildObjectSchema([...groups.values()][0]);
+    }
+    // Multiple groups — check for discriminator across all samples
+    const discriminator = findDiscriminatorAcrossSamples(objects);
+    if (discriminator) {
+        return buildDiscriminatedUnion(discriminator, objects);
+    }
+    // Multiple groups, no discriminator → plain union
+    const options = [...groups.values()].map((groupSamples) => buildObjectSchema(groupSamples));
+    return z.union(options);
+}

package/dist/progressive.d.ts

@@ -0,0 +1,3 @@
+import { z } from "zod/v4";
+import type { ProgressiveSchema } from "./types";
+export declare function progressive(name: string, schema?: z.ZodTypeAny): ProgressiveSchema;

package/dist/progressive.js

@@ -0,0 +1,48 @@
+import { getRedis, getConfig } from "./redis-client";
+export function progressive(name, schema) {
+    return {
+        name,
+        parse(input) {
+            const redis = getRedis();
+            const { keyPrefix, maxViolations, maxSamples } = getConfig();
+            const prefix = `${keyPrefix}${name}`;
+            // Fire-and-forget: register name
+            redis.sadd(`${keyPrefix}names`, name).catch(() => { });
+            // Fire-and-forget: record sample
+            const serialized = JSON.stringify(input);
+            redis
+                .pipeline()
+                .lpush(`${prefix}:samples`, serialized)
+                .ltrim(`${prefix}:samples`, 0, maxSamples - 1)
+                .exec()
+                .catch(() => { });
+            if (schema) {
+                const result = schema.safeParse(input);
+                if (result.success) {
+                    redis.incr(`${prefix}:conform`).catch(() => { });
+                }
+                else {
+                    redis.incr(`${prefix}:violate`).catch(() => { });
+                    redis
+                        .pipeline()
+                        .lpush(`${prefix}:violations`, serialized)
+                        .ltrim(`${prefix}:violations`, 0, maxViolations - 1)
+                        .exec()
+                        .catch(() => { });
+                }
+            }
+            else {
+                // No schema — everything is a violation
+                redis.incr(`${prefix}:violate`).catch(() => { });
+                redis
+                    .pipeline()
+                    .lpush(`${prefix}:violations`, serialized)
+                    .ltrim(`${prefix}:violations`, 0, maxViolations - 1)
+                    .exec()
+                    .catch(() => { });
+            }
+            // Always return input unchanged, never throw
+            return input;
+        },
+    };
+}

package/dist/redis-client.d.ts

@@ -0,0 +1,6 @@
+import Redis from "ioredis";
+import type { ProgressiveConfig } from "./types";
+export declare function configure(opts: ProgressiveConfig): void;
+export declare function getConfig(): Required<ProgressiveConfig>;
+export declare function getRedis(): Redis;
+export declare function disconnectRedis(): Promise<void>;

package/dist/redis-client.js

@@ -0,0 +1,48 @@
+import Redis from "ioredis";
+let client = null;
+let config = {};
+export function configure(opts) {
+    config = { ...config, ...opts };
+    // Reset client so next access picks up new config
+    if (client) {
+        client.disconnect();
+        client = null;
+    }
+}
+export function getConfig() {
+    return {
+        redisUrl: config.redisUrl ??
+            process.env.PROGRESSIVE_ZOD_REDIS_URL ??
+            "redis://localhost:6379",
+        keyPrefix: config.keyPrefix ??
+            process.env.PROGRESSIVE_ZOD_KEY_PREFIX ??
+            "pzod:",
+        maxViolations: config.maxViolations ??
+            (Number(process.env.PROGRESSIVE_ZOD_MAX_VIOLATIONS) || 1000),
+        maxSamples: config.maxSamples ??
+            (Number(process.env.PROGRESSIVE_ZOD_MAX_SAMPLES) || 1000),
+    };
+}
+export function getRedis() {
+    if (!client) {
+        const { redisUrl } = getConfig();
+        client = new Redis(redisUrl, { lazyConnect: true, maxRetriesPerRequest: 1 });
+        client.on("error", (err) => {
+            if (process.env.PROGRESSIVE_ZOD_DEBUG) {
+                console.error("[progressive-zod] Redis error:", err.message);
+            }
+        });
+        client.connect().catch(() => {
+            // swallow — fire-and-forget
+        });
+    }
+    return client;
+}
+export function disconnectRedis() {
+    if (client) {
+        const c = client;
+        client = null;
+        return c.quit().then(() => { });
+    }
+    return Promise.resolve();
+}

package/dist/schema-to-code.d.ts

@@ -0,0 +1,5 @@
+import { z } from "zod/v4";
+/**
+ * Serialize a zod schema to a TypeScript code string.
+ */
+export declare function schemaToCode(schema: z.ZodTypeAny, indent?: number): string;