@seam-rpc/client 2.2.1 → 3.0.1

package/README.md

@@ -61,6 +61,34 @@ export async function getUser(id: string): Promise<User | undefined> {
 }
 ```
 
+#### Create a Seam Space
+
+A Seam Space is linked to an Express app and is what you defined routers to. You define one Seam Space for your API, which can then be separated in to different routers. Each router can be any kind of structure with functions (e.g. an object or a module). This example uses files as modules.
+
+```ts
+import express from "express";
+import { createSeamSpace } from "@seam-rpc/server";
+
+// Import as modules
+import * as usersRouter from "./api/users.js";
+import * as postsRouter from "./api/posts.js";
+
+// Create express app
+const app = express();
+
+// Create Seam Space with express app
+const seamSpace = await createSeamSpace(app);
+
+// Create routers
+seamSpace.createRouter("/users", usersRouter);
+seamSpace.createRouter("/posts", postsRouter);
+
+// Start express server
+app.listen(3000, () => {
+    console.log("Listening on port 3000");
+});
+```
+
 ### Client
 The client needs to have the same schema as your API so you can call the API functions and have autocomplete. Behind the scenes these functions will send an HTTP requests to the server. SeamRPC can automatically generate the client schema files. To do this, you can either run the command `seam-rpc gen-client <input-files> <output-folder>` or [define a config file](#config-file) and then run the command `seam-rpc gen-client`.
 
@@ -101,6 +129,13 @@ export function createUser(name: string): Promise<string> { return callApi("user
 export function getUser(id: string): Promise<User | undefined> { return callApi("users", "getUser", [id]); }
 ```
 
+#### Connect client to server
+To establish the connection from the client to the server, you need to specify which URL to call. This example is using a self-hosted server running on port 3000 so it uses `http://localhost:3000`. Just call `createClient` to create the client and specify the URL.
+
+```ts
+createClient("http://localhost:3000");
+```
+
 ### Config file
 If you don't want to specify the input files and output folder every time you want to generate the client files, you can create a config file where you define these paths. You can create a `seam-rpc.config.json` file at the root of your project and use the following data:
 ```json
@@ -180,4 +215,71 @@ export async function createUser(name: string, context: SeamContext): Promise<st
 ```
 
 ### Client
-The client currently doesn't support access to the response object from the fetch.
+The client currently doesn't support access to the response object from the fetch.
+
+## Error handling
+
+### Server
+To catch errors across router functions in the server, you can use the `apiError` and `internalError` events.
+- `apiError` - Error ocurred when calling or during execution of your API function.
+- `internalError` - SeamRPC internal error. Please report if you find an error that seems like a bug or requires improvement.
+
+Example:
+```ts
+const seamSpace = await createSeamSpace(app);
+
+seamSpace.on("apiError", (error, context) => {
+    console.error(`API Error at ${context.functionName}!`, error);
+});
+
+seamSpace.on("internalError", (error, context) => {
+    console.error(`Internal Error at ${context.functionName}!`, error);
+});
+```
+
+> **Note:** The above example is to illustrate the use of error handlers and is not a complete example. Please consult the rest of the README or the examples in the examples directory.
+
+## Middleware
+
+### Client
+You can add middleware functions in the client. There's two types:
+- Pre-request - Before the request is sent. You might for example want to add some header to the request.
+- Post-request - After the request was sent. You might for example want to read some header from reponse.
+
+There's two ways to add middleware, either when creating the client:
+```ts
+createClient("http://localhost:3000", {
+    middleware: {
+        request: [
+            ctx => {
+                ctx.request.headers = {
+                    ...ctx.request.headers,
+                    "X-MyHeader": "Test"
+                };
+            },
+        ],
+        response: [
+            ctx => {
+                console.log(ctx.response.headers.get("X-SomeHeader"));
+            }
+        ]
+    }
+});
+```
+... or after creating the client:
+```ts
+const client = createClient("http://localhost:3000");
+
+client.preRequest(ctx => {
+    ctx.request.headers = {
+        ...ctx.request.headers,
+        "X-MyHeader": "Test"
+    };
+});
+
+client.postRequest(ctx => {
+    console.log(ctx.response.headers.get("X-SomeHeader"));
+});
+```
+
+> You can add as many middleware functions as you like.

package/dist/index.d.ts

@@ -1,4 +1,30 @@
 import { SeamFile, ISeamFile } from "@seam-rpc/core";
 export { SeamFile, ISeamFile };
