Services

Overview

Services provide a flexible way to:

1. run server code that can be isomorphically executed from the client or server while
2. executing that code either on a web server or a background worker-type server.

A lot of boilerplate code is eliminated since server-side routes and controllers and client-side service code does not need to be written since Tyranid handles the marshaling and unmarshaling of data automatically across the HTTP call.

Furthermore, Tyranid services are strongly type-checked at both the client- and server-level using both run-time type checking and compile-time type-checking (via generated TypeScript interfaces).

Client calls to server methods will also pass through the standard fromClient() and toClient() mechanisms defined on types, fields, and documents.

Tyranid will also perform the following processing on service return values:

• Embedded documents will be automatically wrapped in the appropriate Tyr.Document instance.
• Embedded documents will also update the local database cache (similar to what something like normalizr would do).

Rethrowable exceptions thrown from inside services will be caught and rethrown in the client to ensure that error handling is also done isomorphically.

API

To implement a service:

1. Define your service metadata in the collection definition under the service option.

   const MyCollection = new Tyr.Collection({
     ...,
     service: {
       my service methods
     },
     ...
   }) as Tyr.MyCollectionCollection;

2. Implement the MyCollectionService interface that tyranid-tdgen generates from your service metadata and register it with the collection by assigning to service:

   MyCollection.service = {
     async myServiceMethod1(myServiceMethod1Parameters ...) {
       ...
     },
     async myServiceMethod2(myServiceMethod2Parameters ...) {
       ...
     },
     ...
   };

   Note that MyCollection.service is typed by tyranid-tdgen to implement MyCollectionService.

this Context

Inside service methods, this is available with the following properties:

Example

Server /user.model.ts

const User = new Tyr.Collection({
  ...,
  service: {
    activationCodesCsv: {
      route: '/api/user/activationCodesCsv',
      help: ‘Lorem ipsum dolor sit amet, ...’,
      params: {
        orgIds: {
          help: ‘Amet dolor sit ipsum’,
          is: 'array',
          of: { link: 'organization' }
        },
        groupIds: { is: 'array', of: { link: 'group' } },
      },
      return: {
        is: 'object',
        help: ‘Lorem ipsum dolor sit amet, ...’ },
        fields: {
          userId: { link: ‘user’ },
          activationCode: { is: ‘url’ },
        }
      }
    }
  },
  ...
}) as Tyr.UserCollection;

// could also be defined in a user.service.ts file or someplace else
User.service = {
  async activationCodesCsv(orgIds: ObjectId[], groupIds: ObjectId[]) {
    …
  }
};

Note that the

route: '/api/user/activationCodesCsv/',

line is redundant because the default route format is:

/api/collection name/service method name

interface UserService {
  /**
   * Lorem ipsum dolor sit amet, ...
   * @param orgIds Amet dolor sit ipsum
   * @return Lorem ipsum dolor sit amet, ...
   */
  activationCodesCsv(orgIds: ObjectId[], groupIds: ObjectId[]):
    Promise<{ userId: ObjectId, activationCode: string }>;
}

...
service: UserService;
...

const activationCodes = await User.activationCodesCsv(
  userIds: myUserIds, groupIds: myGroupIds);