@contember/bindx-uploader 0.1.0

package/src/index.ts

@@ -0,0 +1,126 @@
+// Types
+export type {
+	// Upload client
+	UploadClient,
+	FileUploadResult,
+	FileUploadProgress,
+	UploadClientUploadArgs,
+	// File
+	FileWithMeta,
+	// State
+	UploaderFileState,
+	UploaderFileStateInitial,
+	UploaderFileStateUploading,
+	UploaderFileStateFinalizing,
+	UploaderFileStateSuccess,
+	UploaderFileStateError,
+	UploaderState,
+	// Events
+	BeforeUploadEvent,
+	StartUploadEvent,
+	ProgressEvent,
+	SuccessEvent,
+	AfterUploadEvent,
+	ErrorEvent,
+	UploaderEvents,
+	// Extractors
+	FileDataExtractor,
+	FileDataExtractorPopulator,
+	// File type
+	FileType,
+	DiscriminatedFileType,
+	DiscriminatedFileTypeMap,
+	// Field name utility type
+	FieldName,
+	// Options
+	UploaderOptions,
+	// Errors
+	UploaderErrorType,
+	UploaderErrorOptions,
+} from './types.js'
+
+// Error class
+export { UploaderError } from './UploaderError.js'
+
+// Contexts
+export {
+	UploaderUploadFilesContext,
+	useUploaderUploadFiles,
+	UploaderStateContext,
+	useUploaderState,
+	UploaderOptionsContext,
+	useUploaderOptions,
+	UploaderFileStateContext,
+	useUploaderFileState,
+	UploaderClientContext,
+	useUploaderClient,
+	UploaderDropzoneStateContext,
+	useUploaderDropzoneState,
+} from './contexts.js'
+
+// Upload client
+export {
+	S3UploadClient,
+	type S3UploadClientOptions,
+	type S3FileOptions,
+	type S3Acl,
+	type S3FileParameters,
+	type S3SignedUrlResponse,
+	type S3UrlSigner,
+} from './uploadClient/index.js'
+
+// Utils
+export { createContentApiS3Signer, attrAccept, acceptToString } from './utils/index.js'
+
+// Extractors
+export {
+	getFileUrlDataExtractor,
+	type FileUrlDataExtractorProps,
+	getGenericFileMetadataExtractor,
+	type GenericFileMetadataExtractorProps,
+	getImageFileDataExtractor,
+	type ImageFileDataExtractorProps,
+	getVideoFileDataExtractor,
+	type VideoFileDataExtractorProps,
+	getAudioFileDataExtractor,
+	type AudioFileDataExtractorProps,
+} from './extractors/index.js'
+
+// File type creators
+export {
+	createImageFileType,
+	type CreateImageFileTypeProps,
+	createVideoFileType,
+	type CreateVideoFileTypeProps,
+	createAudioFileType,
+	type CreateAudioFileTypeProps,
+	createAnyFileType,
+	type CreateAnyFileTypeProps,
+} from './fileTypes/index.js'
+
+// Hooks
+export {
+	useUploaderStateFiles,
+	type StateFilter,
+	useS3Client,
+} from './hooks/index.js'
+
+// Components
+export {
+	Uploader,
+	UploaderWithMeta,
+	type UploaderProps,
+	MultiUploader,
+	MultiUploaderWithMeta,
+	type MultiUploaderProps,
+	UploaderEachFile,
+	type UploaderEachFileProps,
+	UploaderHasFile,
+	type UploaderHasFileProps,
+	UploaderFileStateSwitch,
+	type UploaderFileStateSwitchProps,
+	UploaderDropzoneRoot,
+	type UploaderDropzoneRootProps,
+	UploaderDropzoneArea,
+	type UploaderDropzoneAreaProps,
+} from './components/index.js'

package/src/internal/hooks/index.ts

