convex-cms 0.0.1

package/dist/component/validation.d.ts

@@ -0,0 +1,387 @@
+/**
+ * Content Validation Functions
+ *
+ * Runtime validation helpers that check content data against field configurations.
+ * These complement the Convex validators by providing detailed validation logic
+ * and human-readable error messages.
+ *
+ * Supports both plain field values and localized field values (LocalizedFieldValue<T>)
+ * for fields marked as `localized: true` in their field definition.
+ */
+import { FieldType } from "./validators.js";
+/**
+ * Field options structure (matches schema.ts fieldOptionsValidator)
+ */
+export interface FieldOptions {
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    precision?: number;
+    allowedContentTypes?: string[];
+    multiple?: boolean;
+    /** Minimum number of references required (only applies when multiple is true) */
+    minItems?: number;
+    allowedMimeTypes?: string[];
+    maxFileSize?: number;
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    allowedBlocks?: string[];
+    allowedMarks?: string[];
+    taxonomyId?: string;
+    allowCreate?: boolean;
+    maxTags?: number;
+    minTags?: number;
+    allowMultiple?: boolean;
+}
+/**
+ * Field definition structure (matches schema.ts fieldDefinitionValidator)
+ */
+export interface FieldDefinition {
+    name: string;
+    label: string;
+    type: FieldType;
+    required: boolean;
+    searchable?: boolean;
+    localized?: boolean;
+    description?: string;
+    defaultValue?: unknown;
+    options?: FieldOptions;
+}
+/**
+ * Content type schema structure
+ */
+export interface ContentTypeSchema {
+    name: string;
+    displayName: string;
+    description?: string;
+    fields: FieldDefinition[];
+    titleField?: string;
+    slugField?: string;
+    singleton?: boolean;
+}
+/**
+ * Content data is a record of field names to their values
+ */
+export type ContentData = Record<string, unknown>;
+export type ValidationError = {
+    field: string;
+    message: string;
+    code: ValidationErrorCode;
+};
+export type ValidationErrorCode = "REQUIRED" | "MIN_LENGTH" | "MAX_LENGTH" | "PATTERN_MISMATCH" | "MIN_VALUE" | "MAX_VALUE" | "NOT_INTEGER" | "MIN_DATE" | "MAX_DATE" | "INVALID_TYPE" | "MIN_ITEMS" | "MAX_ITEMS" | "INVALID_CONTENT_TYPE" | "UNKNOWN_FIELD" | "INVALID_MIME_TYPE" | "FILE_TOO_LARGE" | "INVALID_LOCALIZED_STRUCTURE" | "MISSING_LOCALE";
+export type ValidationResult = {
+    valid: true;
+    errors: [];
+} | {
+    valid: false;
+    errors: ValidationError[];
+};
+/**
+ * Validate a text field value against its configuration
+ */
+export declare function validateTextField(value: unknown, fieldDef: FieldDefinition): ValidationError[];
+/**
+ * Validate a rich text field value against its configuration
+ */
+export declare function validateRichTextField(value: unknown, fieldDef: FieldDefinition): ValidationError[];
+/**
+ * Validate a number field value against its configuration
+ */
+export declare function validateNumberField(value: unknown, fieldDef: FieldDefinition): ValidationError[];
+/**
+ * Validate a boolean field value against its configuration
+ */
+export declare function validateBooleanField(value: unknown, fieldDef: FieldDefinition): ValidationError[];
+/**
+ * Validate a date or datetime field value against its configuration
+ */
+export declare function validateDateField(value: unknown, fieldDef: FieldDefinition): ValidationError[];
+/**
+ * Validate a reference field value against its configuration.
+ *
+ * Reference fields store IDs to other content entries. They support:
+ * - Single reference: `string` (one entry ID)
+ * - Multiple references: `string[]` (array of entry IDs) when `multiple: true`
+ *
+ * Configuration options:
+ * - `allowedContentTypes`: Array of content type names that can be referenced
+ * - `multiple`: If true, accepts an array of references
+ * - `minItems`: Minimum number of references required (only when `multiple: true`)
+ * - `max`: Maximum number of references allowed (only when `multiple: true`)
+ *
+ * @example
+ * ```typescript
+ * // Single reference to an author
+ * const authorField: FieldDefinition = {
+ *   name: "author",
+ *   label: "Author",
+ *   type: "reference",
+ *   required: true,
+ *   options: {
+ *     allowedContentTypes: ["user"],
+ *   },
+ * };
+ *
+ * // Multiple references to related posts (1-5 required)
+ * const relatedPostsField: FieldDefinition = {
+ *   name: "relatedPosts",
+ *   label: "Related Posts",
+ *   type: "reference",
+ *   required: true,
+ *   options: {
+ *     allowedContentTypes: ["blog_post"],
+ *     multiple: true,
+ *     minItems: 1,
+ *     max: 5,
+ *   },
+ * };
+ * ```
+ */
+export declare function validateReferenceField(value: unknown, fieldDef: FieldDefinition): ValidationError[];
+/**
+ * Check if a reference value is valid for a given content type constraint.
+ *
+ * This is a helper function that can be used in mutation handlers to validate
+ * that referenced entries exist and belong to allowed content types.
+ *
+ * @param referenceId - The content entry ID to validate
+ * @param allowedContentTypes - Array of allowed content type names (optional)
+ * @param contentTypeLookup - Function to get content type name by entry ID
+ * @returns Object with `valid` boolean and optional `error` message
+ */
+export declare function validateReferenceContentType(referenceId: string, allowedContentTypes: string[] | undefined, contentTypeLookup: (entryId: string) => Promise<string | null>): Promise<{
+    valid: boolean;
+    error?: string;
+}>;
+/**
+ * Validate a media field value against its configuration.
+ *
+ * Media fields store IDs to media assets. They support:
+ * - Single reference: `string` (one media asset ID)
+ * - Multiple references (gallery): `string[]` (array of media asset IDs) when `multiple: true`
+ *
+ * Configuration options:
+ * - `allowedMimeTypes`: Array of allowed MIME types (supports wildcards like "image/*")
+ * - `multiple`: If true, accepts an array of references (gallery mode)
+ * - `minItems`: Minimum number of media assets required (only when `multiple: true`)
+ * - `max`: Maximum number of media assets allowed (only when `multiple: true`)
+ * - `maxFileSize`: Maximum file size in bytes (validated at upload time, not here)
+ *
+ * Note: MIME type validation requires database lookups and is performed by
+ * `validateAllMediaReferences` in the mediaReferenceResolver module.
+ *
+ * @example
+ * ```typescript
+ * // Single featured image (images only)
+ * const featuredImageField: FieldDefinition = {
+ *   name: "featuredImage",
+ *   label: "Featured Image",
+ *   type: "media",
+ *   required: true,
+ *   options: {
+ *     allowedMimeTypes: ["image/*"],
+ *   },
+ * };
+ *
+ * // Gallery with 2-10 images
+ * const galleryField: FieldDefinition = {
+ *   name: "gallery",
+ *   label: "Photo Gallery",
+ *   type: "media",
+ *   required: true,
+ *   options: {
+ *     allowedMimeTypes: ["image/jpeg", "image/png", "image/webp"],
+ *     multiple: true,
+ *     minItems: 2,
+ *     max: 10,
+ *   },
+ * };
+ * ```
+ */
+export declare function validateMediaField(value: unknown, fieldDef: FieldDefinition): ValidationError[];
+/**
+ * Validate a select field value against its configuration
+ */
+export declare function validateSelectField(value: unknown, fieldDef: FieldDefinition): ValidationError[];
+/**
+ * Validate a multi-select field value against its configuration
+ */
+export declare function validateMultiSelectField(value: unknown, fieldDef: FieldDefinition): ValidationError[];
+/**
+ * Validate a JSON field value
+ */
+export declare function validateJsonField(value: unknown, fieldDef: FieldDefinition): ValidationError[];
+/**
+ * Validate a tags field value against its configuration.
+ *
+ * Tags fields store arrays of taxonomy term IDs for flexible content categorization.
+ * They support:
+ * - Multiple term selection
+ * - Optional inline term creation (when allowCreate is true)
+ * - Min/max limits on number of tags
+ *
+ * Configuration options:
+ * - `taxonomyId`: The taxonomy these tags belong to (required at content type level)
+ * - `allowCreate`: If true, users can create new tags inline
+ * - `minTags`: Minimum number of tags required
+ * - `maxTags`: Maximum number of tags allowed
+ *
+ * @example
+ * ```typescript
+ * const tagsField: FieldDefinition = {
+ *   name: "tags",
+ *   label: "Tags",
+ *   type: "tags",
+ *   required: true,
+ *   options: {
+ *     taxonomyId: "tags_taxonomy_id",
+ *     allowCreate: true,
+ *     minTags: 1,
+ *     maxTags: 10,
+ *   },
+ * };
+ * ```
+ */
+export declare function validateTagsField(value: unknown, fieldDef: FieldDefinition): ValidationError[];
+/**
+ * Validate a category field value against its configuration.
+ *
+ * Category fields store taxonomy term IDs for hierarchical content organization.
+ * They support:
+ * - Single category selection (default)
+ * - Multiple category selection (when allowMultiple is true)
+ *
+ * Configuration options:
+ * - `taxonomyId`: The taxonomy these categories belong to (required at content type level)
+ * - `allowMultiple`: If true, accepts an array of category IDs
+ *
+ * @example
+ * ```typescript
+ * // Single category selection
+ * const categoryField: FieldDefinition = {
+ *   name: "category",
+ *   label: "Category",
+ *   type: "category",
+ *   required: true,
+ *   options: {
+ *     taxonomyId: "categories_taxonomy_id",
+ *   },
+ * };
+ *
+ * // Multiple category selection
+ * const categoriesField: FieldDefinition = {
+ *   name: "categories",
+ *   label: "Categories",
+ *   type: "category",
+ *   required: true,
+ *   options: {
+ *     taxonomyId: "categories_taxonomy_id",
+ *     allowMultiple: true,
+ *   },
+ * };
+ * ```
+ */
+export declare function validateCategoryField(value: unknown, fieldDef: FieldDefinition): ValidationError[];
+/**
+ * Options for validating localized fields.
+ */
+export interface LocalizedValidationOptions {
+    /**
+     * The locale to validate. If provided, only that locale's value is validated
+     * for localized fields. If not provided, all locale values are validated.
+     */
+    locale?: string;
+    /**
+     * Locales that must have values for required localized fields.
+     * If not provided, only checks if at least one locale has a value for required fields.
+     */
+    requiredLocales?: string[];
+}
+/**
+ * Validate a localized field value.
+ *
+ * For localized fields, the value should be a LocalizedFieldValue structure:
+ * `{ "en-US": "Hello", "es-ES": "Hola" }`
+ *
+ * This function validates:
+ * 1. The structure is a valid LocalizedFieldValue
+ * 2. Each locale's value passes the field type validation
+ * 3. Required locales have values (if specified)
+ *
+ * @param value - The localized field value to validate
+ * @param fieldDef - The field definition
+ * @param options - Validation options for localized fields
+ * @returns Array of validation errors
+ */
+export declare function validateLocalizedFieldValue(value: unknown, fieldDef: FieldDefinition, options?: LocalizedValidationOptions): ValidationError[];
+/**
+ * Validate a single field value based on its definition.
+ *
+ * Handles both localized and non-localized fields:
+ * - Non-localized fields: Validates the value directly
+ * - Localized fields: Validates the LocalizedFieldValue structure and each locale's value
+ *
+ * @param value - The field value to validate (plain value or LocalizedFieldValue)
+ * @param fieldDef - The field definition
+ * @param options - Optional validation options for localized fields
+ * @returns Array of validation errors
+ */
+export declare function validateFieldValue(value: unknown, fieldDef: FieldDefinition, options?: LocalizedValidationOptions): ValidationError[];
+/**
+ * Options for validating content data.
+ */
+export interface ContentValidationOptions {
+    /**
+     * If true, reports unknown fields as errors.
+     * If false (default), unknown fields are silently ignored.
+     */
+    strictFields?: boolean;
+    /**
+     * Locale to validate for localized fields.
+     * If provided, only that locale's values are validated.
+     */
+    locale?: string;
+    /**
+     * Locales that must have values for required localized fields.
+     */
+    requiredLocales?: string[];
+}
+/**
+ * Validate content data against a content type schema
+ *
+ * @param data - The content data to validate
+ * @param schema - The content type schema defining expected fields
+ * @param options - Validation options
+ * @returns ValidationResult with any errors found
+ *
+ * @example
+ * ```typescript
+ * // Basic validation
+ * const result = validateContentData(data, schema);
+ *
+ * // Validate with localized field support
+ * const result = validateContentData(data, schema, {
+ *   locale: "en-US",
+ *   requiredLocales: ["en-US", "es-ES"],
+ * });
+ * ```
+ */
+export declare function validateContentData(data: ContentData, schema: ContentTypeSchema, options?: ContentValidationOptions): ValidationResult;
+/**
+ * Apply default values to content data based on field definitions
+ */
+export declare function applyFieldDefaults(data: ContentData, schema: ContentTypeSchema): ContentData;
+/**
+ * Get the field type from a field definition
+ */
+export declare function getFieldType(fieldDef: FieldDefinition): FieldType;
+/**
+ * Check if a field is required based on its configuration
+ */
+export declare function isFieldRequired(fieldDef: FieldDefinition): boolean;
+//# sourceMappingURL=validation.d.ts.map

