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

package/common/Routing.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Helpers for parsing and composing path strings used by the Router utilities.
+ */
+/**
+ * The delimiter used to separate paths.
+ */
+export declare const PATH_DELIMITER = "/";
+/**
+ * Parse a string into JSON if possible, otherwise return the raw value.
+ *
+ * @param value - Input string to parse.
+ * @returns Parsed JSON or the original string.
+ */
+export declare const getPotentialJSONValue: (value: string) => any;
+/**
+ * Get the path segments from a path string.
+ *
+ * @param path - Path string to split.
+ * @param delimiter - Delimiter used to split the path.
+ * @param filterEmptyOutput - Whether to remove empty output segments.
+ * @param filterEmptyInput - Whether to remove empty input segments.
+ * @param useJson - Whether to parse each segment as JSON.
+ * @param uriDecodeParts - Whether to URI-decode each segment.
+ * @returns Array of path segments.
+ * */
+export declare const getPathArray: (path: string, delimiter?: string, filterEmptyOutput?: boolean, filterEmptyInput?: boolean, useJson?: boolean, uriDecodeParts?: boolean) => any[];
+/**
+ * Get the path string from path segments.
+ *
+ * @param parts - Path segments to join.
+ * @param delimiter - Delimiter used to join the path.
+ * @param filterEmptyInput - Whether to remove empty input segments.
+ * @param useJson - Whether to JSON-stringify each segment.
+ * @param uriEncodeParts - Whether to URI-encode each segment.
+ * @returns Joined path string.
+ * */
+export declare const getPathString: (parts?: any[], delimiter?: string, filterEmptyInput?: boolean, useJson?: boolean, uriEncodeParts?: boolean) => string;
+/**
+ * Merge two path strings.
+ *
+ * @param path1 - First path string.
+ * @param path2 - Second path string.
+ * @param delimiter - Delimiter used to split and join paths.
+ * @param filterEmptyOutput - Whether to remove empty output segments.
+ * @param filterEmptyInput - Whether to remove empty input segments.
+ * @param useJson - Whether to parse/serialize segments as JSON.
+ * @param uriEncodeParts - Whether to URI-encode each segment.
+ * @returns Merged path string.
+ * */
+export declare const mergeStringPaths: (path1: string, path2: string, delimiter?: string, filterEmptyOutput?: boolean, filterEmptyInput?: boolean, useJson?: boolean, uriEncodeParts?: boolean) => string;
+/**
+ * Resolve a path string against another path string.
+ *
+ * @param currentPath - Base path to resolve against.
+ * @param newPath - New path to resolve, absolute or relative.
+ * @returns Resolved path string.
+ * */
+export declare const resolvePath: (currentPath: string, newPath: string) => string;
+/**
+ * Resolve RouteAdapter navigation input against the current path.
+ *
+ * Rules:
+ * - `"/x"` resolves from root.
+ * - `"x"` and `"./x"` resolve under current path.
+ * - `"../x"` resolves one level up per `..`.
+ * - `"/"` and `""` both resolve to root (`"/"`).
+ *
+ * @param currentPath - Current absolute path (query/hash ignored).
+ * @param nextPath - Adapter navigation target (absolute or relative).
+ * @returns Resolved absolute path string.
+ */
+export declare const resolveRouteAdapterPath: (currentPath: string, nextPath: string) => string;
+/**
+ * Get the parameter values from a path string and test the `path` against a `testPath`.
+ *
+ * @param path - Actual path to test.
+ * @param testPath - Route pattern to match against.
+ * @param exact - Whether to require an exact match.
+ * @returns Params object when matched, otherwise false.
+ * */
+export declare const getParamsAndTestPath: (path: string, testPath: string, exact?: boolean) => Record<string, any> | false;

