@seam-rpc/core 1.0.1 → 1.0.3

package/README.md

@@ -0,0 +1,144 @@
+<img width="1940" height="829" alt="image" src="https://github.com/user-attachments/assets/8a4a8a8b-1b57-4c1e-b6bb-ebab81ba8a32" />
+
+# SeamRPC
+
+## About
+SeamRPC is a simple RPC library for client-server communication using TypeScript using Express for the server.
+
+Making requests to the server is as simple as calling a function and SeamRPC sends it to server for you under the hood.
+
+## Setup
+### Server
+Implement your API functions in a TypeScript file. It's recommended to split different routes into different files, all inside the same folder. You can also optionally include JSDoc comments for the functions. The returned value of an API function is sent from the server to the client. If an error is thrown in the API function in the server, the function throws an error in the client as well (Seam RPC internally responds with HTTP code 400 which the client interprets as an error).
+
+> **Note:** For consistency reasons between server and client API functions, Seam RPC requires all API functions to return a Promise.
+
+**Example:**
+```
+server-app
+  ├─ index.ts
+  └─ api
+     ├─ users.ts
+     └─ posts.ts
+```
+
+`api/users.ts`
+```ts
+import { SeamFile } from "@seam-rpc/server";
+
+export interface User {
+    id: string;
+    name: string;
+}
+
+const users: User[] = [];
+
+/**
+ * Creates a new user and returns its ID.
+ * @param name The name of the user.
+ * @returns ID of the newly created user.
+ */
+export async function createUser(name: string): Promise<string> {
+    const user = {
+        id: Date.now().toString(),
+        name
+    };
+    users.push(user);
+    return user.id;
+}
+
+/**
+ * Gets a user by ID.
+ * @param id The ID of the user.
+ * @returns The user object.
+ */
+export async function getUser(id: string): Promise<User | undefined> {
+    const user = users.find(e => e.id == id);
+    if (user)
+        return user;
+    else
+        throw new Error("user not found");
+}
+```
+
+### 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`.
+
+- `input-files` - Specify what files to generate the client files from. You can use [glob pattern](https://en.wikipedia.org/wiki/Glob_(programming)) to specify the files.
+- `output-folder` - Specify the folder where to store the generated client api files.
+
+**Example:**
+`seam-rpc gen-client ./src/api/* ../server-app/src/api`
+
+```
+client-app
+  ├─ index.ts
+  └─ api
+     ├─ users.ts
+     └─ posts.ts
+```
+The api folder in the client contains the generated API client files, and should not be manually edited.
+
+The generated `api/users.ts` file:
+> Notice that the JSDoc comments are included in the client files.
+```ts
+import { callApi, SeamFile, ISeamFile } from "@seam-rpc/client";
+export interface User {
+    id: string;
+    name: string;
+}
+/**
+ * Creates a new user and returns its ID.
+ * @param name The name of the user.
+ * @returns ID of the newly created user.
+ */
+export function createUser(name: string): Promise<string> { return callApi("users", "createUser", [name]); }
+/**
+ * Gets a user by ID.
+ * @param id The ID of the user.
+ * @returns The user object.
+ */
+export function getUser(id: string): Promise<User | undefined> { return callApi("users", "getUser", [id]); }
+```
+
+### 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
+{
+    "inputFiles": "./src/api/*",
+    "outputFolder": "../client/src/api"
+}
+```
+or you can automatically generate a file using `seam-rpc gen-config [input-files] [output-folder]`. If you don't specify the input files and output folder, it will use the default paths (see JSON above).
+
+## Uploading and downloading files
+Both server and client can send files seamlessly. Just use the SeamFile class for this. You can have a parameter as a file or an array/object containing a file. You can have deeply nested files inside objects.
+
+A SeamFile has 3 properties:
+- `data` - binary data
+- `fileName` (optional) - name of the file
+- `mimeType` (optional) - The MIME type of the file ([Learn more](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types))
+
+
+**Example:**
+```ts
+interface UserData {
+    id: string;
+    name: string;
+    avatar: SeamFile;
+}
+
+export async function updateUser(userId: string, userData: UserData): Promise<void> {
+    if (userData.avatar.mimeType != "image/png" && userData.avatar.mimeType != "image/jpeg")
+        throw new Error("Only PNGs and JPEGs allowed for avatar.");
+
+    users[userId].name = userData.name;
+    users[userId].avatar = userData.avatar.fileName;
+    writeFileSync(`../avatars/${userData.avatar.fileName}`, userData.avatar.data);
+}
+```
+
+## Important notices
+- The generated client files contain all imports from the api implementation file in the backend that import from the current relative folder (`./`). This is the simplest way I have to include imports (at least for now). It may import functions and unused symbols but that shouldn't be too worrying.
+- Don't include backend/server functions inside the server api files.
+- Only exported functions will be included in the client generated files.

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export interface ISeamFile {
+    readonly data: Uint8Array;
+    readonly fileName?: string;
+    readonly mimeType?: string;
+}
+export declare class SeamFile implements ISeamFile {
+    readonly data: Uint8Array;
+    readonly fileName?: string | undefined;
+    readonly mimeType?: string | undefined;
+    constructor(data: Uint8Array, fileName?: string | undefined, mimeType?: string | undefined);
+    static fromJSON(data: ISeamFile): SeamFile;
+}
+export declare function extractFiles(input: unknown): {
+    json: any;
+    files: SeamFile[];
+    paths: (string | number)[][];
+};
+export declare function injectFiles(json: any, files: {
+    path: (string | number)[];
+    file: ISeamFile;
+}[]): void;

package/dist/index.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SeamFile = void 0;
+exports.extractFiles = extractFiles;
+exports.injectFiles = injectFiles;
+class SeamFile {
+    constructor(data, fileName, mimeType) {
+        this.data = data;
+        this.fileName = fileName;
+        this.mimeType = mimeType;
+    }
+    static fromJSON(data) {
+        return new SeamFile(data.data, data.fileName, data.mimeType);
+    }
+}
+exports.SeamFile = SeamFile;
+function extractFiles(input) {
+    const files = [];
+    const paths = [];
+    function walk(value, path) {
+        if (value instanceof SeamFile) {
+            files.push(value);
+            paths.push(path);
+            return null;
+        }
+        if (Array.isArray(value)) {
+            return value.map((e, index) => walk(e, [...path, index]));
+        }
+        if (value && typeof value === "object") {
+            return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, walk(v, [...path, k])]));
+        }
+        return value;
+    }
+    return {
+        json: walk(input, []),
+        files,
+        paths,
+    };
+}
+function injectFiles(json, files) {
+    for (const file of files) {
+        let value = json;
+        for (let i = 0; i < file.path.length; i++) {
+            const key = file.path[i];
+            if (i < file.path.length - 1)
+                value = value[key];
+            else
+                value[key] = SeamFile.fromJSON(file.file);
+        }
+    }
+}

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@seam-rpc/core",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "",
   "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },

package/src/index.ts

@@ -1,61 +0,0 @@
-export interface ISeamFile {
-    readonly data: Uint8Array;
-    readonly fileName?: string;
-    readonly mimeType?: string;
-}
-
-export class SeamFile implements ISeamFile {
-    constructor(
-        public readonly data: Uint8Array,
-        public readonly fileName?: string,
-        public readonly mimeType?: string
-    ) { }
-
-    public static fromJSON(data: ISeamFile): SeamFile {
-        return new SeamFile(data.data, data.fileName, data.mimeType);
-    }
-}
-
-export function extractFiles(input: unknown) {
-    const files: SeamFile[] = [];
-    const paths: (string | number)[][] = [];
-
-    function walk(value: unknown, path: (string | number)[]): any {
-        if (value instanceof SeamFile) {
-            files.push(value);
-            paths.push(path);
-            return null;
-        }
-
-        if (Array.isArray(value)) {
-            return value.map((e, index) => walk(e, [...path, index]));
-        }
-
-        if (value && typeof value === "object") {
-            return Object.fromEntries(
-                Object.entries(value).map(([k, v]) => [k, walk(v, [...path, k])])
-            );
-        }
-
-        return value;
-    }
-
-    return {
-        json: walk(input, []),
-        files,
-        paths,
-    };
-}
-
-export function injectFiles(json: any, files: { path: (string | number)[], file: ISeamFile }[]) {
-    for (const file of files) {
-        let value = json;
-        for (let i = 0; i < file.path.length; i++) {
-            const key = file.path[i];
-            if (i < file.path.length - 1)
-                value = value[key];
-            else
-                value[key] = SeamFile.fromJSON(file.file);
-        }
-    }
-}

package/tsconfig.json

@@ -1,113 +0,0 @@
-{
-  "compilerOptions": {
-    /* Visit https://aka.ms/tsconfig to read more about this file */
-
-    /* Projects */
-    // "incremental": true,                              /* Save .tsbuildinfo files to allow for incremental compilation of projects. */
-    // "composite": true,                                /* Enable constraints that allow a TypeScript project to be used with project references. */
-    // "tsBuildInfoFile": "./.tsbuildinfo",              /* Specify the path to .tsbuildinfo incremental compilation file. */
-    // "disableSourceOfProjectReferenceRedirect": true,  /* Disable preferring source files instead of declaration files when referencing composite projects. */
-    // "disableSolutionSearching": true,                 /* Opt a project out of multi-project reference checking when editing. */
-    // "disableReferencedProjectLoad": true,             /* Reduce the number of projects loaded automatically by TypeScript. */
-
-    /* Language and Environment */
-    "target": "es2016",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
-    // "lib": [],                                        /* Specify a set of bundled library declaration files that describe the target runtime environment. */
-    // "jsx": "preserve",                                /* Specify what JSX code is generated. */
-    // "libReplacement": true,                           /* Enable lib replacement. */
-    // "experimentalDecorators": true,                   /* Enable experimental support for legacy experimental decorators. */
-    // "emitDecoratorMetadata": true,                    /* Emit design-type metadata for decorated declarations in source files. */
-    // "jsxFactory": "",                                 /* Specify the JSX factory function used when targeting React JSX emit, e.g. 'React.createElement' or 'h'. */
-    // "jsxFragmentFactory": "",                         /* Specify the JSX Fragment reference used for fragments when targeting React JSX emit e.g. 'React.Fragment' or 'Fragment'. */
-    // "jsxImportSource": "",                            /* Specify module specifier used to import the JSX factory functions when using 'jsx: react-jsx*'. */
-    // "reactNamespace": "",                             /* Specify the object invoked for 'createElement'. This only applies when targeting 'react' JSX emit. */
-    // "noLib": true,                                    /* Disable including any library files, including the default lib.d.ts. */
-    // "useDefineForClassFields": true,                  /* Emit ECMAScript-standard-compliant class fields. */
-    // "moduleDetection": "auto",                        /* Control what method is used to detect module-format JS files. */
-
-    /* Modules */
-    "module": "commonjs",                                /* Specify what module code is generated. */
-    "rootDir": "./src",                                  /* Specify the root folder within your source files. */
-    // "moduleResolution": "node10",                     /* Specify how TypeScript looks up a file from a given module specifier. */
-    // "baseUrl": "./",                                  /* Specify the base directory to resolve non-relative module names. */
-    // "paths": {},                                      /* Specify a set of entries that re-map imports to additional lookup locations. */
-    // "rootDirs": [],                                   /* Allow multiple folders to be treated as one when resolving modules. */
-    // "typeRoots": [],                                  /* Specify multiple folders that act like './node_modules/@types'. */
-    // "types": [],                                      /* Specify type package names to be included without being referenced in a source file. */
-    // "allowUmdGlobalAccess": true,                     /* Allow accessing UMD globals from modules. */
-    // "moduleSuffixes": [],                             /* List of file name suffixes to search when resolving a module. */
-    // "allowImportingTsExtensions": true,               /* Allow imports to include TypeScript file extensions. Requires '--moduleResolution bundler' and either '--noEmit' or '--emitDeclarationOnly' to be set. */
-    // "rewriteRelativeImportExtensions": true,          /* Rewrite '.ts', '.tsx', '.mts', and '.cts' file extensions in relative import paths to their JavaScript equivalent in output files. */
-    // "resolvePackageJsonExports": true,                /* Use the package.json 'exports' field when resolving package imports. */
-    // "resolvePackageJsonImports": true,                /* Use the package.json 'imports' field when resolving imports. */
-    // "customConditions": [],                           /* Conditions to set in addition to the resolver-specific defaults when resolving imports. */
-    // "noUncheckedSideEffectImports": true,             /* Check side effect imports. */
-    // "resolveJsonModule": true,                        /* Enable importing .json files. */
-    // "allowArbitraryExtensions": true,                 /* Enable importing files with any extension, provided a declaration file is present. */
-    // "noResolve": true,                                /* Disallow 'import's, 'require's or '<reference>'s from expanding the number of files TypeScript should add to a project. */
-
-    /* JavaScript Support */
-    // "allowJs": true,                                  /* Allow JavaScript files to be a part of your program. Use the 'checkJS' option to get errors from these files. */
-    // "checkJs": true,                                  /* Enable error reporting in type-checked JavaScript files. */
-    // "maxNodeModuleJsDepth": 1,                        /* Specify the maximum folder depth used for checking JavaScript files from 'node_modules'. Only applicable with 'allowJs'. */
-
-    /* Emit */
-    "declaration": true,                              /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
-    // "declarationMap": true,                           /* Create sourcemaps for d.ts files. */
-    // "emitDeclarationOnly": true,                      /* Only output d.ts files and not JavaScript files. */
-    // "sourceMap": true,                                /* Create source map files for emitted JavaScript files. */
-    // "inlineSourceMap": true,                          /* Include sourcemap files inside the emitted JavaScript. */
-    // "noEmit": true,                                   /* Disable emitting files from a compilation. */
-    // "outFile": "./",                                  /* Specify a file that bundles all outputs into one JavaScript file. If 'declaration' is true, also designates a file that bundles all .d.ts output. */
-    "outDir": "./dist",                                   /* Specify an output folder for all emitted files. */
-    // "removeComments": true,                           /* Disable emitting comments. */
-    // "importHelpers": true,                            /* Allow importing helper functions from tslib once per project, instead of including them per-file. */
-    // "downlevelIteration": true,                       /* Emit more compliant, but verbose and less performant JavaScript for iteration. */
-    // "sourceRoot": "",                                 /* Specify the root path for debuggers to find the reference source code. */
-    // "mapRoot": "",                                    /* Specify the location where debugger should locate map files instead of generated locations. */
-    // "inlineSources": true,                            /* Include source code in the sourcemaps inside the emitted JavaScript. */
-    // "emitBOM": true,                                  /* Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files. */
-    // "newLine": "crlf",                                /* Set the newline character for emitting files. */
-    // "stripInternal": true,                            /* Disable emitting declarations that have '@internal' in their JSDoc comments. */
-    // "noEmitHelpers": true,                            /* Disable generating custom helper functions like '__extends' in compiled output. */
-    // "noEmitOnError": true,                            /* Disable emitting files if any type checking errors are reported. */
-    // "preserveConstEnums": true,                       /* Disable erasing 'const enum' declarations in generated code. */
-    // "declarationDir": "./",                           /* Specify the output directory for generated declaration files. */
-
-    /* Interop Constraints */
-    // "isolatedModules": true,                          /* Ensure that each file can be safely transpiled without relying on other imports. */
-    // "verbatimModuleSyntax": true,                     /* Do not transform or elide any imports or exports not marked as type-only, ensuring they are written in the output file's format based on the 'module' setting. */
-    // "isolatedDeclarations": true,                     /* Require sufficient annotation on exports so other tools can trivially generate declaration files. */
-    // "erasableSyntaxOnly": true,                       /* Do not allow runtime constructs that are not part of ECMAScript. */
-    // "allowSyntheticDefaultImports": true,             /* Allow 'import x from y' when a module doesn't have a default export. */
-    "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
-    // "preserveSymlinks": true,                         /* Disable resolving symlinks to their realpath. This correlates to the same flag in node. */
-    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
-
-    /* Type Checking */
-    "strict": true,                                      /* Enable all strict type-checking options. */
-    // "noImplicitAny": true,                            /* Enable error reporting for expressions and declarations with an implied 'any' type. */
-    // "strictNullChecks": true,                         /* When type checking, take into account 'null' and 'undefined'. */
-    // "strictFunctionTypes": true,                      /* When assigning functions, check to ensure parameters and the return values are subtype-compatible. */
-    // "strictBindCallApply": true,                      /* Check that the arguments for 'bind', 'call', and 'apply' methods match the original function. */
-    // "strictPropertyInitialization": true,             /* Check for class properties that are declared but not set in the constructor. */
-    // "strictBuiltinIteratorReturn": true,              /* Built-in iterators are instantiated with a 'TReturn' type of 'undefined' instead of 'any'. */
-    // "noImplicitThis": true,                           /* Enable error reporting when 'this' is given the type 'any'. */
-    // "useUnknownInCatchVariables": true,               /* Default catch clause variables as 'unknown' instead of 'any'. */
-    // "alwaysStrict": true,                             /* Ensure 'use strict' is always emitted. */
-    // "noUnusedLocals": true,                           /* Enable error reporting when local variables aren't read. */
-    // "noUnusedParameters": true,                       /* Raise an error when a function parameter isn't read. */
-    // "exactOptionalPropertyTypes": true,               /* Interpret optional property types as written, rather than adding 'undefined'. */
-    // "noImplicitReturns": true,                        /* Enable error reporting for codepaths that do not explicitly return in a function. */
-    // "noFallthroughCasesInSwitch": true,               /* Enable error reporting for fallthrough cases in switch statements. */
-    // "noUncheckedIndexedAccess": true,                 /* Add 'undefined' to a type when accessed using an index. */
-    // "noImplicitOverride": true,                       /* Ensure overriding members in derived classes are marked with an override modifier. */
-    // "noPropertyAccessFromIndexSignature": true,       /* Enforces using indexed accessors for keys declared using an indexed type. */
-    // "allowUnusedLabels": true,                        /* Disable error reporting for unused labels. */
-    // "allowUnreachableCode": true,                     /* Disable error reporting for unreachable code. */
-
-    /* Completeness */
-    // "skipDefaultLibCheck": true,                      /* Skip type checking .d.ts files that are included with TypeScript. */
-    "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
-  }
-}