Skip to content

Commit

Permalink
Docs: Update lastRun() documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
janiceilene authored and phated committed Oct 19, 2018
1 parent e447d81 commit 363df21
Show file tree
Hide file tree
Showing 2 changed files with 83 additions and 43 deletions.
83 changes: 83 additions & 0 deletions docs/api/last-run.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
<!-- front-matter
id: api-lastrun
title: lastRun()
hide_title: true
sidebar_label: lastRun()
-->

# lastRun()

Retrieves the last time a task was successfully completed during the current running process. Most useful on subsequent task runs while a watcher is running.

When combined with `src()`, enables incremental builds to speed up your execution times by skipping files that haven't changed since the last successful task completion.

## Usage

```js
const { src, dest, lastRun, watch } = require('gulp');
const imagemin = require('gulp-imagemin');

function images() {
return src('src/images/**/*.jpg', { since: lastRun(images) })
.pipe(imagemin())
.pipe(dest('build/img/'));
}

function watch() {
watch('src/images/**/*.jpg', images);
}

exports.watch = watch;
```


## Signature

```js
lastRun(task, [precision])
```

### Parameters

| parameter | type | note |
|:--------------:|:------:|-------|
| task <br> **(required)** | function <br> string | The task function or the string alias of a registered task. |
| precision | number | Default: `1000` on Node v0.10, `0` on Node v0.12+. Detailed in Timestamp precision][timestamp-precision-section] section below. |

### Returns

A timestamp (in milliseconds), matching the last completion time of the task. If the task has not been run or has failed, returns `undefined`.

To avoid an invalid state being cached, the returned value will be `undefined` if a task errors.

### Errors

When called with a value other than a string or function, throws an error with the message, "Only functions can check lastRun".

When called on a non-extensible function and Node is missing WeakMap, throws an error with the message, "Only extensible functions can check lastRun".

## Timestamp precision

While there are sensible defaults for the precision of timestamps, they can be rounded using the `precision` parameter. Useful if your file system or Node version has a lossy precision on file time attributes.

* `lastRun(someTask)` returns 1426000001111
* `lastRun(someTask, 100)` returns 1426000001100
* `lastRun(someTask, 1000)` returns 1426000001000

A file's [mtime stat][fs-stats-concepts] precision may vary depending on the node version and/or the file system used:


| platform | precision |
|:-----------:|:------------:|
| Node v0.10 | 1000ms |
| Node v0.12+ | 1ms |
| FAT32 file system | 2000ms |
| HFS+ or Ext3 file systems | 1000ms |
| NTFS using Node v0.10 | 1s |
| NTFS using Node 0.12+ | 100ms |
| Ext4 using Node v0.10 | 1000ms |
| Ext4 using Node 0.12+ | 1ms |


[timestamp-precision-section]: #timestamp-precision
[fs-stats-concepts]: concepts.md#file-system-stats
43 changes: 0 additions & 43 deletions docs/api/lastRun.md

This file was deleted.

0 comments on commit 363df21

Please sign in to comment.