package/common/SearchTypes.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Search-related types used by list/search APIs.
+ */
+import { ItemRelationshipInfo, ItemRelationshipOriginItemInfo } from "./ItemRelationshipInfoTypes";
+/**
+ * The logical operators for a search criteria.
+ * */
+export declare enum LogicalOperators {
+    /**
+     * Require all criteria to match.
+     * */
+    AND = "AND",
+    /**
+     * Require any criteria to match.
+     * */
+    OR = "OR"
+}
+/**
+ * The comparison operators for a field criterion.
+ * */
+export declare enum ComparisonOperators {
+    /**
+     * Field value equals the criterion value.
+     * */
+    EQUALS = "EQUALS",
+    /**
+     * Field value does not equal the criterion value.
+     * */
+    NOT_EQUALS = "NOT_EQUALS",
+    /**
+     * Field value is greater than the criterion value.
+     * */
+    GREATER_THAN = "GREATER_THAN",
+    /**
+     * Field value is greater than or equal to the criterion value.
+     * */
+    GREATER_THAN_OR_EQUAL = "GREATER_THAN_OR_EQUAL",
+    /**
+     * Field value is less than the criterion value.
+     * */
+    LESS_THAN = "LESS_THAN",
+    /**
+     * Field value is less than or equal to the criterion value.
+     * */
+    LESS_THAN_OR_EQUAL = "LESS_THAN_OR_EQUAL",
+    /**
+     * Field value is in the provided options.
+     * */
+    IN = "IN",
+    /**
+     * Field value is not in the provided options.
+     * */
+    NOT_IN = "NOT_IN",
+    /**
+     * Field value contains the criterion value as a substring.
+     * */
+    LIKE = "LIKE",
+    /**
+     * Field value does not contain the criterion value as a substring.
+     * */
+    NOT_LIKE = "NOT_LIKE",
+    /**
+     * Field value exists and is not null.
+     * */
+    EXISTS = "EXISTS",
+    /**
+     * Field value is missing or null.
+     * */
+    NOT_EXISTS = "NOT_EXISTS",
+    /**
+     * Field value is not empty.
+     * */
+    IS_NOT_EMPTY = "IS_NOT_EMPTY",
+    /**
+     * Field value is empty.
+     * */
+    IS_EMPTY = "IS_EMPTY",
+    /**
+     * Field value is within an inclusive range.
+     * */
+    BETWEEN = "BETWEEN",
+    /**
+     * Field value is outside an inclusive range.
+     * */
+    NOT_BETWEEN = "NOT_BETWEEN",
+    /**
+     * Field value array contains the criterion value.
+     * */
+    CONTAINS = "CONTAINS",
+    /**
+     * Field value array does not contain the criterion value.
+     * */
+    NOT_CONTAINS = "NOT_CONTAINS",
+    /**
+     * Field value starts with the criterion value.
+     * */
+    STARTS_WITH = "STARTS_WITH",
+    /**
+     * Field value ends with the criterion value.
+     * */
+    ENDS_WITH = "ENDS_WITH",
+    /**
+     * Field value does not start with the criterion value.
+     * */
+    DOES_NOT_START_WITH = "DOES_NOT_START_WITH",
+    /**
+     * Field value does not end with the criterion value.
+     * */
+    DOES_NOT_END_WITH = "DOES_NOT_END_WITH"
+}
+/**
+ * The field criterion for a search criteria.
+ * */
+export type FieldCriterion = {
+    /**
+     * Field name to compare.
+     * */
+    fieldName: string;
+    /**
+     * Comparison operator to apply.
+     * */
+    operator?: ComparisonOperators;
+    /**
+     * Custom operator label when using backend-specific operators.
+     * */
+    customOperator?: string;
+    /**
+     * Primary comparison value.
+     * */
+    value?: any;
+    /**
+     * Comparison value options (e.g., IN/BETWEEN).
+     * */
+    valueOptions?: any[];
+};
+/**
+ * The criteria for a search.
+ * */
+export type SearchCriteria = {
+    /**
+     * Logical operator to apply across field criteria.
+     * */
+    logicalOperator: LogicalOperators;
+    /**
+     * Field-level criteria to evaluate.
+     * */
+    fieldCriteria: FieldCriterion[];
+};
+/**
+ * The results from a request to list items.
+ * */
+export type ListItemsResults<ItemType extends Record<any, any>> = {
+    /**
+     * Cursor for paging into the next page, when available.
+     * */
+    cursor?: string;
+    /**
+     * Items returned by the request.
+     * */
+    items: ItemType[];
+};
+/**
+ * The information used to sort a list of items by a specified field.
+ * */
+export type SortField = {
+    /**
+     * Field name to sort by.
+     * */
+    field?: string;
+    /**
+     * Whether to reverse sort order.
+     * */
+    reverse?: boolean;
+};
+/**
+ * The data used to page a specific set of search results that uses full paging.
+ * @see SupportedTags.fullPaging
+ * */
+export type StandardExpandedPagingCursor = {
+    /**
+     * Current page number.
+     * */
+    currentPage?: number;
+    /**
+     * Total number of pages available.
+     * */
+    totalPages?: number;
+};
+/**
+ * The information for paging through a list of items.
+ * */
+export type PagingInfo = {
+    /**
+     * Items per page to request.
+     * */
+    itemsPerPage?: number;
+    /**
+     * Cursor token for paging.
+     * */
+    cursor?: string;
+};
+/**
+ * The configuration for listing and searching for items.
+ * */
+export type ListItemsConfig = PagingInfo & {
+    /**
+     * Structured search criteria.
+     * */
+    criteria?: SearchCriteria;
+    /**
+     * Sort fields to apply.
+     * */
+    sortFields?: SortField[];
+};
+/**
+ * A configuration for listing relationships.
+ * */
+export type ListRelationshipsConfig = PagingInfo & {
+    /**
+     * Relationship origin info used to filter related records.
+     * */
+    relationshipItemOrigin: ItemRelationshipOriginItemInfo;
+};
+/**
+ * The results from a request to list relationships.
+ * */
+export type ListRelationshipsResults = ListItemsResults<ItemRelationshipInfo>;

