adapt-migrations 1.0.0

package/lib/CacheManager.js

@@ -0,0 +1,95 @@
+import crypto from 'crypto'
+import path from 'path'
+import globs from 'globs'
+import fs from 'fs-extra'
+import os from 'os'
+import Logger from './Logger.js'
+
+export const ONE_MINUTE = 60 * 1000
+export const ONE_HOUR = 60 * ONE_MINUTE
+export const ONE_WEEK = 7 * 24 * ONE_HOUR
+
+const logger = Logger.getInstance();
+
+export default class CacheManager {
+  constructor (maxAge = ONE_WEEK) {
+    this.maxAge = maxAge
+  }
+
+  static hash (path) {
+    return crypto
+      .createHash('sha1')
+      .update(path, 'utf8')
+      .digest('hex')
+  }
+
+  async getTempPath () {
+    const osTempPath = await fs.promises.realpath(path.resolve(os.tmpdir()))
+    const tempPath = path.posix.join(osTempPath, 'migrations')
+    await fs.ensureDir(tempPath)
+    return tempPath
+  }
+
+  async getCachePath ({ basePath = process.cwd(), outputPath, tempPath }) {
+    const projectHash = CacheManager.hash(path.join(basePath, outputPath))
+    if (tempPath) await fs.ensureDir(tempPath)
+    const cachePath = path.join(tempPath ?? await this.getTempPath(), `${projectHash}.cache`)
+    return cachePath
+  }
+
+  async getCheckFilePath () {
+    const checkFilePath = path.join(await this.getTempPath(), 'last.touch')
+    return checkFilePath
+  }
+
+  async isCleaningTime () {
+    // By default, clean once a day, or with a floor of one hourly intervals
+    const checkInterval = Math.max(this.maxAge / 7, ONE_HOUR)
+    const checkFilePath = await this.getCheckFilePath()
+    // Check if checkFile is older than the cleaning interval
+    return (!fs.existsSync(checkFilePath) || Date.now() - (await fs.stat(checkFilePath)).mtime >= checkInterval)
+  }
+
+  async clean () {
+    if (!await this.isCleaningTime()) return
+    logger.debug('CacheManager -- Clean running')
+    const checkFilePath = await this.getCheckFilePath()
+    // Touch checkFile
+    await fs.writeFile(checkFilePath, String(Date.now()))
+    logger.debug('CacheManager -- Clearing compilation caches')
+    const tempPath = await this.getTempPath()
+    // Fetch all cache files except checkFile
+    const files = await new Promise((resolve, reject) => globs([
+      `${tempPath}/**`,
+      `!${checkFilePath}`
+    ], {
+      nodir: true
+    }, (err, files) => err ? reject(err) : resolve(files)))
+    // Fetch file ages
+    const fileAges = []
+    const now = Date.now()
+    for (const index in files) {
+      const file = files[index]
+      let age = this.maxAge
+      try {
+        const stat = await fs.stat(file)
+        age = (now - stat.mtime)
+      } catch (err) {
+        logger.error(`CacheManager -- ${err}`)
+      }
+      fileAges[index] = { file, age }
+    }
+    // Sort by oldest
+    fileAges.sort((a, b) => b.age - a.age)
+    // Filter by expired
+    const toRemove = fileAges.filter(fileAge => fileAge.age >= this.maxAge)
+    // Delete expired cache files
+    for (const fileAge of toRemove) {
+      try {
+        await fs.unlink(fileAge.file)
+      } catch (err) {
+        logger.error(`CacheManager -- Could not clear cache file ${fileAge.file}`)
+      }
+    }
+  }
+};

package/lib/Journal.js

