Nourished Personal Mucus

    canonical-instance

    2.0.0 • Public • Published

    canonical-instance

    A Javascript library that reduces the need for deepEquals by simply producing a canonical instance for all extensionally equivalent values.

    Use Cases

    Wouldn't it be nice if === worked like deepEquals? It would simplify alot of testing at the least. Well, === would work like deepEquals if Javascript gave us the same instance for objects that were deepEquals in the first place.

    For instance, suppose we had a function canonical:

    var a = { a: 1 };
    var b = { a: 1 };
     
    canonical(a) === canonical(b); // True!

    Well, canonical-instance provides just that functionality!

    import { canonical } from "canonical-instance";

    It also provides its internal bisect method used for efficient object lookup in a sorted array.

    import { bisect } from "canonical-instance";

    It Works Recursively!

    It's worth noting that the return value from canonical will never be the same instance as the object passed in.

    var a = { a: 1 };
    var b = { a: 1 };
     
    canonical(a) === canonical(b); // True!
    === canonical(a); // False!
    === canonical(b); // False!

    That's because the objects need to be reconstructed such that inner properties are also canonical! Check this out:

    var a = { b: [ {c: {}, d: {}] };
    var b = { b: [ {c: {}, d: {}] };
     
    canonical(a.b[0].d) === canonical(b).b[0].c; // True!

    Limitations

    Of course, the canonical(a) and canonical(b) are only safe if you are not mutating either of a, b, or canonical's result, so make sure you are accessing these objects in a read only way.

    canonical works well with Number, String, Boolean, Array, Date, and plain Objects as you might expect. Notably, however, strings that are created with the new String() constructor are treated as unique instances due to the special case of these values. But really, you should probably never be doing this.

    For functions, it considers every function completely unique (thus having no extensionality), and thus returns the value passed to canonical every time.

    For Objects that contain dynamic properties or prototypes, canonical only cares about the iterable properties returned from Object.keys for the purpose of extensional equality.

    Install

    npm i canonical-instance

    DownloadsWeekly Downloads

    0

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    10.3 kB

    Total Files

    6

    Last publish

    Collaborators

    • corps