package/common/SearchUtils.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Filtering and sorting utilities for search criteria.
+ */
+import { TypeInfoDataItem, TypeInfoMap } from "./TypeParsing/TypeInfo";
+import { ComparisonOperators, FieldCriterion, SearchCriteria, SortField } from "./SearchTypes";
+/**
+ * Basic comparison operators for filtering data.
+ * */
+export declare const COMPARATORS: Record<ComparisonOperators, (
+/**
+ * Criterion value to compare against.
+ * */
+criterionValue: any, 
+/**
+ * Criterion options for operators like IN/BETWEEN.
+ * */
+criterionValueOptions: any[] | undefined, 
+/**
+ * Field value from the item.
+ * */
+fieldValue: any) => boolean>;
+/**
+ * Compare a field criterion to a field value.
+ *
+ * @param fieldCriterion - Criterion to compare.
+ * @param fieldValue - Field value to test.
+ * @returns Whether the criterion matches the field value.
+ * */
+export declare const compare: (fieldCriterion: FieldCriterion, fieldValue: any) => boolean;
+/**
+ * Compare a field criterion to an array of field values.
+ *
+ * @param fieldCriterion - Criterion to compare.
+ * @param fieldValue - Array field value to test.
+ * @returns Whether the criterion matches the field value array.
+ * */
+export declare const compareArray: (fieldCriterion: FieldCriterion, fieldValue: any[] | undefined) => boolean;
+/**
+ * Get the filtered data items based on the search criteria.
+ *
+ * @param searchCriteria - Criteria to apply.
+ * @param items - Items to filter.
+ * @param typeInfoName - Optional type name for field metadata.
+ * @param typeInfoMap - Optional type info map for field metadata.
+ * @returns Filtered items that match the criteria.
+ * */
+export declare const getFilterTypeInfoDataItemsBySearchCriteria: (searchCriteria: SearchCriteria, items: TypeInfoDataItem[], typeInfoName?: string, typeInfoMap?: TypeInfoMap) => TypeInfoDataItem[];
+/**
+ * Get the sorted data items based on the given sort fields.
+ *
+ * @param sortFields - Sort field configuration.
+ * @param items - Items to sort.
+ * @returns Sorted items array.
+ * */
+export declare const getSortedItems: (sortFields?: SortField[], items?: TypeInfoDataItem[]) => TypeInfoDataItem[];

