@flink-app/flink 0.12.1-alpha.9 → 0.13.1

package/src/FlinkErrors.ts

@@ -4,6 +4,17 @@ import { FlinkResponse } from "./FlinkResponse";
 // A marker for FlinkError, but all it means is that data is undefined
 export type FlinkError = undefined;
 
+/**
+ * Returns a 404 Not Found error response.
+ * Use when a requested resource doesn't exist (e.g., invalid ID, missing entity).
+ *
+ * @param detail - Optional custom error message
+ * @param code - Optional custom error code
+ * @example
+ * ```ts
+ * if (!user) return notFound("User not found");
+ * ```
+ */
 export function notFound(detail?: string, code?: string ): FlinkResponse<FlinkError> {
   return {
     status: 404,
@@ -11,11 +22,22 @@ export function notFound(detail?: string, code?: string ): FlinkResponse<FlinkEr
       id: v4(),
       title: "Not Found",
       detail: detail || "The requested resource does not exist",
-      code : code || "notFound"
+      code : code || "notFound"
     },
   };
 }
 
+/**
+ * Returns a 409 Conflict error response.
+ * Use when a request conflicts with existing data (e.g., duplicate username/email).
+ *
+ * @param detail - Optional custom error message
+ * @param code - Optional custom error code
+ * @example
+ * ```ts
+ * if (existingUser) return conflict("Email already registered");
+ * ```
+ */
 export function conflict(detail?: string, code?: string ): FlinkResponse<FlinkError> {
   return {
     status: 409,
@@ -23,13 +45,24 @@ export function conflict(detail?: string, code?: string ): FlinkResponse<FlinkEr
       id: v4(),
       title: "Conflict",
       detail: detail || "An identical entity exits",
-      code : code || "conflict"
+      code : code || "conflict"
     },
   };
 }
 
 
 
+/**
+ * Returns a 400 Bad Request error response.
+ * Use when the request is malformed or contains invalid data (e.g., validation errors).
+ *
+ * @param detail - Optional custom error message
+ * @param code - Optional custom error code
+ * @example
+ * ```ts
+ * if (!email || !password) return badRequest("Email and password are required");
+ * ```
+ */
 export function badRequest(detail?: string, code?: string): FlinkResponse<FlinkError> {
   return {
     status: 400,
@@ -37,11 +70,23 @@ export function badRequest(detail?: string, code?: string): FlinkResponse<FlinkE
       id: v4(),
       title: "Bad Request",
       detail: detail || "Invalid request",
-      code : code || "badRequest"
+      code : code || "badRequest"
     },
   };
 }
 
+/**
+ * Returns a 401 Unauthorized error response.
+ * Use when authentication is required but missing or invalid (e.g., no token, expired token).
+ * This means "who are you?" - the user needs to identify themselves first.
+ *
+ * @param detail - Optional custom error message
+ * @param code - Optional custom error code
+ * @example
+ * ```ts
+ * if (!ctx.auth?.user) return unauthorized("Authentication required");
+ * ```
+ */
 export function unauthorized(detail?: string, code?: string): FlinkResponse<FlinkError> {
   return {
     status: 401,
@@ -49,12 +94,47 @@ export function unauthorized(detail?: string, code?: string): FlinkResponse<Flin
       id: v4(),
       title: "Unauthorized",
       detail:
-        detail || "User not logged in or or not allowed to access resource",
-      code : code || "badRequest"
+        detail || "Authentication required",
+      code : code || "unauthorized"
     },
   };
 }
 
+/**
+ * Returns a 403 Forbidden error response.
+ * Use when the user is authenticated but lacks permission to access the resource.
+ * This means "I know who you are, but you're not allowed to do this."
+ *
+ * @param detail - Optional custom error message
+ * @param code - Optional custom error code
+ * @example
+ * ```ts
+ * if (ctx.auth?.user?.role !== "admin") return forbidden("Admin access required");
+ * ```
+ */
+export function forbidden(detail?: string, code?: string): FlinkResponse<FlinkError> {
+  return {
+    status: 403,
+    error: {
+      id: v4(),
+      title: "Forbidden",
+      detail: detail || "You do not have permission to access this resource",
+      code : code || "forbidden"
+    },
+  };
+}
+
+/**
+ * Returns a 500 Internal Server Error response.
+ * Use when an unexpected error occurs on the server side.
+ *
+ * @param detail - Optional custom error message
+ * @param code - Optional custom error code
+ * @example
+ * ```ts
+ * try { ... } catch (error) { return internalServerError("Failed to process request"); }
+ * ```
+ */
 export function internalServerError(
   detail?: string,
   code?: string
@@ -65,7 +145,7 @@ export function internalServerError(
       id: v4(),
       title: "Internal Server Error",
       detail: detail || "Something unexpected went wrong",
-      code : code || "internalServerError"
+      code : code || "internalServerError"
     },
   };
 }

