@energica-city/shared-amplify-utils/dist/queries/restAware.d.ts

Shared utilities for AWS Amplify projects

import type { QueryFactoryResult, AmplifyModelType, ModelType, CreateInput, UpdateInput, DeleteInput, Identifier, SortDirection, AmplifyAuthMode, PaginationResult, ModelFilter, SelectionSet } from './types';
/**
 * REST-aware query operations interface with HTTP error handling.
 *
 * Extends standard QueryFactory operations with REST-specific error handling
 * that automatically maps database errors to appropriate HTTP status codes.
 * All operations throw RestErrors instead of generic errors.
 *
 * @template T - Model name as string literal
 * @template TTypes - Record of all available Amplify model types
 * @interface RestAwareQueryOperations
 */
export interface RestAwareQueryOperations<T extends string, TTypes extends Record<T, AmplifyModelType>> {
    /**
     * Retrieve a single record by identifier with 404 error handling.
     *
     * @param props - Object containing identifier input
     * @param props.input - Identifier for the record to retrieve
     * @param props.selectionSet - Optional array of fields to retrieve (supports dot notation)
     * @returns Promise resolving to the retrieved record
     * @throws {RestError} 404 if record not found, 500 for other errors
     */
    get(props: {
        input: Identifier<T, TTypes>;
        selectionSet?: SelectionSet;
    }): Promise<ModelType<T, TTypes>>;
    /**
     * Create a new record with validation and conflict error handling.
     *
     * @param props - Object containing creation input
     * @param props.input - Data for creating the record
     * @returns Promise resolving to the created record
     * @throws {RestError} 400 for validation errors, 409 for conflicts, 500 for other errors
     */
    create(props: {
        input: CreateInput<T, TTypes>;
    }): Promise<ModelType<T, TTypes>>;
    /**
     * Update an existing record with comprehensive error handling.
     *
     * @param props - Object containing update input
     * @param props.input - Data for updating the record (must include identifier)
     * @returns Promise resolving to the updated record
     * @throws {RestError} 404 if not found, 400 for validation, 409 for conflicts, 500 for other errors
     */
    update(props: {
        input: UpdateInput<T, TTypes>;
    }): Promise<ModelType<T, TTypes>>;
    /**
     * Delete an existing record with 404 error handling.
     *
     * @param props - Object containing deletion input
     * @param props.input - Identifier for the record to delete
     * @returns Promise resolving to the deleted record
     * @throws {RestError} 404 if record not found, 500 for other errors
     */
    delete(props: {
        input: DeleteInput<T, TTypes>;
    }): Promise<ModelType<T, TTypes>>;
    /**
     * Retrieve multiple records with pagination and general error handling.
     *
     * @param props - Optional configuration for the list operation
     * @returns Promise resolving to paginated results
     * @throws {RestError} 500 for any operation errors
     */
    list(props?: {
        filter?: ModelFilter<ModelType<T, TTypes>>;
        sortDirection?: SortDirection;
        limit?: number;
        nextToken?: string;
        authMode?: AmplifyAuthMode;
        followNextToken?: boolean;
        maxPages?: number;
        selectionSet?: SelectionSet;
    }): Promise<PaginationResult<ModelType<T, TTypes>>>;
    /**
     * Execute a named secondary index query with general error handling.
     *
     * @param props - Configuration for the index query
     * @returns Promise resolving to paginated results
     * @throws {RestError} 500 for any operation errors
     */
    queryIndex(props: {
        queryField: string;
        input?: Record<string, unknown>;
        filter?: ModelFilter<ModelType<T, TTypes>>;
        limit?: number;
        nextToken?: string;
        authMode?: AmplifyAuthMode;
        followNextToken?: boolean;
        maxPages?: number;
        selectionSet?: SelectionSet;
    }): Promise<PaginationResult<ModelType<T, TTypes>>>;
}
/**
 * Creates REST-aware query factory wrappers with automatic HTTP error mapping.
 *
 * Wraps standard QueryFactory operations to intercept database errors and convert
 * them to appropriate REST errors with proper HTTP status codes. This enables
 * consistent REST API error responses without manual error handling in each endpoint.
 *
 * **Error Mapping Strategy:**
 * - `"No data returned"` → 404 Not Found
 * - AppSync validation errors → 400 Bad Request
 * - Conflict/constraint violations → 409 Conflict
 * - All other errors → 500 Internal Server Error
 *
 * @template T - Model name type extending string
 * @template TTypes - Record of all available Amplify model types
 * @param rawModel - Original QueryFactory instance to wrap
 * @param modelName - Human-readable model name for error messages
 * @param context - Request context object for error logging and tracing
 * @returns REST-aware query operations that throw HTTP-appropriate errors
 *
 * @example
 * ```typescript
 * const restQueries = createRestAwareQueryOperations(
 *   queries.User,
 *   "User",
 *   { requestId: "req-123", userId: "current-user" }
 * );
 *
 * // Automatically throws 404 RestError if user not found
 * const user = await restQueries.get({ input: { userId: "123" } });
 * ```
 */
export declare function createRestAwareQueryOperations<T extends string, TTypes extends Record<T, AmplifyModelType>>(rawModel: QueryFactoryResult<T, TTypes>, modelName: string, context: Record<string, unknown>): RestAwareQueryOperations<T, TTypes>;
//# sourceMappingURL=restAware.d.ts.map