1
0
mirror of https://github.com/kremalicious/metamask-extension.git synced 2024-11-23 02:10:12 +01:00

Add a few missing docblocks to background files

This commit is contained in:
Whymarrh Whitby 2018-04-16 12:59:43 -02:30
parent 061975cd4a
commit 603c1310ff
9 changed files with 150 additions and 48 deletions

View File

@ -1,16 +1,20 @@
const log = require('loglevel')
// log rpc activity
module.exports = createLoggerMiddleware
function createLoggerMiddleware ({ origin }) {
return function loggerMiddleware (req, res, next, end) {
next((cb) => {
/**
* Returns a middleware that logs RPC activity
* @param {{ origin: string }} opts - The middleware options
* @returns {Function}
*/
function createLoggerMiddleware (opts) {
return function loggerMiddleware (/** @type {any} */ req, /** @type {any} */ res, /** @type {Function} */ next) {
next((/** @type {Function} */ cb) => {
if (res.error) {
log.error('Error in RPC response:\n', res)
}
if (req.isMetamaskInternal) return
log.info(`RPC (${origin}):`, req, '->', res)
log.info(`RPC (${opts.origin}):`, req, '->', res)
cb()
})
}

View File

@ -1,9 +1,13 @@
// append dapp origin domain to request
module.exports = createOriginMiddleware
function createOriginMiddleware ({ origin }) {
return function originMiddleware (req, res, next, end) {
req.origin = origin
/**
* Returns a middleware that appends the DApp origin to request
* @param {{ origin: string }} opts - The middleware options
* @returns {Function}
*/
function createOriginMiddleware (opts) {
return function originMiddleware (/** @type {any} */ req, /** @type {any} */ _, /** @type {Function} */ next) {
req.origin = opts.origin
next()
}
}

View File

@ -1,26 +1,37 @@
/**
* Returns an EventEmitter that proxies events from the given event emitter
* @param {any} eventEmitter
* @param {object} listeners - The listeners to proxy to
* @returns {any}
*/
module.exports = function createEventEmitterProxy (eventEmitter, listeners) {
let target = eventEmitter
const eventHandlers = listeners || {}
const proxy = new Proxy({}, {
get: (obj, name) => {
const proxy = /** @type {any} */ (new Proxy({}, {
get: (_, name) => {
// intercept listeners
if (name === 'on') return addListener
if (name === 'setTarget') return setTarget
if (name === 'proxyEventHandlers') return eventHandlers
return target[name]
return (/** @type {any} */ (target))[name]
},
set: (obj, name, value) => {
set: (_, name, value) => {
target[name] = value
return true
},
})
function setTarget (eventEmitter) {
}))
function setTarget (/** @type {EventEmitter} */ eventEmitter) {
target = eventEmitter
// migrate listeners
Object.keys(eventHandlers).forEach((name) => {
eventHandlers[name].forEach((handler) => target.on(name, handler))
/** @type {Array<Function>} */ (eventHandlers[name]).forEach((handler) => target.on(name, handler))
})
}
/**
* Attaches a function to be called whenever the specified event is emitted
* @param {string} name
* @param {Function} handler
*/
function addListener (name, handler) {
if (!eventHandlers[name]) eventHandlers[name] = []
eventHandlers[name].push(handler)

View File

@ -1,6 +1,11 @@
const ethUtil = require('ethereumjs-util')
const ethUtil = (/** @type {object} */ (require('ethereumjs-util')))
const BN = ethUtil.BN
/**
* Returns a [BinaryNumber]{@link BN} representation of the given hex value
* @param {string} hex
* @return {any}
*/
module.exports = function hexToBn (hex) {
return new BN(ethUtil.stripHexPrefix(hex), 16)
}

View File

@ -1,11 +1,13 @@
// We should not rely on local storage in an extension!
// We should use this instead!
// https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/storage/local
const extension = require('extensionizer')
const log = require('loglevel')
/**
* A wrapper around the extension's storage local API
*/
module.exports = class ExtensionStore {
/**
* @constructor
*/
constructor() {
this.isSupported = !!(extension.storage.local)
if (!this.isSupported) {
@ -13,6 +15,10 @@ module.exports = class ExtensionStore {
}
}
/**
* Returns all of the keys currently saved
* @return {Promise<*>}
*/
async get() {
if (!this.isSupported) return undefined
const result = await this._get()
@ -25,14 +31,24 @@ module.exports = class ExtensionStore {
}
}
/**
* Sets the key in local state
* @param {object} state - The state to set
* @return {Promise<void>}
*/
async set(state) {
return this._set(state)
}
/**
* Returns all of the keys currently saved
* @private
* @return {object} the key-value map from local storage
*/
_get() {
const local = extension.storage.local
return new Promise((resolve, reject) => {
local.get(null, (result) => {
local.get(null, (/** @type {any} */ result) => {
const err = extension.runtime.lastError
if (err) {
reject(err)
@ -43,6 +59,12 @@ module.exports = class ExtensionStore {
})
}
/**
* Sets the key in local state
* @param {object} obj - The key to set
* @return {Promise<void>}
* @private
*/
_set(obj) {
const local = extension.storage.local
return new Promise((resolve, reject) => {
@ -58,6 +80,11 @@ module.exports = class ExtensionStore {
}
}
/**
* Returns whether or not the given object contains no keys
* @param {object} obj - The object to check
* @returns {boolean}
*/
function isEmpty(obj) {
return Object.keys(obj).length === 0
}

View File

@ -1,7 +1,23 @@
const EventEmitter = require('events')
/**
* @typedef {object} Migration
* @property {number} version - The migration version
* @property {Function} migrate - Returns a promise of the migrated data
*/
/**
* @typedef {object} MigratorOptions
* @property {Array<Migration>} [migrations] - The list of migrations to apply
* @property {number} [defaultVersion] - The version to use in the initial state
*/
class Migrator extends EventEmitter {
/**
* @constructor
* @param {MigratorOptions} opts
*/
constructor (opts = {}) {
super()
const migrations = opts.migrations || []
@ -42,19 +58,30 @@ class Migrator extends EventEmitter {
return versionedData
// migration is "pending" if it has a higher
// version number than currentVersion
/**
* Returns whether or not the migration is pending
*
* A migration is considered "pending" if it has a higher
* version number than the current version.
* @param {Migration} migration
* @returns {boolean}
*/
function migrationIsPending (migration) {
return migration.version > versionedData.meta.version
}
}
generateInitialState (initState) {
/**
* Returns the initial state for the migrator
* @param {object} [data] - The data for the initial state
* @returns {{meta: {version: number}, data: any}}
*/
generateInitialState (data) {
return {
meta: {
version: this.defaultVersion,
},
data: initState,
data,
}
}

View File

@ -8,20 +8,34 @@ module.exports = {
setupMultiplex: setupMultiplex,
}
/**
* Returns a stream transform that parses JSON strings passing through
* @return {stream.Transform}
*/
function jsonParseStream () {
return Through.obj(function (serialized, encoding, cb) {
return Through.obj(function (serialized, _, cb) {
this.push(JSON.parse(serialized))
cb()
})
}
/**
* Returns a stream transform that calls {@code JSON.stringify}
* on objects passing through
* @return {stream.Transform} the stream transform
*/
function jsonStringifyStream () {
return Through.obj(function (obj, encoding, cb) {
return Through.obj(function (obj, _, cb) {
this.push(JSON.stringify(obj))
cb()
})
}
/**
* Sets up stream multiplexing for the given stream
* @param {any} connectionStream - the stream to mux
* @return {stream.Stream} the multiplexed stream
*/
function setupMultiplex (connectionStream) {
const mux = new ObjectMultiplex()
pump(

View File

@ -1,20 +1,25 @@
class SwPlatform {
//
// Public
//
/**
* Reloads the platform
*/
reload () {
// you cant actually do this
global.location.reload()
// TODO: you can't actually do this
/** @type {any} */ (global).location.reload()
}
openWindow ({ url }) {
// this doesnt actually work
global.open(url, '_blank')
/**
* Opens a window
* @param {{url: string}} opts - The window options
*/
openWindow (opts) {
// TODO: this doesn't actually work
/** @type {any} */ (global).open(opts.url, '_blank')
}
/**
* Returns the platform version
* @returns {string}
*/
getVersion () {
return '<unable to read version>'
}

View File

@ -1,18 +1,23 @@
class WindowPlatform {
//
// Public
//
/**
* Reload the platform
*/
reload () {
global.location.reload()
/** @type {any} */ (global).location.reload()
}
openWindow ({ url }) {
global.open(url, '_blank')
/**
* Opens a window
* @param {{url: string}} opts - The window options
*/
openWindow (opts) {
/** @type {any} */ (global).open(opts.url, '_blank')
}
/**
* Returns the platform version
* @returns {string}
*/
getVersion () {
return '<unable to read version>'
}