@contember/bindx-uploader 0.1.0

package/src/types.ts

@@ -0,0 +1,242 @@
+import type { EntityRef, FieldRef, HasManyRef, HasOneRef } from '@contember/bindx'
+
+// ============================================================================
+// Upload Client Types
+// ============================================================================
+
+export interface UploadClient<
+	Options = unknown,
+	Result extends FileUploadResult = FileUploadResult,
+> {
+	upload: (args: UploadClientUploadArgs & Omit<Options, keyof UploadClientUploadArgs>) => Promise<Result>
+}
+
+export interface FileUploadResult {
+	publicUrl: string
+}
+
+export interface FileUploadProgress {
+	progress: number
+	uploadedBytes: number
+	totalBytes: number
+}
+
+export interface UploadClientUploadArgs {
+	file: File
+	signal: AbortSignal
+	onProgress: (progress: FileUploadProgress) => void
+}
+
+// ============================================================================
+// File Types
+// ============================================================================
+
+export interface FileWithMeta {
+	id: string
+	file: File
+	previewUrl: string
+	abortController: AbortController
+}
+
+// ============================================================================
+// Upload State Types
+// ============================================================================
+
+export interface UploaderFileStateInitial {
+	state: 'initial'
+	file: FileWithMeta
+}
+
+export interface UploaderFileStateUploading {
+	state: 'uploading'
+	file: FileWithMeta
+	progress: FileUploadProgress
+}
+
+export interface UploaderFileStateFinalizing {
+	state: 'finalizing'
+	file: FileWithMeta
+	result: FileUploadResult
+}
+
+export interface UploaderFileStateSuccess {
+	state: 'success'
+	file: FileWithMeta
+	result: FileUploadResult
+	dismiss: () => void
+}
+
+export interface UploaderFileStateError {
+	state: 'error'
+	file: FileWithMeta
+	error: unknown
+	dismiss: () => void
+}
+
+export type UploaderFileState =
+	| UploaderFileStateInitial
+	| UploaderFileStateUploading
+	| UploaderFileStateFinalizing
+	| UploaderFileStateSuccess
+	| UploaderFileStateError
+
+export type UploaderState = UploaderFileState[]
+
+// ============================================================================
+// Event Types
+// ============================================================================
+
+export interface BeforeUploadEvent {
+	file: FileWithMeta
+	reject: (reason: string) => never
+}
+
+export interface StartUploadEvent {
+	file: FileWithMeta
+	fileType: FileType
+}
+
+export interface ProgressEvent {
+	file: FileWithMeta
+	progress: FileUploadProgress
+	fileType: FileType
+}
+
+export interface SuccessEvent {
+	file: FileWithMeta
+	result: FileUploadResult
+	fileType: FileType
+}
+
+export interface AfterUploadEvent {
+	file: FileWithMeta
+	result: FileUploadResult
+	fileType: FileType
+}
+
+export interface ErrorEvent {
+	file: FileWithMeta
+	error: unknown
+	fileType?: FileType
+}
+
+export interface UploaderEvents {
+	onBeforeUpload: (event: BeforeUploadEvent) => Promise<FileType | undefined>
+	onStartUpload: (event: StartUploadEvent) => void
+	onProgress: (event: ProgressEvent) => void
+	onAfterUpload: (event: AfterUploadEvent) => Promise<void> | void
+	onSuccess: (event: SuccessEvent) => void
+	onError: (event: ErrorEvent) => void
+}
+
+// ============================================================================
+// Extractor Types
+// ============================================================================
+
+/**
+ * Extract string keys from entity type (field names).
+ */
+export type FieldName<TEntity> = keyof TEntity & string
+
+/**
+ * Result from file data extraction that can populate entity fields
+ */
+export type FileDataExtractorPopulator<TEntity> = (options: {
+	entity: EntityRef<TEntity>
+	result: FileUploadResult
+}) => void
+
+/**
+ * File data extractor interface for bindx.
+ * Provides field names for selection collection and data extraction/population methods.
+ */
+export interface FileDataExtractor<TEntity = Record<string, unknown>> {
+	/**
+	 * Returns the field names this extractor will populate.
+	 * Used by the selection system to know which fields to fetch.
+	 */
+	getFieldNames: () => FieldName<TEntity>[]
+
+	/**
+	 * Extract data from the file (async, e.g., image dimensions)
+	 */
+	extractFileData?: (file: FileWithMeta) => Promise<FileDataExtractorPopulator<TEntity> | undefined> | FileDataExtractorPopulator<TEntity> | undefined
+
+	/**
+	 * Populate entity fields synchronously (e.g., URL field from upload result)
+	 */
+	populateFields?: (options: { entity: EntityRef<TEntity>; result: FileUploadResult }) => void
+}
+
+// ============================================================================
+// File Type Definition
+// ============================================================================
+
+/**
+ * Configuration for a file type that defines how files are handled.
+ */
+export interface FileType<TEntity = Record<string, unknown>> {
+	/**
+	 * Accepted MIME types and extensions.
+	 * @see https://developer.mozilla.org/en-US/docs/Web/API/window/showOpenFilePicker#accept
+	 * undefined means "any mime type"
+	 */
+	accept?: Record<string, string[]> | undefined
+
+	/**
+	 * Custom file validation. Optionally reject with rejection reason.
+	 */
+	acceptFile?: ((file: FileWithMeta) => boolean | Promise<void>) | undefined
+
+	/**
+	 * Data extractors for this file type
+	 */
+	extractors?: FileDataExtractor<TEntity>[]
+
+	/**
+	 * Custom upload client (overrides default)
+	 */
+	uploader?: UploadClient<unknown>
+}
+
+/**
+ * File type with optional base field for discriminated uploads.
+ */
+export interface DiscriminatedFileType<TEntity = Record<string, unknown>> extends FileType<TEntity> {
+	/**
+	 * Base field name for has-one relation (e.g., 'image' for article.image)
+	 */
+	baseField?: string
+}
+
+/**
+ * Map of discriminator values to file types for polymorphic file handling.
+ */
+export type DiscriminatedFileTypeMap<TEntity = Record<string, unknown>> = Record<string, DiscriminatedFileType<TEntity>>
+
+// ============================================================================
+// Options Types
+// ============================================================================
+
+export interface UploaderOptions {
+	accept?: Record<string, string[]>
+	multiple: boolean
+}
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+export type UploaderErrorType =
+	| 'fileRejected'
+	| 'networkError'
+	| 'httpError'
+	| 'aborted'
+	| 'timeout'
+
+export interface UploaderErrorOptions {
+	type: UploaderErrorType
+	endUserMessage?: string
+	developerMessage?: string
+	error?: unknown
+}

