Add docs and tests

.github/workflows/cache-tests.yml

@@ -0,0 +1,61 @@
+name: cache-unit-tests
+on: push
+
+jobs:
+  build:
+    name: Build
+
+    strategy:
+      matrix:
+        runs-on: [ubuntu-latest, windows-latest, macOS-latest]
+      fail-fast: false
+
+    runs-on: ${{ matrix.runs-on }}
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+
+    - name: Set Node.js 12.x
+      uses: actions/setup-node@v1
+      with:
+        node-version: 12.x
+
+    # In order to save & restore cache artifacts from a shell script, certain env variables need to be set that are only available in the
+    # node context. This runs a local action that gets and sets the necessary env variables that are needed
+    - name: Set env variables
+      uses: ./packages/cache/__tests__/__fixtures__/
+
+    # Need root node_modules because certain npm packages like jest are configured for the entire repository and it won't be possible
+    # without these to just compile the cache package
+    - name: Install root npm packages
+      run: npm ci
+
+    - name: Compile cache package
+      run: |
+        npm ci
+        npm run tsc
+      working-directory: packages/cache
+    
+    - name: Generate files in working directory
+      shell: bash
+      run: scripts/create-cache-files.sh ${{ runner.os }} test-cache
+
+    - name: Generate files outside working directory
+      shell: bash
+      run: scripts/create-cache-files.sh ${{ runner.os }} ~/test-cache
+
+    # We're using node -e to call the functions directly available in the @actions/cache package
+    - name: Save cache using saveCache()
+      run: |
+        node -e "Promise.resolve(require('./packages/cache/lib/cache').saveCache(['test-cache','~/test-cache'],'test-${{ runner.os }}-${{ github.run_id }}'))"
+
+    - name: Restore cache using restoreCache()
+      run: |
+        node -e "Promise.resolve(require('./packages/cache/lib/cache').restoreCache(['test-cache','~/test-cache'],'test-${{ runner.os }}-${{ github.run_id }}'))"
+
+    - name: Verify cache 
+      shell: bash
+      run: |
+        scripts/verify-cache-files.sh ${{ runner.os }} test-cache
+        scripts/verify-cache-files.sh ${{ runner.os }} ~/test-cache

README.md

@@ -59,6 +59,8 @@ $ npm install @actions/io --save
 
 Provides functions for downloading and caching tools.  e.g. setup-* actions. Read more [here](packages/tool-cache)
 
+See @actions/cache for caching workflow dependencies. 
+
 ```bash
 $ npm install @actions/tool-cache --save
 ```
@@ -84,7 +86,7 @@ $ npm install @actions/artifact --save
 
 :dart: [@actions/cache](packages/cache) 
 
