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

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[];
+};

package/common/Testing/Utils.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @packageDocumentation
+ *
+ * Helpers for executing JSON spec tests, including expectation generation.
+ */
+import { ConditionConfig, ResolvedTestConfig, Test, TestComparisonOperation, TestConfig, TestResults } from "./Types";
+/**
+ * A map of comparison functions for each `TestComparisonOperation`.
+ * */
+export declare const OPERATIONS: Record<string, (a: unknown, b: unknown) => boolean>;
+/**
+ * Compare a result with an expectation using a specified `TestComparisonOperation`.
+ *
+ * @param result - Actual test result.
+ * @param expectation - Expected value.
+ * @param operation - Comparison operation to use.
+ * @returns Whether the result matches the expectation.
+ * */
+export declare const compare: (result: unknown, expectation: unknown, operation?: TestComparisonOperation) => boolean;
+/**
+ * Get the target module for testing from a file being tested.
+ *
+ * @param testFilePath - Path to the test file.
+ * @param targetTestIndex - Index of the test in the test array.
+ * @param targetTestExport - Export name for the test.
+ * @param conditions - Conditions array or config to load.
+ * @param isSetup - Whether the conditions are for setup.
+ * @returns Resolved conditions array.
+ * */
+export declare const getResolvedConditions: (testFilePath: string, targetTestIndex: number, targetTestExport: string, conditions: unknown[] | ConditionConfig, isSetup?: boolean) => Promise<unknown[]>;
+/**
+ * Get the target base instance from a module, for a given test setup.
+ *
+ * @param testFilePath - Path to the test file.
+ * @param targetTestIndex - Index of the test in the test array.
+ * @param targetTestExport - Export name for the test.
+ * @param test - Test definition.
+ * @param module - Required module containing exports.
+ * @returns Instance to use for the test function.
+ * */
+export declare const getSetupInstance: (testFilePath: string, targetTestIndex: number, targetTestExport: string, test: Test, module: any) => Promise<any>;
+/**
+ * Resolve the test function from the target module or setup instance.
+ *
+ * @param testFilePath - Path to the test file.
+ * @param file - Module file defined in the test config.
+ * @param targetTestIndex - Index of the test in the test array.
+ * @param test - Test definition.
+ * @param targetModule - Required module containing exports.
+ * @returns Test function to execute.
+ */
+export declare const getTestFunction: (testFilePath: string, file: string, targetTestIndex: number, test: Test, targetModule: any) => Promise<(...args: unknown[]) => Promise<unknown> | unknown>;
+/**
+ * Get the test configuration from a test file.
+ *
+ * @param testFilePath - Path to the test file.
+ * @returns Parsed test config.
+ * */
+export declare const getTestConfig: (testFilePath: string) => Promise<TestConfig>;
+/**
+ * Get the target module for testing from a file being tested.
+ *
+ * @param testFilePath - Path to the test file.
+ * @returns Resolved test config with module and tests.
+ * */
+export declare const getResolvedTestConfig: (testFilePath: string) => Promise<ResolvedTestConfig>;
+/**
+ * Merge multiple test results into a single result.
+ *
+ * @param results - Test result sets to merge.
+ * @returns Combined test results.
+ * */
+export declare const mergeTestResults: (...results: TestResults[]) => TestResults;
+/**
+ * Run a test using a test function and a test condition.
+ *
+ * @param testFilePath - Path to the test file.
+ * @param testFunction - Test function to execute.
+ * @param test - Test definition.
+ * @param index - Test index in the list.
+ * @param targetExport - Export name for the test.
+ * @param report - Reporter for test results.
+ * @returns Resolves when the test completes.
+ * */
+export declare const runTest: (testFilePath: string, testFunction: (...args: unknown[]) => Promise<unknown> | unknown, test: Test, index: number, targetExport: string, report: (results: TestResults) => void) => Promise<void>;
+/**
+ * Generate tests for a file by running the tests, capturing the current result and storing it as the new expectation.
+ *
+ * @param testFilePath - Path to the test file.
+ * @param report - Reporter for test results.
+ * @returns Resolves when generation completes.
+ * */
+export declare const generateTestsForFile: (testFilePath: string, report: (results: TestResults) => void) => Promise<void>;
+/**
+ * Run the tests for a given test file.
+ *
+ * The test file content is expected to be a JSON in the structure of a `TestConfig`.
+ *
+ * @param testFilePath - Path to the test file.
+ * @param report - Reporter for test results.
+ * @returns Resolves when tests finish.
+ * */
+export declare const runTestsForFile: (testFilePath: string, report: (results: TestResults) => void) => Promise<void>;
+/**
+ * Run or generate all of the tests in the specified `testPath` glob.
+ *
+ * @param testFiles - Test file paths to execute.
+ * @param generateMode - Whether to generate expectations.
+ * @param report - Reporter for test results.
+ * @returns Resolves when execution completes.
+ * */
+export declare const executeTestingCommand: (testFiles: string[], generateMode: boolean | undefined, report: (results: TestResults) => void) => Promise<void>;

