hinoki.coffee

((root, factory) ->
  # amd
  if ('function' is typeof define) and define.amd?
    define(['bluebird', 'lodash', 'helfer'], factory)
  # nodejs
  else if exports?
    module.exports = factory(
      require('bluebird')
      require('lodash')
      require('helfer')
      require('fs')
      require('path')
    )
  # other
  else
    unless root.Promise?
      throw new Error 'missing global variable `Promise`'
    unless root._?
      throw new Error 'missing global variable `_`'
    unless root.helfer?
      throw new Error 'missing global variable `helfer`'
    root.hinoki = factory(root.Promise, root._, root.helfer)
)(this, (Promise, _, helfer, fsModule, pathModule) ->

################################################################################
# get

  # polymorphic
  hinoki = (arg1, arg2, arg3) ->
    source = hinoki.source arg1

    if arg3?
      lifetimes = helfer.coerceToArray arg2
      keyOrKeysOrFunction = arg3
    else
      lifetimes = [{}]
      keyOrKeysOrFunction = arg2

    cacheTarget = 0

    if 'function' is typeof keyOrKeysOrFunction
      keys = hinoki.getKeysToInject(keyOrKeysOrFunction)
      paths = _.map keys, helfer.coerceToArray
      return hinoki.getValuesAndCacheTarget(
        source,
        lifetimes,
        paths,
        cacheTarget
      ).promise.spread(keyOrKeysOrFunction)

    if Array.isArray keyOrKeysOrFunction
      keys = helfer.coerceToArray(keyOrKeysOrFunction)
      paths = _.map keys, helfer.coerceToArray
      return hinoki.getValuesAndCacheTarget(
        source,
        lifetimes,
        paths,
        cacheTarget
      ).promise

    path = helfer.coerceToArray(keyOrKeysOrFunction)
    return hinoki.getValueAndCacheTarget(
      source,
      lifetimes,
      path,
      cacheTarget
    ).promise

  hinoki.isNodejs = fsModule?.statSync? and fsModule?.readdirSync?

  # monomorphic
  hinoki.PromiseAndCacheTarget = (promise, cacheTarget) ->
    this.promise = promise
    this.cacheTarget = cacheTarget
    return this

  # monomorphic
  hinoki.getValuesAndCacheTarget = (source, lifetimes, paths, cacheTarget) ->
    # result.cacheTarget is determined synchronously
    nextCacheTarget = cacheTarget
    # result.promise is fulfilled asynchronously
    promise = Promise.all(_.map(paths, (path) ->
      result = hinoki.getValueAndCacheTarget(
        source
        lifetimes
        path
        cacheTarget
      )
      nextCacheTarget = Math.max(nextCacheTarget, result.cacheTarget)
      return result.promise
    ))
    return new hinoki.PromiseAndCacheTarget promise, nextCacheTarget

  # monomorphic
  hinoki.getValueAndCacheTarget = (source, lifetimes, path, cacheTarget) ->
    key = path[0]
    # look if there already is a value for that key in one of the lifetimes
    lifetimeIndex = helfer.findIndexWhereProperty lifetimes, key
    unless lifetimeIndex is -1
      valueOrPromise = lifetimes[lifetimeIndex][key]
      promise =
        if helfer.isThenable valueOrPromise
          # if the value is already being constructed
          # wait for that instead of starting a second construction.
          hinoki.debug? {
            event: 'lifetimeHasPromise'
            path: path
            promise: valueOrPromise
            lifetime: lifetimes[lifetimeIndex]
            lifetimeIndex: lifetimeIndex
          }
          valueOrPromise
        else
          hinoki.debug? {
            event: 'lifetimeHasValue'
            path: path
            value: valueOrPromise
            lifetime: lifetimes[lifetimeIndex]
            lifetimeIndex: lifetimeIndex
          }
          Promise.resolve valueOrPromise
      return new hinoki.PromiseAndCacheTarget promise, lifetimeIndex

    # we have no value
    # look if there is a factory for that key in the source
    factory = source(key)
    unless factory?
      return new hinoki.PromiseAndCacheTarget(
        Promise.reject(new hinoki.NotFoundError(path))
        cacheTarget
      )

    unless hinoki.isFactory factory
      return new hinoki.PromiseAndCacheTarget(
        Promise.reject new hinoki.BadFactoryError path, factory
        cacheTarget
      )

    hinoki.debug? {
      event: 'sourceReturnedFactory'
      path: path
      factory: factory
    }

    # we've got a factory.
    # lets make a value

    # first lets resolve the dependencies of the factory

    dependencyKeys = hinoki.baseGetKeysToInject factory, true

    dependencyKeysIndex = -1
    dependencyKeysLength = dependencyKeys.length
    dependencyPaths = []
    while ++dependencyKeysIndex < dependencyKeysLength
      dependencyKey = dependencyKeys[dependencyKeysIndex]
      newPath = path.slice()
      newPath.unshift dependencyKey
      # is this key already in the path?
      # if so then it would introduce a circular dependency.
      if -1 isnt path.indexOf dependencyKey
        return new hinoki.PromiseAndCacheTarget(
          Promise.reject(new hinoki.CircularDependencyError(newPath))
          cacheTarget
        )
      dependencyPaths.push newPath

    # no cycle - yeah!

    # this code is reached synchronously from the start of the function call
    # without interleaving.

    if dependencyPaths.length isnt 0
      result = hinoki.getValuesAndCacheTarget(
        source,
        lifetimes,
        dependencyPaths,
        cacheTarget
      )
      dependenciesPromise = result.promise
      nextCacheTarget = result.cacheTarget
    else
      dependenciesPromise = Promise.resolve([])
      nextCacheTarget = cacheTarget

    factoryCallResultPromise = dependenciesPromise.then (dependencyValues) ->
      # the dependencies are ready!
      # we can finally call the factory!
      return hinoki.callFactory(path, factory, dependencyValues)

    # cache the promise:
    # this code is reached synchronously from the start of the function call
    # without interleaving.
    # its important that the factoryCallResultPromise is added
    # to lifetimes[maxCacheTarget] synchronously
    # because as soon as control is given back to the scheduler
    # another process might request the value as well.
    # this way that process just reuses the factoryCallResultPromise
    # instead of building it all over again.
    # invariant:
    # if we reach this line we are guaranteed that:
    # lifetimes[nextCacheTarget][key] is undefined
    # because we checked that synchronously

    unless factory.__nocache
      lifetimes[nextCacheTarget][key] = factoryCallResultPromise

    returnPromise = factoryCallResultPromise
      .then (value) ->
        # cache
        unless factory.__nocache
          lifetimes[nextCacheTarget][key] = value
        return value
      .catch (error) ->
        # prevent errored promises from being reused
        # and allow further requests for the errored keys to succeed.
        unless factory.__nocache
          delete lifetimes[nextCacheTarget][key]
        return Promise.reject error

    return new hinoki.PromiseAndCacheTarget(returnPromise, nextCacheTarget)

  # try catch prevents functions from being optimized.
  # wrapping it into a function keeps the unoptimized part small.
  hinoki.tryCatch = (fun, args) ->
    try
      return fun.apply null, args
    catch error
      if helfer.isError error
        return error
      else
        return new Error error.toString()

  # returns a promise
  hinoki.callFactoryFunction = (path, factoryFunction, args) ->
    result = hinoki.tryCatch(factoryFunction, args)
    if helfer.isUndefined result
      # note that a null value is allowed!
      return Promise.reject new hinoki.FactoryReturnedUndefinedError path, factoryFunction
    if helfer.isError(result)
      return Promise.reject new hinoki.ErrorInFactory path, factoryFunction, result
    if helfer.isThenable result
      hinoki.debug? {
        event: 'factoryReturnedPromise'
        path: path
        promise: result
        factory: factoryFunction
      }
      return result
        .then (value) ->
          hinoki.debug? {
            event: 'promiseResolved'
            path: path
            value: value
            factory: factoryFunction
          }
          return value
        .catch (rejection) ->
          Promise.reject new hinoki.PromiseRejectedError path, factoryFunction, rejection
    hinoki.debug? {
      event: 'factoryReturnedValue'
      path: path
      value: result
      factory: factoryFunction
    }
    return Promise.resolve result

  hinoki.callFactoryObjectArray = (path, factoryObject, dependenciesObject) ->
    iterator = (f, key) ->
      newPath = path.slice()
      newPath[0] += '[' + key + ']'

      unless hinoki.isFactory f
        return Promise.reject new hinoki.BadFactoryError newPath, f

      if 'function' is typeof f
        dependencyKeys = hinoki.getKeysToInject f
        dependencies = _.map dependencyKeys, (dependencyKey) ->
          dependenciesObject[dependencyKey]
        return hinoki.callFactoryFunction(newPath, f, dependencies)
      else if 'object' is typeof f
        # supports nesting
        return hinoki.callFactoryObjectArray(newPath, f, dependenciesObject)

    if Array.isArray factoryObject
      Promise.all(factoryObject).map(iterator)
    else if 'object' is typeof factoryObject
      keys = Object.keys(factoryObject)
      length = keys.length
      i = -1
      result = {}
      while ++i < length
        key = keys[i]
        # ignore special properties:
        # special properties are those starting with `__`
        # like: `__inject`, `__file`, ...
        unless 0 is key.indexOf '__'
          result[key] = iterator(factoryObject[key], key)
      return Promise.props result

  hinoki.callFactory = (path, factory, dependencyValues) ->
    if 'function' is typeof factory
      return hinoki.callFactoryFunction path, factory, dependencyValues
    else
      dependencyKeys = hinoki.getKeysToInject factory
      dependenciesObject = _.zipObject dependencyKeys, dependencyValues
      return hinoki.callFactoryObjectArray path, factory, dependenciesObject

################################################################################
# errors

  # constructors for errors which are catchable with bluebirds `catch`

  # the base error for all other hinoki errors
  # not to be instantiated directly
  hinoki.BaseError = ->
  helfer.inherits hinoki.BaseError, Error

  hinoki.NotFoundError = (path) ->
    this.name = 'NotFoundError'
    this.message = "neither value nor factory found for `#{path[0]}` in path `#{hinoki.pathToString path}`"
    if Error.captureStackTrace?
      # second argument excludes the constructor from inclusion in the stack trace
      Error.captureStackTrace(this, this.constructor)
    this.path = path
    return
  helfer.inherits hinoki.NotFoundError, hinoki.BaseError

  hinoki.CircularDependencyError = (path) ->
    this.name = 'CircularDependencyError'
    this.message = "circular dependency `#{hinoki.pathToString path}`"
    if Error.captureStackTrace?
      Error.captureStackTrace(this, this.constructor)
    this.path = path
    return
  helfer.inherits hinoki.CircularDependencyError, hinoki.BaseError

  hinoki.ErrorInFactory = (path, factory, error) ->
    this.name = 'ErrorInFactory'
    this.message = "error in factory for `#{path[0]}`. original error `#{error.toString()}`"
    if Error.captureStackTrace?
      Error.captureStackTrace(this, this.constructor)
    this.path = path
    this.factory = factory
    this.error = error
    return
  helfer.inherits hinoki.ErrorInFactory, hinoki.BaseError

  hinoki.FactoryReturnedUndefinedError = (path, factory) ->
    this.name = 'FactoryReturnedUndefinedError'
    this.message = "factory for `#{path[0]}` returned undefined"
    if Error.captureStackTrace?
      Error.captureStackTrace(this, this.constructor)
    this.path = path
    this.factory = factory
    return
  helfer.inherits hinoki.FactoryReturnedUndefinedError, hinoki.BaseError

  hinoki.PromiseRejectedError = (path, factory, error) ->
    this.name = 'PromiseRejectedError'
    this.message = "promise returned from factory for `#{path[0]}` was rejected. original error `#{error.toString()}`"
    if Error.captureStackTrace?
      Error.captureStackTrace(this, this.constructor)
    this.path = path
    this.factory = factory
    this.error = error
    return
  helfer.inherits hinoki.PromiseRejectedError, hinoki.BaseError

  hinoki.BadFactoryError = (path, factory) ->
    this.name = 'BadFactoryError'
    this.message = "factory for `#{path[0]}` has to be a function, object of factories or array of factories but is `#{typeof factory}`"
    if Error.captureStackTrace?
      Error.captureStackTrace(this, this.constructor)
    this.path = path
    this.factory = factory
    return
  helfer.inherits hinoki.BadFactoryError, hinoki.BaseError

################################################################################
# helper

  hinoki.pathToString = (path) ->
    path.join ' <- '

  hinoki.getKeysToInject = (factory) ->
    hinoki.baseGetKeysToInject factory, false

  hinoki.baseGetKeysToInject = (factory, cache) ->
    if factory.__inject?
      return factory.__inject

    type = typeof factory
    if ('object' is type) or ('function' is type)
      if ('function' is type)
        keys = helfer.parseFunctionArguments factory
      else
        keysSet = {}
        _.forEach factory, (subFactory) ->
          subKeys = hinoki.baseGetKeysToInject(subFactory, cache)
          _.forEach subKeys, (subKey) ->
            keysSet[subKey] = true
        keys = Object.keys(keysSet)
      if cache
        factory.__inject = keys
      return keys

    return []

  hinoki.isFactory = (value) ->
    type = typeof value
    (type is 'function') or Array.isArray(value) or (type is 'object')

################################################################################
# functions for working with sources

  # returns an object containing all the exported properties
  # of all `*.js` and `*.coffee` files in `filepath`.
  # if `filepath` is a directory recurse into every file and subdirectory.

  if hinoki.isNodejs
    # TODO better name
    hinoki.requireSource = (filepath) ->
      unless 'string' is typeof filepath
        throw new Error 'argument must be a string'
      hinoki.baseRequireSource filepath, {}

    # TODO call this something like fromExports
    hinoki.baseRequireSource = (filepath, object) ->
      stat = fsModule.statSync(filepath)
      if stat.isFile()
        extension = pathModule.extname(filepath)

        if extension isnt '.js' and extension isnt '.coffee'
          return

        # coffeescript is only required on demand when the project contains .coffee files
        # in order to support pure javascript projects
        if extension is '.coffee'
          require('coffee-script/register')

        exports = require(filepath)

        Object.keys(exports).map (key) ->
          unless hinoki.isFactory exports[key]
            throw new Error('export is not a factory: ' + key + ' in :' + filepath)
          if object[key]?
            throw new Error('duplicate export: ' + key + ' in: ' + filepath + '. first was in: ' + object[key].__file)
          object[key] = exports[key]
          # add filename as metadata
          object[key].__file = filepath

      else if stat.isDirectory()
        filenames = fsModule.readdirSync(filepath)
        filenames.forEach (filename) ->
          hinoki.baseRequireSource pathModule.join(filepath, filename), object

      return object

  hinoki.source = (arg) ->
    if 'function' is typeof arg
      return arg

    if Array.isArray arg
      coercedSources = _.map arg, hinoki.source
      source = (key) ->
        # try all sources in order
        index = -1
        length = arg.length
        while ++index < length
          result = coercedSources[index](key)
          if result?
            return result
        return null
      source.keys = ->
        keys = []
        _.each coercedSources, (source) ->
          if source.keys?
            keys = keys.concat(source.keys())
        return keys
      return source

    if 'string' is typeof arg
      unless hinoki.isNodejs
        throw new Error 'string sources only work on Node.js because they need the filesystem module to be present'
      return hinoki.source hinoki.requireSource arg

    if 'object' is typeof arg
      source = (key) ->
        arg[key]
      source.keys = ->
        Object.keys(arg)
      return source

    throw new Error 'argument must be a function, string, object or array of these'

  hinoki.decorateSourceToAlsoLookupWithPrefix = (innerSource, prefix) ->
    source = (key) ->
      result = innerSource(key)
      if result?
        return result

      if 0 is key.indexOf(prefix)
        return null

      # factory that resolves to the same value
      wrapperFactory = (wrapped) -> wrapped
      wrapperFactory.__inject = [prefix + key]
      return wrapperFactory
    if innerSource.keys?
      source.keys = innerSource.keys
    return source

################################################################################
# return the hinoki object from the factory

  return hinoki
)