compile.js

/**
 * @fileoverview MicroQL Query Compiler
 *
 * Compiles query configurations into queryTree
 * Handles service validation and dependency extraction.
 */

import _ from 'lodash'
import lodashDeep from 'lodash-deep'
_.mixin(lodashDeep)

import {DEP_REGEX, SERVICE_REGEX, RESERVE_ARGS} from './common.js'
import applyWrappers from './wrappers.js'
import {parseSchema} from './validation.js'
import util from './services/util.js'
import RateLimitedQueue from './ratelimit.js'
import Cache from './cache.js'

// Detects if a descriptor is a chain (nested arrays)
const isChain = (descriptor) => {
  return Array.isArray(descriptor) &&
    descriptor.length > 0 &&
    _.every(descriptor, d => Array.isArray(d))
}

// Detects if a descriptor uses method syntax: ['target', 'service:action', args]
const hasMethodSyntax = (descriptor) => {
  return Array.isArray(descriptor) &&
         descriptor.length >= 2 &&
         typeof descriptor[1] === 'string' &&
         SERVICE_REGEX.test(descriptor[1])
}

// Transforms method syntax ['target', 'service:action', args] to standard service call ['service:action', {on: target, ...args}]
const parseServiceDescriptor = (descriptor) => {
  // check for method descriptor
  if (hasMethodSyntax(descriptor)) {
    const [arg0, serviceMethod, args = {}] = descriptor
    const [__, serviceName, action] = serviceMethod.match(SERVICE_REGEX)
    return [serviceName, action, args, arg0]

  } else {
    // assume normal service descriptor
    const [serviceAction, args = {}] = descriptor
    const match = serviceAction?.match(SERVICE_REGEX)
    if (!match) {
      throw new Error(`Invalid service descriptor. Expected ['service:action', {...}] format. Got: ${JSON.stringify(descriptor)}`)
    }
    const [, serviceName, action] = match
    return [serviceName, action, args]
  }
}

// Extracts dependencies from query arguments
const getDeps = (args) => {
  const deps = new Set()
  _.deepMapValues(args, (value) => {
    let m = (typeof value === 'string') && value.match(DEP_REGEX)
    if (m) deps.add(m[1])
  })
  return deps
}

function parseSchemaWithErrorContext(designation, order, schema) {
  try {
    return parseSchema(schema)
  } catch (error) {
    error.message = `${designation} ${order} schema parse error:\n${error.message}`
    throw error
  }
}

// weave the schema compilation with proper context for error reporting
const compileValidators = (args, validators) => {
  const order = {
    precheck: {query: args.precheck, service: validators.precheck},
    postcheck: {service: validators.postcheck, query: args.postcheck}
  }
  let hasValidators = false
  for (const o in order) {
    for (const d in order[o])
      if (order[o][d]) {
        hasValidators = true
        order[o][d] = parseSchemaWithErrorContext(d, o, order[o][d])
      }
  }
  return hasValidators ? order : undefined
}

// settings are merged from query level settings and service level settings
// they are placed in their own `settings` key on the compiled service definition
const compileSettings = (queryName, serviceName, args, argtypes, config) => {
  const reserveArgs = _.pick(args, RESERVE_ARGS)
  // get args with their argtypes set to 'settings'
  const settingsArgs = _.pickBy(args, (a, k) => argtypes[k]?.type === 'settings')

  // exclude some global settings from being merged with the service
  const globalSettings = config.settings ?
    _.omit(config.settings, ['onError', 'ignoreErrors', 'cache']) : {}
  const settings = _.defaults({}, reserveArgs, ...Object.values(settingsArgs), globalSettings)

  // compile onError if we have it
  if (settings.onError) {
    settings.onError = compileServiceOrChain(queryName, settings.onError, config)
  }

  // rate limit is defined globally for the service
  settings.rateLimit = config.settings?.rateLimit?.[serviceName]

  return settings
}

// any time we expect a service, it could instead be a chain
const compileServiceOrChain = (queryName, value, config) => {
  const makeFn = (descriptor) => compileServiceFunction(queryName, descriptor, config).service

  // is it a chain?
  if (isChain(value)) {
    return value.map(makeFn)

    // or a single service call?
  } else {
    return makeFn(value)
  }
}

// Compile arguments based on argtypes metadata
const compileArgs = (queryName, serviceName, args, argtypes, config, settings) => {
  const compiled = {}

  for (const [key, value] of Object.entries(args)) {

    // compile object to service template
    if (argtypes[key]?.type === 'service' && typeof value === 'object' && !Array.isArray(value)) {
      const fn = compileServiceFunction(queryName, ['util:template', value], config)
      compiled[key] = fn.service

    // compile service descriptor
    } else if (argtypes[key]?.type === 'service' && Array.isArray(value)) {
      compiled[key] = compileServiceOrChain(queryName, value, config)

    // reject raw JavaScript functions
    } else if (argtypes[key]?.type === 'service' && typeof value === 'function') {
      throw new Error(`Raw JavaScript functions are not supported in MicroQL. Use service descriptors instead of raw functions for argument '${key}' in ${serviceName}:${queryName}. Example: ['serviceName:methodName', {arg: '@'}]`)

    } else if (RESERVE_ARGS.includes(key)) {
      // exclude reserve args

    } else {
      compiled[key] = value
    }
  }

  for (const [key, type] of Object.entries(argtypes)) {
    // inject settings if requested
    if (type?.type === 'settings') {
      compiled[key] = _.defaults(args[key], settings)
    }
  }

  return compiled
}