@@ -0,0 +1,4 @@
+export { useUploadState, type UseUploadStateResult } from './useUploadState.js'
+export { useUploaderDoUpload } from './useUploaderDoUpload.js'
+export { useGetPreviewUrls } from './useGetPreviewUrls.js'
+export { useFillEntity, type UseFillEntityArgs } from './useFillEntity.js'

package/src/internal/hooks/useFillEntity.ts

@@ -0,0 +1,89 @@
+import { useCallback } from 'react'
+import type { EntityRef, HasOneRef } from '@contember/bindx'
+import type { FileType, StartUploadEvent, UploaderEvents } from '../../types.js'
+import { resolveAcceptingSingleType } from '../utils/resolveAccept.js'
+import { executeExtractors } from '../utils/executeExtractors.js'
+
+export interface UseFillEntityArgs<TEntity = Record<string, unknown>> extends UploaderEvents {
+	/**
+	 * The entity to fill. Can be:
+	 * - EntityRef: fill the entity directly
+	 * - HasOneRef: fill the related entity (disconnect first on upload start)
+	 */
+	entity: EntityRef<TEntity> | HasOneRef<TEntity>
+	fileType: FileType<TEntity>
+}
+
+/**
+ * Checks if the entity is a HasOneRef (has $disconnect method)
+ */
+const isHasOneRef = <TEntity>(entity: EntityRef<TEntity> | HasOneRef<TEntity>): entity is HasOneRef<TEntity> => {
+	return '$disconnect' in entity && typeof entity.$disconnect === 'function'
+}
+
+/**
+ * Gets the target entity for filling.
+ * For HasOneRef, returns the related entity. For EntityRef, returns the entity itself.
+ */
+const getTargetEntity = <TEntity>(entity: EntityRef<TEntity> | HasOneRef<TEntity>): EntityRef<TEntity> => {
+	if (isHasOneRef(entity)) {
+		return entity.$entity
+	}
+	return entity
+}
+
+/**
+ * Hook that connects upload events to entity field population.
+ * Handles both direct EntityRef and HasOneRef (for has-one relations).
+ */
+export const useFillEntity = <TEntity extends Record<string, unknown>>({
+	entity,
+	fileType,
+	...events
+}: UseFillEntityArgs<TEntity>): UploaderEvents => {
+	const handleBeforeUpload = useCallback(
+		async (event: Parameters<UploaderEvents['onBeforeUpload']>[0]): Promise<FileType | undefined> => {
+			if (!(await resolveAcceptingSingleType(event.file, fileType as FileType))) {
+				return undefined
+			}
+			return (await events.onBeforeUpload?.(event)) ?? (fileType as FileType)
+		},
+		[events, fileType],
+	)
+
+	const handleStartUpload = useCallback(
+		(event: StartUploadEvent) => {
+			// Disconnect existing relation before upload
+			if (isHasOneRef(entity)) {
+				entity.$disconnect()
+			}
+			events.onStartUpload?.(event)
+		},
+		[entity, events],
+	)
+
+	const handleAfterUpload = useCallback(
+		async (event: Parameters<UploaderEvents['onAfterUpload']>[0]) => {
+			await Promise.all([
+				(async () => {
+					const targetEntity = getTargetEntity(entity)
+					const extractionResult = await executeExtractors({
+						fileType: fileType as FileType,
+						result: event.result,
+						file: event.file,
+					})
+					extractionResult?.({ entity: targetEntity as EntityRef<unknown> })
+				})(),
+				events.onAfterUpload?.(event),
+			])
+		},
+		[entity, events, fileType],
+	)
+
+	return {
+		...events,
+		onBeforeUpload: handleBeforeUpload,
+		onStartUpload: handleStartUpload,
+		onAfterUpload: handleAfterUpload,
+	}
+}

package/src/internal/hooks/useGetPreviewUrls.ts

