arkos 2.0.0-next.3 → 2.0.0-next.30

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 {};
+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';

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

@@ -0,0 +1,45 @@
+import type { ArkosFileInternalState } from "./internal";
+import type { ArkosRequest } from "./index";
+export type UploadDirParams = Record<string, string>;
+export type UploadUrlPath = string | {
+    exact: string;
+};
+/**
+ * Resolves the disk parameters for an upload or serving folder.
+ *
+ * It is the only source of disk parameters. It may perform authorization and
+ * throw to deny the request.
+ */
+export type UploadPrepare = (req: ArkosRequest, locals: Record<string, any>) => {
+    dirParams?: UploadDirParams;
+} | Promise<{
+    dirParams?: UploadDirParams;
+}>;
+export type PrepareFileContext = {
+    file: ArkosFile;
+    dirParams: UploadDirParams;
+    index: number;
+};
+/**
+ * Resolves per-file data before a file is written. Only `filename` is
+ * consumed; the file extension is always preserved.
+ */
+export type UploadPrepareFile = (context: PrepareFileContext, req: ArkosRequest, locals: Record<string, any>) => {
+    filename?: string;
+} | Promise<{
+    filename?: string;
+}>;
+export interface ArkosFile extends Express.Multer.File {
+    /**
+     * The file pathname without the server host
+     */
+    pathname: string;
+    /**
+     * The file full URL
+     */
+    url: string;
+    /**
+     * @internal Upload metadata resolved by Arkos.
+     */
+    __arkos?: ArkosFileInternalState;
+}

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

