/**
 * We try to keep public and private types close to keep the API more
 * maintainable. However, occasionally we must diverge to hide some private
 * details from the public API.
 *
 * Use this type helper when public TypeScript type must diverge from the
 * private type.
 *
 * @example
 * ```ts
 * type ActionType = PublicApiNarrowType<
 *   "create" | "update" | "delete",
 *   "create" | "delete"
 * >;
 * ```
 *
 * In private types, the 1st type parameter will be used for type checking,
 * making the effective type `"create" | "update" | "delete"`.
 *
 * But in public `.d.ts` and public docs, the above will appear like this:
 *
 * ```ts
 * type ActionType = "create" | "delete";
 * ```
 *
 * Remember that properties without `public` tag are not publicly exposed.
 * Thus, in practice, `PublicApiNarrowType` is most commonly needed to hide
 * private union members.
 *
 * To ensure public type does not get out of date, `PublicApiNarrowType`
 * requires that the public type extends the private type (or in other words, a
 * subset of the private type). If that restriction is too tight, use
 * `PublicApiRelaxType` instead.
 */
export type PublicApiNarrowType<PrivateType, _PublicType extends PrivateType> = PrivateType;

/**
 * Most of the time, when the public type must diverge from the private type,
 * the public type is a subset of the private type - in such cases use
 * `PublicApiNarrowType`.
 *
 * Occasionally, the public type may need to be a superset of the private type
 * or even an unrelated type. For those cases, use `PublicApiRelaxType`.
 *
 * Keep usages of `PublicApiRelaxType` at minimum as it disables type
 * checking between public and private types.
 *
 * @example
 * ```ts
 * type EditableLayers = FeatureLayer | ...;
 * class MyClass {
 *   // Layer is a superset of EditableLayers, not subset,
 *   // so we must use PublicApiRelaxType.
 *   layer: PublicApiRelaxType<EditableLayers, Layer>;
 *
 *   // StrictNumberType is a branded type that is incompatible
 *   // with regular number type.
 *   jobId: PublicApiRelaxType<StrictNumberType<"JobId">, number>;
 * }
 * ```
 */
export type PublicApiRelaxType<PrivateType, _PublicType> = PrivateType;