@kanun-hq/plugin-file 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,164 @@
+import { ValidatorPlugin } from "kanun";
+
+//#region src/types.d.ts
+type MaybePromise<T> = T | Promise<T>;
+interface FileRuleResolverArgs {
+  attribute: string;
+  context: Record<string, any>;
+  data: Record<string, any>;
+  value: unknown;
+}
+interface FileValidatorPluginOptions {
+  resolveFiles?: (args: FileRuleResolverArgs) => MaybePromise<unknown>;
+}
+interface ValidatorWithData<TSelf = any> {
+  getContext: () => Record<string, any>;
+  getData: () => Record<string, any>;
+  setData: (data: Record<string, any>) => TSelf;
+}
+type WildcardRuleInput = string | string[];
+//#endregion
+//#region src/adapters.d.ts
+interface ValidatorWithContext<TSelf = any> {
+  getContext: () => Record<string, any>;
+  withContext: (context: Record<string, any>) => TSelf;
+}
+interface ExpressLikeRequest {
+  file?: unknown;
+  files?: unknown;
+}
+interface FastifyLikeRequest {
+  body?: unknown;
+  file?: unknown;
+  files?: unknown;
+  parts?: (() => AsyncIterable<unknown>) | unknown;
+  raw?: unknown;
+}
+interface HonoLikeContext {
+  req?: {
+    parseBody?: (options?: Record<string, any>) => Promise<Record<string, unknown>>;
+  };
+}
+interface H3LikeEvent {
+  context?: Record<string, any>;
+  req?: {
+    formData?: () => Promise<FormData>;
+  };
+  request?: {
+    formData?: () => Promise<FormData>;
+  };
+}
+/**
+ * Attaches uploaded files from an Express-like request object to the validator
+ * context under `requestFiles`. It supports both `request.file`
+ * and `request.files` properties, normalizing them into a consistent format.
+ * The original request object is also included in the context for plugin use.
+ *
+ * @param validator     The validator instance to attach the files to.
+ * @param request       The Express-like request object containing the uploaded files.
+ * @returns             The validator instance with the updated context.
+ */
+declare function withExpressUploadContext<TValidator extends ValidatorWithContext<TValidator>>(validator: TValidator, request: ExpressLikeRequest): TValidator;
+/**
+ * Attaches uploaded files from an Express-like request object to the validator
+ * context for use within validation rules.
+ *
+ * @param request   The Express-like request object containing the uploaded files.
+ * @returns         A context object containing the uploaded files and the original request.
+ */
+declare function useExpressUploadContext(request: ExpressLikeRequest): Record<string, any>;
+/**
+ * Attaches uploaded files from a Fastify-like request object to the validator context under `requestFiles`.
+ * It supports multiple ways that files may be provided (e.g., `request.files()`,
+ * `request.parts()`, `request.file()`, and nested `request.raw.files`), normalizing
+ * them into a consistent format. The original request object is also included in
+ * the context for plugin use.
+ *
+ * @param validator
+ * @param request
+ * @returns
+ */
+declare function withFastifyUploadContext<TValidator extends ValidatorWithContext<TValidator>>(validator: TValidator, request: FastifyLikeRequest): Promise<TValidator>;
+/**
+ * Attaches uploaded files from a Fastify-like request object to the validator
+ * context for use within validation rules.
+ *
+ * @param request
+ * @returns
+ */
+declare function useFastifyUploadContext(request: FastifyLikeRequest): Promise<Record<string, any>>;
+/**
+ * Attaches uploaded files from a Hono-like context to the validator context under `requestFiles`.
+ *
+ * @param validator
+ * @param context
+ * @returns
+ */
+declare function withHonoUploadContext<TValidator extends ValidatorWithContext<TValidator>>(validator: TValidator, context: HonoLikeContext): Promise<TValidator>;
+/**
+ * Attaches uploaded files from a Hono-like context to the validator context for use within validation rules.
+ *
+ * @param context
+ * @returns
+ */
+declare function useHonoUploadContext(context: HonoLikeContext): Promise<Record<string, any>>;
+/**
+ * Read files from multiple sources on the
+ * event, including `event.context.requestFiles`, `request.formData()`, and multipart
+ * parsing when available. It merges found files into the validator context
+ * under `requestFiles` and also attaches the original event and request for plugin use.
+ *
+ * @param validator     The validator instance to which the files will be added.
+ * @param event         The H3 event containing potential file uploads.
+ * @returns             The validator instance with the merged file context.
+ */
+declare function withH3UploadContext<TValidator extends ValidatorWithContext<TValidator>>(validator: TValidator, event: H3LikeEvent): Promise<TValidator>;
+/**
+ * Uses files from multiple sources on the event, including
+ * `event.context.requestFiles`, `request.formData()`, and multipart parsing when available.
+ *
+ * @param event
+ * @returns
+ */
+declare function useH3UploadContext(event: H3LikeEvent): Promise<Record<string, any>>;
+//#endregion
+//#region src/index.d.ts
+declare module 'kanun' {
+  interface CustomValidationRuleNameMap {
+    dimensions: 'paramable';
+    extensions: 'paramable';
+    file: 'plain';
+    files: 'plain';
+    image: 'plain';
+    mimes: 'paramable';
+    mimetypes: 'paramable';
+  }
+}
+/**
+ * Create the validation rules for a wildcard attribute based on the given item and
+ * collection rules.
+ *
+ * @param attribute             The name of the attribute.
+ * @param itemRules             The rules to apply to each individual file.
+ * @param collectionRules       The rules to apply to the array of files as a whole.
+ * @returns                     An object containing the normalized rules for the attribute.
+ */
+declare function createWildcardFileRules<TAttribute extends string>(attribute: TAttribute, itemRules: WildcardRuleInput, collectionRules?: WildcardRuleInput): Record<TAttribute | `${TAttribute}.*`, string[]>;
+/**
+ * Sync the files from the request context to the validator's data.
+ *
+ * @param validator
+ * @param attributes
+ * @returns
+ */
+declare function syncRequestFilesToData<TValidator extends ValidatorWithData<TValidator>>(validator: TValidator, attributes?: string[]): TValidator;
+/**
+ * Create the file validator plugin with the given options.
+ *
+ * @param options
+ * @returns
+ */
+declare function createFileValidatorPlugin(options?: FileValidatorPluginOptions): ValidatorPlugin;
+declare const fileValidatorPlugin: ValidatorPlugin;
+//#endregion
+export { ExpressLikeRequest, FastifyLikeRequest, H3LikeEvent, HonoLikeContext, ValidatorWithContext, createFileValidatorPlugin, createWildcardFileRules, fileValidatorPlugin, syncRequestFilesToData, useExpressUploadContext, useFastifyUploadContext, useH3UploadContext, useHonoUploadContext, withExpressUploadContext, withFastifyUploadContext, withH3UploadContext, withHonoUploadContext };