@qikdev/sdk/src/api/qik.content.js

Promise based Javascript SDK

///////////////////////////////////////////////////

/**
 * Creates a new QikContent instance.
 * This module provides a number of helper functions for creating and modifying content via the REST API
 * @alias content
 * @constructor
 * @hideconstructor
 * @param {QikCore} qik A reference to the parent instance of the QikCore module. This module is usually created by a QikCore instance that passes itself in as the first argument.
 */
export default function (qik) {
  if (!qik.api) {
    throw new Error(`Can't Instantiate QikContent before QikAPI exists`);
  }

  ///////////////////////////////////////////////////

  var service = {
    debug: false,
    loadingGlossary: false,
  };

  ///////////////////////////////////////////////////////////////////////////////

  const variables = {};
  let inflightVariablesRequest;

  /**
   *
   * Retrieves all global variables for the current user. This is often used when running custom code in an action.
   * @alias content.variables
   * @param  {Array} keys Provide specific keys of variables you want to retrieve
   * @param  {Object} options Additional options when making the request
   * @param  {Boolean} options.reload Force variables to reload and not be cached. If false will retrieve any variables that are already known from the in memory cache.
   * @example
   *
   * const { OAUTH_CLIENT_ID, OAUTH_KEY } = await sdk.content.variables();
   */

  service.variables = async function (keys, options) {
    options = options || {};
    keys = keys || [];

    var reload = options.refresh || options.reload || !variables.data;
    if (reload) {
      if (!inflightVariablesRequest) {
        inflightVariablesRequest = qik.api.post(`/variables`, { keys });
        inflightVariablesRequest.then(resolveRequest, resolveRequest);
        function resolveRequest() {
          inflightVariablesRequest = null;
        }
      }

      const { data } = await inflightVariablesRequest;
      variables.data = data;
      qik.dispatch("variables", data);
    }

    return variables.data;
  };

  ///////////////////////////////////////////////////

  const glossaryCache = qik.cache.get("user:glossary");

  let inflightGlossaryRequest;

  /**
   * Yield to the event loop to keep the UI responsive
   * @private
   */
  function yieldToMain() {
    return new Promise((resolve) => {
      if (typeof requestIdleCallback === "function") {
        requestIdleCallback(resolve, { timeout: 50 });
      } else {
        setTimeout(resolve, 0);
      }
    });
  }

  /**
   * Inflate compressed glossary data from the /glossary/compressed endpoint
   * Processes in chunks to avoid blocking the main thread
   * @private
   */
  async function inflateGlossary({ _s: strings, _k: keyMap, types }) {
    function inflate(val) {
      if (typeof val === "string" && val[0] === "~") {
        return strings[parseInt(val.slice(1))];
      }
      if (Array.isArray(val)) return val.map(inflate);
      if (val && typeof val === "object") {
        const result = {};
        for (const [k, v] of Object.entries(val)) {
          result[keyMap[k] || k] = inflate(v);
        }
        return result;
      }
      return val;
    }

    const CHUNK_SIZE = 50;
    const results = [];

    for (let i = 0; i < types.length; i += CHUNK_SIZE) {
      const chunk = types.slice(i, i + CHUNK_SIZE);
      results.push(...chunk.map(inflate));

      // Yield to main thread between chunks
      if (i + CHUNK_SIZE < types.length) {
        await yieldToMain();
      }
    }

    return results;
  }

  /**
     *
     * Retrieves the glossary of all content types visible to the requesting user.
     By default this will include all fields, validation, expressions and other configuration
     * @alias content.glossary
     * @param  {Object} options Additional options
     * @param  {Boolean} options.hash Whether to return the data as a keyed object
     allowing for fast selection of specific content types, by default will return as an array
     * @param  {Boolean} options.reload Force glossary to reload and not be cached.
      If false will retrieve content type data from the in memory cache
     * @param  {Boolean} options.uncompressed Use the uncompressed endpoint
     * @example
     *
     * const { article, profile } = await sdk.content.glossary({hash:true});
     * // Use compressed endpoint for faster loading
     * const glossary = await sdk.content.glossary({compressed:true});
     */
  service.glossary = async function (options) {
    options = options || {};

    // Check if we already have the glossary cached
    let cached = glossaryCache.get("glossary");
    const uncompressed = !!options.uncompressed;
    let compressed = !uncompressed;
    var reload = options.refresh || options.reload || !cached;

    // If we are forcing a reload
    if (reload) {
      if (!inflightGlossaryRequest) {
        service.loadingGlossary = true;

        // Use compressed endpoint if requested
        const endpoint = compressed ? `/glossary/compressed` : `/glossary`;
        inflightGlossaryRequest = qik.api.get(endpoint, { cache: false });
        inflightGlossaryRequest.then(resolveRequest, resolveRequest);
        function resolveRequest() {
          inflightGlossaryRequest = null;
          service.loadingGlossary = false;
        }
      }

      // Now we have the glossary
      const { data } = await inflightGlossaryRequest;

      // Inflate if compressed format (async to avoid blocking UI)
      const glossaryData =
        data._s && data._k && data.types ? await inflateGlossary(data) : data;

      // Cache it for later
      glossaryCache.set("glossary", glossaryData);
      cached = glossaryData;
      qik.dispatch("glossary", glossaryData);
    }

    if (options.hash) {
      var result = qik.utils.hash(cached, "key");
      return result;
    }

    if (options.hex) {
      var result = qik.utils.hash(cached, "hex");
      return result;
    }

    return cached;
  };

  ///////////////////////////////////////////////////

  const scopeGlossary = {};

  let inflightScopeGlossaryRequest;

  /**
     *
     * Retrieves the scope glossary of all scopes the user can know about. This helps to convert a scope id into a human readable title.
     * @alias content.scopeGlossary
     * @param  {Object} options Additional options
     * @param  {Boolean} options.hash Whether to return the data as a keyed object with each scopes _id as the key
     allowing for fast selection of specific scopes, by default will return a structured tree
     * @param  {Boolean} options.reload Force the glossary to reload and not be cached.
      If false will retrieve content type data from the in memory cache
     * @example
     *
     * const scopes = await sdk.content.scopeGlossary();
     */

  service.scopeGlossary = async function (options) {
    options = options || {};

    var reload = options.refresh || options.reload || !scopeGlossary.data;

    if (reload) {
      if (!inflightScopeGlossaryRequest) {
        inflightScopeGlossaryRequest = qik.api.get(`/scope/glossary`, {
          cache: false,
        });
        inflightScopeGlossaryRequest.then(resolveRequest, resolveRequest);
        function resolveRequest() {
          inflightScopeGlossaryRequest = null;
        }
      }

      const { data } = await inflightScopeGlossaryRequest;
      scopeGlossary.data = data;
    }

    if (options.hash) {
      var result = qik.utils.hash(scopeGlossary.data, "_id");
      return result;
    }

    return scopeGlossary.data;
  };

  ///////////////////////////////////////////////////

  /**
   *
   * Retrieves all available filter comparators for each data type
   * @alias content.comparators
   * @param  {Object} options Additional options
   * @param  {Boolean} options.reload Ignore any locally cached data
   * @example
   * const {hash, available, types} = await sdk.content.comparators();
   * console.log(available) // {boolean:[{title:'Is equal to', operator:'equal'...}]}
   * console.log(hash) // {equal:[{title:'Is equal to', operator:'equal'...}]}
   */

  const comparators = {};

  service.comparators = async function (options) {
    options = options || {};

    var reload = options.reload || options.refresh || !comparators.data;

    if (reload) {
      const { data } = await qik.api.get(`/system/comparators`);

      /////////////////////////////

      data.available = {};

      Object.entries(data.types).forEach(([key, value]) => {
        data.available[key] = value.map(function (comparatorKey) {
          return data.hash[comparatorKey];
        });
      });

      /////////////////////////////

      comparators.data = data;
    }

    // if (options.hash) {
    //     var result = qik.utils.hash(comparators.data, 'key');
    //     return result;
    // }

    return comparators.data;
  };

  ///////////////////////////////////////////////////

  function getLimits(fieldDefinition) {
    var { minimum, maximum } = fieldDefinition;
    minimum = qik.utils.parseInt(minimum);
    minimum = Math.max(minimum, 0);

    maximum = qik.utils.parseInt(maximum);
    maximum = Math.max(maximum, 0); // cant be less than 0
    if (maximum == 0) {
      //Unlimited maximum
    } else {
      maximum = Math.max(maximum, minimum); // cant be less than the minimum
    }
    return { minimum, maximum };
  }

  service.meetsValidationRequirements = function (
    input,
    fieldType,
    validationCriteria,
  ) {
    if (validationCriteria.minLength) {
      var stringLength = String(input).length;
      if (stringLength < validationCriteria.minLength) {
        return `Must be at least ${validationCriteria.minLength} characters`;
      }
    }

    if (validationCriteria.maxLength) {
      var stringLength = String(input).length;
      if (stringLength > validationCriteria.maxLength) {
        return `Can be no more than ${validationCriteria.maxLength} characters`;
      }
    }

    if (validationCriteria.minValue) {
      if (input !== undefined) {
        var number = Number(input);
        if (number < validationCriteria.minValue) {
          return `Must be at least ${validationCriteria.minValue}`;
        }
      }
    }

    if (validationCriteria.maxValue) {
      if (input !== undefined) {
        var number = Number(input);
        if (number > validationCriteria.maxValue) {
          return `Can be no greater than ${validationCriteria.maxValue}`;
        }
      }
    }
  };

  /**
   * Checks if a certain input validates against a field definition
   * @alias content.validateField
   * @param  {Any} input The input to validate
   * @param  {Object} fieldDefinition The field to validate against
   * @param  {Object} options Additional options when calling the function
   * @example
   * const validationResult = await sdk.content.validateField('Johnny Bobbins', {title:'Name', key:'firstName', type:'string', minimum:1, maximum:1, ...});
   * console.log(validationResult)
   * // Results in { valid:true }
   *
   * const validationResult = await sdk.content.validateField('Johnny Bobbins', {title:'Number', key:'number', type:'integer', minimum:1, maximum:1, ...});
   * console.log(validationResult)
   * // Results in { valid:false, status:400, message:'Invalid number input for field' }
   */

  service.validateField = function (input, fieldDefinition, options) {
    options = options || {};

    var fieldType = fieldDefinition.type || "string";
    var { minimum, maximum } = getLimits(fieldDefinition);

    var isObject = fieldDefinition.type == "group" && fieldDefinition.asObject;
    var singleValue = isObject
      ? minimum === maximum && maximum === 1
      : maximum === 1;
    var multiValue = !singleValue;

    //////////////////

    var isNumeric;
    switch (fieldType) {
      case "integer":
      case "decimal":
      case "number":
      case "float":
        isNumeric = true;
        break;
    }

    //////////////////

    var inputWasProvided = qik.utils.exists(input);

    // A required boolean field means "must be true" — false counts as missing.
    if (fieldDefinition.type === "boolean" && input !== true) {
      inputWasProvided = false;
    }

    //If an answer is required
    if (minimum) {
      //but none was provided
      if (!inputWasProvided) {
        //Throw an error
        return {
          valid: false,
          message: `${fieldDefinition.title} is a required field`,
          status: 400,
        };
      }
    } else {
      //No answer is needed and none was provided
      if (!inputWasProvided) {
        return {
          valid: true,
        };
      }
    }

    //////////////////

    //If we are requiring multiple values
    if (multiValue) {
      //But the input is not an array
      if (!Array.isArray(input)) {
        if (minimum) {
          return {
            valid: false,
            message: `${fieldDefinition.title} requires at least ${minimum} values`,
            status: 400,
          };
        } else {
          console.log("NOT PROVIDED AS ARRAY", fieldDefinition.title, input);
          return {
            valid: false,
            message: `${fieldDefinition.title} must be provided as an array`,
            status: 400,
          };
        }
      }

      ////////////////////////////

      var compacted = input;

      compacted = compacted.filter(function (v) {
        //Check if we care about this value
        var empty = v === undefined || v === null || v === "";
        return !empty;
      });

      // console.log('COMPACTED', input.length, compacted.length);

      ////////////////////////////

      //We need an exact number of answers
      if (minimum == maximum) {
        //But we don't have the number of answers needed
        if (minimum && compacted.length != minimum) {
          return {
            valid: false,
            message: `${fieldDefinition.title} requires exactly ${maximum} values`,
            status: 400,
          };
        }
      }

      //We have too many answers
      if (maximum && compacted.length > maximum) {
        return {
          valid: false,
          message: `${fieldDefinition.title} requires less than ${maximum + 1} values`,
          status: 400,
        };
      }

      //We don't have enough answers
      if (compacted.length < minimum) {
        // console.log(fieldDefinition.title, 'INPUT', input.length, minimum, input, compacted)

        return {
          valid: false,
          message: `${fieldDefinition.title} requires at least ${minimum} values`,
          status: 400,
        };
      }

      ////////////////////////////

      var foundBadEntry;

      //Find any bad values
      var badEntry = compacted.find(function (val) {
        var valueFieldType = fieldType;

        if (fieldDefinition.type === "group") {
          valueFieldType = "object";
        }

        if (
          fieldDefinition.type === "reference" &&
          fieldDefinition.widget === "form"
        ) {
          valueFieldType = "object";
        }

        var isValid = qik.utils.isValidValue(
          val,
          valueFieldType,
          options.strict,
        );

        ////////////////////////////

        if (!isValid) {
          foundBadEntry = true;
          return true;
        }

        ////////////////////////////

        //Is there additional validation requirements
        if (fieldDefinition.validation) {
          var additionalValidationErrors = service.meetsValidationRequirements(
            val,
            fieldType,
            fieldDefinition.validation,
          );
          if (additionalValidationErrors) {
            foundBadEntry = true;
            return true;
          }
        }
      });

      if (foundBadEntry) {
        let badValueMessage = `Invalid input for ${fieldDefinition.title}`;
        return {
          valid: false,
          message: badValueMessage,
          status: 400,
        };
      }
    } else {
      var dataType = fieldType;
      var widgetType = fieldDefinition.widget;
      if (dataType === "group") {
        dataType = "object";
      }

      if (dataType === "reference" && widgetType === "form") {
        dataType = "object";
      }

      //////////////////

      var cleanedValue = service.getCleanedValue(input, dataType, options);

      //////////////////

      var isValidValue = qik.utils.isValidValue(
        cleanedValue,
        dataType,
        options.strict,
      );

      //////////////////

      //Invalid input
      if (!isValidValue) {
        return {
          valid: false,
          message: `Single value '${input}' is not a valid ${dataType} for ${fieldDefinition.title}`,
          criteria: {
            isValidValue,
            cleanedValue,
            fieldType,
            options,
          },
          status: 400,
        };
      }

      //Is there additional validation requirements
      let hasAdditionalValidation = false;

      const validation = {};
      if (String(fieldDefinition.minValue)) {
        validation.minValue = parseInt(fieldDefinition.minValue);
        hasAdditionalValidation = true;
      }
      if (String(fieldDefinition.maxValue)) {
        validation.maxValue = parseInt(fieldDefinition.maxValue);
        hasAdditionalValidation = true;
      }
      if (String(fieldDefinition.minLength)) {
        validation.minLength = parseInt(fieldDefinition.minLength);
        hasAdditionalValidation = true;
      }
      if (String(fieldDefinition.maxLength)) {
        validation.maxLength = parseInt(fieldDefinition.maxLength);
        hasAdditionalValidation = true;
      }

      if (hasAdditionalValidation) {
        const validationCriteria = Object.assign(
          {},
          validation,
          fieldDefinition.validation || {},
        );
        var additionalValidationError = service.meetsValidationRequirements(
          input,
          fieldType,
          validationCriteria,
        );
        if (additionalValidationError) {
          return {
            valid: false,
            message: additionalValidationError,
            status: 400,
          };
        }
      }
    }

    //////////////////

    return {
      valid: true,
    };
  };

  service.getCleanedValue = function (input, dataType, options) {
    switch (dataType) {
      case "number":
      case "float":
      case "decimal":
        if (!qik.utils.exists(input)) {
          return undefined;
        } else {
          return Number(input);
        }
        break;
      case "integer":
        if (!qik.utils.exists(input)) {
          return undefined;
        } else {
          return parseInt(input);
        }
        break;
      case "boolean":
        if (!qik.utils.exists(input)) {
          return undefined;
        }
        return qik.utils.parseBoolean(input);
        break;
      case "email":
        return options.strict ? input : String(input).toLowerCase();
        break;
      case "reference":
        return options.strict ? input : qik.utils.id(input);
        break;
      default:
        return options.strict
          ? input
          : qik.utils.cleanValue(input, dataType, options);
        break;
    }

    return input;
  };

  ///////////////////////////////////////////////////

  /**
   *
   * Retrieves a list of records matching the provided criteria
   * @alias content.list
   * @param  {String} type The type or definition of records we want to retrieve
   * @param  {Object} options The options for our query
   * @param  {String} options.search Freeform text keywords
   * @param  {Object} options.sort How to sort the results
   * @param  {String} options.sort.key Which key to sort on
   * @param  {String} options.sort.direction Which direction to sort on
   * @param  {Object} options.sort.type What type of data is being sorted
   * @param  {Object} options.page Page configuration
   * @param  {Number} options.page.size Page size
   * @param  {Number} options.page.index Page index
   * @param  {Object} options.filter How to filter the results
   * @example
   *
   *
   * sdk.content.list('profile', {
   *     search:'Jim',
   *     page:{
   *         size:50,
   *         index:2,
   *     },
   *     sort:{
   *         key:'age',
   *         direction:'asc',
   *         type:'integer',
   *     },
   *     filter:{
   *         operator:'and',
   *         filters:[{
   *             key:'age',
   *             comparator:'>',
   *             value:5,
   *         }],
   *     },
   * })
   */

  service.list = async function (type, options, advanced) {
    if (!advanced) {
      advanced = {};
    }

    const remoteURL = advanced.remoteURL || `/content/${type}/list`;

    if (advanced.cancellable) {
      if (!advanced.config) {
        advanced.config = {};
      }

      //Create a cancel token
      const CancelToken = qik.api.CancelToken;
      const source = CancelToken.source();
      advanced.config.cancelToken = source.token;

      const promise = qik.api.post(remoteURL, options, advanced.config);
      return {
        promise,
        cancel(message) {
          source.cancel(message || "Operation canceled by the user.");
        },
      };
    } else {
      const { data } = await qik.api.post(remoteURL, options, advanced.config);
      return data;
    }
  };

  ///////////////////////////////////////////////////

  /**
   *
   * Create an item
   * @alias content.create
   * @param  {String} type The type or definition of the record we want to create
   * @param  {Object} input The data for our new record
   * @example
   *
   *
   * const result = await sdk.content.create('profile', {
   *     firstName:'Mickey',
   *     lastName:'Mouse',
   *     gender:'male',
   *     meta:{
   *       scopes:['61eca4746971e75c1fc670cf'],
   *     }
   * })
   */

  service.create = async function (type, input) {
    const dataModel = { ...input };

    // Sanitize down to just ids before we send
    if (dataModel.meta?.scopes) {
      dataModel.meta.scopes = qik.utils.ids(dataModel.meta.scopes);
    }

    const { data } = await qik.api.post(`/content/${type}/create`, dataModel);
    return data;
  };

  /**
   *
   * Update an item, Only fields the user has permission to view will be returned
   * @alias content.update
   * @param  {String} id The id of the record we want to update
   * @param  {Object} input The data to update
   * @example
   *
   * const result = await sdk.content.update('61eca4746971e75c1fc670cd', {
   *     firstName:'Minnie',
   *     lastName:'Mouse',
   *     gender:'female',
   *     meta:{
   *       scopes:['61eca4746971e75c1fc670cd'],
   *     }
   * })
   */
  service.update = async function (id, input) {
    id = qik.utils.id(id);

    const dataModel = { ...input };

    // Sanitize down to just ids before we send
    if (dataModel.meta?.scopes) {
      dataModel.meta.scopes = qik.utils.ids(dataModel.meta.scopes);
    }

    const { data } = await qik.api.put(`/content/${id}`, dataModel);
    return data;
  };

  /**
   *
   * Partially update and patch an item, Only fields the user has permission to edit will be updated
   * @alias content.patch
   * @param  {String} id The id of the record we want to update
   * @param  {Object} input The data to update, this will be merged with existing data
   * @example
   *
   * const result = await sdk.content.patch('61eca4746971e75c1fc670cd', {
   *     firstName:'Mickey',
   *     gender:'male',
   * })
   */
  service.patch = async function (id, input) {
    id = qik.utils.id(id);

    const dataModel = { ...input };

    // Sanitize down to just ids before we send
    if (dataModel.meta?.scopes) {
      dataModel.meta.scopes = qik.utils.ids(dataModel.meta.scopes);
    }

    const { data } = await qik.api.patch(`/content/${id}`, dataModel);
    return data;
  };

  /**
   *
   * Get an item from the database, Only fields the user has permission to view will be returned
   * @alias content.get
   * @param  {String} id The id of the record we want to update
   * @example
   *
   * const result = await sdk.content.get('61eca4746971e75c1fc670cd')
   */
  service.get = async function (id, params) {
    id = qik.utils.id(id);
    params = params || {};

    const { data } = await qik.api.get(`/content/${id}`, params);
    return data;
  };

  service.getFromID = async function (id) {
    return service.get(id);
  };

  /**
   *
   * Delete an item from the database
   * @alias content.delete
   * @param  {String} id The id of the record we want to delete
   * @example
   * const result = await sdk.content.delete('61eca4746971e75c1fc670cd')
   */
  service.delete = async function (id, input) {
    id = qik.utils.id(id);
    const { data } = await qik.api.delete(`/content/${id}`, input);
    return data;
  };

  /**
   *
   * Restore a deleted item from the database
   * @alias content.restore
   * @param  {String} id The id of the record we want to restore
   * @example
   * const result = await sdk.content.restore('61eca4746971e75c1fc670cd')
   */
  service.restore = async function (id, input) {
    id = qik.utils.id(id);
    const { data } = await qik.api.get(`/content/${id}/restore`, input);
    return data;
  };

  /**
   *
   * Retrieve an item from the database by providing it's 'slug'
   * @alias content.getFromSlug
   * @param  {String} slug The slug id of the record we want to retrieve
   * it must be provided as either `(type):(slug)`` or `(definition):(slug)`
   * (if unsure use the `meta.abs` absolute slug property of the item you are wanting to retrieve).
   * @example
   * const result = await sdk.content.getFromSlug('article:how-to-get-started')
   * const result = await sdk.content.getFromSlug('car:toyota-landcruiser')
   * const result = await sdk.content.getFromSlug('article:toyota-landcruiser')
   */
  service.getFromSlug = async function (slug) {
    const { data } = await qik.api.get(`/content/slug/${slug}`);
    return data;
  };

  // service.getFromSlug = async function(type, slug) {
  //     const { data } = await qik.api.get(`/content/${type}/slug/${slug}`);
  //     return data;
  // }

  // service.getFromExternalID = async function(type, externalID) {
  //     const { data } = await qik.api.get(`/content/${type}/external/${externalID}`);
  //     return data;
  // }

  return service;
}