terkelg / zet

Set() as it should be.

JavaScript Set() as it should be.

ECMAScript 6 sets have no methods for computing the union (∪), intersection (∩) or difference (⊖). Zet is an extension of ES6 Set and comes with all its functionality included with extra set logic. The API is similar to how sets work in Python.

Features

Additions to the default ECMAScript 6 set

• Union (∪)
• Intersection (∩)
• Difference/subtract (-)
• Symmetric difference (⊖)
• Subset (⊆)
• Superset (⊇)
• Map
• Filter
• Reduce

Additionally, this module is delivered as:

• ES Module: dist/zet.mjs
• CommonJS: dist/zet.js
• UMD: dist/zet.umd.js

Install

$ npm install --save zet

Usage

import Zet from 'zet';

let a = new Zet([1, 2, 3]);
let b = new Zet([3, 4, 5]);
let c = new Zet([2, 3, 4]);

Zet.union(a, b);
//=> [Zet] {1, 2, 3, 4, 5}

a.union(b, c);
//=> [Zet] {1, 2, 3, 4, 5}

a.intersection(b);
//=> [Zet] {3}

a.symmetricDifference(c);
//=> [Zet] {1, 4}

a.subset(b);
//=> false

a.filter(i => i % 2);
//=> [Zet] {1, 3}

API

Zet([iterable])

Returns:Zet

Returns the Zet instance.

Zet extends Set() and inherit all its functionality, like has(), size() etc.

Zet.union(...sets) ∪

Returns:zet

Static variadic function that return a new set with elements from all other sets.

sets

Type: Zet|Set

Two or more sets of type Zet or Set.

Zet.intersection(...sets) ∩

Returns:zet

Static variadic function that return a new set with elements common to this and all other sets.

sets

Type: Zet|Set

Two or more sets of type Zet or Set.

Zet.difference(...sets) - or \

Returns:zet

Returns the difference between two or more sets. The order of the sets matters. Sets are differentiated against the first argument/set.

sets

Type: Zet|Set

Two or more sets of type Zet or Set.

Zet.symmetricDifference(setA, setB) ⊖ or ∆

Returns:zet

Static function that return a new set with elements in either setA or setB but not both.

setA

Type: Zet|Set

Set A of type Zet or Set.

setB

Type: Zet|Set

Set B of type Zet or Set.

Zet.subset(setA, setB)

Returns: Boolean

Test whether every element in setB is in setA.

setA

Type: Zet|Set

Set of type Zet or Set.

setB

Type: Zet|Set

Set of type Zet or Set.

Zet.superset(setA, setB)

Returns: Boolean

Test whether every element in setA is in setB.

setA

Type: Zet|Set

Set of type Zet or Set.

setB

Type: Zet|Set

Set of type Zet or Set.

map(set, func)

Returns: Zet|Set

Creates a set with the results of calling the provided function on every element.

set

Type: Zet|Set

Set of type Zet or Set.

func

Type: Function

Function that produces an element of the new set.

filter(set, func)

Returns: Zet|Set

Creates a set with all elements that pass the test implemented by the provided function.

set

Type: Zet|Set It is the set going to be examined.

func

Type: Function

It is a predicate, to test each element of the set.

reduce(set, func, initializer)

Returns: Number

Reduces the set to a single value, by executing the provided function for each element in the set (from left-to-right).

set

Type: Zet|Set

Set of type Zet or Set.

func

Type: Function

Function to be executed for each element in the set.

initializer

Type: Number

Optional. A value to be passed to the function as the initial value.

Instance Methods

union(...sets) ∪

Returns:zet

Variadic method that return a new set with elements from this and all other sets.

sets

Type: Zet|Set

One or more sets of type Zet or Set.

intersection(...sets) ∩

Returns:zet

Variadic method that return a new set with elements common to this and all other sets.

sets

Type: Zet|Set

One or more sets of type Zet or Set.

difference(...sets) - or \

Returns:zet

Variadic method tht return a new set with elements in this that are not in the other sets.

sets

Type: Zet|Set

