@mcp-web/core 0.1.0

package/dist/expanded-schema-tools/schema-analysis.js

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+import { isKeyField, unwrapSchema } from './schema-helpers.js';
+/**
+ * Analyzes a schema to determine its shape characteristics.
+ */
+export function analyzeSchemaShape(schema) {
+    const unwrapped = unwrapSchema(schema);
+    // Default result
+    const result = {
+        type: 'unsupported',
+        subtype: 'unknown',
+        hasOptionalFields: false,
+        optionalPaths: [],
+        fixedPaths: [],
+        dynamicPaths: [],
+    };
+    if (unwrapped instanceof z.ZodString ||
+        unwrapped instanceof z.ZodNumber ||
+        unwrapped instanceof z.ZodBoolean ||
+        unwrapped instanceof z.ZodLiteral ||
+        unwrapped instanceof z.ZodEnum) {
+        result.type = 'fixed';
+        result.subtype = 'primitive';
+        return result;
+    }
+    if (unwrapped instanceof z.ZodTuple) {
+        result.type = 'fixed';
+        result.subtype = 'tuple';
+        return result;
+    }
+    if (unwrapped instanceof z.ZodArray) {
+        result.type = 'dynamic';
+        result.subtype = 'array';
+        return result;
+    }
+    if (unwrapped instanceof z.ZodRecord) {
+        result.type = 'dynamic';
+        result.subtype = 'record';
+        return result;
+    }
+    // Objects - analyze further
+    if (unwrapped instanceof z.ZodObject) {
+        result.subtype = 'object';
+        const shape = unwrapped.shape;
+        for (const [key, field] of Object.entries(shape)) {
+            const zodField = field;
+            const unwrappedField = unwrapSchema(zodField);
+            // Check for optional fields
+            if (zodField instanceof z.ZodOptional) {
+                result.hasOptionalFields = true;
+                result.optionalPaths.push(key);
+            }
+            // Check if field is dynamic (array or record)
+            if (unwrappedField instanceof z.ZodArray || unwrappedField instanceof z.ZodRecord) {
+                result.dynamicPaths.push(key);
+            }
+            else {
+                result.fixedPaths.push(key);
+            }
+        }
+        // Determine object type
+        if (result.dynamicPaths.length > 0 && result.fixedPaths.length > 0) {
+            result.type = 'mixed';
+        }
+        else if (result.dynamicPaths.length > 0) {
+            result.type = 'dynamic';
+        }
+        else {
+            result.type = 'fixed';
+        }
+        return result;
+    }
+    return result;
+}
+/**
+ * Detects the ID field in an object schema.
+ * Returns information about explicit id() markers.
+ * Throws an error if multiple id() markers are found.
+ */
+export function findIdField(schema) {
+    const shape = schema.shape;
+    let explicitKey = null;
+    for (const [name, field] of Object.entries(shape)) {
+        if (isKeyField(field)) {
+            // Error if multiple id() markers
+            if (explicitKey) {
+                throw new Error(`Multiple fields marked with id(): '${explicitKey}' and '${name}'.\n` +
+                    `Only one field can be the ID. For compound keys, use index-based addressing.`);
+            }
+            explicitKey = name;
+        }
+    }
+    if (explicitKey) {
+        return { type: 'explicit', field: explicitKey };
+    }
+    // No id() marker → use index-based addressing
+    return { type: 'none' };
+}
+/**
+ * Validates that a schema only uses supported types.
+ * Throws an error if unsupported types are found.
+ */
+export function validateSupportedTypes(schema, path = 'root') {
+    const errors = [];
+    const unwrapped = unwrapSchema(schema);
+    const supported = [
+        z.ZodObject,
+        z.ZodArray,
+        z.ZodRecord,
+        z.ZodString,
+        z.ZodNumber,
+        z.ZodBoolean,
+        z.ZodLiteral,
+        z.ZodEnum,
+        z.ZodTuple,
+        z.ZodDate,
+        z.ZodBigInt,
+        z.ZodNull,
+        z.ZodUndefined,
+    ];
+    const isSupported = supported.some((type) => unwrapped instanceof type);
+    if (!isSupported) {
+        errors.push(`Unsupported type at '${path}': ${unwrapped.constructor.name}`);
+    }
+    // Recurse for nested schemas
+    if (unwrapped instanceof z.ZodObject) {
+        for (const [key, field] of Object.entries(unwrapped.shape)) {
+            errors.push(...validateSupportedTypes(field, `${path}.${key}`));
+        }
+    }
+    else if (unwrapped instanceof z.ZodArray) {
+        errors.push(...validateSupportedTypes(unwrapped.element, `${path}[]`));
+    }
+    else if (unwrapped instanceof z.ZodRecord) {
+        const def = unwrapped._def;
+        const valueType = def.valueType;
+        if (valueType) {
+            errors.push(...validateSupportedTypes(valueType, `${path}{}`));
+        }
+    }
+    return errors;
+}

