Create a IZosFilesTypedResponse to offer stronger type inference for returned items

[traeok]

Is your feature or enhancement request related to a problem or limitation? Please describe

When using z/OS File APIs, the expected properties in apiResponse are unclear. Since apiResponse is typed as any, this has also allowed inconsistencies to appear in the structure for apiResponse, even though we populate this property ourselves - see #2410

Describe your enhancement idea

By offering a IZosFilesTypedResponse, we can strongly type the apiResponse property to provide TypeScript inference for developers that process these responses.

Example:

export interface IApiResponseWithItems<T> {
    items: T[];
    // ...any remaining properties in `apiResponse` if applicable
    // support any responses that have an `items` property of type `T[]`
    [key: string]: any;
}

export interface IZosFilesTypedResponse<T> implements IZosFilesResponse {
    apiResponse?: IApiResponseWithItems<T>;
}

Describe alternatives you've considered

Users can try to interpret the response by printing it and keeping track of the keys that are returned, referencing existing code, or looking at z/OSMF API documentation. However, this opens up room for mistakes as apiResponse is any, so any property access is considered valid by TypeScript until executed at runtime:

// Invalid property, but this will compile due to the use of `any`
apiResponse.banana

[github-actions]

Thank you for raising this enhancement request.
The community has 90 days to vote on it.
If the enhancement receives at least 5 upvotes, it is added to our development backlog.
If it receives fewer votes, the issue is closed.