@wildo-ai/zod-decorators 1.0.0

package/dist/esm/zod-utils.shared.d.ts

@@ -0,0 +1,783 @@
+import { z } from 'zod';
+import type { ArrayUIParams, BigDecimalUIParams, BooleanUIParams, CodeUIParams, DateUIParams, DateTimeUIParams, DurationUIParams, EnumUIParams, FileUIParams, ForeignKeyUIParams, MoneyUIParams, NumberUIParams, ObjectUIParams, PhoneUIParams, StringUIParams, TimeUIParams, PrimitiveUIBaseEditParams, PrimitiveUIBaseDisplayParams } from './zod-decorators.types.js';
+import { BackendOnlyFieldParams, BigDecimalSchemaMetadata, DurationSchemaMetadata, CodeSchemaMetadata, DiscriminatorFieldParams, FileSchemaMetadata, ForeignKeyStructuralParams, ForeignKeyUIDisplayParams, MoneySchemaMetadata, CustomFieldMetadata, FieldSchemaType, FormFieldComponent, HiddenFieldParams, NotEditableFieldParams, OtpFieldParams, PhoneSchemaMetadata, PolymorphicFkVariant, RangeConstraintValue, RangeSchemaMetadata, RangeType, SerializableZodSchema, SummaryFieldParams, VersionedForeignKeySchemaMetadata, VersionedSchemaMetadata, ZodDecorator, UniqueFieldParams, VirtualFieldParams, TtlFieldParams, ShowWhenParams } from './zod-decorators.types.js';
+export declare function hasZodInternals(schema: unknown): schema is {
+    def: {
+        type: string;
+        [key: string]: unknown;
+    };
+    type?: string;
+};
+/**
+ * Check if a schema has a specific decorator.
+ * Note: getCustomFieldMetadata already handles recursive unwrapping for all wrapper types
+ * including pipe (from refine/superRefine), optional, nullable, default, etc.
+ */
+export declare function hasDecorator(schema: z.ZodTypeAny, decorator: ZodDecorator): boolean;
+/**
+ * Unwrap optional, nullable, default, and other wrapper schemas
+ * to get the underlying base schema
+ */
+export declare function unwrapSchema(schema: z.ZodTypeAny): z.ZodTypeAny;
+export declare function getZodType(schema: z.ZodTypeAny): string | undefined;
+/**
+ * Type guard to check if a schema has a specific type
+ * Uses Zod v4's type system where types are lowercase strings
+ */
+export declare function hasZodType(schema: z.ZodTypeAny, type: string): boolean;
+export declare function isZodObject(schema: z.ZodTypeAny): schema is z.ZodObject<any>;
+export declare function isZodArray(schema: z.ZodTypeAny): boolean;
+export declare function isZodOptional(schema: z.ZodTypeAny): boolean;
+export declare function isZodNullable(schema: z.ZodTypeAny): boolean;
+export declare function isZodDefault(schema: z.ZodTypeAny): boolean;
+export declare function isZodUnion(schema: z.ZodTypeAny): boolean;
+export declare function isZodIntersection(schema: z.ZodTypeAny): boolean;
+export declare function isZodLiteral(schema: z.ZodTypeAny): boolean;
+export declare function isZodLazy(schema: z.ZodTypeAny): boolean;
+export declare function isZodTuple(schema: z.ZodTypeAny): boolean;
+export declare function isZodRecord(schema: z.ZodTypeAny): boolean;
+export declare function isZodSet(schema: z.ZodTypeAny): boolean;
+export declare function isZodPipe(schema: z.ZodTypeAny): boolean;
+export declare function isZodTransform(schema: z.ZodTypeAny): boolean;
+export declare function isZodCustom(schema: z.ZodTypeAny): boolean;
+export declare function isArray(value: unknown): value is unknown[];
+export declare function isZodTypeAny(value: unknown): value is z.ZodTypeAny;
+/**
+ * Check if a union is discriminated (has discriminator property)
+ * In Zod v4, discriminated unions have type: "union" with a discriminator property
+ */
+export declare function isDiscriminatedUnion(schema: z.ZodTypeAny): boolean;
+/**
+ * Check if a schema is optional (can be undefined)
+ */
+export declare function isOptional(schema: z.ZodTypeAny): boolean;
+/**
+ * Check if a schema has refine/superRefine transformations
+ * This triggers onChange validation mode
+ */
+export declare function hasRefine(schema: z.ZodTypeAny): boolean;
+/**
+ * Get the schema type category for component selection.
+ *
+ * Important: RANGE schemas (created by z_range()) are detected by their
+ * SCHEMA_METADATA.rangeConfig before checking for object type. This allows range schemas
+ * to be rendered with appropriate range components instead of as composite objects.
+ */
+export declare function getSchemaType(schema: z.ZodTypeAny): FieldSchemaType;
+/**
+ * Get the shape of a Zod object schema.
+ *
+ * IMPORTANT: This function only returns valid Zod schema instances, not definitions.
+ * In Zod 4, `def.shape` contains JSON-serializable definitions, not schema instances
+ * with methods like safeParse.
+ *
+ * Prefer using getObjectShape() which handles unwrapping and validation.
+ */
+export declare function getZodObjectShape(schema: z.ZodTypeAny): Record<string, z.ZodTypeAny>;
+export declare function getZodDef(schema: z.ZodTypeAny): {
+    type: string;
+    [key: string]: unknown;
+} | undefined;
+export declare function getZodDefSchemaProperty(schema: z.ZodTypeAny, property: string): z.ZodTypeAny | undefined;
+export declare function getZodDefArrayProperty(schema: z.ZodTypeAny, property: string): unknown[] | undefined;
+export declare function getZodDefStringProperty(schema: z.ZodTypeAny, property: string): string | undefined;
+export declare function getZodDefFunctionProperty(schema: z.ZodTypeAny, property: string): (() => z.ZodTypeAny) | undefined;
+export declare function getZodDefProperty(schema: z.ZodTypeAny, property: string): unknown;
+/**
+ * Get the inner schema from a pipe type (for transforms/refinements)
+ * In Zod v4, pipe types have def.in and def.out
+ * For most cases, we want def.in (the input schema before transformation)
+ */
+export declare function getPipeInputSchema(schema: z.ZodTypeAny): z.ZodTypeAny | undefined;
+/**
+ * Get all custom field metadata from a schema, traversing through wrapper types
+ * (optional, nullable, default, pipe, readonly, catch, array, effects).
+ * Always returns an object (never undefined) — empty `{}` if no metadata found.
+ *
+ * Delegates to the unified getMetadataRecursive from zod.module-override.ts.
+ */
+export declare function getCustomFieldMetadata(schema: z.ZodTypeAny): CustomFieldMetadata;
+/**
+ * Extract the edit-context base params from whichever `{primitive}UI` decorator
+ * is present on the schema. Works generically because all `*UIEditParams`
+ * extend `PrimitiveUIBaseEditParams`.
+ *
+ * Use this for cross-cutting concerns (validationMode, autosave, tooltip, etc.)
+ * where the consumer doesn't know the concrete primitive type.
+ */
+export declare function getFieldUIEditConfig(schema: z.ZodTypeAny): PrimitiveUIBaseEditParams | undefined;
+/**
+ * Extract the display-context base params from whichever `{primitive}UI` decorator
+ * is present on the schema. Works generically because all `*UIDisplayParams`
+ * extend `PrimitiveUIBaseDisplayParams`.
+ *
+ * Use this for cross-cutting concerns (tooltip, inlineEditable, etc.)
+ * where the consumer doesn't know the concrete primitive type.
+ */
+export declare function getFieldUIDisplayConfig(schema: z.ZodTypeAny): PrimitiveUIBaseDisplayParams | undefined;
+/**
+ * Check if a field should show a tooltip in display mode.
+ * Reads from `{primitive}UI.display.tooltip` (boolean flag).
+ * The actual tooltip text comes from the i18n label system, NOT from the decorator.
+ */
+export declare function hasTooltipForDisplay(schema: z.ZodTypeAny): boolean;
+/**
+ * Check if a field should show a tooltip in edit mode.
+ * Reads from `{primitive}UI.edit.tooltip` (boolean flag).
+ * The actual tooltip text comes from the i18n label system, NOT from the decorator.
+ */
+export declare function hasTooltipForEdit(schema: z.ZodTypeAny): boolean;
+/**
+ * Check if a field is marked as draft-relaxed (validation is relaxed in draft mode).
+ *
+ * @param schema - Zod schema to check
+ * @returns true if the field is draft-relaxed
+ *
+ * @example
+ * if (isDraftRelaxed(schema) && isDraftMode) {
+ *   // Skip strict validation for this field
+ * }
+ */
+export declare function isDraftRelaxed(schema: z.ZodTypeAny): boolean;
+/**
+ * FIX-P5-H1: Get showWhen parameters from a field schema.
+ * Returns the conditional visibility configuration if present.
+ *
+ * @param schema - The field schema to get showWhen params from
+ * @returns ShowWhenParams if decorator was applied, undefined otherwise
+ *
+ * @example
+ * const showWhenParams = getShowWhenParams(fieldSchema);
+ * if (showWhenParams) {
+ *   // Evaluate visibility based on conditions
+ *   const isVisible = evaluateShowWhenConditions(showWhenParams, formValues);
+ * }
+ */
+export declare function getShowWhenParams(schema: z.ZodTypeAny): ShowWhenParams | undefined;
+/**
+ * String format types detected from schema
+ */
+export type StringFormat = 'email' | 'url' | 'uuid' | 'cuid' | 'cuid2' | 'ulid' | 'regex' | 'datetime' | 'time' | 'ip' | null;
+/**
+ * Get string format from schema checks (email, url, etc.)
+ */
+export declare function getStringFormat(schema: z.ZodTypeAny): StringFormat;
+/**
+ * Get min/max length constraints from string schema
+ */
+export declare function getStringConstraints(schema: z.ZodTypeAny): {
+    minLength?: number;
+    maxLength?: number;
+};
+/**
+ * Get min/max value constraints from number schema
+ */
+export declare function getNumberConstraints(schema: z.ZodTypeAny): {
+    min?: number;
+    max?: number;
+    step?: number;
+    isInt?: boolean;
+};
+/**
+ * Extract enum values from z.enum (Zod 4)
+ * In Zod 4, both z.enum() and z.enum() create schemas with type 'enum'
+ * - z.enum(['a', 'b', 'c']) - def.entries is an object map (e.g. { a: 'a', b: 'b' })
+ * - z.enum(TypeScriptEnum) / z.enum(TypeScriptEnum) - def.entries is the enum object map
+ */
+export declare function getEnumValues(schema: z.ZodTypeAny): string[];
+/**
+ * Get the shape of an object schema.
+ *
+ * IMPORTANT: In Zod 4, `def.shape` contains schema DEFINITIONS (JSON-serializable),
+ * NOT schema instances with methods. This function validates that returned shapes
+ * contain actual Zod schema instances.
+ *
+ * If the schema is wrapped (e.g., with .default()), it will be unwrapped first.
+ */
+export declare function getObjectShape(schema: z.ZodTypeAny): Record<string, z.ZodTypeAny> | null;
+/**
+ * Get the keys of an object schema shape
+ */
+export declare function getObjectKeys(schema: z.ZodTypeAny): string[];
+/**
+ * Extract all flattened paths from a Zod schema.
+ * Recursively traverses object schemas to build dot-notation paths (e.g., 'field.nestedField').
+ * Handles optional, nullable, array, and union types.
+ *
+ * @param zodSchema - The Zod schema to extract paths from
+ * @param prefix - Current path prefix (used for recursion)
+ * @param schemaDepthCounters - Map to track depth per schema instance (prevents infinite recursion)
+ * @param maxDepthPerSchema - Maximum depth to traverse per schema instance (default: 3)
+ * @returns Array of flattened dot-notation paths
+ */
+export declare function extractFlattenedPathsFromZodSchema(zodSchema: z.ZodTypeAny, prefix?: string, schemaDepthCounters?: Map<any, number>, maxDepthPerSchema?: number): string[];
+/**
+ * Get the item schema from an array schema
+ */
+export declare function getArrayItemSchema(schema: z.ZodTypeAny): z.ZodTypeAny | null;
+/**
+ * Get min/max constraints for array
+ */
+export declare function getArrayConstraints(schema: z.ZodTypeAny): {
+    minLength?: number;
+    maxLength?: number;
+};
+/**
+ * Get the value schema from a record schema
+ */
+export declare function getRecordValueSchema(schema: z.ZodTypeAny): z.ZodTypeAny | null;
+/**
+ * Get the key and value schemas from a map schema
+ */
+export declare function getMapSchemas(schema: z.ZodTypeAny): {
+    keySchema: z.ZodTypeAny;
+    valueSchema: z.ZodTypeAny;
+} | null;
+/**
+ * Get the default value from a schema if it has one
+ */
+export declare function getDefaultValue(schema: z.ZodTypeAny): unknown | undefined;
+export declare function isDBIndexed(schema: z.ZodTypeAny): boolean;
+/** @see isForeignKeyField — alias for backward compatibility */
+export declare function isForeignKey(schema: z.ZodTypeAny): boolean;
+/** @see isUniqueField — alias for backward compatibility */
+export declare function isUnique(schema: z.ZodTypeAny): boolean;
+/** @see getUniqueFieldParams — alias for backward compatibility */
+export declare function getUniqueParams(schema: z.ZodTypeAny): UniqueFieldParams | undefined;
+/**
+ * Check if a field is a primary key.
+ * Primary keys are automatically: excludeFromCreate, isHidden, isUnique, isDBIndexed
+ * @see isPrimaryKeyField — alias for backward compatibility
+ */
+export declare function isPrimaryKey(schema: z.ZodTypeAny): boolean;
+/**
+ * Check if a field has a TTL (Time To Live) decorator.
+ * TTL fields are used for MongoDB document expiration.
+ */
+export declare function hasTtl(schema: z.ZodTypeAny): boolean;
+/**
+ * Get TTL field params from a schema.
+ * Returns undefined if the schema is not a TTL field.
+ */
+export declare function getTtlParams(schema: z.ZodTypeAny): TtlFieldParams | undefined;
+/**
+ * Get the structural FK params (polymorphicVariants) from `IS_FOREIGN_KEY`.
+ * Returns undefined if the schema is not a foreign key.
+ */
+export declare function getForeignKeyParams(schema: z.ZodTypeAny): ForeignKeyStructuralParams | undefined;
+/**
+ * Get FK UI display params from `FOREIGN_KEY_UI.display`. Returns mode, linkable, displayPresetOverride.
+ * Falls back to default `mode: LABEL` if the FK exists but has no explicit UI config.
+ */
+export declare function getForeignKeyUIDisplay(schema: z.ZodTypeAny): ForeignKeyUIDisplayParams | undefined;
+/**
+ * Get the polymorphic variants from a foreign key field.
+ * Returns the array of PolymorphicFkVariant if the FK is polymorphic, or undefined.
+ */
+export declare function getPolymorphicFkVariants(schema: z.ZodTypeAny): PolymorphicFkVariant[] | undefined;
+/**
+ * Check if a schema field is a foreign key (recursive traversal through wrappers).
+ */
+export declare function isForeignKeyField(schema: z.ZodTypeAny): boolean;
+/**
+ * Check if a schema field has the isSummaryField decorator.
+ */
+export declare function isSummaryField(schema: z.ZodTypeAny): boolean;
+/**
+ * Get the isSummaryField decorator parameters.
+ * @returns SummaryFieldParams or default empty object if decorator is used without params
+ */
+export declare function getSummaryFieldParams(schema: z.ZodTypeAny): SummaryFieldParams | undefined;
+/**
+ * Check if a schema field has the isBackendOnly decorator.
+ */
+export declare function isBackendOnlyField(schema: z.ZodTypeAny): boolean;
+/**
+ * Get the isBackendOnly decorator parameters.
+ */
+export declare function getBackendOnlyParams(schema: z.ZodTypeAny): BackendOnlyFieldParams | undefined;
+/**
+ * Check if a field has auditAccess enabled via `.isBackendOnly({ auditAccess: true })`.
+ * Fields with this flag generate FIELD_ACCESS audit events when included in API responses.
+ */
+export declare function isAuditAccessField(schema: z.ZodTypeAny): boolean;
+/**
+ * Check if a schema field has the isDiscriminator decorator.
+ */
+export declare function isDiscriminatorField(schema: z.ZodTypeAny): boolean;
+/**
+ * Get the isDiscriminator decorator parameters.
+ */
+export declare function getDiscriminatorParams(schema: z.ZodTypeAny): DiscriminatorFieldParams | undefined;
+/**
+ * Check if a schema field has the excludeFromCreate decorator.
+ */
+export declare function isExcludedFromCreate(schema: z.ZodTypeAny): boolean;
+/**
+ * Check if a schema field has the excludeFromUpdate decorator.
+ */
+export declare function isExcludedFromUpdate(schema: z.ZodTypeAny): boolean;
+/**
+ * Check if a schema field is hidden (recursive traversal through wrappers).
+ */
+export declare function isHiddenField(schema: z.ZodTypeAny): boolean;
+/**
+ * Get the isHidden decorator parameters.
+ * Returns default params (hidden in both display and edit) when decorator is used without params.
+ */
+export declare function getHiddenFieldParams(schema: z.ZodTypeAny): HiddenFieldParams | undefined;
+/**
+ * Check if a schema field is not editable (recursive traversal through wrappers).
+ */
+export declare function isNotEditableField(schema: z.ZodTypeAny): boolean;
+/**
+ * Get the isNotEditable decorator parameters.
+ */
+export declare function getNotEditableFieldParams(schema: z.ZodTypeAny): NotEditableFieldParams | undefined;
+/**
+ * Check if a schema field has the isUnique decorator (recursive traversal through wrappers).
+ */
+export declare function isUniqueField(schema: z.ZodTypeAny): boolean;
+/**
+ * Get the isUnique decorator parameters (recursive traversal through wrappers).
+ * Returns default params { scope: 'global', sparse: true } when decorator is used without params.
+ */
+export declare function getUniqueFieldParams(schema: z.ZodTypeAny): UniqueFieldParams | undefined;
+/**
+ * Check if a schema field has the isPrimaryKey decorator (recursive traversal through wrappers).
+ */
+export declare function isPrimaryKeyField(schema: z.ZodTypeAny): boolean;
+/**
+ * Get all metadata for a schema field (non-recursive, direct access only).
+ */
+export declare function getFieldMetadata(schema: z.ZodTypeAny): CustomFieldMetadata | undefined;
+/**
+ * Get all metadata for a schema field, traversing through wrapper types.
+ */
+export declare function getFieldMetadataRecursive(schema: z.ZodTypeAny): CustomFieldMetadata | undefined;
+/**
+ * Check if a schema is a range schema (created by z_range()).
+ * Detects by the presence of rangeConfig in SCHEMA_METADATA.
+ * Checks both the schema directly and the unwrapped inner schema.
+ */
+export declare function isRangeSchema(schema: z.ZodTypeAny): boolean;
+/**
+ * Get the range metadata from a schema.
+ * Returns undefined if not a range schema.
+ * Checks both the schema directly and the unwrapped inner schema.
+ */
+export declare function getRangeMetadata(schema: z.ZodTypeAny): RangeSchemaMetadata | undefined;
+/**
+ * Get the range type from a schema.
+ * Returns undefined if not a range schema.
+ */
+export declare function getRangeType(schema: z.ZodTypeAny): RangeType | undefined;
+/**
+ * Check if a schema is a money schema (created by z_money()).
+ * Detects by the presence of moneyConfig in SCHEMA_METADATA.
+ * Checks both the schema directly and the unwrapped inner schema.
+ */
+export declare function isMoneySchema(schema: z.ZodTypeAny): boolean;
+/**
+ * Get the money metadata from a schema.
+ * Returns undefined if not a money schema.
+ * Checks both the schema directly and the unwrapped inner schema.
+ */
+export declare function getMoneyMetadata(schema: z.ZodTypeAny): MoneySchemaMetadata | undefined;
+/**
+ * Check if a schema is a bigdecimal schema (created by z_bigdecimal()).
+ * Detects by the presence of bigDecimalConfig in SCHEMA_METADATA.
+ * Checks both the schema directly and the unwrapped inner schema.
+ */
+export declare function isBigDecimalSchema(schema: z.ZodTypeAny): boolean;
+/**
+ * Get the bigdecimal metadata from a schema.
+ * Returns undefined if not a bigdecimal schema.
+ * Checks both the schema directly and the unwrapped inner schema.
+ */
+export declare function getBigDecimalMetadata(schema: z.ZodTypeAny): BigDecimalSchemaMetadata | undefined;
+/**
+ * Get bigdecimal constraints from schema metadata.
+ * Returns min, max, precision from the bigdecimal schema configuration.
+ */
+export declare function getBigDecimalConstraints(schema: z.ZodTypeAny): {
+    min?: string;
+    max?: string;
+    precision?: number;
+};
+/**
+ * Check if a schema is a duration schema (created by z_duration()).
+ * Detects by the presence of durationConfig in SCHEMA_METADATA.
+ * Checks both the schema directly and the unwrapped inner schema.
+ */
+export declare function isDurationSchema(schema: z.ZodTypeAny): boolean;
+/**
+ * Get the duration metadata from a schema.
+ * Returns undefined if not a duration schema.
+ */
+export declare function getDurationMetadata(schema: z.ZodTypeAny): DurationSchemaMetadata | undefined;
+/**
+ * Get duration constraints from schema metadata.
+ */
+export declare function getDurationConstraints(schema: z.ZodTypeAny): {
+    minValue?: number;
+    maxValue?: number;
+    allowedUnits?: string[];
+};
+/**
+ * Check if a schema is a phone schema (created by z_phone()).
+ * Detects by the presence of phoneConfig in SCHEMA_METADATA.
+ * Checks both the schema directly and the unwrapped inner schema.
+ */
+export declare function isPhoneSchema(schema: z.ZodTypeAny): boolean;
+/**
+ * Get the phone metadata from a schema.
+ * Returns undefined if not a phone schema.
+ */
+export declare function getPhoneMetadata(schema: z.ZodTypeAny): PhoneSchemaMetadata | undefined;
+/**
+ * Check if a schema is a code schema created by z_code().
+ * Checks both the schema directly and the unwrapped inner schema.
+ */
+export declare function isCodeSchema(schema: z.ZodTypeAny): boolean;
+/**
+ * Get code schema metadata if this is a code schema.
+ * Checks both the schema directly and the unwrapped inner schema.
+ */
+export declare function getCodeMetadata(schema: z.ZodTypeAny): CodeSchemaMetadata | undefined;
+/**
+ * Check if a schema is a file schema created by z_file().
+ * Checks both the schema directly and the unwrapped inner schema.
+ */
+export declare function isFileSchema(schema: z.ZodTypeAny): boolean;
+/**
+ * Get file schema metadata if this is a file schema.
+ * Checks both the schema directly and the unwrapped inner schema.
+ */
+export declare function getFileMetadata(schema: z.ZodTypeAny): FileSchemaMetadata | undefined;
+/**
+ * Check if a schema is a versioned foreign key schema created by z_foreignKeyVersioned().
+ * Checks both the schema directly and the unwrapped inner schema.
+ */
+export declare function isVersionedForeignKeySchema(schema: z.ZodTypeAny): boolean;
+/**
+ * Get versioned foreign key schema metadata if this is a versioned foreign key schema.
+ * Checks both the schema directly and the unwrapped inner schema.
+ */
+export declare function getVersionedForeignKeyMetadata(schema: z.ZodTypeAny): VersionedForeignKeySchemaMetadata | undefined;
+/**
+ * Check if a schema is a versioned object schema created by versioned().
+ * Checks both the schema directly and the unwrapped inner schema.
+ */
+export declare function isVersionedObjectSchema(schema: z.ZodTypeAny): boolean;
+/**
+ * Get versioned schema metadata if this is a versioned object schema.
+ * Checks both the schema directly and the unwrapped inner schema.
+ */
+export declare function getVersionedObjectMetadata(schema: z.ZodTypeAny): VersionedSchemaMetadata | undefined;
+/**
+ * Check if the 'from' field is optional in a range schema.
+ */
+export declare function isRangeFromOptional(schema: z.ZodTypeAny): boolean | undefined;
+/**
+ * Check if the 'to' field is optional in a range schema.
+ */
+export declare function isRangeToOptional(schema: z.ZodTypeAny): boolean | undefined;
+/**
+ * Get the min constraint from a range schema.
+ */
+export declare function getRangeMin(schema: z.ZodTypeAny): RangeConstraintValue | undefined;
+/**
+ * Get the max constraint from a range schema.
+ */
+export declare function getRangeMax(schema: z.ZodTypeAny): RangeConstraintValue | undefined;
+/**
+ * Get the form component from `{primitive}UI.edit.component`.
+ * Returns undefined if no form component is specified.
+ */
+export declare function getFormFieldComponent(schema: z.ZodTypeAny): FormFieldComponent | undefined;
+/**
+ * Check if a field should be hidden based on the current context.
+ * @param schema - The Zod schema to check
+ * @param context - Optional context with mode ('display' | 'edit') and operation name
+ */
+export declare function shouldHideField(schema: z.ZodTypeAny, context?: {
+    mode?: 'display' | 'edit';
+    operation?: string;
+}): boolean;
+export declare function isFormInput(schema: z.ZodTypeAny): boolean;
+export declare function isFormTextarea(schema: z.ZodTypeAny): boolean;
+export declare function isFormSelect(schema: z.ZodTypeAny): boolean;
+export declare function isFormRadioGroup(schema: z.ZodTypeAny): boolean;
+export declare function isFormCheckbox(schema: z.ZodTypeAny): boolean;
+export declare function isFormCheckboxGroup(schema: z.ZodTypeAny): boolean;
+export declare function isFormSwitch(schema: z.ZodTypeAny): boolean;
+export declare function isFormSlider(schema: z.ZodTypeAny): boolean;
+export declare function isFormDate(schema: z.ZodTypeAny): boolean;
+/**
+ * Get the hidden field metadata from schema decorator.
+ * Returns undefined if no hidden decorator is set.
+ * Returns true if field is hidden in all cases.
+ * Returns HiddenFieldParams if conditional hiding is configured.
+ * Note: getCustomFieldMetadata already handles recursive unwrapping for all wrapper types
+ * including pipe (from refine/superRefine), optional, nullable, default, etc.
+ */
+export declare function getHiddenFieldMetadata(schema: z.ZodTypeAny): HiddenFieldParams | true | undefined;
+/**
+ * Check if a schema has a hidden decorator.
+ */
+export declare function hasHiddenDecorator(schema: z.ZodTypeAny): boolean;
+/**
+ * Check if a field should be hidden for display mode.
+ * @param schema - The Zod schema to check
+ * @returns true if the field should be hidden in display mode
+ */
+export declare function isHiddenForDisplay(schema: z.ZodTypeAny): boolean;
+/**
+ * Check if a field should be hidden for edit mode.
+ * @param schema - The Zod schema to check
+ * @returns true if the field should be hidden in edit mode
+ */
+export declare function isHiddenForEdit(schema: z.ZodTypeAny): boolean;
+/**
+ * Check if a field should be hidden for a specific operation.
+ * @param schema - The Zod schema to check
+ * @param operation - The operation identifier (e.g., 'create', 'update')
+ * @returns true if the field should be hidden for the given operation
+ */
+export declare function isHiddenForOperation(schema: z.ZodTypeAny, operation: string): boolean;
+/**
+ * Get the not editable field metadata from schema decorator.
+ * Returns undefined if no isNotEditable decorator is set.
+ * Returns true if field is not editable for all operations.
+ * Returns NotEditableFieldParams if operation-specific.
+ * Note: getCustomFieldMetadata already handles recursive unwrapping for all wrapper types
+ * including pipe (from refine/superRefine), optional, nullable, default, etc.
+ */
+export declare function getNotEditableFieldMetadata(schema: z.ZodTypeAny): NotEditableFieldParams | true | undefined;
+/**
+ * Check if a schema has a isNotEditable decorator.
+ */
+export declare function hasNotEditableDecorator(schema: z.ZodTypeAny): boolean;
+/**
+ * Check if a field is not editable for a specific operation (or all operations).
+ * @param schema - The Zod schema to check
+ * @param operation - Optional operation identifier. If not provided, checks if not editable for all operations.
+ * @returns true if the field is not editable
+ */
+export declare function isNotEditableForOperation(schema: z.ZodTypeAny, operation?: string): boolean;
+/**
+ * Resolved inline editable params with all defaults applied.
+ */
+export interface ResolvedInlineEditableParams {
+    mode: 'direct' | 'button';
+    saveOn: 'blur' | 'explicit';
+    showSaveButton: boolean;
+    showCancelButton: boolean;
+}
+/**
+ * Check if a schema has inline editable configuration.
+ * Reads from `{primitive}UI.display.inlineEditable`.
+ */
+export declare function hasInlineEditableDecorator(schema: z.ZodTypeAny): boolean;
+/**
+ * Get the resolved inline editable params from `{primitive}UI.display.inlineEditable`.
+ * Handles both `true` shorthand and full object config.
+ */
+export declare function getInlineEditableParams(schema: z.ZodTypeAny): ResolvedInlineEditableParams | undefined;
+/**
+ * Extract the `.describe()` text from a Zod schema, unwrapping optional/nullable/default wrappers.
+ * Returns undefined if no `.describe("...")` is set.
+ *
+ * **IMPORTANT**: Zod `.describe("...")` is for developer documentation, AI prompting systems,
+ * and API documentation generation. It is NOT used for UI field descriptions — those are
+ * managed through `{primitive}UI.display.showDescription` + i18n system.
+ *
+ * In Zod 4, `.describe("...")` sets the `.description` property on the schema.
+ * When `.optional()`, `.nullable()`, or `.default()` wrap the schema, the description
+ * may live on the inner schema. We check both levels.
+ */
+export declare function getZodDescription(schema: z.ZodTypeAny): string | undefined;
+/**
+ * Check if a field should have a description i18n key generated for **display** mode.
+ *
+ * Reads from `{primitive}UI.display.showDescription` (boolean flag).
+ * This follows the same opt-in pattern as tooltips: only generate i18n keys for
+ * fields that explicitly declare intent via a decorator.
+ *
+ * **NOTE**: Zod `.describe("...")` is NOT an opt-in signal for UI descriptions.
+ * `.describe()` serves a different purpose (developer docs, AI prompting, API docs).
+ * UI field descriptions are purely decorator-driven + i18n-resolved.
+ *
+ * @param schema - The Zod schema to check
+ * @returns true if a description i18n key should be generated for display mode
+ */
+export declare function hasDescriptionForDisplay(schema: z.ZodTypeAny): boolean;
+/**
+ * Check if a field should have a description i18n key generated for **edit** mode.
+ *
+ * Reads from `{primitive}UI.edit.showDescription` (boolean flag).
+ * If a field declares it wants a description, both display AND edit i18n keys are generated
+ * so translators can provide mode-appropriate text.
+ *
+ * @param schema - The Zod schema to check
+ * @returns true if a description i18n key should be generated for edit mode
+ */
+export declare function hasDescriptionForEdit(schema: z.ZodTypeAny): boolean;
+/**
+ * Check if a string schema should render as a password input.
+ * Checks IS_PASSWORD structural marker first, then STRING_UI editMode fallback.
+ */
+export declare function isPasswordField(schema: z.ZodTypeAny): boolean;
+/**
+ * Check if a string schema should render as an OTP input.
+ * Checks IS_OTP structural marker first, then STRING_UI editMode fallback.
+ */
+export declare function isOtpField(schema: z.ZodTypeAny): boolean;
+/**
+ * Check if a string schema should render as a color input.
+ * Checks IS_COLOR structural marker first, then STRING_UI editMode fallback.
+ */
+export declare function isColorField(schema: z.ZodTypeAny): boolean;
+/**
+ * Get OTP field params from a schema.
+ * Returns the OTP params with defaults merged in if the decorator is present.
+ * Defaults: maxLength=6
+ */
+export declare function getOtpFieldParams(schema: z.ZodTypeAny): OtpFieldParams | undefined;
+/**
+ * Get the system enum name from a schema's metadata.
+ * Returns the name string (e.g. 'AvailableCurrency') if the .systemEnum() decorator is set,
+ * or undefined if the field is not a system enum.
+ */
+export declare function getSystemEnumName(schema: z.ZodTypeAny): string | undefined;
+/**
+ * Serialize a Zod schema to a JSON-serializable format.
+ * Uses Zod 4 internal structure (_zod.def.type).
+ */
+export declare function serializeZodSchema(schema: z.ZodTypeAny | undefined, seen?: Set<z.ZodTypeAny>): SerializableZodSchema | null;
+/**
+ * Deserialize a SerializableZodSchema back into a Zod schema.
+ * - Reconstructs approximate Zod types from the descriptor
+ * - Re-applies optional/nullable wrappers
+ * - Re-applies SCHEMA_METADATA as decorators when possible
+ */
+export declare function deserializeZodSchema(desc: SerializableZodSchema | null | undefined): any;
+/**
+ * Check if a schema is marked as a virtual field.
+ * Virtual fields are computed at runtime and not stored in the database.
+ */
+export declare function isVirtualField(schema: z.ZodTypeAny): boolean;
+/**
+ * Get the virtual field parameters from a schema.
+ * Returns undefined if the field is not virtual.
+ */
+export declare function getVirtualFieldParams(schema: z.ZodTypeAny): VirtualFieldParams | undefined;
+/**
+ * Get the dependencies declared for a virtual field.
+ * Returns an empty array if no dependencies are declared or the field is not virtual.
+ */
+export declare function getVirtualFieldDependencies(schema: z.ZodTypeAny): string[];
+/**
+ * Check if a virtual field needs object context (parents/children) for computation.
+ */
+export declare function virtualFieldNeedsObjectContext(schema: z.ZodTypeAny): boolean;
+/**
+ * Check if a virtual field needs user context for computation.
+ */
+export declare function virtualFieldNeedsUserContext(schema: z.ZodTypeAny): boolean;
+/**
+ * Operation type for schema preparation.
+ */
+export type FormSchemaOperationType = 'CREATE' | 'UPDATE' | 'READ';
+/**
+ * Options for prepareFormSchema utility.
+ */
+export interface PrepareFormSchemaOptions {
+    /**
+     * The operation type (CREATE, UPDATE, or READ).
+     * Used to filter excludeFromCreate/excludeFromUpdate fields.
+     */
+    operationType: FormSchemaOperationType;
+    /**
+     * Whether the form is in draft mode.
+     * When true, fields with isDraftRelaxed() become optional.
+     * @default false
+     */
+    isDraftMode?: boolean;
+    /**
+     * Optional operation that behaves like a core operation.
+     * For example, 'DUPLICATE' might behave like 'CREATE'.
+     */
+    operationLike?: FormSchemaOperationType;
+}
+/**
+ * Check if a field should be excluded from form validation based on its decorators.
+ */
+export declare function shouldExcludeFieldFromForm(fieldSchema: z.ZodTypeAny, operationType: FormSchemaOperationType): boolean;
+/**
+ * Check if a field has isDraftRelaxed decorator.
+ */
+export declare function isDraftRelaxedField(fieldSchema: z.ZodTypeAny): boolean;
+/**
+ * Prepare a schema for form validation by filtering out fields that shouldn't be validated
+ * and adjusting optionality based on draft mode.
+ *
+ * This function:
+ * - Removes virtual fields
+ * - Removes backend-only fields
+ * - Removes hidden fields
+ * - Removes excludeFromCreate fields (for CREATE operations)
+ * - Removes excludeFromUpdate fields (for UPDATE operations)
+ * - Makes isDraftRelaxed fields optional when in draft mode
+ *
+ * **WARNING: Schema-level refinements (.refine(), .superRefine()) are NOT carried over.**
+ * The returned schema is a new z.object() with the filtered shape — any cross-field
+ * validation defined via refinements on the original schema will be silently lost.
+ * This is intentional for draft mode (draft = relaxed validation), but callers using
+ * this outside of draft mode should be aware that cross-field rules won't apply.
+ * For non-draft form validation, use the original schema (e.g., operation.requestDto) directly.
+ *
+ * @param schema - The original object schema
+ * @param options - Preparation options
+ * @returns A new schema suitable for form validation (without schema-level refinements)
+ */
+export declare function prepareFormSchema<T extends z.ZodObject<z.ZodRawShape>>(schema: T, options: PrepareFormSchemaOptions): z.ZodObject<z.ZodRawShape>;
+/**
+ * Check if a schema field is marked as ephemeral (transient response-only data).
+ * Ephemeral fields are shown once (e.g., API keys upon creation) and not persisted in the UI.
+ */
+export declare function isEphemeralField(schema: z.ZodTypeAny): boolean;
+export declare function getBooleanUI(schema: z.ZodTypeAny): BooleanUIParams | undefined;
+export declare function hasBooleanUI(schema: z.ZodTypeAny): boolean;
+export declare function getStringUI(schema: z.ZodTypeAny): StringUIParams | undefined;
+export declare function hasStringUI(schema: z.ZodTypeAny): boolean;
+export declare function getNumberUI(schema: z.ZodTypeAny): NumberUIParams | undefined;
+export declare function hasNumberUI(schema: z.ZodTypeAny): boolean;
+export declare function getEnumUI(schema: z.ZodTypeAny): EnumUIParams | undefined;
+export declare function hasEnumUI(schema: z.ZodTypeAny): boolean;
+export declare function getDateUI(schema: z.ZodTypeAny): DateUIParams | undefined;
+export declare function hasDateUI(schema: z.ZodTypeAny): boolean;
+export declare function getDateTimeUI(schema: z.ZodTypeAny): DateTimeUIParams | undefined;
+export declare function hasDateTimeUI(schema: z.ZodTypeAny): boolean;
+export declare function getTimeUI(schema: z.ZodTypeAny): TimeUIParams | undefined;
+export declare function hasTimeUI(schema: z.ZodTypeAny): boolean;
+export declare function getMoneyUI(schema: z.ZodTypeAny): MoneyUIParams | undefined;
+export declare function hasMoneyUI(schema: z.ZodTypeAny): boolean;
+export declare function getCodeUI(schema: z.ZodTypeAny): CodeUIParams | undefined;
+export declare function hasCodeUI(schema: z.ZodTypeAny): boolean;
+export declare function getFileUI(schema: z.ZodTypeAny): FileUIParams | undefined;
+export declare function hasFileUI(schema: z.ZodTypeAny): boolean;
+export declare function getDurationUI(schema: z.ZodTypeAny): DurationUIParams | undefined;
+export declare function hasDurationUI(schema: z.ZodTypeAny): boolean;
+export declare function getPhoneUI(schema: z.ZodTypeAny): PhoneUIParams | undefined;
+export declare function hasPhoneUI(schema: z.ZodTypeAny): boolean;
+export declare function getBigDecimalUI(schema: z.ZodTypeAny): BigDecimalUIParams | undefined;
+export declare function hasBigDecimalUI(schema: z.ZodTypeAny): boolean;
+export declare function getForeignKeyUI(schema: z.ZodTypeAny): ForeignKeyUIParams | undefined;
+export declare function hasForeignKeyUI(schema: z.ZodTypeAny): boolean;
+export declare function getArrayUI(schema: z.ZodTypeAny): ArrayUIParams | undefined;
+export declare function hasArrayUI(schema: z.ZodTypeAny): boolean;
+export declare function getObjectUI(schema: z.ZodTypeAny): ObjectUIParams | undefined;
+export declare function hasObjectUI(schema: z.ZodTypeAny): boolean;
+//# sourceMappingURL=zod-utils.shared.d.ts.map