<commit_before>

- [jsoid](#jsoid)
	- [Motivation](#motivation)
	- [Usage](#usage)
	- [Source](#source)

> **Table of Contents**  *generated with [DocToc](http://doctoc.herokuapp.com/)*


# jsoid

`jsoid` provides unique Object IDs for NodeJS (io.js at this time, really).

## Motivation

When comparing classical JavaScript to a language like Python, there are (among many others)
two things that JavaScript lacks and for which workarounds are sometimes necessary:

* Classical JS has no concept of a 'unique Object ID' (OID).
* Classical JS has no true Maps; you only get objects which accept strings as keys;
* Classical JS has no Weak Maps, meaning when you have to cache objects, you must
	always make sure to appropriately clear the cache when objects get out of scope.
* Because classical JS has only strings as keys, there are quite a few opportunities for
	key collsions in case you're not careful (i.e. `x[ '123' ]` shadows `x[ 123 ]`,
	`x[ 'NaN' ] shadows `x[ 0 / 0 ]` and so on).
* Because classical JS has only strings as keys, it is somewhat hard to tack private attributes
	such as `x.__FOOBAR_ID` to objects; in the general case, you should make those keys
	non-iterable in the general case (which has only been possible at all for a few years).
* Because classical JS has no OIDs, it is hard to efficiently look into a given cache or somesuch
	collection for the existence of a given object; an easy way to achieve that is to put
	everything in an array and then query for `cache.indexOf( x )`, but that isn't bound to scale
	very well (and is prone to leak memory).

All this has quite recently changed; for NodeJS people, the most obvious change is
the release of [io.js](https://iojs.org/) in January 2015, which out-of-the-box provides
ES6 Symbols, Maps, Sets, WeakMaps, generators / `yield`, you name it.

> For a quick-and-easy instruction how to install the latest `iojs` binary on your
> machine, have a look at my [how-to](https://github.com/loveencounterflow/how-to).

It turns out that Symbols, Maps, Sets, WeakMaps have some amount of overlap in their
features that make all of the above tasks a lot easier. `jsoid` uses ES6 WeakMaps
to implement efficient, memory-safe, bijective, non-obstrusive Object IDs that can readily
be used as string values for your favorite object collection. Because 'primitive'
values (numbers, strings, true, NaN, ...) are supported, you should never have to care
about the type of the values when using `jsoid`.

## Usage

Install as `npm install --save jsoid`.

**Be aware that this is not a mature module; i just slapped something together that seems
to work with a tiny test (run `node --harmony jsoid/index.js` or, better still, `iojs jsoid/index.js`;
if you get no output, the tests have passed).**

From with your module, use

```js
var jsoid = require( 'jsoid' )();
var d = {};
var e = {};
console.log( jsoid( d ) );
console.log( jsoid( e ) );
console.log( jsoid( 42 ) );
console.log( jsoid( 42 ) );
console.log( jsoid( 'helo' ) );
console.log( jsoid( 'helo!' ) );
```

to see the generated OIDs; you should get something like:

```js
o#0
o#1
n#42
n#42
t#c6efaf27673d
t#8e95a23efc4e
```

Basically, that's a running ID for objects, and some kind of stringification for
primitive values. Ah yes, and the IDs are all (short) strings, because with the
more traditional numerical IDs, it's obviously logically impossible to represent all
of JS numbers and all the other possible values uniquely; only strings can do that, and
only strings can act as object keys, so there's an added value there.

As it stands, each call to `require( 'jsoid' )` will return a new
instance of a OID-generating function; that function will generated unqiue IDs that
are consistent with the IDs of all other instances of the `jsoid` function, but
since a simple counter is used in the case of objects, you must make sure to use only
one and the same `jsoid` function for all your IDs. I'm willing to look into ways to fix that,<commit_msg>autocommit<commit_after>

- [jsoid](#jsoid)
	- [Motivation](#motivation)
	- [Usage](#usage)
	- [Source](#source)

> **Table of Contents**  *generated with [DocToc](http://doctoc.herokuapp.com/)*


# jsoid

`jsoid` provides unique Object IDs for NodeJS (io.js at this time, really).

## Motivation

When comparing classical JavaScript to a language like Python, there are (among many others)
two things that JavaScript lacks and for which workarounds are sometimes necessary:

* Classical JS has no concept of a 'unique Object ID' (OID).
* Classical JS has no true Maps; you only get objects which accept strings as keys;
* Classical JS has no Weak Maps, meaning when you have to cache objects, you must
	always make sure to appropriately clear the cache when objects get out of scope.
* Because classical JS has only strings as keys, there are quite a few opportunities for
	key collsions in case you're not careful (i.e. `x[ '123' ]` shadows `x[ 123 ]`,
	`x[ 'NaN' ] shadows `x[ 0 / 0 ]` and so on).
* Because classical JS has only strings as keys, it is somewhat hard to tack private attributes
	such as `x.__FOOBAR_ID` to objects; in the general case, you should make those keys
	non-iterable in the general case (which has only been possible at all for a few years).
* Because classical JS has no OIDs, it is hard to efficiently look into a given cache or somesuch
	collection for the existence of a given object; an easy way to achieve that is to put
	everything in an array and then query for `cache.indexOf( x )`, but that isn't bound to scale
	very well (and is prone to leak memory).

All this has quite recently changed; for NodeJS people, the most obvious change is
the release of [io.js](https://iojs.org/) in January 2015, which out-of-the-box provides
ES6 Symbols, Maps, Sets, WeakMaps, generators / `yield`, you name it.

> For a quick-and-easy instruction how to install the latest `iojs` binary on your
> machine, have a look at my [how-to](https://github.com/loveencounterflow/how-to).

It turns out that Symbols, Maps, Sets, WeakMaps have some amount of overlap in their
features that make all of the above tasks a lot easier. `jsoid` uses ES6 WeakMaps
to implement efficient, memory-safe, bijective, non-obstrusive Object IDs that can readily
be used as string values for your favorite object collection. Because 'primitive'
values (numbers, strings, true, NaN, ...) are supported, you should never have to care
about the type of the values when using `jsoid`.

## Usage

Install as `npm install --save jsoid`.

**Be aware that this is not a mature module; i just slapped something together that seems
to work with a tiny test (run `node --harmony jsoid/index.js` or, better still, `iojs jsoid/index.js`;
if you get no output, the tests have passed).**

From with your module, use

```js
var jsoid = require( 'jsoid' )();
var d = {};
var e = {};
console.log( jsoid( d ) );
console.log( jsoid( e ) );
console.log( jsoid( 42 ) );
console.log( jsoid( 42 ) );
console.log( jsoid( 'helo' ) );
console.log( jsoid( 'helo!' ) );
```

to see the generated OIDs; you should get something like:

```js
o#0
o#1
n#42
n#42
t#c6efaf27673d
t#8e95a23efc4e
```

Basically, that's a running ID for objects, and some kind of stringification for
primitive values. Ah yes, and the IDs are all (short) strings, because with the
more traditional numerical IDs, it's logically inconceivable to represent *both* all
JS numbers *and* all the other possible values uniquely; only strings can do that, and
only strings can act as object keys, so there's an added value there.

As it stands, each call to `require( 'jsoid' )` will return a new
instance of a OID-generating function; that function will generated unqiue IDs that
are consistent with the IDs of all other instances of the `jsoid` function, but
since a simple counter is used in the case of objects, you must make sure to use only
one and the same `jsoid` function for all your IDs. I'm willing to look into ways to fix that,
{'fraction_non_alphanumeric': 0.08492462311557789, 'fraction_numerical': 0.009045226130653266, 'mean_word_length': 4.230617608409987, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 9, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1474629', 'n_tokens_mistral': 2467, 'n_tokens_neox': 2305, 'n_words': 1228}