@resistdesign/voltra 3.0.0-alpha.4 → 3.0.0-alpha.41

package/common/TypeParsing/TypeInfo.d.ts

@@ -0,0 +1,222 @@
+/**
+ * TypeInfo definitions and tags used across parsing and validation.
+ */
+/**
+ * A set of possible operations for a type or field value.
+ *
+ * @category TypeInfo
+ */
+export declare enum TypeOperation {
+    /**
+     * Create operation.
+     */
+    CREATE = "CREATE",
+    /**
+     * Read operation.
+     */
+    READ = "READ",
+    /**
+     * Update operation.
+     */
+    UPDATE = "UPDATE",
+    /**
+     * Delete operation.
+     */
+    DELETE = "DELETE"
+}
+/**
+ * A map of denied operations for a type or field value.
+ * */
+export type DeniedOperations = Partial<Record<TypeOperation, boolean>>;
+/**
+ * Voltra supported `TypeInfo` tags.
+ * */
+export type SupportedTags = Partial<{
+    /**
+     * The human-readable label for the type.
+     * */
+    label: string;
+    /**
+     * Operations that will be denied at the type level.
+     * */
+    deniedOperations: DeniedOperations;
+    /**
+     * Whether a pagination UI should enable full paging or just expect cursor-based paging.
+     * */
+    fullPaging: boolean;
+    /**
+     * Whether this type will be persisted in a storage solution.
+     * */
+    persisted: boolean;
+}>;
+/**
+ * Voltra supported `TypeInfoField` tags.
+ * */
+export type SupportedFieldTags = Partial<{
+    /**
+     * Is this field the primary (uniquely identifying) field for the type?
+     * */
+    primaryField: boolean;
+    /**
+     * The human-readable label for the field.
+     * */
+    label: string;
+    /**
+     * The format or "type" for the field inout.
+     * Example: "number", "email", "tel", etc.
+     * */
+    format: string;
+    /**
+     * Allows a custom entry in a select input.
+     * */
+    allowCustomSelection: boolean;
+    /**
+     * A custom type name used to process the field value with custom validators and/or other custom application features.
+     * */
+    customType: string;
+    /**
+     * Whether this field is displayed in forms, information displays, lists, etc.
+     * */
+    hidden: boolean;
+    /**
+     * Whether a pagination UI should enable full paging or just expect cursor-based paging.
+     * NOTE: This is only used when the field has type reference.
+     * */
+    fullPaging: boolean;
+    /**
+     * A set of constraints for the field value.
+     * */
+    constraints: Partial<{
+        /**
+         * The default value for the field.
+         */
+        defaultValue: any;
+        /**
+         * The step increment for the field.
+         * */
+        step: number;
+        /**
+         * The minimum value for the field.
+         * */
+        min: number;
+        /**
+         * The maximum value for the field.
+         * */
+        max: number;
+        /**
+         * A regex pattern used to validate the field value.
+         * */
+        pattern: string;
+    }>;
+    /**
+     * Operations that will be denied at the field level.
+     * */
+    deniedOperations: DeniedOperations;
+    /**
+     * Validation behavior overrides for field processing.
+     * */
+    validation: Partial<{
+        /**
+         * Whether hidden fields should be validated.
+         * Defaults to false for data-item validation flows that opt into field-level behavior.
+         */
+        validateHidden: boolean;
+        /**
+         * Whether readonly fields should enforce required-value checks.
+         * Defaults to false for data-item validation flows that opt into field-level behavior.
+         */
+        validateReadonly: boolean;
+        /**
+         * Whether empty arrays are accepted for required array fields.
+         * Defaults to false.
+         */
+        emptyArrayIsValid: boolean;
+    }>;
+}>;
+/**
+ * The set of acceptable literal value types.
+ */
+export type LiteralValue = string | number | boolean | null;
+/**
+ * The set of acceptable type keywords.
+ */
+export type TypeKeyword = "string" | "number" | "boolean";
+/**
+ * Information about a field in a type definition.
+ */
+export type TypeInfoField = {
+    /**
+     * Scalar type keyword for the field.
+     */
+    type: TypeKeyword;
+    /**
+     * Referenced TypeInfo type name, when relational.
+     */
+    typeReference?: string;
+    /**
+     * Whether the field is an array.
+     */
+    array: boolean;
+    /**
+     * Whether the field is read-only.
+     */
+    readonly: boolean;
+    /**
+     * Whether the field is optional.
+     */
+    optional: boolean;
+    /**
+     * Allowed literal values for the field.
+     */
+    possibleValues?: LiteralValue[];
+    /**
+     * Optional field tags and constraints.
+     */
+    tags?: SupportedFieldTags;
+};
+/**
+ * Information about a type definition.
+ *
+ * @category TypeInfo
+ */
+export type TypeInfo = {
+    /**
+     * Primary field name for the type.
+     */
+    primaryField?: string;
+    /**
+     * Map of field names to field definitions.
+     */
+    fields?: Record<string, TypeInfoField>;
+    /**
+     * Optional type-level tags.
+     */
+    tags?: SupportedTags;
+    /**
+     * Field name groupings for union type definitions.
+     */
+    unionFieldSets?: string[][];
+};
+/**
+ * A map of type information maps.
+ *
+ * @category TypeInfo
+ */
+export type TypeInfoMap = Record<string, TypeInfo>;
+/**
+ * The necessary information to use a {@link TypeInfo} with the entire {@link TypeInfoMap} containing it.
+ * */
+export type TypeInfoPack = {
+    /**
+     * Entry type name to resolve.
+     */
+    entryTypeName: string;
+    /**
+     * Type info map containing the entry type.
+     */
+    typeInfoMap: TypeInfoMap;
+};
+/**
+ * An actual data item described by type info.
+ * */
+export type TypeInfoDataItem = Record<string, LiteralValue | LiteralValue[]>;