package/dist/component/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/component/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAM5C;;GAEG;AACH,MAAM,WAAW,YAAY;IAE3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IAGnB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IAGrB,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAGlD,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAGxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAMlD,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,mBAAmB,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAC3B,UAAU,GACV,YAAY,GACZ,YAAY,GACZ,kBAAkB,GAClB,WAAW,GACX,WAAW,GACX,aAAa,GACb,UAAU,GACV,UAAU,GACV,cAAc,GACd,WAAW,GACX,WAAW,GACX,sBAAsB,GACtB,eAAe,GACf,mBAAmB,GACnB,gBAAgB,GAChB,6BAA6B,GAC7B,gBAAgB,CAAC;AAErB,MAAM,MAAM,gBAAgB,GACxB;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,EAAE,CAAA;CAAE,GAC3B;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC;AAMhD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,eAAe,GACxB,eAAe,EAAE,CA4DnB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,eAAe,GACxB,eAAe,EAAE,CA0CnB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,eAAe,GACxB,eAAe,EAAE,CAyDnB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,eAAe,GACxB,eAAe,EAAE,CA6BnB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,eAAe,GACxB,eAAe,EAAE,CAgDnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,eAAe,GACxB,eAAe,EAAE,CAgFnB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,4BAA4B,CAChD,WAAW,EAAE,MAAM,EACnB,mBAAmB,EAAE,MAAM,EAAE,GAAG,SAAS,EACzC,iBAAiB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAC7D,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA0B7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,eAAe,GACxB,eAAe,EAAE,CAgFnB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,eAAe,GACxB,eAAe,EAAE,CA0CnB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,eAAe,GACxB,eAAe,EAAE,CA4DnB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,eAAe,GACxB,eAAe,EAAE,CAiBnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,eAAe,GACxB,eAAe,EAAE,CAwEnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,eAAe,GACxB,eAAe,EAAE,CA+DnB;AAMD;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAmDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,eAAe,EACzB,OAAO,GAAE,0BAA+B,GACvC,eAAe,EAAE,CAyFnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,0BAA0B,GACnC,eAAe,EAAE,CAQnB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,wBAA6B,GACrC,gBAAgB,CAoClB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,iBAAiB,GACxB,WAAW,CAeb;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,SAAS,CAEjE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAElE"}