One or more sets of type Zet or Set.

symmetricDifference(other) ⊖ or ∆

Returns:zet

Method that return a new set with elements in either this or other but not both. This is also known as xor.

other

Type: Zet|Set

Set of type Zet or Set.

subset(other)

Returns: Boolean

Test whether every element in the set is in other.

other

Type: Zet|Set

Set of type Zet or Set.

superset(other)

Returns: Boolean

Test whether every element in other is in the set.

other

Type: Zet|Set

Set of type Zet or Set.

map(func)

Returns: Zet|Set

Creates a set with the results of calling the provided function on every element.

func

Type: Function

Function that produces an element of the new set.

filter(func)

Returns: Zet|Set

Creates a set with all elements that pass the test implemented by the provided function.

func

Type: Function

It is a predicate, to test each element of the set.

reduce(func, initializer)

Returns: Number

Reduces the set to a single value, by executing the provided function for each element in the set (from left-to-right).

func

Type: Function

Function to be executed for each element in the set.

initializer

Type: Number

Optional. A value to be passed to the function as the initial value.

License

MIT © Terkel Gjervig

zet's Issues

How to export zet type back to array?

I can use the zet, now it return zet, how to export it as array?

typescript

First let me say that this is a fantastic library, and I really appreciate you making it available.

I've been poking at this with typescript and I was wondering what you level of typescript interest is? To use this library seamlessly with typescript, we need type declarations. There are several ways to handle this.

Firstly you need types, that would be an index.d.ts file like this:

export default class Zet<T> extends Set<T> {
    static union<T>(...sets: Set<T>[]): Zet<T>;
    static intersection<T>(...sets: Set<T>[]): Zet<T>;
    static difference<T>(...sets: Set<T>[]): Zet<T>;
    static symmetricDifference<T>(setA?: Zet<T>, setB?: Zet<T>): Zet<T>;
    static subset<T>(setA: Set<T>, setB: Set<T>): boolean;
    static superset<T>(setA: Set<T>, setB: Set<T>): boolean;
    static map<T>(set: Set<T>, func: (value: T, index?: number, array?: T[]) => unknown): Zet<unknown>;
    static filter<T>(set: Set<T>, func: (value: T, index?: number, array?: T[]) => unknown): Zet<T>;
    static reduce<T>(set: Set<T>, func: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => any, initializer?: any): T;
    union(...sets: Set<T>[]): Zet<T>;
    intersection(...sets: Set<T>[]): Zet<T>;
    difference(...sets: Set<T>[]): Zet<T>;
    symmetricDifference(other?: Zet<T>): Zet<T>;
    subset(other: Set<T>): boolean;
    superset(other: Set<T>): boolean;
    map(func: (value: T, index?: number, array?: T[]) => unknown): Zet<unknown>;
    filter(func: (value: T, index?: number, array?: T[]) => unknown): Zet<T>;
    reduce(func: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => any, initializer?: any): T;
}

There are a number of ways to handle this.

1. We could just add this to this repo and add them to the build. I'll admit that I don't know rollup and completely failed to work out how to get this added to the build correctly.
2. I could submit the types to DefinintelyTyped - this is the main repo for third party types. This requires no changes in this repo, but adds another dependency for library users.
3. I've already ported the whole library over to typescript, mostly because I was curious and it helped me understand the code better. It was pretty quick and painless, having good tests helped immensely here. If you were interested I could just submit a PR for all of this, but since it's quite the change, I figured I'd see if you were interested in this before pushing ahead.
4. I could just create a separate ts-zet library. Honestly I'm not sure if this is worth it. It does make maintaining the types trivial, since they end out being in lockstep with the code, and any signature changes there (likely around the generics) would just flow though, but since there's no functional change, and honestly, very little code change, I don't know if it adds any value.

FYI the only significant change in the code other than adding types was replacing the spread operator with Array.from since typescript doesn't support spreading Sets.

Thoughts?

Map, Filter, and Reduce

I’ve always thought it would be quite useful to have these array methods. Map and filter would return sets.