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

package/common/Routing.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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;
+/**
+ * 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,248 @@
+/**
+ * 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;
+};
+/**
+ * Configuration for full-text search requests.
+ * */
+export type TextSearchConfig = {
+    /**
+     * Text query to search for.
+     * */
+    query: string;
+    /**
+     * Index mode to use when searching.
+     * */
+    mode?: "lossy" | "exact";
+    /**
+     * Optional index field name.
+     * */
+    indexField?: string;
+};
+/**
+ * The configuration for listing and searching for items.
+ * */
+export type ListItemsConfig = PagingInfo & {
+    /**
+     * Structured search criteria.
+     * */
+    criteria?: SearchCriteria;
+    /**
+     * Sort fields to apply.
+     * */
+    sortFields?: SortField[];
+    /**
+     * Full-text search configuration.
+     * */
+    text?: TextSearchConfig;
+};
+/**
+ * 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/{src/common → common}/SearchValidation.d.ts

@@ -1,3 +1,6 @@
+/**
+ * Validation rules for search criteria against TypeInfo definitions.
+ */
 import { FieldCriterion } from "./SearchTypes";
 import { CustomTypeInfoFieldValidatorMap, TypeInfoValidationResults } from "./TypeParsing/Validation";
 import { TypeInfoMap } from "./TypeParsing/TypeInfo";
@@ -13,5 +16,12 @@ export declare const SEARCH_VALIDATION_ERRORS: {
 };
 /**
  * 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/{src/common → common}/StringTransformers.d.ts

@@ -1,6 +1,12 @@
+/**
+ * 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;
 /**
@@ -13,5 +19,10 @@ export declare const STRING_TRANSFORMERS: Record<TypeKeyword, StringTransformer>
 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>;