Skip to content

Commit

Permalink
Merge pull request #46 from alexreardon/api-cleanup
Browse files Browse the repository at this point in the history
2.0.0 API cleanup
alexreardon authored Jan 9, 2017
2 parents 41cdc0d + 685f37a commit 7b7a1f4
Showing 4 changed files with 27 additions and 75 deletions.
37 changes: 19 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
@@ -118,9 +118,9 @@ Created by `createStub()`
type Stub = {|
add: (cb: Function) => number,
remove: (id: number) => void,
flush: (duration: ?number) => void,
flush: (duration?: number) => void,
reset: () => void,
step: (steps?: number, duration?: ?number) => void
step: (steps?: number, duration?: number) => void
|};
```

@@ -152,16 +152,17 @@ const stub = createStub(frameDuration, startTime);

### `stub.add(callback)`

It schedules the callback to be called in the next frame.
It returns an `id` that can be used to cancel the frame in the future. Same api as `requestAnimationFrame`.

Callbacks will *not* automatically get called after a period of time. You need to explicitly release it using `stub.step()` or `stub.flush()`

**type signature**

```js
function add (cb: Function): number
```

Same api as `requestAnimationFrame`. It schedules the callback to be called in the next frame.
It returns an `id` that can be used to cancel the frame in the future.
Callbacks will *not* automatically get called after a period of time. You need to explicitly release it using `step()` or `flush()`

```js
const stub = createStub();
const callback = () => {};
@@ -171,14 +172,14 @@ stub.add(callback);

### `stub.remove(id)`

It takes the id of a `stub.add()` call and cancels it without calling it. Same api as `cancelAnimationFrame(id)`.

**type signature**

```js
function remove (id: number): void
```

Same api as `cancelAnimationFrame(id)`. It takes the id of a `stub.add()` call and cancels it without calling it.

```js
const stub = createStub();
const callback = () => console.log('hi');
@@ -195,14 +196,14 @@ stub.step();

### `.step()`

Executes all callbacks in the current frame and optionally additional frames.

**type signature**

```js
step: (steps?: number, duration?: ?number) => void
```

Executes all callbacks in the current frame and optionally additional frames.

- `steps` => the amount of animation frames you would like to release. Defaults to `1`. This is useful when you have nested calls.
- `duration (Number)` => the amount of time the frame takes to execute. The default `duration` value is provided by the `frameDuration` argument to `createStub(frameDuration)`. However, you can override it for a specific `.step()` call using the `duration` argument.

@@ -265,15 +266,15 @@ stub.step(1, longFrameDuration);

### `stub.flush()`

Executes all `requestAnimationFrame` callbacks, including nested calls. It will keep executing frames until there are no frames left. An easy way to to think of this function is "`step()` until there are no more steps left.

**type signature**

```js
flush: (duration: ?number) => void
```
Executes all `requestAnimationFrame` callbacks, including nested calls. It will keep executing frames until there are no frames left. An easy way to to think of this function is "`step()` until there are no more steps left"
- `duration (Number)` => the duration for each frame in the flush - each frame gets the same value. If you want different frames to get different values then use `.step()`. The default `duration` value is provided by the `frameDuration` argument to `createStub(frameDuration)`. However, you can override it for a specific `.flush()` call using the `duration` argument.
- `duration` => the duration for each frame in the flush - each frame gets the same value. If you want different frames to get different values then use `.step()`. The default `duration` value is provided by the `frameDuration` argument to `createStub(frameDuration)`. However, you can override it for a specific `.flush()` call using the `duration` argument.
**Warning** if your code just calls `requestAnimationFrame` in an infinite loop then this will never end. Consider using `.step()` for this use case
@@ -311,14 +312,14 @@ stub.flush(200);
### `.reset()`
Clears all the frames without executing any callbacks, unlike `flush()` which executes all the callbacks. Reverts the stub to it's initial state. This is similar to `remove(id)` but it does not require an `id`; `reset` will also clear **all** callbacks in the frame whereas `remove(id)` only removes a single one.
**type signature**
```js
reset: () => void
```
Clears all the frames without executing any callbacks, unlike `flush()` which executes all the callbacks. Reverts the stub to it's initial state. This is similar to `remove(id)` but it does not require an `id`; `reset` will also clear **all** callbacks in the frame whereas `remove(id)` only removes a single one.
```js