package/common/TypeParsing/Utils.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Field-selection helpers for shaping TypeInfo data items.
+ */
+import { TypeInfo, TypeInfoDataItem } from "./TypeInfo";
+/**
+ * Remove all fields, from a list of selected fields, that are not in the type info.
+ *
+ * @typeParam ItemType - Data item shape for field selection.
+ * @param typeInfo - Type info describing available fields.
+ * @param selectedFields - Fields to filter.
+ * @returns Filtered list of selected fields.
+ * */
+export declare const removeNonexistentFieldsFromSelectedFields: <ItemType extends TypeInfoDataItem>(typeInfo?: TypeInfo, selectedFields?: (keyof ItemType)[]) => (keyof ItemType)[] | undefined;
+/**
+ * Remove all fields, from a list of selected fields, that are a type reference.
+ *
+ * @typeParam ItemType - Data item shape for field selection.
+ * @param typeInfo - Type info describing available fields.
+ * @param selectedFields - Fields to filter.
+ * @returns Filtered list of selected fields.
+ * */
+export declare const removeTypeReferenceFieldsFromSelectedFields: <ItemType>(typeInfo?: TypeInfo, selectedFields?: (keyof ItemType)[]) => (keyof ItemType)[] | undefined;
+/**
+ * Remove all fields, from a data item, that are a type reference.
+ *
+ * @param typeInfo - Type info describing available fields.
+ * @param dataItem - Data item to filter.
+ * @returns Filtered data item.
+ * */
+export declare const removeTypeReferenceFieldsFromDataItem: (typeInfo?: TypeInfo, dataItem?: Partial<TypeInfoDataItem>) => Partial<TypeInfoDataItem>;
+/**
+ * Remove all fields, from a data item, that are not in the type info.
+ *
+ * @param typeInfo - Type info describing available fields.
+ * @param dataItem - Data item to filter.
+ * @returns Filtered data item.
+ * */
+export declare const removeNonexistentFieldsFromDataItem: (typeInfo?: TypeInfo, dataItem?: Partial<TypeInfoDataItem>) => Partial<TypeInfoDataItem>;
+/**
+ * Remove all fields, from a data item, that are not selected.
+ *
+ * @typeParam ItemType - Data item shape for field selection.
+ * @param dataItem - Data item to filter.
+ * @param selectedFields - Fields to include.
+ * @returns Filtered data item.
+ * */
+export declare const removeUnselectedFieldsFromDataItem: <ItemType extends TypeInfoDataItem>(dataItem?: Partial<ItemType>, selectedFields?: (keyof ItemType)[]) => Partial<ItemType>;

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,40 @@
-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 {
+ *   getPathString,
+ *   getSimpleId,
+ * } from "@resistdesign/voltra/common";
+ *
+ * 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 Type Parsing
+ */
+export * from "./TypeParsing";
+/**
+ * @category common
+ * @group Shared Types
+ */
+export * from "./TypeInfoORM";