package/dist/expanded-schema-tools/schema-analysis.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=schema-analysis.test.d.ts.map

package/dist/expanded-schema-tools/schema-analysis.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-analysis.test.d.ts","sourceRoot":"","sources":["../../src/expanded-schema-tools/schema-analysis.test.ts"],"names":[],"mappings":""}

package/dist/expanded-schema-tools/schema-analysis.test.js

@@ -0,0 +1,314 @@
+import { expect, test } from 'bun:test';
+import { z } from 'zod';
+import { analyzeSchemaShape, findIdField, validateSupportedTypes, } from './schema-analysis.js';
+import { id } from './schema-helpers.js';
+// ============================================================================
+// Shape Detection - Primitives
+// ============================================================================
+test('analyzeSchemaShape() - string is fixed primitive', () => {
+    const schema = z.string();
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.type).toBe('fixed');
+    expect(shape.subtype).toBe('primitive');
+});
+test('analyzeSchemaShape() - number is fixed primitive', () => {
+    const schema = z.number();
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.type).toBe('fixed');
+    expect(shape.subtype).toBe('primitive');
+});
+test('analyzeSchemaShape() - boolean is fixed primitive', () => {
+    const schema = z.boolean();
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.type).toBe('fixed');
+    expect(shape.subtype).toBe('primitive');
+});
+test('analyzeSchemaShape() - enum is fixed primitive', () => {
+    const schema = z.enum(['light', 'dark', 'system']);
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.type).toBe('fixed');
+    expect(shape.subtype).toBe('primitive');
+});
+test('analyzeSchemaShape() - literal is fixed primitive', () => {
+    const schema = z.literal('constant');
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.type).toBe('fixed');
+    expect(shape.subtype).toBe('primitive');
+});
+// ============================================================================
+// Shape Detection - Collections
+// ============================================================================
+test('analyzeSchemaShape() - array is dynamic', () => {
+    const schema = z.array(z.string());
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.type).toBe('dynamic');
+    expect(shape.subtype).toBe('array');
+});
+test('analyzeSchemaShape() - record is dynamic', () => {
+    const schema = z.record(z.string(), z.number());
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.type).toBe('dynamic');
+    expect(shape.subtype).toBe('record');
+});
+test('analyzeSchemaShape() - tuple is fixed', () => {
+    const schema = z.tuple([z.string(), z.number(), z.boolean()]);
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.type).toBe('fixed');
+    expect(shape.subtype).toBe('tuple');
+});
+// ============================================================================
+// Shape Detection - Objects
+// ============================================================================
+test('analyzeSchemaShape() - object with only fixed props is fixed', () => {
+    const schema = z.object({
+        name: z.string(),
+        age: z.number(),
+        active: z.boolean(),
+    });
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.type).toBe('fixed');
+    expect(shape.subtype).toBe('object');
+    expect(shape.fixedPaths).toEqual(['name', 'age', 'active']);
+    expect(shape.dynamicPaths).toEqual([]);
+});
+test('analyzeSchemaShape() - object with only dynamic props is dynamic', () => {
+    const schema = z.object({
+        todos: z.array(z.string()),
+        projects: z.record(z.string(), z.object({ name: z.string() })),
+    });
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.type).toBe('dynamic');
+    expect(shape.subtype).toBe('object');
+    expect(shape.fixedPaths).toEqual([]);
+    expect(shape.dynamicPaths).toEqual(['todos', 'projects']);
+});
+test('analyzeSchemaShape() - object with mixed props is mixed', () => {
+    const schema = z.object({
+        name: z.string(),
+        todos: z.array(z.string()),
+        settings: z.object({ theme: z.string() }),
+        projects: z.record(z.string(), z.object({ title: z.string() })),
+    });
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.type).toBe('mixed');
+    expect(shape.subtype).toBe('object');
+    expect(shape.fixedPaths).toContain('name');
+    expect(shape.fixedPaths).toContain('settings');
+    expect(shape.dynamicPaths).toContain('todos');
+    expect(shape.dynamicPaths).toContain('projects');
+});
+// ============================================================================
+// Optional Field Detection
+// ============================================================================
+test('analyzeSchemaShape() - detects optional fields', () => {
+    const schema = z.object({
+        name: z.string(),
+        email: z.string().optional(),
+        age: z.number().optional(),
+    });
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.hasOptionalFields).toBe(true);
+    expect(shape.optionalPaths).toContain('email');
+    expect(shape.optionalPaths).toContain('age');
+    expect(shape.optionalPaths).not.toContain('name');
+});
+test('analyzeSchemaShape() - no optional fields when none present', () => {
+    const schema = z.object({
+        name: z.string(),
+        age: z.number(),
+    });
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.hasOptionalFields).toBe(false);
+    expect(shape.optionalPaths).toEqual([]);
+});
+test('analyzeSchemaShape() - wrapped optional fields (optional before default not detected)', () => {
+    // When optional() comes before default(), the field is wrapped by ZodDefault
+    // So the optional detection doesn't see it (checks the outer ZodDefault, not inner ZodOptional)
+    const schema = z.object({
+        value: z.string().optional().default('hello'),
+    });
+    const shape = analyzeSchemaShape(schema);
+    // This is a limitation - wrapped optionals are not detected
+    expect(shape.hasOptionalFields).toBe(false);
+});
+// ============================================================================
+// Fixed vs Dynamic Path Tracking
+// ============================================================================
+test('analyzeSchemaShape() - fixedPaths contains non-collection fields', () => {
+    const schema = z.object({
+        title: z.string(),
+        count: z.number(),
+        nested: z.object({ value: z.string() }),
+        items: z.array(z.string()),
+    });
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.fixedPaths).toContain('title');
+    expect(shape.fixedPaths).toContain('count');
+    expect(shape.fixedPaths).toContain('nested');
+    expect(shape.fixedPaths).not.toContain('items');
+});
+test('analyzeSchemaShape() - dynamicPaths contains array/record fields', () => {
+    const schema = z.object({
+        name: z.string(),
+        todos: z.array(z.string()),
+        projects: z.record(z.string(), z.object({ title: z.string() })),
+    });
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.dynamicPaths).toContain('todos');
+    expect(shape.dynamicPaths).toContain('projects');
+    expect(shape.dynamicPaths).not.toContain('name');
+});
+test('analyzeSchemaShape() - correctly categorizes nested objects', () => {
+    const schema = z.object({
+        settings: z.object({
+            theme: z.string(),
+            language: z.string(),
+        }),
+    });
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.fixedPaths).toContain('settings');
+    expect(shape.dynamicPaths).not.toContain('settings');
+});
+// ============================================================================
+// ID Field Detection
+// ============================================================================
+test('findIdField() - detects explicit id() marker', () => {
+    const schema = z.object({
+        id: id(z.string()),
+        name: z.string(),
+    });
+    const result = findIdField(schema);
+    expect(result.type).toBe('explicit');
+    expect(result.field).toBe('id');
+});
+test('findIdField() - returns none when no marker', () => {
+    const schema = z.object({
+        id: z.string(),
+        name: z.string(),
+    });
+    const result = findIdField(schema);
+    expect(result.type).toBe('none');
+    expect(result.field).toBeUndefined();
+});
+test('findIdField() - throws error on multiple id() markers', () => {
+    const schema = z.object({
+        id: id(z.string()),
+        userId: id(z.string()),
+        name: z.string(),
+    });
+    expect(() => findIdField(schema)).toThrow();
+});
+test('findIdField() - error message mentions both fields', () => {
+    const schema = z.object({
+        primaryId: id(z.string()),
+        secondaryId: id(z.string()),
+    });
+    try {
+        findIdField(schema);
+        expect(true).toBe(false); // Should not reach here
+    }
+    catch (error) {
+        const message = error.message;
+        expect(message).toContain('primaryId');
+        expect(message).toContain('secondaryId');
+        expect(message).toContain('Multiple');
+    }
+});
+test('findIdField() - error suggests using index-based for compound keys', () => {
+    const schema = z.object({
+        id1: id(z.string()),
+        id2: id(z.string()),
+    });
+    try {
+        findIdField(schema);
+        expect(true).toBe(false); // Should not reach here
+    }
+    catch (error) {
+        const message = error.message;
+        expect(message).toContain('index-based');
+        expect(message).toContain('compound');
+    }
+});
+// ============================================================================
+// Type Validation
+// ============================================================================
+test('validateSupportedTypes() - allows all JSON-compatible types', () => {
+    const schema = z.object({
+        str: z.string(),
+        num: z.number(),
+        bool: z.boolean(),
+        date: z.date(),
+        bigint: z.bigint(),
+        nullValue: z.null(),
+        undefinedValue: z.undefined(),
+        literal: z.literal('constant'),
+        enum: z.enum(['a', 'b']),
+    });
+    const errors = validateSupportedTypes(schema);
+    expect(errors).toEqual([]);
+});
+test('validateSupportedTypes() - detects unsupported types', () => {
+    const schema = z.function();
+    const errors = validateSupportedTypes(schema);
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]).toContain('Unsupported');
+});
+test('validateSupportedTypes() - recurses into nested objects', () => {
+    const schema = z.object({
+        valid: z.string(),
+        nested: z.object({
+            alsoValid: z.number(),
+        }),
+    });
+    const errors = validateSupportedTypes(schema);
+    expect(errors).toEqual([]);
+});
+test('validateSupportedTypes() - checks array elements', () => {
+    const schema = z.array(z.string());
+    const errors = validateSupportedTypes(schema);
+    expect(errors).toEqual([]);
+});
+test('validateSupportedTypes() - checks record values', () => {
+    const schema = z.record(z.string(), z.object({
+        name: z.string(),
+        count: z.number(),
+    }));
+    const errors = validateSupportedTypes(schema);
+    expect(errors).toEqual([]);
+});
+test('validateSupportedTypes() - detects unsupported nested types', () => {
+    const schema = z.object({
+        valid: z.string(),
+        nested: z.object({
+            invalid: z.function(),
+        }),
+    });
+    const errors = validateSupportedTypes(schema);
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]).toContain('nested.invalid');
+});
+// ============================================================================
+// Wrapped Schema Handling
+// ============================================================================
+test('analyzeSchemaShape() - handles wrapped schemas (default, optional, nullable)', () => {
+    const schema = z.object({
+        withDefault: z.string().default('hello'),
+        withOptional: z.number().optional(),
+        withNullable: z.boolean().nullable(),
+    });
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.type).toBe('fixed');
+    expect(shape.subtype).toBe('object');
+});
+test('analyzeSchemaShape() - unwraps arrays with defaults', () => {
+    const schema = z.array(z.string()).default([]);
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.type).toBe('dynamic');
+    expect(shape.subtype).toBe('array');
+});
+test('analyzeSchemaShape() - unwraps records with defaults', () => {
+    const schema = z.record(z.string(), z.number()).default({});
+    const shape = analyzeSchemaShape(schema);
+    expect(shape.type).toBe('dynamic');
+    expect(shape.subtype).toBe('record');
+});

