set.map()

Apply a provided function to each element of a Set. Can’t perform writes.

Loading strategy:

Lazy loading

Signature

map(mapper: (A => B)) => Set<B>

Description

Creates a Set by applying a mapper function to each element in the calling Set.

Writes are not permitted. The calling Set isn’t changed.

If map() is the last value in a query, the first page of the new Set is returned.

Iterator methods

FQL provides several methods for iterating over a Set. set.forEach(), set.map(), set.flatMap() are similar but used for different purposes:

Method Primary use Notes

set.forEach()

Perform in-place writes on Set elements.

Doesn’t return a value.

set.map()

Returns a new Set.

Can’t perform writes.

set.flatMap()

Similar to set.map(), but flattens the resulting Set by one level.

Can’t perform writes.

For examples, see:

Parameters

Parameter Type Required Description

mapper

Function

Yes

Anonymous FQL function to call on each element of the calling Set. Each call returns a value that’s returned in the result Set.

Return value

Type Description

Set<Generic>

Set containing values returned by each mapper function call.

Examples

Basic example

For all Customer documents, combine the address.city and address.state properties into a single string:

Customer.all().map(
  customer => {
    name: customer.name,
    city: "#{customer.address.city}, #{customer.address.state}"
  }
)
{
  data: [
    {
      name: "Alice Appleseed",
      city: "Washington, DC"
    },
    {
      name: "Bob Brown",
      city: "Washington, DC"
    },
    {
      name: "Carol Clark",
      city: "Washington, DC"
    }
  ]
}

Project Sets using set.map()

You can use set.map() to project a Set, similar to using Set projection.

For example, the following projection query:

Product.sortedByPriceLowToHigh() {
  name,
  description,
  price
}

Is equivalent to the following set.map() query:

Product.sortedByPriceLowToHigh().map(prod => {
  name: prod.name,
  description: prod.description,
  price: prod.price,
})

set.forEach() vs. set.map()

You can use both set.forEach() and set.map() to iterate through a Set.

Use set.forEach() to perform in-place writes on the calling Set:

// Gets the frozen category.
let frozen = Category.byName("frozen").first()

// Uses `forEach()` to delete each product in
// the frozen category.
Product.byCategory(frozen).forEach(product => {
  product.delete()
})
null

Although it returns null, set.forEach() still performs the requested operations.

Unlike set.forEach(), set.map() can’t perform writes:

// Gets the produce category.
let produce = Category.byName("produce").first()

// Attempts to use `map()` to delete each product in
// the produce category.
Product.byCategory(produce).map(product => {
  product.delete()
})
invalid_effect: `delete` performs a write, which is not allowed in set functions.

error: `delete` performs a write, which is not allowed in set functions.
at *query*:7:17
  |
7 |   product.delete()
  |                 ^^
  |

Instead, you can use set.map() to output a new Set containing extracted or transformed values:

// Gets the produce category.
let produce = Category.byName("produce").first()

// Uses `map()` to outputs a new Set containing products in
// the produce category. The new Set transforms each product's
// name.
Product.byCategory(produce).map(product => {
  let product: Any = product
  {
    name: product.category.name + ": " + product.name,
  }
})
{
  data: [
    {
      name: "produce: avocados"
    },
    {
      name: "produce: single lime"
    },
    {
      name: "produce: organic limes"
    },
    {
      name: "produce: limes"
    },
    {
      name: "produce: cilantro"
    }
  ]
}

set.map() vs. set.flatMap()

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

In the following example, set.map() returns a two-dimensional Set:

// Get a Set of all `Category` collection documents.
let categories = Category.all()

// Use `map()` to get a Set of `Product` documents
// for each category.
categories.map(category => {
  Product.byCategory(category)
})
// Two-dimensional Set.
{
  data: [
    {
      data: [
        {
          id: "111",
          coll: Product,
          ts: Time("2099-10-02T22:37:39.583Z"),
          name: "cups",
          description: "Translucent 9 Oz, 100 ct",
          price: 698,
          stock: 100,
          category: Category("123")
        },
        ...
      ]
    },
    {
      data: [
        {
          id: "333",
          coll: Product,
          ts: Time("2099-10-02T22:37:39.583Z"),
          name: "pizza",
          description: "Frozen Cheese",
          price: 499,
          stock: 100,
          category: Category("456")
        }
      ]
    },
    {
      data: [
        {
          id: "444",
          coll: Product,
          ts: Time("2099-10-02T22:37:39.583Z"),
          name: "avocados",
          description: "Conventional Hass, 4ct bag",
          price: 399,
          stock: 1000,
          category: Category("789")
        },
        ...
      ]
    }
  ]
}

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

// Get a Set of all `Category` collection documents.
let categories = Category.all()

// Use `flatMap()` to get a Set of `Product` documents
// for each category. Then flatten the resulting Set.
categories.flatMap(category => {
  Product.byCategory(category)
})
// One-dimensional Set.
{
  data: [
    {
      id: "111",
      coll: Product,
      ts: Time("2099-10-02T22:37:39.583Z"),
      name: "cups",
      description: "Translucent 9 Oz, 100 ct",
      price: 698,
      stock: 100,
      category: Category("123")
    },
    ...
    {
      id: "333",
      coll: Product,
      ts: Time("2099-10-02T22:37:39.583Z"),
      name: "pizza",
      description: "Frozen Cheese",
      price: 499,
      stock: 100,
      category: Category("456")
    },
    ...
    {
      id: "444",
      coll: Product,
      ts: Time("2099-10-02T22:37:39.583Z"),
      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!