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

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

@@ -0,0 +1,12 @@
+import { UnionTypeNode } from "typescript";
+import { LiteralValue, TypeKeyword } from "../TypeInfo";
+/**
+ * Determine literal options and base type keyword for a union type.
+ *
+ * @param unionType - Union type node to inspect.
+ * @returns Literal options and inferred type keyword.
+ */
+export declare const checkUnionType: (unionType: UnionTypeNode) => {
+    options: LiteralValue[] | undefined;
+    typeKeyword: TypeKeyword;
+};

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

@@ -0,0 +1,8 @@
+import { Node } from "typescript";
+/**
+ * Extract structured comment tags from a TypeScript node's JSDoc.
+ *
+ * @param node - AST node to read JSDoc tags from.
+ * @returns Nested object of tag values keyed by tag name paths.
+ */
+export declare const extractCommentTags: (node: Node) => Record<any, any>;

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

@@ -0,0 +1,12 @@
+import { UnionTypeNode } from "typescript";
+import { LiteralValue, TypeKeyword } from "../TypeInfo";
+/**
+ * Extract literal values and inferred keyword from a union of literals.
+ *
+ * @param node - Union type node containing literal members.
+ * @returns Literal values and detected type keyword, or undefined if mixed.
+ */
+export declare const extractLiteralValues: (node: UnionTypeNode) => {
+    values: LiteralValue[];
+    type: TypeKeyword;
+} | undefined;

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

@@ -0,0 +1,14 @@
+import { TypeNode } from "typescript";
+import { LiteralValue, TypeKeyword } from "../TypeInfo";
+/**
+ * Extract TypeInfo field details from a type node.
+ *
+ * @param type - Type node to inspect.
+ * @returns Type details including keyword, reference, array flag, and options.
+ */
+export declare const extractTypeDetails: (type: TypeNode) => {
+    type: TypeKeyword;
+    typeReference?: string;
+    array: boolean;
+    options?: LiteralValue[];
+};

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

@@ -0,0 +1,18 @@
+import { TypeInfo } from "../TypeInfo";
+/**
+ * Errors raised while resolving primary fields.
+ */
+export declare enum TypeInfoPrimaryFieldErrors {
+    /**
+     * Primary field cannot be read due to denied operations.
+     * */
+    READ_DENIED_PRIMARY_FIELD_NOT_SUPPORTED = "READ_DENIED_PRIMARY_FIELD_NOT_SUPPORTED"
+}
+/**
+ * Resolve the primary field name for a TypeInfo definition.
+ *
+ * @param typeInfo - TypeInfo definition to inspect.
+ * @returns Primary field name, if available.
+ * @throws Error when the primary field is read-denied.
+ */
+export declare const getPrimaryFieldForTypeInfo: (typeInfo: TypeInfo) => string | undefined;

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

@@ -0,0 +1,9 @@
+import { TypeLiteralNode } from "typescript";
+import { TypeInfo } from "../TypeInfo";
+/**
+ * Build a TypeInfo definition from a type literal node.
+ *
+ * @param typeLiteral - Type literal node to inspect.
+ * @returns TypeInfo definition with fields and tags.
+ */
+export declare const getTypeInfo: (typeLiteral: TypeLiteralNode) => TypeInfo;

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

@@ -0,0 +1,9 @@
+import { PropertySignature } from "typescript";
+import { TypeInfoField } from "../TypeInfo";
+/**
+ * Build TypeInfo field metadata from a property signature.
+ *
+ * @param propertySignature - Property signature node to inspect.
+ * @returns TypeInfo field metadata.
+ */
+export declare const getTypeInfoField: (propertySignature: PropertySignature) => TypeInfoField;

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

@@ -0,0 +1,11 @@
+import { TypeNode } from "typescript";
+import type { TypeMap } from "../../../build/TypeMapping";
+import { TypeInfo } from "../TypeInfo";
+/**
+ * Resolve TypeInfo for a type alias node based on its kind.
+ *
+ * @param type - Alias type node to inspect.
+ * @param typeMap - Map of available type aliases.
+ * @returns Resolved TypeInfo or undefined when unsupported.
+ */
+export declare const getTypeInfoFromAliasType: (type: TypeNode, typeMap: TypeMap) => TypeInfo | undefined;

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

@@ -0,0 +1,12 @@
+import { TypeReferenceNode } from "typescript";
+import type { TypeMap } from "../../../build/TypeMapping";
+import { TypeInfo } from "../TypeInfo";
+/**
+ * Resolve TypeInfo for field-filter helper types (Pick/Omit/Exclude).
+ *
+ * @param typeNameStr - Type name or filter identifier.
+ * @param typeRef - Type reference node with type arguments.
+ * @param typeMap - Map of available type aliases.
+ * @returns Filtered TypeInfo or undefined when not resolvable.
+ */
+export declare const getTypeInfoFromFieldFilter: (typeNameStr: string | undefined, typeRef: TypeReferenceNode, typeMap: TypeMap) => TypeInfo | undefined;

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

@@ -0,0 +1,11 @@
+import { TypeAliasDeclaration } from "typescript";
+import type { TypeMap } from "../../../build/TypeMapping";
+import { TypeInfo } from "../TypeInfo";
+/**
+ * Resolve TypeInfo for a type alias declaration.
+ *
+ * @param typeAliasDec - Type alias declaration node.
+ * @param typeMap - Map of available type aliases.
+ * @returns Resolved TypeInfo or undefined when unsupported.
+ */
+export declare const getTypeInfoFromTypeAlias: (typeAliasDec: TypeAliasDeclaration, typeMap: TypeMap) => TypeInfo | undefined;

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

@@ -0,0 +1,9 @@
+import { TypeNode } from "typescript";
+import { TypeKeyword } from "../TypeInfo";
+/**
+ * Resolve a TypeScript type node into a TypeInfo keyword.
+ *
+ * @param node - Type node to inspect.
+ * @returns TypeInfo keyword (string, number, boolean).
+ */
+export declare const getTypeKeyword: (node: TypeNode) => TypeKeyword;

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/common/TypeParsing/TypeInfo.d.ts

@@ -0,0 +1,235 @@
+/**
+ * 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;
+    }>;
+    /**
+     * Indexing behavior flags used to derive ORM indexing configuration.
+     * */
+    indexed: Partial<{
+        /**
+         * Whether this field should be added to the type's default full-text index fields.
+         * */
+        fullText: boolean;
+        /**
+         * Whether this field should be added to the type's structured indexed field list.
+         * */
+        structured: 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>;