@kiyasov/platform-hono 1.6.0 → 2.0.0

package/src/drivers/graphQLUpload/index.ts

@@ -1,4 +1,38 @@
+// Core
+export { Upload, FileUpload } from './Upload';
+export { GraphQLUpload } from './GraphQLUpload';
+export { processRequest, ProcessRequestOptions } from './processRequest';
+
+// Streams
 export * from './fs-capacitor';
-export * from './Upload';
-export * from './GraphQLUpload';
-export * from './processRequest';
+
+// Storage - re-export with GQL prefix to avoid conflicts
+export type {
+  StorageFile as GQLStorageFile,
+  StorageOptions as GQLStorageOptions,
+} from './storage';
+export { Storage as GQLStorage } from './storage/storage';
+export {
+  CapacitorStorage as GQLCapacitorStorage,
+  CapacitorStorageFile as GQLCapacitorStorageFile,
+} from './storage/capacitor-storage';
+export {
+  MemoryStorage as GQLMemoryStorage,
+  MemoryStorageFile as GQLMemoryStorageFile,
+} from './storage/memory-storage';
+
+// Utils - prefix to avoid conflicts with multer
+export {
+  formatBytes as gqlFormatBytes,
+  validateFileSize as gqlValidateFileSize,
+  getFileExtension as gqlGetFileExtension,
+  isAllowedFileType as gqlIsAllowedFileType,
+  sanitizeFilename as gqlSanitizeFilename,
+  getUniqueFilename as gqlGetUniqueFilename,
+} from './utils/file';
+
+export {
+  FileTypes as GQLFileTypes,
+  FileValidatorOptions as GQLFileValidatorOptions,
+  validateFile as gqlValidateFile,
+} from './utils/validators';

package/src/drivers/graphQLUpload/processRequest.ts

@@ -1,56 +1,110 @@
 import { Context } from 'hono';
-import { Readable } from 'stream';
 
-import { WriteStream, Upload } from '.';
+import { CapacitorStorage } from './storage/capacitor-storage';
+import { Storage } from './storage/storage';
+import { FileUpload, Upload } from './Upload';
 
