arri 0.12.8 → 0.15.1

package/README.md

@@ -149,7 +149,9 @@ Setup your npm scripts:
 
 ## Usage
 
-### File Based Routing
+### Creating Procedures
+
+#### 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.
 
@@ -184,7 +186,7 @@ export default defineRpc({
 });
 ```
 
-#### Customizing the File Based Router
+##### Customizing the File Based Router
 
 ```ts
 export default defineConfig({
@@ -194,7 +196,7 @@ export default defineConfig({
 });
 ```
 
-### Manual Routing
+#### Manual Routing
 
 ```ts
 // using the app instance
@@ -208,6 +210,76 @@ router.rpc('sayHello', {...})
 app.use(router)
 ```
 
+#### Creating Event Stream Procedures
+
+Event stream procedures make use of [Server Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) to stream events to clients.
+
+Normal events will have the event type `message`. Error events will have the event type `error`, and a `done` event will be sent when closing the connection. Additionally the `EventStreamConnection` will periodically since a `ping` event to keep the connection alive
+
+```ts
+/// standard event ///
+id: string | undefined;
+event: "message";
+data: Response; // whatever you have specified as the response serialized to json
+
+/// error event ///
+id: string | undefined;
+event: "error";
+data: ArriRequestError; // serialized to json
+
+/// done event ///
+event: "done";
+data: "this stream has ended";
+
+/// ping event ///
+event: "ping";
+data: "";
+```
+
+##### Example Usage:
+
+```ts
+// procedures/users/watchUser.rpc.ts
+export default defineEventStreamRpc({
+    params: a.object({
+        userId: a.string(),
+    }),
+    response: a.object({
+        id: a.string(),
+        name: a.string(),
+        createdAt: a.timestamp(),
+        updatedAt: a.timestamp(),
+    }),
+    handler({ params, connection }) {
+        // send a message every second
+        const interval = setInterval(async () => {
+            await connection.push({
+                id: "1",
+                name: "John Doe",
+                createdAt: new Date(),
+                updatedAt: new Date(),
+            });
+        }, 1000);
+        // cleanup when the client disconnects
+        connection.on("disconnect", () => {
+            clearInterval(interval);
+        });
+        // start streaming events to the client
+        connection.start();
+    },
+});
+```
+
+#### EventStreamConnection methods
+
+```ts
+connection.push(data: Data, eventId?: string)
+connection.pushError(error: ArriRequestError, eventId?: string)
+connection.start()
+connection.end()
+connection.on(e: 'disconnect' | 'end', callback: () => any)
+```
+
 ### Adding Non-RPC Routes
 
 You can also add generic endpoints for instances when a message-based RPC endpoint doesn't fit.

package/dist/cli.cjs

@@ -9,9 +9,10 @@ const arriCodegenUtils = require('arri-codegen-utils');
 const c12 = require('c12');
 const consola = require('consola');
 const esbuild = require('esbuild');
+const esbuildPluginReplace = require('esbuild-plugin-replace');
 const path = require('pathe');
 const prettier = require('prettier');
-const config = require('./shared/arri.fa32b1ba.cjs');
+const config = require('./shared/arri.2eb37786.cjs');
 const globby = require('globby');
 const scule = require('scule');
 const arriCodegenDart = require('arri-codegen-dart');
@@ -45,10 +46,11 @@ 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";
+const GEN_APP_FILE = "__arri_app.js";
+const GEN_SERVER_ENTRY_FILE = "__arri_server.js";
+const OUT_APP_FILE = "app.js";
+const OUT_SERVER_ENTRY = "server.js";
+const OUT_CODEGEN = "codegen.js";
 async function setupWorkingDir(config) {
   const arriDir = path__default.resolve(config.rootDir, config.buildDir);
   const outDir = path__default.resolve(config.rootDir, ".output");
@@ -61,12 +63,15 @@ async function setupWorkingDir(config) {
   await fs__default.mkdir(arriDir);
   await fs__default.mkdir(outDir);
 }
-async function createRoutesModule(config) {
+async function createAppWithRoutesModule(config) {
+  const appModule = path__default.resolve(config.rootDir, config.srcDir, config.entry);
+  const appImportParts = path__default.relative(path__default.resolve(config.rootDir, config.srcDir), appModule).split(".");
+  appImportParts.pop();
   const routes = [];
   const existingRoutes = [];
   await Promise.all(
     config.procedureGlobPatterns.map(async (pattern) => {
-      const results = await getVirtualRouteBatch(pattern, config);
+      const results = await getFsRouteBatch(pattern, config);
       for (const result of results) {
         if (!existingRoutes.includes(result.name)) {
           routes.push(result);
@@ -77,22 +82,29 @@ async function createRoutesModule(config) {
   );
   routes.sort((a, b) => a.name < b.name ? -1 : 1);
   const module = await prettier__default.format(
-    `${routes.map(
+    `import app from './${appImportParts.join(".")}';
+        ${routes.map(
       (route) => `import ${route.importName} from '${route.importPath}';`
     ).join("\n")}
         const routes = [${routes.map(
       (route) => `{ id: '${route.name}', route: ${route.importName} }`
     ).join(",\n")}
         ];
-        export default routes`,
+        for(const route of routes) {
+            app.rpc({
+                name: route.id,
+                ...route.route,
+            });
+        }
+        export default app`,
     { parser: "typescript", tabWidth: 4 }
   );
   await fs__default.writeFile(
-    path__default.resolve(config.rootDir, config.buildDir, "routes.js"),
+    path__default.resolve(config.rootDir, config.buildDir, GEN_APP_FILE),
     module
   );
 }
-async function getVirtualRouteBatch(globPattern, config) {
+async function getFsRouteBatch(globPattern, config) {
   if (!config.procedureDir) {
     return [];
   }
@@ -198,19 +210,15 @@ async function startBuild(config, skipCodeGen = false) {
   logger$2.log("Bundling server....");
   await setupWorkingDir(config);
   await Promise.all([
-    createRoutesModule(config),
-    createBuildEntryModule(config),
-    createBuildCodegenModule(config)
+    createAppWithRoutesModule(config),
+    createServerEntryFile(config),
+    createCodegenEntryFile(config),
+    transpileFiles(config)
   ]);
-  await transpileFiles(config);
-  await bundleFiles(config);
+  await bundleAppEntry(config);
   logger$2.log("Finished bundling");
   const clientCount = config.clientGenerators.length;
-  const codegenModule = path__default.resolve(
-    config.rootDir,
-    ".output",
-    CODEGEN_OUTPUT
-  );
+  const codegenModule = path__default.resolve(config.rootDir, ".output", OUT_CODEGEN);
   if (!skipCodeGen) {
     logger$2.log("Generating Arri app definition (__definition.json)");
     node_child_process.execSync(`node ${codegenModule}`, { env: process.env });
@@ -237,48 +245,18 @@ async function startBuild(config, skipCodeGen = false) {
   logger$2.log("Cleaning up files");
   await fs__default.rm(codegenModule);
   logger$2.success(
-    `Build finished! You can start your server by running "node .output/${SERVER_ENTRY_OUTPUT}"`
+    `Build finished! You can start your server by running "node .output/${OUT_SERVER_ENTRY}"`
   );
 }
-async function bundleFiles(config, allowCodegen = true) {
-  if (allowCodegen) {
-    await esbuild.build({
-      ...config.esbuild,
-      entryPoints: [
-        path__default.resolve(
-          config.rootDir,
-          config.buildDir,
-          DEFAULT_CODEGEN_FILE
-        )
-      ],
-      platform: config.esbuild.platform ?? "node",
-      target: config.esbuild.target ?? "node20",
-      packages: "external",
-      bundle: true,
-      format: "esm",
-      sourcemap: false,
-      minifyWhitespace: false,
-      banner: {
-        js: `import { createRequire as topLevelCreateRequire } from 'module';
-const require = topLevelCreateRequire(import.meta.url);`
-      },
-      outfile: path__default.resolve(config.rootDir, ".output", CODEGEN_OUTPUT)
-    });
-  }
-  let buildEntry = path__default.resolve(
+async function bundleAppEntry(config, allowCodegen = true) {
+  const appEntry = path__default.resolve(
     config.rootDir,
     config.buildDir,
-    DEFAULT_SERVER_ENTRY_FILE
+    GEN_APP_FILE
   );
-  if (config.buildEntry) {
-    const parts = config.buildEntry.split(".");
-    parts.pop();
-    const mergedParts = `${parts.join(".")}.js`;
-    buildEntry = path__default.resolve(config.rootDir, config.buildDir, mergedParts);
-  }
   await esbuild.build({
     ...config.esbuild,
-    entryPoints: [buildEntry],
+    entryPoints: [appEntry],
     platform: config.esbuild.platform ?? "node",
     target: config.esbuild.target ?? "node20",
     bundle: true,
@@ -291,11 +269,34 @@ const require = topLevelCreateRequire(import.meta.url);`
 const require = topLevelCreateRequire(import.meta.url);`
     },
     allowOverwrite: true,
-    outfile: path__default.resolve(config.rootDir, ".output", SERVER_ENTRY_OUTPUT)
+    outfile: path__default.resolve(config.rootDir, ".output", OUT_APP_FILE)
   });
 }
-async function createBuildEntryModule(config) {
-  if (config.buildEntry) {
+async function createServerEntryFile(config) {
+  if (config.serverEntry) {
+    const buildEntry = path__default.resolve(
+      config.rootDir,
+      config.srcDir,
+      config.serverEntry
+    );
+    await esbuild.build({
+      ...config.esbuild,
+      entryPoints: [buildEntry],
+      platform: config.esbuild.platform ?? "node",
+      target: config.esbuild.target ?? "node20",
+      bundle: false,
+      packages: "external",
+      format: "esm",
+      sourcemap: true,
+      minifyWhitespace: true,
+      banner: {
+        js: `import { createRequire as topLevelCreateRequire } from 'module';
+const require = topLevelCreateRequire(import.meta.url);`
+      },
+      plugins: [esbuildPluginReplace.replace({ "virtual:arri/app": "./app.js" })],
+      allowOverwrite: true,
+      outfile: path__default.resolve(config.rootDir, ".output", OUT_SERVER_ENTRY)
+    });
     return;
   }
   const appModule = path__default.resolve(config.rootDir, config.srcDir, config.entry);
@@ -303,34 +304,18 @@ async function createBuildEntryModule(config) {
   appImportParts.pop();
   const virtualEntry = `import { toNodeListener } from 'arri';
 import { listen } from 'listhen';
-import routes from './routes.js';
-import app from './${appImportParts.join(".")}.js';
-
-for (const route of routes) {
-    app.rpc({
-        name: route.id,
-        method: route.route.method,
-        params: route.route.params,
-        response: route.route.response,
-        handler: route.route.handler,
-        postHandler: route.route.postHandler,
-    });
-}
+import app from './${OUT_APP_FILE}';
 
 void listen(toNodeListener(app.h3App), {
     port: process.env.PORT ?? ${config.port},
     public: true,
 });`;
   await fs__default.writeFile(
-    path__default.resolve(
-      config.rootDir,
-      config.buildDir,
-      DEFAULT_SERVER_ENTRY_FILE
-    ),
+    path__default.resolve(config.rootDir, ".output", GEN_SERVER_ENTRY_FILE),
     virtualEntry
   );
 }
-async function createBuildCodegenModule(config) {
+async function createCodegenEntryFile(config) {
   const appModule = path__default.resolve(config.rootDir, config.srcDir, config.entry);
   const appImportParts = path__default.relative(path__default.resolve(config.rootDir, config.srcDir), appModule).split(".");
   appImportParts.pop();
@@ -338,20 +323,7 @@ async function createBuildCodegenModule(config) {
     `
     import { writeFileSync } from 'node:fs';
     import path from 'pathe';
-    import app from './${appImportParts.join(".")}.js';
-    import routes from './routes.js';
-
-    for (const route of routes) {
-        app.rpc({
-            name: route.id,
-            method: route.route.method,
-            path: route.route.path,
-            params: route.route.params,
-            response: route.route.response,
-            handler: route.route.handler,
-            postHandler: route.route.postHandler,
-        });
-    }
+    import app from './${OUT_APP_FILE}';
 
     const __dirname = new URL(".", import.meta.url).pathname;
     const def = app.getAppDefinition();
@@ -362,7 +334,7 @@ async function createBuildCodegenModule(config) {
     { tabWidth: 4, parser: "typescript" }
   );
   await fs__default.writeFile(
-    path__default.resolve(config.rootDir, config.buildDir, DEFAULT_CODEGEN_FILE),
+    path__default.resolve(config.rootDir, ".output", OUT_CODEGEN),
     virtualModule
   );
 }
@@ -464,26 +436,26 @@ const dev = citty.defineCommand({
     await startDevServer(config$1);
   }
 });
-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
-  }
-);
+const startListener = (config, showQr = false) => listhen.listenAndWatch(path__default.resolve(config.rootDir, ".output", OUT_SERVER_ENTRY), {
+  public: true,
+  port: config.port,
+  logger: logger$1,
+  qr: showQr
+});
 async function bundleFilesContext(config) {
+  const serverContent = `import app from './${OUT_APP_FILE}';
+
+export default app.h3App;`;
+  await fs__default.writeFile(
+    path__default.resolve(config.rootDir, ".output", OUT_SERVER_ENTRY),
+    serverContent
+  );
   return await esbuild__namespace.context({
     ...config.esbuild,
     entryPoints: [
-      path__default.resolve(
-        config.rootDir,
-        config.buildDir,
-        DEFAULT_SERVER_ENTRY_FILE
-      )
+      path__default.resolve(config.rootDir, config.buildDir, GEN_APP_FILE)
     ],
-    outfile: path__default.resolve(config.rootDir, ".output", SERVER_ENTRY_OUTPUT),
+    outfile: path__default.resolve(config.rootDir, ".output", OUT_APP_FILE),
     format: "esm",
     bundle: true,
     sourcemap: true,
@@ -495,8 +467,11 @@ async function bundleFilesContext(config) {
 async function startDevServer(config) {
   await setupWorkingDir(config);
   let fileWatcher;
-  await Promise.all([createRoutesModule(config), createEntryModule(config)]);
-  await transpileFiles(config);
+  await Promise.all([
+    createEntryModule(config),
+    createAppWithRoutesModule(config),
+    transpileFiles(config)
+  ]);
   const bundleFiles = await bundleFilesContext(config);
   await bundleFiles.rebuild();
   const listener = await startListener(config, true);
@@ -534,7 +509,7 @@ async function startDevServer(config) {
         if (event === "add" || event === "addDir") {
           return;
         }
-        await createRoutesModule(config);
+        await createAppWithRoutesModule(config);
         let bundleCreated = false;
         try {
           logger$1.log(
@@ -587,28 +562,11 @@ async function createEntryModule(config) {
   appImportParts.pop();
   const virtualEntry = `import { toNodeListener } from 'h3';
 import { listen } from 'listhen';
-import routes from './routes';
-import app from './${appImportParts.join(".")}';
-
-for (const route of routes) {
-    app.rpc({
-        name: route.id,
-        method: route.route.method,
-        path: route.route.path,
-        params: route.route.params,
-        response: route.route.response,
-        handler: route.route.handler,
-        postHandler: route.route.postHandler,
-    });
-}
+import app from './${GEN_APP_FILE}';
 
 export default app.h3App;`;
   await fs__default.writeFile(
-    path__default.resolve(
-      config.rootDir,
-      config.buildDir,
-      DEFAULT_SERVER_ENTRY_FILE
-    ),
+    path__default.resolve(config.rootDir, config.buildDir, GEN_SERVER_ENTRY_FILE),
     virtualEntry
   );
 }