@@ -0,0 +1,303 @@
+/**
+ * Set a property value
+ * @param {Object|Array} object
+ * @param {[string]} keys
+ * @param {*} value
+ * @throws {Cannot locate intermediate key: ${keys}}
+ */
+export function setKeys (object, keys, value) {
+  const initialKeys = keys.slice(0, -1)
+  const lastKey = keys[keys.length - 1]
+  const finalObject = initialKeys.reduce((object, key) => {
+    if (!(key in object)) throw new Error(`Cannot locate intermediate key: ${keys}`)
+    return object[key]
+  }, object)
+  finalObject[lastKey] = value
+}
+
+/**
+ * Get a property value
+ * @param {Object|Array} object
+ * @param {[string]} keys
+ * @returns {*}
+ * @throws {Cannot locate intermediate key: ${keys}}
+ */
+export function getKeys (object, keys) {
+  return keys.reduce((object, key) => {
+    if (!(key in object)) throw new Error(`Cannot locate intermediate key: ${keys}`)
+    return object[key]
+  }, object)
+}
+
+/**
+ * Delete a property
+ * @param {Object|Array} object
+ * @param {[string]} keys
+ * @throws {Cannot locate intermediate key: ${keys}}
+ */
+export function deleteKeys (object, keys) {
+  const initialKeys = keys.slice(0, -1)
+  const lastKey = keys[keys.length - 1]
+  const finalObject = initialKeys.reduce((object, key) => {
+    if (!(key in object)) throw new Error(`Cannot locate intermediate key: ${keys}`)
+    return object[key]
+  }, object)
+  delete finalObject[lastKey]
+}
+
+/**
+ * Clones some JSON
+ * @param {Object|Array|string|number|null} object
+ * @returns {Object|Array|string|number|null}
+ */
+export function clone (object) {
+  return JSON.parse(JSON.stringify(object))
+}
+
+/**
+ * Wraps a JSON hierarchy in transparent, dynamically generated
+ * Proxy instances to trap JSON change entries, keeping them in
+ * a journal to undo, patch or capture.
+ */
+export default class Journal {
+  /**
+   * @param {Object} options
+   * @param {Object|Array} options.data JSON to wrap
+   * @param {Function} [options.supplementEntry] Entry supplementation function
+   */
+  constructor ({
+    logger,
+    data
+  }) {
+
+    /**
+     * Add supplemental information to the journal
+     *   for both adapt content and plugins
+     */
+    const supplementEntry = (entry, data) => {
+      switch (entry.keys[0]) {
+        case 'fromPlugins':
+          // plugin name
+          entry._name = data[entry.keys[0]][entry.keys[1]]?.name ?? '';
+          break;
+        case 'content':
+          // object _id, _type and _component or _extension if available
+          entry._id = data[entry.keys[0]][entry.keys[1]]?._id ?? '';
+          entry._type = data[entry.keys[0]][entry.keys[1]]?._type ?? '';
+          if (entry._type && data[entry.keys[0]][entry.keys[1]]?.[`_${entry._type}`]) {
+            entry._name = entry[`_${entry._type}`] = data[entry.keys[0]][entry.keys[1]]?.[`_${entry._type}`] ?? '';
+          }
+      }
+      return entry;
+    }
+    /**
+     *
+     * @param {string} method add/set/delete to signify how the JSON was modified
+     * @param {[string]} keys An array of key names to a location in the JSON hierarchy
+     * @param {Object|Array|string|number|null}  value Value after change
+     * @param {Object|Array|string|number|null}  previous Value before change
+     * @returns
+     */
+    const addEntry = (method, keys, value = null, previous = null) => {
+      // Prevent entries from being added whilst undoing.
+      if (this.isUndoing) return
+      // Add entries to the entries list with any necessary supplemental information.
+      this.entries.push(supplementEntry({
+        method,
+        keys,
+        // Clone the value and previous to preserve the values of objects by reference.
+        value: clone(value),
+        previous: clone(previous)
+      }, this.data))
+    }
+    /**
+     * Wrap an Object or Array in a proxy to trap changes
+     * @param {Object|Array} data JSON object or array to wrap in a proxy
+     * @param {[string]} [keys] Use the closure to store the key location of the generated proxy instance
+     * @returns {Proxy<Object|Array>}
+     */
+    const wrap = (data, keys = []) => {
+      const journal = this
+      return new Proxy(data, {
+        /**
+         * Getter trap. If the property value is an Array or Object, return wrapped at the next key location
+         * @param {Object|Array} target
+         * @param {string} prop Array index or object property name
+         * @returns {Proxy<Object|Array>|string|number|null}
+         */
+        get (target, prop) {
+          const value = target[prop]
+          if (prop === 'valueOf' && typeof value === 'function') {
+            // Special case for turning a proxy into its JSON, which is otherwise not possible
+            // This prevents the data side from being infected by proxies.
+            return function () {
+              return target
+            }
+          }
+          if (Array.isArray(value) || typeof value === 'object') {
+            // Wrap an array or object in a new proxy, passing the appropriate key into the closure.
+            return wrap(value, keys.concat([prop]))
+          }
+          return Reflect.get(...arguments)
+        },
+        /**
+         * Setter trap. Adds entries to the journal at the current key location for sets or adds to the Object or Array.
+         * Has special cases for array length modifications.
+         * @param {Object|Array} target
+         * @param {string} prop
+         * @param {Object|Array|string|number|null} value
+         * @param {Proxy} proxy
+         * @returns {boolean}
+         * @throws {Data is frozen, cannot modify}
+         */
+        set (target, prop, value, proxy) {
+          if (journal.isFrozen) throw new Error('Data is frozen, cannot modify')
+          // Special case for turning a proxy into its JSON, which is otherwise not possible.
+          // This prevents the data side from being infected by proxies.
+          if (value?.valueOf) value = value.valueOf()
+          const previous = target[prop]
+          const isArrayLength = (Array.isArray(target) && prop === 'length')
+          const isObjectPropertyAdd = !(prop in target)
+          if (isArrayLength && target.length === value) {
+            // Ignore identically set lengths for array (splice can do this)
+            // We don't need to add an entry for this.
+            return true
+          } else if (isObjectPropertyAdd) {
+            if (Array.isArray(target) && !isNaN(prop)) {
+              // An array index value is being set.
+              const intProp = parseInt(prop)
+              if (intProp >= target.length) {
+                // Make sure to keep the previous length if the array is growing.
+                addEntry('set', keys.concat(['length']), intProp + 1, target.length)
+              }
+            }
+            // Add an entry for an indexed/named property addition, with its new value.
+            addEntry('add', keys.concat([prop]), value, undefined)
+          } else {
+            // Add an entry for a changed indexed/named property value.
+            addEntry('set', keys.concat([prop]), value, previous)
+          }
+          return Reflect.set(target, prop, value, proxy)
+        },
+        /**
+         * Delete trap. Adds a journal entry if an indexed/named property is deleted.
+         * Splice on an array or delete on an object.
+         * @param {Object|Array} target
+         * @param {string} prop
+         * @returns {boolean}
+         * @throws {Data is frozen, cannot modify}
+         */
+        deleteProperty (target, prop) {
+          if (journal.isFrozen) throw new Error('Data is frozen, cannot modify')
+          const previous = target[prop]
+          addEntry('delete', keys.concat([prop]), undefined, previous)
+          return Reflect.deleteProperty(...arguments)
+        }
+      })
+    }
+    /**
+     * Original JSON.
+     * @type {Object|Array}
+     * */
+    this.data = data
+    /**
+     * Proxied version of data.
+     * @type {Proxy<Object|Array>}
+     * */
+    this.subject = wrap(data)
+  }
+
+  /**
+   * Signifies if the proxy is frozen for sets.
+   * @type {boolean}
+   */
+  get isFrozen () {
+    return this._isFrozen ?? false
+  }
+
+  /**
+   * Freeze the subject for sets.
+   */
+  freeze () {
+    this._isFrozen = true
+  }
+
+  /**
+   * Open the subject to sets.
+   */
+  unfreeze () {
+    this._isFrozen = false
+  }
+
+  /**
+   * Undo and return entries.
+   * @param {number} [count] Number of entries to undo. Defaults to all.
+   * @returns {Array<Object>} Returns undone journal entries.
+   * @throws {Cannot locate intermediate key: ${keys}}
+   */
+  undo (count = this.entries.length) {
+    const entries = []
+    this.isUndoing = true
+    for (let i = 0, l = count; i < l; i++) {
+      const entry = this.entries.pop()
+      entries.unshift(entry)
+      switch (entry.method) {
+        case 'delete':
+        case 'set':
+          setKeys(this.subject, entry.keys, entry.previous)
+          break
+        case 'add':
+          deleteKeys(this.subject, entry.keys)
+          break
+      }
+    }
+    this.isUndoing = false
+    return entries
+  }
+
+  /**
+   * Undo entries up until a specified index.
+   * @param {Number} [index=-1] Index up to which to undo. Used in conjunction with lastEntryIndex.
+   * @returns {Array<Object>} Returns undone journal entries.
+   * @throws {Cannot locate intermediate key: ${keys}}
+   */
+  undoToIndex (index = -1) {
+    const lastIndex = this.entries.length - 1
+    const count = lastIndex - index
+    return this.undo(count)
+  }
+
+  /**
+   * Apply specified entries to the data JSON
+   * @param {Array<Object>} entries Entries to apply to the data JSON.
+   * @throws Cannot locate intermediate key: ${keys}
+   */
+  patch (entries) {
+    for (const entry of entries) {
+      switch (entry.method) {
+        case 'delete':
+          deleteKeys(this.subject, entry.keys)
+          break
+        case 'set':
+        case 'add':
+          setKeys(this.subject, entry.keys, entry.value)
+          break
+      }
+    }
+  }
+
+  /** @type {number} */
+  get lastEntryIndex () {
+    return this.entries.length - 1
+  }
+
+  /** @type {Array<Object>} */
+  get entries () {
+    return (this._entries = this._entries || [])
+  }
+
+  /** @type {Object} */
+  get lastEntry () {
+    return this.entries[this.entries.length - 1]
+  }
+}

