# q-local

> Fork of Q which allows easy sharing of data between promises as long as they are part of the same promise chain or any of its subchains

Latest version **1.2.0** (published 2015-04-14) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install q-local
pnpm add q-local
yarn add q-local
bun add q-local
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2015-04-14 |
| First published | 2014-08-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=0.6.0 |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Aleksi Asikainen |
| Maintainers | franksrevenge |
| Keywords | q, local, context, data, promise, promises, promises-a, promises-aplus, deferred, future, async, flow control, fluent, browser, node |

## Links

- npm: https://www.npmjs.com/package/q-local
- Repository: https://github.com/franksrevenge/q-local
- Issues: http://github.com/kriskowal/q/issues
- npm.io page: https://npm.io/package/q-local

## Alternatives

- [apollo-link-http-common](https://npm.io/package/apollo-link-http-common.md) — 879.0K weekly downloads
- [react-relay](https://npm.io/package/react-relay.md) — 336.8K weekly downloads
- [relay-test-utils](https://npm.io/package/relay-test-utils.md) — 181.6K weekly downloads
- [@vendure/core](https://npm.io/package/@vendure/core.md) — 14.8K weekly downloads
- [@pnpm/deps.graph-sequencer](https://npm.io/package/@pnpm/deps.graph-sequencer.md) — 13.4K weekly downloads

## Recent versions

- 1.2.0 (latest) — 2015-04-14
- 1.0.1-2 — 2014-09-15
- 1.0.1 — 2014-08-21

## README

# Q with local data context

This is a fork of Kristopher Kowal's [Q](https://github.com/kriskowal/q) with
one difference -- this version of the library allows data to be shared easily
between promises, as long as they are part of the same promise chain or any 
of its subchains.


## Why not use function scope?

Function scope is a great approach when your code allows it. For example:

```javascript
function run()
{
    var myVariable;
    
    Q(true)
    .then(function() {
        return Q(true)
        .then(function() {
            myVariable = 12;
        });
    })
    .then(function() {
        return Q(true)
        .then(function() {
            console.log(myVariable) // outputs "12"
        });
    });
}
```

That works brilliantly. However, function scope is not always available. Consider
the following:

```javascript
var ClassA = function() {};

ClassA.prototype.setVariable = function() {
    return function() {
        return Q(true)
        .then(function() {
            myVariable = 12; // Undefined variable error
        });
    };
};

module.exports = ClassA;
```

```javascript
var ClassB = function() {};

ClassB.prototype.logVariable = function() {
    return function() {
        return Q(true)
        .then(function() {
            console.log(myVariable); // Undefined variable error
        });
    };
};

module.exports = ClassB;
```

```javascript
var ClassA = require('./class-a'),
    ClassB = require('./class-b');

function run2()
{
    var myVariable,
        a = new ClassA(),
        b = new ClassB();

    Q(true).then(a.setVariable()).then(b.logVariable());
}
```

Since `setVariable()` and `logVariable()` do not share context with `run()`,
`myVariable` will remain undefined within `ClassA` and `ClassB`.


## Why not pass variables as function arguments?

Standard approach to fix the code above would be to pass `myVariable` to
the objects eiter as an argument in the function calls or in their constructors.
This  works well, provided that you have access to the variable(s) _at all times when
you need to use them_. However, it also forces you to pass the variables to
different parts of your chain, and may even force you to pass the variables through
chains that have nothing to do with your variables just so that you can get to
the variables at the parts where they are needed.

When dealing with long promise chains and, particularly, subchains generated by
code in multiple modules, passing variables down the promise chains gets very
cumbersome and increases the likelihood of human error, as accidentally omitting
one variable from being passed will fail all downstream parts of the chain relying
on that variable.


## Is there a better approach?

If you are dealing with relatively simple promise chains, the two strategies
described above should satisfy your needs, despite their limitations.

The local data context is a solution for complex promise chains, in
which isolated promises in the same chain (or in separate subchains which are connected
through a superchain) need to share data between each other.

Instead of forcing developers to pass arguments through the chain manually,
Q-Local introduces an new function `promise.local(function(localData) {})`, which shares
the `localData` object across all members of the promise chain and subchains.

Note that unconnected chains will not share the same `localData` object -- each
unconnected chain will have its own `localData` object.

### Setting values
```javascript
Q(true)
.local(function(localData) {
    localData.myVariable = 1001;
});
```

### Getting values
```javascript
Q(true)
.local(function(localData) {
    // (Will print out 'undefined', unless connected to the previous chain, of course)
    console.log(localData.myVariable);
});
```


### Previous examples in local data flavor

Function context:

```javascript
function run()
{
    var myVariable;
    
    Q(true)
    .then(function() {
        return Q(true)
        .local(function(localData) {
            localData.myVariable = 12;
        });
    })
    .then(function() {
        return Q(true)
        .local(function(localData) {
            console.log(localData.myVariable); // outputs "12"
        });
    });
}
```

Modules:

```javascript
var ClassA = function() {};

ClassA.prototype.setVariable = function() {
    return function() {
        return Q(true)
        .local(function(localData) {
            localData.myVariable = 12;
        });
    };
};

module.exports = ClassA;
```

```javascript
var ClassB = function() {};

ClassB.prototype.logVariable = function() {
    return function() {
        return Q(true)
        .local(function(localData) {
            console.log(localData.myVariable);
        });
    };
};

module.exports = ClassB;
```

```javascript
var ClassA = require('./class-a'),
    ClassB = require('./class-b');

function run2()
{
    var myVariable,
        a = new ClassA(),
        b = new ClassB();

    Q(true).then(a.setVariable()).then(b.logVariable());
}
```


## API Reference

### promise.local(onAccess)

Exposes the shared local data object to `onAccess` function. The local data object will be passed
as the first argument of the function call.

```javascript
function onAccess(localData) {}
```

Any changes to the _properties_ of localData will be automatically shared with other
accessors. Note that changing the `localData` object itself (e.g. `localData = {};`)
will not have any effect outside of `onAccess` function.

The return value of `onAccess` will be treated as if it was `promise.then(onAccess, null, null)`.

Execution order behaves the same way than `promise.then(onAccess, null, null)`


## License
Changes in Q Local are copyright 2014-2015 Aleksi Asikainen.

Q is Copyright 2009–2015 Kristopher Michael Kowal.

MIT License (enclosed)

---
_Source: https://npm.io/package/q-local · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._