@mcp-web/decompose-zod-schema 0.1.0

package/dist/utils.js

@@ -0,0 +1,161 @@
+import { ZodEnum, ZodObject, z } from 'zod';
+// Path utilities - simple and dependency-free
+export const setNestedValue = (obj, path, value) => {
+    const keys = path.split('.');
+    let current = obj;
+    for (let i = 0; i < keys.length - 1; i++) {
+        const key = keys[i];
+        if (!(key in current) ||
+            typeof current[key] !== 'object' ||
+            current[key] === null) {
+            current[key] = {};
+        }
+        current = current[key];
+    }
+    current[keys[keys.length - 1]] = value;
+};
+// Custom even chunking function for optimal distribution
+export const evenChunk = (array, maxChunkSize) => {
+    if (array.length <= maxChunkSize)
+        return [array];
+    const numChunks = Math.ceil(array.length / maxChunkSize);
+    const evenChunkSize = Math.ceil(array.length / numChunks);
+    const chunks = [];
+    for (let i = 0; i < array.length; i += evenChunkSize) {
+        chunks.push(array.slice(i, i + evenChunkSize));
+    }
+    return chunks;
+};
+// Parse split notation including enum splits, array splits, and record splits
+export const parseEnumSplit = (item) => {
+    // Handle nested array split notation: 'views[].tracks.top[]'
+    // This matches patterns where we have array splits within array splits
+    const nestedArrayMatch = item.match(/^(.+)\[\]\.(.+)\[\]$/);
+    if (nestedArrayMatch) {
+        const [, basePath, subPath] = nestedArrayMatch;
+        // For validation, we need to check if the base path exists as an array
+        // and if the subPath exists within the array element schema
+        return { path: `${basePath}.${subPath}`, isArraySplit: true };
+    }
+    // Handle simple array split notation: 'views[]'
+    const arrayMatch = item.match(/^(.+)\[\]$/);
+    if (arrayMatch) {
+        const [, path] = arrayMatch;
+        return { path, isArraySplit: true };
+    }
+    // Handle record split notation: 'configs{}'
+    const recordMatch = item.match(/^(.+)\{\}$/);
+    if (recordMatch) {
+        const [, path] = recordMatch;
+        return { path, isRecordSplit: true };
+    }
+    // Handle chunk size notation: 'category[50]'
+    const chunkMatch = item.match(/^(.+)\[(\d+)\]$/);
+    if (chunkMatch) {
+        const [, path, chunkSizeStr] = chunkMatch;
+        return { path, chunkSize: parseInt(chunkSizeStr, 10) };
+    }
+    // Handle full slice notation: 'category[10:20]' or 'category[-5:10]'
+    const fullSliceMatch = item.match(/^(.+)\[(-?\d+):(-?\d+)\]$/);
+    if (fullSliceMatch) {
+        const [, path, startStr, endStr] = fullSliceMatch;
+        return { path, start: parseInt(startStr, 10), end: parseInt(endStr, 10) };
+    }
+    // Handle slice from index to end: 'category[10:]' or 'category[-5:]'
+    const fromIndexMatch = item.match(/^(.+)\[(-?\d+):\]$/);
+    if (fromIndexMatch) {
+        const [, path, startStr] = fromIndexMatch;
+        return { path, start: parseInt(startStr, 10), end: undefined };
+    }
+    // Handle slice from start to index: 'category[:20]' or 'category[:-5]'
+    const toIndexMatch = item.match(/^(.+)\[:(-?\d+)\]$/);
+    if (toIndexMatch) {
+        const [, path, endStr] = toIndexMatch;
+        return { path, start: 0, end: parseInt(endStr, 10) };
+    }
+    // Handle entire enum slice: 'category[:]'
+    const entireMatch = item.match(/^(.+)\[:\]$/);
+    if (entireMatch) {
+        const [, path] = entireMatch;
+        return { path, start: 0, end: undefined };
+    }
+    // Regular path
+    return { path: item };
+};
+// Extract schema at a given path
+export const getSchemaAtPath = (schema, path) => {
+    const parts = path.split('.');
+    let current = schema;
+    for (const part of parts) {
+        if (current instanceof ZodObject) {
+            const shape = current.shape;
+            current = shape[part];
+            if (!current)
+                return undefined;
+        }
+        else {
+            return undefined;
+        }
+    }
+    return current;
+};
+// Create a schema with only specified paths
+export const extractSchemaForPaths = (originalSchema, paths) => {
+    const shape = {};
+    for (const path of paths) {
+        const parsedPath = parseEnumSplit(path);
+        const schema = getSchemaAtPath(originalSchema, parsedPath.path);
+        if (!schema)
+            continue;
+        // Handle enum splitting
+        if (schema instanceof ZodEnum &&
+            (parsedPath.chunkSize || parsedPath.start !== undefined)) {
+            const enumOptions = schema.options;
+            if (parsedPath.chunkSize) {
+                // For chunk size, we don't handle it in extractSchemaForPaths - that's done in manual-decompose
+                // This should not happen in normal usage as chunks generate multiple schemas
+                // Skip this path and continue with regular schema extraction
+            }
+            else if (parsedPath.start !== undefined) {
+                // Handle slice notation with optional end
+                const end = parsedPath.end !== undefined ? parsedPath.end : enumOptions.length;
+                const slicedOptions = enumOptions.slice(parsedPath.start, end);
+                if (slicedOptions.length > 0) {
+                    setNestedValue(shape, parsedPath.path, z.enum(slicedOptions));
+                }
+            }
+        }
+        else {
+            // Handle regular schema extraction
+            setNestedValue(shape, parsedPath.path, schema);
+        }
+    }
+    return z.object(shape);
+};
+// Estimate tokens in a schema (rough approximation)
+export const estimateTokensByJsonSchema = (schema) => {
+    try {
+        const jsonSchema = z.toJSONSchema(schema);
+        const schemaString = JSON.stringify(jsonSchema);
+        return Math.ceil(schemaString.length / 3.5);
+    }
+    catch {
+        // Fallback for schemas that can't be converted
+        return 100;
+    }
+};
+/**
+ * Helper function to create conditional enum splits based on enum size
+ */
+export function conditionalEnumSplit(path, maxSize, schema) {
+    const enumSchema = getSchemaAtPath(schema, path);
+    if (!(enumSchema instanceof ZodEnum)) {
+        return [path]; // Not an enum, return as regular path
+    }
+    const enumOptions = enumSchema.options;
+    if (enumOptions.length <= maxSize) {
+        return [path]; // Small enough, no split needed
+    }
+    // Return chunk notation
+    return [`${path}[${maxSize}]`];
+}

