<commit_before># Referencejs [![Build Status](https://travis-ci.org/mindblight/referencejs.svg?branch=master)](https://travis-ci.org/mindblight/referencejs)

Referencejs manages references to values in plain JS or [Immutable](https://facebook.github.io/immutable-js/) objects. You can use this to:

1. Easily manage complex denormalized, without needing an explicited schema
3. referencing data that doesn't exist yet (e.g. async data)
4. normalize and denormalize immutable data

## A Basic Example

```js
import {
  createReference,
  resolveReference,
  dereference,
} from 'referencejs';

const user = {
  id: 'abc',
  name: '<NAME>'
};
const reference = createReference('users', user.id);

let store = {};
store = resolveReference(store, reference, user);

dereference(store, reference) === user;
```

## dereferencing using `smartDereference`
Dereferencing one reference at a time isn't that useful. `smartDereference` dereferences
every reference in an object. This is useful if you have data structures that differ
significantly from your store

```js
import {
  createReference,
  smartDereference,
} from 'referencejs';

const store = {
  users: {
    user1: {
      name: '<NAME>'
    },
    user2: {
      name: '<NAME>'
    },
    user3: {
      name: '<NAME>'
    },

    user4: {
      name: '<NAME>'
    }
  }
};

const john = createReference(['users', 'user1']);
const jane = createReference(['users', 'user2']);
const billy = createReference(['users', 'user3']);
const lucy = createReference(['users', 'user4']);

const familyTreeReferences = {
  father: john,
  mother: jane,
  children: [billy, lucy]
};

// familyTree will contain the user objects instead of the references  
const familyTree = smartDereference(store, familyTree);
```

## Plain vs. Immutable
Referencejs implements the same API for both Plain JS and [Immutable](https://facebook.github.io/immutable-js/) objects.
Read full [API](docs/README.md) docs.

## What's a Reference?
A reference is an object that contains everything needed to find a value in a JSON object (called the store).
The signature looks like:

    {
      path : Array<number|string>
    }<commit_msg>Updated README.md with docs/ references<commit_after># Referencejs [![Build Status](https://travis-ci.org/mindblight/referencejs.svg?branch=master)](https://travis-ci.org/mindblight/referencejs)

Referencejs manages references to values in plain JS or [Immutable](https://facebook.github.io/immutable-js/) objects (called stores). You can use this to:

1. Easily manage complex denormalized, without needing an explicited schema
2. referencing data that doesn't exist yet (e.g. async data)
3. normalize and denormalize immutable data
4. Lazily denormalize stored data


## Getting Started
Install the library
```sh
npm install --save referencejs
```

Update a Plain store
```js
import { createReference, resolveReference, dereference } from 'referencejs';
const jon = {
  id: 'user_1',
  name: '<NAME>',
  email: '<EMAIL>'
};
const jonRefrence = createReference('auth', 'users', jon.id);

let store = {};
store = resolveReference(store, jonReference, jon);

dereference(store, jonRefrence) === jon;
```

Or use immutable if that's your jam

```js
import { Map, is } from 'immutable';
import { createReference, resolveReference, dereference } from 'referencejs/immutable';
const jon = Map({
  id: 'user_1',
  name: '<NAME>',
  email: '<EMAIL>'
});
const jonRefrence = createReference('auth', 'users', jon.id);

let store = Map();
store = resolveReference(store, jonReference, jon);

is(dereference(store, jonRefrence), jon);
```

## More Advanced: `smartDereference`
Dereferencing one reference at a time can be painful.
`smartDereference` scans an object or array and dereferences every reference it finds

```js
import {
  createReference,
  smartDereference,
} from 'referencejs';

const store = {
  users: {
    user1: {
      name: '<NAME>'
    },
    user2: {
      name: '<NAME>'
    },
    user3: {
      name: '<NAME>'
    },

    user4: {
      name: '<NAME>'
    }
  }
};

const john = createReference(['users', 'user1']);
const jane = createReference(['users', 'user2']);
const billy = createReference(['users', 'user3']);
const lucy = createReference(['users', 'user4']);

const familyTreeReferences = {
  father: john,
  mother: jane,
  children: [billy, lucy]
};

// familyTree will contain the user objects instead of the references  
const familyTree = smartDereference(store, familyTree);
```

## Like what you see?
- [Read the docs](docs/README.md)
{'fraction_non_alphanumeric': 0.13373121131741822, 'fraction_numerical': 0.005526083112290009, 'mean_word_length': 4.36773428232503, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 17, 'https://': 7, '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': '3326001', 'n_tokens_mistral': 1421, 'n_tokens_neox': 1376, 'n_words': 450}