@mstuercke/api-utils 4.3.1 → 5.0.0

package/package.json

@@ -1,51 +1,26 @@
 {
   "name": "@mstuercke/api-utils",
-  "version": "4.3.1",
+  "version": "5.0.0",
   "type": "module",
+  "main": "src/index.ts",
   "files": [
-    "dist/**/*.js",
-    "dist/**/*.js.map",
-    "dist/**/*.d.ts",
-    "dist/**/*.d.ts.map",
+    "src/**/!(*.test|*.fixture).ts",
     "README.md"
   ],
   "exports": {
-    "./dist": null,
-    "./rest/types": "./dist/rest/types/index.js",
-    "./rest/client": "./dist/rest/client/index.js",
-    "./rest/server": "./dist/rest/server/index.js",
-    "./ws/types": "./dist/ws/types/index.js",
-    "./ws/client": "./dist/ws/client/index.js",
-    "./ws/server": "./dist/ws/server/index.js"
-  },
-  "typesVersions": {
-    "*": {
-      "rest/types": [
-        "dist/rest/types"
-      ],
-      "rest/client": [
-        "dist/rest/client"
-      ],
-      "rest/server": [
-        "dist/rest/server"
-      ],
-      "ws/types": [
-        "dist/ws/types"
-      ],
-      "ws/client": [
-        "dist/ws/client"
-      ],
-      "ws/server": [
-        "dist/ws/server"
-      ]
-    }
+    "./src": null,
+    "./rest/types": "./src/rest/types/index.ts",
+    "./rest/client": "./src/rest/client/index.ts",
+    "./rest/server": "./src/rest/server/index.ts",
+    "./ws/types": "./src/ws/types/index.ts",
+    "./ws/client": "./src/ws/client/index.ts",
+    "./ws/server": "./src/ws/server/index.ts"
   },
   "scripts": {
     "lint": "eslint ./src --max-warnings 0",
     "lint:fix": "eslint ./src --fix",
     "test:unit": "bun test",
-    "clean": "rm -rf dist",
-    "build": "bun scripts/build.ts",
+    "compile": "tsc",
     "bump:major": "npm version major --git-tag-version false",
     "bump:minor": "npm version minor --git-tag-version false",
     "bump:patch": "npm version patch --git-tag-version false",
@@ -60,10 +35,10 @@
     "@types/aws-lambda": "^8.10.133"
   },
   "devDependencies": {
-    "@mstuercke/bun-utils": "5.0.4",
+    "@mstuercke/bun-utils": "6.0.0",
     "@trpc/server": "next",
     "@types/aws-lambda": "^8.10.133",
-    "@types/bun": "^1.0.5",
+    "@types/bun": "^1.0.11",
     "@types/path-to-regexp": "^1.7.0",
     "@types/react": "^18.2.33",
     "aws-sdk-client-mock": "^4.0.0",

package/src/rest/client/fetchRestApi.ts

@@ -0,0 +1,47 @@
+import {
+  RestApiRequest,
+  RestApiRoute,
+  RestPathParams,
+  RestQueryParams,
+  RestRequestBody,
+  RestRequestHeaders,
+  RestRequestHeadersWithAuthorization,
+  RestRequireAuthentication,
+  RestResponseBody,
+} from '../types';
+import {OmitNever} from '../types/internal';
+
+
+export async function fetchRestApi<
+    PathParams extends RestPathParams,
+    QueryParams extends RestQueryParams,
+    RequestHeaders extends RestRequestHeaders,
+    RequestBody extends RestRequestBody,
+    ResponseBody extends RestResponseBody,
+    RequireAuthentication extends RestRequireAuthentication>(
+    restApiUrl: string,
+    route: RestApiRoute<PathParams, QueryParams, RequestHeaders, RequestBody, ResponseBody, RequireAuthentication>,
+    request: OmitNever<RestApiRequest<PathParams, QueryParams, RestRequestHeadersWithAuthorization<RequestHeaders, RequireAuthentication>, RequestBody>>,
+): Promise<ResponseBody> {
+  const pathParams = 'pathParams' in request ? request.pathParams as PathParams : undefined as never;
+  const queryParams = 'queryParams' in request ? request.queryParams as QueryParams : undefined as never;
+  const headers = 'headers' in request ? request.headers as RequestHeaders : undefined as never;
+  const body = 'body' in request ? request.body as RequestBody : undefined as never;
+
+  const url = `${restApiUrl}${route.buildUrl(pathParams, queryParams)}`;
+  const response = await fetch(
+      url,
+      {
+        method: route.method,
+        headers: headers,
+        body: body ? JSON.stringify(body) : null,
+      });
+
+  if (!response.ok && response.status !== 404)
+    throw `Request ${route.method} ${url} failed`;
+
+  const text = (await response.text()).trim();
+  return response.ok && response.status !== 204
+      ? text ? JSON.parse(text) : null
+      : null;
+}

package/src/rest/client/index.ts

@@ -0,0 +1 @@
+export * from './fetchRestApi'

package/src/rest/server/RestApi.ts

@@ -0,0 +1,144 @@
+import {APIGatewayProxyEvent, APIGatewayProxyResult} from 'aws-lambda';
+import {URL} from 'node:url';
+import {match} from 'path-to-regexp';
+import {
+  RestApiRouteHandler,
+  RestPathParams,
+  RestQueryParams,
+  RestRequestBody,
+  RestRequestHeaders,
+  RestRequireAuthentication,
+  RestResponseBody,
+} from '../types';
+
+
+const DEFAULT_RESPONSE_HEADERS = {
+  'Content-Type': 'application/json; charset=utf-8',
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': '*',
+  'Access-Control-Allow-Headers': '*',
+} as const;
+
+export type AnyRestApiRouteHandler = RestApiRouteHandler<
+    RestPathParams,
+    RestQueryParams,
+    RestRequestHeaders,
+    RestRequestBody,
+    RestResponseBody,
+    RestRequireAuthentication
+>
+
+type MatchingRouteHandler = {
+  routeHandler: AnyRestApiRouteHandler,
+  pathParams: RestPathParams,
+}
+
+export class RestApi {
+  private routeHandlers: AnyRestApiRouteHandler[] = [];
+
+  addRouteHandler<
+      PathParams extends RestPathParams,
+      QueryParams extends RestQueryParams,
+      RequestHeaders extends RestRequestHeaders,
+      RequestBody extends RestRequestBody,
+      ResponseBody extends RestResponseBody,
+      RequireAuthentication extends RestRequireAuthentication>(
+      routeHandler: RestApiRouteHandler<PathParams, QueryParams, RequestHeaders, RequestBody, ResponseBody, RequireAuthentication>) {
+    this.routeHandlers = [...this.routeHandlers, routeHandler as unknown as AnyRestApiRouteHandler];
+    return this;
+  }
+
+  async handleRequest(proxyEvent: APIGatewayProxyEvent, onError?: (error: unknown) => Promise<void>): Promise<APIGatewayProxyResult> {
+    try {
+      const url = new URL(`${proxyEvent.headers?.['origin'] || 'https://no-origin'}${proxyEvent.path}`);
+      const routeHandler = this.getMatchingRouteHandler(url, proxyEvent.httpMethod);
+      if (!routeHandler && proxyEvent.httpMethod === 'OPTIONS') {
+        const allowedHttpMethods = this.getMatchingRouteHandlers(url).map(({routeHandler}) => routeHandler.route.method);
+        return {
+          statusCode: 200,
+          body: '',
+          headers: {
+            ...DEFAULT_RESPONSE_HEADERS,
+            'Access-Control-Allow-Methods': allowedHttpMethods.join(','),
+          },
+        };
+      }
+
+      if (!routeHandler)
+        return {
+          statusCode: 405,
+          headers: DEFAULT_RESPONSE_HEADERS,
+          body: `Method ${proxyEvent.httpMethod} not allowed on ${proxyEvent.path}`,
+        };
+
+      const {routeHandler: {requestHandler, route}, pathParams} = routeHandler;
+      const userId = proxyEvent.requestContext.authorizer?.principalId;
+      if (route.requireAuthentication && !userId)
+        return {statusCode: 401, body: ''};
+
+      const responseBody = await requestHandler({
+        pathParams,
+        queryParams: this.extractQueryParams(proxyEvent),
+        headers: proxyEvent.headers as Record<string, string>,
+        body: proxyEvent.body && JSON.parse(proxyEvent.body),
+        userId,
+      });
+      return {
+        statusCode: responseBody.status,
+        body: responseBody.body ? JSON.stringify(responseBody.body) : '',
+        headers: {
+          ...DEFAULT_RESPONSE_HEADERS,
+          ...(responseBody.headers || {}),
+        },
+      };
+    } catch (error) {
+      if (onError)
+        await onError(error);
+
+      console.error(error);
+      return {
+        statusCode: 500,
+        headers: DEFAULT_RESPONSE_HEADERS,
+        body: JSON.stringify({error}),
+      };
+    }
+  }
+
+  private getMatchingRouteHandlers(url: URL): MatchingRouteHandler[] {
+    return this.routeHandlers.reduce((matchingRouteHandlers, routeHandler) => {
+      const pathParams = this.extractPathParams(routeHandler, url);
+      const matchingRouteHandler: MatchingRouteHandler = {
+        routeHandler,
+        pathParams,
+      };
+      return pathParams
+          ? [...matchingRouteHandlers, matchingRouteHandler]
+          : matchingRouteHandlers;
+    }, [] as MatchingRouteHandler[]);
+  }
+
+  private getMatchingRouteHandler(url: URL, httpMethod: string): MatchingRouteHandler | undefined {
+    return this.getMatchingRouteHandlers(url)
+        .find(({routeHandler}) => routeHandler.route.method === httpMethod);
+  }
+
+  private extractPathParams(routeHandler: AnyRestApiRouteHandler, url: URL): object | never {
+    const matcher = match(routeHandler.route.path, {decode: decodeURIComponent});
+    return (matcher(url.pathname) || null)?.params as object | never;
+  }
+
+  private extractQueryParams(proxyEvent: APIGatewayProxyEvent): object {
+    const keys = new Set([
+      ...Object.keys(proxyEvent.queryStringParameters || {}),
+      ...Object.keys(proxyEvent.multiValueQueryStringParameters || {}),
+    ]);
+
+    const queryParams: { [key: string]: string | string[] | undefined } = {};
+    for (const key of keys.values()) {
+      const singleValue = proxyEvent.queryStringParameters?.[key];
+      const multiValues = proxyEvent.multiValueQueryStringParameters?.[key] || [];
+      queryParams[key] = multiValues.length > 1 ? multiValues : singleValue;
+    }
+    return queryParams;
+  }
+}

package/src/rest/server/buildRestApiRouteHandler.ts

@@ -0,0 +1,26 @@
+import {
+  RestApiRequestHandler,
+  RestApiRoute,
+  RestApiRouteHandler,
+  RestPathParams,
+  RestQueryParams,
+  RestRequestBody,
+  RestRequestHeaders,
+  RestRequireAuthentication,
+  RestResponseBody,
+} from '../types';
+
+export const buildRestApiRouteHandler = <
+    PathParams extends RestPathParams = never,
+    QueryParams extends RestQueryParams = never,
+    RequestHeaders extends RestRequestHeaders = never,
+    RequestBody extends RestRequestBody = never,
+    ResponseBody extends RestResponseBody = never,
+    RequireAuthentication extends RestRequireAuthentication = false
+>(
+    route: RestApiRoute<PathParams, QueryParams, RequestHeaders, RequestBody, ResponseBody, RequireAuthentication>,
+    requestHandler: RestApiRequestHandler<PathParams, QueryParams, RequestHeaders, RequestBody, ResponseBody, RequireAuthentication>,
+): RestApiRouteHandler<PathParams, QueryParams, RequestHeaders, RequestBody, ResponseBody, RequireAuthentication> => ({
+  route,
+  requestHandler,
+});

package/{dist/rest/server/index.js → src/rest/server/index.ts}

@@ -1,3 +1,2 @@
 export * from './buildRestApiRouteHandler';
 export * from './RestApi';
-//# sourceMappingURL=index.js.map

package/src/rest/types/RestApiRequest.ts

@@ -0,0 +1,14 @@
+import {RestPathParams, RestQueryParams, RestRequestBody, RestRequestHeaders} from './common';
+import {OmitNever} from './internal';
+
+export type RestApiRequest<
+    PathParams extends RestPathParams = never,
+    QueryParams extends RestQueryParams = never,
+    RequestHeaders extends RestRequestHeaders = never,
+    RequestBody extends RestRequestBody = never> = OmitNever<{
+  pathParams: PathParams,
+  queryParams: QueryParams,
+  headers: RequestHeaders,
+  body: RequestBody
+}>
+

package/src/rest/types/RestApiRequestHandler.ts

@@ -0,0 +1,21 @@
+import {RestApiResponse} from './RestApiResponse';
+import {
+  RestPathParams,
+  RestQueryParams,
+  RestRequestBody,
+  RestRequestHeaders,
+  RestRequireAuthentication,
+  RestResponseBody,
+} from './common';
+import {InternalRestApiRequest} from './internal';
+
+export type RestApiRequestHandler<
+    PathParams extends RestPathParams = never,
+    QueryParams extends RestQueryParams = never,
+    RequestHeaders extends RestRequestHeaders = never,
+    RequestBody extends RestRequestBody = never,
+    ResponseBody extends RestResponseBody = never,
+    RequireAuthentication extends RestRequireAuthentication = false
+> = (request: InternalRestApiRequest<PathParams, QueryParams, RequestHeaders, RequestBody, RequireAuthentication>) => Promise<RestApiResponse<ResponseBody>>;
+
+

package/src/rest/types/RestApiRequestHandlerWithAuthentication.ts

@@ -0,0 +1,12 @@
+import {RestApiRequestHandler} from './RestApiRequestHandler';
+import {RestPathParams, RestQueryParams, RestRequestBody, RestRequestHeaders, RestResponseBody} from './common';
+
+export type RestApiRequestHandlerWithAuthentication<
+    PathParams extends RestPathParams = never,
+    QueryParams extends RestQueryParams = never,
+    RequestHeaders extends RestRequestHeaders = never,
+    RequestBody extends RestRequestBody = never,
+    ResponseBody extends RestResponseBody = never,
+> = RestApiRequestHandler<PathParams, QueryParams, RequestHeaders, RequestBody, ResponseBody, true>
+
+

package/src/rest/types/RestApiResponse.ts

@@ -0,0 +1,5 @@
+export interface RestApiResponse<ResponseBody> {
+  status: number;
+  headers?: Record<string, string>;
+  body?: ResponseBody;
+}

package/src/rest/types/RestApiRoute.ts

@@ -0,0 +1,34 @@
+import {
+  RestPathParams,
+  RestQueryParams,
+  RestRequestBody,
+  RestRequestHeaders,
+  RestRequireAuthentication,
+  RestResponseBody,
+} from './common';
+
+export type RestHttpMethod = 'GET' | 'POST' | 'DELETE' | 'PATCH' | 'PUT' | 'OPTIONS'
+export type RestRoutePath = `/${string}`
+
+export type RestApiRoute<
+    PathParams extends RestPathParams = never,
+    QueryParams extends RestQueryParams = never,
+    RequestHeaders extends RestRequestHeaders = never,
+    RequestBody extends RestRequestBody = never,
+    ResponseBody extends RestResponseBody = never,
+    RequireAuthentication extends RestRequireAuthentication = false
+> = {
+  method: RestHttpMethod;
+  path: RestRoutePath;
+  buildUrl: (pathParams: PathParams, queryParams: QueryParams) => RestRoutePath;
+  requireAuthentication: RequireAuthentication;
+
+  // this is a workaround to force optional generics to be typesafe
+  __types?: {
+    RequestHeaders: RequestHeaders
+    RequestBody: RequestBody
+    ResponseBody: ResponseBody
+  };
+}
+
+

package/src/rest/types/RestApiRouteHandler.ts

@@ -0,0 +1,22 @@
+import {RestApiRequestHandler} from './RestApiRequestHandler';
+import {RestApiRoute} from './RestApiRoute';
+import {
+  RestPathParams,
+  RestQueryParams,
+  RestRequestBody,
+  RestRequestHeaders,
+  RestRequireAuthentication,
+  RestResponseBody,
+} from './common';
+
+export interface RestApiRouteHandler<
+    PathParams extends RestPathParams = never,
+    QueryParams extends RestQueryParams = never,
+    RequestHeaders extends RestRequestHeaders = never,
+    RequestBody extends RestRequestBody = never,
+    ResponseBody extends RestResponseBody = never,
+    RequireAuthentication extends RestRequireAuthentication = false> {
+  route: RestApiRoute<PathParams, QueryParams, RequestHeaders, RequestBody, ResponseBody, RequireAuthentication>,
+  requestHandler: RestApiRequestHandler<PathParams, QueryParams, RequestHeaders, RequestBody, ResponseBody, RequireAuthentication>,
+}
+

package/src/rest/types/RestApiRouteWithAuthentication.ts

@@ -0,0 +1,12 @@
+import {RestApiRoute} from './RestApiRoute';
+import {RestPathParams, RestQueryParams, RestRequestBody, RestRequestHeaders, RestResponseBody} from './common';
+
+export type RestApiRouteWithAuthentication<
+    PathParams extends RestPathParams = never,
+    QueryParams extends RestQueryParams = never,
+    RequestHeaders extends RestRequestHeaders = never,
+    RequestBody extends RestRequestBody = never,
+    ResponseBody extends RestResponseBody = never,
+> = RestApiRoute<PathParams, QueryParams, RequestHeaders, RequestBody, ResponseBody, true>
+
+

package/src/rest/types/common/BearerToken.ts

@@ -0,0 +1 @@
+export type BearerToken = `Bearer ${string}`

package/src/rest/types/common/RestPathParams.ts

@@ -0,0 +1 @@
+export type RestPathParams = object | never

package/src/rest/types/common/RestQueryParams.ts

@@ -0,0 +1 @@
+export type RestQueryParams = object | never

package/src/rest/types/common/RestRequestBody.ts

@@ -0,0 +1 @@
+export type RestRequestBody = object | never

package/src/rest/types/common/RestRequestHeaders.ts

@@ -0,0 +1 @@
+export type RestRequestHeaders = Record<string, string> | never

package/src/rest/types/common/RestRequestHeadersWithAuthorization.ts

@@ -0,0 +1,11 @@
+import {BearerToken} from "./BearerToken";
+import {RestRequestHeaders} from './RestRequestHeaders';
+import {RestRequireAuthentication} from './RestRequireAuthentication';
+
+export type AuthorizationHeader = { Authorization: BearerToken }
+export type RestRequestHeadersWithAuthorization<
+    RequestHeaders extends RestRequestHeaders,
+    RequireAuthentication extends RestRequireAuthentication
+> = RequireAuthentication extends true
+    ? [RequestHeaders] extends [never] ? AuthorizationHeader : RequestHeaders & AuthorizationHeader
+    : RequestHeaders

package/src/rest/types/common/RestRequireAuthentication.ts

@@ -0,0 +1 @@
+export type RestRequireAuthentication = boolean

package/src/rest/types/common/RestResponseBody.ts

@@ -0,0 +1 @@
+export type RestResponseBody = object | object[] | null | never

package/{dist/rest/types/common/index.js → src/rest/types/common/index.ts}

@@ -6,4 +6,3 @@ export * from './RestRequestBody';
 export * from './RestRequestHeaders';
 export * from './RestRequireAuthentication';
 export * from './RestResponseBody';
-//# sourceMappingURL=index.js.map

package/{dist/rest/types/index.js → src/rest/types/index.ts}

@@ -6,4 +6,3 @@ export * from './RestApiResponse';
 export * from './RestApiRoute';
 export * from './RestApiRouteHandler';
 export * from './RestApiRouteWithAuthentication';
-//# sourceMappingURL=index.js.map

package/src/rest/types/internal/InternalRestApiRequest.ts

@@ -0,0 +1,19 @@
+import {OmitNever} from '../../../types/OmitNever';
+import {RestApiRequest} from '../RestApiRequest';
+import {
+  RestPathParams,
+  RestQueryParams,
+  RestRequestBody,
+  RestRequestHeaders,
+  RestRequireAuthentication,
+} from '../common';
+
+export type InternalRestApiRequest<
+    PathParams extends RestPathParams = never,
+    QueryParams extends RestQueryParams = never,
+    RequestHeaders extends RestRequestHeaders = never,
+    RequestBody extends RestRequestBody = never,
+    RequireAuthentication extends RestRequireAuthentication = false> = OmitNever<
+    RestApiRequest<PathParams, QueryParams, RequestHeaders, RequestBody>
+    & { userId: RequireAuthentication extends true ? string : never }>
+

package/src/rest/types/internal/index.ts

@@ -0,0 +1,2 @@
+export * from './InternalRestApiRequest'
+export * from '../../../types/OmitNever'

package/src/types/OmitNever.ts

@@ -0,0 +1 @@
+export type OmitNever<T> = { [P in keyof T as T[P] extends never ? never : P]: T[P] };

package/src/ws/client/index.ts

@@ -0,0 +1 @@
+export * from './useWsApi'

package/src/ws/client/useWsApi.ts

@@ -0,0 +1,88 @@
+import {useCallback, useMemo, useRef, useState} from 'react';
+import {WsApiAction, WsApiRequest, WsApiResponse, WsApiRoute} from '../types';
+
+type WsApiConnection<
+    Action extends WsApiAction,
+    Request extends WsApiRequest<Action>,
+> = {
+  disconnect: () => void
+  sendRequest: (request: Request) => void
+}
+
+export type WsApiOptions<
+    Action extends WsApiAction,
+    Request extends WsApiRequest<Action>,
+    Response extends WsApiResponse> = {
+  onConnected?: (connection: WsApiConnection<Action, Request>) => void
+  onResponse?: (response: Response, connection: WsApiConnection<Action, Request>) => void
+  onError?: (error: unknown, connection: WsApiConnection<Action, Request>) => void
+  onDisconnected?: () => void
+}
+export const useWsApi = <
+    Action extends WsApiAction,
+    Request extends WsApiRequest<Action>,
+    Response extends WsApiResponse
+>(wsApiUrl: string, route: WsApiRoute<Action, Request, Response> | undefined) => {
+  const [error, setError] = useState<boolean>(false);
+  const [connected, setConnected] = useState<boolean>(false);
+  const webSocket = useRef<WebSocket>();
+
+  const sendRequest = useCallback((request: Omit<Request, 'action'>) => {
+    if (!route) throw 'Not route';
+    if (!webSocket.current) throw 'Not connected';
+
+    webSocket.current.send(JSON.stringify({
+      ...request,
+      action: route.action,
+    }));
+  }, [route]);
+  const disconnect = useCallback(() => webSocket.current?.close(), [webSocket]);
+  const connection: WsApiConnection<Action, Request> = useMemo(() => {
+    return {
+      disconnect,
+      sendRequest,
+    };
+  }, [disconnect, sendRequest]);
+
+  const connect = useCallback(async (options: WsApiOptions<Action, Request, Response>) => {
+    return new Promise<void>((resolve) => {
+      if (webSocket.current && (webSocket.current.readyState === WebSocket.CONNECTING || webSocket.current.readyState === WebSocket.OPEN))
+        throw 'Already connected';
+
+      webSocket.current = new WebSocket(wsApiUrl);
+
+      webSocket.current.onopen = () => {
+        setConnected(true);
+        setError(false);
+        options?.onConnected?.(connection);
+      };
+
+      webSocket.current.onmessage = (ev) => {
+        if (!ev.data || ev.data === '{}')
+          return;
+        setError(false);
+        options?.onResponse?.(JSON.parse(ev.data as string), connection);
+      };
+
+      webSocket.current.onerror = (error) => {
+        setError(false);
+        options?.onError?.(error, connection);
+      };
+
+      webSocket.current.onclose = () => {
+        setConnected(false);
+        options?.onDisconnected?.();
+        webSocket.current = undefined;
+        resolve();
+      };
+    });
+  }, [wsApiUrl, connection]);
+
+  return {
+    connect,
+    connected,
+    connection,
+    error,
+    disconnect,
+  };
+};