Add archive extractor to @actions/tool-cache

[nikolai-laevskii]

A helper that adds a thin wrapper around toolkit cache methods extractZip, extractTar, extract7z, extractXar and downloadTool. Allows to download archive from remote source, automatically detect its type and apply appropriate utility for extraction. This allows consistent and predictable archive processing which is much necessary within setup-actions.

Basic usage:

import {Archive} from '@actions/tool-cache'

const archive = await Archive.retrieve('https://archiveurl')
const extPath = await archive.extract()

/** Or with additional options **/
const archive = await Archive.retrieve('https://downloadurl', {
  type: 'zip', // archive type can be specified right away
  downloadPath: 'C:\\some\arbitrary\path', // download folder can also be specified
  /* auth and headers parameters work exactly like in downloadTool: */
  auth: 'token',
  headers: {
     accept: 'application/zip'
  }
});

Narrowing down archive types:

import {Archive} from '@actions/tool-cache'

/** Option 1: narrowing down with typeguards **/

const archive = await Archive.retrieve('https://archiveurl')
let extPath: string;

// This will allow to pass parameters specific for extractTar method
if (Archive.isTarArchive(archive)) {
  extPath = await archive.extract(undefined, ['xz', '--strip', '1'])
}

/** Option 2: narrowing down manually, this way autodetection of archive type is disabled **/

const archive = await Archive.retrieve('https://archiveurl', { type: 'tar' })
const extPath  = await archive.extract(undefined, ['xz', '--strip', '1'])