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

package/api/ORM/TypeInfoORMService.d.ts

@@ -0,0 +1,555 @@
+/**
+ * @packageDocumentation
+ *
+ * TypeInfo-driven ORM service. Configure with a type map and a driver resolver,
+ * and optionally provide DAC and indexing integrations. The constructor validates
+ * configuration once, and each call resolves drivers as needed.
+ */
+import { LiteralValue, TypeInfo, TypeInfoDataItem, TypeInfoMap, TypeOperation } from "../../common/TypeParsing/TypeInfo";
+import { CustomTypeInfoFieldValidatorMap } from "../../common/TypeParsing/Validation";
+import { ListItemsConfig, ListItemsResults, ListRelationshipsConfig } from "../../common/SearchTypes";
+import { DeleteRelationshipResults, RelationshipOperation, TypeInfoORMAPI, TypeInfoORMContext } from "../../common/TypeInfoORM";
+import { DataItemDBDriver, IndexingRelationshipDriver, ItemRelationshipDBDriver } from "./drivers";
+import { BaseItemRelationshipInfo, ItemRelationshipInfo, ItemRelationshipInfoKeys, ItemRelationshipInfoType, ItemRelationshipOriginatingItemInfo } from "../../common/ItemRelationshipInfoTypes";
+import { DACAccessResult, DACDataItemResourceAccessResultMap, DACRole } from "../DataAccessControl";
+import type { IndexBackend } from "../Indexing/Types";
+import { type StructuredSearchDependencies } from "../Indexing/structured/SearchStructured";
+import type { StructuredWriter } from "../Indexing/structured/Handlers";
+import type { ResolvedSearchLimits } from "../Indexing/Handler/Config";
+import type { StructuredDocFieldsRecord } from "../Indexing/structured/StructuredDdb";
+import type { Where, WhereValue } from "../Indexing/structured/Types";
+import type { RelationalBackend } from "./drivers/IndexingRelationshipDriver";
+/**
+ * Strip a relationship item down to its identifying keys.
+ * @returns Relationship item containing only identifying fields.
+ * */
+export declare const cleanRelationshipItem: (
+/**
+ * Relationship item to normalize.
+ */
+relationshipItem: BaseItemRelationshipInfo) => BaseItemRelationshipInfo;
+/**
+ * Wrap a driver method to attach extra fields to thrown errors.
+ * @returns Wrapped driver method with extended error data.
+ * */
+export declare const getDriverMethodWithModifiedError: <ItemType extends TypeInfoDataItem, UniquelyIdentifyingFieldName extends keyof ItemType, DriverMethodNameType extends keyof DataItemDBDriver<ItemType, UniquelyIdentifyingFieldName>, MethodType extends DataItemDBDriver<ItemType, UniquelyIdentifyingFieldName>[DriverMethodNameType]>(
+/**
+ * Extra fields to attach to thrown errors.
+ */
+extendedData: Record<any, any>, 
+/**
+ * Driver instance containing the method.
+ */
+driver: DataItemDBDriver<ItemType, UniquelyIdentifyingFieldName>, 
+/**
+ * Driver method name to wrap.
+ */
+driverMethodName: DriverMethodNameType) => MethodType;
+/**
+ * The configuration for the TypeInfoORMService DAC features.
+ * */
+export type TypeInfoORMDACConfig = {
+    /**
+     * DAC path prefix for item resources.
+     *
+     * This prefix is prepended to canonical item paths before evaluating
+     * DAC constraints.
+     */
+    itemResourcePathPrefix: LiteralValue[];
+    /**
+     * DAC path prefix for relationship resources.
+     *
+     * This prefix is prepended to canonical relationship paths before
+     * evaluating DAC constraints.
+     */
+    relationshipResourcePathPrefix: LiteralValue[];
+    /**
+     * Optional resolver for owner/tenant prefix applied to item resource paths.
+     *
+     * When present, the returned prefix is inserted after
+     * `itemResourcePathPrefix` and before the canonical item path segments.
+     *
+     * Relationship create/delete operations also use this prefix to validate
+     * endpoint ownership for both the `from` and `to` items.
+     */
+    getOwnerPrefix?: (typeName: string, primaryFieldValue: LiteralValue) => Promise<LiteralValue[] | undefined>;
+    /**
+     * Lookup helper used to resolve roles by id.
+     */
+    getDACRoleById: (id: string) => Promise<DACRole>;
+};
+/**
+ * Configuration for TypeInfoORM indexing integrations.
+ */
+export type TypeInfoORMIndexingConfig = {
+    /**
+     * Full text indexing configuration.
+     */
+    fullText?: {
+        /**
+         * Backend used for full text indexing.
+         */
+        backend: IndexBackend;
+        /**
+         * Default index field names by type.
+         */
+        defaultIndexFieldByType?: Record<string, string>;
+    };
+    /**
+     * Structured indexing configuration.
+     */
+    structured?: {
+        /**
+         * Reader used for structured queries.
+         */
+        reader: StructuredSearchDependencies;
+        /**
+         * Optional writer for structured indexing.
+         */
+        writer?: StructuredWriter;
+        /**
+         * Field name mapping per type.
+         */
+        fieldMapByType?: Record<string, Record<string, string>>;
+    };
+    /**
+     * Relationship indexing configuration.
+     */
+    relations?: {
+        /**
+         * Backend used for relationship indexing.
+         */
+        backend: RelationalBackend;
+        /**
+         * Resolver for relation name from type/field.
+         */
+        relationNameFor: (fromTypeName: string, fromTypeFieldName: string) => string;
+        /**
+         * Optional encoder for entity ids.
+         */
+        encodeEntityId?: (typeName: string, primaryFieldValue: string) => string;
+        /**
+         * Optional decoder for entity ids.
+         */
+        decodeEntityId?: (typeName: string, entityId: string) => string;
+    };
+    /**
+     * Optional search limits for indexing queries.
+     */
+    limits?: ResolvedSearchLimits;
+};
+/**
+ * The basis for the configuration for the TypeInfoORMService.
+ * */
+export type BaseTypeInfoORMServiceConfig = {
+    /**
+     * Type info map used to validate and shape items.
+     */
+    typeInfoMap: TypeInfoMap;
+    /**
+     * Driver resolver for item types.
+     */
+    getDriver: (typeName: string) => DataItemDBDriver<any, any>;
+    /**
+     * Optional relationship driver resolver.
+     */
+    getRelationshipDriver?: (typeName: string, fieldName: string) => ItemRelationshipDBDriver;
+    /**
+     * Optional indexing configuration.
+     */
+    indexing?: TypeInfoORMIndexingConfig;
+    /**
+     * Optional relationship cleanup hook on delete.
+     */
+    createRelationshipCleanupItem?: (relationshipOriginatingItem: ItemRelationshipOriginatingItemInfo) => Promise<void>;
+    /**
+     * Optional custom validators by type/field.
+     */
+    customValidators?: CustomTypeInfoFieldValidatorMap;
+};
+/**
+ * The options determining the usage of DAC features in a {@link TypeInfoORMServiceConfig}.
+ * */
+export type TypeInfoORMServiceDACOptions = {
+    useDAC: true;
+    dacConfig: TypeInfoORMDACConfig;
+} | {
+    useDAC: false;
+};
+/**
+ * The configuration for the TypeInfoORMService, including DAC features.
+ * */
+export type TypeInfoORMServiceConfig = BaseTypeInfoORMServiceConfig & TypeInfoORMServiceDACOptions;
+/**
+ * TypeInfo-driven ORM service with optional DAC and indexing integrations.
+ */
+export declare class TypeInfoORMService implements TypeInfoORMAPI {
+    protected config: TypeInfoORMServiceConfig;
+    protected dacRoleCache: Record<string, DACRole>;
+    protected indexingRelationshipDriver?: IndexingRelationshipDriver;
+    /**
+     * @param config ORM service configuration.
+     */
+    constructor(config: TypeInfoORMServiceConfig);
+    protected resolveAccessingRole: (context?: TypeInfoORMContext) => Promise<DACRole | undefined>;
+    protected getItemDACValidation: (
+    /**
+     * Item to evaluate for access.
+     */
+    item: Partial<TypeInfoDataItem>, 
+    /**
+     * Type name for the item.
+     */
+    typeName: string, 
+    /**
+     * Operation being evaluated.
+     */
+    typeOperation: TypeOperation, 
+    /**
+     * Optional access context for the call.
+     */
+    context?: TypeInfoORMContext) => Promise<DACDataItemResourceAccessResultMap>;
+    protected getRelationshipDACValidation: (
+    /**
+     * Relationship to evaluate for access.
+     */
+    itemRelationship: BaseItemRelationshipInfo, 
+    /**
+     * Relationship operation being evaluated.
+     */
+    relationshipOperation: RelationshipOperation, 
+    /**
+     * Optional access context for the call.
+     */
+    context?: TypeInfoORMContext, 
+    /**
+     * Optional relationship resource path prefix override.
+     */
+    relationshipPrefixOverride?: LiteralValue[]) => Promise<DACAccessResult>;
+    protected getRelationshipEndpointDACValidation: (relationshipItem: BaseItemRelationshipInfo, relationshipOperation: RelationshipOperation, relatedTypeName: string, context?: TypeInfoORMContext) => Promise<DACAccessResult>;
+    protected getWrappedDriverWithExtendedErrorData: <ItemType extends TypeInfoDataItem, UniquelyIdentifyingFieldName extends keyof ItemType>(
+    /**
+     * Driver instance to wrap.
+     */
+    driver: DataItemDBDriver<ItemType, UniquelyIdentifyingFieldName>, 
+    /**
+     * Extra fields to attach to thrown errors.
+     */
+    extendedData: Record<any, any>) => DataItemDBDriver<ItemType, UniquelyIdentifyingFieldName>;
+    protected getDriverInternal: (
+    /**
+     * Type name used to resolve the driver.
+     */
+    typeName: string) => DataItemDBDriver<any, any>;
+    protected getRelationshipDriverInternal: (
+    /**
+     * Type name used to resolve the relationship driver.
+     */
+    typeName: string, 
+    /**
+     * Field name used to resolve the relationship driver.
+     */
+    fieldName: string) => ItemRelationshipDBDriver;
+    /**
+     * @returns Indexing relationship driver for relation indexing.
+     */
+    /**
+     * @returns Indexing relationship driver for relation indexing.
+     */
+    protected getIndexingRelationshipDriverInternal: () => IndexingRelationshipDriver;
+    /**
+     * @param typeName Type name to resolve.
+     * @returns Type info for the requested type.
+     */
+    /**
+     * @param typeName Type name to resolve.
+     * @returns Type info for the requested type.
+     */
+    protected getTypeInfo: (typeName: string) => TypeInfo;
+    /**
+     * @returns Resolved index field name, if available.
+     */
+    protected resolveFullTextIndexField: (
+    /**
+     * Type name used to resolve the default index field.
+     */
+    typeName: string, 
+    /**
+     * Optional override for the index field.
+     */
+    override?: string) => string | undefined;
+    /**
+     * @param value Value to check.
+     * @returns True when the value is a supported structured value.
+     */
+    protected isStructuredValue: (value: unknown) => value is WhereValue;
+    /**
+     * @returns Structured fields record for indexing.
+     */
+    protected buildStructuredFields: (
+    /**
+     * Type name for field mapping.
+     */
+    typeName: string, 
+    /**
+     * Item to extract structured fields from.
+     */
+    item: Partial<TypeInfoDataItem>) => StructuredDocFieldsRecord;
+    /**
+     * @returns Mapped structured query.
+     */
+    protected applyStructuredFieldMap: (
+    /**
+     * Type name used for field qualification.
+     */
+    typeName: string, 
+    /**
+     * Structured query to map.
+     */
+    where: Where, 
+    /**
+     * Optional field mapping by type.
+     */
+    fieldMap?: Record<string, string>) => Where;
+    /**
+     * @returns Promise resolved once indexing is complete.
+     */
+    protected indexFullTextDocument(
+    /**
+     * Type name for index field resolution.
+     */
+    typeName: string, 
+    /**
+     * Item to index.
+     */
+    item: Partial<TypeInfoDataItem>, 
+    /**
+     * Optional override for the index field.
+     */
+    indexFieldOverride?: string): Promise<void>;
+    /**
+     * @returns Promise resolved once removal is complete.
+     */
+    protected removeFullTextDocument(
+    /**
+     * Type name for index field resolution.
+     */
+    typeName: string, 
+    /**
+     * Item to remove from the index.
+     */
+    item: Partial<TypeInfoDataItem>, 
+    /**
+     * Optional override for the index field.
+     */
+    indexFieldOverride?: string): Promise<void>;
+    /**
+     * @returns Promise resolved once replacement is complete.
+     */
+    protected replaceFullTextDocument(
+    /**
+     * Type name for index field resolution.
+     */
+    typeName: string, 
+    /**
+     * Previous item state to remove from the index.
+     */
+    previousItem: Partial<TypeInfoDataItem>, 
+    /**
+     * Next item state to index.
+     */
+    nextItem: Partial<TypeInfoDataItem>, 
+    /**
+     * Optional override for the index field.
+     */
+    indexFieldOverride?: string): Promise<void>;
+    /**
+     * @returns Promise resolved once indexing is complete.
+     */
+    protected indexStructuredDocument(
+    /**
+     * Type name for field mapping.
+     */
+    typeName: string, 
+    /**
+     * Item to index.
+     */
+    item: Partial<TypeInfoDataItem>): Promise<void>;
+    /**
+     * @returns Promise resolved once removal is complete.
+     */
+    protected removeStructuredDocument(
+    /**
+     * Type name for field mapping.
+     */
+    typeName: string, 
+    /**
+     * Item to remove from the structured index.
+     */
+    item: Partial<TypeInfoDataItem>): Promise<void>;
+    /**
+     * @returns Nothing (throws on invalid operations).
+     */
+    protected validateReadOperation: (
+    /**
+     * Type name to validate for read.
+     */
+    typeName: string, 
+    /**
+     * Optional selected fields to validate.
+     */
+    selectedFields?: (keyof TypeInfoDataItem)[]) => void;
+    /**
+     * @returns Nothing (throws on invalid items).
+     */
+    protected validate: (
+    /**
+     * Type name to validate.
+     */
+    typeName: string, 
+    /**
+     * Item to validate.
+     */
+    item: TypeInfoDataItem, 
+    /**
+     * Operation being validated.
+     */
+    typeOperation: TypeOperation, 
+    /**
+     * Whether the item is a partial update.
+     */
+    itemIsPartial?: boolean) => void;
+    /**
+     * @returns Cleaned item with selected fields and DAC constraints applied.
+     */
+    protected getCleanItem: (
+    /**
+     * Type name used to look up TypeInfo.
+     */
+    typeName: string, 
+    /**
+     * Item to clean.
+     */
+    item: Partial<TypeInfoDataItem>, 
+    /**
+     * Optional DAC field resource map.
+     */
+    dacFieldResources?: Partial<Record<keyof TypeInfoDataItem, DACAccessResult>>, 
+    /**
+     * Optional selected fields to include.
+     */
+    selectedFields?: (keyof TypeInfoDataItem)[]) => Partial<TypeInfoDataItem>;
+    /**
+     * @returns Sanitized selected fields or undefined for all fields.
+     */
+    protected getCleanSelectedFields: (
+    /**
+     * Type name used to look up TypeInfo.
+     */
+    typeName: string, 
+    /**
+     * Optional selected fields to include.
+     */
+    selectedFields?: (keyof TypeInfoDataItem)[]) => (keyof TypeInfoDataItem)[] | undefined;
+    /**
+     * @returns Nothing (throws on invalid relationships).
+     */
+    protected validateRelationshipItem: (
+    /**
+     * Relationship item to validate.
+     */
+    relationshipItem: ItemRelationshipInfoType, 
+    /**
+     * Relationship fields to omit from validation.
+     */
+    omitFields: ItemRelationshipInfoKeys[]) => void;
+    /**
+     * @returns Promise resolved once cleanup is complete.
+     */
+    protected cleanupRelationships: (
+    /**
+     * Relationship originating item used for cleanup.
+     */
+    relationshipOriginatingItem: ItemRelationshipOriginatingItemInfo) => Promise<void>;
+    /**
+     * Create a new relationship between two items.
+     * @param relationshipItem Relationship item to create.
+     *
+     * When DAC is enabled and `getOwnerPrefix` is configured, relationship
+     * creation requires:
+     * 1) relationship permission on the relationship resource path, and
+     * 2) endpoint ownership permission for both `from` and `to` items.
+     * @returns True when the relationship was created.
+     * */
+    createRelationship: (relationshipItem: BaseItemRelationshipInfo, context?: TypeInfoORMContext) => Promise<boolean>;
+    /**
+     * Delete a relationship between two items.
+     * @param relationshipItem Relationship item to delete.
+     *
+     * When DAC is enabled and `getOwnerPrefix` is configured, relationship
+     * deletion requires:
+     * 1) relationship permission on the relationship resource path, and
+     * 2) endpoint ownership permission for both `from` and `to` items.
+     * @returns Deletion results including whether items remain.
+     * */
+    deleteRelationship: (relationshipItem: BaseItemRelationshipInfo, context?: TypeInfoORMContext) => Promise<DeleteRelationshipResults>;
+    /**
+     * List the relationships for a given item.
+     * @param config Relationship list configuration.
+     * @returns Relationship items and paging cursor.
+     * */
+    listRelationships: (config: ListRelationshipsConfig, context?: TypeInfoORMContext) => Promise<ListItemsResults<ItemRelationshipInfo>>;
+    /**
+     * List related items for the relationship origin.
+     * @param config Relationship list configuration.
+     * @param selectedFields Optional fields to select on related items.
+     * @returns Items and cursor for related items.
+     */
+    listRelatedItems: (config: ListRelationshipsConfig, selectedFields?: (keyof TypeInfoDataItem)[], context?: TypeInfoORMContext) => Promise<{
+        items: Partial<TypeInfoDataItem>[];
+        cursor: string | undefined;
+    }>;
+    /**
+     * Create a new item of the given type.
+     * @param typeName Type name to create.
+     * @param item Item payload to create.
+     * @returns Primary field value for the created item.
+     * */
+    create: (typeName: string, item: TypeInfoDataItem) => Promise<any>;
+    /**
+     * Read an existing item of the given type.
+     * @param typeName Type name to read.
+     * @param primaryFieldValue Primary field value to fetch.
+     * @param selectedFields Optional fields to select.
+     * @returns Cleaned item data.
+     * */
+    read: (typeName: string, primaryFieldValue: any, selectedFields?: string[], context?: TypeInfoORMContext) => Promise<Partial<TypeInfoDataItem>>;
+    /**
+     * Update an existing item of the given type.
+     *
+     * This update will always act as a **patch**.
+     * Use `null` to signify the deletion of a field.
+     * Assign values to **all** fields to perform a **replacement**.
+     *
+     * The `item` **must always** contain its **primary field value**.
+     * @param typeName Type name to update.
+     * @param item Item payload to update.
+     * @returns True when the update succeeded.
+     * */
+    update: (typeName: string, item: TypeInfoDataItem, context?: TypeInfoORMContext) => Promise<boolean>;
+    /**
+     * Delete an existing item of the given type.
+     * @param typeName Type name to delete.
+     * @param primaryFieldValue Primary field value to delete.
+     * @returns True when the delete succeeded.
+     * */
+    delete: (typeName: string, primaryFieldValue: any, context?: TypeInfoORMContext) => Promise<boolean>;
+    /**
+     * List items of the given type, with the given criteria.
+     * @param typeName Type name to list.
+     * @param config List configuration and criteria.
+     * @param selectedFields Optional fields to select.
+     * @returns List results with items and cursor.
+     * */
+    list: (typeName: string, config: ListItemsConfig, selectedFields?: (keyof TypeInfoDataItem)[], context?: TypeInfoORMContext) => Promise<ListItemsResults<Partial<TypeInfoDataItem>>>;
+}