@resistdesign/voltra 3.0.0-alpha.5 → 3.0.0-alpha.51

package/common/TypeParsing/Validation.d.ts

@@ -0,0 +1,327 @@
+/**
+ * @packageDocumentation
+ *
+ * Validation helpers for TypeInfo values, including relationship rules and
+ * custom type validators.
+ */
+import { TypeInfo, TypeInfoDataItem, TypeInfoField, TypeInfoMap, TypeKeyword, TypeOperation } from "./TypeInfo";
+/**
+ * Relationship validation behavior for TypeInfo checks.
+ */
+export declare enum RelationshipValidationType {
+    /**
+     * Include relationship values in validation.
+     */
+    INCLUDE = "INCLUDE",
+    /**
+     * Exclude relationship values from validation.
+     */
+    EXCLUDE = "EXCLUDE",
+    /**
+     * Disallow relationship values entirely.
+     */
+    STRICT_EXCLUDE = "STRICT_EXCLUDE"
+}
+/**
+ * A custom type info field validator.
+ * */
+export type CustomTypeInfoFieldValidator = (value: any) => boolean;
+/**
+ * A map of custom type info field validators.
+ * */
+export type CustomTypeInfoFieldValidatorMap = Record<string, CustomTypeInfoFieldValidator>;
+/**
+ * A custom field validator that can return a domain-specific error descriptor.
+ */
+export type FieldValueValidator = (value: any, typeInfoField: TypeInfoField) => ErrorDescriptor;
+/**
+ * A map of custom field validators by field key.
+ */
+export type FieldValueValidatorMap = Record<string, FieldValueValidator>;
+/**
+ * Error code for custom type validation failures.
+ */
+export declare const INVALID_CUSTOM_TYPE = "INVALID_CUSTOM_TYPE";
+/**
+ * Error codes for primitive type validation failures.
+ *
+ * Keys intentionally match `typeof value` results.
+ */
+export declare const PRIMITIVE_ERROR_MESSAGE_CONSTANTS: {
+    readonly string: "NOT_A_STRING";
+    readonly number: "NOT_A_NUMBER";
+    readonly boolean: "NOT_A_BOOLEAN";
+};
+/**
+ * Error codes for denied type operations.
+ *
+ * Keys intentionally match `TypeOperation` names.
+ */
+export declare const DENIED_TYPE_OPERATIONS: {
+    readonly CREATE: "DENIED_TYPE_OPERATION_CREATE";
+    readonly READ: "DENIED_TYPE_OPERATION_READ";
+    readonly UPDATE: "DENIED_TYPE_OPERATION_UPDATE";
+    readonly DELETE: "DENIED_TYPE_OPERATION_DELETE";
+};
+/**
+ * Error codes for TypeInfo validation failures.
+ *
+ * Uses canonical string-valued keys (for example `NOT_A_STRING` and
+ * `DENIED_TYPE_OPERATION_CREATE`) so consumers can key by code values.
+ */
+export declare const ERROR_MESSAGE_CONSTANTS: {
+    readonly NONE: "NONE";
+    readonly INVALID_CUSTOM_TYPE: "INVALID_CUSTOM_TYPE";
+    readonly NOT_A_STRING: "NOT_A_STRING";
+    readonly NOT_A_NUMBER: "NOT_A_NUMBER";
+    readonly NOT_A_BOOLEAN: "NOT_A_BOOLEAN";
+    readonly DENIED_TYPE_OPERATION_CREATE: "DENIED_TYPE_OPERATION_CREATE";
+    readonly DENIED_TYPE_OPERATION_READ: "DENIED_TYPE_OPERATION_READ";
+    readonly DENIED_TYPE_OPERATION_UPDATE: "DENIED_TYPE_OPERATION_UPDATE";
+    readonly DENIED_TYPE_OPERATION_DELETE: "DENIED_TYPE_OPERATION_DELETE";
+    readonly MISSING_FIELD_VALUE: "MISSING_FIELD_VALUE";
+    readonly INVALID_OPTION: "INVALID_OPTION";
+    readonly INVALID_FIELD: "INVALID_FIELD";
+    readonly RELATIONSHIP_VALUES_ARE_STRICTLY_EXCLUDED: "RELATIONSHIP_VALUES_ARE_STRICTLY_EXCLUDED";
+    readonly INVALID_TYPE: "INVALID_TYPE";
+    readonly NO_UNION_TYPE_MATCHED: "NO_UNION_TYPE_MATCHED";
+    readonly TYPE_DOES_NOT_EXIST: "TYPE_DOES_NOT_EXIST";
+    readonly INVALID_PATTERN: "INVALID_PATTERN";
+    readonly VALUE_DOES_NOT_MATCH_PATTERN: "VALUE_DOES_NOT_MATCH_PATTERN";
+    readonly VALUE_BELOW_MINIMUM: "VALUE_BELOW_MINIMUM";
+    readonly VALUE_ABOVE_MAXIMUM: "VALUE_ABOVE_MAXIMUM";
+};
+export type ErrorCode = (typeof ERROR_MESSAGE_CONSTANTS)[keyof typeof ERROR_MESSAGE_CONSTANTS];
+/**
+ * Primitive type keyword to error code mapping used during validation.
+ */
+export declare const TYPE_KEYWORD_ERROR_MESSAGE_CONSTANTS: Record<TypeKeyword, ErrorCode>;
+/**
+ * A descriptor for a validation error.
+ */
+export type ErrorDescriptor = {
+    code: ErrorCode | string;
+    values?: string[];
+};
+/**
+ * A map of errors for an array of items.
+ */
+export type ArrayItemErrorMap = {
+    [index: number]: ErrorDescriptor[];
+};
+/**
+ * A descriptor for an array of errors.
+ */
+export type ArrayErrorDescriptorCollection = {
+    itemErrorMap: ArrayItemErrorMap;
+};
+/**
+ * A map of errors.
+ */
+export type ErrorMap = {
+    [key: string]: (ErrorDescriptor | ArrayErrorDescriptorCollection)[];
+};
+/**
+ * The validation results for type info fields.
+ */
+export type TypeInfoValidationResults = {
+    /**
+     * Type name being validated.
+     */
+    typeName: string | null;
+    /**
+     * Whether the validation passed.
+     */
+    valid: boolean;
+    /**
+     * Primary error code when validation fails.
+     */
+    error: ErrorDescriptor;
+    /**
+     * Field-level error mapping.
+     */
+    errorMap: ErrorMap;
+};
+/**
+ * Creates an error descriptor from a code and optional values.
+ */
+export declare const getErrorDescriptor: (code?: ErrorCode | string, values?: string[]) => ErrorDescriptor;
+/**
+ * Creates a descriptor representing the absence of an error.
+ */
+export declare const getNoErrorDescriptor: () => ErrorDescriptor;
+/**
+ * Type guard for array-item error collection entries.
+ */
+export declare const isArrayErrorDescriptorCollection: (value: ErrorDescriptor | ArrayErrorDescriptorCollection) => value is ArrayErrorDescriptorCollection;
+/**
+ * Returns only descriptor entries from a mixed error entry list.
+ */
+export declare const getErrorDescriptors: (values?: (ErrorDescriptor | ArrayErrorDescriptorCollection)[]) => ErrorDescriptor[];
+/**
+ * Merges all array-item error maps from a mixed entry list.
+ */
+export declare const getArrayItemErrorMap: (values?: (ErrorDescriptor | ArrayErrorDescriptorCollection)[]) => ArrayItemErrorMap;
+/**
+ * Validates a value against a pattern.
+ *
+ * `value` must be a string or not supplied.
+ * `pattern` must be a string or not supplied.
+ *
+ * If either are not supplied, the result is valid.
+ *
+ * @param typeName - Type name for the validation context.
+ * @param value - Value to validate.
+ * @param pattern - Regex pattern to validate against.
+ * @returns Validation results for the pattern.
+ * */
+export declare const validateValueMatchesPattern: (typeName: string, value?: any, pattern?: string) => TypeInfoValidationResults;
+/**
+ * Gets the validity value.
+ *
+ * @param existing - Current validity value.
+ * @param pending - New validity value.
+ * @returns Updated validity value.
+ */
+export declare const getValidityValue: (existing: boolean, pending: boolean) => boolean;
+/**
+ * The validators for primitive values.
+ */
+export declare const TYPE_KEYWORD_VALIDATORS: Record<TypeKeyword, (value: any) => boolean>;
+/**
+ * Checks if a value has a value.
+ *
+ * @param value - Value to check.
+ * @returns Whether the value is present.
+ */
+export declare const hasValue: (value: any) => boolean;
+/**
+ * Validates a primitive value.
+ *
+ * @param value - Value to validate.
+ * @param type - Primitive type keyword.
+ * @returns Whether the value matches the type.
+ */
+export declare const validateKeywordType: (value: any, type: string) => boolean;
+/**
+ * Validates a custom type.
+ *
+ * @param value - Value to validate.
+ * @param customType - Custom type name.
+ * @param customValidators - Custom validators map.
+ * @returns Whether the value passes custom validation.
+ */
+export declare const validateCustomType: (value: any, customType?: string, customValidators?: CustomTypeInfoFieldValidatorMap) => boolean;
+/**
+ * Validates a type info field value.
+ *
+ * @param value - Value to validate.
+ * @param typeInfoField - Field metadata.
+ * @param typeInfoMap - Type info map for referenced types.
+ * @param ignoreArray - Whether to ignore array validation.
+ * @param strict - Whether to validate unknown fields and unions strictly.
+ * @param customValidators - Custom validators map.
+ * @param typeOperation - Operation being validated.
+ * @param relationshipValidationType - Relationship validation behavior.
+ * @param itemIsPartial - Whether the item is partial.
+ * @returns Validation results for the field.
+ */
+export declare const validateTypeInfoFieldValue: (value: any, typeInfoField: TypeInfoField, typeInfoMap: TypeInfoMap, ignoreArray?: boolean, strict?: boolean, customValidators?: CustomTypeInfoFieldValidatorMap, typeOperation?: TypeOperation, relationshipValidationType?: RelationshipValidationType, itemIsPartial?: boolean) => TypeInfoValidationResults;
+/**
+ * Validates an array of type info field values.
+ *
+ * @param values - Values to validate.
+ * @param typeInfoField - Field metadata.
+ * @param typeInfoMap - Type info map for referenced types.
+ * @param strict - Whether to validate unknown fields and unions strictly.
+ * @param customValidators - Custom validators map.
+ * @param typeOperation - Operation being validated.
+ * @param relationshipValidationType - Relationship validation behavior.
+ * @param itemIsPartial - Whether the item is partial.
+ * @returns Validation results for the array.
+ */
+export declare const validateArrayOfTypeInfoFieldValues: (values: any[] | undefined, typeInfoField: TypeInfoField, typeInfoMap: TypeInfoMap, strict?: boolean, customValidators?: CustomTypeInfoFieldValidatorMap, typeOperation?: TypeOperation, relationshipValidationType?: RelationshipValidationType, itemIsPartial?: boolean) => TypeInfoValidationResults;
+/**
+ * Validates a type info field operation.
+ *
+ * @param fieldName - Field name to validate.
+ * @param fieldOperation - Operation to validate.
+ * @param typeInfoField - Field metadata.
+ * @returns Validation results for the field operation.
+ * */
+export declare const validateTypeInfoFieldOperationAllowed: (fieldName: string, fieldOperation?: TypeOperation, typeInfoField?: TypeInfoField) => TypeInfoValidationResults;
+/**
+ * Validates a type info operation.
+ *
+ * @param typeName - Type name to validate.
+ * @param valueFields - Fields included in the operation.
+ * @param typeOperation - Operation to validate.
+ * @param typeInfo - Type info metadata.
+ * @returns Validation results for the type operation.
+ * */
+export declare const validateTypeOperationAllowed: (typeName: string, valueFields: string[], typeOperation: TypeOperation, typeInfo: TypeInfo) => TypeInfoValidationResults;
+/**
+ * Options for validating a data item against a single TypeInfo definition.
+ */
+export type ValidateTypeInfoDataItemOptions = {
+    /**
+     * Type name used for result metadata and nested lookups.
+     */
+    typeName?: string;
+    /**
+     * Additional types used for nested type references.
+     */
+    typeInfoMap?: TypeInfoMap;
+    /**
+     * Whether unknown fields should fail validation.
+     */
+    strict?: boolean;
+    /**
+     * Custom validators for `tags.customType` handling.
+     */
+    customTypeValidators?: CustomTypeInfoFieldValidatorMap;
+    /**
+     * Operation context for denied operation checks.
+     */
+    typeOperation?: TypeOperation;
+    /**
+     * Relationship validation behavior.
+     */
+    relationshipValidationType?: RelationshipValidationType;
+    /**
+     * Whether this is a partial payload.
+     */
+    itemIsPartial?: boolean;
+    /**
+     * Default hidden-field validation behavior.
+     */
+    validateHidden?: boolean;
+    /**
+     * Default readonly-field required-value behavior.
+     */
+    validateReadonly?: boolean;
+};
+/**
+ * Validates a data item against a TypeInfo definition.
+ *
+ * @param value - Data item to validate.
+ * @param typeInfo - TypeInfo definition used for validation.
+ * @param customValidatorMap - Optional custom validators keyed by field.
+ * @param options - Validation behavior options.
+ * @returns Validation result for the entire item.
+ */
+export declare const validateTypeInfoDataItem: (value: Partial<TypeInfoDataItem> | undefined, typeInfo: TypeInfo, customValidatorMap?: FieldValueValidatorMap, options?: ValidateTypeInfoDataItemOptions) => TypeInfoValidationResults;
+/**
+ * Validates a type info value.
+ *
+ * @param value - Value to validate.
+ * @param typeInfoFullName - Fully qualified type name.
+ * @param typeInfoMap - Type info map for referenced types.
+ * @param strict - Whether to validate unknown fields and unions strictly.
+ * @param customValidators - Custom validators map.
+ * @param typeOperation - Operation being validated.
+ * @param relationshipValidationType - Relationship validation behavior.
+ * @param itemIsPartial - Whether the item is partial.
+ * @returns Validation results for the value.
+ */
+export declare const validateTypeInfoValue: (value: any, typeInfoFullName: string, typeInfoMap: TypeInfoMap, strict?: boolean, customValidators?: CustomTypeInfoFieldValidatorMap, typeOperation?: TypeOperation, relationshipValidationType?: RelationshipValidationType, itemIsPartial?: boolean) => TypeInfoValidationResults;

