diff options
Diffstat (limited to 'node_modules/@apple-media-services/media-api/src/models/server-data.ts')
| -rw-r--r-- | node_modules/@apple-media-services/media-api/src/models/server-data.ts | 476 |
1 files changed, 476 insertions, 0 deletions
diff --git a/node_modules/@apple-media-services/media-api/src/models/server-data.ts b/node_modules/@apple-media-services/media-api/src/models/server-data.ts new file mode 100644 index 0000000..a1aca3f --- /dev/null +++ b/node_modules/@apple-media-services/media-api/src/models/server-data.ts @@ -0,0 +1,476 @@ +// +// server-data.ts +// AppStoreKit +// +// Created by Kevin MacWhinnie on 8/17/16. +// Copyright (c) 2016 Apple Inc. All rights reserved. +// + +// TODO: Replace this utility for JSON Parsing +import * as validation from "@jet/environment/json/validation"; +import { Nothing, Opt, isNothing } from "@jet/environment/types/optional"; +import { JSONArray, JSONData, JSONValue, MapLike } from "./json-types"; + +// region Traversal + +/** + * Union type that describes the possible representations for an object traversal path. + */ +export type ObjectPath = string | string[]; + +/** + * Returns the string representation of a given object path. + * @param path The object path to coerce to a string. + * @returns A string representation of `path`. + */ +export function objectPathToString(path: Opt<ObjectPath>): Opt<string> { + if (isNull(path)) { + return null; + } else if (Array.isArray(path)) { + return path.join("."); + } else { + return path; + } +} + +const PARSED_PATH_CACHE: { [key: string]: string[] } = {}; + +/** + * Traverse a nested JSON object structure, short-circuiting + * when finding `undefined` or `null` values. Usage: + * + * const object = {x: {y: {z: 42}}}; + * const meaningOfLife = serverData.traverse(object, 'x.y.z'); + * + * @param object The JSON object to traverse. + * @param path The path to search. If falsy, `object` will be returned without being traversed. + * @param defaultValue The object to return if the path search fails. + * @return The value at `path` if found; default value otherwise. + */ +export function traverse(object: JSONValue, path?: ObjectPath, defaultValue?: JSONValue): JSONValue { + if (object === undefined || object === null) { + return defaultValue; + } + + if (isNullOrEmpty(path)) { + return object; + } + + let components: string[]; + if (typeof path === "string") { + components = PARSED_PATH_CACHE[path]; + if (isNullOrEmpty(components)) { + // Fast Path: If the path contains only a single component, we can skip + // all of the work below here and speed up storefronts that + // don't have JIT compilation enabled. + if (!path.includes(".")) { + const value = object[path]; + if (value !== undefined && value !== null) { + return value; + } else { + return defaultValue; + } + } + + components = path.split("."); + PARSED_PATH_CACHE[path] = components; + } + } else { + components = path; + } + + let current: JSONValue = object; + for (const component of components) { + current = current[component]; + if (current === undefined || current === null) { + return defaultValue; + } + } + return current; +} + +// endregion + +// region Nullability + +/** + * Returns a bool indicating whether or not a given object null or undefined. + * @param object The object to test. + * @return true if the object is null or undefined; false otherwise. + */ +export function isNull<Type>(object: Type | Nothing): object is Nothing { + return object === null || object === undefined; +} + +/** + * Returns a bool indicating whether or not a given object is null or empty. + * @param object The object to test + * @return true if object is null or empty; false otherwise. + */ +export function isNullOrEmpty<Type>(object: Type | Nothing): object is Nothing { + // eslint-disable-next-line @typescript-eslint/no-explicit-any + return isNull(object) || Object.keys(object as any).length === 0; +} + +/** + * Returns a bool indicating whether or not a given object is non-null. + * @param object The object to test. + * @return true if the object is not null or undefined; false otherwise. + */ +export function isDefinedNonNull<Type>(object: Type | null | undefined): object is Type { + return typeof object !== "undefined" && object !== null; +} + +/** + * Returns a bool indicating whether or not a given object is non-null or empty. + * @param object The object to test. + * @return true if the object is not null or undefined and not empty; false otherwise. + */ +export function isDefinedNonNullNonEmpty<Type>(object: Type | Nothing): object is Type { + // eslint-disable-next-line @typescript-eslint/no-explicit-any + return isDefinedNonNull(object) && Object.keys(object as any).length !== 0; +} + +/** + * Checks if the passed string or number is a number + * + * @param value The value to check + * @return True if the value is an number, false if not + */ +export function isNumber(value: number | string | null | undefined): value is number { + if (isNull(value)) { + return false; + } + + let valueToCheck; + if (typeof value === "string") { + valueToCheck = parseInt(value); + } else { + valueToCheck = value; + } + + return !Number.isNaN(valueToCheck); +} + +/** + * Returns a bool indicating whether or not a given object is defined but empty. + * @param object The object to test. + * @return true if the object is not null and empty; false otherwise. + */ +export function isArrayDefinedNonNullAndEmpty<Type extends JSONArray>(object: Type | null | undefined): object is Type { + return isDefinedNonNull(object) && object.length === 0; +} + +// endregion + +// region Defaulting Casts + +/** + * Check that a given object is an array, substituting an empty array if not. + * @param object The object to coerce. + * @param path The path to traverse on `object` to find an array. + * Omit this parameter if `object` is itself an array. + * @returns An untyped array. + */ +export function asArrayOrEmpty<T extends JSONValue>(object: JSONValue, path?: ObjectPath): T[] { + const target = traverse(object, path, null); + if (Array.isArray(target)) { + // Note: This is kind of a nasty cast, but I don't think we want to validate that everything is of type T + return target as T[]; + } else { + if (!isNull(target)) { + validation.context("asArrayOrEmpty", () => { + validation.unexpectedType("defaultValue", "array", target, objectPathToString(path)); + }); + } + return []; + } +} + +/** + * Check that a given object is a boolean, substituting the value `false` if not. + * @param object The object to coerce. + * @param path The path to traverse on `object` to find a boolean. + * Omit this parameter if `object` is itself a boolean. + * @returns A boolean from `object`, or defaults to `false`. + */ +export function asBooleanOrFalse(object: JSONValue, path?: ObjectPath): boolean { + const target = traverse(object, path, null); + if (typeof target === "boolean") { + return target; + } else { + if (!isNull(target)) { + validation.context("asBooleanOrFalse", () => { + validation.unexpectedType("defaultValue", "boolean", target, objectPathToString(path)); + }); + } + return false; + } +} + +// endregion + +// region Coercing Casts + +export type ValidationPolicy = "strict" | "coercible" | "none"; + +/** + * Safely coerce an object into a string. + * @param object The object to coerce. + * @param path The path to traverse on `object` to find a string. + * Omit this parameter if `object` is itself a string. + * @param policy The validation policy to use when resolving this value + * @returns A string from `object`, or `null` if `object` is null. + */ +export function asString(object: JSONValue, path?: ObjectPath, policy: ValidationPolicy = "coercible"): Opt<string> { + const target = traverse(object, path, null); + if (isNull(target)) { + return target; + } else if (typeof target === "string") { + return target; + } else { + // We don't consider arbitrary objects as convertable to strings even through they will result in some value + const coercedValue = typeof target === "object" ? null : String(target); + switch (policy) { + case "strict": { + validation.context("asString", () => { + validation.unexpectedType("coercedValue", "string", target, objectPathToString(path)); + }); + break; + } + case "coercible": { + if (isNull(coercedValue)) { + validation.context("asString", () => { + validation.unexpectedType("coercedValue", "string", target, objectPathToString(path)); + }); + } + break; + } + case "none": + default: { + break; + } + } + + return coercedValue; + } +} + +/** + * Safely coerce an object into a date. + * @param object The object to coerce. + * @param path The path to traverse on `object` to find a date. + * @param policy The validation policy to use when resolving this value + * @returns A date from `object`, or `null` if `object` is null. + */ +export function asDate(object: JSONValue, path?: ObjectPath, policy: ValidationPolicy = "coercible"): Opt<Date> { + const dateString = asString(object, path, policy); + if (isNothing(dateString)) { + return null; + } + return new Date(dateString); +} + +/** + * Safely coerce an object into a number. + * @param object The object to coerce. + * @param path The path to traverse on `object` to find a number. + * Omit this parameter if `object` is itself a number. + * @param policy The validation policy to use when resolving this value + * @returns A number from `object`, or `null` if `object` is null. + */ +export function asNumber(object: JSONValue, path?: ObjectPath, policy: ValidationPolicy = "coercible"): Opt<number> { + const target = traverse(object, path, null); + if (isNull(target) || typeof target === "number") { + return target; + } else { + const coercedValue = Number(target); + switch (policy) { + case "strict": { + validation.context("asNumber", () => { + validation.unexpectedType("coercedValue", "number", target, objectPathToString(path)); + }); + break; + } + case "coercible": { + if (isNaN(coercedValue)) { + validation.context("asNumber", () => { + validation.unexpectedType("coercedValue", "number", target, objectPathToString(path)); + }); + return null; + } + break; + } + case "none": + default: { + break; + } + } + + return coercedValue; + } +} + +/** + * Safely coerce an object into a dictionary. + * @param object The object to coerce. + * @param path The path to traverse on `object` to find the dictionary. + * Omit this parameter if `object` is itself a dictionary. + * @param defaultValue The object to return if the path search fails. + * @returns A sub-dictionary from `object`, or `null` if `object` is null. + */ +export function asDictionary<Type extends JSONValue>( + object: JSONValue, + path?: ObjectPath, + defaultValue?: MapLike<Type>, +): MapLike<Type> | null { + const target = traverse(object, path, null); + if (target instanceof Object && !Array.isArray(target)) { + // Note: It's too expensive to actually validate this is a dictionary of { string : Type } at run time + return target as MapLike<Type>; + } else { + if (!isNull(target)) { + validation.context("asDictionary", () => { + validation.unexpectedType("defaultValue", "object", target, objectPathToString(path)); + }); + } + + if (isDefinedNonNull(defaultValue)) { + return defaultValue; + } + return null; + } +} + +/** + * Safely coerce an object into a given interface. + * @param object The object to coerce. + * @param path The path to traverse on `object` to find a string. + * Omit this parameter if `object` is itself a string. + * @param defaultValue The object to return if the path search fails. + * @returns A sub-dictionary from `object`, or `null` if `object` is null. + */ +export function asInterface<Interface>( + object: JSONValue, + path?: ObjectPath, + defaultValue?: JSONData, +): Interface | null { + return asDictionary(object, path, defaultValue) as unknown as Interface; +} + +/** + * Coerce an object into a boolean. + * @param object The object to coerce. + * @param path The path to traverse on `object` to find a boolean. + * Omit this parameter if `object` is itself a boolean. + * @param policy The validation policy to use when resolving this value + * @returns A boolean from `object`, or `null` if `object` is null. + * @note This is distinct from `asBooleanOrFalse` in that it doesn't default to false, + * and it tries to convert string boolean values into actual boolean types + */ +export function asBoolean( + object: JSONValue, + path?: ObjectPath, + policy: ValidationPolicy = "coercible", +): boolean | null { + const target = traverse(object, path, null); + + // Value was null + if (isNull(target)) { + return null; + } + + // Value was boolean. + if (typeof target === "boolean") { + return target; + } + + // Value was string. + if (typeof target === "string") { + if (target === "true") { + return true; + } else if (target === "false") { + return false; + } + } + + // Else coerce. + const coercedValue = Boolean(target); + switch (policy) { + case "strict": { + validation.context("asBoolean", () => { + validation.unexpectedType("coercedValue", "number", target, objectPathToString(path)); + }); + break; + } + case "coercible": { + if (isNull(coercedValue)) { + validation.context("asBoolean", () => { + validation.unexpectedType("coercedValue", "number", target, objectPathToString(path)); + }); + return null; + } + break; + } + case "none": + default: { + break; + } + } + + return coercedValue; +} + +/** + * Attempts to coerce the passed value to a JSONValue + * + * Note: due to performance concerns this does not perform a deep inspection of Objects or Arrays. + * + * @param value The value to coerce + * @return A JSONValue or null if value is not a valid JSONValue type + */ +export function asJSONValue(value: unknown): JSONValue | null { + if (value === null || value === undefined) { + return null; + } + switch (typeof value) { + case "string": + case "number": + case "boolean": + return value as JSONValue; + case "object": + // Note: It's too expensive to actually validate this is an array of JSONValues at run time + if (Array.isArray(value)) { + return value as JSONValue; + } + // Note: It's too expensive to actually validate this is a dictionary of { string : JSONValue } at run time + return value as JSONValue; + default: + validation.context("asJSONValue", () => { + validation.unexpectedType("defaultValue", "JSONValue", typeof value); + }); + return null; + } +} + +/** + * Attempts to coerce the passed value to JSONData + * + * @param value The value to coerce + * @return A JSONData or null if the value is not a valid JSONData object + */ +export function asJSONData(value: unknown): JSONData | null { + if (value === null || value === undefined) { + return null; + } + if (value instanceof Object && !Array.isArray(value)) { + // Note: It's too expensive to actually validate this is a dictionary of { string : Type } at run time + return value as JSONData; + } + validation.context("asJSONValue", () => { + validation.unexpectedType("defaultValue", "object", typeof value); + }); + return null; +} + +// endregion |