Setters

As the name implies, in a Joystick app, a setter is a way to "set" data on/to a data source. Typically that data source is a database, but could also be a third-party API, a static file, etc. Ultimately, a setter is nothing more than a function being called with some helpful utilities and context added.

It's recommended that setters are organized in your /api folder, in sub-directories with names related to the data being retrieved. For example, if we had a collection/table in our database called books, we'd want to define a folder like /api/books. Inside of that folder, we'd create a file for our setters at /api/books/setters.js, exporting an object from that file with all of our book-related setter definitions.

Defining a Setter

Following the above example, let's define a setter for retrieving some books from our database.

import joystick from '@joystick.js/node';

const setters = {
  create_book: {
    set: () => {
      return process.databases.mongodb.collection('books').insertOne({
        _id: joystick.id(),
        title: 'Example Book',
        author: 'Example Author',
      });
    }
  }
};

export default setters;

Above, we've defined a simple setter create_book. To do it, we assign create_book as a key on a parent object containing all of our book-related setters. To that key, we've assigned another object with a single method set(): the function on our setter that's responsible for setting data.

In this example, we're calling to our database and inserting an example book.

Accessing input and context

When a setter is called (typically via the set() method imported from @joystick.js/ui or the api.set() method passed to a component's data function), input can be passed along with the request containing the data to insert, data to update, or data for deciding which data to update.

import joystick from '@joystick.js/node';

const setters = {
  create_book: {
    set: (input = {}) => {
      return process.databases.mongodb.collection('books').insertOne({
        _id: joystick.id(),
        title: input?.title,
        author: input?.author,
        category: input?.category,
      });
    }
  }
};

export default setters;

If there's any input passed with a setter request, Joystick will pass it as the first argument to your set() function. Above, we anticipate a title, author, and category being passed in the input and utilize it in our database insert.

const setters = {
  books: {
    get: (input = {}, context = {}) => {
      return process.databases.mongodb.collection('books').insertOne({
        _id: joystick.id(),
        title: input?.title,
        author: input?.author,
        category: input?.category,
        owner: context?.user?._id,
      });
    }
  }
};

export default setters;

In addition to input, as the second argument to your getter's set() function, a context object is passed with a few different sub-fields:

• req the inbound HTTP request related to the getter request.
• user if available, the currently logged in user.
• <database_provider> a connection to the database driver for one of your app's configured database providers (e.g., context.mongodb or context.postgresql).

Above, as an example, we've referenced the currently logged in user's _id field (if our user's database provider was a SQL database like PostgreSQL, we'd reference context.user.user_id) on the context object.

API Reference

set()

Function API

set(input: object, context: object) => any;

Arguments