npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

define-operator

v0.0.5

Published

In some situations operator overloading can result in code that's easier to write and easier to read.

Downloads

4

Readme

Operator Overloading

In some situations operator overloading can result in code that's easier to write and easier to read.

without overloading

let u = new Vector(1, 0);
let v = new Vector(2, -1);

let w = u.add(v);
w = w.plus(v.scale(3));

with overloading

let u = new Vector(1, 0);
let v = new Vector(2, -1);

let w = u + v;
w += 3 * v;

Function.defineOperator

Binary operators are defined as follows:

Function.defineOperator(
    '+',
    [Vector, Vector],
    (u, v) => new Vector(u.x + v.x, u.y + v.y)
);

Unary operators are defined as follows:

Function.defineOperator(
    '-',
    [Vector],
    (v) => new Vector(-v.x, -v.y)
);

Notes:

  • Commutative operators, +, *, &&, ||, &, |, ^, automatically flip the order of operands when their types are different.

  • Function.defineOperator(T == T, (a, b) => fn(a, b) will automatically define != as (a, b) => !fn(a, b).

  • ! and != cannot be overloaded in order to perserve identities:

    X ? A : B <=> !X ? B : A
    !(X && Y) <=> !X || !Y
    !(X || Y) <=> !X && !Y
    X != Y    <=> !(X == Y)

    Source: http://www.slideshare.net/BrendanEich/js-resp (page 7)

  • > and >= are derived from < and <= as follows:

    A > B     <=> B < A
    A >= B    <=> B <= A

    Source: http://www.slideshare.net/BrendanEich/js-resp (page 8)

  • Redefining some operators on some built-in types is prohibited. The reason being that operator overloading should be used to make classes that don't have operator support easier to work with and prevent changing behavior of those classes do that.

    • all operators on [Number, Number]
    • logical operators on [Boolean, Boolean]
    • + on [String, String]
    • unary + and - on [Number]

'use overloading' directive

The 'use overloading' directive can be used to limit the scope of overloading can be used. This directive is opt-in because for existing code it will have negative performance impacts. In general, overloading should be used where readability is more important that performance.

It can be used at the start of a file or function/method definition. The @operator section has an example of the 'use overloading' directive in action.

@operator decorator

The @operator decorator is a convenience for declaring methods as operators when defining a class.

class Vector {
    constructor(x, y) {
        Object.assign(this, { x, y });
    }

    @operator('+')
    add(other) {
        return new Vector(this.x + other.x, this.y + other.y);
    }

    @operator('-')
    neg() {
        return new Vector(-this.x, -this.y);
    }

    @operator('-')
    sub(other) {
        'use overloading';
        return this + -other;
    }

    @operator('*', Number)
    scale(factor) {
        return new Vector(factor * this.x, factor * this.y);
    }
}

The @operator decorator makes the assumption that both operands are the same type as the class. If this is not the case, the type of the other operand can be specified as the second parameter to @operator.

Implementation Details

The following code:

'use overloading'

let u = new Vector(1, 0);
let v = new Vector(2, -1);

let w = u + v;
w += 3 * v;

relies one the following operators to be defined:

Function.defineOperator(Vector + Vector,
    (u, v) => new Vector(u.x + v.x, u.y + v.y);

Function.defineOperator(Number * Vector, (k, v))

and compiles to:

let u = new Vector(1, 0);
let v = new Vector(2, -1);

let w = Function[Symbol.plus](u, v);
w = Function[Symbol.plus](w, Function[Symbol.times](3, v));

The implementation defines the following well-known Symbols:

Binary Operators

  • Symbol.plus +
  • Symbol.minus -
  • Symbol.times *
  • Symbol.divide /
  • Symbol.remainder %
  • Symbol.equality ==
  • Symbol.inequality !=
  • Symbol.lessThan <
  • Symbol.lessThanOrEqual <=
  • Symbol.greaterThan >
  • Symbol.greaterThanOrEqual >=
  • Symbol.shiftLeft <<
  • Symbol.shiftRight >>
  • Symbol.unsignedShiftRight >>>
  • Symbol.bitwiseOr |
  • Symbol.bitwiseAnd &
  • Symbol.bitwiseXor ^
  • Symbol.logicalOr ||
  • Symbol.logicalAnd &&

Unary Operators

  • Symbol.unaryPlus +
  • Symbol.unaryMinus -
  • Symbol.bitwiseNot ~

Note: only the following operators can actually be overloaded: |, ^, &, ==, <, <=, <<, >>, >>>, +, -, *, /, %, ~, unary-, and unary+

Function Lookup

The functions for each operator are stored in a lookup table. When a call to Function.defineOperator is made, we get the prototype for the types of the arguments. The prototypes are stored in a protoypes array the index of the prototype from that array is used to determine the key in the lookup table.

In the case of unary operators the index is the key. For binary operators, the index is a string with the two indices separate by commas.

TODO: describe how prototype chain support works.

Future Work

  • [x] handle prototype chain
  • [ ] support exponentiation operator
  • [ ] use static type information to improve performance (could determine which function to call at compile time)