+/**
+ * Options for processing GraphQL file uploads
+ */
+export interface ProcessRequestOptions {
+  /** Storage implementation to use for uploaded files */
+  storage?: Storage<FileUpload>;
+  /** Maximum file size in bytes */
+  maxFileSize?: number;
+  /** Temporary directory for capacitor storage */
+  tmpDir?: string;
+}
+
+/**
+ * Sets a value in an object using a dot-notation path
+ * @param obj - Target object
+ * @param path - Dot-notation path (e.g., 'user.profile.avatar')
+ * @param value - Value to set
+ */
+function setByPath(
+  obj: Record<string, unknown>,
+  path: string,
+  value: unknown,
+): void {
+  const segments = path.split('.');
+  let current = obj;
+
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i];
+    if (!current[segment] || typeof current[segment] !== 'object') {
+      current[segment] = {};
+    }
+    current = current[segment] as Record<string, unknown>;
+  }
+
+  current[segments[segments.length - 1]] = value;
+}
+
+/**
+ * Processes a GraphQL multipart request with file uploads
+ * @param ctx - Hono context
+ * @param options - Processing options
+ * @returns Processed operations with Upload promises
+ */
 export async function processRequest(
   ctx: Context,
+  options?: ProcessRequestOptions,
 ): Promise<Record<string, unknown>> {
   const body = await ctx.req.parseBody();
-  const operations = JSON.parse(body.operations as string);
-  const map = new Map(Object.entries(JSON.parse(body.map as string)));
 
-  for (const [fieldName, file] of Object.entries(body)) {
-    if (
-      fieldName === 'operations' ||
-      fieldName === 'map' ||
-      !(file instanceof File)
-    )
-      continue;
+  const operations = JSON.parse(body.operations as string) as Record<
+    string,
+    unknown
+  >;
+  const fileMap = new Map(
+    Object.entries(JSON.parse(body.map as string) as Record<string, string[]>),
+  );
+
+  // Determine storage strategy
+  // Default to CapacitorStorage for GraphQL uploads (supports createReadStream)
+  const storage =
+    options?.storage ??
+    new CapacitorStorage({
+      maxSize: options?.maxFileSize,
+      tmpDir: options?.tmpDir,
+    });
 
-    const fileKeys = map.get(fieldName);
-    if (!Array.isArray(fileKeys) || !fileKeys.length) continue;
+  // Process each file upload
+  for (const [fieldName, value] of Object.entries(body)) {
+    if (fieldName === 'operations' || fieldName === 'map') continue;
+    if (!(value instanceof File)) continue;
 
-    const buffer = Buffer.from(await file.arrayBuffer());
-    const capacitor = new WriteStream();
-    Readable.from(buffer).pipe(capacitor);
+    const fileKeys = fileMap.get(fieldName);
+    if (!fileKeys?.length) continue;
+
+    // Extract the actual field name from the GraphQL path
+    // e.g., "variables.file" -> "file", "variables.files.0" -> "files"
+    const firstPath = fileKeys[0];
+    const pathParts = firstPath.split('.');
+    let actualFieldName = pathParts[pathParts.length - 1];
+
+    // If the last part is a number (array index), get the parent key
+    if (/^\d+$/.test(actualFieldName) && pathParts.length > 1) {
+      actualFieldName = pathParts[pathParts.length - 2];
+    }
 
+    // Create upload promise
     const upload = new Upload();
 
-    upload.file = {
-      filename: file.name,
-      mimetype: file.type,
-      fieldName,
-      encoding: '7bit',
-      createReadStream: (options) => {
-        const stream = capacitor.createReadStream(options);
-        stream.on('close', () => {
-          capacitor.release();
-        });
-        return stream;
-      },
-      capacitor,
-    };
-    upload.resolve(upload.file);
+    // Handle file in background
+    storage
+      .handleFile(value, ctx.req, actualFieldName)
+      .then((file) => {
+        upload.resolve(file);
+      })
+      .catch((error) => {
+        upload.reject(error);
+      });
 
+    // Map upload to all specified paths in operations
     for (const fileKey of fileKeys) {
-      const pathSegments = fileKey.split('.');
-      let current = operations;
-      for (let i = 0; i < pathSegments.length - 1; i++) {
-        if (!current[pathSegments[i]]) current[pathSegments[i]] = {};
-        current = current[pathSegments[i]];
-      }
-      current[pathSegments[pathSegments.length - 1]] = upload;
+      setByPath(operations, fileKey, upload);
     }
   }
 

package/src/drivers/graphQLUpload/storage/capacitor-storage.ts

@@ -0,0 +1,86 @@
+import { HonoRequest } from 'hono';
+import { Readable } from 'stream';
+
+import { ReadStream, ReadStreamOptions, WriteStream } from '../fs-capacitor';
+import { FileUpload } from '../Upload';
+import { Storage, StorageOptions } from './storage';
+
+/**
+ * File upload with stream support for capacitor storage
+ */
+export interface CapacitorStorageFile extends FileUpload {
+  /** Original File object */
+  file: File;
+  /** Creates a readable stream for the file content */
+  createReadStream(options?: ReadStreamOptions): ReadStream;
+  /** The write stream capacitor for this file */
+  capacitor: WriteStream;
+}
+
+/**
+ * Capacitor-based storage that uses temporary files with stream support.
+ * Allows multiple concurrent reads and automatic cleanup.
+ */
+export class CapacitorStorage implements Storage<CapacitorStorageFile> {
+  public readonly options?: StorageOptions;
+
+  constructor(options?: StorageOptions) {
+    this.options = options;
+  }
+
+  public async handleFile(
+    file: File,
+    _req: HonoRequest,
+    fieldName: string,
+  ): Promise<CapacitorStorageFile> {
+    // Check file size limit
+    if (this.options?.maxSize && file.size > this.options.maxSize) {
+      throw new Error(
+        `File "${file.name}" exceeds maximum size of ${this.options.maxSize} bytes`,
+      );
+    }
+
+    // Create capacitor and write file content
+    const capacitor = new WriteStream(
+      this.options?.tmpDir ? { tmpdir: () => this.options.tmpDir! } : undefined,
+    );
+
+    const buffer = Buffer.from(await file.arrayBuffer());
+    Readable.from(buffer).pipe(capacitor);
+
+    // Wait for the stream to finish
+    await new Promise<void>((resolve, reject) => {
+      capacitor.on('finish', resolve);
+      capacitor.on('error', reject);
+    });
+
+    return {
+      fieldName: fieldName,
+      originalFilename: file.name,
+      mimetype: file.type,
+      encoding: '7bit',
+      size: file.size,
+      uploadedAt: new Date().toISOString(),
+      file,
+      createReadStream: (options?: ReadStreamOptions) => {
+        const stream = capacitor.createReadStream(options);
+        stream.on('close', () => {
+          capacitor.release();
+        });
+        stream.on('error', () => {
+          capacitor.release();
+        });
+        return stream;
+      },
+      capacitor,
+    };
+  }
+
+  public async removeFile(
+    file: CapacitorStorageFile,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    force?: boolean,
+  ): Promise<void> {
+    file.capacitor.release();
+  }
+}

package/src/drivers/graphQLUpload/storage/index.ts

@@ -0,0 +1,3 @@
+export * from './storage';
+export * from './capacitor-storage';
+export * from './memory-storage';

package/src/drivers/graphQLUpload/storage/memory-storage.ts

@@ -0,0 +1,62 @@
+import { HonoRequest } from 'hono';
+
+import { FileUpload } from '../Upload';
+import { Storage, StorageOptions } from './storage';
+
+/**
+ * In-memory storage file with buffer
+ */
+export interface MemoryStorageFile extends FileUpload {
+  /** Buffer containing the file data */
+  buffer: Buffer;
+  /** Original File object */
+  file: File;
+}
+
+/**
+ * In-memory storage implementation for file uploads.
+ * Files are stored as buffers in memory. Suitable for small files and testing.
+ */
+export class MemoryStorage implements Storage<MemoryStorageFile> {
+  public readonly options?: StorageOptions;
+
+  constructor(options?: StorageOptions) {
+    this.options = options;
+  }
+
+  public async handleFile(
+    file: File,
+    _req: HonoRequest,
+    fieldName: string,
+  ): Promise<MemoryStorageFile> {
+    // Check file size limit
+    if (this.options?.maxSize && file.size > this.options.maxSize) {
+      throw new Error(
+        `File "${file.name}" exceeds maximum size of ${this.options.maxSize} bytes`,
+      );
+    }
+
+    const buffer = Buffer.from(await file.arrayBuffer());
+
+    return {
+      fieldName: fieldName,
+      originalFilename: file.name,
+      mimetype: file.type,
+      encoding: '7bit',
+      size: buffer.length,
+      uploadedAt: new Date().toISOString(),
+      buffer,
+      file,
+    };
+  }
+
+  public async removeFile(
+    file: MemoryStorageFile,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    force?: boolean,
+  ): Promise<void> {
+    if ('buffer' in file) {
+      delete (file as MemoryStorageFile).buffer;
+    }
+  }
+}

package/src/drivers/graphQLUpload/storage/storage.ts

@@ -0,0 +1,52 @@
+import { HonoRequest } from 'hono';
+
+/**
+ * Represents a file that has been uploaded and stored.
+ * Provides metadata about the file and optionally access to its content.
+ */
+export interface StorageFile {
+  /** Field name in the multipart form */
+  fieldName: string;
+  /** Original filename provided by client */
+  originalFilename: string;
+  /** MIME type of the file */
+  mimetype: string;
+  /** Encoding type (e.g., '7bit', '8bit', 'binary') */
+  encoding: string;
+  /** Size of the file in bytes */
+  size: number;
+  /** Timestamp when file was uploaded (ISO 8601) */
+  uploadedAt?: string;
+}
+
+/**
+ * Storage handler options
+ */
+export interface StorageOptions {
+  /** Maximum file size in bytes */
+  maxSize?: number;
+  /** Temporary directory path (for disk storage) */
+  tmpDir?: string;
+}
+
+/**
+ * Abstract storage interface for handling uploaded files.
+ * Implementations can store files in memory, on disk, or in cloud storage.
+ */
+export interface Storage<TFile extends StorageFile = StorageFile> {
+  /**
+   * Handles an uploaded file, storing it according to the implementation strategy.
+   * @param file - The file to store
+   * @param req - The Hono request object
+   * @param fieldName - The field name from the multipart form
+   * @returns Information about the stored file
+   */
+  handleFile(file: File, req: HonoRequest, fieldName: string): Promise<TFile>;
+
+  /**
+   * Removes a previously stored file.
+   * @param file - The file metadata to remove
+   * @param force - Force removal even if storage options don't specify it
+   */
+  removeFile(file: TFile, force?: boolean): Promise<void>;
+}

package/src/drivers/graphQLUpload/utils/file.ts

@@ -0,0 +1,109 @@
+/**
+ * File utilities for GraphQL upload handling
+ */
+
+/**
+ * Format bytes to human-readable size
+ * @param bytes - Size in bytes
+ * @returns Formatted size string (e.g., "1.5 MB")
+ */
+export function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 Bytes';
+
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
+}
+
+/**
+ * Validate file size against limit
+ * @param file - File to validate
+ * @param maxSize - Maximum size in bytes
+ * @returns true if file size is within limit
+ * @throws Error if file exceeds limit
+ */
+export function validateFileSize(file: File, maxSize: number): void {
+  if (file.size > maxSize) {
+    throw new Error(
+      `File "${file.name}" (${formatBytes(file.size)}) exceeds maximum size of ${formatBytes(maxSize)}`,
+    );
+  }
+}
+
+/**
+ * Get file extension from filename
+ * @param filename - Name of the file
+ * @returns File extension without dot, or empty string
+ */
+export function getFileExtension(filename: string): string {
+  const ext = filename.lastIndexOf('.');
+  return ext === -1 ? '' : filename.slice(ext + 1);
+}
+
+/**
+ * Check if file is of expected type
+ * @param file - File to check
+ * @param allowedTypes - Array of allowed MIME types or extensions
+ * @returns true if file type is allowed
+ */
+export function isAllowedFileType(file: File, allowedTypes: string[]): boolean {
+  return allowedTypes.some((type) => {
+    if (type.startsWith('.')) {
+      // Extension check
+      return getFileExtension(file.name).toLowerCase() === type.slice(1);
+    }
+    // MIME type check (supports wildcards like 'image/*')
+    if (type.endsWith('/*')) {
+      const prefix = type.slice(0, -2);
+      return file.type.startsWith(prefix);
+    }
+    return file.type === type;
+  });
+}
+
+/**
+ * Generate a safe filename from user input
+ * @param filename - Original filename
+ * @returns Safe filename without special characters
+ */
+export function sanitizeFilename(filename: string): string {
+  return filename
+    .replace(/[^a-zA-Z0-9.-]/g, '_')
+    .replace(/_{2,}/g, '_')
+    .replace(/^\.+|\.+$/g, '');
+}
+
+/**
+ * Generate a unique filename if file already exists
+ * @param filename - Original filename
+ * @param existingFilenames - Set of existing filenames
+ * @returns Unique filename
+ */
+export function getUniqueFilename(
+  filename: string,
+  existingFilenames?: Set<string>,
+): string {
+  if (!existingFilenames?.has(filename)) {
+    return filename;
+  }
+
+  const name = filename.lastIndexOf('.');
+  if (name === -1) {
+    return `${filename}_1`;
+  }
+
+  const baseName = filename.slice(0, name);
+  const ext = filename.slice(name);
+
+  let counter = 1;
+  let newFilename = `${baseName}_${counter}${ext}`;
+
+  while (existingFilenames.has(newFilename)) {
+    counter++;
+    newFilename = `${baseName}_${counter}${ext}`;
+  }
+
+  return newFilename;
+}

package/src/drivers/graphQLUpload/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './file';
+export * from './validators';