package/src/FlinkHttpHandler.ts

@@ -5,24 +5,25 @@ import { FlinkError } from "./FlinkErrors";
 import { FlinkResponse } from "./FlinkResponse";
 
 export enum HttpMethod {
-  get = "get",
-  post = "post",
-  put = "put",
-  delete = "delete",
+    get = "get",
+    post = "post",
+    put = "put",
+    delete = "delete",
 }
 
 type Params = Request["params"];
-type Query = Request["query"];
+
+/**
+ * Query type for request query parameters.
+ * Does currently not allow nested objects, although
+ * underlying express Request does allow it.
+ */
+type Query = Record<string, string | string[] | undefined>;
 
 /**
  * Flink request extends express Request but adds reqId and user object.
  */
-export type FlinkRequest<T = any, P = Params, Q = Query> = Request<
-  P,
-  any,
-  T,
-  Q
-> & { reqId: string; user?: any };
+export type FlinkRequest<T = any, P = Params, Q = Query> = Request<P, any, T, Q> & { reqId: string; user?: any };
 
 /**
  * Route props to control routing.
@@ -31,66 +32,69 @@ export type FlinkRequest<T = any, P = Params, Q = Query> = Request<
  * instructs express web server how to route traffic.
  */
 export interface RouteProps {
-  /**
-   * HTTP method which this handlers responds to.
-   *
-   * Will if not set attempt to extract HTTP method based
-   * on handler file name prefix, for example `GetFoo.ts` will assume
-   * HTTP method `GET`.
-   */
-  method?: HttpMethod;
-
-  /**
-   * Route path including any path params.
-   * Example: `/user/:id`
-   */
-  path: string;
-
-  /**
-   * Generates mock response based on handlers response schema.
-   *
-   * Will be ignored if handler does not have any response schema defined.
-   *
-   * This should only be used during development 💥
-   */
-  mockApi?: boolean;
-
-  /**
-   * Set permissions needed to access route if route requires authentication.
-   */
-  permissions?: string | string[];
-
-  /**
-   * Optional documentation of endpoint. Can be used for example in API docs.
-   * Supports markdown strings.
-   */
-  docs?: string; // TODO
-
-  /**
-   * If handler should not be auto registered
-   */
-  skipAutoRegister?: boolean;
-
-  /**
-   * I.e. filename or plugin name that describes where handler origins from
-   */
-  origin?: string;
+    /**
+     * HTTP method which this handlers responds to.
+     *
+     * Will if not set attempt to extract HTTP method based
+     * on handler file name prefix, for example `GetFoo.ts` will assume
+     * HTTP method `GET`.
+     */
+    method?: HttpMethod;
+
+    /**
+     * Route path including any path params.
+     * Example: `/user/:id`
+     */
+    path: string;
+
+    /**
+     * Generates mock response based on handlers response schema.
+     *
+     * Will be ignored if handler does not have any response schema defined.
+     *
+     * This should only be used during development 💥
+     */
+    mockApi?: boolean;
+
+    /**
+     * Set permissions needed to access route if route requires authentication.
+     */
+    permissions?: string | string[];
+
+    /**
+     * Optional documentation of endpoint. Can be used for example in API docs.
+     * Supports markdown strings.
+     */
+    docs?: string; // TODO
+
+    /**
+     * If handler should not be auto registered
+     */
+    skipAutoRegister?: boolean;
+
+    /**
+     * I.e. filename or plugin name that describes where handler origins from
+     */
+    origin?: string;
+
+    /**
+     * Order handler should be registered in.
+     *
+     * By default all handlers has order 0 and in most cases this is fine,
+     * but if for example you want to register a handler before all others
+     * to avoid conflicts you can set a negative order.
+     */
+    order?: number;
 }
 
 /**
  * Http handler function that handlers implements in order to
  * handle HTTP requests and return a JSON response.
  */
