v2.0.0-rc.6 🚀 Refactor client & Rest.rpc

Author: DZakh

README.md

@@ -40,7 +40,7 @@ let getPosts = Rest.route(() => {
 })
 ```
 
-Set an endpoint your fetch calls should use:
+In the same file set an endpoint your fetch calls should use:
 
 ```rescript
 // Contract.res
@@ -98,6 +98,7 @@ let _ = app->Fastify.listen({port: 3000})
 - [Table of Contents](#table-of-contents)
 - [Install](#install)
 - [Route Definition](#route-definition)
+  - [RPC-like abstraction](#rpc-like-abstraction)
   - [Path Parameters](#path-parameters)
   - [Query Parameters](#query-parameters)
   - [Request Headers](#request-headers)
@@ -106,6 +107,8 @@ let _ = app->Fastify.listen({port: 3000})
   - [Responses](#responses)
   - [Response Headers](#response-headers)
   - [Temporary Redirect](#temporary-redirect)
+- [Fetch & Client](#fetch--client)
+  - [API Fetcher](#api-fetcher)
 - [Client-side Integrations](#client-side-integrations)
   - [SWR](#swr)
     - [Polling](#polling)
@@ -142,6 +145,30 @@ Routes are the main building block of the library and a perfect way to describe
 
 For every route you can describe how the HTTP transport will look like, the `'input` and `'output` types, as well as add additional metadata to use for OpenAPI.
 
+### RPC-like abstraction
+
+Alternatively if you use ReScript Rest both on client and server and you don't care about how the data is transfered, there's a helper built on top of `Rest.route`. Just define input and output schemas and done:
+
+```rescript
+let getPosts = Rest.rpc(() => {
+  input: S.sceham(s => {
+    "skip": s.matches(S.int),
+    "take": s.matches(S.int),
+    "page": s.matches(S.option(S.int)),
+  }),
+  output: S.array(postSchema),
+})
+
+let result = await Contract.getPosts->Rest.fetch(
+  {"skip": 0, "take": 10, "page": Some(1)}
+)
+// ℹ️ It'll do a POST request to http://localhost:3000/getPosts with the `{"skip": 0, "take": 10, "page": 1}` body and application/json Content Type
+```
+
+This is a code snipped from the super simple example above. Note how I only changed the route definition, but the fetching call stayed untouched. The same goes for the server implementation - if the input and output types of the route don't change there's no need to rewrite any logic.
+
+> 🧠 The path for the route is either taken from `operationId` or the name of the route variable.
+
 ### Path Parameters
 
 You can define path parameters by adding them to the `path` strin with a curly brace `{}` including the parameter name. Then each parameter must be defined in `input` with the `s.param` method.
@@ -429,7 +456,7 @@ let fetch = Rest.fetch(~client, ...)
 
 ### API Fetcher
 
-You can override the client fetching logic by passing the `~apiFetcher` param.
+You can override the client fetching logic by passing the `~fetcher` param.
 
 ## Client-side Integrations
 

__tests__/Rest_test.res

@@ -607,7 +607,7 @@ let bigint: S.t<bigint> = S.custom("BigInt", s => {
 })
 
 asyncTest("Test query params encoding to path", async t => {
-  let getHeight = Rest.route(() => {
+  let routeFn = (): Rest.definition<'i, 'o> => {
     path: "/height",
     method: Get,
     input: s =>
@@ -630,12 +630,11 @@ asyncTest("Test query params encoding to path", async t => {
         "trueString": s.query("trueString", S.literal("true")),
         "nested": s.query(
           "nested",
-          S.object(
-            s =>
-              {
-                "unit": s.field("unit", S.unit),
-                "nestedNested": s.nested("nestedNested").field("field", S.string),
-              },
+          S.object(s =>
+            {
+              "unit": s.field("unit", S.unit),
+              "nestedNested": s.nested("nestedNested").field("field", S.string),
+            }
           ),
         ),
       },
@@ -645,7 +644,9 @@ asyncTest("Test query params encoding to path", async t => {
         s.data(S.bool)
       },
     ],
-  })
+  }
+
+  let getHeight = Rest.route(routeFn)
 
   let input = {
     "string": "abc",
@@ -685,7 +686,7 @@ asyncTest("Test query params encoding to path", async t => {
   t->Assert.deepEqual(await Rest.fetch(~client, getHeight, input), true)
 
   let getHeight = Rest.route(() => {
-    ...(getHeight->Rest.params).definition,
+    ...routeFn(),
     jsonQuery: true,
   })
 
@@ -712,7 +713,7 @@ asyncTest("Test query params encoding to path", async t => {
 })
 
 asyncTest("Test query params support by Fastify", async t => {
-  let getHeight = Rest.route(() => {
+  let routeFn = (): Rest.definition<'i, 'o> => {
     path: "/height",
     method: Get,
     input: s =>
@@ -749,7 +750,8 @@ asyncTest("Test query params support by Fastify", async t => {
         s.data(S.bool)
       },
     ],
-  })
+  }
+  let getHeight = Rest.route(routeFn)
 
   let input = {
     "string": "abc",
@@ -792,7 +794,7 @@ asyncTest("Test query params support by Fastify", async t => {
   t->Assert.deepEqual(await Rest.fetch(~client, getHeight, input), true)
 
   let getHeight = Rest.route(() => {
-    ...(getHeight->Rest.params).definition,
+    ...routeFn(),
     jsonQuery: true,
   })
 
@@ -1211,6 +1213,30 @@ asyncTest("Fails with an invalid response data", async t => {
   )
 })
 
+asyncTest("Test Rest.rpc", async t => {
+  let client = Rest.client("http://localhost:3000", ~fetcher=async (
+    data
+  ): Rest.ApiFetcher.response => {
+    t->Assert.deepEqual(
+      data,
+      {
+        path: "http://localhost:3000/getHeight",
+        method: "POST",
+        body: Some("false"->Obj.magic),
+        headers: Some(Js.Dict.fromArray([("content-type", "application/json"->Obj.magic)])),
+      },
+    )
+    {data: false->Obj.magic, status: 200, headers: Js.Dict.empty()}
+  })
+
+  let getHeight = Rest.rpc(() => {
+    input: S.bool,
+    output: S.bool,
+  })
+
+  t->Assert.deepEqual(await getHeight->Rest.fetch(~client, false), false)
+})
+
 asyncTest("Test POST request with rawBody", async t => {
   let createGame = Rest.route(() => {
     path: "/game",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "rescript-rest",
-  "version": "2.0.0-rc.5",
+  "version": "2.0.0-rc.6",
   "description": "😴 ReScript RPC-like client, contract, and server implementation for a pure REST API",
   "keywords": [
     "rest",
@@ -44,7 +44,7 @@
     "@dzakh/rescript-ava": "3.1.0",
     "@fastify/swagger": "9.2.0",
     "@scalar/fastify-api-reference": "1.25.60",
-    "ava": "6.2.0",
+    "ava": "5.3.1",
     "c8": "10.1.2",
     "fastify": "5.1.0",
     "swr": "2.3.2",