arri 0.13.0 → 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

@@ -12,7 +12,7 @@ const esbuild = require('esbuild');
 const esbuildPluginReplace = require('esbuild-plugin-replace');
 const path = require('pathe');
 const prettier = require('prettier');
-const config = require('./shared/arri.165b8604.cjs');
+const config = require('./shared/arri.2eb37786.cjs');
 const globby = require('globby');
 const scule = require('scule');
 const arriCodegenDart = require('arri-codegen-dart');
@@ -93,11 +93,7 @@ async function createAppWithRoutesModule(config) {
         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,
+                ...route.route,
             });
         }
         export default app`,

package/dist/cli.mjs

@@ -11,7 +11,7 @@ import { build as build$1 } from 'esbuild';
 import { replace } from 'esbuild-plugin-replace';
 import path from 'pathe';
 import prettier from 'prettier';
-import { n as defaultConfig, m as isResolvedArriConfig, a as DEV_DEFINITION_ENDPOINT } from './shared/arri.cc0da87a.mjs';
+import { n as defaultConfig, m as isResolvedArriConfig, a as DEV_DEFINITION_ENDPOINT } from './shared/arri.28516ef9.mjs';
 import { globby } from 'globby';
 import { camelCase, kebabCase } from 'scule';
 import { dartClientGenerator } from 'arri-codegen-dart';
@@ -69,11 +69,7 @@ async function createAppWithRoutesModule(config) {
         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,
+                ...route.route,
             });
         }
         export default app`,

package/dist/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-const config = require('./shared/arri.165b8604.cjs');
+const config = require('./shared/arri.2eb37786.cjs');
 const h3 = require('h3');
 require('arri-validate');
 require('arri-codegen-utils');
@@ -13,24 +13,32 @@ exports.ArriRouter = config.ArriRouter;
 exports.DEV_DEFINITION_ENDPOINT = config.DEV_DEFINITION_ENDPOINT;
 exports.DEV_ENDPOINT_ROOT = config.DEV_ENDPOINT_ROOT;
 exports.ErrorResponse = config.ErrorResponse;
+exports.EventStreamConnection = config.EventStreamConnection;
 exports.createRpcDefinition = config.createRpcDefinition;
 exports.defaultConfig = config.defaultConfig;
 exports.defineConfig = config.defineConfig;
 exports.defineError = config.defineError;
+exports.defineEventStreamRpc = config.defineEventStreamRpc;
 exports.defineRoute = config.defineRoute;
 exports.defineRpc = config.defineRpc;
 exports.errorResponseFromValidationErrors = config.errorResponseFromValidationErrors;
+exports.formatSse = config.formatSse;
+exports.formatSseList = config.formatSseList;
 exports.getRpcParamName = config.getRpcParamName;
 exports.getRpcPath = config.getRpcPath;
 exports.getRpcResponseName = config.getRpcResponseName;
 exports.handleH3Error = config.handleH3Error;
 exports.handleRoute = config.handleRoute;
 exports.isArriConfig = config.isArriConfig;
+exports.isEventStreamRpc = config.isEventStreamRpc;
 exports.isResolvedArriConfig = config.isResolvedArriConfig;
 exports.isRpc = config.isRpc;
 exports.isRpcParamSchema = config.isRpcParamSchema;
+exports.registerEventStreamRpc = config.registerEventStreamRpc;
 exports.registerRoute = config.registerRoute;
 exports.registerRpc = config.registerRpc;