package/common/Testing/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @packageDocumentation
+ *
+ * JSON-spec testing helpers used by the custom test runner. Specs live alongside
+ * code in `*.spec.json` files and point to test-utils modules.
+ */
+export * from "./Types";
+export * from "./Utils";

package/common/TypeInfoDataItemUtils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @packageDocumentation
+ *
+ * Helpers for deriving default values from TypeInfo field constraints.
+ */
+import { LiteralValue, TypeInfoField } from "./TypeParsing/TypeInfo";
+/**
+ * Supported default value types for a TypeInfo field.
+ * */
+export type FieldValueType = LiteralValue | LiteralValue[];
+/**
+ * Result describing whether a field has a default value.
+ * */
+export type DefaultValueInfo = {
+    /**
+     * Indicates a default value is present.
+     * */
+    hasDefaultValue: true;
+    /**
+     * Default value for the field.
+     * */
+    defaultValue: FieldValueType;
+} | {
+    /**
+     * Indicates no default value is present.
+     * */
+    hasDefaultValue: false;
+    /**
+     * Always undefined when no default value is present.
+     * */
+    defaultValue: undefined;
+};
+/**
+ * Determine the default value for a TypeInfo field.
+ *
+ * @param typeInfoField - TypeInfo field metadata to inspect.
+ * @returns Default value info for the field.
+ */
+export declare const getDefaultValueInfo: (typeInfoField: TypeInfoField) => DefaultValueInfo;

package/{Types-C7XjUjoF.d.ts → common/TypeInfoORM/Types.d.ts}

@@ -1,16 +1,20 @@
-import { B as BaseItemRelationshipInfo, L as ListRelationshipsConfig, a as ListItemsResults, I as ItemRelationshipInfo, T as TypeInfoDataItem, b as ListItemsConfig, c as TypeOperation } from './SearchTypes-DjN6YQzE.js';
-
 /**
  * @packageDocumentation
  *
  * Shared TypeInfoORM API types, route paths, and error enums used by services
  * and clients.
  */
-
+import { ListItemsConfig, ListItemsResults, ListRelationshipsConfig } from "../SearchTypes";
+import { BaseItemRelationshipInfo, ItemRelationshipInfo } from "../ItemRelationshipInfoTypes";
+import { TypeInfoDataItem, TypeOperation } from "../TypeParsing/TypeInfo";
 /**
- * A set of possible operations for a {@link ItemRelationshipInfo}.
+ * The DAC Resource name for item relationships.
  * */
