TwiceJS
Manage duplicates, count item occurences, dedupe an Array, in an easy way.
Getting started
Installation
To install TwiceJS, you just have to download TwiceJS.min.js
in the dist
folder and add a script into your HTML page :
<script src="path/to/TwiceJS.min.js"></script>
Or, if you prefer, you can use TwiceJS via NPM (or Yarn) :
# Use with npm
$ npm install --save @betaweb/twicejs
# Use with yarn
$ yarn add @betaweb/twicejs
Basic usage
There are several ways uo use TwiceJS, as you can see in the examples below.
const iterable = [{id: 1}, {id: 1}, {id: 2}, {id: 1}, {id: 3}, {id: 3}]
/* .: Instanciate via TwiceJS class :. */
let set = new TwiceJS()
set.append(iterable)
// OR
/* .: With Array prototype property `dedupe` :. */
arr.dedupe()
// it instanciates twiceJs under the hood, and exposes the instance in `twiceJs` property
let set = arr.twiceJs
The main TwiceJS purpuse is to dedupe a collection, and especially an objects collection. You can get the deduped collection with the .entries
getter.
// dedupe entries
console.log(set.entries)
// > [{"id":1},{"id":2},{"id":3}]
You can also dedupe a collection, and get the count of occurrences for each entry with the .withCount
getter.
// dedupe entries with occurences count
console.log(set.withCount)
// > [{"id":1,"_count":3},{"id":2,"_count":1},{"id":3,"_count":2}]
The key
_count
can be set by modifying thecount_key
option in TwiceJS's options object passed in parameter on instanciation.
Now, let see how handle the created collection with TwiceJS.
There are three methods availables with TwiceJS : append
, replace
and remove
.
// Removes all occurrences of `{id: 1}` on the collection
set.remove({id: 1})
console.log(set.withCount)
// > [{"id":2,"_count":1},{"id":3,"_count":2}]
// Appends an entry
set.append({ id: 2 })
console.log(set.withCount)
// > [{"id":3,"_count":2},{"id":2,"_count":2}]
// Replaces all occurrences of `{id: 2}` by `{id: 7}`
set.replace({ id: 2 }, { id: 7 })
console.log(set.withCount)
// > [{"id":3,"_count":2},{"id":7,"_count":2}]
Methods & events
Methods
TwiceJS.append(item: Array|Object[]|any
): TwiceJS
Appends an item or a list of items on current collection.
const dataset = new TwiceJS
const item = {id: 4}
dataset.append(item)
// > [{id: 4}]
// OR
const items = [{id: 4}, {id: 4}, {id: 3}]
dataset.append(items)
// > [{id: 4}, {id: 4}, {id: 3}]
TwiceJS.replace(oldItem: any
,newItem: any
): TwiceJS
Replace an item on current collection.
const data = [{id: 4}, {id: 4}]
const dataset = (new TwiceJS)
.append(data)
const oldItem = {id: 4}
const newItem = {id: 5}
dataset.replace(oldItem, newItem)
// > [{id: 5}, {id: 5}]
TwiceJS.remove(item: Array|Object[]|any
): TwiceJS
Remove an item or a list of items on current collection.
const data = [{id: 4}, {id: 4}, {id: 5}]
const dataset = (new TwiceJS)
.append(data)
const item = {id: 4}
dataset.remove(item)
// > [{id: 5}]
TwiceJS.isEmpty(): Boolean
Returns true if the collection is empty, false otherwise.
const data = [{id: 4}, {id: 4}]
const dataset = (new TwiceJS)
.append(data)
const item = {id: 4}
dataset.remove(item)
dataset.isEmpty() // true
TwiceJS.clear(): TwiceJS
Clear the collection
const data = [{id: 4}, {id: 4}, {id: 5}]
const dataset = (new TwiceJS)
.append(data)
dataset.clear()
dataset.isEmpty() // true
TwiceJS.has(item: Array|Object[]|any
): Boolean
Returns true if the collection contains the searched entry, false otherwise.
const data = [{id: 4}, {id: 4}, {id: 5}]
const dataset = (new TwiceJS)
.append(data)
dataset.has({id: 4}) // true
dataset.has({id: 7}) // false
TwiceJS.occurrence(item: Array|Object[]|any
): Number
Get an entry occurrences count.
const data = [{id: 4}, {id: 4}, {id: 5}]
const dataset = (new TwiceJS)
.append(data)
dataset.occurrence({id: 4}) // 2
dataset.occurrence({id: 7}) // 0
TwiceJS.encode(item: Array|Object[]|any
): String
Encode an entry according the defined key_encoder
option.
const dataset = new TwiceJS({
key_encoder: TwiceJS.ENCODERS.BASE_64
})
dataset.encode({id: 4}) // eyJpZCI6NH0=
TwiceJS.decode(item: String
): any
Decode an entry according the defined key_encoder
option.
const dataset = new TwiceJS({
key_encoder: TwiceJS.ENCODERS.BASE_64
})
const base64_str = dataset.encode({id: 4}) // eyJpZCI6NH0=
dataset.decode(base64_str) // {id: 4}
Todo
- [x] Add keyify option choice : JSON or base64.
- [ ] Add
.increment(<item>)
(alias of.append(<items>)
) and.decrement(<item>)
(alias of.delete(<item>)
) methods which adds or removes only one occurrency of an entry on the collection, and increment or decrement his count. - [ ] Rewrite TwiceJS class with TypeScript.
- [ ] Add unit tests.