package/src/uploadClient/S3UploadClient.ts

@@ -0,0 +1,119 @@
+import type { UploadClient, UploadClientUploadArgs } from '../types.js'
+import type { S3FileParameters, S3SignedUrlResponse, S3UrlSigner } from './types.js'
+import { UploaderError } from '../UploaderError.js'
+
+export interface S3UploadClientOptions {
+	signUrl: S3UrlSigner
+	getUploadOptions?: (file: File) => Partial<S3FileParameters>
+	concurrency?: number
+}
+
+export type S3FileOptions = Partial<S3FileParameters>
+
+export class S3UploadClient implements UploadClient<S3FileOptions> {
+	private activeCount = 0
+	private resolverQueue: Array<() => void> = []
+
+	public constructor(public readonly options: S3UploadClientOptions) {}
+
+	public async upload({
+		file,
+		signal,
+		onProgress,
+		...options
+	}: UploadClientUploadArgs & S3FileOptions): Promise<{ publicUrl: string }> {
+		const parameters: S3FileParameters = {
+			contentType: file.type,
+			...this.options.getUploadOptions?.(file),
+			...options,
+		}
+
+		const signedUrl = await this.options.signUrl({ ...parameters, file })
+		await this.uploadSingleFile(signedUrl, { file, onProgress, signal })
+
+		return {
+			publicUrl: signedUrl.publicUrl,
+		}
+	}
+
+	private async uploadSingleFile(
+		signedUrl: S3SignedUrlResponse,
+		options: UploadClientUploadArgs,
+	): Promise<void> {
+		try {
+			if (this.activeCount >= (this.options.concurrency ?? 5)) {
+				await new Promise<void>(resolve => this.resolverQueue.push(resolve))
+			}
+			this.activeCount++
+
+			await xhrAdapter(signedUrl, options)
+		} finally {
+			this.activeCount--
+			this.resolverQueue.shift()?.()
+		}
+	}
+}
+
+const xhrAdapter = async (
+	signedUrl: S3SignedUrlResponse,
+	{ file, signal, onProgress }: UploadClientUploadArgs,
+): Promise<void> => {
+	return await new Promise<void>((resolve, reject) => {
+		const xhr = new XMLHttpRequest()
+
+		signal.addEventListener('abort', () => {
+			xhr.abort()
+		})
+
+		xhr.open(signedUrl.method, signedUrl.url)
+
+		for (const header of signedUrl.headers) {
+			xhr.setRequestHeader(header.key, header.value)
+		}
+
+		xhr.addEventListener('load', () => {
+			if (xhr.status >= 200 && xhr.status < 300) {
+				resolve()
+			} else {
+				reject(
+					new UploaderError({
+						type: 'httpError',
+						developerMessage: `HTTP error: ${xhr.status}`,
+					}),
+				)
+			}
+		})
+
+		xhr.addEventListener('error', () => {
+			reject(
+				new UploaderError({
+					type: 'networkError',
+				}),
+			)
+		})
+		xhr.addEventListener('abort', () => {
+			reject(
+				new UploaderError({
+					type: 'aborted',
+				}),
+			)
+		})
+		xhr.addEventListener('timeout', () => {
+			reject(
+				new UploaderError({
+					type: 'timeout',
+				}),
+			)
+		})
+
+		xhr.upload?.addEventListener('progress', e => {
+			onProgress({
+				totalBytes: e.total,
+				uploadedBytes: e.loaded,
+				progress: e.loaded / e.total,
+			})
+		})
+
+		xhr.send(file)
+	})
+}

