@firebolt-js/core-client 1.0.0-next.5

package/dist/lib/Events/index.mjs

@@ -0,0 +1,345 @@
+/*
+ * Copyright 2021 Comcast Cable Communications Management, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import Gateway from '../Gateway/index.mjs'
+
+let listenerId = 0
+
+// holds two maps of ${module}.${event} => listenerId, e.g. callback method id
+// note that one callback can listen to multiple events, e.g. 'discovery.*'
+// internal is only available via a private export that we use to ensure our modules know about
+// events before the apps using the SDK (otherwise state errors can happen)
+const listeners = {
+  internal: {},
+  external: {},
+
+  // Several convenience functions below for checking both internal & external lists w/ one operation
+
+  // gets a merge list of ids for a single event key
+  get: (key) => {
+    return Object.assign(
+      Object.assign({}, listeners.internal[key]),
+      listeners.external[key],
+    )
+  },
+  // adds a callback/id to a key on the external list only
+  set: (key, id, value) => {
+    listeners.external[key] = listeners.external[key] || {}
+    listeners.external[key][id] = value
+  },
+  // adds a callback/id to a key on the internal list only
+  setInternal: (key, id, value) => {
+    listeners.internal[key] = listeners.internal[key] || {}
+    listeners.internal[key][id] = value
+  },
+  // finds the key for an id in either list (it can only be in one)
+  find: (id) => {
+    let key
+    ;[listeners.internal, listeners.external].find((group) => {
+      key = Object.keys(group).find((key) => group[key][id])
+      if (key) return true
+    })
+    return key
+  },
+  // removes an id from either list
+  remove: (id) => {
+    ;[listeners.internal, listeners.external].forEach((group) => {
+      Object.keys(group).forEach((key) => {
+        if (group[key] && group[key][id]) {
+          delete group[key][id]
+          if (Object.values(group[key]).length === 0) {
+            delete group[key]
+          }
+        }
+      })
+    })
+  },
+  // removes a key from both lists if _internal is true, otherwise only the external list
+  removeKey: (key, _internal = false) => {
+    _internal && listeners.internal[key] && delete listeners.internal[key]
+    listeners.external[key] && delete listeners.external[key]
+  },
+  // gives a list of all keys
+  keys: () => {
+    return Array.from(
+      new Set(
+        Object.keys(listeners.internal).concat(Object.keys(listeners.external)),
+      ),
+    )
+  },
+  // counts how many listeners are in a key across both lists
+  count: (key) => {
+    return Object.values(listeners.get(key)).length
+  },
+}
+
+// holds a map of ${module}.${event} => Transport.send calls (only called once per event)
+// note that the keys here MUST NOT contain wild cards
+const oncers = []
+const validEvents = {}
+const validContext = {}
+
+export const registerEvents = (module, events) => {
+  validEvents[module] = events.concat()
+}
+
+export const registerEventContext = (module, event, context) => {
+  validContext[module] = validContext[module] || {}
+  validContext[module][event] = context.concat()
+}
+
+const callCallbacks = (key, params) => {
+  const args = Object.values(params)
+  const callbacks = Object.entries(listeners.internal[key] || {}).concat(
+    Object.entries(listeners.external[key] || {}),
+  )
+  callbacks.forEach(([listenerId, callback]) => {
+    if (oncers.indexOf(parseInt(listenerId)) >= 0) {
+      oncers.splice(oncers.indexOf(parseInt(listenerId)), 1)
+      delete listeners.external[key][listenerId]
+    }
+    if (args.length <= callback.length) {
+      callback.apply(null, args)
+    } else if (
+      args.length > 0 &&
+      callback.length > 0 &&
+      callback.length < args.length
+    ) {
+      // read the params the callback takes and if they are less then the size of args remove the extra params from the front
+      const callbackArgs = args.slice(-callback.length, args.length)
+      callback.apply(null, callbackArgs)
+    } else {
+      callback.call(null)
+    }
+  })
+}
+
+const doListen = function (
+  module,
+  event,
+  callback,
+  context,
+  once,
+  internal = false,
+) {
+  init()
+
+  if (typeof callback !== 'function') {
+    return Promise.reject('No valid callback function provided.')
+  } else {
+    if (module === '*') {
+      return Promise.reject('No valid module name provided')
+    }
+
+    //TODO: This is a patch and should be removed! Adds "on" if the event does not start with "on".
+    // Added temporarily for backward compatibility with older event namings
+    if (event != '*' && !event.startsWith('on')) {
+      event = 'on' + event[0].toUpperCase() + event.substring(1)
+      console.warn(
+        `Event names should begin with 'on'. Using '${module + '.' + event}' instead.`,
+      )
+    }
+
+    const wildcard = event === '*'
+    const events = wildcard ? validEvents[module] : [event] // explodes wildcards into an array
+    const promises = []
+    const hasContext = Object.values(context).length > 0
+    const contextKey = Object.keys(context)
+      .sort()
+      .map((key) => key + '=' + JSON.stringify(context[key]))
+      .join('&')
+
+    listenerId++
+
+    if (once) {
+      oncers.push(listenerId)
+    }
+
+    events.forEach((event) => {
+      const key = module + '.' + event + (hasContext ? `.${contextKey}` : '')
+
+      if (Object.values(listeners.get(key)).length === 0) {
+        const args = Object.assign({ listen: true }, context)
+
+        const subscriber = module + '.' + event
+        const notifier = module + '.' + event
+
+        Gateway.subscribe(notifier, (params) => {
+          callCallbacks(key, params)
+        })
+        const promise = Gateway.request(subscriber, args)
+        promises.push(promise)
+      }
+
+      const setter = internal ? listeners.setInternal : listeners.set
+
+      if (wildcard) {
+        setter(key, '' + listenerId, (value) => callback(event, value))
+      } else {
+        setter(key, '' + listenerId, callback)
+      }
+    })
+
+    let resolve, reject
+    let p = new Promise((res, rej) => {
+      resolve = res
+      reject = rej
+    })
+
+    // Iterate and resolve/reject through the list of promises sequentially
+    const templistenerId = listenerId
+    if (promises.length) {
+      promises.reduce((prevPromise, currentPromise) => {
+        return prevPromise
+          .then(() => currentPromise)
+          .then((responses) => {
+            resolve(templistenerId)
+          })
+          .catch((error) => {
+            if (event === '*') {
+              resolve(templistenerId)
+            } else {
+              // Remove the failed listener
+              doClear(templistenerId, event, context)
+              reject(error)
+            }
+          })
+      }, Promise.resolve())
+    } else {
+      resolve(listenerId)
+    }
+
+    return p
+  }
+}
+
+const getListenArgs = function (...args) {
+  const callback = args.pop()
+  const [module, event, context] = getClearArgs(...args)
+
+  return [module, event, callback, context]
+}
+
+const getClearArgs = function (...args) {
+  const module = args.shift() || '*'
+  const event = args.shift() || '*'
+  const context = {}
+
+  // populate context based on registered context for this module/event
+  // if an argument is not registered in validContext, that is ok meaning it is not a context argument
+  // Needed after introducing x-contextual-params
+  for (let i = 0; args.length; i++) {
+    let currentArg = args.shift()
+    if (
+      validContext[module] &&
+      validContext[module][event] &&
+      validContext[module][event][i]
+    ) {
+      context[validContext[module][event][i]] = currentArg
+    }
+  }
+  return [module, event, context]
+}
+
+const once = function (...args) {
+  const [module, event, callback, context] = getListenArgs(...args)
+  return doListen(module, event, callback, context, true)
+}
+
+const listen = function (...args) {
+  const [module, event, callback, context] = getListenArgs(...args)
+  return doListen(module, event, callback, context, false)
+}
+
+const clear = function (...args) {
+  if (args && args.length && typeof args[0] === 'number') {
+    return doClear(args[0])
+  } else if (args && args.length && typeof args[1] === 'number') {
+    return doClear(args[1])
+  } else {
+    const [moduleOrId, event, context] = getClearArgs(...args)
+    return doClear(moduleOrId, event, context)
+  }
+}
+
+// calls doListen with a priority flag for internal listeners to get priority
+export const prioritize = function (...args) {
+  const [module, event, callback, context] = getListenArgs(...args)
+  return doListen(module, event, callback, context, false, true)
+}
+
+const unsubscribe = (key, context) => {
+  const [module, event] = key.split('.').slice(0, 2)
+  const args = Object.assign({ listen: false }, context)
+  Gateway.request(module + '.' + event, args)
+  Gateway.unsubscribe(`${module}.${event}`)
+}
+
+// TODO: clear needs to go through Transport Layer
+const doClear = function (moduleOrId = false, event = false, context) {
+  if (event === '*') {
+    event = false
+  }
+
+  if (typeof moduleOrId === 'number') {
+    const searchId = moduleOrId.toString()
+    const key = listeners.find(searchId)
+
+    if (key) {
+      listeners.remove(searchId)
+      if (listeners.count(key) === 0) {
+        unsubscribe(key)
+      }
+      return true
+    }
+    return false
+  } else {
+    if (!moduleOrId && !event) {
+      listeners.keys().forEach((key) => {
+        listeners.removeKey(key)
+        unsubscribe(key)
+      })
+    } else if (!event) {
+      listeners.keys().forEach((key) => {
+        if (key.indexOf(moduleOrId) === 0) {
+          listeners.removeKey(key)
+          unsubscribe(key)
+        }
+      })
+    } else {
+      const hasContext = Object.values(context).length > 0
+      const contextKey = Object.keys(context)
+        .sort()
+        .map((key) => key + '=' + JSON.stringify(context[key]))
+        .join('&')
+      const key =
+        moduleOrId + '.' + event + (hasContext ? `.${contextKey}` : '')
+
+      listeners.removeKey(key)
+      unsubscribe(key, context)
+    }
+  }
+}
+
+const init = () => {}
+
+export default {
+  listen: listen,
+  once: once,
+  clear: clear,
+}

package/dist/lib/Gateway/AppApi.mjs

@@ -0,0 +1,125 @@
+/*
+ * Copyright 2021 Comcast Cable Communications Management, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import Transport from '../Transport/index.mjs'
+
+const win = typeof window !== 'undefined' ? window : {}
+win.__firebolt = win.__firebolt || {}
+
+// JSON RPC id generator, to be shared across all SDKs
+class JsonRpcIdIterator {
+  constructor() {
+    this._id = 1
+  }
+  getJsonRpcId() {
+    return this._id++
+  }
+}
+
+let idGenerator = win.__firebolt.idGenerator || new JsonRpcIdIterator()
+win.__firebolt.idGenerator = idGenerator
+
+const promises = {}
+const deprecated = {}
+
+// request = { method: string, params: object, id: boolean }[]
+// request with no `id` property are assumed to NOT be notifications, i.e. id must be set to false explicitly
+export async function batch(requests) {
+  if (Array.isArray(requests)) {
+    const processed = requests.map((req) =>
+      processRequest(req.method, req.params, req.id, req.id === false),
+    )
+
+    // filter requests exclude notifications, as they don't need promises
+    const promises = processed
+      .filter((req) => req.id)
+      .map((request) => addPromiseToQueue(request.id))
+
+    Transport.send(processed)
+
+    // Using Promise.all get's us batch blocking for free
+    return Promise.all(promises)
+  }
+  throw `Bulk requests must be in an array`
+}
+
+// Request that the server provide fulfillment of an method
+export async function request(method, params) {
+  const json = processRequest(method, params)
+  const promise = addPromiseToQueue(json.id)
+  Transport.send(json)
+  return promise
+}
+
+export function notify(method, params) {
+  Transport.send(processRequest(method, params, true))
+}
+
+export function response(id, result, error) {
+  const promise = promises[id]
+
+  if (promise) {
+    if (error !== undefined) {
+      promises[id].reject(error)
+    } else {
+      promises[id].resolve(result)
+    }
+
+    // TODO make sure this works
+    delete promises[id]
+  } else {
+    // All SDKs use a global id generator and a global transport where they register their callbacks for the responses.
+    // When the global transport receives a message, it calls all registered callbacks with that same message.
+    // That's why we can't generate an error here, as the response could be for a request made by another SDK.
+    // console.log(`Received a response for an unidentified request ${id}, result: ${result}, error: ${error}`);
+  }
+}
+
+export function deprecate(method, alternative) {
+  deprecated[method] = alternative
+}
+
+function addPromiseToQueue(id) {
+  return new Promise((resolve, reject) => {
+    promises[id] = {}
+    promises[id].promise = this
+    promises[id].resolve = resolve
+    promises[id].reject = reject
+  })
+}
+
+function processRequest(method, params, notification = false) {
+  if (deprecated[method]) {
+    console.warn(`WARNING: ${method}() is deprecated. ` + deprecated[method])
+  }
+
+  const id = !notification && idGenerator.getJsonRpcId()
+  const jsonrpc = '2.0'
+  const json = { jsonrpc, method, params }
+
+  !notification && (json.id = id)
+
+  return json
+}
+
+export default {
+  request,
+  batch,
+  response,
+  deprecate,
+}

package/dist/lib/Gateway/Bidirectional.mjs

@@ -0,0 +1,113 @@
+/*
+ * Copyright 2021 Comcast Cable Communications Management, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import PlatformApi from './PlatformApi.mjs'
+import AppApi from './AppApi.mjs'
+import Transport from '../Transport/index.mjs'
+import Settings from '../Settings/index.mjs'
+
+Transport.receive(async (message) => {
+  const json = JSON.parse(message)
+  if (Array.isArray(json)) {
+    json.forEach((message) => processMessage(message))
+  } else {
+    processMessage(json)
+  }
+})
+
+function processMessage(json) {
+  if (Settings.getLogLevel() === 'DEBUG') {
+    console.debug(
+      'Receiving message from transport: \n' +
+        JSON.stringify(json, { indent: '\t' }),
+    )
+  }
+
+  if (json.method !== undefined) {
+    if (json.id !== undefined) {
+      PlatformApi.request(json.id, json.method, json.params)
+    } else {
+      let params = json.params
+      // TODO: Check if json.params is an array and if so, convert to a key-value object
+      // This is necessary because for Ripple, if params is an array this means that
+      // the callback function is expected to have one argument - the array itself.
+      // This is not compliant with the JSON-RPC specification, i.e. it should be removed.
+      if (Array.isArray(params)) {
+        params = { value: json.params }
+      }
+      PlatformApi.notify(json.method, params)
+    }
+  } else if (json.id !== undefined) {
+    AppApi.response(json.id, json.result, json.error)
+  }
+}
+
+export async function batch(requests) {
+  if (Array.isArray(requests)) {
+    return await AppApi.batch(requests)
+  } else {
+    throw 'Gateway.batch() requires an array of requests: { method: String, params: Object, id: Boolean }'
+  }
+}
+
+export async function request(method, params) {
+  if (Array.isArray(method)) {
+    throw 'Use Gateway.batch() for batch requests.'
+  } else {
+    return await AppApi.request(method, params)
+  }
+}
+
+export async function notify(method, params) {
+  if (Array.isArray(method)) {
+    throw 'Use Gateway.batch() for batch requests.'
+  } else {
+    return await AppApi.notify(method, params)
+  }
+}
+
+export function subscribe(event, callback) {
+  PlatformApi.subscribe(event, callback)
+}
+
+export function unsubscribe(event) {
+  PlatformApi.unsubscribe(event)
+}
+
+export function simulate(event, value) {
+  PlatformApi.simulate(event, value)
+}
+
+export function provide(interfaceName, provider) {
+  PlatformApi.provide(interfaceName, provider)
+}
+
+export function deprecate(method, alternative) {
+  AppApi.deprecate(method, alternative)
+}
+
+export default {
+  request,
+  notify,
+  batch,
+  subscribe,
+  unsubscribe,
+  simulate,
+  provide,
+  deprecate,
+}

package/dist/lib/Gateway/PlatformApi.mjs

@@ -0,0 +1,130 @@
+/*
+ * Copyright 2021 Comcast Cable Communications Management, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import Transport from '../Transport/index.mjs'
+
+const providers = {}
+const interfaces = {}
+const listeners = {}
+
+// Request that the app provide fulfillment of an method
+export async function request(id, method, params, transforms) {
+  let result, error
+  try {
+    result = await getProviderResult(method, params)
+  } catch (e) {
+    error = e
+  }
+
+  const response = {
+    jsonrpc: '2.0',
+    id: id,
+  }
+
+  if (error) {
+    // todo: make sure this conforms to JSON-RPC schema for errors
+    response.error = error
+  } else {
+    response.result = result
+    if (result === undefined) {
+      response.result = null
+    }
+  }
+
+  Transport.send(response)
+}
+
+export async function notify(method, params) {
+  if (listeners[method]) {
+    listeners[method](params)
+    return
+  }
+  // All SDKs use a global transport where they register their callbacks for the responses.
+  // When the global transport receives a message, it calls all registered callbacks with that same message.
+  // That's why we can't generate an error here, as the response could be for an event registered by another SDK.
+  //console.log( `Notification not implemented: ${method}`);
+}
+
+// Register a provider implementation with an interface name
+export function provide(interfaceName, provider) {
+  providers[interfaceName] = provider
+}
+
+// Register a notification listener with an event name
+export function subscribe(event, callback) {
+  listeners[event] = callback
+}
+
+export function unsubscribe(event) {
+  delete listeners[event]
+}
+
+export function simulate(event, value) {
+  listeners[event](value)
+}
+
+// TODO: consider renaming
+export function registerProviderInterface(
+  capability,
+  _interface,
+  method,
+  parameters,
+  response,
+  focusable,
+) {
+  interfaces[_interface] = interfaces[_interface] || {
+    capability,
+    name: _interface,
+    methods: [],
+  }
+
+  interfaces[_interface].methods.push({
+    name: method,
+    parameters,
+    response,
+    focusable,
+  })
+}
+
+async function getProviderResult(method, params = {}) {
+  const split = method.split('.')
+  method = split.pop()
+  const interfaceName = split.join('.')
+
+  if (providers[interfaceName]) {
+    if (providers[interfaceName][method]) {
+      // sort the params into an array based on the interface parameter order
+      const parameters = interfaces[interfaceName].methods
+        .find((m) => m.name === method)
+        .parameters.map((p) => params[p])
+        .filter((p) => p !== undefined)
+      return await providers[interfaceName][method](...parameters)
+    }
+    throw `Method not implemented: ${method}`
+  }
+  throw `Interface not provided: ${interfaceName}`
+}
+
+export default {
+  request,
+  notify,
+  provide,
+  subscribe,
+  unsubscribe,
+  simulate,
+}