@@ -0,0 +1,25 @@
+import type { UserArkosConfig } from "../../utils/define-config";
+import { Validator } from "./validator";
+declare class ValidationManager {
+    arkosConfig: UserArkosConfig;
+    get validationConfig(): ({
+        strict?: boolean;
+    } & ({
+        resolver: "class-validator";
+        validationOptions?: import("class-validator").ValidatorOptions;
+    } | {
+        resolver: "zod" | "hybrid";
+        validationOptions?: {
+            forbidNonWhitelisted?: boolean;
+        };
+    })) | undefined;
+    get validatorName(): "zod schema or class-validator dto" | "zod schema" | "class-validator dto";
+    get validationFn(): (schema: any, data: any, options: any) => Promise<unknown>;
+    get validatorNameType(): "Schema or Dto" | "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 { ZodType } from "zod";
+export type Validator = ZodType | (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.

package/dist/types/utils/arkos-router/index.d.ts

@@ -1,6 +1,85 @@
-import { RouterOptions } from "express";
-import { IArkosRouter } from "./types";
-import { OpenAPIV3 } from "openapi-types";
+import { RouterOptions } from 'express';
+import { IArkosRouter } from './types';
+import { OpenAPIV3 } from 'openapi-types';
+import { Arkos } from '../../types/arkos';
+import { ArkosRouterBaseUploadConfig } from './types/upload-config';
+export type ArkosRouterOptions = {
+    /**
+     * Prefix to apply to all routes in this router.
+     * Nested routers inherit and concatenate prefixes from parent routers.
+     *
+     * @since 1.5.0-beta
+     * @example
+     * // All routes in this router will be prefixed with "/api"
+     * prefix: "/api"
+     */
+    prefix?: string | RegExp | Array<string | RegExp>;
+    /**
+     * OpenAPI metadata to apply to all routes in this router.
+     * Nested routers inherit from parent routers unless explicitly overridden.
+     * Route-level openapi config fully replaces inherited values when defined.
+     *
+     * @since 1.6.0-beta
+     * @example
+     * openapi: {
+     *   tags: ["Users"],
+     *   security: [{ bearerAuth: [] }]
+     * }
+     */
+    openapi?: {
+        /**
+         * Tags to apply to all routes in this router, used to group them in OpenAPI documentation.
+         * Route-level tags fully replaces this value when defined.
+         *
+         * @since 1.6.0-beta
+         * @example
+         * // Group all routes in this router under "Users"
+         * tags: ["Users"]
+         */
+        tags?: string[];
+        /**
+         * Security requirements to apply to all routes in this router.
+         * Route-level security fully replaces this value when defined.
+         *
+         * @since 1.6.2-canary.1
+         * @example
+         * // Require bearer auth for all routes in this router
+         * security: [{ bearerAuth: [] }]
+         *
+         * // Explicitly make all routes public (overridable per route)
+         * security: []
+         */
+        security?: OpenAPIV3.SecurityRequirementObject[];
+        /**
+         * Server definitions to apply to all routes in this router.
+         * Follows the OpenAPI 3.0 Server Object specification.
+         * Route-level servers fully replaces this value when defined.
+         *
+         * @since 1.6.2-canary.1
+         * @example
+         * servers: [{ url: "https://api.example.com/v2", description: "V2 API" }]
+         */
+        servers?: OpenAPIV3.ServerObject[];
+        /**
+         * External documentation to apply to all routes in this router.
+         * Route-level externalDocs fully replaces this value when defined.
+         *
+         * @since 1.6.2-canary.1
+         * @example
+         * externalDocs: {
+         *   description: "Find more information here",
+         *   url: "https://docs.example.com/users"
+         * }
+         */
+        externalDocs?: OpenAPIV3.ExternalDocumentationObject;
+    };
+    /**
+     * Allow customizing uploads on route level
+     *
+     * @since 1.7.0-canary.39
+     */
+    uploads?: ArkosRouterBaseUploadConfig;
+};
 /**
  * Creates an enhanced Express Router with features like OpenAPI documentation capabilities and smart data validation.
  *
@@ -23,15 +102,11 @@ import { OpenAPIV3 } from "openapi-types";
  *
  * @returns {IArkosRouter} A proxied Express Router instance with enhanced OpenAPI capabilities
  *
- * @see {@link ArkosRouteConfig} for configuration options
+ * @see {@link https://www.arkosjs.com/docs/reference/arkos-router} for configuration options
+ * @since 1.4.0-beta
  */
-export default function ArkosRouter(options?: RouterOptions & {
-    prefix?: string | RegExp | Array<string | RegExp>;
-    openapi?: {
-        tags?: string[];
-    };
-}): IArkosRouter;
-export declare function generateOpenAPIFromApp(app: any): Record<string, Record<string, Partial<{
+export default function ArkosRouter(options?: RouterOptions & ArkosRouterOptions): IArkosRouter;
+export declare function generateOpenAPIFromApp(app: Arkos): Record<string, Record<string, Partial<{
     tags?: string[];
     summary?: string;
     description?: string;

package/dist/types/utils/arkos-router/types/index.d.ts

@@ -1,15 +1,31 @@
-import { IRoute, IRouter } from "express";
-import { ZodSchema } from "zod";
-import { Options as RateLimitOptions } from "express-rate-limit";
-import { Options as QueryParserOptions } from "../../../utils/helpers/query-parser.helpers";
-import { DetailedAccessControlRule } from "../../../types/auth";
-import { ArkosErrorRequestHandler, ArkosRequestHandler } from "../../../types";
-import compression from "compression";
-import { OpenApiConfig } from "./openapi-config";
-import { UploadConfig } from "./upload-config";
-import { BodyParserConfig } from "./body-parser-config";
+import { Application, IRoute, IRouter, IRouterHandler, IRouterMatcher, Locals } from 'express';
+import z, { ZodType } from 'zod';
+import { Options as RateLimitOptions } from 'express-rate-limit';
+import { Options as QueryParserOptions } from '../../../utils/helpers/query-parser.helpers';
+import { DetailedAccessControlRule } from '../../../types/auth';
+import { ArkosAnyRequestHandler, ArkosErrorRequestHandler, ArkosRequestHandler } from '../../../types';
+import compression from 'compression';
+import { OpenApiConfig } from './openapi-config';
+import { UploadConfig } from './upload-config';
+import { BodyParserConfig } from './body-parser-config';
+import { ArkosRouterOptions } from '..';
+import { Validator } from '../../../types/validation/validator';
+import { ArkosLoadable } from '../../../exports';
+export type ArkosUseConfig = Pick<ArkosRouteConfig, 'authentication' | 'rateLimit' | 'compression' | 'queryParser' | 'bodyParser' | 'disabled'> & {
+    path?: PathParams;
+};
+export type InferValidationType<T, Fallback> = T extends ZodType ? unknown extends z.infer<T> ? Fallback : z.infer<T> : T extends new (...args: any[]) => infer I ? unknown extends I ? Fallback : I : Fallback;
 export type PathParams = string | RegExp | Array<string | RegExp>;
-export type ArkosAnyRequestHandler = ArkosRequestHandler | ArkosErrorRequestHandler | Array<ArkosRequestHandler | ArkosErrorRequestHandler>;
+export type InternalIArkosRouter = IArkosRouter & {
+    _arkos: {
+        options?: ArkosRouterOptions;
+        routes: Array<{
+            handler: ArkosAnyRequestHandler;
+            config: ArkosRouteConfig;
+            method: string;
+        }>;
+    };
+};
 /**
  * Handler function for HTTP methods that accepts route configuration and request handlers.
  *
@@ -17,9 +33,31 @@ export type ArkosAnyRequestHandler = ArkosRequestHandler | ArkosErrorRequestHand
  * @param {...(ArkosRequestHandler | ArkosErrorRequestHandler)[]} handlers - Request and error handlers for the route.
  * @returns {IRouter} The Express router instance.
  */
-type RouterMethodHandler<T> = (config: ArkosRouteConfig | PathParams, ...handlers: Array<ArkosAnyRequestHandler>) => T;
-export type ArkosRouteMethodHandler<T> = (config: ArkosAnyRequestHandler | Omit<ArkosRouteConfig, "path">, ...handlers: Array<ArkosRequestHandler | ArkosErrorRequestHandler | Array<ArkosRequestHandler | ArkosErrorRequestHandler>>) => T;
-export interface ArkosIRoute extends IRoute {
+type IArkosRouterMethodHandler<T> = IRouterHandler<T> & IRouterMatcher<T> & {
+    <TQuery extends Validator = any, TBody extends Validator = any, TParams extends Validator = any>(config: ArkosRouteConfig<TQuery, TBody, TParams>, ...handlers: Array<ArkosRequestHandler<InferValidationType<TParams, Record<string, string>>, any, InferValidationType<TBody, any>, InferValidationType<TQuery, qs.ParsedQs>, any> | Array<ArkosRequestHandler<InferValidationType<TParams, Record<string, string>>, any, InferValidationType<TBody, any>, InferValidationType<TQuery, qs.ParsedQs>, any>>>): T;
+    <TQuery extends Validator = any, TBody extends Validator = any, TParams extends Validator = any>(config: ArkosRouteConfig<TQuery, TBody, TParams> | PathParams, ...handlers: Array<ArkosAnyRequestHandler<InferValidationType<TParams, Record<string, string>>, any, InferValidationType<TBody, any>, InferValidationType<TQuery, qs.ParsedQs>, any> | Array<ArkosAnyRequestHandler<InferValidationType<TParams, Record<string, string>>, any, InferValidationType<TBody, any>, InferValidationType<TQuery, qs.ParsedQs>, any> | Array<ArkosErrorRequestHandler<InferValidationType<TParams, Record<string, string>>, any, InferValidationType<TBody, any>, InferValidationType<TQuery, qs.ParsedQs>, any>>>>): T;
+    <TQuery extends Validator = any, TBody extends Validator = any, TParams extends Validator = any>(config: ArkosRouteConfig<TQuery, TBody, TParams>, subApplication: Application): T;
+};
+export type ArkosRouteMethodHandler<T> = {
+    <TQuery extends Validator = any, TBody extends Validator = any, TParams extends Validator = any>(config: ArkosAnyRequestHandler | Omit<ArkosRouteConfig, 'path'>, ...handlers: Array<ArkosAnyRequestHandler<InferValidationType<TParams, Record<string, string>>, any, InferValidationType<TBody, any>, InferValidationType<TQuery, qs.ParsedQs>, Locals>>): T;
+    <TQuery extends Validator = any, TBody extends Validator = any, TParams extends Validator = any>(config: Omit<ArkosRouteConfig<TQuery, TBody, TParams>, 'path'>, ...handlers: Array<ArkosAnyRequestHandler<InferValidationType<TParams, Record<string, string>>, any, InferValidationType<TBody, any>, InferValidationType<TQuery, qs.ParsedQs>, Locals> | Array<ArkosRequestHandler<InferValidationType<TParams, Record<string, string>>, any, InferValidationType<TBody, any>, InferValidationType<TQuery, qs.ParsedQs>, Locals>>>): T;
+    <TQuery extends Validator = any, TBody extends Validator = any, TParams extends Validator = any>(config: Omit<ArkosRouteConfig<TQuery, TBody, TParams>, 'path'>, ...handlers: Array<ArkosAnyRequestHandler<InferValidationType<TParams, Record<string, string>>, any, InferValidationType<TBody, any>, InferValidationType<TQuery, qs.ParsedQs>, Locals> | Array<ArkosAnyRequestHandler<InferValidationType<TParams, Record<string, string>>, any, InferValidationType<TBody, any>, InferValidationType<TQuery, qs.ParsedQs>, Locals>>>): T;
+};
+/**
+ * Handler function for `use` that accepts route configuration and middleware handlers.
+ *
+ * @param {ArkosUseConfig} config - The use configuration object or path.
+ * @param {...ArkosAnyRequestHandler} handlers - Middleware handlers.
+ * @returns {T} The router instance.
+ */
+export type UseMethodHandler<T> = IRouterHandler<T> & IRouterMatcher<T> & {
+    (config: ArkosUseConfig, router: IArkosRouter | Application): T;
+    (config: ArkosUseConfig, ...handlers: Array<ArkosRequestHandler | Array<ArkosRequestHandler>>): T;
+    (config: ArkosUseConfig, ...handlers: Array<ArkosErrorRequestHandler | Array<ArkosErrorRequestHandler>>): T;
+    (config: ArkosUseConfig, ...handlers: Array<ArkosRequestHandler | ArkosErrorRequestHandler | Array<ArkosRequestHandler | ArkosErrorRequestHandler>>): T;
+    (...handlers: Array<ArkosRequestHandler | ArkosErrorRequestHandler | Array<ArkosRequestHandler | ArkosErrorRequestHandler>>): T;
+};
+export interface IArkosRoute extends IRoute {
     /** GET method handler with route configuration support */
     get: ArkosRouteMethodHandler<this>;
     /** POST method handler with route configuration support */
@@ -64,29 +102,42 @@ export interface ArkosIRoute extends IRoute {
  */
 export interface IArkosRouter extends IRouter {
     /** GET method handler with route configuration support */
-    get: RouterMethodHandler<this>;
+    get: IArkosRouterMethodHandler<this>;
     /** POST method handler with route configuration support */
-    post: RouterMethodHandler<this>;
+    post: IArkosRouterMethodHandler<this>;
     /** PUT method handler with route configuration support */
-    put: RouterMethodHandler<this>;
+    put: IArkosRouterMethodHandler<this>;
     /** PATCH method handler with route configuration support */
-    patch: RouterMethodHandler<this>;
+    patch: IArkosRouterMethodHandler<this>;
     /** DELETE method handler with route configuration support */
-    delete: RouterMethodHandler<this>;
+    delete: IArkosRouterMethodHandler<this>;
     /** OPTIONS method handler with route configuration support */
-    options: RouterMethodHandler<this>;
+    options: IArkosRouterMethodHandler<this>;
     /** HEAD method handler with route configuration support */
-    head: RouterMethodHandler<this>;
-    trace: RouterMethodHandler<this>;
+    head: IArkosRouterMethodHandler<this>;
+    trace: IArkosRouterMethodHandler<this>;
     /** ALL methods handler with route configuration support */
-    all: RouterMethodHandler<this>;
-    route<T extends string>(prefix: T): ArkosIRoute;
-    route(prefix: PathParams): ArkosIRoute;
+    all: IArkosRouterMethodHandler<this>;
+    use: UseMethodHandler<this>;
+    route<T extends string>(prefix: T): IArkosRoute;
+    route(prefix: PathParams): IArkosRoute;
+    /**
+     * Loads Arkos-specific instances into the app for internal usage.
+     * Unlike use(), load() has no order — it simply makes the loaded
+     * data available for Arkos to apply where needed.
+     */
+    load(...items: ArkosLoadable[]): this;
+    /**
+     * Loads Arkos-specific instances into the app for internal usage.
+     * Unlike use(), load() has no order — it simply makes the loaded
+     * data available for Arkos to apply where needed.
+     */
+    load(items: ArkosLoadable[] | ArkosLoadable): this;
 }
 /**
  * Configuration object for defining routes in Arkos.js.
  */
-export type ArkosRouteConfig = {
+export type ArkosRouteConfig<TQuery extends Validator = any, TBody extends Validator = any, TParams extends Validator = any> = {
     /**
      * Disables the route by not mounting it internally.
      */
@@ -108,20 +159,21 @@ export type ArkosRouteConfig = {
     authentication?: boolean | {
         resource: string;
         action: string;
-        rule?: DetailedAccessControlRule | string[] | "*";
+        rule?: DetailedAccessControlRule | string[] | '*';
     };
     /**
      * Request validation configuration using Zod schemas or class constructors.
      *
      * @remarks
      * - Set to `false` to disable all validation.
+     * - Set to `null` to forbidden all request inputs.
      * - Provide an object with `query`, `body`, and/or `params` properties to validate specific parts of the request.
      * - Each property accepts a Zod schema, a class constructor, or `false` to disable validation for that part.
      */
-    validation?: false | {
-        query?: ZodSchema | (new (...args: any[]) => object) | false;
-        body?: ZodSchema | (new (...args: any[]) => object) | false;
-        params?: ZodSchema | (new (...args: any[]) => object) | false;
+    validation?: false | null | {
+        query?: TQuery;
+        body?: TBody;
+        params?: TParams;
     };
     /**
      * Rate limiting configuration for this route.

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

@@ -1,10 +1,11 @@
 import { OpenAPIV3 } from "openapi-types";
 import { ZodSchema } from "zod";
+import { JsonSchema } from "../../prisma/types";
 /**
  * Represents a schema-like object that can be used for OpenAPI documentation.
  * Accepts Zod schemas, class constructors (DTOs), or plain JSON Schema objects.
  */
-type SchemaLike = ZodSchema | (new (...args: any[]) => object) | OpenAPIV3.SchemaObject;
+type SchemaLike = ZodSchema | (new (...args: any[]) => object) | OpenAPIV3.SchemaObject | JsonSchema;
 /**
  * Extended media type object that accepts SchemaLike in addition to standard OpenAPI schemas.
  */
@@ -131,7 +132,7 @@ type RequestBodyDefinition = SchemaLike | {
  * Defining both validation and openapi schemas for the same field will cause
  * a startup error to prevent documentation drift.
  */
-type ExtendedOperationObject = Omit<OpenAPIV3.OperationObject, "responses" | "requestBody"> & {
+export type ExtendedOperationObject = Omit<OpenAPIV3.OperationObject, "responses" | "requestBody"> & {
     /**
      * Response definitions keyed by HTTP status code.
      * Supports shorthand, medium, and full OpenAPI formats.