immutable-ai

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
• Immutable Core Component
• Immutable Core Model
• Immutable Core Task
• Immutable HTTP Client

Immutable AI is integrated with 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(...)