Source: util/type-checks.ts

  1. /**
  2.  * @author Michael Hasenstein <hasenstein@yahoo.com>
  3.  * @copyright REFINIO GmbH 2018
  4.  * @license CC-BY-NC-SA-2.5; portions MIT License
  5.  * @version 0.0.1
  6.  */
  8. /**
  9.  * A module with functions that perform runtime type checks. There are very simple checks such
  10.  * as `isString()`, there also are complex checks.
  11.  * @module
  12.  */
  14. /**
  15.  * (Simulated) opaque type name alias for strings that are SHA-256 hashes _pointing to
  16.  * concrete objects_.
  17.  *
  18.  * This type has a generic parameter: A member or a union of {@link OneObjectTypes} as well
  19.  * as the virtual types {@link BLOB} and {@link CLOB}.
  20.  *
  21.  * This generic parameter is used by and passed through all major one.core functions' type
  22.  * definitions. For example, after storing an object the hashes in the object creation
  23.  * result object will be tagged with the typed of the object.
  24.  * @global
  25.  * @typedef {string} SHA256Hash
  26.  */
  27. export type SHA256Hash<T extends HashTypes = OneObjectTypes> = string & {
  28.     _: 'SHA256Hash';
  29.     type: T;
  30. };
  32. /**
  33.  * (Simulated) opaque type name alias for strings that are SHA-256 hashes _pointing to ID
  34.  * objects, i.e. to all past, present and future versions of a versioned object_.
  35.  *
  36.  * This type has a generic parameter: A member or a union of {@link OneObjectTypes} as well
  37.  * as the virtual types {@link BLOB} and {@link CLOB}.
  38.  * @global
  39.  * @typedef {string} SHA256IdHash
  40.  */
  41. export type SHA256IdHash<
  42.     T extends OneVersionedObjectTypes | OneIdObjectTypes = OneVersionedObjectTypes
  43. > = string & {
  44.     _: 'SHA256IdHash';
  45.     type: T;
  46. };
  48. /**
  49.  * This is a TypeScript helper type that extracts the type of the elements of certain container
  50.  * types. If the container is read-only and its elements are known this results in a union type
  51.  * of those elements.
  52.  *
  53.  * Examples:
  54.  * ```
  55.  * const set = new Set(['a', 'b', 'c'] as const);
  56.  * // "a" | "b" | "c"
  57.  * type SSS = ElementType<typeof set>;
  58.  *
  59.  * const arr = ['aa', 'bb', 'cc'] as const;
  60.  * // // "aa" | "bb" | "cc"
  61.  * type AAA = ElementType<typeof arr>;
  62.  *
  63.  * const map = new Map([['a', 1], ['b', 2], ['c', 42]] as const);
  64.  * // 1 | 2 | 42
  65.  * type MMM = ElementType<typeof map>;
  66.  * ```
  67.  * @global
  68.  * @template T
  69.  * @typedef {*} ElementType<T>
  70.  */
  71. export type ElementType<T> = T extends Array<infer U>
  72.     ? U
  73.     : T extends Readonly<Array<infer U>>
  74.     ? U
  75.     : T extends Set<infer U>
  76.     ? U
  77.     : T extends Readonly<Set<infer U>>
  78.     ? U
  79.     : T extends Map<any, infer U>
  80.     ? U
  81.     : T extends Readonly<Map<any, infer U>>
  82.     ? U
  83.     : T extends Promise<infer U>
  84.     ? U
  85.     : T;
  87. import {createError} from '../errors';
  88. import type {
  89.     ArrayValue,
  90.     BagValue,
  91.     HashTypes,
  92.     OneIdObjectTypes,
  93.     OneObjectTypes,
  94.     OneVersionedObjectTypes,
  95.     RecipeRule,
  96.     SetValue,
  97.     ValueType
  98. } from '../recipes';
  99. import type {FileCreation, SimpleReadStream} from '../storage-base-common';
  100. import {CREATION_STATUS} from '../storage-base-common';
  101. import type {AnyObject} from './object';
  102. import type {OneEventSource, OneEventSourceConsumer} from './one-event-source';
  103. import {isFunction, isObject, isString} from './type-checks-basic';
  105. /**
  106.  * A regular expression that can be used to verify that a given string looks like a
  107.  * cryptographic hash string used to represent ONE objects. For SHA-256 it tests if there
  108.  * are 64 characters and that each one of them is between 0-9 or a-f.
  109.  * @private
  110.  * @type {RegExp}
  111.  */
  112. const CRYPTO_HASH_RE = /^[0-9a-f]{64}$/;
  114. /**
  115.  * Used to check request results. Values "new" and "exists".
  116.  * @private
  117.  * @type {Set<string>}
  118.  */
  119. const FILE_CREATION_STATUS_VALUES = new Set(Object.values(CREATION_STATUS));
  121. /**
  122.  * An alternative to `Object.keys(o).length` that is more efficient. Running a test loop
  123.  * comparing the two showed less than half the time for the for-loop option. Also, `Object.keys`
  124.  * creates a temporary array.
  125.  * @static
  126.  * @param {object} o
  127.  * @returns {number}
  128.  */
  129. export function countEnumerableProperties(o: AnyObject): number {
  130.     let count = 0;
  132.     for (const prop in o) {
  133.         if (Object.prototype.hasOwnProperty.call(o, prop)) {
  134.             count += 1;
  135.         }
  136.     }
  138.     return count;
  139. }
  141. /**
  142.  * Valid encodings for file streams are binary (undefined or null), "base64" and "utf8".
  143.  * @static
  144.  * @param {*} thing
  145.  * @returns {boolean}
  146.  */
  147. export function isEncoding(thing: unknown): thing is undefined | 'base64' | 'utf8' {
  148.     return thing === undefined || thing === 'base64' || thing === 'utf8';
  149. }
  151. /**
  152.  * ONE uses SHA-256 hashes in hexadecimal lowercase format to represent the contents of files.
  153.  * This functions tests a given "thing" of any type if it is such a string.
  154.  *
  155.  * For the curious: Why a function?
  156.  *
  157.  * While one might simply test against a regular expression using myRegEx.test(thing) this
  158.  * method has one more or less theoretical problem: If the thing is an object with a toString()
  159.  * method that returns a matching string the test will return "true" even though the thing is an
  160.  * object and not a string. For example,
  161.  * ```javascript
  162.  * /^s+$/.test( {toString: () => 'sss'} );
  163.  * ```
  164.  * will return true.
  165.  * @static
  166.  * @param {*} thing - An argument that can be of any type
  167.  * @returns {boolean} True if the argument is a SHA-256 lowercase hexadecimal string, false if not
  168.  */
  169. export function isHash<T extends HashTypes>(
  170.     thing: unknown
  171. ): thing is SHA256Hash<T> | SHA256IdHash<T extends OneVersionedObjectTypes ? T : never> {
  172.     return isString(thing) && CRYPTO_HASH_RE.test(thing);
  173. }
  175. /**
  176.  * Non-regex version of the "isHash" function in an attempt to save a tiny bit of CPU because we
  177.  * don't need a full regex check here. "Premature optimization" vs. "it's cheap and easy", and
  178.  * according to reported real world runtime experience these hash checks can add up and become
  179.  * significant.
  180.  * @param {*} s
  181.  * @returns {boolean}
  182.  */
  183. export function looksLikeHash(s: unknown): boolean {
  184.     return typeof s === 'string' && s.length === 64;
  185. }
  187. /**
  188.  * The function returns the given value after making sure it is a SHA-256 hexadecimal string. It
  189.  * throws an Error if this is not the case.
  190.  * @static
  191.  * @param {*} thing
  192.  * @returns {SHA256Hash}
  193.  * @throws {Error}
  194.  */
  195. export function ensureHash<T extends HashTypes>(thing: unknown): SHA256Hash<T> {
  196.     if (isHash<T>(thing)) {
  197.         return thing as SHA256Hash<T>;
  198.     }
  200.     throw createError('UTC-EHASH', {thing});
  201. }
  203. /**
  204.  * The function returns the given value after making sure it is a SHA-256 hexadecimal string. It
  205.  * throws an Error if this is not the case.
  206.  * @static
  207.  * @param {*} thing
  208.  * @returns {SHA256Hash}
  209.  * @throws {Error}
  210.  */
  211. export function ensureIdHash<T extends OneVersionedObjectTypes = any>(
  212.     thing: unknown
  213. ): SHA256IdHash<T> {
  214.     if (isHash<T>(thing)) {
  215.         return thing as SHA256IdHash<T>;
  216.     }
  218.     throw createError('UTC-EHASH', {thing});
  219. }
  221. /**
  222.  * Checks if a given object is a ONE.core {@link OneEventSourceConsumer} object by testing the
  223.  * properties (duck typing).
  224.  * @static
  225.  * @param {*} thing
  226.  * @returns {boolean}
  227.  */
  228. export function isEventSourceConsumer(thing: unknown): thing is OneEventSourceConsumer<unknown> {
  229.     return isObject(thing) && isFunction(thing.addListener) && isFunction(thing.removeListener);
  230. }
  232. /**
  233.  * Checks if a given object is a ONE.core {@link OneEventSource} object by testing the properties
  234.  * (duck typing).
  235.  * @static
  236.  * @param {*} thing
  237.  * @returns {boolean}
  238.  */
  239. export function isEventSource(thing: unknown): thing is OneEventSource<unknown> {
  240.     return isObject(thing) && isEventSourceConsumer(thing.consumer);
  241. }
  243. /**
  244.  * Checks if a given object is a ONE.core {@link SimpleReadStream} object by testing the
  245.  * properties (duck typing).
  246.  * @static
  247.  * @param {*} thing
  248.  * @returns {boolean}
  249.  */
  250. export function isSimpleReadStream(thing: unknown): thing is SimpleReadStream {
  251.     return (
  252.         isObject(thing) &&
  253.         isFunction(thing.pause) &&
  254.         isFunction(thing.resume) &&
  255.         isFunction(thing.cancel) &&
  256.         thing.promise instanceof Promise &&
  257.         isEncoding(thing.thing) &&
  258.         isEventSourceConsumer(thing.onData)
  259.     );
  260. }
  262. /**
  263.  * Checks for {@link FileCreation} objects. They are used to return the result of saving BLOBs
  264.  * and CLOBs to storage.
  265.  * @static
  266.  * @param {*} thing
  267.  * @returns {boolean}
  268.  */
  269. export function isFileCreationResult(thing: unknown): thing is FileCreation<any> {
  270.     return (
  271.         isObject(thing) &&
  272.         countEnumerableProperties(thing) === 2 &&
  273.         isHash(thing.hash) &&
  274.         FILE_CREATION_STATUS_VALUES.has(thing.status)
  275.     );
  276. }
  278. /**
  279.  * @static
  280.  * @param {*} thing - Data e.g. from a network connection expected to be of format SHA256Hash[]
  281.  * @returns {SHA256Hash[]} Returns the data now confirmed to be of type Array of SHA256Hash
  282.  * @throws {Error} Throws an Error when the given data is not an array of (only) SHA-256
  283.  * hashes
  284.  */
  285. export function ensureArrayOfSHA256Hash(thing: unknown): Array<SHA256Hash<HashTypes>> {
  286.     if (Array.isArray(thing) && thing.every(item => isHash(item))) {
  287.         return thing as Array<SHA256Hash<HashTypes>>;
  288.     }
  290.     throw createError('UTC-AHASH', {thing});
  291. }
  293. /**
  294.  * @static
  295.  * @param {RecipeRule} obj
  296.  * @returns {RecipeRule}
  297.  */
  298. export function ruleHasItemType(obj: RecipeRule): obj is RecipeRule & {itemtype: ValueType} {
  299.     return Object.prototype.hasOwnProperty.call(obj, 'itemtype');
  300. }
  302. /**
  303.  * Check if the valueType is a list type: array, bag, or set.
  304.  * @static
  305.  * @param {ValueType} arg
  306.  * @returns {boolean}
  307.  */
  308. export function isListItemType(arg: ValueType): arg is BagValue | ArrayValue | SetValue {
  309.     return arg.type === 'array' || arg.type === 'bag' || arg.type === 'set';
  310. }