package/dist/expanded-schema-tools/schema-helpers.d.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+/**
+ * Marks a field as the unique identifier for array elements.
+ * Enables ID-based tools instead of index-based.
+ * Only one field per schema can be marked with id().
+ *
+ * @example
+ * ```typescript
+ * const TodoSchema = z.object({
+ *   id: id(z.string()),
+ *   value: z.string()
+ * });
+ * ```
+ */
+export declare function id<T extends z.ZodTypeAny>(schema: T): T;
+/**
+ * Marks a field as system-generated.
+ * Field is excluded from input schemas (add/set).
+ * MUST have a default() — error thrown otherwise.
+ *
+ * @example
+ * ```typescript
+ * const TodoSchema = z.object({
+ *   id: id(system(z.string().default(() => crypto.randomUUID()))),
+ *   created_at: system(z.number().default(() => Date.now()))
+ * });
+ * ```
+ */
+export declare function system<T extends z.ZodTypeAny>(schema: T): T;
+/**
+ * Checks if a field is marked with id().
+ */
+export declare function isKeyField(field: z.ZodTypeAny): boolean;
+/**
+ * Checks if a field is marked with system().
+ */
+export declare function isSystemField(field: z.ZodTypeAny): boolean;
+/**
+ * Checks if a schema has a default value.
+ */
+export declare function hasDefault(schema: z.ZodTypeAny): boolean;
+/**
+ * Unwraps a schema from ZodDefault, ZodOptional, ZodNullable wrappers.
+ * Returns the innermost schema.
+ */
+export declare function unwrapSchema(schema: z.ZodTypeAny): z.ZodTypeAny;
+/**
+ * Unwraps ZodDefault to get the inner schema.
+ */
+export declare function unwrapDefault(schema: z.ZodTypeAny): z.ZodTypeAny;
+/**
+ * Derives an input schema for add operations.
+ * - system() fields are excluded
+ * - default() fields become optional
+ * - other fields remain required
+ */
+export declare function deriveAddInputSchema(schema: z.ZodObject<z.ZodRawShape>): z.ZodObject<z.ZodRawShape>;
+/**
+ * Derives an input schema for set operations (partial updates).
+ * - system() fields are excluded
+ * - all other fields become optional
+ */
+export declare function deriveSetInputSchema(schema: z.ZodObject<z.ZodRawShape>): z.ZodObject<z.ZodRawShape>;
+/**
+ * Validates that all system() fields have default values.
+ * Throws an error if a system field lacks a default.
+ */
+export declare function validateSystemFields(schema: z.ZodObject<z.ZodRawShape>): void;
+//# sourceMappingURL=schema-helpers.d.ts.map