@@ -0,0 +1,26 @@
+import { useCallback, useEffect, useRef } from 'react'
+
+/**
+ * Hook that manages preview URL creation and cleanup.
+ * Returns a function that creates object URLs for file preview.
+ */
+export const useGetPreviewUrls = (): ((file: File) => string) => {
+	const urlsRef = useRef<Set<string>>(new Set())
+
+	// Cleanup URLs on unmount
+	useEffect(() => {
+		const urls = urlsRef.current
+		return () => {
+			for (const url of urls) {
+				URL.revokeObjectURL(url)
+			}
+			urls.clear()
+		}
+	}, [])
+
+	return useCallback((file: File): string => {
+		const url = URL.createObjectURL(file)
+		urlsRef.current.add(url)
+		return url
+	}, [])
+}

package/src/internal/hooks/useUploadState.ts

@@ -0,0 +1,159 @@
+import { useCallback, useMemo, useState } from 'react'
+import type {
+	AfterUploadEvent,
+	BeforeUploadEvent,
+	ErrorEvent,
+	ProgressEvent,
+	StartUploadEvent,
+	SuccessEvent,
+	UploaderEvents,
+	UploaderFileState,
+	UploaderState,
+} from '../../types.js'
+
+export interface UseUploadStateResult extends UploaderEvents {
+	files: UploaderState
+	purgeFinal: () => void
+	purgeAll: () => void
+}
+
+/**
+ * Hook that manages the upload state machine.
+ * Tracks file states through the upload lifecycle: initial -> uploading -> finalizing -> success/error
+ */
+export const useUploadState = ({
+	onBeforeUpload,
+	onStartUpload,
+	onSuccess,
+	onError,
+	onProgress,
+	onAfterUpload,
+}: UploaderEvents): UseUploadStateResult => {
+	const [files, setFiles] = useState<Record<string, UploaderFileState>>({})
+
+	const purgeFinal = useCallback(() => {
+		setFiles(files => {
+			return Object.fromEntries(
+				Object.entries(files).filter(
+					([, file]) => file.state !== 'success' && file.state !== 'error',
+				),
+			)
+		})
+	}, [])
+
+	const purgeAll = useCallback(() => {
+		setFiles({})
+	}, [])
+
+	const handleBeforeUpload = useCallback(
+		async (event: BeforeUploadEvent) => {
+			setFiles(files => ({
+				...files,
+				[event.file.id]: { state: 'initial', file: event.file },
+			}))
+			return await onBeforeUpload?.(event)
+		},
+		[onBeforeUpload],
+	)
+
+	const handleStartUpload = useCallback(
+		(event: StartUploadEvent) => {
+			setFiles(files => ({
+				...files,
+				[event.file.id]: {
+					state: 'uploading',
+					file: event.file,
+					progress: {
+						progress: 0,
+						uploadedBytes: 0,
+						totalBytes: event.file.file.size,
+					},
+				},
+			}))
+			onStartUpload?.(event)
+		},
+		[onStartUpload],
+	)
+
+	const handleProgress = useCallback(
+		(event: ProgressEvent) => {
+			setFiles(files => ({
+				...files,
+				[event.file.id]: {
+					state: 'uploading',
+					file: event.file,
+					progress: event.progress,
+				},
+			}))
+			onProgress?.(event)
+		},
+		[onProgress],
+	)
+
+	const handleAfterUpload = useCallback(
+		async (event: AfterUploadEvent) => {
+			setFiles(files => ({
+				...files,
+				[event.file.id]: {
+					state: 'finalizing',
+					file: event.file,
+					result: event.result,
+				},
+			}))
+			return await onAfterUpload?.(event)
+		},
+		[onAfterUpload],
+	)
+
+	const handleSuccess = useCallback(
+		(event: SuccessEvent) => {
+			setFiles(files => ({
+				...files,
+				[event.file.id]: {
+					state: 'success',
+					file: event.file,
+					result: event.result,
+					dismiss: () =>
+						setFiles(files => {
+							const { [event.file.id]: _, ...rest } = files
+							return rest
+						}),
+				},
+			}))
+			onSuccess?.(event)
+		},
+		[onSuccess],
+	)
+
+	const handleError = useCallback(
+		(event: ErrorEvent) => {
+			setFiles(files => ({
+				...files,
+				[event.file.id]: {
+					state: 'error',
+					file: event.file,
+					error: event.error,
+					dismiss: () =>
+						setFiles(files => {
+							const { [event.file.id]: _, ...rest } = files
+							return rest
+						}),
+				},
+			}))
+			onError?.(event)
+		},
+		[onError],
+	)
+
+	return {
+		files: useMemo(() => Object.values(files), [files]),
+		purgeFinal,
+		purgeAll,
+		onBeforeUpload: handleBeforeUpload,
+		onStartUpload: handleStartUpload,
+		onProgress: handleProgress,
+		onAfterUpload: handleAfterUpload,
+		onSuccess: handleSuccess,
+		onError: handleError,
+	}
+}

