arkos 2.0.0-next.2 → 2.0.0-next.21

package/dist/types/types/new-arkos-config.d.ts

@@ -1,5 +1,5 @@
 import cors from "cors";
-import express from "express";
+import express, { CookieOptions } from "express";
 import { Options as RateLimitOptions } from "express-rate-limit";
 import cookieParser from "cookie-parser";
 import compression from "compression";
@@ -11,16 +11,52 @@ import type { ApiReferenceConfiguration } from "@scalar/express-api-reference" w
 import nodemailer from "nodemailer";
 import { ArkosRequestHandler } from ".";
 import { PrismaClient } from "../generated";
+import { AuthenticateHookHandler, AuthenticateAfterHookHandler, AuthenticateErrorHookHandler, AuthorizeHookHandler, AuthorizeAfterHookHandler, AuthorizeErrorHookHandler } from "./arkos-config/utils";
 /**
  * Defines the initial configs of the api to be loaded at startup when arkos.init() is called.
  */
 export type ArkosConfig = {
+    /**
+     * Configuration for resolving your Arkos application's source files at runtime.
+     *
+     * @since 1.6.1-canary.2
+     *
+     */
+    source?: {
+        /**
+         * The entry point file of your Arkos application, resolved at runtime.
+         *
+         * This should point to the file where `app.listen()` or `app.listen(server)`
+         * is called to start the HTTP server.
+         *
+         * Supports both TypeScript and JavaScript projects.
+         *
+         * @type {string}
+         *
+         * @default "src/app.ts" (TypeScript) | "src/app.js" (JavaScript)
+         *
+         * @since 1.6.1-canary.2
+         *
+         * @example
+         * ```ts
+         * // TypeScript project
+         * entryPoint: "src/app.ts"
+         *
+         * // JavaScript project
+         * entryPoint: "src/app.js"
+         *
+         * // Custom path
+         * entryPoint: "src/server/main.ts"
+         * ```
+         */
+        entryPoint?: string;
+    };
     /**
      * The global prefixer for the whole application
      *
      * @default "/api"
      */
-    globalPrefix?: string;
+    readonly globalPrefix?: string;
     /**
      * Allows to configure request configs
      */
@@ -66,14 +102,137 @@ export type ArkosConfig = {
     /**
      * Defines authentication related configurations, by default is undefined.
      *
-     * See [www.arkosjs.com/docs/core-concepts/authentication-system](https://www.arkosjs.com/docs/core-concepts/authentication-system) for details.
+     * See [www.arkosjs.com/docs/core-concepts/authentication/setup](https://www.arkosjs.com/docs/core-concepts/authentication/setup) for details.
      */
     authentication?: {
+        /**
+         * Lifecycle hooks for the built-in authentication and authorization pipeline.
+         *
+         * These hooks only apply to **auto-generated Arkos routes**. On custom routes using
+         * `authService.authenticate` directly, chain them manually as standard middlewares.
+         *
+         * Hooks run as standard Express middlewares — call `next()` to continue or
+         * `next(error)` to abort and forward to the global error handler.
+         *
+         * @see {@link https://www.arkosjs.com/docs/core-concepts/authentication/hooks}
+         */
+        hooks?: {
+            authenticate?: {
+                /**
+                 * Runs before JWT extraction and verification.
+                 *
+                 * @example
+                 * ```ts
+                 * before: ({ req, skip, action, resource, rule }) => {
+                 *   req.authContext = { startedAt: Date.now() };
+                 * }
+                 * ```
+                 *
+                 * @example Skip core logic entirely (e.g. custom auth)
+                 * ```ts
+                 * before: ({ req, skip, action, resource, rule }) => {
+                 *   req.user = myCustomAuth(req);
+                 *   skip();
+                 * }
+                 * ```
+                 */
+                before?: AuthenticateHookHandler | AuthenticateHookHandler[];
+                /**
+                 * Runs after `req.user` has been set.
+                 *
+                 * @example
+                 * ```ts
+                 * after: ({ req }) => {
+                 *   if (!req.user.hasChangedPassword) {
+                 *     throw new AppError("Password change required.", 403, "PasswordChangeRequired");
+                 *   }
+                 * }
+                 * ```
+                 */
+                after?: AuthenticateAfterHookHandler | AuthenticateAfterHookHandler[];
+                /**
+                 * Runs when authentication throws — invalid token, expired token, user not found, etc.
+                 * Throw to forward to the global error handler, or call `skip()` to suppress and jump to `after` hooks.
+                 *
+                 * @example
+                 * ```ts
+                 * onError: ({ req, error, skip, action, resource, rule }) => {
+                 *   console.warn(`Auth failed:`, error);
+                 *   throw error;
+                 * }
+                 * ```
+                 *
+                 * @example Suppress error and continue
+                 * ```ts
+                 * onError: ({ req, skip, action, resource, rule }) => {
+                 *   req.user = guestUser;
+                 *   skip();
+                 * }
+                 * ```
+                 */
+                onError?: AuthenticateErrorHookHandler | AuthenticateErrorHookHandler[];
+            };
+            authorize?: {
+                /**
+                 * Runs before the role/permission check.
+                 *
+                 * @example
+                 * ```ts
+                 * before: ({ req }) => {
+                 *   if (req.headers["x-elevated-access"] === process.env.ELEVATION_KEY) {
+                 *     req.user.role = "admin";
+                 *   }
+                 * }
+                 * ```
+                 *
+                 * @example Skip permission check entirely
+                 * ```ts
+                 * before: ({ req, skip, action, resource, rule }) => {
+                 *   req.user.role = myCustomRoleResolver(req);
+                 *   skip();
+                 * }
+                 * ```
+                 */
+                before?: AuthorizeHookHandler | AuthorizeHookHandler[];
+                /**
+                 * Runs after the permission check passes.
+                 *
+                 * @example
+                 * ```ts
+                 * after: ({ req }) => {
+                 *   auditLog.record({ userId: req.user.id, path: req.path });
+                 * }
+                 * ```
+                 */
+                after?: AuthorizeAfterHookHandler | AuthorizeAfterHookHandler[];
+                /**
+                 * Runs when the user lacks sufficient permissions (403).
+                 * Throw to forward to the global error handler, or call `skip()` to suppress and jump to `after` hooks.
+                 *
+                 * @example
+                 * ```ts
+                 * onError: ({ req, error, action, resource, rule }) => {
+                 *   auditLog.record({ userId: req.user?.id, reason: "insufficient_permissions" });
+                 *   throw error;
+                 * }
+                 * ```
+                 *
+                 * @example Suppress error and continue
+                 * ```ts
+                 * onError: ({ req, skip, action, resource, rule }) => {
+                 *   req.user.role = "guest";
+                 *   skip();
+                 * }
+                 * ```
+                 */
+                onError?: AuthorizeErrorHookHandler | AuthorizeErrorHookHandler[];
+            };
+        };
         enabled?: boolean;
         /**
          * Defines whether to use Static or Dynamic Role-Based Acess Control
          *
-         * Visit [www.arkosjs.com/docs/core-concepts/authentication-system](https://www.arkosjs.com/docs/core-concepts/authentication-system) for more details.
+         * Visit [www.arkosjs.com/docs/core-concepts/authentication/setup](https://www.arkosjs.com/docs/core-concepts/authentication/setup) for more details.
          */
         mode: "static" | "dynamic";
         /**
@@ -96,7 +255,7 @@ export type ArkosConfig = {
              * POST /api/auth/login?usernameField=email
              * ```
              *
-             * See more at [www.arkosjs.com/docs/core-concepts/authentication-system#login-with-different-fileds](https://www.arkosjs.com/docs/core-concepts/authentication-system#login-with-different-fileds)
+             * See more at [www.arkosjs.com/docs/core-concepts/authentication/setup#login-with-different-fileds](https://www.arkosjs.com/docs/core-concepts/authentication/setup#login-with-different-fileds)
              *
              * By specifing here another field for username, for example passing "email", "companyCode" or something else your json will be like:
              *
@@ -113,19 +272,6 @@ export type ArkosConfig = {
             /** Defines wether to send the access token in response after login or only send as cookie, defeault is both.*/
             sendAccessTokenThrough?: "cookie-only" | "response-only" | "both";
         };
-        /**
-         * Specifies the regex pattern used by the authentication system to enforce password strength requirements.
-         *
-         * **Important**: If using validation libraries like Zod or class-validator, this will be completely overwritten.
-         *
-         * **Default**: ```/^(?=.*[A-Z])(?=.*[a-z])(?=.*\d).+$/``` - Ensures the password contains at least one uppercase letter, one lowercase letter, and one numeric digit.
-         *
-         * **message**: (Optional) A custom error message to display when the password does not meet the required strength criteria.
-         */
-        passwordValidation?: {
-            regex: RegExp;
-            message?: string;
-        };
         /**
          * Allows to specify the request rate limit for all authentication endpoints but `/api/users/me`.
          *
@@ -172,20 +318,42 @@ export type ArkosConfig = {
                 /**
                  * Whether the cookie should be marked as secure (sent only over HTTPS).
                  * Defaults to `true` in production and `false` in development.
+                 *
+                 * @env `JWT_COOKIE_SECURE`
                  */
                 secure?: boolean;
                 /**
                  * Whether the cookie should be marked as HTTP-only.
                  * Default is `true` to prevent access via JavaScript.
+                 *
+                 * @env `JWT_COOKIE_HTTP_ONLY`
                  */
                 httpOnly?: boolean;
                 /**
                  * Controls the SameSite attribute of the cookie.
                  * Defaults to "none" in production and "lax" in development.
                  * Options: "lax" | "strict" | "none"
+                 *
+                 * @env `JWT_COOKIE_SAME_SITE`
                  */
                 sameSite?: "lax" | "strict" | "none";
-            };
+                /**
+                 * Expiry date of the cookie in GMT. If not specified (undefined), creates a session cookie.
+                 *
+                 * @default `now() + authentication.jwt.expireIn | JWT_EXPIRES_IN`
+                 *
+                 * @since 1.5.11-beta
+                 */
+                expires?: Date | undefined;
+                /**
+                 * Domain for the cookie. Use a leading dot (e.g. `.example.com`) to include all subdomains.
+                 *
+                 * @env `JWT_COOKIE_DOMAIN`
+                 *
+                 * @since 1.5.11-beta
+                 */
+                domain?: string | undefined;
+            } & Omit<CookieOptions, "secure" | "httpOnly" | "sameSite" | "expires" | "domain">;
         };
     };
     /** Allows to customize and toggle the built-in validation, by default it is set to `false`. If true is passed it will use validation with the default resolver set to `class-validator` if you intend to change the resolver to `zod` do the following:
@@ -201,7 +369,7 @@ export type ArkosConfig = {
      * })
      * ```
      *
-     * @See [www.arkosjs.com/docs/core-concepts/request-data-validation](https://www.arkosjs.com/docs/core-concepts/request-data-validation) for more details.
+     * @See [www.arkosjs.com/docs/guides/validation/setup](https://www.arkosjs.com/docs/guides/validation/setup) for more details.
      */
     validation?: {
         /**
@@ -225,6 +393,8 @@ export type ArkosConfig = {
          * })
          *
          * ```
+         *
+         * @since 1.4.0-beta
          */
         strict?: boolean;
     } & ({
@@ -243,6 +413,9 @@ export type ArkosConfig = {
         validationOptions?: ValidatorOptions;
     } | {
         resolver: "zod";
+        /**
+         * @since v1.5.0-beta
+         */
         validationOptions?: {
             /**
              * Throws an error for know whitelisted fields
@@ -255,9 +428,15 @@ export type ArkosConfig = {
     /**
      * Defines file upload configurations
      *
-     * See [www.arkosjs.com/docs/core-concepts/file-upload#costum-configurations](https://www.arkosjs.com/docs/core-concepts/file-upload#costum-configurations)
+     * See {@link https://www.arkosjs.com/docs/guides/file-handling/file-uploads/setup}
      */
     fileUpload?: {
+        /**
+         * Disables built-in file upload
+         *
+         * @since 1.5.11-beta
+         */
+        enabled?: boolean;
         /**
          * Defiens the base file upload directory, default is set to /uploads (on root directory)
          *
@@ -292,7 +471,7 @@ export type ArkosConfig = {
               etag: true,
               lastModified: true,
               dotfiles: "ignore",
-              fallthrough: true,
+              fallthrough: false,
               index: false,
               cacheControl: true,
             }
@@ -312,7 +491,7 @@ export type ArkosConfig = {
          * Passing an object without overriding everything will only cause it
          * to be deepmerged with the default options.
          *
-         * See [www.arkosjs.com/docs/api-reference/default-supported-upload-files](https://www.arkosjs.com/docs/api-reference/default-supported-upload-files) for detailed explanation about default values.
+         * See [www.arkosjs.com/docs/reference/default-supported-upload-files](https://www.arkosjs.com/docs/reference/default-supported-upload-files) for detailed explanation about default values.
          * ```
          */
         restrictions?: {
@@ -371,25 +550,35 @@ export type ArkosConfig = {
         /**
          * Configuration for CORS (Cross-Origin Resource Sharing).
          *
-         * @property {string | string[] | "all"} [allowedOrigins] - List of allowed origins. If set to `"all"`, all origins are accepted.
-         * @property {import('cors').CorsOptions} [options] - Additional CORS options passed directly to the `cors` middleware.
-         * @property {import('cors').CorsOptionsDelegate} [customHandler] - A custom middleware function that overrides the default behavior.
+         * Accepts:
+         * - `false` — disables CORS middleware entirely.
+         * - `cors.CorsOptions` — passed directly to the `cors` middleware.
+         * - `cors.CorsOptionsDelegate` — a delegate function passed directly to the `cors` middleware.
+         * - `ArkosRequestHandler` — a full Express middleware that replaces the cors middleware entirely.
+         * - An object with deprecated `allowedOrigins`, `options`, and `customHandler` properties.
          *
-         * @remarks
-         * If `customHandler` is provided, both `allowedOrigins` and `options` will be ignored in favor of the custom logic.
+         * In development, defaults to `origin: true, credentials: true`.
+         * In production, defaults to `origin: "*"` (equivalent to plain `cors()`).
          *
          * See https://www.npmjs.com/package/cors
          */
-        cors?: false | {
+        cors?: false | cors.CorsOptions | cors.CorsOptionsDelegate | {
+            /**
+             * Defines allowed origins to access the API.
+             *
+             * @deprecated Use `cors: { origin: string | string[] }` (cors.CorsOptions) directly instead.
+             */
+            allowedOrigins?: string | string[] | "*" | true;
             /**
-             * Defines allowed origins to acess the API.
+             * Additional cors options.
+             *
+             * @deprecated Pass cors.CorsOptions directly instead: `cors: { origin: "...", credentials: true }`.
              */
-            allowedOrigins?: string | string[] | "*";
             options?: cors.CorsOptions;
             /**
-             * If you would like to override the entire middleware
+             * If you would like to override the entire middleware.
              *
-             * see
+             * @deprecated Pass the handler directly instead: `cors: myCorsHandler`.
              */
             customHandler?: cors.CorsOptionsDelegate;
         } | ArkosRequestHandler;
@@ -404,7 +593,10 @@ export type ArkosConfig = {
          *
          * See [www.npmjs.com/package/cookie-parser](https://www.npmjs.com/package/cookie-parser) for further details.
          */
-        cookieParser?: false | Parameters<typeof cookieParser> | ArkosRequestHandler;
+        cookieParser?: false | {
+            secret?: string | string[];
+            options?: Parameters<typeof cookieParser>[1];
+        } | ArkosRequestHandler;
         /**
        * Options to define how query must be parsed.
        *
@@ -479,7 +671,7 @@ export type ArkosConfig = {
     /**
      * Allows to configure email configurations for sending emails through `emailService`
      *
-     * See [www.arkosjs.com/docs/core-concepts/sending-emails](https://www.arkosjs.com/docs/core-concepts/sending-emails)
+     * See [www.arkosjs.com/docs/guides/email-service](https://www.arkosjs.com/docs/guides/email-service)
      */
     email?: {
         /**
@@ -542,13 +734,18 @@ export type ArkosConfig = {
      *  }
      * })
      * ```
-     * @see {@link https://www.arkosjs.com/docs/core-concepts/open-api-documentation}
+     * @see {@link https://www.arkosjs.com/docs/guides/open-api-documentation/setup}
      */
     swagger?: {
         /**
          * By default Arkos will disable API Documentation when the project is built `npm run build`, it does not matter what node environment is set. If you want to use it even after the `arkos build` command just set this to `true`.
          * */
         enableAfterBuild?: boolean;
+        /**
+         * Whether to require superUser authentication to access docs in production.
+         * Default: true after build
+         */
+        authenticate?: boolean;
         /**
          * Endpoint where the Swagger UI will be available.
          *
@@ -732,4 +929,97 @@ export type ArkosConfig = {
          */
         instance: PrismaClient;
     };
+    /**
+     * Allows to suppress specific warnings emitted by Arkos at startup or runtime.
+     *
+     * @since 1.5.10-beta
+     */
+    warnings?: {
+        /**
+         * Suppresses specific warning messages.
+         */
+        suppress?: {
+            /**
+             * Suppresses Prisma-related warnings.
+             */
+            prisma?: {
+                /**
+                 * Suppresses the warning emitted when no Prisma instance is found.
+                 */
+                noInstanceFound?: boolean;
+                /**
+                 * Suppresses the warning emitted when no Prisma schema is found.
+                 */
+                noSchemaFound?: boolean;
+            };
+        };
+    };
+    /**
+     * Defines static file serving configurations.
+     *
+     * Arkos will automatically serve files from the configured folder using `express.static`.
+     * If the folder does not exist at startup, a warning will be emitted.
+     *
+     * **Note:** The static files route is **not** prefixed with the `globalPrefix`.
+     *
+     * @since 1.7.0-canary.16
+     *
+     * @example
+     * ```ts
+     * import { defineConfig } from "arkos"
+     *
+     * export default defineConfig({
+     *   staticFiles: {
+     *     folder: "assets",
+     *     prefix: "/static",
+     *   }
+     * })   */
+    staticFiles?: {
+        /**
+         * Whether to enable static file serving.
+         *
+         * Set to `false` to disable static file serving entirely and suppress
+         * the warning when the folder is not found.
+         *
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * The folder to serve static files from, relative to the project root.
+         *
+         * @default "public"
+         */
+        folder?: string;
+        /**
+         * The URL path prefix under which static files will be served.
+         *
+         * **Note:** This is not affected by `globalPrefix`.
+         *
+         * @default "/"
+         *
+         * @example "/static" // files served at /static/image.png
+         */
+        prefix?: string;
+        /**
+         * Options passed directly to `express.static()`.
+         *
+         * By passing custom options, they will be deep merged with the defaults.
+         *
+         * #### Default:
+         * ```ts
+         * {
+         *   maxAge: "1y",
+         *   etag: true,
+         *   lastModified: true,
+         *   dotfiles: "ignore",
+         *   fallthrough: true,
+         *   index: false,
+         *   cacheControl: true,
+         * }
+         * ```
+         *
+         * @see {@link https://expressjs.com/en/4x/api.html#express.static}
+         */
+        expressStatic?: Parameters<typeof express.static>[1];
+    };
 };

package/dist/types/types/router-config.d.ts

@@ -1,66 +1,3 @@
-import { ArkosRouteConfig } from "../exports";
 export type RouterEndpoint = "createOne" | "findOne" | "updateOne" | "deleteOne" | "findMany" | "createMany" | "updateMany" | "deleteMany";
 export type AuthRouterEndpoint = "getMe" | "updateMe" | "deleteMe" | "login" | "logout" | "signup" | "updatePassword" | "findManyAuthAction" | "findOneAuthAction";
 export type FileUploadRouterEndpoint = "findFile" | "uploadFile" | "updateFile" | "deleteFile";
-type BaseRouterConfig = {
-    /**
-     * Backward compatibility (prior 1.4.0-beta) - disables/enables endpoints
-     *
-     * prefer to rather to use the following:
-     *
-     * ```ts
-     * export const config = {
-     *  findMany: {
-     *    disabled: true
-     *  }
-     * }
-     * ```
-     */
-    disable?: boolean | {
-        [K in RouterEndpoint]?: boolean;
-    };
-} & {
-    [K in RouterEndpoint]?: Omit<ArkosRouteConfig, "path">;
-};
-type AuthRouterConfig = {
-    /**
-     * Backward compatibility (prior 1.4.0-beta) - disables/enables endpoints
-     *
-     * prefer to rather to use the following:
-     *
-     * ```ts
-     * export const config = {
-     *  getMe: {
-     *    disabled: true
-     *  }
-     * }
-     * ```
-     */
-    disable?: boolean | {
-        [K in AuthRouterEndpoint]?: boolean;
-    };
-} & {
-    [K in AuthRouterEndpoint]?: Omit<ArkosRouteConfig, "path">;
-};
-type FileUploadRouterConfig = {
-    /**
-     * Backward compatibility (prior 1.4.0-beta) - disables/enables endpoints
-     *
-     * prefer to rather to use the following:
-     *
-     * ```ts
-     * export const config = {
-     *  deleteFile: {
-     *    disabled: true
-     *  }
-     * }
-     * ```
-     */
-    disable?: boolean | {
-        [K in FileUploadRouterEndpoint]?: boolean;
-    };
-} & {
-    [K in FileUploadRouterEndpoint]?: Omit<ArkosRouteConfig, "path" | "uploads">;
-};
-export type RouterConfig<T extends string = string> = T extends "auth" ? AuthRouterConfig : T extends "file-upload" ? FileUploadRouterConfig : BaseRouterConfig;
-export {};

package/dist/types/types/upload.d.ts

@@ -0,0 +1,10 @@
+export interface ArkosFile extends Express.Multer.File {
+    /**
+     * The file pathname without the server host
+     */
+    pathname: string;
+    /**
+     * The file full URL
+     */
+    url: string;
+}

package/dist/types/types/validation/validation-manager.d.ts

@@ -0,0 +1,27 @@
+import validateDto from "../../utils/validate-dto";
+import validateSchema from "../../utils/validate-schema";
+import { ArkosConfig } from "../new-arkos-config";
+import { Validator } from "./validator";
+declare class ValidationManager {
+    arkosConfig: ArkosConfig;
+    get validationConfig(): ({
+        strict?: boolean;
+    } & ({
+        resolver: "class-validator";
+        validationOptions?: import("class-validator").ValidatorOptions;
+    } | {
+        resolver: "zod";
+        validationOptions?: {
+            forbidNonWhitelisted?: boolean;
+        };
+    })) | undefined;
+    get validatorName(): "zod schema" | "class-validator dto";
+    get validationFn(): typeof validateSchema | typeof validateDto;
+    get validatorNameType(): "Schema" | "Dto";
+    isValidValidator: (validator: Validator) => boolean;
+    isValidator: (validator: Validator) => boolean;
+    shouldValidate: (validator: Validator, data: any) => "prohibit" | "passthrough" | "validate";
+    getInvalidValidatorError(): void;
+}
+declare const validationManager: ValidationManager;
+export default validationManager;

package/dist/types/types/validation/validator.d.ts

@@ -0,0 +1,2 @@
+import { ZodSchema } from "zod";
+export type Validator = ZodSchema | (new (...args: any[]) => object) | null | false;

package/dist/types/utils/arkos-router/arkos-router-openapi-manager.d.ts

@@ -1,6 +1,7 @@
 import { OpenAPIV3 } from "openapi-types";
 import { UploadConfig } from "./types/upload-config";
 declare class ArkosRouterOpenAPIManager {
+    private resolveSchemaFieldName;
     /**
      * Generates OpenAPI schema for file upload fields in multipart/form-data requests.
      * Converts upload configuration into OpenAPI-compliant schema and merges with existing body schema.
@@ -20,9 +21,21 @@ declare class ArkosRouterOpenAPIManager {
      *
      * @example
      * // Multiple fields upload
-     * addUploadFields({ type: 'fields', fields: [{ name: 'avatar', maxCount: 1 }, { name: 'resume', maxCount: 1 }] })
+     * addUploadFields({
+     *   type: 'fields',
+     *   fields: [
+     *     { name: 'avatar', type: 'single', uploadDir: 'images' },
+     *     { name: 'gallery', type: 'array', maxCount: 6, uploadDir: 'gallery' },
+     *     { name: 'banners[][images]', type: 'array', maxCount: 5, uploadDir: 'banners' }
+     *   ]
+     * })
      */
     addUploadFields(uploadConfig: UploadConfig, existingSchema?: OpenAPIV3.SchemaObject): OpenAPIV3.SchemaObject;
+    /**
+     * Builds the OpenAPI property schema for a single field entry.
+     * Legacy entries (no type) are treated as array.
+     */
+    private buildFieldSchema;
     /**
      * Validates that a user-defined multipart/form-data schema includes all required upload fields
      * with correct types, formats, and required flags.