zodern:relay - Type safe Meteor methods and publications

zodern:relay allows you to easily write methods and publications, and have typescript check the types of the args and result wherever you call the method or subscribe to a publication.

/imports/methods/projects.ts:

1import { createMethod } from 'meteor/zodern:relay';
2import { z } from 'zod';
3import { Projects } from '/shared/collections';
4
5export const createProject = createMethod({
6  schema: z.object({
7    name: z.string(),
8    description: z.string().optional(),
9    isPublic: z.boolean(),
10  }),
11  run({ name, description, isPublic }): string {
12    let id = Projects.insert({
13      name,
14
15      // Type 'string | undefined' is not assignable to type 'string'.
16      //   Type 'undefined' is not assignable to type 'string'.ts(2322)
17      description,
18      public: isPublic,
19    });
20
21    return id;
22  },
23});
24

/client/exampleProject.ts

1import { createProject } from '/imports/methods/projects';
2
3export async function createExampleProject() {
4  // id has type of string
5  const id = await createProject({
6    // Property 'isPublic' is missing in type '{ name: string; }'
7    // but required in type
8    // '{ description?: string | undefined; name: string; isPublic: boolean; }'.ts(2345)
9    name: 'Example',
10  });
11}
12

You might be wondering if this can expose server code on the client. None of the content of files in methods or publications directories are used on the client. If any of these files are imported on the client, their content is completely replaced. On the client, the files will export small functions for calling any methods or subscribing to any publications that were originally exported by the file.

Getting started

Install zodern:relay and zod

meteor add zodern:relay
meteor npm install zod

Set up @zodern/babel-plugin-meteor-relay

meteor npm install @zodern/babel-plugin-meteor-relay

Create a .babelrc in the root of your Meteor app:

1{
2  "plugins": [
3    "@zodern/babel-plugin-meteor-relay"
4  ]
5}

Set up zodern:types

If you haven't already, add zodern:types to your app so typescript can use the type definitions from zodern:relay.

Methods

You can define methods in files in methods directories. The methods directories should not be inside a client or server folder so you can import the methods on both the client and server. The babel plugin will replace the content of these files when imported on the client, so you don't have to worry about server code being exposed.

1import { createMethod } from 'meteor/zodern:relay';
2import { z } from 'zod';
3
4export const add = createMethod({
5  name: 'add',
6  schema: z.number().array().length(2),
7  run([a, b]) {
8    return a + b;
9  },
10});

schema is always required, and must be a schema created from the zod npm package. If the method does not have any arguments, you can use zod.undefined() as the schema. If you do not want to check the arguments, you can use zod.any().

The schema is used to provide types for for the run function's parameter, and to check the arguments when calling the method.

The name is optional. If it is not provided, the babel plugin will add one based on the export name and file name.

createMethod returns a function you can use to call the method. The function returns a promise that resolves with the result. The result will have the same type as the return value of the run function.

1import { add } from '/imports/methods/add'
2
3add([1, 2]).then(result => {
4  console.log(result) // logs 3
5});

The method name, schema, or run function, are available on the config property of the function returned by createMethod:

1import { add } from '/imports/methods/add';
2
3
4console.log(
5  add.config.name,
6  add.config.schema,
7  add.config.run
8)

On the client, only config.name is defined.

Publications

You can define publications in files in publications directories. The publications directories should not be inside a client or server folder so you can import the publications on both the client and server. The babel plugin will replace the content of these files when imported on the client, so you don't have to worry about server code being exposed.

1import { createPublication } from 'meteor/zodern:relay';
2import { z } from 'zod';
3import { Projects } from '/collections';
4
5export const subscribeProject = createPublication({
6  name: 'project',
7  schema: z.object({
8    id: z.string()
9  }),
10  run({ id }) {
11    return Projects.find({ _id: id });
12  },
13});

The schema is used to provide types for for the run function's parameter, and to check the arguments when subscribing to the publication.

The name is optional. If it is not provided, the babel plugin will add one based on the export name and file name.

createPublication returns a function you can use to subscribe to the publication. This function returns a Subscription Handle, the same as Meteor.subscribe would.

1import { subscribeProject } from '/imports/publications/projects'
2
3const exampleId = 'example';
4
5subscribeProject({ id: exampleId });
6
7subscribeProject({ id: exampleId }, {
8  onStop(err) {
9    console.log('subscription stopped', err);
10  },
11  onReady() {
12    console.log('subscription ready');
13  }
14});

Like with methods, the function returned by createPublication has a config property to access the name, schema, and run function. On the client, only the name is available.

