# immutable-ai

> Alternative interface for immutable-core

Latest version **0.9.0** (published 2023-12-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install immutable-ai
pnpm add immutable-ai
yarn add immutable-ai
bun add immutable-ai
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.9.0 |
| Published | 2023-12-15 |
| First published | 2017-02-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 29.4 KB |
| Known vulnerabilities | 0 (+3 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Ersun Warncke |
| Maintainers | ersun.warncke |

## Links

- npm: https://www.npmjs.com/package/immutable-ai
- Repository: https://github.com/warncke/immutable-ai
- Homepage: https://github.com/warncke/immutable-ai#readme
- Issues: https://github.com/warncke/immutable-ai/issues
- npm.io page: https://npm.io/package/immutable-ai

## Dependencies (2)

- [lodash](https://npm.io/package/lodash.md) 4.17.21
- [if-defined](https://npm.io/package/if-defined.md) 1.0.18

## Recent versions

- 0.9.0 (latest) — 2023-12-15
- 0.8.3 — 2018-11-17
- 0.8.2 — 2018-11-17
- 0.8.1 — 2018-01-15
- 0.8.0 — 2017-10-21
- 0.7.4 — 2017-10-06
- 0.7.3 — 2017-10-06
- 0.7.2 — 2017-10-04
- 0.7.1 — 2017-10-04
- 0.7.0 — 2017-10-01
- 0.6.2 — 2017-09-19
- 0.6.1 — 2017-09-10
- 0.6.0 — 2017-09-10
- 0.5.6 — 2017-09-04
- 0.5.5 — 2017-08-05
- … 30 more at https://npm.io/package/immutable-ai/versions

## README

# immutable-ai

Immutable AI provides a convenient object oriented facade for Immutable modules
that are functional by design and require manually passing a session object
between calls.

Immutable AI supports:

* [Immutable Core](https://www.npmjs.com/package/immutable-core)
* [Immutable Core Component](https://www.npmjs.com/package/immutable-core-component)
* [Immutable Core Model](https://www.npmjs.com/package/immutable-core-model)
* [Immutable Core Task](https://www.npmjs.com/package/immutable-core-task)
* [Immutable HTTP Client](https://www.npmjs.com/package/immutable-http-client)

Immutable AI is integrated with
[immutable-app](https://www.npmjs.com/package/immutable-app) and
Immutable Core by default so the manual configuration documented here should not
need to be used for most cases.

## Creating a new Immutable AI instance

    const ImmutableAI = require('immutable-ai')
    const ImmutableCore = require('immutable-core')
    const ImmutableCoreModel = require('immutable-core-model')
    const ImmutableHttpClient = require('immutable-http-client')

    ImmutableAI.immutableCore(ImmutableCore)
    ImmutabelAI.immutableCoreModel(ImmutableCoreModel)
    ImmutableAI.immutableHttpClient(ImmutableHttpClient)

    ImmutableCore.module('barModule', {
        bar: function (args) {
            ...
        }
    })

    ImmutableCore.module('fooModule', {})

    ImmutableCore.method('fooModule.foo', function (args) {
        // create new instance from args
        var ai = ImmutableAI(args)
        // call barModule.bar using Immutable AI
        ai.module.bar.bar()
    })

Immutable Core methods are functional and stateless which means that all of the
data they operate on must be passed in the arguments.

Typically all Immutable Core method calls must include a `session` object which
includes the state needed to provide access control.

Immutable AI provides an object oriented facade for Immutable Core that removes
the tedious, error prone, and potentially risky necessity of manually passing
session objects between Immutable method calls.

## Using Immutable AI by default

    ImmutableCore.method('fooModule.foo', function (args) {
        this.module.bar.bar()
    })

With Immutable AI integration enabled in Immutable Core every Immutable method
call will be invoked using `Function.prototype.call` with an Immutable AI
instance as the `this` arg.

The Immutable AI instance will always be identical to calling
`ImmutableAI(args)` from within the method body.

## Immutable AI namespaces

    // create a new ImmutableAI instance
    var ai = ImmutableAI({
        session: { ... }
    })

    // call foo method on fooModule
    ai.module.foo.foo(...)

    // call the list method for fooController
    ai.controller.foo.list(...)

Immutable AI provides three local name spaces for method calls: controller,
model, module.

Each namespace simply adds a postfix to the name that follows it and uses this
to lookup the correct Immutable Core module.

Immutable Core Model and Immutable Core Controller append the words 'Model' and
'Controller' to their respective names in order to form their Immutable Core
module name.

To be used with Immutable AI all other modules must be named like `fooModule`
and addressed via the `module` namespace.

## Seting a custom local namespace

    // set custom namespace with alias and module name postfix
    ImmutableAI.localNamespace('myNamespace', 'MyNamespace')

    // call fooMyNamespace.foo
    ai.myNamespace.foo.foo(...)

A namespace is defined with an alias that will be used when calling methods and
and postfix that will be appended to the module name in the call string in order
to get the full Immutable Core module name.

Both the alias and postfix must be strings with a positive length.

Errors will be thrown on attempts to create an invalid local namespace.

## Accessing ImmutableCoreModels

    // perform a select on fooModel
    ai.model.foo.select.by.id(...)

When `ai.model` is called it will return an ImmutableCoreModelLocal instance
with the session set. The ImmutableCoreModelLocal instance can then be used to
create, query, and select.

## Making HTTP requests

    ai.http.get('http://immutable.ai')

`ai.http` can be used to call any Immutable HTTP Client request method: delete,
get, post, put and request.

The arguments will be passed to the underlying Immutable HTTP Client method and
the current session object will be added if it is not set in the arguments.

## Access the session

    var session = ai.session

The session for the instance can be access via `ai.session`.

## Accessing module data

    ai.module.foo.data = {}

    var foo = ai.module.foo.data

The data for any module can be accessed from the ai instance via the module
name.

## Accessing module data in method call

    ImmutableCore.method('fooModule.foo', function (args) {
        // set data for fooModule
        this.data = {foo: true}
        // get data for fooModule
        var foo = this.data.foo
    })

In the context of a method the module data for the module that the method
belongs to can be accessed via `this.data`.

## Create a new ImmutableCoreComponentInstance

    ai.component.foo.new({...})

## Create a new ImmutableCoreTaskInstance

    ai.task.foo.new({...})
    
## Invalid calling patterns

    // create a new ImmutableAI instance
    var ai = ImmutableAI({
        session: { ... }
    })

    // THIS IS BAD!
    var module = ai.module.foo

    // this works
    module.foo(...)

    // THIS FAILS!
    module.bar(...)

The ImmutableAI proxy stores the state of each property access to set the
namespace, module, and method to call, then when the method is called the
state of the proxy is reset.

To make it simple: ALWAYS use ImmutableAI by making the entire call in a single
statement like:

    ai.module.foo.foo(...)

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