@resistdesign/voltra 3.0.0-alpha.2 → 3.0.0-alpha.21

package/common/TypeParsing/ParsingUtils/getUnionOrIntersectionTypeInfo.d.ts

@@ -0,0 +1,11 @@
+import { IntersectionTypeNode, UnionTypeNode } from "typescript";
+import type { TypeMap } from "../../../build/TypeMapping";
+import { TypeInfo } from "../TypeInfo";
+/**
+ * Resolve TypeInfo for union or intersection types.
+ *
+ * @param unionType - Union or intersection type node to inspect.
+ * @param typeMap - Map of available type aliases.
+ * @returns Resolved TypeInfo or undefined when unsupported.
+ */
+export declare const getUnionOrIntersectionTypeInfo: (unionType: UnionTypeNode | IntersectionTypeNode, typeMap: TypeMap) => TypeInfo | undefined;

package/common/TypeParsing/ParsingUtils/getUnionOrLiteralStringValues.d.ts

@@ -0,0 +1,8 @@
+import { Node } from "typescript";
+/**
+ * Extract string literal values from a union or literal type node.
+ *
+ * @param node - Type node to inspect.
+ * @returns List of literal values as strings.
+ */
+export declare const getUnionOrLiteralStringValues: (node?: Node) => string[];

package/{src/common → common}/TypeParsing/TypeInfo.d.ts

@@ -1,10 +1,27 @@
+/**
+ * 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"
 }
 /**
@@ -108,32 +125,75 @@ 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;
 };
 /**

package/{src/common → common}/TypeParsing/Utils.d.ts

@@ -1,21 +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/{src/common → common}/TypeParsing/Validation.d.ts

@@ -1,7 +1,25 @@
+/**
+ * @packageDocumentation
+ *
+ * Validation helpers for TypeInfo values, including relationship rules and
+ * custom type validators.
+ */
 import { TypeInfo, 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"
 }
 /**
@@ -22,13 +40,34 @@ export type ErrorMap = {
  * 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: string;
+    /**
+     * Field-level error mapping.
+     */
     errorMap: ErrorMap;
 };
+/**
+ * Error code for custom type validation failures.
+ */
 export declare const INVALID_CUSTOM_TYPE = "INVALID_CUSTOM_TYPE";
+/**
+ * Error codes for primitive type validation failures.
+ */
 export declare const PRIMITIVE_ERROR_MESSAGE_CONSTANTS: Record<TypeKeyword, string>;
+/**
+ * Error codes for TypeInfo validation failures.
+ */
 export declare const ERROR_MESSAGE_CONSTANTS: {
     MISSING: string;
     INVALID_OPTION: string;
@@ -40,6 +79,9 @@ export declare const ERROR_MESSAGE_CONSTANTS: {
     INVALID_PATTERN: string;
     VALUE_DOES_NOT_MATCH_PATTERN: string;
 };
+/**
+ * Error codes for denied type operations.
+ */
 export declare const DENIED_TYPE_OPERATIONS: Record<TypeOperation, string>;
 /**
  * Validates a value against a pattern.
@@ -48,10 +90,19 @@ export declare const DENIED_TYPE_OPERATIONS: Record<TypeOperation, string>;
  * `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;
 /**
@@ -60,33 +111,87 @@ export declare const getValidityValue: (existing: boolean, pending: boolean) =>
 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;
 /**
  * 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

@@ -0,0 +1,50 @@
+/**
+ * @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 { TypeOperation, } from "./TypeParsing/TypeInfo";
+/**
+ * @category common
+ * @group Type Parsing
+ */
+export type { DeniedOperations, SupportedFieldTags, SupportedTags, TypeInfo, TypeInfoField, TypeInfoMap, } from "./TypeParsing/TypeInfo";
+/**
+ * @category common
+ * @group Shared Types
+ */
+export { TypeInfoORMServiceError, } from "./TypeInfoORM/Types";
+/**
+ * @category common
+ * @group Type Parsing
+ */
+export * from "./TypeParsing/Validation";