package/common/SearchValidation.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Validation rules for search criteria against TypeInfo definitions.
+ */
+import { FieldCriterion } from "./SearchTypes";
+import { CustomTypeInfoFieldValidatorMap, TypeInfoValidationResults } from "./TypeParsing/Validation";
+import { TypeInfoMap } from "./TypeParsing/TypeInfo";
+/**
+ * Search validation errors.
+ * */
+export declare const SEARCH_VALIDATION_ERRORS: {
+    INVALID_TYPE_INFO: string;
+    RELATIONAL_FIELDS_NOT_ALLOWED: string;
+    INVALID_FIELD: string;
+    INVALID_VALUE_OPTION: string;
+    INVALID_OPERATOR: string;
+};
+/**
+ * Validate search fields against type info fields.
+ *
+ * @param typeInfoName - Type name to validate against.
+ * @param typeInfoMap - Type info map containing field definitions.
+ * @param searchFields - Field criteria to validate.
+ * @param disallowRelationalFields - Whether to forbid relational fields.
+ * @param customValidators - Custom field validators by type name.
+ * @returns Validation results with errors and error map.
+ * */
+export declare const validateSearchFields: (typeInfoName: string, typeInfoMap: TypeInfoMap, searchFields?: FieldCriterion[], disallowRelationalFields?: boolean, customValidators?: CustomTypeInfoFieldValidatorMap) => TypeInfoValidationResults;

package/common/StringTransformers.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Built-in and custom string transformers for type keywords.
+ */
+import { TypeKeyword } from "./TypeParsing/TypeInfo";
+/**
+ * A function that transforms a value into a string.
+ *
+ * @param value - Value to transform.
+ * @returns String representation of the value.
+ * */
+export type StringTransformer = (value: any) => string;
+/**
+ * A map of string transformers for each type keyword.
+ * */
+export declare const STRING_TRANSFORMERS: Record<TypeKeyword, StringTransformer>;
+/**
+ * A map of custom string transformers for each custom type.
+ * */
+export declare const CUSTOM_STRING_TRANSFORMERS: Record<string, StringTransformer>;
+/**
+ * Transform a value into a string based on the type keyword or custom type.
+ *
+ * @param value - Value to transform.
+ * @param typeKeyword - Type keyword used to select the transformer.
+ * @param customType - Custom type name, if applicable.
+ * @returns String representation for the value.
+ * */
+export declare const transformValueToString: (value: any, typeKeyword: TypeKeyword, customType?: string) => string;

package/common/Testing/CLI.d.ts

@@ -0,0 +1,6 @@
+/**
+ * CLI entrypoint for the JSON spec test runner.
+ *
+ * @returns Resolves when the CLI finishes and exits the process.
+ */
+export declare const main: () => Promise<void>;

