Skip to main content

Global

Methods

arrayConcatElement()

Create a new array consistent of a1 plus an additional element. Avoids the unnecessary array allocation when using a1.concat([element]).

Source:
request/complement.js, line 207

arrayConcatSlice()

Create a new array consisting of a1 + a subset of a2. Avoids allocating an extra array by calling slice on a2.

Source:
request/complement.js, line 179

arrayConcatSlice2()

Create a new array consisting of a1 + a2 + a subset of a3. Avoids allocating an extra array by calling slice on a3.

Source:
request/complement.js, line 193

findPartialIntersections()

Recursive function to calculate intersection and complement paths in 2 given pathsets at a given depth.

Parameters:

  • requestedPath: full requested path set (can include ranges)
  • optimizedPath: corresponding optimized path (can include ranges)
  • requestTree: path tree for in-flight request, against which to dedupe

Returns a 3-tuple consisting of

  • the intersection of requested paths with requestTree
  • the complement of optimized paths with requestTree
  • the complement of corresponding requested paths with requestTree

Example scenario:

  • requestedPath: ['lolomo', 0, 0, 'tags', { from: 0, to: 2 }]
  • optimizedPath: ['videosById', 11, 'tags', { from: 0, to: 2 }]
  • requestTree: { videosById: 11: { tags: { 0: null, 1: null }}}

This returns: [ [['lolomo', 0, 0, 'tags', 0], ['lolomo', 0, 0, 'tags', 1]], [['videosById', 11, 'tags', 2]], [['lolomo', 0, 0, 'tags', 2]] ]

Source:
request/complement.js, line 64

GetRequestV2(scheduler, requestQueue, attemptCount)

Creates a new GetRequest. This GetRequest takes a scheduler and the request queue. Once the scheduler fires, all batched requests will be sent to the server. Upon request completion, the data is merged back into the cache and all callbacks are notified.

Parameters:
Name Type Description
scheduler Scheduler
requestQueue RequestQueueV2
attemptCount number
Source:
request/GetRequestV2.js, line 24

RequestQueueV2(model, scheduler)

The request queue is responsible for queuing the operations to the model"s dataSource.

Parameters:
Name Type Description
model Model
scheduler Scheduler
Source:
request/RequestQueueV2.js, line 13

Type Definitions

Atom

An atom allows you to treat a JSON value as atomic regardless of its type, ensuring that a JSON object or array is always returned in its entirety. The JSON value must be treated as immutable. Atoms can also be used to associate metadata with a JSON value. This metadata can be used to influence the way values are handled.

Type:
Object
Properties
Name Type Attributes Description
$type String

the $type must be "atom"
value *

the immutable JSON value
$expires number <optional>

the time to expire in milliseconds

  • positive number: expires in milliseconds since epoch
  • negative number: expires relative to when the Atom is merged into the JSONGraph
  • number 1: never expires
Source:
typedefs/Atom.js, line 1
Example
// Atom with number value, expiring in 2 seconds
 {
    $type: "atom",
    value: 5
    $expires: -2000
 }
 // Atom with Object value that never expires
 {
    $type: "atom",
    value: {
        foo: 5,
        bar: "baz"
    },
    $expires: 1
 }

JSONEnvelope

An envelope that wraps a JSON object.

Type:
Object
Properties
Name Type Description
json JSON

a JSON object
Source:
typedefs/JSONEnvelope.js, line 1
Example
var model = new falcor.Model();
 model.set({
    json: {
      name: "Steve",
      surname: "McGuire"
    }
 }).then(function(jsonEnvelope) {
    console.log(jsonEnvelope);
 });

JSONGraph

JavaScript Object Notation Graph (JSONGraph) is a notation for expressing graphs in JSON. For more information, see the JSONGraph Guide.

Type:
Object
Source:
typedefs/JSONGraph.js, line 1
Example
var $ref = falcor.ref;
 // JSONGraph model modeling a list of film genres, each of which contains the same title.
 {
    // list of user's genres, modeled as a map with ordinal keys
    "genreLists": {
        "0": $ref('genresById[123]'),
        "1": $ref('genresById[522]'),
        "length": 2
    },
    // map of all genres, organized by ID
    "genresById": {
        // genre list modeled as map with ordinal keys
        "123": {
            "name": "Drama",
            "0": $ref('titlesById[23]'),
            "1": $ref('titlesById[99]'),
            "length": 2
        },
        // genre list modeled as map with ordinal keys
        "522": {
            "name": "Comedy",
            "0": $ref('titlesById[23]'),
            "1": $ref('titlesById[44]'),
            "length": 2
        }
    },
    // map of all titles, organized by ID
    "titlesById": {
       "99": {
            "name": "House of Cards",
            "rating": 5
        },
        "23": {
            "name": "Orange is the New Black",
            "rating": 5
        },
        "44": {
            "name": "Arrested Development",
            "rating": 5
        }
    }
}