-declare enum RelationshipOperation {
+export declare const ITEM_RELATIONSHIP_DAC_RESOURCE_NAME = "TYPE_INFO_ORM_ITEM_RELATIONSHIP";
+/**
+ * A set of possible operations for an item relationship record.
+ * */
+export declare enum RelationshipOperation {
     /**
      * Read relationship info.
      * */
@@ -27,7 +31,7 @@ declare enum RelationshipOperation {
 /**
  * A set groups of possible operations for a type, field value or relationship.
  * */
-declare enum OperationGroup {
+export declare enum OperationGroup {
     /**
      * All possible operations.
      * */
@@ -44,11 +48,13 @@ declare enum OperationGroup {
 /**
  * A set of possible ORM operations.
  * */
-type ORMOperation = TypeOperation | RelationshipOperation | OperationGroup;
+export type ORMOperation = TypeOperation | RelationshipOperation | OperationGroup;
 /**
  * Error types for a TypeInfoORM service.
+ *
+ * @category ORM
  * */
-declare enum TypeInfoORMServiceError {
+export declare enum TypeInfoORMServiceError {
     /**
      * No data drivers were supplied.
      * */
@@ -85,6 +91,14 @@ declare enum TypeInfoORMServiceError {
      * Operation is not supported.
      * */
     INVALID_OPERATION = "INVALID_OPERATION",
+    /**
+     * Update operator config is invalid.
+     * */
+    INVALID_UPDATE_OPERATOR = "INVALID_UPDATE_OPERATOR",
+    /**
+     * Accessing role is missing when DAC is required.
+     * */
+    MISSING_ACCESSING_ROLE = "MISSING_ACCESSING_ROLE",
     /**
      * Indexing criteria is not supported.
      * */
@@ -93,10 +107,6 @@ declare enum TypeInfoORMServiceError {
      * Indexing criteria combination is not supported.
      * */
     INDEXING_UNSUPPORTED_COMBINATION = "INDEXING_UNSUPPORTED_COMBINATION",
-    /**
-     * Required index field is missing.
-     * */
-    INDEXING_MISSING_INDEX_FIELD = "INDEXING_MISSING_INDEX_FIELD",
     /**
      * Indexing backend dependency is missing.
      * */
@@ -109,7 +119,7 @@ declare enum TypeInfoORMServiceError {
 /**
  * A collection of kebab-case route paths for a TypeInfoORM API.
  * */
-declare enum TypeInfoORMAPIRoutePaths {
+export declare enum TypeInfoORMAPIRoutePaths {
     /**
      * Create item route.
      * */
@@ -150,7 +160,7 @@ declare enum TypeInfoORMAPIRoutePaths {
 /**
  * The results of a delete relationship operation.
  */
-type DeleteRelationshipResults = {
+export type DeleteRelationshipResults = {
     /**
      * Whether the delete operation succeeded.
      * */
@@ -161,9 +171,130 @@ type DeleteRelationshipResults = {
     remainingItemsExist: boolean;
 };
 /**
- * The API type for TypeInfoORM providers to implement.
- * */
-type TypeInfoORMAPI = {
+ * Access context for a single ORM call.
+ */
+export type TypeInfoORMContext = {
+    /**
+     * Role identifier for the caller.
+     *
+     * Required when DAC is enabled; ignored when DAC is disabled.
+     */
+    accessingRoleId: string;
+};
+/**
+ * Supported numeric field update operators.
+ */
+export declare const TypeInfoORMUpdateOperators: {
+    readonly NUMBER: {
+        readonly INCREMENT: "INCREMENT";
+        readonly DECREMENT: "DECREMENT";
+    };
+};
+/**
+ * Supported numeric field update operator values.
+ */
+export type TypeInfoORMNumberFieldUpdateOperator = (typeof TypeInfoORMUpdateOperators.NUMBER)[keyof typeof TypeInfoORMUpdateOperators.NUMBER];
+/**
+ * Supported field update operator values.
+ */
+export type TypeInfoORMFieldUpdateOperator = TypeInfoORMNumberFieldUpdateOperator;
+/**
+ * Optional config for TypeInfo ORM update calls.
+ */
+export type TypeInfoORMUpdateConfig = {
+    /**
+     * Optional per-field operator map applied during update.
+     */
+    fieldOperators?: Record<string, TypeInfoORMFieldUpdateOperator>;
+};
+/**
+ * Server-side TypeInfoORM API contract.
+ *
+ * Methods that perform DAC-sensitive work may accept
+ * `context?: TypeInfoORMContext`.
+ */
+export type TypeInfoORMAPI = {
+    /**
+     * Create a relationship record.
+     *
+     * @param relationshipItem - Relationship payload to create.
+     * @returns Whether the create succeeded.
+     */
+    createRelationship: (relationshipItem: BaseItemRelationshipInfo, context?: TypeInfoORMContext) => Promise<boolean>;
+    /**
+     * Delete a relationship record.
+     *
+     * @param relationshipItem - Relationship payload to delete.
+     * @returns Results describing deletion outcome.
+     */
+    deleteRelationship: (relationshipItem: BaseItemRelationshipInfo, context?: TypeInfoORMContext) => Promise<DeleteRelationshipResults>;
+    /**
+     * List relationships matching the query.
+     *
+     * @param config - Relationship list configuration.
+     * @returns Relationship list results.
+     */
+    listRelationships: (config: ListRelationshipsConfig, context?: TypeInfoORMContext) => Promise<ListItemsResults<ItemRelationshipInfo>>;
+    /**
+     * List related items for a relationship query.
+     *
+     * @param config - Relationship list configuration.
+     * @param selectedFields - Optional fields to project.
+     * @returns Related item list results.
+     */
+    listRelatedItems: (config: ListRelationshipsConfig, selectedFields?: (keyof TypeInfoDataItem)[], context?: TypeInfoORMContext) => Promise<ListItemsResults<Partial<TypeInfoDataItem>>>;
+    /**
+     * Create an item.
+     *
+     * @param typeName - Type name to create.
+     * @param item - Item payload to create.
+     * @returns The created item result.
+     */
+    create: (typeName: string, item: TypeInfoDataItem) => Promise<any>;
+    /**
+     * Read an item by primary field value.
+     *
+     * @param typeName - Type name to read.
+     * @param primaryFieldValue - Primary field value to lookup.
+     * @param selectedFields - Optional fields to project.
+     * @returns Retrieved item data.
+     */
+    read: (typeName: string, primaryFieldValue: any, selectedFields?: (keyof TypeInfoDataItem)[], context?: TypeInfoORMContext) => Promise<Partial<TypeInfoDataItem>>;
+    /**
+     * Update an item.
+     *
+     * @param typeName - Type name to update.
+     * @param item - Updated item payload.
+     * @param updateConfig - Optional per-field operator config.
+     * @returns Whether the update succeeded.
+     */
+    update: (typeName: string, item: TypeInfoDataItem, updateConfig?: TypeInfoORMUpdateConfig, context?: TypeInfoORMContext) => Promise<boolean>;
+    /**
+     * Delete an item by primary field value.
+     *
+     * @param typeName - Type name to delete.
+     * @param primaryFieldValue - Primary field value to delete.
+     * @returns Whether the delete succeeded.
+     */
+    delete: (typeName: string, primaryFieldValue: any, context?: TypeInfoORMContext) => Promise<boolean>;
+    /**
+     * List items matching the configuration.
+     *
+     * @param typeName - Type name to list.
+     * @param config - List configuration.
+     * @param selectedFields - Optional fields to project.
+     * @returns List results.
+     */
+    list: (typeName: string, config: ListItemsConfig, selectedFields?: (keyof TypeInfoDataItem)[], context?: TypeInfoORMContext) => Promise<ListItemsResults<Partial<TypeInfoDataItem>>>;
+};
+/**
+ * Client-safe TypeInfoORM API shape derived from {@link TypeInfoORMAPI}.
+ *
+ * This type is intentionally explicit and does not include any
+ * `context?: TypeInfoORMContext` arguments so app-side callers cannot pass
+ * server DAC context.
+ */
+export type TypeInfoORMClientAPI = {
     /**
      * Create a relationship record.
      *
@@ -215,9 +346,10 @@ type TypeInfoORMAPI = {
      *
      * @param typeName - Type name to update.
      * @param item - Updated item payload.
+     * @param updateConfig - Optional per-field operator config.
      * @returns Whether the update succeeded.
      */
-    update: (typeName: string, item: TypeInfoDataItem) => Promise<boolean>;
+    update: (typeName: string, item: TypeInfoDataItem, updateConfig?: TypeInfoORMUpdateConfig) => Promise<boolean>;
     /**
      * Delete an item by primary field value.
      *
@@ -236,5 +368,3 @@ type TypeInfoORMAPI = {
      */
     list: (typeName: string, config: ListItemsConfig, selectedFields?: (keyof TypeInfoDataItem)[]) => Promise<ListItemsResults<Partial<TypeInfoDataItem>>>;
 };
-
-export { type DeleteRelationshipResults as D, type ORMOperation as O, RelationshipOperation as R, type TypeInfoORMAPI as T, TypeInfoORMServiceError as a, TypeInfoORMAPIRoutePaths as b };

package/common/TypeInfoORM/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./Types";
+export * from "../SearchTypes";
+export * from "../TypeParsing/TypeInfo";

package/common/TypeParsing/Constants.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Built-in type names used when parsing TypeInfo.
+ * */
+export declare const BUILTIN_TYPE_NAMES: string[];

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

@@ -0,0 +1,8 @@
+/**
+ * Field filter tags used when parsing TypeInfo types.
+ * */
+export declare const FIELD_FILTERS: {
+    OMIT: string;
+    PICK: string;
+    EXCLUDE: string;
+};

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

@@ -0,0 +1,14 @@
+import { TypeNode } from "typescript";
+import { LiteralValue, TypeKeyword } from "../TypeInfo";
+/**
+ * Inspect a TypeScript type node to determine type metadata.
+ *
+ * @param node - AST type node to inspect.
+ * @returns Type metadata including reference, array, keyword, and options.
+ */
+export declare const checkType: (node: TypeNode) => {
+    typeReference?: string | undefined;
+    isArray?: boolean;
+    typeKeyword?: TypeKeyword;
+    options?: LiteralValue[] | undefined;
+};