package/src/internal/hooks/useUploaderDoUpload.ts

@@ -0,0 +1,129 @@
+import { useCallback } from 'react'
+import type { FileWithMeta, UploaderEvents } from '../../types.js'
+import { UploaderError } from '../../UploaderError.js'
+import { useUploaderClient } from '../../contexts.js'
+import { useGetPreviewUrls } from './useGetPreviewUrls.js'
+
+/**
+ * Hook that orchestrates the file upload process.
+ * Handles file preparation, validation, and upload execution.
+ */
+export const useUploaderDoUpload = ({
+	onBeforeUpload,
+	onError,
+	onProgress,
+	onSuccess,
+	onStartUpload,
+	onAfterUpload,
+}: UploaderEvents): ((files: File[]) => Promise<void>) => {
+	const getPreviewUrl = useGetPreviewUrls()
+	const defaultUploader = useUploaderClient()
+
+	return useCallback(
+		async (files: File[]) => {
+			// Prepare files with metadata
+			const fileWithMeta = files.map((file): FileWithMeta => {
+				const abortController = new AbortController()
+				const previewUrl = getPreviewUrl(file)
+				abortController.signal.addEventListener('abort', () => {
+					URL.revokeObjectURL(previewUrl)
+				}, { once: true })
+
+				return {
+					id: Math.random().toString(36).substring(7),
+					file,
+					previewUrl,
+					abortController,
+				}
+			})
+
+			// Validate and prepare files
+			const preparePromises = await Promise.allSettled(
+				fileWithMeta.map(async file => {
+					try {
+						const result = await onBeforeUpload?.({
+							file,
+							reject: (reason: string): never => {
+								throw new UploaderError({
+									type: 'fileRejected',
+									endUserMessage: reason,
+								})
+							},
+						})
+						if (!result) {
+							throw new UploaderError({ type: 'fileRejected' })
+						}
+						return {
+							file,
+							fileType: result,
+						}
+					} catch (e) {
+						onError?.({ file, error: e })
+						return Promise.reject(e)
+					}
+				}),
+			)
+
+			// Filter successful preparations
+			const preparedFiles = preparePromises
+				.filter(
+					<T extends PromiseFulfilledResult<unknown>>(
+						p: T | PromiseRejectedResult,
+					): p is T => p.status === 'fulfilled',
+				)
+				.map(p => p.value)
+
+			// Upload files
+			await Promise.allSettled(
+				preparedFiles.map(async ({ file, fileType }) => {
+					try {
+						if (file.abortController.signal.aborted) {
+							return
+						}
+
+						onStartUpload?.({ file, fileType })
+
+						const uploader = fileType.uploader ?? defaultUploader
+						if (!uploader) {
+							throw new Error(
+								'No uploader. Please specify the uploader in FileType or using UploaderClientContext.',
+							)
+						}
+
+						const result = await uploader.upload({
+							file: file.file,
+							signal: file.abortController.signal,
+							onProgress: progress => {
+								onProgress?.({ file, progress, fileType })
+							},
+						})
+
+						if (file.abortController.signal.aborted) {
+							throw new UploaderError({ type: 'aborted' })
+						}
+
+						await onAfterUpload?.({ file, result, fileType })
+
+						if (file.abortController.signal.aborted) {
+							throw new UploaderError({ type: 'aborted' })
+						}
+
+						onSuccess?.({ file, result, fileType })
+					} catch (e) {
+						onError?.({ file, error: e, fileType })
+					}
+				}),
+			)
+		},
+		[
+			defaultUploader,
+			getPreviewUrl,
+			onAfterUpload,
+			onBeforeUpload,
+			onError,
+			onProgress,
+			onStartUpload,
+			onSuccess,
+		],
+	)
+}