JSONGraphEnvelope

An envelope that wraps a JSONGraph fragment.

Type:
Object
Properties
Name Type Attributes Description
jsonGraph JSONGraph

a JSONGraph fragment
paths Array.<PathSet> <nullable>

the paths to the values in the JSONGraph fragment
invalidated Array.<PathSet> <nullable>

the paths to invalidate in the Model
Source:
typedefs/JSONGraphEnvelope.js, line 1
Example
var $ref = falcor.ref;
var model = new falcor.Model();
model.set({
  paths: [
    ["todos", [0,1], ["name","done"]]
  ],
  jsonGraph: {
    todos: [
      $ref("todosById[12]"),
      $ref("todosById[15]")
    ],
    todosById: {
      12: {
        name: "go to the ATM",
        done: false
      },
      15: {
        name: "buy milk",
        done: false
      }
    }
  },
}).then(function(jsonEnvelope) {
  console.log(JSON.stringify(jsonEnvelope, null, 4));
});

// prints...
// {
//   json: {
//     todos: {
//       0: {
//         name: "go to the ATM",
//         done: false
//       },
//       1: {
//         name: "buy milk",
//         done: false
//       }
//     }
//   }
// }

Key

A part of a Path that can be any JSON value type. All types are coerced to string, except null. This makes the number 1 and the string "1" equivalent.

Type:
string or number or boolean or null
Source:
typedefs/Key.js, line 1

KeySet

A part of a PathSet that can be either a Key, Range, or Array of either.

Type:
Key or Range or Array.<(Key|Range)>
Source:
typedefs/KeySet.js, line 1

Options

Type:
Object
Properties
Name Type Attributes Description
source DataSource <optional>

A data source to retrieve and manage the JSONGraph
cache JSONGraph <optional>

Initial state of the JSONGraph
maxSize number <optional>

The maximum size of the cache before cache pruning is performed. The unit of this value depends on the algorithm used to calculate the $size field on graph nodes by the backing source for the Model's DataSource. If no DataSource is used, or the DataSource does not provide $size values, a naive algorithm is used where the cache size is calculated in terms of graph node count and, for arrays and strings, element count.
collectRatio number <optional>

The ratio of the maximum size to collect when the maxSize is exceeded.
maxRetries number <optional>

The maximum number of times that the Model will attempt to retrieve the value from its DataSource. Defaults to 3.
errorSelector Model~errorSelector <optional>

A function used to translate errors before they are returned
onChange Model~onChange <optional>

A function called whenever the Model's cache is changed
comparator Model~comparator <optional>

A function called whenever a value in the Model's cache is about to be replaced with a new value.
disablePathCollapse boolean <optional>

Disables the algorithm that collapses paths on GET requests. The algorithm is enabled by default. This is a relatively computationally expensive feature.
disableRequestDeduplication boolean <optional>

Disables the algorithm that deduplicates paths across in-flight GET requests. The algorithm is enabled by default. This is a computationally expensive feature.
Source:
Model.js, line 61

Path

An ordered list of Keys that point to a value in a JSONGraph.

Type:
Array.<Key>
Source:
typedefs/Path.js, line 1
Example
// Points to the name of product 1234
 ["productsById", "1234", "name"]

PathSet

An ordered list of KeySets that point to location(s) in the JSONGraph. It enables pointing to multiple locations in a more terse format than a set of Paths and is generally more efficient to evaluate.

Type:
Array.<KeySet>
Source:
typedefs/PathSet.js, line 1
Example
// Points to the name and price of products 1234 and 5678
 ["productsById", ["1234", "5678"], ["name", "price"]]

PathValue

A wrapper around a path and its value.

Type:
Object
Properties
Name Type Attributes Description
path PathSet

the path to a location in the JSONGraph
value * <nullable>

the value of that path
Source:
typedefs/PathValue.js, line 1
Example
{
	path: ["productsById", "1234", "name"],
	value: "ABC"
 }

Range

Describe a range of integers. Must contain either a "to" or "length" property.

Type:
Object
Properties
Name Type Attributes Default Description
from number <optional>
 0

the lower bound of the range (inclusive)
to number <nullable>

the upper bound of the range (inclusive). Must be >= to the "from" value
length number <nullable>

the length of the range. Must be >= 0
Source:
typedefs/Range.js, line 1
Example
// The following range specifies the numbers 0, 1, and 2
 {from: 0, to: 2}
 // The following range specifies the numbers 1 and 2
 {from: 1, length: 2}