const callback = () => console.log('first callback');
@@ -336,13 +337,13 @@ api.step();
### `replaceRaf()`
This function is used to set a `requestAnimationFrame` and `cancelAnimationFrame` on a root (eg `window`).
This function is used to set overwrite `requestAnimationFrame` and `cancelAnimationFrame` on a root (eg `window`). This is useful if you want to control `requestAnimationFrame` for dependencies.
**type signature**
```js
type ReplaceRafOptions = {
duration?: number,
frameDuration?: number,
startTime?: number
};

@@ -534,7 +535,7 @@ stub.add(currentTime => {
if(startTime + currentTime > idealFrameDuration) {
console.log('a slow frame occured');
} else {
console.log('a standard frame occured');
console.log('a standard frame occured');
}
});

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "raf-stub",
"version": "1.0.4",
"version": "2.0.0",
"description": "Accurate and predictable testing of requestAnimationFrame and cancelAnimationFrame",
"main": "lib/index.js",
"module": "src/index.js",
26 changes: 6 additions & 20 deletions src/index.js
Original file line number Diff line number Diff line change
@@ -88,31 +88,18 @@ export default function createStub (frameDuration: number = defaultFrameDuration
}

type ReplaceRafOptions = {
duration?: number,
frameDuration?: number,
startTime?: number
};

/* eslint-disable no-redeclare*/
// 0.3.x api
declare function replaceRaf(...rest: Array<Object>): void;

// new api
declare function replaceRaf(roots?: Object[], options?: ?ReplaceRafOptions): void;

// all calls to replaceRaf get the same stub;
export function replaceRaf(roots?: Object[] = [], { duration = defaultFrameDuration, startTime = now() }: ReplaceRafOptions = {}) {
// 0.3.x api support
if (arguments.length && !Array.isArray(roots)) {
console.warn('replaceRaf(roots) has been depreciated. Please now use replaceRaf([roots], options). See here for more details: https://github.com/alexreardon/raf-stub/releases');
roots = Array.from(arguments);
}

// automatic usage of 'window' or 'global'
export function replaceRaf(roots?: Object[] = [], { frameDuration = defaultFrameDuration, startTime = now() }: ReplaceRafOptions = {}) {
// automatic usage of 'window' or 'global' if no roots are provided
if (!roots.length) {
roots.push(typeof window !== 'undefined' ? window : global);
}

const stub = createStub(duration, startTime);
// all roots share the same stub
const stub = createStub(frameDuration, startTime);

roots.forEach(root => {
root.requestAnimationFrame = stub.add;
@@ -124,5 +111,4 @@ export function replaceRaf(roots?: Object[] = [], { duration = defaultFrameDurat

root.cancelAnimationFrame = stub.remove;
});
}
/* eslint-enable no-redeclare*/
}
37 changes: 1 addition & 36 deletions test/index.js
Original file line number Diff line number Diff line change
@@ -504,7 +504,7 @@ describe('replaceRaf', () => {

replaceRaf([root], {
startTime,
duration: customDuration,
frameDuration: customDuration,
});

root.requestAnimationFrame(callback);
@@ -528,39 +528,4 @@ describe('replaceRaf', () => {
expect(callback.calledWith(customStartTime + defaultFrameDuration)).to.be.true;
});
});

describe('0.3.x support', () => {
beforeEach(() => {
sinon.stub(console, 'warn');
});

afterEach(() => {
console.warn.restore();
});

it('should support a single root as an argument', () => {
const root = {};

replaceRaf(root);

expect(root.requestAnimationFrame).to.be.a.function;
});

it('should support passing in multiple roots separated by commas', () => {
const root1 = {};
const root2 = {};

replaceRaf(root1, root2);

expect(root1.requestAnimationFrame).to.equal(root2.requestAnimationFrame);
});

it('should log a deprecation message', () => {
const root = {};

replaceRaf(root);

expect(console.warn.called).to.be.true;
});
});
});

0 comments on commit 7b7a1f4

Please sign in to comment.