package/src/uploadClient/index.ts

@@ -0,0 +1,2 @@
+export { S3UploadClient, type S3UploadClientOptions, type S3FileOptions } from './S3UploadClient.js'
+export type { S3Acl, S3FileParameters, S3SignedUrlResponse, S3UrlSigner } from './types.js'

package/src/uploadClient/types.ts

@@ -0,0 +1,30 @@
+/**
+ * S3 upload URL signing types.
+ * These types mirror @contember/client's GenerateUploadUrlMutationBuilder types
+ * but are self-contained for bindx-uploader.
+ */
+
+export type S3Acl = 'PUBLIC_READ' | 'PRIVATE' | 'NONE'
+
+export interface S3FileParameters {
+	contentType: string
+	expiration?: number
+	size?: number
+	prefix?: string
+	extension?: string
+	suffix?: string
+	fileName?: string
+	acl?: S3Acl
+}
+
+export interface S3SignedUrlResponse {
+	url: string
+	publicUrl: string
+	method: string
+	headers: Array<{
+		key: string
+		value: string
+	}>
+}
+
+export type S3UrlSigner = (args: S3FileParameters & { file: File }) => Promise<S3SignedUrlResponse>

package/src/utils/attrAccept.ts

@@ -0,0 +1,87 @@
+/**
+ * Check if a file type matches an accept specification.
+ * Ported from react-dropzone's attr-accept utility.
+ *
+ * @param file - File or object with type and name properties
+ * @param accept - Accept specification (MIME type, extension, or wildcard)
+ */
+export function attrAccept(
+	file: { type?: string; name?: string },
+	accept?: string | string[] | Record<string, string[]>,
+): boolean {
+	if (!accept) {
+		return true
+	}
+
+	const acceptArray = normalizeAccept(accept)
+
+	if (acceptArray.length === 0) {
+		return true
+	}
+
+	const mimeType = (file.type || '').toLowerCase()
+	const baseMimeType = mimeType.replace(/\/.*$/, '')
+	const fileName = file.name || ''
+	const dotIndex = fileName.lastIndexOf('.')
+	const extension = dotIndex >= 0 ? fileName.toLowerCase().slice(dotIndex + 1) : ''
+
+	return acceptArray.some(type => {
+		const normalizedType = type.trim().toLowerCase()
+
+		// Extension match (e.g., ".png")
+		if (normalizedType.startsWith('.')) {
+			return extension === normalizedType.slice(1)
+		}
+
+		// Wildcard MIME type (e.g., "image/*")
+		if (normalizedType.endsWith('/*')) {
+			return baseMimeType === normalizedType.replace(/\/\*$/, '')
+		}
+
+		// Exact MIME type match
+		return mimeType === normalizedType
+	})
+}
+
+/**
+ * Normalize accept specification to an array of strings.
+ */
+function normalizeAccept(accept: string | string[] | Record<string, string[]>): string[] {
+	if (typeof accept === 'string') {
+		return accept.split(',').map(s => s.trim())
+	}
+
+	if (Array.isArray(accept)) {
+		return accept
+	}
+
+	// Record<mimeType, extensions[]>
+	const result: string[] = []
+	for (const mimeType in accept) {
+		result.push(mimeType)
+		const extensions = accept[mimeType]
+		if (extensions) {
+			result.push(...extensions)
+		}
+	}
+	return result
+}
+
+/**
+ * Convert accept record to a flat string for input accept attribute.
+ */
+export function acceptToString(accept?: Record<string, string[]>): string | undefined {
+	if (!accept) {
+		return undefined
+	}
+
+	const result: string[] = []
+	for (const mimeType in accept) {
+		result.push(mimeType)
+		const extensions = accept[mimeType]
+		if (extensions) {
+			result.push(...extensions)
+		}
+	}
+	return result.join(',')
+}

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export { createContentApiS3Signer } from './urlSigner.js'
+export { attrAccept, acceptToString } from './attrAccept.js'