-export declare function setApiUrl(url: string): void;
+export type SeamRequestMiddleware = (context: SeamRequestMiddlewareContext) => void | Promise<void>;
+export type SeamResponseMiddleware = (context: SeamResponseMiddlewareContext) => void | Promise<void>;
+export interface SeamRequestMiddlewareContext {
+    request: RequestInit;
+    routerName: string;
+    funcName: string;
+    args: any[];
+}
+export type SeamResponseMiddlewareContext = SeamRequestMiddlewareContext & {
+    response: Response;
+    parsedResponse: any;
+};
+export interface SeamClientOptions {
+    middleware?: {
+        request?: SeamRequestMiddleware[];
+        response?: SeamResponseMiddleware[];
+    };
+}
+export declare class SeamClient {
+    readonly baseUrl: string;
+    readonly options?: SeamClientOptions | undefined;
+    static _instance: SeamClient;
+    constructor(baseUrl: string, options?: SeamClientOptions | undefined);
+    preRequest(middleware: SeamRequestMiddleware): void;
+    postRequest(middleware: SeamResponseMiddleware): void;
+}
+export declare function createClient(baseUrl: string, options?: SeamClientOptions): SeamClient;
 export declare function callApi(routerName: string, funcName: string, args: any[]): Promise<any>;

package/dist/index.js

@@ -1,40 +1,37 @@
 import { SeamFile, extractFiles, injectFiles } from "@seam-rpc/core";
 export { SeamFile };
-let apiUrl = null;
-export function setApiUrl(url) {
-    apiUrl = url;
+export class SeamClient {
+    constructor(baseUrl, options) {
+        this.baseUrl = baseUrl;
+        this.options = options;
+        SeamClient._instance = this;
+    }
+    preRequest(middleware) {
+        this.options?.middleware?.request?.push(middleware);
+    }
+    postRequest(middleware) {
+        this.options?.middleware?.response?.push(middleware);
+    }
+}
+export function createClient(baseUrl, options) {
+    return new SeamClient(baseUrl, options);
 }
 export async function callApi(routerName, funcName, args) {
-    if (!apiUrl)
-        throw new Error("Missing API URL");
-    let req;
-    const { json, files, paths } = extractFiles(args);
-    if (files.length > 0) {
-        const formData = new FormData();
-        formData.append("json", JSON.stringify(json));
-        formData.append("paths", JSON.stringify(paths));
-        for (let i = 0; i < files.length; i++) {
-            const file = files[i];
-            const blob = new Blob([new Uint8Array(file.data)], {
-                type: file.mimeType || "application/octet-stream",
+    if (!SeamClient._instance)
+        throw new Error("Seam Client not instantiated.");
+    const seamClient = SeamClient._instance;
+    const req = buildRequest(args);
+    const url = `${seamClient.baseUrl}/${routerName}/${funcName}`;
+    if (seamClient.options?.middleware?.request) {
+        for (const mw of seamClient.options.middleware.request) {
+            await mw({
+                request: req,
+                routerName,
+                funcName,
+                args,
             });
-            formData.append(`file-${i}`, blob, file.fileName || `file-${i}`);
         }
-        req = {
-            method: "POST",
-            body: formData,
-        };
     }
-    else {
-        req = {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify(args),
-        };
-    }
-    const url = `${apiUrl}/${routerName}/${funcName}`;
     let res;
     try {
         res = await fetch(url, req);
@@ -72,6 +69,48 @@ export async function callApi(routerName, funcName, args) {
             }
         }
         injectFiles(jsonPart, responseFiles);
+        if (seamClient.options?.middleware?.response) {
+            for (const mw of seamClient.options.middleware.response) {
+                await mw({
+                    request: req,
+                    response: res,
+                    parsedResponse: jsonPart.result,
+                    routerName,
+                    funcName,
+                    args,
+                });
+            }
+        }
         return jsonPart.result;
     }
 }
+function buildRequest(args) {
+    let req;
+    const { json, files, paths } = extractFiles(args);
+    if (files.length > 0) {
+        const formData = new FormData();
+        formData.append("json", JSON.stringify(json));
+        formData.append("paths", JSON.stringify(paths));
+        for (let i = 0; i < files.length; i++) {
+            const file = files[i];
+            const blob = new Blob([new Uint8Array(file.data)], {
+                type: file.mimeType || "application/octet-stream",
+            });
+            formData.append(`file-${i}`, blob, file.fileName || `file-${i}`);
+        }
+        req = {
+            method: "POST",
+            body: formData,
+        };
+    }
+    else {
+        req = {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(args),
+        };
+    }
+    return req;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seam-rpc/client",
-  "version": "2.2.1",
+  "version": "3.0.1",
   "main": "./dist/index.js",
   "type": "module",
   "files": [