@depack/cache

    1.2.1 • Public • Published

    @depack/cache

    npm version Node.js CI

    @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

    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 © Art Deco™ for Depack 2020

    Install

    npm i @depack/cache

    DownloadsWeekly Downloads

    5

    Version

    1.2.1

    License

    MIT

    Unpacked Size

    96 kB

    Total Files

    16

    Last publish

    Collaborators

    • zvr