-export type Handler<
-  Ctx extends FlinkContext,
-  ReqSchema = any,
-  ResSchema = any,
-  P extends Params = Params,
-  Q extends Query = Query
-> = (props: {
-  req: FlinkRequest<ReqSchema, P, Q>;
-  ctx: Ctx;
-  origin?: string;
+export type Handler<Ctx extends FlinkContext, ReqSchema = any, ResSchema = any, P extends Params = Params, Q extends Query = Query> = (props: {
+    req: FlinkRequest<ReqSchema, P, Q>;
+    ctx: Ctx;
+    origin?: string;
 }) => Promise<FlinkResponse<ResSchema | FlinkError>>;
 
 /**
@@ -99,12 +103,7 @@ export type Handler<
  *
  * Just syntactic sugar on top op `HandlerFn`
  */
-export type GetHandler<
-  Ctx extends FlinkContext,
-  ResSchema = any,
-  P extends Params = Params,
-  Q extends Query = Query
-> = Handler<Ctx, any, ResSchema, P, Q>;
+export type GetHandler<Ctx extends FlinkContext, ResSchema = any, P extends Params = Params, Q extends Query = Query> = Handler<Ctx, any, ResSchema, P, Q>;
 
 /**
  * Type for Handler file. Describes shape of exports when using
@@ -113,32 +112,32 @@ export type GetHandler<
  * `import * as FooHandler from "./src/handlers/FooHandler"
  */
 export type HandlerFile = {
-  default: Handler<any, any, any, any, any>;
-  Route?: RouteProps;
-  /**
-   * Name of schemas, is set at compile time by Flink compiler.
-   */
-  __schemas?: {
-    reqSchema?: JSONSchema;
-    resSchema?: JSONSchema;
-  };
-  /**
-   * Typescript source file name, is set at compile time by Flink compiler.
-   */
-  __file?: string;
-
-  /**
-   * Description of query params, is set at compile time by Flink compiler.
-   */
-  __query?: QueryParamMetadata[];
-
-  /**
-   * Description of path params, is set at compile time by Flink compiler.
-   */
-  __params?: QueryParamMetadata[];
+    default: Handler<any, any, any, any, any>;
+    Route?: RouteProps;
+    /**
+     * Name of schemas, is set at compile time by Flink compiler.
+     */
+    __schemas?: {
+        reqSchema?: JSONSchema;
+        resSchema?: JSONSchema;
+    };
+    /**
+     * Typescript source file name, is set at compile time by Flink compiler.
+     */
+    __file?: string;
+
+    /**
+     * Description of query params, is set at compile time by Flink compiler.
+     */
+    __query?: QueryParamMetadata[];
+
+    /**
+     * Description of path params, is set at compile time by Flink compiler.
+     */
+    __params?: QueryParamMetadata[];
 };
 
 export type QueryParamMetadata = {
-  name: string;
-  description: string;
+    name: string;
+    description: string;
 };

package/src/FlinkRepo.ts

@@ -82,7 +82,14 @@ export abstract class FlinkRepo<C extends FlinkContext, Model extends Document>
         return deletedCount || 0;
     }
 
-    private buildId(id: string | ObjectId) {
+    /**
+     * Helper to ensure the id is always an ObjectId.
+     * If a string is passed, it will be converted to an ObjectId.
+     * If an ObjectId is passed, it will be returned as is.
+     * @param id
+     * @returns
+     */
+    buildId(id: string | ObjectId) {
         let oid: ObjectId | string;
 
         if (typeof id === "string") {

package/src/FlinkResponse.ts

@@ -1,48 +1,45 @@
 import { Response, Request } from "express";
 
 export interface FlinkResponse<T = any> {
-  /**
-   * Unique id of request.
-   * Used to track request in logs.
-   */
-  reqId?: string;
+    /**
+     * Unique id of request.
+     * Used to track request in logs.
+     */
+    reqId?: string;
 
-  /**
-   * HTTP status code, default to 200.
-   */
-  status?: number;
+    /**
+     * HTTP status code, default to 200.
+     */
+    status?: number;
 
-  /**
-   * Optional redirect. Will trigger a redirect of provided type.
-   */
-  redirect?: {
-    to: string;
-    type?: "TEMPORARY" | "PERMANENT";
-  };
+    /**
+     * Optional redirect. Will trigger a redirect of provided type.
+     */
+    redirect?: {
+        to: string;
+        type?: "TEMPORARY" | "PERMANENT";
+    };
 
-  /**
-   * Actual payload to return.
-   */
-  data?: T;
+    /**
+     * Actual payload to return.
+     */
+    data?: T;
 
-  /**
-   * Error object set if error response.
-   * If set the `status` is set to 4xx or 5xx code.
-   */
-  error?: {
-    id: string;
-    title: string;
-    detail?: string;
-    code?: string;
-  };
+    /**
+     * Error object set if error response.
+     * If set the `status` is set to 4xx or 5xx code.
+     */
+    error?: {
+        id: string;
+        title: string;
+        detail?: string;
+        code?: string;
+    };
 
-  /**
-   * HTTP headers, names are lower cased
-   */
-  headers?: {
-    [x: string]: string;
-  };
+    /**
+     * HTTP headers, names are lower cased
+     */
+    headers?: {
+        [x: string]: string;
+    };
 }
-
-export type ExpressResponse = Response;
-export type ExpressRequest = Request;