https://github.com/kyleross/autopurge
Automatically purge old items from an array once it hits a certain length
https://github.com/kyleross/autopurge
Last synced: about 1 year ago
JSON representation
Automatically purge old items from an array once it hits a certain length
- Host: GitHub
- URL: https://github.com/kyleross/autopurge
- Owner: KyleRoss
- License: mit
- Created: 2015-07-13T18:56:47.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2015-07-14T16:44:54.000Z (about 11 years ago)
- Last Synced: 2024-10-30T00:43:34.256Z (over 1 year ago)
- Language: JavaScript
- Size: 133 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: HISTORY.md
- License: LICENSE
Awesome Lists containing this project
README
# Auto Purge
Automatically purge items from an array when the maxlength is hit. This module can be used in Node or the browser. Browser support is for modern ES5 browsers (IE9+, Chrome, Firefox, etc.)
**Why?** There are certain cases where you want a rolling array of values that are limited such as a log system or chat. Once the array fills up to the maxlength, the oldest records are purged from the array.
## Getting Started
Install the AutoPurge module.
### Node
npm install autopurge
```javascript
var AutoPurge = require('autopurge');
```
### Bower
bower install autopurge
### Without Package Manager
Download `autopurge.js` or `autopurge.min.js` in the repository and include in your application.
### Browser
```html
```
## Example
```javascript
var myArray = ['test', 'value', true, false, 1, 20],
purge = new AutoPurge(10, myArray);
purge.push('new value'); // => 0 (no records purged)
purge.length; // => 7
purge.value; // => ['test', 'value', true, false, 1, 20, 'new value']
purge.push.apply(purge, [1, 2, 3, 4, 5]); // => 2 (records purged)
purge.value; // => [true, false, 1, 20, 'new value', 1, 2, 3, 4, 5]
purge.purge(2); // => [true, false]
purge.length; // => 8
// Array modified outside of AutoPurge?
myArray.push('modifying', 'outside', 'does', 'not', 'purge');
purge.length; // => 13 (over the maxlength!)
purge.auto(); // => [1, 20, 'new value']
purge.length; // => 3
purge.clear();
purge.value; // => []
purge.length; // => 0
```
## API Documentation
### Methods
#### AutoPurge([maxlength], [array])
Constructor function to create a new purgable array. Can be called with or without the `new` keyword.
Required | Argument | Type | Description
-------- | ------------- | --------- | ------------
No | maxlength | Number | The maxlength the array can be. Default is `50`.
No | array | Array | An external array to use. Default is `[]`.
```javascript
var purge = new AutoPurge();
var purge2 = AutoPurge(10);
var purge3 = AutoPurge(null, ['custom', 'array']);
var purge4 = new AutoPurge(10, ['custom', 'array']);
```
Returns `AutoPurge`
#### AutoPurge.push(...)
Push item(s) to the array. Each item should be an argument if pushing multiple items. If you need to push an array of items, use `purge.push.apply(purge, [1, 2, 3, 4, 5]);`.
Required | Argument | Type | Description
-------- | ------------- | --------- | ------------
Yes | ... | Any | Each item to push to the array as a separate argument.
```javascript
purge.push('new item');
purge.push(1, 2, 'test', false);
purge.push.apply(purge, [1, 2, 3, 4, 5]);
```
Returns `Number` (the number of items purged as result of the push)
#### AutoPurge.purge([num])
Purge the given number of old items from the array or remove all items without resetting the `_purged` counter like `AutoPurge.clear()`.
Required | Argument | Type | Description
-------- | ------------- | ------------------ | ------------
No | num | Number/String/null | The number of items to remove, `null`, `undefined`, or `'all'` to remove all items.
```javascript
var purge = new AutoPurge(10, ['custom', 'array', 1, 2, 3, 4]);
purge.purge(2); // => ['custom', 'array']
purge.purge(); // => [1, 2, 3, 4]
purge.value; // => []
purge._purged; // => 6
```
Returns `Array` (the items purged from the array)
#### AutoPurge.auto()
If the array is modified without using any of the API methods, you will need to purge it. This will purge the array if the length of the array is greater than `maxlength`.
```javascript
var arr = ['custom', 'array', 1, 2, 3, 4, true, false, {}, []],
purge = new AutoPurge(10, arr);
purge.length; // => 10
arr.push('not', 'using', 'AutoPurge');
purge.length; // => 13
purge.auto(); // => ['custom', 'array', 1]
purge.length; // => 13
```
Returns `Array` (the items purged from the array)
#### AutoPurge.clear()
Clears the array and resets the `_purged` counter back to 0.
```javascript
var purge = new AutoPurge(10, ['custom', 'array', 1, 2, 3, 4]);
purge.purge(2); // => ['custom', 'array']
purge._purged; // => 2
purge.clear();
purge.value; // => []
purge._purged; // => 0
```
Returns `undefined`
### Properties
#### AutoPurge.length
**Type:** Number (getter)
The total length of the array.
#### AutoPurge.value
**Type:** Array (getter)
Returns the purgable array.
#### AutoPurge.maxlength
**Type:** Number
The configuration maxlength for the array.
#### AutoPurge._store
**Type:** Array
Reference to the purgable array.
#### AutoPurge._purged
**Type:** Number
The total items that have been purged from the array.
---
## TODO
* Make the array observable when it's no longer "hacky" to do so.
## Contributing
Want to fix a bug or implement a new feature? Submit a pull request! Before you submit the request, please follow the guidelines below:
* If you implement a new feature, write the test case for it.
* Make sure all tests pass.
* Build the minified version using grunt.
* If bumping version, update `package.json`, `bower.json` and the JS file.
## License
Licensed under MIT.