grubba:rpc

v0.6.0Published 4 hours ago

RPC

What is this package?

Inspired on zodern:relay

This package provides functions for building E2E type-safe RPCs. The functions are:

  • crateMethod
  • createPublication

How to download it?

meteor npm i grubba-rpc
meteor npm i zod

or if you prefer using meteor package manager

meteor add grubba:rpc 
meteor npm i zod

How to use it?

1import {   
2  ReturnMethod, // <- Type
3  ReturnSubscription, // <- Type
4  Config, // <- Type
5  SubscriptionCallbacks, // <- Type
6  createMethod, // <- function
7  createPublication // <- function
8} from 'grubba-rpc';

createMethod

1
2const test1 = createMethod('name', z.any(), () => 'str');
3const result = await test1();
4//    ˆ? is string and their value is 'str'

For semantics uses you can as well use the methods below with the same output as createMethod:

1const joinStr =  createMutation(
2  'join', 
3  z.object({ foo: z.string(), bar: z.string() }),
4  ({ foo, bar }) => foo + bar);
5const result = await joinStr({ foo: 'foo', bar: 'bar' });
6//    ˆ? is string and their value is 'foobar'
1const query =  createQuery(
2  'query', 
3  z.object({ _id: z.string() }),
4  async ({ _id }) => {
5    const someData = await DB.findOne(_id);
6    const otherData = await DB.find({ _id: { $ne: someData._id } }).fetchAsync();
7    return { someData, otherData };
8  });
9const result = await query({ _id: 'id' });
10//    ˆ? is string and their value is the item you was querying

example of use

createMethod accepts 4 arguments:

  • name: string
  • schema: ZodSchema (validator)
  • handler (optional): function that receives the arguments of the method and returns the result
  • config (optional): object with the following properties:
1type Config<S, T> = {
2  rateLimit?: {
3    interval: number,
4    limit: number
5  },
6  hooks?: {
7    onBeforeResolve?: Array<(raw: unknown, parsed: S,) => void>;
8    onAfterResolve?: Array<(raw: Maybe<T>, parsed: S, result: T) => void>;
9    onErrorResolve?: Array<(err: Meteor.Error | Error | unknown, raw: Maybe<T>, parsed: S) => void>;
10  }
11}

createPublication

1  const publication = createPublication('findRooms', z.object({ level: z.number() }), ({ level }) => Rooms.find({ level: level }));
2const result = publication({ level: 1 }, (rooms) => console.log(rooms));
3//                                            ˆ? subscription 
4

example of use

createPublication accepts 4 arguments:

  • name: string
  • schema: ZodSchema (validator)
  • handler (optional): function that is being published
  • config (optional): object with the following properties:

note that subscription returns the subscription handler the same way as Meteor.publish

1type Config<S, T> = {
2  rateLimit?: {
3    interval: number,
4    limit: number
5  },
6  hooks?: {
7    onBeforeResolve?: Array<(raw: unknown, parsed: S,) => void>;
8    onAfterResolve?: Array<(raw: Maybe<T>, parsed: S, result: T) => void>;
9    onErrorResolve?: Array<(err: Meteor.Error | Error | unknown, raw: Maybe<T>, parsed: S) => void>;
10  }
11}

Advanced usage

you can take advantage of the hooks to add custom logic to your methods and publications

1
2const fn = createMethod('name', z.any(), () => 'str', {
3  hooks: {
4    onBeforeResolve: [
5      (raw, parsed) => {
6        console.log('before resolve', raw, parsed);
7      }
8    ],
9    onAfterResolve: [
10      (raw, parsed, result) => {
11        console.log('after resolve', raw, parsed, result);
12      }
13    ],
14    onErrorResolve: [
15      (err, raw, parsed) => {
16        console.log('error resolve', err, raw, parsed);
17      }
18    ]
19  }
20});
21// valid ways as well
22fn.addErrorResolveHook((err, raw, parsed) => {
23  console.log('error resolve', err, raw, parsed);
24});
25fn.addBeforeResolveHook((raw, parsed) => {
26  console.log('before resolve', raw, parsed);
27});
28fn.addAfterResolveHook((raw, parsed, result) => {
29  console.log('after resolve', raw, parsed, result);
30});
31const result = await fn();

Using safe methods

check this example that illustrates this 'secure way' of using safe methods, as it is not bundled in the client

1
2import { createMethod } from 'grubba-rpc'
3import { z } from "zod";
4
5const DescriptionValidator = z.object({ description: z.string() });
6
7// tasks.mutations.ts
8// it expects the return type to be a void
9export const insert = createMethod('task.insert', DescriptionValidator).expect<void>();
10
11// tasks.mutations.js
12// If you are using javascript, you can use the following syntax
13export const insert = createMethod('task.insert', DescriptionValidator).expect(z.void());
14
15// ---------
16
17// tasks.methods.ts
18import { insert } from './tasks.mutations.ts'
19insertTask = ({ description }) => {
20  TasksCollection.insert({
21    description,
22    userId: Meteor.userId(),
23    createdAt: new Date(),
24  });
25};
26
27insert.setResolver(insertTask);
28
29// ---------
30
31
32// client.ts
33import { insert } from './tasks.mutations.ts'
34insert({ description: 'test' });
35//^? it return void and it will run
36// if resolver is not set it will throw an error
37

Examples?

in the examples folder you can find a simple example of how to use this package it uses simpletasks as a base

for downloading it you can do the command below or just access this link

git clone https://github.com/Grubba27/meteor-rpc-template.git