package/dist/validate.d.ts

@@ -0,0 +1,9 @@
+import { type ZodObject, type ZodType } from 'zod';
+import type { SplitPlan } from './types.js';
+export declare const validatePlan: (plan: SplitPlan, schema: ZodObject<Record<string, ZodType>>) => string[];
+export declare const validateSliceCompleteness: (enumPath: string, slices: Array<{
+    start: number;
+    end: number;
+    item: string;
+}>, enumLength: number) => string[];
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI5C,eAAO,MAAM,YAAY,GACvB,MAAM,SAAS,EACf,QAAQ,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KACzC,MAAM,EAyHR,CAAC;AAGF,eAAO,MAAM,yBAAyB,GACpC,UAAU,MAAM,EAChB,QAAQ,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAC3D,YAAY,MAAM,KACjB,MAAM,EA4CR,CAAC"}

package/dist/validate.js

@@ -0,0 +1,134 @@
+import { ZodEnum } from 'zod';
+import { getSchemaAtPath, parseEnumSplit } from './utils.js';
+// Validate that a split plan is structurally correct
+export const validatePlan = (plan, schema) => {
+    const errors = [];
+    const enumSlices = new Map();
+    for (const item of plan) {
+        const parsed = parseEnumSplit(item);
+        // Handle nested array validation (e.g., 'views[].tracks.top[]')
+        if (parsed.isArraySplit && item.includes('[].')) {
+            const nestedMatch = item.match(/^(.+)\[\]\.(.+)\[\]$/);
+            if (nestedMatch) {
+                const [, basePath, subPath] = nestedMatch;
+                // Check if the base path exists and is an array
+                const baseSchema = getSchemaAtPath(schema, basePath);
+                if (!baseSchema) {
+                    errors.push(`Base path '${basePath}' does not exist in schema`);
+                    continue;
+                }
+                // For array schemas, we need to check the element schema
+                if ('element' in baseSchema && baseSchema.element) {
+                    const elementSchema = baseSchema.element;
+                    if (elementSchema && typeof elementSchema === 'object' && 'shape' in elementSchema) {
+                        const subSchemaAtPath = getSchemaAtPath(elementSchema, subPath);
+                        if (!subSchemaAtPath) {
+                            errors.push(`Sub-path '${subPath}' does not exist in array element schema at '${basePath}'`);
+                            continue;
+                        }
+                        // Unwrap optional schemas to get to the inner array
+                        let actualSubSchema = subSchemaAtPath;
+                        if (subSchemaAtPath && typeof subSchemaAtPath === 'object' && 'unwrap' in subSchemaAtPath) {
+                            actualSubSchema = subSchemaAtPath.unwrap();
+                        }
+                        // Check if the sub-path is also an array (for the final [])
+                        if (!actualSubSchema || typeof actualSubSchema !== 'object' || !('element' in actualSubSchema) || !actualSubSchema.element) {
+                            errors.push(`Sub-path '${subPath}' at '${basePath}' is not an array schema`);
+                            continue;
+                        }
+                    }
+                    else {
+                        errors.push(`Array element at '${basePath}' is not an object schema`);
+                        continue;
+                    }
+                }
+                else {
+                    errors.push(`Path '${basePath}' is not an array schema`);
+                    continue;
+                }
+            }
+        }
+        // Get schema at path for all non-nested array items
+        let schemaAtPath;
+        if (!(parsed.isArraySplit && item.includes('[].'))) {
+            schemaAtPath = getSchemaAtPath(schema, parsed.path);
+            if (!schemaAtPath) {
+                errors.push(`Path '${parsed.path}' does not exist in schema`);
+                continue;
+            }
+        }
+        // Validate enum split notation
+        if (parsed.chunkSize || parsed.start !== undefined) {
+            if (!schemaAtPath || !(schemaAtPath instanceof ZodEnum)) {
+                errors.push(`Path '${parsed.path}' is not an enum but has enum split notation`);
+                continue;
+            }
+            const enumOptions = schemaAtPath.options;
+            if (parsed.chunkSize) {
+                if (parsed.chunkSize <= 0) {
+                    errors.push(`Chunk size must be positive for '${parsed.path}[${parsed.chunkSize}]'`);
+                }
+            }
+            else if (parsed.start !== undefined) {
+                const end = parsed.end !== undefined ? parsed.end : enumOptions.length;
+                // Validate slice bounds
+                if (parsed.start < 0) {
+                    errors.push(`Start index cannot be negative in '${item}'`);
+                }
+                if (end > enumOptions.length) {
+                    errors.push(`End index ${end} exceeds enum length ${enumOptions.length} in '${item}'`);
+                }
+                if (parsed.start >= end) {
+                    errors.push(`Start index must be less than end index in '${item}'`);
+                }
+                // Track slices for completeness validation
+                if (!enumSlices.has(parsed.path)) {
+                    enumSlices.set(parsed.path, []);
+                }
+                const slicesArray = enumSlices.get(parsed.path);
+                if (slicesArray) {
+                    slicesArray.push({ start: parsed.start, end, item });
+                }
+            }
+        }
+    }
+    // Validate slice completeness for each enum path
+    for (const [enumPath, slices] of enumSlices) {
+        const schemaAtPath = getSchemaAtPath(schema, enumPath);
+        if (!(schemaAtPath instanceof ZodEnum))
+            continue;
+        const enumLength = schemaAtPath.options.length;
+        const sliceErrors = validateSliceCompleteness(enumPath, slices, enumLength);
+        errors.push(...sliceErrors);
+    }
+    return errors;
+};
+// Validate that slices for an enum are complete (no gaps, no overlaps)
+export const validateSliceCompleteness = (enumPath, slices, enumLength) => {
+    const errors = [];
+    // Sort slices by start index
+    const sortedSlices = [...slices].sort((a, b) => a.start - b.start);
+    // Check for overlaps and gaps
+    let expectedStart = 0;
+    for (let i = 0; i < sortedSlices.length; i++) {
+        const slice = sortedSlices[i];
+        // Check for gap
+        if (slice.start > expectedStart) {
+            errors.push(`Gap in enum slices for '${enumPath}': missing range [${expectedStart}:${slice.start}]`);
+        }
+        // Check for overlap with previous slice
+        if (slice.start < expectedStart) {
+            errors.push(`Overlapping enum slices for '${enumPath}': '${slice.item}' overlaps with previous slice`);
+        }
+        expectedStart = slice.end;
+    }
+    // Check if we covered the entire enum
+    if (expectedStart < enumLength) {
+        errors.push(`Incomplete enum slices for '${enumPath}': missing range [${expectedStart}:${enumLength}]`);
+    }
+    // Check if we went beyond the enum length
+    if (expectedStart > enumLength) {
+        errors.push(`Enum slices for '${enumPath}' extend beyond enum length ${enumLength}`);
+    }
+    return errors;
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@mcp-web/decompose-zod-schema",
+  "version": "0.1.0",
+  "description": "Utility for decomposing large Zod schemas into smaller, manageable sub-schemas with partial update support",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "@mcp-web/decompose-zod-schema": "./dist/cli.js"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "immer": "^10.1.1",
+    "zod": "~4.1.12"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "tsx": "^4.16.0",
+    "typescript": "~5.9.3"
+  },
+  "keywords": [
+    "zod",
+    "schema",
+    "decomposition",
+    "validation",
+    "typescript",
+    "partial-updates"
+  ],
+  "author": "MCP Frontend Integration System",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "cli": "tsx src/cli.ts",
+    "example": "tsx src/cli.ts -i examples/example-schema.ts -s userSchema -v"
+  }
+}