package/common/Testing/Types.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Operations used for comparison during tests.
+ */
+export declare enum TestComparisonOperation {
+    /**
+     * Strict equality comparison.
+     * */
+    EQUALS = "===",
+    /**
+     * Strict inequality comparison.
+     * */
+    NOT_EQUALS = "!==",
+    /**
+     * Value is contained in expectation array.
+     * */
+    IN = "IN",
+    /**
+     * Array contains the expectation value.
+     * */
+    ARRAY_CONTAINS = "ARRAY_CONTAINS",
+    /**
+     * Numeric value is between two bounds.
+     * */
+    BETWEEN = "BETWEEN",
+    /**
+     * String contains another string.
+     * */
+    CONTAINS = "CONTAINS",
+    /**
+     * Regex match against a pattern.
+     * */
+    REGEX = "REGEX",
+    /**
+     * Extended regex match with explicit pattern elements.
+     * */
+    EXT_REGEX = "EXT_REGEX",
+    /**
+     * Deep equality using JSON stringification.
+     * */
+    DEEP_EQUALS = "DEEP_EQUALS",
+    /**
+     * Array equality using JSON stringification.
+     * */
+    ARRAY_EQUALS = "ARRAY_EQUALS"
+}
+/**
+ * A pattern definition object for use with extended regex expectations.
+ * */
+export type PatternElement = {
+    /**
+     * Literal pattern segment value.
+     * */
+    value: string;
+    /**
+     * Whether to escape regex characters in the value.
+     * */
+    escaped?: boolean;
+};
+/**
+ * An extended regex expectation with a patter structure, optional flags and
+ * escaping properties that allow for clear and explicit declaration of regex
+ * patterns in JSON.
+ *
+ * Used when a `TestCondition` `operation` is `TestComparisonOperation.EXT_REGEX`.
+ * */
+export type EXTRegexExpectation = {
+    /**
+     * Pattern elements to build the regex.
+     * */
+    pattern: PatternElement[];
+    /**
+     * Regex flags to apply.
+     * */
+    flags?: string;
+};
+/**
+ * A regex expectation with a pattern and optional flags.
+ *
+ * Used when a `TestCondition` `operation` is `TestComparisonOperation.REGEX`.
+ * */
+export type RegexExpectation = {
+    /**
+     * Regex pattern string.
+     * */
+    pattern: string;
+    /**
+     * Regex flags to apply.
+     * */
+    flags?: string;
+};
+/**
+ * A configuration used to acquire conditions from code instead of a JSON array.
+ * */
+export type ConditionConfig = {
+    /**
+     * Relative file path containing the conditions export.
+     * */
+    file: string;
+    /**
+     * Export name that contains the conditions array.
+     * */
+    export: string;
+};
+/**
+ * Preparation for a test when some setup is required or a class needs to be instantiated.
+ * */
+export type TestSetup = {
+    /**
+     * Conditions to use for the setup function or constructor.
+     * */
+    conditions: unknown[] | ConditionConfig;
+    /**
+     * Export name to call or instantiate for setup.
+     * */
+    export: string;
+    /**
+     * Whether to use `new` with the setup export.
+     * */
+    instantiate?: boolean;
+};
+/**
+ * The basis for a test.
+ * */
+export type BaseTest = {
+    /**
+     * Export name for the test function.
+     * */
+    export: string;
+    /**
+     * Optional setup configuration.
+     * */
+    setup?: TestSetup;
+    /**
+     * Conditions to pass to the test function.
+     * */
+    conditions: unknown[] | ConditionConfig;
+    /**
+     * Allow missing expectation and treat undefined as pass.
+     * */
+    expectUndefined?: boolean;
+};
+/**
+ * A singular test with specific types of expectations for a given operation.
+ * */
+export type Test = BaseTest & ({
+    operation?: TestComparisonOperation.EQUALS | TestComparisonOperation.NOT_EQUALS;
+    expectation: string | number | boolean | null | undefined;
+} | {
+    operation: TestComparisonOperation.IN | TestComparisonOperation.ARRAY_CONTAINS;
+    expectation: unknown[];
+} | {
+    operation: TestComparisonOperation.BETWEEN;
+    expectation: [number, number];
+} | {
+    operation: TestComparisonOperation.CONTAINS;
+    expectation: string;
+} | {
+    operation: TestComparisonOperation.REGEX;
+    expectation: RegexExpectation;
+} | {
+    operation: TestComparisonOperation.EXT_REGEX;
+    expectation: EXTRegexExpectation;
+} | {
+    operation: TestComparisonOperation.DEEP_EQUALS;
+    expectation: Record<string, unknown>;
+} | {
+    operation: TestComparisonOperation.ARRAY_EQUALS;
+    expectation: unknown[];
+});
+/**
+ * A configuration for a test. Designed to be used in JSON spec files.
+ */
+export type TestConfig = {
+    /**
+     * Relative module path containing test exports.
+     * */
+    file: string;
+    /**
+     * Tests to execute for the module.
+     * */
+    tests: Test[];
+};
+/**
+ * A resolved test configuration with the module and tests.
+ * */
+export type ResolvedTestConfig = {
+    /**
+     * Required module with test exports.
+     * */
+    targetModule: any;
+} & TestConfig;
+/**
+ * The results from running one or more tests.
+ * */
+export type TestResults = {
+    /**
+     * Informational messages.
+     * */
+    messages?: string[];
+    /**
+     * Generated expectation messages.
+     * */
+    generated?: string[];
+    /**
+     * Passed test messages.
+     * */
+    passes?: string[];
+    /**
+     * Failed test messages.
+     * */
+    failures?: string[];
+    /**
+     * Error messages.
+     * */
+    errors?: string[];
+};