// check to see if the service has an argOrder: 0 defined
// and merge arg0 if we have it
function mergeArgs(args, arg0, argtypes = {}, serviceName, action) {
  if (!arg0) {
    return
  }
  const [argOrder0] = Object.entries(argtypes).find(([, typeinfo]) => typeinfo.argOrder === 0) || []
  if (!argOrder0)
    throw new Error(`Method syntax was used for ${serviceName}:${action} but no {argOrder: 0} was defined.`)
  args[argOrder0] = arg0
}

// Compiles a service descriptor like ['@', 'util:print', {color: 'green'}]
// into [a compiled function, recursive dependencies]
function compileServiceFunction(queryName, descriptor, config) {
  const [serviceName, action, args, arg0] = parseServiceDescriptor(descriptor)

  // Validate service exists and has the required method
  const service = config.services[serviceName]
  if (!service) {
    throw new Error(`Service '${serviceName}' not found`)
  }

  const serviceCall = service[action]
  if (typeof service === 'object') {
    if (!serviceCall || typeof serviceCall !== 'function') {
      throw new Error(`Method '${action}' not found on service '${serviceName}'`)
    }
  } else {
    throw new Error(`Service '${serviceName}' must be an object with methods in the form: async (args) => result`)
  }

  try {
    const argtypes = serviceCall._argtypes || {}
    mergeArgs(args, arg0, argtypes, serviceName, action)
    const settings = compileSettings(queryName, serviceName, args, argtypes, config)
    const rateLimit = config.rateLimiters?.[serviceName]
    const compiledArgs = compileArgs(queryName, serviceName, args, argtypes, config, settings)
    const validators = compileValidators(args, serviceCall._validators || {}, queryName, serviceName, action)

    // Compile function arguments based on _argtypes
    const serviceDef = {
      type: 'service',
      queryName,
      serviceName,
      action,
      validators,
      settings,
      rateLimit,
      args: compiledArgs,
      dependencies: getDeps(args),
      noTimeout: serviceCall._noTimeout || false
    }

    // prepare the service with arg resolution, debugging, error handling, timeout, retry
    serviceDef.service = applyWrappers(serviceDef, config)

    return serviceDef

  } catch (error) {
    error.message = `[${queryName} - ${serviceName}:${action}] ${error.message}`
    throw error
  }
}

function compileDescriptor(queryName, descriptor, config) {
  // Handle chains - arrays of service calls
  if (isChain(descriptor)) {
    let allDeps = new Set()

    // for each step in chain, collect the service definition and the dependencies
    const chainSteps = descriptor.map((d, i) => {
      const def = compileServiceFunction(`${queryName}[${i}]`, d, config)
      allDeps = allDeps.union(def.dependencies)
      def.stepIndex = i
      delete def.dependencies
      return def
    })

    return {
      type: 'chain',
      queryName,
      steps: chainSteps,
      dependencies: allDeps
    }
  } else {
    // Handle single service call
    return compileServiceFunction(queryName, descriptor, config)
  }
}


/**
 * Compile a query configuration into a queryTree
 * @param {Object} config - Query configuration
 * @param {Object} config.services - Service objects
 * @param {Object} config.queries - Query definitions
 * @param {Object} config.given - given data
 * @param {boolean} config.debug - Debug logging flag
 * @returns {Object} Compiled queryTree
 */
export function compile(config) {
  _.defaults(config, {services: {}, queries: {}, debug: false, settings: {}})
  const {services, queries, given, debug, settings} = config
  _.defaults(config.services, {util})

  // set up a cache for query results using the global settings provided
  config.cache = new Cache(config.settings.cache)

  // Create rate limiter cache to share rate limiters across queries
  config.rateLimiters = {}
  if (settings.rateLimit) {
    for (const [serviceName, interval] of Object.entries(settings.rateLimit)) {
      config.rateLimiters[serviceName] = new RateLimitedQueue(interval)
    }
  }

  // Build tree for each query (use config as-is for service compilation)
  const queryTree = {}

  for (const [queryName, descriptor] of Object.entries(queries)) {
    queryTree[queryName] = compileDescriptor(queryName, descriptor, config)
  }

  // Compile global settings separately
  const globalSettings = {...settings}
  if (settings.onError) {
    globalSettings.onError = compileServiceOrChain('global', settings.onError, config)
  }

  return {
    queries: queryTree,
    given,
    services,
    debug,
    settings: globalSettings
  }
}

export default compile