package/src/internal/utils/executeExtractors.ts

@@ -0,0 +1,46 @@
+import type { EntityRef } from '@contember/bindx'
+import type { FileType, FileWithMeta, FileUploadResult } from '../../types.js'
+
+interface ExecuteExtractorsArgs {
+	fileType: FileType
+	file: FileWithMeta
+	result: FileUploadResult
+}
+
+/**
+ * Executes all extractors for a file type and returns a populator function
+ * that can be used to fill entity fields.
+ */
+export const executeExtractors = async ({
+	fileType,
+	file,
+	result,
+}: ExecuteExtractorsArgs): Promise<((options: { entity: EntityRef<unknown> }) => void) | undefined> => {
+	const extractorsResult =
+		fileType.extractors?.map(it => {
+			return it.extractFileData?.(file)
+		}) ?? []
+
+	const extractionResult = await Promise.allSettled(extractorsResult)
+
+	if (file.abortController.signal.aborted) {
+		return undefined
+	}
+
+	return ({ entity }) => {
+		// Cast entity to the expected type - extractors use runtime field access via $fields proxy
+		const typedEntity = entity as EntityRef<Record<string, unknown>>
+
+		// First populate fields synchronously
+		fileType.extractors?.forEach(it => {
+			it.populateFields?.({ entity: typedEntity, result })
+		})
+
+		// Then populate from async extractors
+		extractionResult.forEach(it => {
+			if (it.status === 'fulfilled' && it.value) {
+				it.value({ entity: typedEntity, result })
+			}
+		})
+	}
+}

package/src/internal/utils/index.ts

@@ -0,0 +1,3 @@
+export { resolveAcceptingSingleType } from './resolveAccept.js'
+export { executeExtractors } from './executeExtractors.js'
+export { uploaderErrorHandler } from './uploaderErrorHandler.js'

package/src/internal/utils/resolveAccept.ts

@@ -0,0 +1,26 @@
+import type { FileType, FileWithMeta } from '../../types.js'
+import { attrAccept } from '../../utils/attrAccept.js'
+
+/**
+ * Checks if a file is accepted by a single file type.
+ * Returns false if rejected, true if accepted.
+ */
+export const resolveAcceptingSingleType = async (
+	file: FileWithMeta,
+	fileType: FileType,
+): Promise<boolean> => {
+	// Check MIME type
+	if (fileType.accept && !attrAccept(file.file, fileType.accept)) {
+		return false
+	}
+
+	// Run custom validator
+	if (fileType.acceptFile) {
+		const result = await fileType.acceptFile(file)
+		if (result === false) {
+			return false
+		}
+	}
+
+	return true
+}

package/src/internal/utils/uploaderErrorHandler.ts

@@ -0,0 +1,15 @@
+import type { ErrorEvent } from '../../types.js'
+import { UploaderError } from '../../UploaderError.js'
+
+/**
+ * Default error handler that filters out expected errors (fileRejected, aborted)
+ * and logs unexpected errors.
+ */
+export const uploaderErrorHandler = (event: ErrorEvent): void => {
+	if (event.error instanceof UploaderError) {
+		if (event.error.options.type === 'fileRejected' || event.error.options.type === 'aborted') {
+			return
+		}
+	}
+	console.error('Upload error:', event.error)
+}