convex-cms 0.0.1

package/dist/component/lib/metadataExtractor.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Media Metadata Extractor
+ *
+ * Internal utility functions for extracting and normalizing metadata from uploaded files.
+ * This module provides type-safe metadata extraction based on file MIME types.
+ *
+ * Since Convex functions don't have direct file access (files are in storage),
+ * this extractor works with:
+ * 1. Client-provided metadata (dimensions, duration from browser APIs)
+ * 2. MIME type analysis for capability detection
+ * 3. Filename analysis for additional hints
+ *
+ * The extractor normalizes and validates this information into a structured format
+ * that can be stored in the media asset's metadata field.
+ */
+/**
+ * Base metadata properties common to all media types.
+ */
+export interface BaseMetadata {
+    /** Original filename */
+    filename: string;
+    /** MIME type of the file */
+    mimeType: string;
+    /** File size in bytes */
+    size: number;
+    /** Classified media type */
+    mediaType: "image" | "video" | "audio" | "document" | "other";
+    /** File extension (lowercase, without dot) */
+    extension: string;
+    /** Whether this file type is typically web-compatible */
+    isWebCompatible: boolean;
+}
+/**
+ * Extended metadata for image files.
+ */
+export interface ImageMetadata extends BaseMetadata {
+    mediaType: "image";
+    /** Width in pixels */
+    width?: number;
+    /** Height in pixels */
+    height?: number;
+    /** Aspect ratio (width / height) */
+    aspectRatio?: number;
+    /** Whether the format supports transparency */
+    supportsTransparency: boolean;
+    /** Whether this is a vector format (infinitely scalable) */
+    isVector: boolean;
+    /** Whether this format supports animation */
+    supportsAnimation: boolean;
+    /** Suggested image optimization format */
+    suggestedFormat?: "webp" | "avif" | "jpeg" | "png" | "svg";
+}
+/**
+ * Extended metadata for video files.
+ */
+export interface VideoMetadata extends BaseMetadata {
+    mediaType: "video";
+    /** Width in pixels */
+    width?: number;
+    /** Height in pixels */
+    height?: number;
+    /** Aspect ratio (width / height) */
+    aspectRatio?: number;
+    /** Duration in seconds */
+    duration?: number;
+    /** Duration formatted as HH:MM:SS */
+    durationFormatted?: string;
+    /** Video codec (if known) */
+    codec?: string;
+    /** Whether the format is widely supported in browsers */
+    hasBroadBrowserSupport: boolean;
+}
+/**
+ * Extended metadata for audio files.
+ */
+export interface AudioMetadata extends BaseMetadata {
+    mediaType: "audio";
+    /** Duration in seconds */
+    duration?: number;
+    /** Duration formatted as HH:MM:SS */
+    durationFormatted?: string;
+    /** Audio codec (if known) */
+    codec?: string;
+    /** Whether the format is widely supported in browsers */
+    hasBroadBrowserSupport: boolean;
+}
+/**
+ * Extended metadata for document files.
+ */
+export interface DocumentMetadata extends BaseMetadata {
+    mediaType: "document";
+    /** Page count (if known, typically from PDF) */
+    pageCount?: number;
+    /** Document category */
+    documentCategory: "pdf" | "word" | "spreadsheet" | "presentation" | "text" | "other";
+    /** Whether the document can be previewed in browser */
+    canPreviewInBrowser: boolean;
+}
+/**
+ * Metadata for unrecognized file types.
+ */
+export interface OtherMetadata extends BaseMetadata {
+    mediaType: "other";
+}
+/**
+ * Union type for all possible metadata shapes.
+ */
+export type ExtractedMetadata = ImageMetadata | VideoMetadata | AudioMetadata | DocumentMetadata | OtherMetadata;
+/**
+ * Input parameters for metadata extraction.
+ */
+export interface MetadataExtractionInput {
+    /** Original filename */
+    filename: string;
+    /** MIME type of the file */
+    mimeType: string;
+    /** File size in bytes */
+    size: number;
+    /** Optional width in pixels (for images/videos, from client) */
+    width?: number;
+    /** Optional height in pixels (for images/videos, from client) */
+    height?: number;
+    /** Optional duration in seconds (for audio/video, from client) */
+    duration?: number;
+    /** Optional page count (for documents, from client) */
+    pageCount?: number;
+}
+/**
+ * Extracts the file extension from a filename.
+ *
+ * @param filename - The filename to extract the extension from
+ * @returns The lowercase extension without the dot, or empty string if none
+ */
+export declare function extractExtension(filename: string): string;
+/**
+ * Classifies a MIME type into a media category.
+ *
+ * @param mimeType - The MIME type to classify
+ * @returns The media type category
+ */
+export declare function classifyMimeType(mimeType: string): "image" | "video" | "audio" | "document" | "other";
+/**
+ * Calculates aspect ratio from dimensions.
+ *
+ * @param width - Width in pixels
+ * @param height - Height in pixels
+ * @returns Aspect ratio rounded to 3 decimal places, or undefined if invalid
+ */
+export declare function calculateAspectRatio(width?: number, height?: number): number | undefined;
+/**
+ * Formats duration in seconds to HH:MM:SS format.
+ *
+ * @param seconds - Duration in seconds
+ * @returns Formatted duration string, or undefined if invalid
+ */
+export declare function formatDuration(seconds?: number): string | undefined;
+/**
+ * Determines the optimal image format for web delivery.
+ *
+ * @param mimeType - Original MIME type
+ * @param supportsTransparency - Whether transparency is needed
+ * @returns Suggested format for optimization
+ */
+export declare function suggestImageFormat(mimeType: string, supportsTransparency: boolean): "webp" | "avif" | "jpeg" | "png" | "svg" | undefined;
+/**
+ * Categorizes document MIME types into subcategories.
+ *
+ * @param mimeType - The document MIME type
+ * @returns Document category
+ */
+export declare function categorizeDocument(mimeType: string): "pdf" | "word" | "spreadsheet" | "presentation" | "text" | "other";
+/**
+ * Determines if a document can be previewed in the browser.
+ *
+ * @param mimeType - The document MIME type
+ * @returns Whether the document can be previewed
+ */
+export declare function canPreviewDocument(mimeType: string): boolean;
+/**
+ * Extracts and normalizes metadata from uploaded file information.
+ *
+ * This is the main function to call for metadata extraction. It analyzes
+ * the MIME type, filename, and any provided dimensions/duration to build
+ * a comprehensive metadata object specific to the file type.
+ *
+ * @param input - The file information to extract metadata from
+ * @returns Structured metadata object with type-specific properties
+ *
+ * @example
+ * ```typescript
+ * // Image with dimensions from browser
+ * const imageMetadata = extractMetadata({
+ *   filename: "photo.jpg",
+ *   mimeType: "image/jpeg",
+ *   size: 500000,
+ *   width: 1920,
+ *   height: 1080,
+ * });
+ * // Returns ImageMetadata with aspectRatio, suggestedFormat, etc.
+ *
+ * // Video with duration from browser
+ * const videoMetadata = extractMetadata({
+ *   filename: "clip.mp4",
+ *   mimeType: "video/mp4",
+ *   size: 10000000,
+ *   width: 1920,
+ *   height: 1080,
+ *   duration: 120,
+ * });
+ * // Returns VideoMetadata with durationFormatted, hasBroadBrowserSupport, etc.
+ *
+ * // Document
+ * const docMetadata = extractMetadata({
+ *   filename: "report.pdf",
+ *   mimeType: "application/pdf",
+ *   size: 2000000,
+ *   pageCount: 15,
+ * });
+ * // Returns DocumentMetadata with documentCategory, canPreviewInBrowser, etc.
+ * ```
+ */
+export declare function extractMetadata(input: MetadataExtractionInput): ExtractedMetadata;
+/**
+ * Validates that dimensions are positive integers.
+ *
+ * @param width - Width to validate
+ * @param height - Height to validate
+ * @returns Whether both dimensions are valid
+ */
+export declare function validateDimensions(width?: number, height?: number): boolean;
+/**
+ * Validates that duration is a non-negative number.
+ *
+ * @param duration - Duration to validate
+ * @returns Whether the duration is valid
+ */
+export declare function validateDuration(duration?: number): boolean;
+/**
+ * Validates that file size is a positive integer.
+ *
+ * @param size - File size to validate
+ * @returns Whether the size is valid
+ */
+export declare function validateFileSize(size: number): boolean;
+//# sourceMappingURL=metadataExtractor.d.ts.map

package/dist/component/lib/metadataExtractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadataExtractor.d.ts","sourceRoot":"","sources":["../../../src/component/lib/metadataExtractor.ts"],"names":[],"mappings":"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"}