package/common/TypeParsing/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @packageDocumentation
+ *
+ * Includes TypeInfo definitions, validation helpers, and AST mapping.
+ */
+export * from "./Validation";
+export * from "./TypeInfo";
+export * from "./Constants";

package/common/index.d.ts

@@ -1,4 +1,47 @@
-export { b as IDGeneration, d as ItemRelationships, f as Logging, R as Routing, S as SearchUtils, c as StringTransformers, e as Testing, a as TypeParsing } from '../index-C3-iD9Mh.js';
-export { H as HelperTypes, l as ItemRelationshipInfoTypes, m as SearchTypes } from '../SearchTypes-DjN6YQzE.js';
-import '../Validation-CFP59oIP.js';
-import 'typescript';
+/**
+ * @packageDocumentation
+ *
+ * Common module exports for shared utilities, types, and helpers used across
+ * app, API, and IaC layers.
+ *
+ * Import from the common subpath only:
+ * ```ts
+ * import {
+ *   getPathArray,
+ *   getPathString,
+ *   getSimpleId,
+ * } from "@resistdesign/voltra/common";
+ *
+ * const segments = getPathArray("/users/42", "/", true, true, false, false);
+ * const path = getPathString(["users", 42], "/", true, false);
+ * const id = getSimpleId();
+ * ```
+ *
+ * See also: `@resistdesign/voltra/app`, `@resistdesign/voltra/api`, and
+ * `@resistdesign/voltra/iac`.
+ */
+/**
+ * @category common
+ * @group Shared Types
+ */
+export type * from "./HelperTypes";
+/**
+ * @category common
+ * @group Command Line
+ */
+export * from "./CommandLine";
+/**
+ * @category common
+ * @group Routing
+ */
+export * from "./Routing";
+/**
+ * @category common
+ * @group Type Parsing
+ */
+export * from "./TypeParsing";
+/**
+ * @category common
+ * @group Shared Types
+ */
+export * from "./TypeInfoORM";