package/dist/expanded-schema-tools/schema-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-helpers.d.ts","sourceRoot":"","sources":["../../src/expanded-schema-tools/schema-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;GAYG;AACH,wBAAgB,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAGvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAG3D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC,UAAU,GAAG,OAAO,CAEvD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,UAAU,GAAG,OAAO,CAE1D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,OAAO,CASxD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAa/D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAMhE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAiBnG;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAanG;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,IAAI,CAa7E"}

package/dist/expanded-schema-tools/schema-helpers.js

@@ -0,0 +1,139 @@
+import { z } from 'zod';
+/**
+ * Marks a field as the unique identifier for array elements.
+ * Enables ID-based tools instead of index-based.
+ * Only one field per schema can be marked with id().
+ *
+ * @example
+ * ```typescript
+ * const TodoSchema = z.object({
+ *   id: id(z.string()),
+ *   value: z.string()
+ * });
+ * ```
+ */
+export function id(schema) {
+    schema.def.__mcpWebKey = true;
+    return schema;
+}
+/**
+ * Marks a field as system-generated.
+ * Field is excluded from input schemas (add/set).
+ * MUST have a default() — error thrown otherwise.
+ *
+ * @example
+ * ```typescript
+ * const TodoSchema = z.object({
+ *   id: id(system(z.string().default(() => crypto.randomUUID()))),
+ *   created_at: system(z.number().default(() => Date.now()))
+ * });
+ * ```
+ */
+export function system(schema) {
+    schema.def.__mcpWebSystem = true;
+    return schema;
+}
+/**
+ * Checks if a field is marked with id().
+ */
+export function isKeyField(field) {
+    return field.def.__mcpWebKey === true;
+}
+/**
+ * Checks if a field is marked with system().
+ */
+export function isSystemField(field) {
+    return field.def.__mcpWebSystem === true;
+}
+/**
+ * Checks if a schema has a default value.
+ */
+export function hasDefault(schema) {
+    // Check for ZodDefault wrapper
+    if (schema instanceof z.ZodDefault) {
+        return true;
+    }
+    // Check _def for default value
+    const def = schema.def;
+    return def.defaultValue !== undefined || typeof def.defaultValue === 'function';
+}
+/**
+ * Unwraps a schema from ZodDefault, ZodOptional, ZodNullable wrappers.
+ * Returns the innermost schema.
+ */
+export function unwrapSchema(schema) {
+    let current = schema;
+    while (current instanceof z.ZodDefault ||
+        current instanceof z.ZodOptional ||
+        current instanceof z.ZodNullable) {
+        const def = current.def;
+        current = def.innerType || current;
+    }
+    return current;
+}
+/**
+ * Unwraps ZodDefault to get the inner schema.
+ */
+export function unwrapDefault(schema) {
+    if (schema instanceof z.ZodDefault) {
+        const def = schema.def;
+        return def.innerType;
+    }
+    return schema;
+}
+/**
+ * Derives an input schema for add operations.
+ * - system() fields are excluded
+ * - default() fields become optional
+ * - other fields remain required
+ */
+export function deriveAddInputSchema(schema) {
+    const inputShape = {};
+    for (const [key, field] of Object.entries(schema.shape)) {
+        const zodField = field;
+        // Skip system fields entirely
+        if (isSystemField(zodField))
+            continue;
+        // Fields with default() become optional in add
+        if (hasDefault(zodField)) {
+            inputShape[key] = unwrapDefault(zodField).optional();
+        }
+        else {
+            inputShape[key] = zodField;
+        }
+    }
+    return z.object(inputShape);
+}
+/**
+ * Derives an input schema for set operations (partial updates).
+ * - system() fields are excluded
+ * - all other fields become optional
+ */
+export function deriveSetInputSchema(schema) {
+    const inputShape = {};
+    for (const [key, field] of Object.entries(schema.shape)) {
+        const zodField = field;
+        // Skip system fields entirely
+        if (isSystemField(zodField))
+            continue;
+        // All fields optional for partial updates
+        inputShape[key] = unwrapDefault(zodField).optional();
+    }
+    return z.object(inputShape);
+}
+/**
+ * Validates that all system() fields have default values.
+ * Throws an error if a system field lacks a default.
+ */
+export function validateSystemFields(schema) {
+    for (const [key, field] of Object.entries(schema.shape)) {
+        const zodField = field;
+        if (isSystemField(zodField) && !hasDefault(zodField)) {
+            throw new Error(`Error: Field '${key}' is marked as system() but has no default value.\n\n` +
+                `System fields are excluded from input schemas, so a default is required.\n` +
+                `The handler uses this default to fill in the value when creating new items.\n\n` +
+                `Fix: Add a default value or generator:\n` +
+                `  ${key}: system(z.number().default(() => Date.now()))`);
+        }
+    }
+}

package/dist/expanded-schema-tools/schema-helpers.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=schema-helpers.test.d.ts.map

package/dist/expanded-schema-tools/schema-helpers.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-helpers.test.d.ts","sourceRoot":"","sources":["../../src/expanded-schema-tools/schema-helpers.test.ts"],"names":[],"mappings":""}