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

package/README.md

@@ -14,6 +14,33 @@
 yarn add @resistdesign/voltra
 ```
 
+### Imports
+
+Prefer the public entrypoints below to keep imports stable and IDE auto-imports clean.
+
+Preferred:
+
+```ts
+import { IaC } from "@resistdesign/voltra";
+import { Packs } from "@resistdesign/voltra/iac";
+import { addDNS } from "@resistdesign/voltra/iac/packs";
+```
+
+Not supported:
+
+```ts
+import addDNS from "@resistdesign/voltra/iac/packs/dns";
+```
+
+Public entrypoints:
+
+- `@resistdesign/voltra`
+- `@resistdesign/voltra/api`
+- `@resistdesign/voltra/app`
+- `@resistdesign/voltra/common`
+- `@resistdesign/voltra/iac`
+- `@resistdesign/voltra/iac/packs`
+
 ## With our powers combined!
 
 <table style="border: 0 solid black;">
@@ -41,6 +68,35 @@ front-end apps.</td>
 | ORM: TypeScript Type Driven Auto-generated Data Contexts with Relationships |                                               | Typed Build Spec Creation                                     |
 |                                                                             |                                               | Typed Resource Parameters                                     |
 
+## Docs Site
+
+The docs site is both reference documentation and a canonical usage example.
+Key pieces:
+
+- Astro app in `site/app` builds the UI into `site-dist/app` via `yarn site:build:app`.
+- API bundle for the docs site is built by `yarn site:build:api` (see `site/build-api.mjs`) and written to `site-dist/api`.
+- The IaC demo template is generated by `yarn site:build:iac` from `site/iac/index.ts` and written to `site-dist/iac/index.yml`.
+
+API docs flow:
+
+1) `yarn doc` generates TypeDoc output into `docs/`.
+2) `yarn doc-to-site` copies `docs/` into `site-dist/app/`.
+3) `yarn site:build:app` runs Astro and then `yarn finalize-site` to refresh the docs site with API docs.
+
+## IaC Type Generation
+
+IaC types are generated from the AWS CloudFormation resource specification.
+When updating, follow this flow:
+
+1) Download the latest CloudFormation resource specification JSON from AWS (region: `us-east-1`).
+2) Replace the contents of `src/iac/types/CloudFormationResourceSpecification.ts` with the JSON payload (as the exported data).
+3) Run `yarn iac:types:gen` to regenerate `dist/IaCTypes.ts`.
+4) Verify `dist/IaCTypes.ts` looks correct, then commit both files.
+
+Notes:
+- `src/iac/types/IaCTypes.ts` and `src/iac/types/CloudFormationResourceSpecification.ts` are generated artifacts; do not edit by hand.
+- The generator entrypoint is `src/iac/types/generate.ts` and uses `src/iac/types/Renderers.ts` for output.
+
 ## Releasing
 
 Voltra publishes npm packages from GitHub Releases. The release tag is used verbatim
@@ -70,3 +126,22 @@ When the GitHub Release is marked as a prerelease, the npm publish step uses the
 ```bash
 yarn add @resistdesign/voltra@next
 ```
+
+## Project
+
+### Build and test commands
+
+```bash
+yarn build
+yarn test
+yarn test:gen
+yarn doc
+yarn start
+yarn site:build:app
+```
+
+### Contribution guidelines
+
+- Use Conventional Commits (`feat:`, `fix:`, `doc:`, `chore:`) with optional scopes.
+- Keep subjects imperative and concise.
+- Include test commands run (or reasons for skipping) in PR descriptions.

package/SearchTypes-DjN6YQzE.d.ts

@@ -0,0 +1,577 @@
+/**
+ * TypeInfo definitions and tags used across parsing and validation.
+ */
+/**
+ * A set of possible operations for a type or field value.
+ */
+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.
+ * */
+type DeniedOperations = Partial<Record<TypeOperation, boolean>>;
+/**
+ * Voltra supported `TypeInfo` tags.
+ * */
+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.
+ * */
+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;
+}>;
+/**
+ * The set of acceptable literal value types.
+ */
+type LiteralValue = string | number | boolean | null;
+/**
+ * The set of acceptable type keywords.
+ */
+type TypeKeyword = "string" | "number" | "boolean";
+/**
+ * Information about a field in a type definition.
+ */
+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.
+ */
+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.
+ */
+type TypeInfoMap = Record<string, TypeInfo>;
+/**
+ * The necessary information to use a {@link TypeInfo} with the entire {@link TypeInfoMap} containing it.
+ * */
+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.
+ * */
+type TypeInfoDataItem = Record<string, LiteralValue | LiteralValue[]>;
+
+type TypeInfo$1_DeniedOperations = DeniedOperations;
+type TypeInfo$1_LiteralValue = LiteralValue;
+type TypeInfo$1_SupportedFieldTags = SupportedFieldTags;
+type TypeInfo$1_SupportedTags = SupportedTags;
+type TypeInfo$1_TypeInfo = TypeInfo;
+type TypeInfo$1_TypeInfoDataItem = TypeInfoDataItem;
+type TypeInfo$1_TypeInfoField = TypeInfoField;
+type TypeInfo$1_TypeInfoMap = TypeInfoMap;
+type TypeInfo$1_TypeInfoPack = TypeInfoPack;
+type TypeInfo$1_TypeKeyword = TypeKeyword;
+type TypeInfo$1_TypeOperation = TypeOperation;
+declare const TypeInfo$1_TypeOperation: typeof TypeOperation;
+declare namespace TypeInfo$1 {
+  export { type TypeInfo$1_DeniedOperations as DeniedOperations, type TypeInfo$1_LiteralValue as LiteralValue, type TypeInfo$1_SupportedFieldTags as SupportedFieldTags, type TypeInfo$1_SupportedTags as SupportedTags, type TypeInfo$1_TypeInfo as TypeInfo, type TypeInfo$1_TypeInfoDataItem as TypeInfoDataItem, type TypeInfo$1_TypeInfoField as TypeInfoField, type TypeInfo$1_TypeInfoMap as TypeInfoMap, type TypeInfo$1_TypeInfoPack as TypeInfoPack, type TypeInfo$1_TypeKeyword as TypeKeyword, TypeInfo$1_TypeOperation as TypeOperation };
+}
+
+/**
+ * Expand inferred types for clearer IntelliSense/display.
+ *
+ * @typeParam T - Type to expand.
+ */
+type ExpandComplexType<T> = {
+    [K in keyof T]: T[K];
+} & {};
+declare const HelperTypes: {};
+
+type HelperTypes$1_ExpandComplexType<T> = ExpandComplexType<T>;
+declare const HelperTypes$1_HelperTypes: typeof HelperTypes;
+declare namespace HelperTypes$1 {
+  export { type HelperTypes$1_ExpandComplexType as ExpandComplexType, HelperTypes$1_HelperTypes as HelperTypes };
+}
+
+/**
+ * Relationship info types used by ORM and relationship utilities.
+ */
+
+/**
+ * The keys for item relationship info.
+ * */
+declare enum ItemRelationshipInfoKeys {
+    /**
+     * Relationship origin type name.
+     * */
+    fromTypeName = "fromTypeName",
+    /**
+     * Relationship origin field name.
+     * */
+    fromTypeFieldName = "fromTypeFieldName",
+    /**
+     * Relationship origin primary field value.
+     * */
+    fromTypePrimaryFieldValue = "fromTypePrimaryFieldValue",
+    /**
+     * Relationship destination primary field value.
+     * */
+    toTypePrimaryFieldValue = "toTypePrimaryFieldValue"
+}
+/**
+ * The identifying keys for item relationship info.
+ * */
+declare enum ItemRelationshipInfoIdentifyingKeys {
+    /**
+     * Identifier value for a relationship item.
+     * */
+    id = "id"
+}
+/**
+ * The basis for an `ItemRelationshipInfo` without an assigned identifier.
+ * */
+type BaseItemRelationshipInfo = Record<ItemRelationshipInfoKeys, string>;
+/**
+ * An item containing the information about a relationship between two items.
+ * */
+type ItemRelationshipInfo = BaseItemRelationshipInfo & Record<ItemRelationshipInfoIdentifyingKeys, string>;
+/**
+ * The origination portion of an `ItemRelationshipInfo`.
+ * */
+type ItemRelationshipOriginInfo = Record<ItemRelationshipInfoKeys.fromTypeName | ItemRelationshipInfoKeys.fromTypeFieldName, string>;
+/**
+ * The origination portion of an `ItemRelationshipInfo` for a specific item and field relationship.
+ * */
+type ItemRelationshipOriginItemInfo = ExpandComplexType<ItemRelationshipOriginInfo & Record<ItemRelationshipInfoKeys.fromTypePrimaryFieldValue, string>>;
+/**
+ * The destination portion of an `ItemRelationshipInfo` for a specific, related item.
+ * */
+type ItemRelationshipDestinationItemInfo = Record<ItemRelationshipInfoKeys.toTypePrimaryFieldValue, string>;
+/**
+ * The originating item info portion of an `ItemRelationshipInfo`.
+ *
+ * Used for relationship originating from a specific item, regardless of field relationship.
+ * */
+type ItemRelationshipOriginatingItemInfo = Record<ItemRelationshipInfoKeys.fromTypeName | ItemRelationshipInfoKeys.fromTypePrimaryFieldValue, string>;
+/**
+ * One of the various types describing an item relationship.
+ * */
+type ItemRelationshipInfoType = BaseItemRelationshipInfo | ItemRelationshipInfo | ItemRelationshipOriginInfo | ItemRelationshipOriginItemInfo;
+
+type ItemRelationshipInfoTypes_BaseItemRelationshipInfo = BaseItemRelationshipInfo;
+type ItemRelationshipInfoTypes_ItemRelationshipDestinationItemInfo = ItemRelationshipDestinationItemInfo;
+type ItemRelationshipInfoTypes_ItemRelationshipInfo = ItemRelationshipInfo;
+type ItemRelationshipInfoTypes_ItemRelationshipInfoIdentifyingKeys = ItemRelationshipInfoIdentifyingKeys;
+declare const ItemRelationshipInfoTypes_ItemRelationshipInfoIdentifyingKeys: typeof ItemRelationshipInfoIdentifyingKeys;
+type ItemRelationshipInfoTypes_ItemRelationshipInfoKeys = ItemRelationshipInfoKeys;
+declare const ItemRelationshipInfoTypes_ItemRelationshipInfoKeys: typeof ItemRelationshipInfoKeys;
+type ItemRelationshipInfoTypes_ItemRelationshipInfoType = ItemRelationshipInfoType;
+type ItemRelationshipInfoTypes_ItemRelationshipOriginInfo = ItemRelationshipOriginInfo;
+type ItemRelationshipInfoTypes_ItemRelationshipOriginItemInfo = ItemRelationshipOriginItemInfo;
+type ItemRelationshipInfoTypes_ItemRelationshipOriginatingItemInfo = ItemRelationshipOriginatingItemInfo;
+declare namespace ItemRelationshipInfoTypes {
+  export { type ItemRelationshipInfoTypes_BaseItemRelationshipInfo as BaseItemRelationshipInfo, type ItemRelationshipInfoTypes_ItemRelationshipDestinationItemInfo as ItemRelationshipDestinationItemInfo, type ItemRelationshipInfoTypes_ItemRelationshipInfo as ItemRelationshipInfo, ItemRelationshipInfoTypes_ItemRelationshipInfoIdentifyingKeys as ItemRelationshipInfoIdentifyingKeys, ItemRelationshipInfoTypes_ItemRelationshipInfoKeys as ItemRelationshipInfoKeys, type ItemRelationshipInfoTypes_ItemRelationshipInfoType as ItemRelationshipInfoType, type ItemRelationshipInfoTypes_ItemRelationshipOriginInfo as ItemRelationshipOriginInfo, type ItemRelationshipInfoTypes_ItemRelationshipOriginItemInfo as ItemRelationshipOriginItemInfo, type ItemRelationshipInfoTypes_ItemRelationshipOriginatingItemInfo as ItemRelationshipOriginatingItemInfo };
+}
+
+/**
+ * Search-related types used by list/search APIs.
+ */
+
+/**
+ * The logical operators for a search criteria.
+ * */
+declare enum LogicalOperators {
+    /**
+     * Require all criteria to match.
+     * */
+    AND = "AND",
+    /**
+     * Require any criteria to match.
+     * */
+    OR = "OR"
+}
+/**
+ * The comparison operators for a field criterion.
+ * */
+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.
+ * */
+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.
+ * */
+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.
+ * */
+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.
+ * */
+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
+ * */
+type StandardExpandedPagingCursor = {
+    /**
+     * Current page number.
+     * */
+    currentPage?: number;
+    /**
+     * Total number of pages available.
+     * */
+    totalPages?: number;
+};
+/**
+ * The information for paging through a list of items.
+ * */
+type PagingInfo = {
+    /**
+     * Items per page to request.
+     * */
+    itemsPerPage?: number;
+    /**
+     * Cursor token for paging.
+     * */
+    cursor?: string;
+};
+/**
+ * Configuration for full-text search requests.
+ * */
+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.
+ * */
+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.
+ * */
+type ListRelationshipsConfig = PagingInfo & {
+    /**
+     * Relationship origin info used to filter related records.
+     * */
+    relationshipItemOrigin: ItemRelationshipOriginItemInfo;
+};
+/**
+ * The results from a request to list relationships.
+ * */
+type ListRelationshipsResults = ListItemsResults<ItemRelationshipInfo>;
+
+type SearchTypes_ComparisonOperators = ComparisonOperators;
+declare const SearchTypes_ComparisonOperators: typeof ComparisonOperators;
+type SearchTypes_FieldCriterion = FieldCriterion;
+type SearchTypes_ListItemsConfig = ListItemsConfig;
+type SearchTypes_ListItemsResults<ItemType extends Record<any, any>> = ListItemsResults<ItemType>;
+type SearchTypes_ListRelationshipsConfig = ListRelationshipsConfig;
+type SearchTypes_ListRelationshipsResults = ListRelationshipsResults;
+type SearchTypes_LogicalOperators = LogicalOperators;
+declare const SearchTypes_LogicalOperators: typeof LogicalOperators;
+type SearchTypes_PagingInfo = PagingInfo;
+type SearchTypes_SearchCriteria = SearchCriteria;
+type SearchTypes_SortField = SortField;
+type SearchTypes_StandardExpandedPagingCursor = StandardExpandedPagingCursor;
+type SearchTypes_TextSearchConfig = TextSearchConfig;
+declare namespace SearchTypes {
+  export { SearchTypes_ComparisonOperators as ComparisonOperators, type SearchTypes_FieldCriterion as FieldCriterion, type SearchTypes_ListItemsConfig as ListItemsConfig, type SearchTypes_ListItemsResults as ListItemsResults, type SearchTypes_ListRelationshipsConfig as ListRelationshipsConfig, type SearchTypes_ListRelationshipsResults as ListRelationshipsResults, SearchTypes_LogicalOperators as LogicalOperators, type SearchTypes_PagingInfo as PagingInfo, type SearchTypes_SearchCriteria as SearchCriteria, type SearchTypes_SortField as SortField, type SearchTypes_StandardExpandedPagingCursor as StandardExpandedPagingCursor, type SearchTypes_TextSearchConfig as TextSearchConfig };
+}
+
+export { type BaseItemRelationshipInfo as B, ComparisonOperators as C, type ExpandComplexType as E, type FieldCriterion as F, HelperTypes$1 as H, type ItemRelationshipInfo as I, type ListRelationshipsConfig as L, type SearchCriteria as S, type TypeInfoDataItem as T, type ListItemsResults as a, type ListItemsConfig as b, TypeOperation as c, type TypeKeyword as d, type TypeInfoField as e, type TypeInfoMap as f, type TypeInfo as g, TypeInfo$1 as h, type SortField as i, type ItemRelationshipInfoType as j, ItemRelationshipInfoKeys as k, ItemRelationshipInfoTypes as l, SearchTypes as m, type TypeInfoPack as n, ItemRelationshipInfoIdentifyingKeys as o, type LiteralValue as p, type ItemRelationshipOriginatingItemInfo as q, type ItemRelationshipOriginInfo as r };