+exports.setSseHeaders = config.setSseHeaders;
+exports.validateRpcRequestInput = config.validateRpcRequestInput;
 exports.defineMiddleware = defineMiddleware;
 Object.keys(h3).forEach(function (k) {
     if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) exports[k] = h3[k];

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { HttpMethod, RpcHttpMethod, RpcDefinition, AppDefinition, ClientGenerator } from 'arri-codegen-utils';
-import { AObjectSchema, ASchema, InferType, ARecordSchema, ADiscriminatorSchema, a, ValidationError } from 'arri-validate';
-import { H3EventContext, H3Event, Router, App, H3Error } from 'h3';
+import { HttpMethod, RpcHttpMethod, RpcDefinition, SchemaFormProperties, SchemaFormDiscriminator, SchemaFormValues, AppDefinition, ClientGenerator } from 'arri-codegen-utils';
+import { AObjectSchema, ASchema, InferType, a, ValidationError, ARecordSchema, ADiscriminatorSchema } from 'arri-validate';
+import { H3EventContext, H3Event, Router, H3Error, App } from 'h3';
 export * from 'h3';
 import { BuildOptions } from 'esbuild';
 
@@ -44,20 +44,103 @@ type RouteOptions = Pick<ArriOptions, "onAfterResponse" | "onBeforeResponse" | "
 declare function registerRoute(router: Router, route: ArriRoute<any>, opts: RouteOptions): void;
 declare function handleRoute(router: Router, method: HttpMethod, route: ArriRoute<any>, opts: RouteOptions): void;
 
+declare const ErrorResponse: AObjectSchema<{
+    statusCode: number;
+    statusMessage: string;
+    stack?: string | undefined;
+    data?: any;
+}, false>;
+type ErrorResponse = a.infer<typeof ErrorResponse>;
+declare function defineError(statusCode: StatusCode, input?: Partial<Omit<ErrorResponse, "statusCode" | "stack">> & {
+    stack?: string;
+}): H3Error;
+declare function errorResponseFromValidationErrors(errors: ValidationError["errors"], prefixText?: string): H3Error;
+type StatusCode = number | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 419 | 420 | 421 | 422 | 423 | 424 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 507 | 511;
+declare function handleH3Error(err: unknown, event: H3Event, onError: ArriOptions["onError"]): Promise<void>;
+
+declare function setSseHeaders(event: H3Event): void;
+declare function defineEventStreamRpc<TParams extends RpcParamSchema | undefined = undefined, TResponse extends RpcParamSchema | undefined | never = undefined>(config: Omit<EventStreamRpc<TParams, TResponse>, "isEventStream">): EventStreamRpc<TParams, TResponse>;
+declare function isEventStreamRpc(input: unknown): input is EventStreamRpc<any, any>;
+interface EventStreamRpc<TParams extends RpcParamSchema | undefined = undefined, TResponse extends RpcParamSchema | undefined = undefined> extends Omit<Rpc<true, TParams, TResponse>, "handler" | "postHandler"> {
+    isEventStream: true;
+    handler: EventStreamRpcHandler<TParams extends RpcParamSchema ? InferType<TParams> : undefined, TResponse extends RpcParamSchema ? InferType<TResponse> : undefined>;
+}
+type EventStreamRpcHandler<TParams, TResponse> = (context: EventStreamRpcHandlerContext<TParams, TResponse>, event: EventStreamRpcEvent<TParams, TResponse>) => void | Promise<void>;
+interface EventStreamRpcEvent<TParams, TResponse> extends RpcEvent<TParams> {
+    connection: EventStreamConnection<TResponse>;
+}
+interface EventStreamRpcHandlerContext<TParams = any, TResponse = any> extends RpcHandlerContext<TParams> {
+    connection: EventStreamConnection<TResponse>;
+}
+interface EventStreamConnectionOptions<TData> {
+    serializer: (input: TData) => string;
+    pingInterval?: number;
+}
+/**
+ * A server sent event
+ */
+interface Sse {
+    id?: string;
+    event?: string;
+    data: string;
+}
+declare function formatSse({ id, data, event }: Sse): string;
+declare function formatSseList(events: Sse[]): string;
+declare class EventStreamConnection<TData> {
+    lastEventId: string | undefined;
+    private readonly writable;
+    private readonly readable;
+    private readonly writer;
+    private readonly encoder;
+    private readonly serializer;
+    private readonly h3Event;
+    private pingInterval;
+    private readonly pingIntervalMs;
+    constructor(event: H3Event, opts: EventStreamConnectionOptions<TData>);
+    /**
+     * Start sending the event stream to the client
+     */
+    start(): void;
+    /**
+     * Publish a new event. Events published with this hook will trigger the `onData()` hooks of any connected clients.
+     */
+    push(data: TData[], eventId?: string): Promise<void>;
+    push(data: TData, eventId?: string): Promise<void>;
+    /**
+     * Publish an error event. This will trigger the `onError` hooks of any connected clients.
+     */
+    pushError(error: ErrorResponse, eventId?: string): Promise<void>;
+    private publishEvents;
+    private publishEvent;
+    private cleanup;
+    /**
+     * Tell clients that the stream has ended and close the connection.
+     */
+    end(): Promise<void>;
+    on(event: "disconnect", callback: () => any): void;
+    on(event: "end", callback: () => any): void;
+}
+declare function registerEventStreamRpc(router: Router, path: string, procedure: EventStreamRpc<any, any> & {
+    name: string;
+}, opts: RouteOptions): void;
+
 type RpcParamSchema<TObjectInner = any, TRecordInner extends ASchema = any, TDiscriminatorInner = any> = AObjectSchema<TObjectInner> | ARecordSchema<TRecordInner> | ADiscriminatorSchema<TDiscriminatorInner>;
 declare function isRpcParamSchema(input: unknown): input is RpcParamSchema;
-interface ArriProcedure<TParams extends RpcParamSchema | undefined, TResponse extends RpcParamSchema | undefined> {
-    description?: string;
+interface NamedRpc<TIsEventStream extends boolean = false, TParams extends RpcParamSchema | undefined = undefined, TResponse extends RpcParamSchema | undefined = undefined> extends Rpc<TIsEventStream, TParams, TResponse> {
+    name: string;
+}
+interface Rpc<TIsEventStream extends boolean = false, TParams extends RpcParamSchema | undefined = undefined, TResponse extends RpcParamSchema | undefined = undefined> {
     method?: RpcHttpMethod;
     path?: string;
+    description?: string;
     params: TParams;
     response: TResponse;
-    handler: ArriProcedureHandler<TParams extends RpcParamSchema ? InferType<TParams> : undefined, TResponse extends RpcParamSchema ? InferType<TResponse> : void>;
-    postHandler?: ArriProcedurePostHandler<TParams extends RpcParamSchema ? InferType<TParams> : undefined, TResponse extends RpcParamSchema ? InferType<TResponse> : undefined>;
-}
-interface ArriNamedProcedure<TParams extends RpcParamSchema | undefined, TResponse extends RpcParamSchema | undefined> extends ArriProcedure<TParams, TResponse> {
-    name: string;
+    isEventStream?: TIsEventStream;
+    pingInterval?: TIsEventStream extends true ? number : undefined;
+    handler: TIsEventStream extends true ? EventStreamRpcHandler<TParams extends RpcParamSchema ? InferType<TParams> : undefined, TResponse extends RpcParamSchema ? InferType<TResponse> : undefined> : RpcHandler<TParams extends RpcParamSchema ? InferType<TParams> : undefined, TResponse extends RpcParamSchema ? InferType<TResponse> : void>;
+    postHandler?: TIsEventStream extends true ? undefined : RpcPostHandler<TParams extends RpcParamSchema ? InferType<TParams> : undefined, TResponse extends RpcParamSchema ? InferType<TResponse> : undefined>;
 }
+type HttpRpc<TParams extends RpcParamSchema | undefined, TResponse extends RpcParamSchema | undefined> = Omit<Rpc<false, TParams, TResponse>, "isEventStream">;
 type HandlerContext = Record<string, any>;
 interface RpcHandlerContext<TParams = undefined> extends HandlerContext, Omit<H3EventContext, "params"> {
     rpcName: string;
@@ -72,31 +155,37 @@ interface RpcEvent<TParams = undefined> extends Omit<H3Event, "context"> {
 interface RpcPostEvent<TParams = undefined, TResponse = undefined> extends Omit<H3Event, "context"> {
     context: RpcPostHandlerContext<TParams, TResponse>;
 }
-type ArriProcedureHandler<TParams, TResponse> = (context: RpcHandlerContext<TParams>, event: RpcEvent<TParams>) => TResponse | Promise<TResponse>;
-type ArriProcedurePostHandler<TParams, TResponse> = (context: RpcPostHandlerContext<TParams, TResponse>, event: RpcPostEvent<TParams, TResponse>) => any;
-declare function isRpc(input: any): input is ArriProcedure<any, any>;
-declare function defineRpc<TParams extends RpcParamSchema | undefined = undefined, TResponse extends RpcParamSchema | undefined | never = undefined>(config: ArriProcedure<TParams, TResponse>): ArriProcedure<TParams, TResponse>;
-declare function createRpcDefinition(rpcName: string, httpPath: string, procedure: ArriProcedure<any, any>): RpcDefinition;
+type RpcHandler<TParams, TResponse> = (context: RpcHandlerContext<TParams>, event: RpcEvent<TParams>) => TResponse | Promise<TResponse>;
+type RpcPostHandler<TParams, TResponse> = (context: RpcPostHandlerContext<TParams, TResponse>, event: RpcPostEvent<TParams, TResponse>) => any;
+declare function isRpc(input: unknown): input is Rpc<any, any>;
+declare function defineRpc<TParams extends RpcParamSchema | undefined = undefined, TResponse extends RpcParamSchema | undefined | never = undefined>(config: HttpRpc<TParams, TResponse>): Rpc<false, TParams, TResponse>;
+declare function createRpcDefinition(rpcName: string, httpPath: string, procedure: Rpc<any, any, any>): RpcDefinition;
 declare function getRpcPath(rpcName: string, prefix?: string): string;
-declare function getRpcParamName(rpcName: string, procedure: ArriProcedure<any, any>): string | undefined;
-declare function getRpcResponseName(rpcName: string, procedure: ArriProcedure<any, any>): string | undefined;
-declare function registerRpc(router: Router, path: string, procedure: ArriNamedProcedure<any, any>, opts: RouteOptions): void;
+declare function getRpcParamName(rpcName: string, procedure: Rpc<any, any, any>): string | undefined;
+declare function getRpcResponseName(rpcName: string, procedure: Rpc<any, any, any>): string | undefined;
+declare function registerRpc(router: Router, path: string, procedure: NamedRpc<any, any, any>, opts: RouteOptions): void;
+declare function validateRpcRequestInput(event: H3Event, httpMethod: RpcHttpMethod, schema: ASchema): Promise<void>;
 
 interface ArriRouterBase {
-    rpc: <TParams extends AObjectSchema<any, any> | undefined, TResponse extends AObjectSchema<any, any> | undefined>(procedure: ArriNamedProcedure<TParams, TResponse>) => void;
+    rpc: <TIsEventStream extends boolean, TParams extends AObjectSchema<any, any> | undefined, TResponse extends AObjectSchema<any, any> | undefined>(procedure: NamedRpc<TIsEventStream, TParams, TResponse>) => void;
     route: <TPath extends string, TQuery extends AObjectSchema<any, any> = any, TBody extends ASchema<any> = any, TResponse = any>(route: ArriRoute<TPath, TQuery, TBody, TResponse>) => void;
+    registerModels: (models: ModelMap) => void;
 }
 declare class ArriRouter implements ArriRouterBase {
     private readonly procedures;
     private readonly routes;
-    rpc<TParams extends AObjectSchema<any, any> | undefined, TResponse extends AObjectSchema<any, any> | undefined>(procedure: ArriNamedProcedure<TParams, TResponse>): void;
+    private readonly models;
+    rpc<TIsEventStream extends boolean = false, TParams extends AObjectSchema<any, any> | undefined = undefined, TResponse extends AObjectSchema<any, any> | undefined = undefined>(procedure: NamedRpc<TIsEventStream, TParams, TResponse>): void;
     route<TPath extends string, TQuery extends AObjectSchema<any, any> = any, TBody extends ASchema<any> = any, TResponse = any>(route: ArriRoute<TPath, TQuery, TBody, TResponse>): void;
-    getProcedures(): ArriNamedProcedure<any, any>[];
+    registerModels(models: ModelMap): void;
+    getProcedures(): NamedRpc<any, any, any>[];
     getRoutes(): ArriRoute<any, any, any, any>[];
+    getModels(): ModelMap;
 }
 
 declare const DEV_ENDPOINT_ROOT = "/__arri_dev__";
 declare const DEV_DEFINITION_ENDPOINT = "/__arri_dev__/__definition";
+type ModelMap = Record<string, SchemaFormProperties | SchemaFormDiscriminator | SchemaFormValues>;
 declare class ArriApp implements ArriRouterBase {
     __isArri__: boolean;
     readonly h3App: App;
@@ -113,8 +202,9 @@ declare class ArriApp implements ArriRouterBase {
     private readonly onError;
     constructor(opts?: ArriOptions);
     use(input: Middleware | ArriRouter): void;
-    rpc<TParams extends AObjectSchema<any, any> | undefined, TResponse extends AObjectSchema<any, any> | undefined>(procedure: ArriNamedProcedure<TParams, TResponse>): void;
+    rpc<TIsEventStream extends boolean = false, TParams extends AObjectSchema<any, any> | undefined = undefined, TResponse extends AObjectSchema<any, any> | undefined = undefined>(procedure: NamedRpc<TIsEventStream, TParams, TResponse>): void;
     route<TPath extends string, TQuery extends AObjectSchema<any, any>, TBody extends ASchema<any>, TResponse = any>(route: ArriRoute<TPath, TQuery, TBody, TResponse>): void;
+    registerModels(models: ModelMap): void;
     getAppDefinition(): AppDefinition;
 }
 interface ArriOptions {
@@ -135,20 +225,6 @@ interface ArriOptions {
     onError?: (error: H3Error, event: MiddlewareEvent) => void | Promise<void>;
 }
 
-declare const ErrorResponse: AObjectSchema<{
-    statusCode: number;
-    statusMessage: string;
-    stack?: string | undefined;
-    data?: any;
-}, false>;
-type ErrorResponse = a.infer<typeof ErrorResponse>;
-declare function defineError(statusCode: StatusCode, input?: Partial<Omit<ErrorResponse, "statusCode" | "stack">> & {
-    stack?: string;
-}): H3Error;
-declare function errorResponseFromValidationErrors(errors: ValidationError["errors"], prefixText?: string): H3Error;
-type StatusCode = number | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 419 | 420 | 421 | 422 | 423 | 424 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 507 | 511;
-declare function handleH3Error(err: unknown, event: H3Event, onError: ArriOptions["onError"]): Promise<void>;
-
 interface ArriConfig {
     port: number;
     entry: string;
@@ -170,4 +246,4 @@ type ResolvedArriConfig = Required<ArriConfig>;
 declare const defaultConfig: Required<ArriConfig>;
 declare function defineConfig(config: ArriConfig): ResolvedArriConfig;
 
-export { ArriApp, type ArriConfig, type ArriNamedProcedure, type ArriOptions, type ArriProcedure, type ArriProcedureHandler, type ArriProcedurePostHandler, type ArriRoute, ArriRouter, type ArriRouterBase, DEV_DEFINITION_ENDPOINT, DEV_ENDPOINT_ROOT, ErrorResponse, type ExtractParam, type ExtractParams, type HandlerContext, type Middleware, type MiddlewareEvent, type MiddlewareEventContext, type PostRouteEvent, type PostRouteEventContext, type ResolvedArriConfig, type RouteEvent, type RouteEventContext, type RouteOptions, type RpcEvent, type RpcHandlerContext, type RpcParamSchema, type RpcPostEvent, type RpcPostHandlerContext, type StatusCode, createRpcDefinition, defaultConfig, defineConfig, defineError, defineMiddleware, defineRoute, defineRpc, errorResponseFromValidationErrors, getRpcParamName, getRpcPath, getRpcResponseName, handleH3Error, handleRoute, isArriConfig, isResolvedArriConfig, isRpc, isRpcParamSchema, registerRoute, registerRpc };
+export { ArriApp, type ArriConfig, type ArriOptions, type ArriRoute, ArriRouter, type ArriRouterBase, DEV_DEFINITION_ENDPOINT, DEV_ENDPOINT_ROOT, ErrorResponse, EventStreamConnection, type EventStreamConnectionOptions, type EventStreamRpc, type EventStreamRpcEvent, type EventStreamRpcHandler, type EventStreamRpcHandlerContext, type ExtractParam, type ExtractParams, type HandlerContext, type HttpRpc, type Middleware, type MiddlewareEvent, type MiddlewareEventContext, type ModelMap, type NamedRpc, type PostRouteEvent, type PostRouteEventContext, type ResolvedArriConfig, type RouteEvent, type RouteEventContext, type RouteOptions, type Rpc, type RpcEvent, type RpcHandler, type RpcHandlerContext, type RpcParamSchema, type RpcPostEvent, type RpcPostHandler, type RpcPostHandlerContext, type Sse, type StatusCode, createRpcDefinition, defaultConfig, defineConfig, defineError, defineEventStreamRpc, defineMiddleware, defineRoute, defineRpc, errorResponseFromValidationErrors, formatSse, formatSseList, getRpcParamName, getRpcPath, getRpcResponseName, handleH3Error, handleRoute, isArriConfig, isEventStreamRpc, isResolvedArriConfig, isRpc, isRpcParamSchema, registerEventStreamRpc, registerRoute, registerRpc, setSseHeaders, validateRpcRequestInput };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { HttpMethod, RpcHttpMethod, RpcDefinition, AppDefinition, ClientGenerator } from 'arri-codegen-utils';
-import { AObjectSchema, ASchema, InferType, ARecordSchema, ADiscriminatorSchema, a, ValidationError } from 'arri-validate';
-import { H3EventContext, H3Event, Router, App, H3Error } from 'h3';
+import { HttpMethod, RpcHttpMethod, RpcDefinition, SchemaFormProperties, SchemaFormDiscriminator, SchemaFormValues, AppDefinition, ClientGenerator } from 'arri-codegen-utils';
+import { AObjectSchema, ASchema, InferType, a, ValidationError, ARecordSchema, ADiscriminatorSchema } from 'arri-validate';
+import { H3EventContext, H3Event, Router, H3Error, App } from 'h3';
 export * from 'h3';
 import { BuildOptions } from 'esbuild';
 
@@ -44,20 +44,103 @@ type RouteOptions = Pick<ArriOptions, "onAfterResponse" | "onBeforeResponse" | "
 declare function registerRoute(router: Router, route: ArriRoute<any>, opts: RouteOptions): void;
 declare function handleRoute(router: Router, method: HttpMethod, route: ArriRoute<any>, opts: RouteOptions): void;
 
+declare const ErrorResponse: AObjectSchema<{
+    statusCode: number;
+    statusMessage: string;
+    stack?: string | undefined;
+    data?: any;
+}, false>;
+type ErrorResponse = a.infer<typeof ErrorResponse>;
+declare function defineError(statusCode: StatusCode, input?: Partial<Omit<ErrorResponse, "statusCode" | "stack">> & {
+    stack?: string;
+}): H3Error;
+declare function errorResponseFromValidationErrors(errors: ValidationError["errors"], prefixText?: string): H3Error;
+type StatusCode = number | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 419 | 420 | 421 | 422 | 423 | 424 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 507 | 511;
+declare function handleH3Error(err: unknown, event: H3Event, onError: ArriOptions["onError"]): Promise<void>;
+
+declare function setSseHeaders(event: H3Event): void;
+declare function defineEventStreamRpc<TParams extends RpcParamSchema | undefined = undefined, TResponse extends RpcParamSchema | undefined | never = undefined>(config: Omit<EventStreamRpc<TParams, TResponse>, "isEventStream">): EventStreamRpc<TParams, TResponse>;
+declare function isEventStreamRpc(input: unknown): input is EventStreamRpc<any, any>;
+interface EventStreamRpc<TParams extends RpcParamSchema | undefined = undefined, TResponse extends RpcParamSchema | undefined = undefined> extends Omit<Rpc<true, TParams, TResponse>, "handler" | "postHandler"> {
+    isEventStream: true;
+    handler: EventStreamRpcHandler<TParams extends RpcParamSchema ? InferType<TParams> : undefined, TResponse extends RpcParamSchema ? InferType<TResponse> : undefined>;
+}
+type EventStreamRpcHandler<TParams, TResponse> = (context: EventStreamRpcHandlerContext<TParams, TResponse>, event: EventStreamRpcEvent<TParams, TResponse>) => void | Promise<void>;
+interface EventStreamRpcEvent<TParams, TResponse> extends RpcEvent<TParams> {
+    connection: EventStreamConnection<TResponse>;
+}
+interface EventStreamRpcHandlerContext<TParams = any, TResponse = any> extends RpcHandlerContext<TParams> {
+    connection: EventStreamConnection<TResponse>;
+}
+interface EventStreamConnectionOptions<TData> {
+    serializer: (input: TData) => string;
+    pingInterval?: number;
+}
+/**
+ * A server sent event
+ */
+interface Sse {
+    id?: string;
+    event?: string;
+    data: string;
+}
+declare function formatSse({ id, data, event }: Sse): string;
+declare function formatSseList(events: Sse[]): string;
+declare class EventStreamConnection<TData> {
+    lastEventId: string | undefined;
+    private readonly writable;
+    private readonly readable;
+    private readonly writer;
+    private readonly encoder;
+    private readonly serializer;
+    private readonly h3Event;
+    private pingInterval;
+    private readonly pingIntervalMs;
+    constructor(event: H3Event, opts: EventStreamConnectionOptions<TData>);
+    /**
+     * Start sending the event stream to the client
+     */
+    start(): void;
+    /**
+     * Publish a new event. Events published with this hook will trigger the `onData()` hooks of any connected clients.
+     */
+    push(data: TData[], eventId?: string): Promise<void>;
+    push(data: TData, eventId?: string): Promise<void>;
+    /**
+     * Publish an error event. This will trigger the `onError` hooks of any connected clients.
+     */
+    pushError(error: ErrorResponse, eventId?: string): Promise<void>;
+    private publishEvents;
+    private publishEvent;
+    private cleanup;
+    /**
+     * Tell clients that the stream has ended and close the connection.
+     */
+    end(): Promise<void>;
+    on(event: "disconnect", callback: () => any): void;
+    on(event: "end", callback: () => any): void;
+}
+declare function registerEventStreamRpc(router: Router, path: string, procedure: EventStreamRpc<any, any> & {
+    name: string;
+}, opts: RouteOptions): void;
+
 type RpcParamSchema<TObjectInner = any, TRecordInner extends ASchema = any, TDiscriminatorInner = any> = AObjectSchema<TObjectInner> | ARecordSchema<TRecordInner> | ADiscriminatorSchema<TDiscriminatorInner>;
 declare function isRpcParamSchema(input: unknown): input is RpcParamSchema;
-interface ArriProcedure<TParams extends RpcParamSchema | undefined, TResponse extends RpcParamSchema | undefined> {
-    description?: string;
+interface NamedRpc<TIsEventStream extends boolean = false, TParams extends RpcParamSchema | undefined = undefined, TResponse extends RpcParamSchema | undefined = undefined> extends Rpc<TIsEventStream, TParams, TResponse> {
+    name: string;
+}
+interface Rpc<TIsEventStream extends boolean = false, TParams extends RpcParamSchema | undefined = undefined, TResponse extends RpcParamSchema | undefined = undefined> {
     method?: RpcHttpMethod;
     path?: string;
+    description?: string;
     params: TParams;
     response: TResponse;
-    handler: ArriProcedureHandler<TParams extends RpcParamSchema ? InferType<TParams> : undefined, TResponse extends RpcParamSchema ? InferType<TResponse> : void>;
-    postHandler?: ArriProcedurePostHandler<TParams extends RpcParamSchema ? InferType<TParams> : undefined, TResponse extends RpcParamSchema ? InferType<TResponse> : undefined>;
-}
-interface ArriNamedProcedure<TParams extends RpcParamSchema | undefined, TResponse extends RpcParamSchema | undefined> extends ArriProcedure<TParams, TResponse> {
-    name: string;
+    isEventStream?: TIsEventStream;
+    pingInterval?: TIsEventStream extends true ? number : undefined;
+    handler: TIsEventStream extends true ? EventStreamRpcHandler<TParams extends RpcParamSchema ? InferType<TParams> : undefined, TResponse extends RpcParamSchema ? InferType<TResponse> : undefined> : RpcHandler<TParams extends RpcParamSchema ? InferType<TParams> : undefined, TResponse extends RpcParamSchema ? InferType<TResponse> : void>;
+    postHandler?: TIsEventStream extends true ? undefined : RpcPostHandler<TParams extends RpcParamSchema ? InferType<TParams> : undefined, TResponse extends RpcParamSchema ? InferType<TResponse> : undefined>;
 }
+type HttpRpc<TParams extends RpcParamSchema | undefined, TResponse extends RpcParamSchema | undefined> = Omit<Rpc<false, TParams, TResponse>, "isEventStream">;
 type HandlerContext = Record<string, any>;
 interface RpcHandlerContext<TParams = undefined> extends HandlerContext, Omit<H3EventContext, "params"> {
     rpcName: string;
@@ -72,31 +155,37 @@ interface RpcEvent<TParams = undefined> extends Omit<H3Event, "context"> {
 interface RpcPostEvent<TParams = undefined, TResponse = undefined> extends Omit<H3Event, "context"> {
     context: RpcPostHandlerContext<TParams, TResponse>;
 }
-type ArriProcedureHandler<TParams, TResponse> = (context: RpcHandlerContext<TParams>, event: RpcEvent<TParams>) => TResponse | Promise<TResponse>;
-type ArriProcedurePostHandler<TParams, TResponse> = (context: RpcPostHandlerContext<TParams, TResponse>, event: RpcPostEvent<TParams, TResponse>) => any;
-declare function isRpc(input: any): input is ArriProcedure<any, any>;
-declare function defineRpc<TParams extends RpcParamSchema | undefined = undefined, TResponse extends RpcParamSchema | undefined | never = undefined>(config: ArriProcedure<TParams, TResponse>): ArriProcedure<TParams, TResponse>;
-declare function createRpcDefinition(rpcName: string, httpPath: string, procedure: ArriProcedure<any, any>): RpcDefinition;
+type RpcHandler<TParams, TResponse> = (context: RpcHandlerContext<TParams>, event: RpcEvent<TParams>) => TResponse | Promise<TResponse>;
+type RpcPostHandler<TParams, TResponse> = (context: RpcPostHandlerContext<TParams, TResponse>, event: RpcPostEvent<TParams, TResponse>) => any;
+declare function isRpc(input: unknown): input is Rpc<any, any>;
+declare function defineRpc<TParams extends RpcParamSchema | undefined = undefined, TResponse extends RpcParamSchema | undefined | never = undefined>(config: HttpRpc<TParams, TResponse>): Rpc<false, TParams, TResponse>;
+declare function createRpcDefinition(rpcName: string, httpPath: string, procedure: Rpc<any, any, any>): RpcDefinition;
 declare function getRpcPath(rpcName: string, prefix?: string): string;
-declare function getRpcParamName(rpcName: string, procedure: ArriProcedure<any, any>): string | undefined;
-declare function getRpcResponseName(rpcName: string, procedure: ArriProcedure<any, any>): string | undefined;
-declare function registerRpc(router: Router, path: string, procedure: ArriNamedProcedure<any, any>, opts: RouteOptions): void;
+declare function getRpcParamName(rpcName: string, procedure: Rpc<any, any, any>): string | undefined;
+declare function getRpcResponseName(rpcName: string, procedure: Rpc<any, any, any>): string | undefined;
+declare function registerRpc(router: Router, path: string, procedure: NamedRpc<any, any, any>, opts: RouteOptions): void;
+declare function validateRpcRequestInput(event: H3Event, httpMethod: RpcHttpMethod, schema: ASchema): Promise<void>;
 
 interface ArriRouterBase {
-    rpc: <TParams extends AObjectSchema<any, any> | undefined, TResponse extends AObjectSchema<any, any> | undefined>(procedure: ArriNamedProcedure<TParams, TResponse>) => void;
+    rpc: <TIsEventStream extends boolean, TParams extends AObjectSchema<any, any> | undefined, TResponse extends AObjectSchema<any, any> | undefined>(procedure: NamedRpc<TIsEventStream, TParams, TResponse>) => void;
     route: <TPath extends string, TQuery extends AObjectSchema<any, any> = any, TBody extends ASchema<any> = any, TResponse = any>(route: ArriRoute<TPath, TQuery, TBody, TResponse>) => void;
+    registerModels: (models: ModelMap) => void;
 }
 declare class ArriRouter implements ArriRouterBase {
     private readonly procedures;
     private readonly routes;
-    rpc<TParams extends AObjectSchema<any, any> | undefined, TResponse extends AObjectSchema<any, any> | undefined>(procedure: ArriNamedProcedure<TParams, TResponse>): void;
+    private readonly models;
+    rpc<TIsEventStream extends boolean = false, TParams extends AObjectSchema<any, any> | undefined = undefined, TResponse extends AObjectSchema<any, any> | undefined = undefined>(procedure: NamedRpc<TIsEventStream, TParams, TResponse>): void;
     route<TPath extends string, TQuery extends AObjectSchema<any, any> = any, TBody extends ASchema<any> = any, TResponse = any>(route: ArriRoute<TPath, TQuery, TBody, TResponse>): void;
-    getProcedures(): ArriNamedProcedure<any, any>[];
+    registerModels(models: ModelMap): void;
+    getProcedures(): NamedRpc<any, any, any>[];
     getRoutes(): ArriRoute<any, any, any, any>[];
+    getModels(): ModelMap;
 }
 
 declare const DEV_ENDPOINT_ROOT = "/__arri_dev__";
 declare const DEV_DEFINITION_ENDPOINT = "/__arri_dev__/__definition";
+type ModelMap = Record<string, SchemaFormProperties | SchemaFormDiscriminator | SchemaFormValues>;
 declare class ArriApp implements ArriRouterBase {
     __isArri__: boolean;
     readonly h3App: App;
@@ -113,8 +202,9 @@ declare class ArriApp implements ArriRouterBase {
     private readonly onError;
     constructor(opts?: ArriOptions);
     use(input: Middleware | ArriRouter): void;
-    rpc<TParams extends AObjectSchema<any, any> | undefined, TResponse extends AObjectSchema<any, any> | undefined>(procedure: ArriNamedProcedure<TParams, TResponse>): void;
+    rpc<TIsEventStream extends boolean = false, TParams extends AObjectSchema<any, any> | undefined = undefined, TResponse extends AObjectSchema<any, any> | undefined = undefined>(procedure: NamedRpc<TIsEventStream, TParams, TResponse>): void;
     route<TPath extends string, TQuery extends AObjectSchema<any, any>, TBody extends ASchema<any>, TResponse = any>(route: ArriRoute<TPath, TQuery, TBody, TResponse>): void;
+    registerModels(models: ModelMap): void;
     getAppDefinition(): AppDefinition;
 }
 interface ArriOptions {
@@ -135,20 +225,6 @@ interface ArriOptions {
     onError?: (error: H3Error, event: MiddlewareEvent) => void | Promise<void>;
 }
 
-declare const ErrorResponse: AObjectSchema<{
-    statusCode: number;
-    statusMessage: string;
-    stack?: string | undefined;
-    data?: any;
-}, false>;
-type ErrorResponse = a.infer<typeof ErrorResponse>;
-declare function defineError(statusCode: StatusCode, input?: Partial<Omit<ErrorResponse, "statusCode" | "stack">> & {
-    stack?: string;
-}): H3Error;
-declare function errorResponseFromValidationErrors(errors: ValidationError["errors"], prefixText?: string): H3Error;
-type StatusCode = number | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 419 | 420 | 421 | 422 | 423 | 424 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 507 | 511;
-declare function handleH3Error(err: unknown, event: H3Event, onError: ArriOptions["onError"]): Promise<void>;
-
 interface ArriConfig {
     port: number;
     entry: string;
@@ -170,4 +246,4 @@ type ResolvedArriConfig = Required<ArriConfig>;
 declare const defaultConfig: Required<ArriConfig>;
 declare function defineConfig(config: ArriConfig): ResolvedArriConfig;
 
-export { ArriApp, type ArriConfig, type ArriNamedProcedure, type ArriOptions, type ArriProcedure, type ArriProcedureHandler, type ArriProcedurePostHandler, type ArriRoute, ArriRouter, type ArriRouterBase, DEV_DEFINITION_ENDPOINT, DEV_ENDPOINT_ROOT, ErrorResponse, type ExtractParam, type ExtractParams, type HandlerContext, type Middleware, type MiddlewareEvent, type MiddlewareEventContext, type PostRouteEvent, type PostRouteEventContext, type ResolvedArriConfig, type RouteEvent, type RouteEventContext, type RouteOptions, type RpcEvent, type RpcHandlerContext, type RpcParamSchema, type RpcPostEvent, type RpcPostHandlerContext, type StatusCode, createRpcDefinition, defaultConfig, defineConfig, defineError, defineMiddleware, defineRoute, defineRpc, errorResponseFromValidationErrors, getRpcParamName, getRpcPath, getRpcResponseName, handleH3Error, handleRoute, isArriConfig, isResolvedArriConfig, isRpc, isRpcParamSchema, registerRoute, registerRpc };
+export { ArriApp, type ArriConfig, type ArriOptions, type ArriRoute, ArriRouter, type ArriRouterBase, DEV_DEFINITION_ENDPOINT, DEV_ENDPOINT_ROOT, ErrorResponse, EventStreamConnection, type EventStreamConnectionOptions, type EventStreamRpc, type EventStreamRpcEvent, type EventStreamRpcHandler, type EventStreamRpcHandlerContext, type ExtractParam, type ExtractParams, type HandlerContext, type HttpRpc, type Middleware, type MiddlewareEvent, type MiddlewareEventContext, type ModelMap, type NamedRpc, type PostRouteEvent, type PostRouteEventContext, type ResolvedArriConfig, type RouteEvent, type RouteEventContext, type RouteOptions, type Rpc, type RpcEvent, type RpcHandler, type RpcHandlerContext, type RpcParamSchema, type RpcPostEvent, type RpcPostHandler, type RpcPostHandlerContext, type Sse, type StatusCode, createRpcDefinition, defaultConfig, defineConfig, defineError, defineEventStreamRpc, defineMiddleware, defineRoute, defineRpc, errorResponseFromValidationErrors, formatSse, formatSseList, getRpcParamName, getRpcPath, getRpcResponseName, handleH3Error, handleRoute, isArriConfig, isEventStreamRpc, isResolvedArriConfig, isRpc, isRpcParamSchema, registerEventStreamRpc, registerRoute, registerRpc, setSseHeaders, validateRpcRequestInput };