-Provides functions to cache dependencies and build outputs to improve workflow execution time.. Read more [here](packages/cache)
+Provides functions to cache dependencies and build outputs to improve workflow execution time. Read more [here](packages/cache)
 
 ```bash
 $ npm install @actions/cache --save

packages/cache/README.md

@@ -6,8 +6,36 @@
 
 #### Restore Cache
 
+Restores a cache based on `key` and `restoreKeys` to the `paths` provided. Function returns the cache key for cache hit and returns undefined if cache not found. 
+
+```js
+const cache = require('@actions/cache');
+const paths = [
+    'node_modules',
+    'packages/*/node_modules/'
+]
+const key = 'npm-foobar-d5ea0750'
+const restoreKeys = [
+    'npm-foobar-',
+    'npm-'
+]
+const cacheKey = await cache.restoreCache(paths, key, restoreKeys)
+```
+
 #### Save Cache
 
+Saves a cache containing the files in `paths` using the `key` provided. Function returns the cache id if the cache was save succesfully.
+
+```js
+const cache = require('@actions/cache');
+const paths = [
+    'node_modules',
+    'packages/*/node_modules/'
+]
+const key = 'npm-foobar-d5ea0750'
+const cacheId = await cache.saveCache(paths, key)
+```
+
 ## Additional Documentation
 
 See ["Caching dependencies to speed up workflows"](https://help.github.com/github/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows).

packages/cache/__tests__/__fixtures__/action.yml

@@ -0,0 +1,5 @@
+name: 'Set env variables'
+description: 'Sets certain env variables so that e2e restore and save cache can be tested in a shell'
+runs:
+  using: 'node12'
+  main: 'index.js'

packages/cache/__tests__/__fixtures__/index.js

@@ -0,0 +1,5 @@
+// Certain env variables are not set by default in a shell context and are only available in a node context from a running action
+// In order to be able to restore and save cache e2e in a shell when running CI tests, we need these env variables set
+console.log(`::set-env name=ACTIONS_RUNTIME_URL::${process.env.ACTIONS_RUNTIME_URL}`)
+console.log(`::set-env name=ACTIONS_RUNTIME_TOKEN::${process.env.ACTIONS_RUNTIME_TOKEN}`)
+console.log(`::set-env name=GITHUB_RUN_ID::${process.env.GITHUB_RUN_ID}`)

packages/cache/package-lock.json

@@ -4,6 +4,28 @@
 	"lockfileVersion": 1,
 	"requires": true,
 	"dependencies": {
+		"@actions/core": {
+			"version": "1.2.4",
+			"resolved": "https://registry.npmjs.org/@actions/core/-/core-1.2.4.tgz",
+			"integrity": "sha512-YJCEq8BE3CdN8+7HPZ/4DxJjk/OkZV2FFIf+DlZTC/4iBlzYCD5yjRR6eiOS5llO11zbRltIRuKAjMKaWTE6cg=="
+		},
+		"@actions/exec": {
+			"version": "1.0.4",
+			"resolved": "https://registry.npmjs.org/@actions/exec/-/exec-1.0.4.tgz",
+			"integrity": "sha512-4DPChWow9yc9W3WqEbUj8Nr86xkpyE29ZzWjXucHItclLbEW6jr80Zx4nqv18QL6KK65+cifiQZXvnqgTV6oHw==",
+			"requires": {
+				"@actions/io": "^1.0.1"
+			}
+		},
+		"@actions/glob": {
+			"version": "0.1.0",
+			"resolved": "https://registry.npmjs.org/@actions/glob/-/glob-0.1.0.tgz",
+			"integrity": "sha512-lx8SzyQ2FE9+UUvjqY1f28QbTJv+w8qP7kHHbfQRhphrlcx0Mdmm1tZdGJzfxv1jxREa/sLW4Oy8CbGQKCJySA==",
+			"requires": {
+				"@actions/core": "^1.2.0",
+				"minimatch": "^3.0.4"
+			}
+		},
 		"@actions/http-client": {
 			"version": "1.0.8",
 			"resolved": "https://registry.npmjs.org/@actions/http-client/-/http-client-1.0.8.tgz",
@@ -12,12 +34,44 @@
 				"tunnel": "0.0.6"
 			}
 		},
+		"@actions/io": {
+			"version": "1.0.2",
+			"resolved": "https://registry.npmjs.org/@actions/io/-/io-1.0.2.tgz",
+			"integrity": "sha512-J8KuFqVPr3p6U8W93DOXlXW6zFvrQAJANdS+vw0YhusLIq+bszW8zmK2Fh1C2kDPX8FMvwIl1OUcFgvJoXLbAg=="
+		},
 		"@types/uuid": {
 			"version": "3.4.9",
 			"resolved": "https://registry.npmjs.org/@types/uuid/-/uuid-3.4.9.tgz",
 			"integrity": "sha512-XDwyIlt/47l2kWLTzw/mtrpLdB+GPSskR2n/PIcPn+VYhVO77rGhRncIR5GPU0KRzXuqkDO+J5qqrG0Y8P6jzQ==",
 			"dev": true
 		},
+		"balanced-match": {
+			"version": "1.0.0",
+			"resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.0.tgz",
+			"integrity": "sha1-ibTRmasr7kneFk6gK4nORi1xt2c="
+		},
+		"brace-expansion": {
+			"version": "1.1.11",
+			"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
+			"integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+			"requires": {
+				"balanced-match": "^1.0.0",
+				"concat-map": "0.0.1"
+			}
+		},
+		"concat-map": {
+			"version": "0.0.1",
+			"resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
+			"integrity": "sha1-2Klr13/Wjfd5OnMDajug1UBdR3s="
+		},
+		"minimatch": {
+			"version": "3.0.4",
+			"resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.4.tgz",
+			"integrity": "sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA==",
+			"requires": {
+				"brace-expansion": "^1.1.7"
+			}
+		},
 		"tunnel": {
 			"version": "0.0.6",
 			"resolved": "https://registry.npmjs.org/tunnel/-/tunnel-0.0.6.tgz",

scripts/create-cache-files.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+
+# Validate args
+prefix="$1"
+if [ -z "$prefix" ]; then
+  echo "Must supply prefix argument"
+  exit 1
+fi
+
+path="$2"
+if [ -z "$path" ]; then
+  echo "Must supply path argument"
+  exit 1
+fi
+
+mkdir -p $path
+echo "$prefix $GITHUB_RUN_ID" > $path/test-file.txt

scripts/verify-cache-files.sh

@@ -0,0 +1,36 @@
+#!/bin/sh
+
+# Validate args
+prefix="$1"
+if [ -z "$prefix" ]; then
+  echo "Must supply prefix argument"
+  exit 1
+fi
+
+path="$2"
+if [ -z "$path" ]; then
+  echo "Must specify path argument"
+  exit 1
+fi
+
+# Sanity check GITHUB_RUN_ID defined
+if [ -z "$GITHUB_RUN_ID" ]; then
+  echo "GITHUB_RUN_ID not defined"
+  exit 1
+fi
+
+# Verify file exists
+file="$path/test-file.txt"
+echo "Checking for $file"
+if [ ! -e $file ]; then
+  echo "File does not exist"
+  exit 1
+fi
+
+# Verify file content
+content="$(cat $file)"
+echo "File content:\n$content"
+if [ -z "$(echo $content | grep --fixed-strings "$prefix $GITHUB_RUN_ID")" ]; then
+  echo "Unexpected file content"
+  exit 1
+fi