Fix mapUri type definition

[joshkel]

It's used with await, so it may return a promise or non-promise value. The examples in API.md return a non-promise.

[Marsup]

In general, I think it's best not to use polymorphic functions, so while it's possible, I'm not sure it should be encouraged.

[joshkel]

@Marsup Thanks for the reply.

Maybe this is just a difference in terminology, but I've never heard this referred to as a polymorphic function. In TypeScript, I've understood polymorphic functions to be more or less a synonym for what the TypeScript documentation calls function overloading. From their docs:

function makeDate(timestamp: number): Date;
function makeDate(m: number, d: number, y: number): Date;
function makeDate(mOrTimestamp: number, d?: number, y?: number): Date {
  if (d !== undefined && y !== undefined) {
    return new Date(y, mOrTimestamp, d);
  } else {
    return new Date(mOrTimestamp);
  }
}

I agree that that style of API design can be confusing. However, this case - a function that can be synchronous or asynchronous, as expressed by a TypeScript return value that's a union of T | Promise<T> - is much simpler and more limited. It's directly supported by JavaScript's await, and it nicely simplifies code (which would otherwise have to add a spurious Promise.resolve calls on every synchronous return value). It's also widely used by Hapi itself - lifecycle methods such as route handlers and failAction methods are documented as returning either a value or a promise that resolves to a value, and plugins' register methods use the same technique to allow them to be synchronous or asynchronous without triggering a type error.

[Marsup]

Makes sense. Thanks!