Blocking

By default, methods and publications will block, meaning each session will run one method or publication at a time, in the order the client calls or subscribes. In cases where you do not want this behavior for a specific method or subscription, you can call this.unblock().

Meteor has a bug for methods and publications with an async function where they will always be unblocked, and there is no way to have them block. zodern:relay fixes this so async methods and publications are consistent with Meteor's normal behavior.

Rate limiting

Both createMethod and createPublication support a rateLimit option:

1export const add = createMethod({
2  name: 'add',
3  schema: z.number().array().length(2),
4  rateLimit: {
5    interval: 2000,
6    limit: 10
7  },
8  run([a, b]) {
9    return a + b;
10  },
11});

interval is the number of ms before the rate limit is reset. limit is the maximum number of method calls or created subscriptions allowed per time interval.

Pipelines

Instead of defining a single run function, a pipeline allows you to use an array of functions as a pipe. The output of each function is then used as the input of the next function. For example:

1export const getTasks = createMethod({
2  name: 'getTasks',
3  schema: z.object({
4    tag: z.string().optional()
5    status: z.string().optional(),
6  })
7}).pipeline(
8  (input) => ({ ...input, status: input.status || 'new' }),
9  pickOrganization,
10  ({ tag, status, organizationId }) => {
11    return Tasks.find({ organizationId, status, tag }).fetch();
12  }
13);

Pipelines are configured by calling the pipeline function returned by createMethod. The pipeline function is only available when run function is not configured.

Each argument passed to the pipeline function is a step in the pipeline. This method has 3 steps in the pipeline. The first step takes the data sent from the client, and then returns an object with the status set to a default value. The next step takes that as the input, and then adds an organizationId property. The final step uses the completed input, and returns some documents from the database. Since this is the last step, its return value is sent to the client.

Benefits of pipelines:

Allows you to break complicated methods and publications into multiple steps
Types for the input are automatically inferred through the pipeline
Composable: you can create functions that are used in the pipelines for many methods or publications. You can even create partial pipelines - groups of pipeline steps you can then add to pipelines while maintaining their types
Reactive Publications: steps of the pipeline can optionally re-run when data in the database changes, allowing you to then change what cursors are published
You can define global pipeline steps that run before and after every method or publication

Re-usable pipeline steps

With js, you can simply create a function that returns the input for the next step:

1function pipelineStep(input) {
2  // Do work...
3
4
5  return input;
6}

With typescript, you have to write it as a generic function so typescript can track the types in the pipeline:

1function pipelineStep<T>(input: T) {
2  // Do work...
3
4  return input;
5}
6
7// Expects the input to have a projectId property
8// Typescript will validate that the previous pipeline step returned an object
9// with projectId
10function pipelineStep<T extends { projectId: string }>(input: T) {
11  let projectId = input;
12  
13  // Do work...
14
15  return input;
16}

If you are using the same group of pipeline steps for multiple methods or publications, you can create partial pipelines. Partial pipelines are created using the partialPipeline function:

1import { partialPipeline } from 'meteor/zodern:relay';
2
3let adminPipeline = partialPipeline(
4  requireAdmin,
5  unblock,
6  auditAdmin
7);
8
9export const listUsers = createMethod({
10  name: 'listUsers',
11  schema: z.undefined()
12}).pipeline(
13  (input) => input,
14  adminPipeline,
15  () => Users.find().fetch();
16);

For typescript to infer the types correctly in reusable steps or partial pipelines, they can not be used as the first step in the pipeline. As in the example above, you can have the first step be a simple function that returns the input. This then allows typescript to correctly infer the return type of adminPipeline.

Pipeline step arguments

Each step in the pipeline is passed two arguments:

The output from the previous step. If the first step, it is given the initial data
The pipeline object.

The pipeline object has a number of useful functions and properties:

originalInput the data given to the first step of the pipeline
type either method or publication
name the name of the method or publication
onResult Pass onResult a callback to run when the method or publication finishes. The callback is given the final result. Please note that the callback should not modify the result.
onError Pass onError a callback to run when the method or publication errors. If you want to change the error, the callback can return an error that should be used instead
stop calling this will stop a publication's pipeline - the current step will finish, but subsequent steps will not run. This will also mark the subscription as ready. stop currently can not be used with methods.

Here is an example of a re-usable pipeline step that logs the results of methods

1function logResult (input, pipeline) {
2  if (pipeline.type === 'publication') {
3    return;
4  }
5
6  pipeline.onResult((result) => {
7    console.log(`Method ${pipeline.name} finished`);
8    console.log('Result', result);
9  });
10
11  pipeline.onError((err) => {
12    console.log(`Method ${pipeline.name} failed`);
13    console.log('Error', err);
14  });
15}
16

