@depack/cache

@depack/cache Computes Necessary Information To Cache A Module, And Allows To Check If It Has Been Updated. Does so with static analysis of source (mtimes), Node.JS built-ins (names) and package dependencies (versions).

yarn add @depack/cache
npm i @depack/cache

Table Of Contents

• Table Of Contents
• API
• async compare(path: string, cache=: !Cache, log=: !Function): !CacheResult
  • Cache
  • CacheEntry
  • CacheResult
• No Cache
• Mtime Change
• Hash Update
• Copyright

API

The package is available by importing its default function:

import compare from '@depack/cache'

async compare(
  path: string,
  cache=: !Cache,
  log=: !Function,
): !CacheResult

Checks the entry file's mtime, calculates its dependencies and compare against the values stored in the cache object. When the result is negative, the cache object must be updated with the result returned by the function.

• path* string: The path to the JS file.
• cache !Cache (optional): Current cache object.
• log !Function (optional): The function used to display what changes have been made to the dependencies.

!Object<string, CacheEntry> Cache: Interface for the cache object.

CacheEntry: A single entry in the cache.

Name	Type	Description
mtime*	number	The mtime of the source file.
hash*	!Array<string>	The analysis array containing strings with internal, external and built-in dependencies and their versions.

CacheResult: The return type of the program.

Name	Type	Description
result*	boolean	Whether the result of the comparison was successful.
reason	string	The reason for the failed comparison. Can be either: NO_CACHE, MTIME_CHANGE, HASH_CHANGE.
mtime	number	The mtime of when the entry file was changed.
currentMtime	number	The mtime from the cache passed to the function.
hash	!Array<string>	The analysis array that is used for comparison and user-friendly display of what dependencies changed.
md5*	string	The md5 of the hash array.

There are multiple scenarios when using this package. Examples of each are given in the examples below.

No Cache

The first instance is when the cache entry does not exist. The cache can be stored in a json file, and read with the require function (but the delete require.cache[path] must be called first), or using fs.readFileSync or any other read method and then parsing the cache.

For example, given the following dir:

example/source/index.js

import { homedir } from 'os'
import dep from './dep'
import staticAnalysis from 'static-analysis'
import myPackage from 'myPackage'

example/source/dep.js

export default () => {
  console.log('dep')
}

The compare method can be called in the following way:

import compare from '@depack/cache'

// returns empty cache
const readCache = () => ({})
// updates cache
const writeCache = (entry) => {
  const current = readCache()
  const updated = { ...current, ...entry }
  // fs.writeFileSync('cache.json', JSON.stringify(updated, null, 2))
}

;(async () => {
  const cache = readCache()
  const modulePath = 'example/source/index.js'
  const res = await compare(modulePath, cache)
  if (res.reason == 'NO_CACHE') {
    console.log(res)
    // do some logic
    const { mtime, hash } = res
    const cacheToWrite = {
      [modulePath]: {
        mtime, hash,
      },
    }
    writeCache(cacheToWrite)
  }
})()

It will return the result that indicates that the cache does not exist, and provide all information that should be written in cache so that it can be retrieved next time:

{
  result: false,
  reason: 'NO_CACHE',
  mtime: 1554399982000,
  hash: [
    'os',
    'example/source/dep.js 1554389422000',
    'static-analysis 2.1.1',
    'myPackage 1.0.0'
  ],
  md5: '980d26e614a016566682df0ddd47bb6f'
}

Mtime Change

If the module's mtime has changed, the result will be false, with the new mtime returned so that it can be updated. The current implementation is coupled to mtime logic, therefore when transferring onto other machines via git for example, the cache will fail. It might be improved in the future.

let cache = {}
const { mtime, hash } = await compare(path, cache)
cache[path] = { mtime, hash }
await update()
const res = await compare(path, cache)
console.log(res)

{
  result: false,
  reason: 'MTIME_CHANGE',
  mtime: 1582738908000,
  hash: [
    'os',
    'example/source/dep.js 1554389422000',
    'static-analysis 2.1.1',
    'myPackage 1.0.0'
  ],
  currentMtime: 1582738907000,
  md5: '980d26e614a016566682df0ddd47bb6f'
}

Hash Update

The hash is an array with strings that show what version of a dependency/file are used by the entry source file. They are saved in cache in the full array form rather than md5 itself so that it is possible to log about when the changes were made and to which files. The changes will be logged using the function provided (console.log by default).

let cache = {}
const { mtime, hash } = await compare(path, cache)
cache[path] = { mtime, hash }
await update()
const res = await compare(path, cache, console.error)
console.log(res)

stderr

+ example/temp/source/dep.js 2/26/2020, 20:41:50
+ myPackage 1.0.1
+ path 
- example/temp/source/dep.js 2/26/2020, 20:41:49
- myPackage 1.0.0

{
  result: false,
  mtime: 1582738909000,
  hash: [
    'os',
    'example/temp/source/dep.js 1582738910000',
    'static-analysis 2.1.1',
    'myPackage 1.0.1',
    'path'
  ],
  reason: 'HASH_CHANGE',
  md5: '8ee4ba1189bd9cae5132e49a0d48856c'
}

Copyright

	© Art Deco™ for Depack 2020