package/lib/Logger.js

@@ -0,0 +1,91 @@
+import chalk from 'chalk'
+import path from 'path'
+import fs from 'fs-extra'
+
+function padNum2(value) {
+  return String(value).padStart(2, '0');
+}
+
+export default class Logger {
+  constructor () {
+    this.logArr = []
+    this.config = {
+      levels: {
+        error: {
+          colour: 'red'
+        },
+        warn: {
+          colour: 'yellow'
+        },
+        info: {
+          colour: 'cyan'
+        },
+        debug: {
+          colour: 'grey'
+        }
+      }
+    }
+  }
+
+  // getInstance used to allow import
+  static getInstance () {
+    if (Logger.instance === null) {
+      Logger.instance = new Logger()
+    }
+    return Logger.instance
+  }
+
+  // Colour level string, easier to differentiate between info/error/warn/debug
+  static colourise (str, colour) {
+    const chalkFunc = chalk[colour]
+    return chalkFunc ? chalkFunc(str) : str
+  }
+
+  // Use getDateStamp to return readable date/time string.
+  static getDateStamp () {
+    const d = new Date()
+    const date = `${d.getFullYear().toString()}/${padNum2(d.getMonth() + 1)}/${padNum2(d.getDate())}`
+    const time = `${padNum2(d.getHours())}:${padNum2(d.getMinutes())}:${padNum2(d.getSeconds())}.${padNum2(d.getMilliseconds())}`
+    const str = `${date} ${time}`
+    return str
+  }
+
+  // Add Success/Fail ?
+  info (...args) {
+    this.log('info', args)
+  }
+
+  error (...args) {
+    this.log('error', args)
+  }
+
+  warn (...args) {
+    this.log('warn', args)
+  }
+
+  debug (...args) {
+    this.log('debug', args)
+  }
+
+  // Colour level for easy read, store log in this.logArr as string
+  log (level, args) {
+    const colour = this?.config?.levels[level]?.colour || 'grey'
+    const logFunc = console[level] ?? console.log
+    const dateStamp = Logger.getDateStamp()
+    const argsStr = args.join(', ')
+    logFunc(`(${dateStamp}) -- ${Logger.colourise(level, colour)} -- `, ...args)
+    this.logArr.push(`[${dateStamp}] -- ${level} -- ${argsStr}`)
+  }
+
+  // Output this.logArr, 2 log outputs, capture & migrate
+  output (dir, type) {
+    const logPath = path.join(dir, './logs/')
+    if (!fs.existsSync(logPath)) fs.mkdirSync(logPath)
+
+    const outputName = `${type}_log`
+    const outputFile = path.join(logPath, `${outputName}.json`)
+    fs.writeJSONSync(outputFile, this.logArr, { replacer: null, spaces: 2 })
+  }
+}
+
+Logger.instance = null