package/src/utils/urlSigner.ts

@@ -0,0 +1,117 @@
+import type { GraphQlClient } from '@contember/graphql-client'
+import type { S3FileParameters, S3SignedUrlResponse } from '../uploadClient/types.js'
+
+/**
+ * Creates an S3 URL signer that batches requests to reduce API calls.
+ * Uses microtask scheduling to batch concurrent signing requests into a single GraphQL mutation.
+ */
+export const createContentApiS3Signer = (
+	client: GraphQlClient,
+): ((parameters: S3FileParameters) => Promise<S3SignedUrlResponse>) => {
+	let uploadUrlBatchParameters: S3FileParameters[] = []
+	let uploadUrlBatchResult: null | Promise<Record<string, S3SignedUrlResponse>> = null
+
+	return async (parameters: S3FileParameters): Promise<S3SignedUrlResponse> => {
+		const index = uploadUrlBatchParameters.length
+		uploadUrlBatchParameters.push(parameters)
+
+		if (uploadUrlBatchResult === null) {
+			uploadUrlBatchResult = (async () => {
+				// Wait for microtask to batch concurrent requests
+				await new Promise(resolve => setTimeout(resolve, 0))
+
+				const currentParams = uploadUrlBatchParameters
+				uploadUrlBatchResult = null
+				uploadUrlBatchParameters = []
+
+				const mutation = buildGenerateUploadUrlMutation(
+					Object.fromEntries(currentParams.map((p, i) => [`url_${i}`, p])),
+				)
+
+				return await client.execute<Record<string, S3SignedUrlResponse>>(mutation.query, {
+					variables: mutation.variables,
+				})
+			})()
+		}
+
+		const result = (await uploadUrlBatchResult)[`url_${index}`]
+		if (!result) {
+			throw new Error(`Failed to get signed URL for index ${index}`)
+		}
+		return result
+	}
+}
+
+/**
+ * Builds a GraphQL mutation for generating S3 upload URLs.
+ */
+function buildGenerateUploadUrlMutation(
+	parameters: Record<string, S3FileParameters>,
+): { query: string; variables: Record<string, unknown> } {
+	const fields: string[] = []
+	const variables: Record<string, unknown> = {}
+	const variableDefinitions: string[] = []
+
+	let varIndex = 0
+	for (const alias in parameters) {
+		const params = parameters[alias]
+		if (!params) continue
+
+		const hasNewFormat = params.suffix || params.fileName || params.extension
+
+		if (hasNewFormat) {
+			const inputVarName = `input_${varIndex}`
+			variableDefinitions.push(`$${inputVarName}: S3GenerateSignedUploadInput`)
+			variables[inputVarName] = {
+				contentType: params.contentType,
+				prefix: params.prefix,
+				expiration: params.expiration,
+				acl: params.acl,
+				size: params.size,
+				suffix: params.suffix,
+				fileName: params.fileName,
+				extension: params.extension,
+			}
+			fields.push(`${alias}: generateUploadUrl(input: $${inputVarName}) {
+				url
+				publicUrl
+				method
+				headers { key value }
+			}`)
+		} else {
+			const contentTypeVar = `contentType_${varIndex}`
+			const expirationVar = `expiration_${varIndex}`
+			const prefixVar = `prefix_${varIndex}`
+			const aclVar = `acl_${varIndex}`
+
+			variableDefinitions.push(`$${contentTypeVar}: String`)
+			variableDefinitions.push(`$${expirationVar}: Int`)
+			variableDefinitions.push(`$${prefixVar}: String`)
+			variableDefinitions.push(`$${aclVar}: S3Acl`)
+
+			variables[contentTypeVar] = params.contentType
+			variables[expirationVar] = params.expiration
+			variables[prefixVar] = params.prefix
+			variables[aclVar] = params.acl
+
+			fields.push(`${alias}: generateUploadUrl(
+				contentType: $${contentTypeVar}
+				expiration: $${expirationVar}
+				prefix: $${prefixVar}
+				acl: $${aclVar}
+			) {
+				url
+				publicUrl
+				method
+				headers { key value }
+			}`)
+		}
+		varIndex++
+	}
+
+	const query = `mutation${variableDefinitions.length > 0 ? `(${variableDefinitions.join(', ')})` : ''} {
+		${fields.join('\n')}
+	}`
+
+	return { query, variables }
+}