arri 0.12.0 → 0.12.4

package/README.md

@@ -1,6 +1,42 @@
 # Arri RPC
 
-## Installation
+Typescript implementation of Arri RPC. It's built on top of [H3](https://github.com/unjs/h3) and uses [esbuild](https://esbuild.github.io/) for bundling.
+
+## Table of Contents
+
+-   [Quickstart](#quickstart)
+-   [Manual Setup](#manual-setup)
+    -   [Install Dependencies](#install-dependencies)
+    -   [Scaffold Your Project](#scaffold-your-project)
+-   [Usage](#usage)
+    -   [File-Based Routing](#file-based-routing)
+    -   [Manual Routing](#manual-routing)
+    -   [Adding Non-RPC Routes](#adding-non-rpc-routes)
+    -   [Adding Middleware](#adding-middleware)
+-   [Key Concepts](#key-concepts)
+    -   [Arri Definition File](#arri-definition-file)
+    -   [How Procedures Map To Endpoints](#how-procedures-map-to-endpoints)
+-   [Arri CLI](#arri-cli)
+
+## Quickstart
+
+```bash
+# npm
+npx arri init [project-name]
+cd [project-name]
+npm install
+npm run dev
+
+# pnpm
+pnpm dlx arri init [project-name]
+cd [project-name]
+pnpm install
+pnpm run dev
+```
+
+## Manual Setup
+
+### Install Dependencies
 
 ```bash
 # npm
@@ -10,7 +46,32 @@ npm install arri arri-validate
 pnpm install arri arri-validate
 ```
 
-## Basic Setup Example
+### Scaffold Your Project
+
+A basic Arri app directory looks something like this:
+
+```fs
+|-- project-dir
+    |-- .arri // temp files go here
+    |-- .output // final bundle goes here
+    |-- src
+        |-- procedures // .rpc.ts files go here
+        |-- app.ts
+    |-- arri.config.ts
+    |-- package.json
+    |-- tsconfig.json
+|
+```
+
+Both `.arri` and `.output` should be added to your `.gitignore` file
+
+```txt
+.arri
+.output
+node_modules
+```
+
+#### Configuration File
 
 Create an `arri.config.ts` in the project directory
 
@@ -37,7 +98,9 @@ export default defineConfig({
 });
 ```
 
-Create an `app.ts` file in the source directory
+##### App Entry
+
+Create an app entry file in your src directory. The name of the file must match whatever you put as the `entry` in your `arri.config.ts`.
 
 ```ts
 // ./src/app.ts
@@ -63,24 +126,30 @@ app.rpc("sayHello", {
 export default app;
 ```
 
+##### Package.json
+
 Setup your npm scripts:
 
 ```json
 {
+    "name": "my-arri-app",
+    "type": "module",
     "scripts": {
         "dev": "arri dev",
         "build": "arri build"
+    },
+    "dependencies": {
+        ...
+    },
+    "devDependencies": {
+        ...
     }
 }
 ```
 
-Start the dev server:
-
-```bash
-npm run dev
-```
+## Usage
 
-## File Based Routing
+### File Based Routing
 
 Arri RPC comes with an optional file based router that will automatically register functions in the `./procedures` directory that end with the `.rpc.ts` file extension.
 
@@ -115,7 +184,7 @@ export default defineRpc({
 });
 ```
 
-### Customizing the File Based Router
+#### Customizing the File Based Router
 
 ```ts
 export default defineConfig({
@@ -125,9 +194,27 @@ export default defineConfig({
 });
 ```
 
-## Adding Non-RPC Endpoints
+### Manual Routing
+
+```ts
+// using the app instance
+const app = new ArriApp()
+app.rpc('sayHello', {...})
+
+// using a sub-router
+const app = new ArriApp();
+const router = new ArriRoute();
+router.rpc('sayHello', {...})
+app.use(router)
+```
+
+### Adding Non-RPC Routes
+
+You can also add generic endpoints for instances when a message-based RPC endpoint doesn't fit.
 
 ```ts
+// using the app instance
+const app = new ArriApp();
 app.route({
     method: "get",
     path: "/hello-world",
@@ -135,25 +222,192 @@ app.route({
         return "hello world";
     },
 });
+
+// using a sub-router
+const app = new ArriApp();
+const router = new ArriRouter();
+router.route({
+    method: "get",
+    path: "/hello-world",
+    handler(event) {
+        return "hello world",
+    }
+})
+app.use(router)
 ```
 
-## Creating sub routers
+### Adding Middleware
 
 ```ts
-import { ArriApp, ArriRouter } from "arri";
-
 const app = new ArriApp();
-const router = new ArriRouter();
 
-router.rpc({
-    // rpc config
+const requestLoggerMiddleware = defineMiddleware((event) => {
+    console.log(`new request at ${event.path}`);
 });
 
-router.route({
-    // route config
+app.use(requestLoggerMiddleware);
+```
+
+#### Adding to the RPC Context
+
+Any values added to `event.context` will become available in the rpc instance
+
+```ts
+const authMiddleware = defineMiddleware(async (event) => {
+    // assume you did something to get the user from the request
+    event.context.user = {
+        id: 1,
+        name: "John Doe",
+        email: "johndoe@gmail.com",
+    };
+});
+
+app.rpc("sayHello", {
+    params: undefined,
+    response: a.object({
+        message: a.string(),
+    }),
+    // user is available here
+    handler({ user }) {
+        return {
+            message: `Hello ${user.name}`,
+        };
+    },
 });
+```
+
+To get type safety for these new properties create a `.d.ts` file and augment the `EventContext` provided by `H3`
+
+```ts
+import "h3";
+
+declare module "h3" {
+    interface H3EventContext {
+        user?: {
+            id: number;
+            name: string;
+            email: string;
+        };
+    }
+}
+```
+
+### Adding Client Generators
+
+Right now Arri RPC has client generators for the following languages:
+
+-   typescript
+-   dart
+
+```ts
+// arri.config.ts
+import { defineConfig } from "arri";
+import { typescriptClientGenerator, dartClientGenerator } from "arri/dist/codegen";
+
+export default defineConfig({
+    // rest of config
+    clientGenerators: [
+        typescriptClientGenerator({...}),
+        dartClientGenerator({...})
+    ]
+});
+```
+
+## Key Concepts
+
+### Arri Definition File
+
+The server generates a `__definition.json` file that acts as a schema for all of the procedures and models in the API. By default this schema is viewable from `/__definition` when the server is running, but it can be modified. The endpoint is also relative to the `rpcRoutePrefix` option.
+
+It looks something like this:
+
+```json
+{
+    "procedures": {
+        "sayHello": {
+            "path": "/say-hello",
+            "method": "post",
+            "params": "SayHelloParams",
+            "response": "SayHelloResponse"
+        }
+        // rest of procedures
+    },
+    "models": {
+        "SayHelloParams": {
+            "properties": {
+                "name": {
+                    "type": "string"
+                }
+            }
+        },
+        "SayHelloResponse": {
+            "properties": {
+                "message": {
+                    "type": "string"
+                }
+            }
+        }
+        // rest of models
+    }
+}
+```
+
+Arri is able to use this schema file to automatically generate clients in multiple languages. In this way it works similarly to an Open API schema, but with much better code-generation support. I've made a lot of deliberate choices in designing this schema to make code-generation easier and more consistent across languages. For example, Arri schemas use a superset of [JSON Type Definition](https://jsontypedef.com/) for their models instead of JSON Schema.
+
+### How Procedures Map To Endpoints
+
+Every procedure maps to a different url based on it's name. For example given the following file structure:
+
+```fs
+|--src
+   |--procedures
+      |--getStatus.rpc.ts
+      |--users
+         |--getUser.rpc.ts
+         |--updateUser.rpc.ts
+```
+
+We will get the following endpoints:
+
+```txt
+POST /get-status
+POST /users/get-user
+POST /users/update-user
+
+(Note: these will always be relative to the `rpcRoutePrefix` option)
+```
+
+By default all procedures will become post requests, but you can change this when creating a procedure:
+
+```ts
+// procedures/users/getUser.rpc.ts
+export default defineRpc({
+    method: "get",
+    // rest of config
+});
+```
+
+The supported HTTP methods are as follows:
+
+-   post
+-   get
+-   delete
+-   patch
+-   put
+
+When using a get method the RPC params will be mapped as query parameters which will be coerced into their type using the `a.coerce` method from `arri-validate`. Get methods support all basic scalar types however arrays and nested objects are not supported.
+
+## Arri CLI
+
+```bash
+# start the dev server
+arri dev [flags]
+
+# create a production build
+arri build [flags]
 
-app.use(router);
+# create a new project
+arri init [dir]
 ```
 
 ## Developing

package/dist/cli.cjs

@@ -45,6 +45,10 @@ const prettier__default = /*#__PURE__*/_interopDefaultCompat(prettier);
 const chokidar__default = /*#__PURE__*/_interopDefaultCompat(chokidar);
 const Degit__default = /*#__PURE__*/_interopDefaultCompat(Degit);
 
+const DEFAULT_SERVER_ENTRY_FILE = "__default_arri_server.js";
+const DEFAULT_CODEGEN_FILE = "__default_arri_codegen.js";
+const SERVER_ENTRY_OUTPUT = "server.js";
+const CODEGEN_OUTPUT = "codegen.js";
 async function setupWorkingDir(config) {
   const arriDir = path__default.resolve(config.rootDir, config.buildDir);
   const outDir = path__default.resolve(config.rootDir, ".output");
@@ -202,10 +206,14 @@ async function startBuild(config, skipCodeGen = false) {
   await bundleFiles(config);
   logger$2.log("Finished bundling");
   const clientCount = config.clientGenerators.length;
-  const codegenModule = path__default.resolve(config.rootDir, ".output", "codegen.js");
+  const codegenModule = path__default.resolve(
+    config.rootDir,
+    ".output",
+    CODEGEN_OUTPUT
+  );
   if (clientCount > 0 && !skipCodeGen) {
     logger$2.log("Generating clients");
-    node_child_process.execSync(`node ${codegenModule}`);
+    node_child_process.execSync(`node ${codegenModule}`, { env: process.env });
     const defJson = path__default.resolve(
       config.rootDir,
       ".output",
@@ -224,11 +232,9 @@ async function startBuild(config, skipCodeGen = false) {
   logger$2.log("Cleaning up files");
   await fs__default.rm(codegenModule);
   logger$2.log(
-    `Build finished! You can start your server by running "node .output/server.js"`
+    `Build finished! You can start your server by running "node .output/${SERVER_ENTRY_OUTPUT}"`
   );
 }
-const BUILD_ENTRY_DEFAULT_FILE = "__default_arri_server.js";
-const CODEGEN_DEFAULT_FILE = "__default_arri_codegen.js";
 async function bundleFiles(config, allowCodegen = true) {
   if (allowCodegen) {
     await esbuild.build({
@@ -237,26 +243,27 @@ async function bundleFiles(config, allowCodegen = true) {
         path__default.resolve(
           config.rootDir,
           config.buildDir,
-          CODEGEN_DEFAULT_FILE
+          DEFAULT_CODEGEN_FILE
         )
       ],
       platform: config.esbuild.platform ?? "node",
-      target: config.esbuild.target ?? "node18",
+      target: config.esbuild.target ?? "node20",
+      packages: "external",
       bundle: true,
       format: "esm",
       sourcemap: false,
-      minifyWhitespace: true,
+      minifyWhitespace: false,
       banner: {
         js: `import { createRequire as topLevelCreateRequire } from 'module';
             const require = topLevelCreateRequire(import.meta.url);`
       },
-      outfile: path__default.resolve(config.rootDir, ".output", "codegen.js")
+      outfile: path__default.resolve(config.rootDir, ".output", CODEGEN_OUTPUT)
     });
   }
   let buildEntry = path__default.resolve(
     config.rootDir,
     config.buildDir,
-    BUILD_ENTRY_DEFAULT_FILE
+    DEFAULT_SERVER_ENTRY_FILE
   );
   if (config.buildEntry) {
     const parts = config.buildEntry.split(".");
@@ -279,7 +286,7 @@ async function bundleFiles(config, allowCodegen = true) {
             const require = topLevelCreateRequire(import.meta.url);`
     },
     allowOverwrite: true,
-    outfile: path__default.resolve(config.rootDir, ".output", "server.js")
+    outfile: path__default.resolve(config.rootDir, ".output", SERVER_ENTRY_OUTPUT)
   });
 }
 async function createBuildEntryModule(config) {
@@ -310,7 +317,11 @@ void listen(toNodeListener(app.h3App), {
     public: true,
 });`;
   await fs__default.writeFile(
-    path__default.resolve(config.rootDir, config.buildDir, BUILD_ENTRY_DEFAULT_FILE),
+    path__default.resolve(
+      config.rootDir,
+      config.buildDir,
+      DEFAULT_SERVER_ENTRY_FILE
+    ),
     virtualEntry
   );
 }
@@ -346,7 +357,7 @@ async function createBuildCodegenModule(config) {
     { tabWidth: 4, parser: "typescript" }
   );
   await fs__default.writeFile(
-    path__default.resolve(config.rootDir, config.buildDir, CODEGEN_DEFAULT_FILE),
+    path__default.resolve(config.rootDir, config.buildDir, DEFAULT_CODEGEN_FILE),
     virtualModule
   );
 }
@@ -448,19 +459,26 @@ const dev = citty.defineCommand({
     await startDevServer(config$1);
   }
 });
-const startListener = (config, showQr = false) => listhen.listenAndWatch(path__default.resolve(config.rootDir, ".output", "server.js"), {
-  public: true,
-  port: config.port,
-  logger: logger$1,
-  qr: showQr
-});
+const startListener = (config, showQr = false) => listhen.listenAndWatch(
+  path__default.resolve(config.rootDir, ".output", SERVER_ENTRY_OUTPUT),
+  {
+    public: true,
+    port: config.port,
+    logger: logger$1,
+    qr: showQr
+  }
+);
 async function bundleFilesContext(config) {
   return await esbuild__namespace.context({
     ...config.esbuild,
     entryPoints: [
-      path__default.resolve(config.rootDir, config.buildDir, "entry.js")
+      path__default.resolve(
+        config.rootDir,
+        config.buildDir,
+        DEFAULT_SERVER_ENTRY_FILE
+      )
     ],
-    outfile: path__default.resolve(config.rootDir, ".output", "server.js"),
+    outfile: path__default.resolve(config.rootDir, ".output", SERVER_ENTRY_OUTPUT),
     format: "esm",
     bundle: true,
     sourcemap: true,
@@ -581,7 +599,11 @@ for (const route of routes) {
 
 export default app.h3App;`;
   await fs__default.writeFile(
-    path__default.resolve(config.rootDir, config.buildDir, "entry.js"),
+    path__default.resolve(
+      config.rootDir,
+      config.buildDir,
+      DEFAULT_SERVER_ENTRY_FILE
+    ),
     virtualEntry
   );
 }

package/dist/cli.mjs

@@ -21,6 +21,10 @@ import Degit from 'degit';
 import 'h3';
 import 'arri-validate';
 
+const DEFAULT_SERVER_ENTRY_FILE = "__default_arri_server.js";
+const DEFAULT_CODEGEN_FILE = "__default_arri_codegen.js";
+const SERVER_ENTRY_OUTPUT = "server.js";
+const CODEGEN_OUTPUT = "codegen.js";
 async function setupWorkingDir(config) {
   const arriDir = path.resolve(config.rootDir, config.buildDir);
   const outDir = path.resolve(config.rootDir, ".output");
@@ -178,10 +182,14 @@ async function startBuild(config, skipCodeGen = false) {
   await bundleFiles(config);
   logger$2.log("Finished bundling");
   const clientCount = config.clientGenerators.length;
-  const codegenModule = path.resolve(config.rootDir, ".output", "codegen.js");
+  const codegenModule = path.resolve(
+    config.rootDir,
+    ".output",
+    CODEGEN_OUTPUT
+  );
   if (clientCount > 0 && !skipCodeGen) {
     logger$2.log("Generating clients");
-    execSync(`node ${codegenModule}`);
+    execSync(`node ${codegenModule}`, { env: process.env });
     const defJson = path.resolve(
       config.rootDir,
       ".output",
@@ -200,11 +208,9 @@ async function startBuild(config, skipCodeGen = false) {
   logger$2.log("Cleaning up files");
   await fs.rm(codegenModule);
   logger$2.log(
-    `Build finished! You can start your server by running "node .output/server.js"`
+    `Build finished! You can start your server by running "node .output/${SERVER_ENTRY_OUTPUT}"`
   );
 }
-const BUILD_ENTRY_DEFAULT_FILE = "__default_arri_server.js";
-const CODEGEN_DEFAULT_FILE = "__default_arri_codegen.js";
 async function bundleFiles(config, allowCodegen = true) {
   if (allowCodegen) {
     await build$1({
@@ -213,26 +219,27 @@ async function bundleFiles(config, allowCodegen = true) {
         path.resolve(
           config.rootDir,
           config.buildDir,
-          CODEGEN_DEFAULT_FILE
+          DEFAULT_CODEGEN_FILE
         )
       ],
       platform: config.esbuild.platform ?? "node",
-      target: config.esbuild.target ?? "node18",
+      target: config.esbuild.target ?? "node20",
+      packages: "external",
       bundle: true,
       format: "esm",
       sourcemap: false,
-      minifyWhitespace: true,
+      minifyWhitespace: false,
       banner: {
         js: `import { createRequire as topLevelCreateRequire } from 'module';
             const require = topLevelCreateRequire(import.meta.url);`
       },
-      outfile: path.resolve(config.rootDir, ".output", "codegen.js")
+      outfile: path.resolve(config.rootDir, ".output", CODEGEN_OUTPUT)
     });
   }
   let buildEntry = path.resolve(
     config.rootDir,
     config.buildDir,
-    BUILD_ENTRY_DEFAULT_FILE
+    DEFAULT_SERVER_ENTRY_FILE
   );
   if (config.buildEntry) {
     const parts = config.buildEntry.split(".");
@@ -255,7 +262,7 @@ async function bundleFiles(config, allowCodegen = true) {
             const require = topLevelCreateRequire(import.meta.url);`
     },
     allowOverwrite: true,
-    outfile: path.resolve(config.rootDir, ".output", "server.js")
+    outfile: path.resolve(config.rootDir, ".output", SERVER_ENTRY_OUTPUT)
   });
 }
 async function createBuildEntryModule(config) {
@@ -286,7 +293,11 @@ void listen(toNodeListener(app.h3App), {
     public: true,
 });`;
   await fs.writeFile(
-    path.resolve(config.rootDir, config.buildDir, BUILD_ENTRY_DEFAULT_FILE),
+    path.resolve(
+      config.rootDir,
+      config.buildDir,
+      DEFAULT_SERVER_ENTRY_FILE
+    ),
     virtualEntry
   );
 }
@@ -322,7 +333,7 @@ async function createBuildCodegenModule(config) {
     { tabWidth: 4, parser: "typescript" }
   );
   await fs.writeFile(
-    path.resolve(config.rootDir, config.buildDir, CODEGEN_DEFAULT_FILE),
+    path.resolve(config.rootDir, config.buildDir, DEFAULT_CODEGEN_FILE),
     virtualModule
   );
 }
@@ -424,19 +435,26 @@ const dev = defineCommand({
     await startDevServer(config);
   }
 });
-const startListener = (config, showQr = false) => listenAndWatch(path.resolve(config.rootDir, ".output", "server.js"), {
-  public: true,
-  port: config.port,
-  logger: logger$1,
-  qr: showQr
-});
+const startListener = (config, showQr = false) => listenAndWatch(
+  path.resolve(config.rootDir, ".output", SERVER_ENTRY_OUTPUT),
+  {
+    public: true,
+    port: config.port,
+    logger: logger$1,
+    qr: showQr
+  }
+);
 async function bundleFilesContext(config) {
   return await esbuild.context({
     ...config.esbuild,
     entryPoints: [
-      path.resolve(config.rootDir, config.buildDir, "entry.js")
+      path.resolve(
+        config.rootDir,
+        config.buildDir,
+        DEFAULT_SERVER_ENTRY_FILE
+      )
     ],
-    outfile: path.resolve(config.rootDir, ".output", "server.js"),
+    outfile: path.resolve(config.rootDir, ".output", SERVER_ENTRY_OUTPUT),
     format: "esm",
     bundle: true,
     sourcemap: true,
@@ -557,7 +575,11 @@ for (const route of routes) {
 
 export default app.h3App;`;
   await fs.writeFile(
-    path.resolve(config.rootDir, config.buildDir, "entry.js"),
+    path.resolve(
+      config.rootDir,
+      config.buildDir,
+      DEFAULT_SERVER_ENTRY_FILE
+    ),
     virtualEntry
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arri",
-  "version": "0.12.0",
+  "version": "0.12.4",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -30,10 +30,10 @@
     "pathe": "^1.1.1",
     "prettier": "^3.0.3",
     "scule": "^1.0.0",
-    "arri-codegen-dart": "0.12.0",
-    "arri-codegen-ts": "0.12.0",
-    "arri-codegen-utils": "0.12.0",
-    "arri-validate": "0.12.0"
+    "arri-codegen-dart": "0.12.4",
+    "arri-codegen-utils": "0.12.4",
+    "arri-codegen-ts": "0.12.4",
+    "arri-validate": "0.12.4"
   },
   "peerDependencies": {
     "listhen": "1.x"