array.map()

This method operates on an array. You typically fetch documents from a collection as a set, not an Array. For the equivalent Set method, see set instance methods.

For differences between Sets and Arrays, see Sets vs. Arrays.

Create an Array by executing a function for each Array element.

Signature

map(function: (val: Any) => Any) => Array<T>

Description

The map() method creates an Array by sequentially invoking a function on the elements of the calling Array. The new Array elements are the value of function after each call. The function parameter can be an anonymous Function or a top-level object method.

The calling Array isn’t changed.

Array iteration methods

FQL provides several methods for iterating over an Array. array.forEach(), array.map(), and array.flatMap() are similar but return different values.

Method Return value

array.forEach()

Null.

array.map()

Array.

array.flatMap()

Array, flattened by one level.

For examples, see:

Parameters

Parameter Type Required Description

function

Function

Yes

Anonymous Function or top-level object method to invoke for each element of the calling Array. The function accepts an Array element as an argument.

function parameters:

Parameter Type Required Description

val

Any

Array element to be evaluated.

Return value

Type Description

Array

Array with the result of function invoked on each element of the calling Array.

Examples

Basic

  1. Create an Array by mapping Array elements to subArrays that are constructed from the element value and the element value plus one, using an anonymous Function:

    [1, 2, 3].map(x => [x, x + 1])
    [
  [
    1,
    2
  ],
  [
    2,
    3
  ],
  [
    3,
    4
  ]
]

  2. Create an Array by passing a top-level object method as the mapping Function:

    [{name: "D"}, {name: "E"}].map(Collection.create)
    [
  {
    name: "D",
    coll: Collection,
    ts: Time("2099-02-18T20:06:25.620Z"),
    indexes: {},
    constraints: [],
    history_days: 0
  },
  {
    name: "E",
    coll: Collection,
    ts: Time("2099-02-18T20:06:25.620Z"),
    indexes: {},
    constraints: [],
    history_days: 0
  }
]

array.forEach() vs. array.map()

You can use both array.forEach() and array.map() to iterate through an Array. However, each method returns a different value type.

array.forEach() returns null:

// Create an Array of objects that contain category data.
let categories = [
  {
    "name": "Electronics",
    "description": "Bargain electronics!"
  },
  {
    "name": "Books",
    "description": "Bargain books!"
  }
]

// Use `forEach()` to create a `Category` collection document for each
// element of the previous Array.
categories.forEach(doc => Category.create({ doc }))
null

Although it returns null, array.forEach() still performed the requested operations. To verify:

// Get all `Category` collection documents
Category.all()
  // The results contain `Customer` documents created by
  // the previous `forEach()` call.
{
  data: [
    ...
    {
      id: "410665732340187209",
      coll: Category,
      ts: Time("2099-10-02T20:16:51.560Z"),
      products: "hdW...",
      name: "Electronics",
      description: "Bargain electronics!"
    },
    {
      id: "410665732340188233",
      coll: Category,
      ts: Time("2099-10-02T20:16:51.560Z"),
      products: "hdW...",
      name: "Books",
      description: "Bargain books!"
    }
  ]
}

array.map() returns an Array:

// Create an Array of objects that contain category data.
let categories = [
  {
    "name": "Movies",
    "description": "Bargain movies!"
  },
  {
    "name": "Music",
    "description": "Bargain music!"
  }
]

// Use `map()` to create a `Category` collection document for each
// element of the previous Array.
categories.map(doc => Category.create({ doc }))

In this case, the Array contains documents created by the array.map() call:

[
  {
    id: "410655308219678797",
    coll: Category,
    ts: Time("2099-10-02T17:31:10.366Z"),
    products: "hdW...",
    name: "Movies",
    description: "Bargain movies!"
  },
  {
    id: "410655308219679821",
    coll: Category,
    ts: Time("2099-10-02T17:31:10.366Z"),
    products: "hdW...",
    name: "Music",
    description: "Bargain music!"
  }
]

array.map() vs. array.flatMap()

array.flatMap() is similar to array.map(), except array.flatMap() also flattens the resulting Array by one level.

In the following example, array.map() returns a two-dimensional Array:

// Create an Array of product names.
let products = [
  "limes",
  "avocados"
]

// Use `map()` to get a Set of matching `Product` collection
// documents for each name. Convert each Set to an Array.
products.map(product => {
  Product.byName(product).toArray()
})
// Two-dimensional Array.
[
  [
    {
      id: "777",
      coll: Product,
      ts: Time("2099-10-02T19:37:36.357Z"),
      name: "limes",
      description: "Conventional, 16 oz bag",
      price: 299,
      stock: 30,
      category: Category("789")
    }
  ],
  [
    {
      id: "444",
      coll: Product,
      ts: Time("2099-10-02T19:37:36.357Z"),
      name: "avocados",
      description: "Conventional Hass, 4ct bag",
      price: 399,
      stock: 1000,
      category: Category("789")
    }
  ]
]

To flatten the result to a one-dimensional array, use array.flatMap() instead:

// Create an Array of product names.
let products = [
  "limes",
  "avocados"
]

// Use `flatMap()` to get a Set of matching `Product` collection
// documents for each name. Convert each Set to an Array.
// Then flatten the resulting Array by one level.
products.flatMap(product => {
  Product.byName(product).toArray()
})
// One-dimensional Array.
[
  {
    id: "777",
    coll: Product,
    ts: Time("2099-10-02T19:37:36.357Z"),
    name: "limes",
    description: "Conventional, 16 oz bag",
    price: 299,
    stock: 30,
    category: Category("789")
  },
  {
    id: "444",
    coll: Product,
    ts: Time("2099-10-02T19:37:36.357Z"),
    name: "avocados",
    description: "Conventional Hass, 4ct bag",
    price: 399,
    stock: 1000,
    category: Category("789")
  }
]

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!