quave:react-data

quave:react-data is a Meteor package that allows you to subscribe to publications and also call methods.

Features

• Call methods with await
• Subscribe to data with skip logic
• Deps array to resubscribe

Why

Almost every Meteor application with React is using Subscriptions and Methods, so it's helpful to provide React Hooks ready to use in common cases.

Installation

meteor add quave:react-data

Usage

Both methods listed below rely on the idea of providing a single object to Meteor.call and also to Meteor.subscribe as the second parameter.

It means that you should send the data to the server putting in the arg field.

For example, instead of using Meteor.call('myMethod', param1, param2); you should do Meteor.call('myMethod', { param1, param2 });. Of course, using the method provided instead of Meteor.call.

The same for Meteor.subscribe but also using useData and in this case, as we have many ways to use it, you should use a named property called arg to send your arguments to the server.

We have decided this way because of our long experience with Meteor projects and as these calls are creating contracts (APIs) between the client and the server clear named objects are better in the long term than positional arguments. This will make your Meteor project more reliable in the long term and easier to maintain.

useMethod

Return a method function that is async. You can call it with a method name and an argument.

Example:

1import { useMethod } from 'meteor/quave:react-data';
2
3export const Snapshot = () => {
4  const { method } = useMethod();
5
6  const save = async () => {
7    const snapshot = await method('saveSnapshot', {
8      snapshot: {
9        _id: snapshotId,
10        items
11      },
12    });
13    clear();
14  };
15  
16  // continue to render...
17}

You can also provide options for useMethod such as:

• onError: it's called with the error, only when it's not expected. It's useful when you want to log errors for example. The promise will also be rejected with this error right after this is invoked. One argument will be passed with the following properties:
  • error: in case of errors
  • methodName: the method name called for all
  • arg: the arg sent to the method for all
• onSuccess: it's called with the result of your method when it finishes without errors. The promise will also be resolved with this result right after this is invoked. One argument will be passed with the following properties:
  • result: in case of success
  • methodName: the method name called for all
  • arg: the arg sent to the method for all
• onExpectedError: it's called with the error, only when it's expected. Two arguments will be passed with the following properties:
  • first: the reason, usually a String, of the error when provided in an EXPECTED_ERROR. Otherwise, you can also set a custom default
  text with QuaveReactData.setDefaultExpectedErrorReason method for all expected errors or it will pass Unknown error text.
  • second: is an object with the following properties:
    • error: in case of errors
    • methodName: the method name called for all
    • arg: the arg sent to the method for all
  • openAlert (deprecated): it will work because onExpectedError has the same behavior, so if will provide openAlert option we will consider it the same as onExpectedError, prefer onExpectedError to avoid breaking changes in the future.

useData

Subscribe to a publication and find the data.

Example:

1import { useData } from 'meteor/quave:react-data';
2import { useLoggedUser } from 'meteor/quave:logged-user-react';
3
4export const Home = () => {
5  const { loggedUser } = useLoggedUser();
6  
7  const {
8    data: snapshots,
9    loading
10  } = useData({
11    publicationName: 'mySnapshots',
12    skip: !loggedUser,
13    find: () => SnapshotsCollection.find({}, { sort: { at: -1 } }),
14  });
15
16  // continue to render...
17}

A more complex example:

1import { useData } from 'meteor/quave:react-data';
2
3export const Snapshot = () => {
4  const navigate = useNavigate();
5  const snapshotId = useParams()[RouteParams.SNAPSHOT_ID];
6
7  const { data: snapshotItems } = useData({
8    publicationName: 'mySnapshots',
9    arg: { snapshotId },
10    skip: !snapshotId,
11    deps: [snapshotId],
12    dataReturnWhenLoading: [],
13    find: () =>
14      SnapshotItemsCollection.find({ snapshotId }, { sort: { at: -1 } }),
15  });
16
17  // continue to render...
18}

shouldSkip property is also available, it works like skip, but it is a function instead of a static property.

Extra Features

EXPECTED_ERROR

When you call a method and the server returns an error, we check if the error is an expected error. To throw this error in the server you can use this constant EXPECTED_ERROR. It is exported from the package.

then you need to throw a Meteor.Error where the first argument is EXPECTED_ERROR and the second argument is the reason for the error, usually a friendly error message for the final user.

Example:

1import { EXPECTED_ERROR } from 'meteor/quave:react-data';
2
3Meteor.methods({
4    updateMyProfile({profileData}) {
5        if (!profileData.email) {
6            throw new Meteor.Error(EXPECTED_ERROR, 'Email field is required to update your profile');
7        }
8    }
9});

meteorCallPromisified

To avoid workarounds and non-standard way to call simple methods when you don't have a React component.

It implements just a Meteor.call wrapped in a Promise to get result or error.

setGetAdditionalArgsFunction

In some cases is nice to inject some argument in all the method calls and subscribes, for example, providing the language from the client or timezone.

We export a method called setGetAdditionalArgsFunction so you can provide additional args for all the calls and subscribe in a single place.

Example:

1import React from 'react';
2import { Meteor } from 'meteor/meteor';
3import { createRoot } from 'react-dom/client';
4import { App } from '../app/general/App';
5import { setGetAdditionalArgsFunction } from 'meteor/quave:react-data';
6import { getLanguage } from '../imports/infra/languages';
7
8setGetAdditionalArgsFunction(() => {
9  const language = getLanguage();
10  return { filter: { language } };
11});
12
13Meteor.startup(() => {
14  const root = createRoot(document.getElementById('app'));
15  root.render(<App />);
16});

Available Imports

To understand which named exports are available, check the client.js and server.js files.

License

MIT