Skip to content

Latest commit

 

History

History
123 lines (78 loc) · 4.31 KB

README.md

File metadata and controls

123 lines (78 loc) · 4.31 KB
Raw

Javascript Set Extensions

Polyfill for extending the Javascript Set class in order to support properties and operations from basic set theory.

Test suite CodeQL Semantic Analysis Project Status: Active – The project has reached a stable, usable state and is being actively developed. JavaScript Style Guide npm bundle size GitHub

Scope

Please read this first, to a get a better understanding, whether this package suits your needs.

Completeness vs. Performance

Focus of this package is to provide a Set implementation, which can be used in context of axiomatic set theory.

Set's class Methods are primarily designed to

  • run with any values, but also values as Sets (of Sets, arbitrary depth)
  • work with arbitrary (but finite) numbers of sets (depending on operation, see documentation)
  • conform with their respective properties (Associative, Commutative etc.)
  • don't mutate any of the given but return a new Set as result

Set's prototype Methods are in contrast designed to work as a binary operation on the current instance but they also won't mutate any of the involved Sets.

Some algorithms may grow exponentially with a raising number of sets to be processes. Please, see the documentation notes on the respective methods.

Extending Set

This package builds upon the Set implementation, instead of providing an own. Some suggest it's bad design to extend core implementations.

However, the core functionality of Set is stable and proven and this package tries to be minimally invasive on the Set implementation.

Please, leave an issue, in case this extension breaks your setup by whatever unexpected or undefined behaviour.

Future Implementations

Currently, this package only supports finite sets. A future implementation could include generators to support infinite sets and function-based operations with infinite sets. Ideas.concepts and contributions are very welcomed.

Installation and Usage

Install this package as usual:

$ npm install --save set-extensions

Import this package in your startup code. The package automatically extends the global Set object.

import 'set-extensions'

You can verify the presence of this polyfill by checking for the __isExtended__ property:

Set.__isExtended__ // true if this package is installed

API Documentation

There is a markdown version and a html version of the API documentation. If you think this documentation can be improved, please leave a pull request or open an issue.

Run the tests

Add the description about testing in the README:

You can run the tests like the following:

$ cd js-set-extension/package
$ npm install

To run tests in watch mode use

$ npm run test-watch

or for a single run use

$ npm run test

The tests are written in mocha but it should not be that hard to get into it as it is written very intuitive.

Linter

Please note, that the tests are very strict about code style and you can check for code style related errors using

npm run lint

You should fix these lint errors, since the CI server will reject to run any tests when the linter as thrown an error.

You can also run lint and tests all in one process using

npm run lint-test

The scripts to run these commands are also in the package.json file:

https://github.com/jankapunkt/js-set-extension/blob/master/package/package.json

License

MIT