[Text Analytics] Adding analyze and healthcare APIs

[deyaaeldeen]

Implements healthcare and analyze APIs which are LROs and return paginated results.

TODO:
- Update CHANGELOG.md
- Update README.md.
- Add samples.

[willmtemple]

Health poller implementation looks good to me, with a couple of notes about some things that have changed recently, or some minor nitpicks/readability optimizations you might choose to make.

[willmtemple]

This looks great, but I can't help but wonder if this could be replaced by something simpler like

const pagedIterator = Object.assign(this._listHealthcareEntities(jobId, input, options), {
  byPage: (settings?: PageSettings) => {
    const pageOptions = { ...options, top: settings?.maxPageSize };
    return this._listHealthcareEntitiesPaginated(jobId, input, pageOptions);
  });

since essentially all we're doing here is providing an escape to the underlying paged API and the unpaged iterator is just a convenience on top of that.

[deyaaeldeen]

nice!

[xirzec]

Looks like a really cool addition for getting bulk analysis done! I don't think I've seen a poller return a paginated result before either, so that's pretty neat.

I left a lot of developer experience feedback, though my biggest piece of feedback is: where are the samples and examples? I would expect not only some samples to get added, but also the README to demonstrate how to use this very complex API.

[xirzec]

is this for open-ended extensibility? Should we instead make this string and have KnownWarningCodes or something?

[deyaaeldeen]

Hey @joheredi, is this related to a recent change in the code generator? This is the swagger definition: https://github.com/Azure/azure-rest-api-specs/blob/28d37f8847253787a56d39814e7ccd5194aeeabe/specification/cognitiveservices/data-plane/TextAnalytics/preview/v3.1-preview.3/TextAnalytics.json#L815

[joheredi]

Yeah this is the way the generator is doing "extensible" enums. I don't think we have reach a formal agreement on how to generate these.

@xirzec your proposal is to instead of generating this:

export type WarningCode = "LongWordsInDocument" | "DocumentTruncated" | string;
export interface TextAnalyticsWarning {
    code: WarningCode;
    message: string;
}

Do this?

export type KnownWarningCode = "LongWordsInDocument" | "DocumentTruncated";
export interface TextAnalyticsWarning {
    code: string;
    message: string;
}

[willmtemple]

The issue with this way of modeling extensible enums is that it is exactly the same as type WarningCode = string;. The information about known values is only contained in the source code text and is fundamentally erased from the type when it comes down to set theory. Even if we added a KnownWarningCodes enum or type, the problem then is how to associate that type with the parameter in a discoverable way. It's not going to show up when you invoke completion in an IDE, for example.

[xirzec]

I don't really understand BeginAnalyzeHealthcareOptions and BeginAnalyzeOptions having custom subkeys that are just copies of TextAnalyticsOperationOptions with no customization.

I would expect this to instead look like

export interface BeginAnalyzeHealthcareOptions  extends TextAnalyticsOperationOptions, PollingOptions { }

or possibly

export type BeginAnalyzeHealthcareOptions = TextAnalyticsOperationOptions &  PollingOptions

[deyaaeldeen]

I think you are discussing two things here:

• analyze key is typed as AnalyzeJobOptions which is just a synonym to TextAnalyticsOperationOptions, so why not type it as TextAnalyticsOperationOptions instead? I think having a distinct relevant name makes a better user experience with intellisense and it makes it easier to extend this type in the future.
• Why not flatten BeginAnalyzeOptions? I think keeping the options type as is makes it clear to the user which options are used to configure the analyze job itself and which are used to configure the poller.

[xirzec]

feels kinda bad this file is named apiKey.spec.ts but it's not really about testing API keys, it's about testing client methods.

[deyaaeldeen]

Yeah, I was actually thinking of having a single test suite parameterized over the method of authentication and I created this as a first step: #11046

[sadasant]

Clean and fascinating use of core-lro with an asynchronously paginated response! Thank you for your hard work. Approved from this perspective!

addressed