Global Pipeline

If you have a step you want to run before or after every method or publication, you can configure the global pipeline. Please note that the global pipeline should return the input unmodified. Any modifications will not be reflected in the types.

1import { setGlobalMethodPipeline, setGlobalPublicationPipeline } from 'meteor/zodern:relay';
2
3setGlobalMethodPipeline(
4  auditMethods,
5  logStatus
6);
7
8setGlobalPublicationPipeline(
9  auditPublications,
10  logStatus
11);

Reactive Publication Pipelines

Reactive pipelines allows steps of the pipeline to re-run when the results of a Mongo cursor change. This is useful for reactive joins, reacting to changes in permissions, and other use cases.

The function withCursors allows the pipeline to watch for changes in the database:

1function pipelineStep(input) {
2  let cursor = Projects.find({ owner: Meteor.userId(), organization: input.organization });
3
4  return withCursors(input, { projects: cursor });
5}

withCursors accepts two arguments. The first one is the input for the next step. The second argument is an object with the Mongo queries to watch. The two objects are merged together, with the cursors being replaced with the cursor results. In the above example, the input for the next step will have a new projects property with the value being the results of the cursor.

When the results of any of the cursors change, the input for the next step will be updated and the pipeline will be re-run starting at the next step.

Here is a complete example:

1createMethod({
2  name: 'allTasks',
3  schema: z.object({
4    organization: z.string()
5  }),
6}).pipeline(
7  (input) => {
8    let cursor = Projects.find({ owner: Meteor.userId(), organization: input.organization });
9
10    return withCursors(input, { projects: cursor });
11  },
12  (input) => {
13    let projectIds = input.projects.map(project => project._id);
14
15    return Tasks.find({ project: { $in: projectIds } });
16  }
17);

The first step of the pipeline creates a cursor to find all projects the user owns. This cursor is passed in the second object to withCursors, with the key projects.

The input of the second step has a new property named projects, matching what the key for the cursor. The projects property has an array of all the docs found by the cursor.

Whenever the results of the cursor change (maybe the user deleted a project or created a new one), the second step of the pipeline is re-run, with the projects property having the new list of docs. This allows it to replace the query being published to use the current list of projects.

Here is an example showing reacting to permission changes:

1createMethod({
2  name: 'adminListUsers',
3  schema: z.undefined()
4}).pipeline(
5  (input) => {
6    const user = Meteor.users.find({_id: Meteor.userId()});
7
8    return withCursors(input, { user })
9  },
10  (input) => {
11    const [ user ] = input.user;
12
13    if (user.isAdmin) {
14      return Users.find().fetch();
15    }
16
17    return [];
18  }
19);

The first step of the pipeline creates a cursor to get the doc for the current user. The second step then uses the doc to check if the user is an admin to decide if it should publish the data. If the user's doc is later modified so they are no longer an admin, the second step of the pipeline will then re-run, allowing it to stop publishing any data.

Method Stubs

By default, no code you write in methods directories will be kept on the client. However, you can mark specific methods that you want to also use as stubs on the client. In this case, zodern:relay only keeps two pieces of code on the client:

The stub function itself
The specific imports used by the stub function

To re-use therun function for a method as the stub on the client, you can set the stub option to true.

1import { Tasks } from '/collections';
2import { createMethod } from 'meteor/zodern:relay';
3
4export const createTask = createMethod({
5  schema: z.string(),
6  stub: true,
7  run(name) {
8    Tasks.insert({ name, owner: Meteor.userId() });
9  }
10});

To use a different method for the stub, configure it using the stop property:

1import { Tasks, Events } from '/collections';
2import { createMethod } from 'meteor/zodern:relay';
3
4export const createTask = createMethod({
5  schema: z.string(),
6  stub() {
7    Tasks.insert({ name, owner: Meteor.userId() });
8  },
9  run(name) {
10    checkPermissions(Meteor.userId());
11    Tasks.insert({ name, owner: Meteor.userId() });
12    sendEmail();
13    Events.insert({ type: 'task.add', user: Meteor.userId() })
14  }
15});

In the above example, only the stub function would be kept on the client:

1  stub() {
2    Tasks.insert({ name, owner: Meteor.userId() });
3  }

Since this function uses the imported Tasks, that import will also be kept on the client:

1import { Tasks } from '/collections';

At this time, stubs are not supported for methods that use pipelines