@contember/bindx-uploader 0.1.49 → 0.1.50

package/dist/components/MultiUploader.d.ts

@@ -1,8 +1,8 @@
 import { type ReactNode } from 'react';
 import type { HasManyRef } from '@contember/bindx';
 import { BINDX_COMPONENT, type SelectionProvider } from '@contember/bindx-react';
-import type { FileType } from '../types.js';
-export interface MultiUploaderProps<TEntity = Record<string, unknown>> {
+import type { FileType, UploaderEvents } from '../types.js';
+export interface MultiUploaderProps<TEntity = Record<string, unknown>> extends Partial<UploaderEvents> {
     /**
      * The has-many relation to add uploaded files to.
      */
@@ -35,7 +35,7 @@ export interface MultiUploaderProps<TEntity = Record<string, unknown>> {
  * </MultiUploader>
  * ```
  */
-export declare function MultiUploader<TEntity extends Record<string, unknown>>({ field, fileType, children, }: MultiUploaderProps<TEntity>): ReactNode;
+export declare function MultiUploader<TEntity extends Record<string, unknown>>({ field, fileType, children, ...events }: MultiUploaderProps<TEntity>): ReactNode;
 declare const multiUploaderWithSelection: typeof MultiUploader & SelectionProvider & {
     [BINDX_COMPONENT]: true;
 };

package/dist/components/MultiUploader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MultiUploader.d.ts","sourceRoot":"","sources":["../../src/components/MultiUploader.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AACpE,OAAO,KAAK,EAAa,UAAU,EAAqC,MAAM,kBAAkB,CAAA;AAEhG,OAAO,EAAE,eAAe,EAAE,KAAK,iBAAiB,EAAoC,MAAM,wBAAwB,CAAA;AAClH,OAAO,KAAK,EAAE,QAAQ,EAAkB,MAAM,aAAa,CAAA;AAa3D,MAAM,WAAW,kBAAkB,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACpE;;OAEG;IACH,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,CAAA;IAC1B;;;OAGG;IACH,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;IAC3B;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACtE,KAAK,EACL,QAAQ,EACR,QAAQ,GACR,EAAE,kBAAkB,CAAC,OAAO,CAAC,GAAG,SAAS,CAiGzC;AA+BD,QAAA,MAAM,0BAA0B,EAAoB,OAAO,aAAa,GAAG,iBAAiB,GAAG;IAAE,CAAC,eAAe,CAAC,EAAE,IAAI,CAAA;CAAE,CAAA;AA2B1H,OAAO,EAAE,0BAA0B,IAAI,qBAAqB,EAAE,CAAA"}
+{"version":3,"file":"MultiUploader.d.ts","sourceRoot":"","sources":["../../src/components/MultiUploader.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AACpE,OAAO,KAAK,EAAa,UAAU,EAAqC,MAAM,kBAAkB,CAAA;AAEhG,OAAO,EAAE,eAAe,EAAE,KAAK,iBAAiB,EAAoC,MAAM,wBAAwB,CAAA;AAClH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAa3D,MAAM,WAAW,kBAAkB,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,OAAO,CAAC,cAAc,CAAC;IACrG;;OAEG;IACH,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,CAAA;IAC1B;;;OAGG;IACH,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;IAC3B;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACtE,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,GAAG,MAAM,EACT,EAAE,kBAAkB,CAAC,OAAO,CAAC,GAAG,SAAS,CAwFzC;AA+BD,QAAA,MAAM,0BAA0B,EAAoB,OAAO,aAAa,GAAG,iBAAiB,GAAG;IAAE,CAAC,eAAe,CAAC,EAAE,IAAI,CAAA;CAAE,CAAA;AA2B1H,OAAO,EAAE,0BAA0B,IAAI,qBAAqB,EAAE,CAAA"}

package/dist/components/Uploader.d.ts

@@ -1,18 +1,24 @@
 import { type ReactNode } from 'react';
-import type { EntityRef, HasOneRef } from '@contember/bindx';
 import { BINDX_COMPONENT, type SelectionProvider } from '@contember/bindx-react';
-import type { FileType } from '../types.js';
-export interface UploaderProps<TEntity = Record<string, unknown>> {
+import type { FileType, PrepareUploadTarget, UploaderEvents, UploaderFillTarget } from '../types.js';
+export interface UploaderProps<TEntity = Record<string, unknown>> extends Partial<UploaderEvents> {
     /**
      * The entity to fill with uploaded file data.
      * Can be an EntityRef or HasOneRef.
      */
-    entity: EntityRef<TEntity> | HasOneRef<TEntity>;
+    entity: UploaderFillTarget<TEntity>;
     /**
      * File type configuration defining accepted files and extractors.
      * Must be created with the same entity type as the entity prop.
      */
     fileType: FileType<TEntity>;
+    /**
+     * Resolves the target of an upload batch: it runs once, after the files pass the accept
+     * check and before the uploader disconnects or fills anything, and receives the accepted
+     * files. A rejected batch never reaches it. Return another target to fork first
+     * (copy-on-write); returning nothing keeps the entity prop.
+     */
+    prepareTarget?: PrepareUploadTarget<UploaderFillTarget<TEntity>>;
     /**
      * Children to render within the uploader context.
      */
@@ -49,8 +55,23 @@ export interface UploaderProps<TEntity = Record<string, unknown>> {
  *   </UploaderEachFile>
  * </Uploader>
  * ```
+ *
+ * @example Copy-on-write: fork a shared asset so the upload lands on a fresh one
+ * ```tsx
+ * <Uploader
+ *   entity={block.asset.image}
+ *   fileType={imageFileType}
+ *   prepareTarget={() => {
+ *     block.asset.$disconnect()
+ *     block.asset.$create()
+ *     return block.asset.image
+ *   }}
+ * >
+ *   <DropZone />
+ * </Uploader>
+ * ```
  */
-export declare function Uploader<TEntity extends Record<string, unknown>>({ entity, fileType, children, }: UploaderProps<TEntity>): ReactNode;
+export declare function Uploader<TEntity extends Record<string, unknown>>({ entity, fileType, prepareTarget, children, ...events }: UploaderProps<TEntity>): ReactNode;
 declare const uploaderWithSelection: typeof Uploader & SelectionProvider & {
     [BINDX_COMPONENT]: true;
 };

package/dist/components/Uploader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Uploader.d.ts","sourceRoot":"","sources":["../../src/components/Uploader.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAqC,MAAM,kBAAkB,CAAA;AAE/F,OAAO,EAAE,eAAe,EAAE,KAAK,iBAAiB,EAAwB,MAAM,wBAAwB,CAAA;AACtG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAW3C,MAAM,WAAW,aAAa,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC/D;;;OAGG;IACH,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC,CAAA;IAC/C;;;OAGG;IACH,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;IAC3B;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;CACpB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,QAAQ,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACjE,MAAM,EACN,QAAQ,EACR,QAAQ,GACR,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,SAAS,CAgCpC;AAsCD,QAAA,MAAM,qBAAqB,EAAe,OAAO,QAAQ,GAAG,iBAAiB,GAAG;IAAE,CAAC,eAAe,CAAC,EAAE,IAAI,CAAA;CAAE,CAAA;AAiC3G,OAAO,EAAE,qBAAqB,IAAI,gBAAgB,EAAE,CAAA"}
+{"version":3,"file":"Uploader.d.ts","sourceRoot":"","sources":["../../src/components/Uploader.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAG/C,OAAO,EAAE,eAAe,EAAE,KAAK,iBAAiB,EAAwB,MAAM,wBAAwB,CAAA;AACtG,OAAO,KAAK,EAAE,QAAQ,EAAE,mBAAmB,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAWpG,MAAM,WAAW,aAAa,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,OAAO,CAAC,cAAc,CAAC;IAChG;;;OAGG;IACH,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAA;IACnC;;;OAGG;IACH,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;IAC3B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAA;IAChE;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,QAAQ,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACjE,MAAM,EACN,QAAQ,EACR,aAAa,EACb,QAAQ,EACR,GAAG,MAAM,EACT,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,SAAS,CA6BpC;AAsCD,QAAA,MAAM,qBAAqB,EAAe,OAAO,QAAQ,GAAG,iBAAiB,GAAG;IAAE,CAAC,eAAe,CAAC,EAAE,IAAI,CAAA;CAAE,CAAA;AAiC3G,OAAO,EAAE,qBAAqB,IAAI,gBAAgB,EAAE,CAAA"}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { UploadClient, FileUploadResult, FileUploadProgress, UploadClientUploadArgs, FileWithMeta, UploaderFileState, UploaderFileStateInitial, UploaderFileStateUploading, UploaderFileStateFinalizing, UploaderFileStateSuccess, UploaderFileStateError, UploaderState, BeforeUploadEvent, StartUploadEvent, ProgressEvent, SuccessEvent, AfterUploadEvent, ErrorEvent, UploaderEvents, FileDataExtractor, FileDataExtractorPopulator, FileType, DiscriminatedFileType, DiscriminatedFileTypeMap, FieldName, UploaderOptions, UploaderErrorType, UploaderErrorOptions, } from './types.js';
+export type { UploadClient, FileUploadResult, FileUploadProgress, UploadClientUploadArgs, FileWithMeta, UploaderFileState, UploaderFileStateInitial, UploaderFileStateUploading, UploaderFileStateFinalizing, UploaderFileStateSuccess, UploaderFileStateError, UploaderState, BeforeUploadEvent, StartUploadEvent, ProgressEvent, SuccessEvent, AfterUploadEvent, ErrorEvent, UploaderEvents, UploaderFillTarget, PrepareUploadTarget, FileDataExtractor, FileDataExtractorPopulator, FileType, DiscriminatedFileType, DiscriminatedFileTypeMap, FieldName, UploaderOptions, UploaderErrorType, UploaderErrorOptions, } from './types.js';
 export { UploaderError } from './UploaderError.js';
 export { UploaderUploadFilesContext, useUploaderUploadFiles, UploaderStateContext, useUploaderState, UploaderOptionsContext, useUploaderOptions, UploaderFileStateContext, useUploaderFileState, UploaderClientContext, useUploaderClient, UploaderDropzoneStateContext, useUploaderDropzoneState, } from './contexts.js';
 export { S3UploadClient, type S3UploadClientOptions, type S3FileOptions, type S3Acl, type S3FileParameters, type S3SignedUrlResponse, type S3UrlSigner, } from './uploadClient/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAEX,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EAEtB,YAAY,EAEZ,iBAAiB,EACjB,wBAAwB,EACxB,0BAA0B,EAC1B,2BAA2B,EAC3B,wBAAwB,EACxB,sBAAsB,EACtB,aAAa,EAEb,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,cAAc,EAEd,iBAAiB,EACjB,0BAA0B,EAE1B,QAAQ,EACR,qBAAqB,EACrB,wBAAwB,EAExB,SAAS,EAET,eAAe,EAEf,iBAAiB,EACjB,oBAAoB,GACpB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAGlD,OAAO,EACN,0BAA0B,EAC1B,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,4BAA4B,EAC5B,wBAAwB,GACxB,MAAM,eAAe,CAAA;AAGtB,OAAO,EACN,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,KAAK,EACV,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,WAAW,GAChB,MAAM,yBAAyB,CAAA;AAGhC,OAAO,EAAE,wBAAwB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAGvF,OAAO,EACN,uBAAuB,EACvB,KAAK,yBAAyB,EAC9B,+BAA+B,EAC/B,KAAK,iCAAiC,EACtC,yBAAyB,EACzB,KAAK,2BAA2B,EAChC,yBAAyB,EACzB,KAAK,2BAA2B,EAChC,yBAAyB,EACzB,KAAK,2BAA2B,GAChC,MAAM,uBAAuB,CAAA;AAG9B,OAAO,EACN,mBAAmB,EACnB,KAAK,wBAAwB,EAC7B,mBAAmB,EACnB,KAAK,wBAAwB,EAC7B,mBAAmB,EACnB,KAAK,wBAAwB,EAC7B,iBAAiB,EACjB,KAAK,sBAAsB,GAC3B,MAAM,sBAAsB,CAAA;AAG7B,OAAO,EACN,qBAAqB,EACrB,KAAK,WAAW,EAChB,WAAW,GACX,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EACN,QAAQ,EACR,gBAAgB,EAChB,KAAK,aAAa,EAClB,aAAa,EACb,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,eAAe,EACf,KAAK,oBAAoB,EACzB,uBAAuB,EACvB,KAAK,4BAA4B,EACjC,oBAAoB,EACpB,KAAK,yBAAyB,EAC9B,oBAAoB,EACpB,KAAK,yBAAyB,GAC9B,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAEX,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EAEtB,YAAY,EAEZ,iBAAiB,EACjB,wBAAwB,EACxB,0BAA0B,EAC1B,2BAA2B,EAC3B,wBAAwB,EACxB,sBAAsB,EACtB,aAAa,EAEb,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,cAAc,EAEd,kBAAkB,EAClB,mBAAmB,EAEnB,iBAAiB,EACjB,0BAA0B,EAE1B,QAAQ,EACR,qBAAqB,EACrB,wBAAwB,EAExB,SAAS,EAET,eAAe,EAEf,iBAAiB,EACjB,oBAAoB,GACpB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAGlD,OAAO,EACN,0BAA0B,EAC1B,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,4BAA4B,EAC5B,wBAAwB,GACxB,MAAM,eAAe,CAAA;AAGtB,OAAO,EACN,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,KAAK,EACV,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,WAAW,GAChB,MAAM,yBAAyB,CAAA;AAGhC,OAAO,EAAE,wBAAwB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAGvF,OAAO,EACN,uBAAuB,EACvB,KAAK,yBAAyB,EAC9B,+BAA+B,EAC/B,KAAK,iCAAiC,EACtC,yBAAyB,EACzB,KAAK,2BAA2B,EAChC,yBAAyB,EACzB,KAAK,2BAA2B,EAChC,yBAAyB,EACzB,KAAK,2BAA2B,GAChC,MAAM,uBAAuB,CAAA;AAG9B,OAAO,EACN,mBAAmB,EACnB,KAAK,wBAAwB,EAC7B,mBAAmB,EACnB,KAAK,wBAAwB,EAC7B,mBAAmB,EACnB,KAAK,wBAAwB,EAC7B,iBAAiB,EACjB,KAAK,sBAAsB,GAC3B,MAAM,sBAAsB,CAAA;AAG7B,OAAO,EACN,qBAAqB,EACrB,KAAK,WAAW,EAChB,WAAW,GACX,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EACN,QAAQ,EACR,gBAAgB,EAChB,KAAK,aAAa,EAClB,aAAa,EACb,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,eAAe,EACf,KAAK,oBAAoB,EACzB,uBAAuB,EACvB,KAAK,4BAA4B,EACjC,oBAAoB,EACpB,KAAK,yBAAyB,EAC9B,oBAAoB,EACpB,KAAK,yBAAyB,GAC9B,MAAM,uBAAuB,CAAA"}

package/dist/internal/hooks/index.d.ts

@@ -1,5 +1,5 @@
 export { useUploadState, type UseUploadStateResult } from './useUploadState.js';
-export { useUploaderDoUpload } from './useUploaderDoUpload.js';
+export { useUploaderDoUpload, type UseUploaderDoUploadArgs } from './useUploaderDoUpload.js';
 export { useGetPreviewUrls } from './useGetPreviewUrls.js';
-export { useFillEntity, type UseFillEntityArgs } from './useFillEntity.js';
+export { useFillEntity, type UseFillEntityArgs, type UseFillEntityResult } from './useFillEntity.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/internal/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/internal/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/internal/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/E,OAAO,EAAE,mBAAmB,EAAE,KAAK,uBAAuB,EAAE,MAAM,0BAA0B,CAAA;AAC5F,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/internal/hooks/useFillEntity.d.ts

@@ -1,17 +1,26 @@
 import type { EntityRef, HasOneAccessor } from '@contember/bindx';
-import type { FileType, UploaderEvents } from '../../types.js';
-export interface UseFillEntityArgs<TEntity = Record<string, unknown>> extends UploaderEvents {
+import type { FileType, PrepareUploadTarget, UploaderEvents } from '../../types.js';
+type FillTarget<TEntity> = EntityRef<TEntity> | HasOneAccessor<TEntity>;
+export interface UseFillEntityArgs<TEntity = Record<string, unknown>> extends Partial<UploaderEvents> {
     /**
      * The entity to fill. Can be:
      * - EntityRef: fill the entity directly
      * - HasOneAccessor: fill the related entity (disconnect first on upload start)
      */
-    entity: EntityRef<TEntity> | HasOneAccessor<TEntity>;
+    entity: FillTarget<TEntity>;
     fileType: FileType<TEntity>;
+    /**
+     * Resolves the target of a validated batch, before the upload disconnects or fills anything.
+     */
+    prepareTarget?: PrepareUploadTarget<FillTarget<TEntity>>;
+}
+export interface UseFillEntityResult extends Partial<UploaderEvents> {
+    prepareUpload: (files: File[]) => Promise<void>;
 }
 /**
  * Hook that connects upload events to entity field population.
  * Handles both direct EntityRef and HasOneRef (for has-one relations).
  */
-export declare const useFillEntity: <TEntity extends Record<string, unknown>>({ entity, fileType, ...events }: UseFillEntityArgs<TEntity>) => UploaderEvents;
+export declare const useFillEntity: <TEntity extends Record<string, unknown>>({ entity, fileType, prepareTarget, ...events }: UseFillEntityArgs<TEntity>) => UseFillEntityResult;
+export {};
 //# sourceMappingURL=useFillEntity.d.ts.map

package/dist/internal/hooks/useFillEntity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFillEntity.d.ts","sourceRoot":"","sources":["../../../src/internal/hooks/useFillEntity.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAoB,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAIhF,MAAM,WAAW,iBAAiB,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,cAAc;IAC3F;;;;OAIG;IACH,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,CAAA;IACpD,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;CAC3B;AAoBD;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,iCAIpE,iBAAiB,CAAC,OAAO,CAAC,KAAG,cA8C/B,CAAA"}
+{"version":3,"file":"useFillEntity.d.ts","sourceRoot":"","sources":["../../../src/internal/hooks/useFillEntity.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,mBAAmB,EAAoB,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAIrG,KAAK,UAAU,CAAC,OAAO,IAAI,SAAS,CAAC,OAAO,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,CAAA;AAEvE,MAAM,WAAW,iBAAiB,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,OAAO,CAAC,cAAc,CAAC;IACpG;;;;OAIG;IACH,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAA;IAC3B,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;IAC3B;;OAEG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAA;CACxD;AAED,MAAM,WAAW,mBAAoB,SAAQ,OAAO,CAAC,cAAc,CAAC;IACnE,aAAa,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/C;AAoBD;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,gDAKpE,iBAAiB,CAAC,OAAO,CAAC,KAAG,mBA2D/B,CAAA"}

package/dist/internal/hooks/useUploadState.d.ts

@@ -8,5 +8,5 @@ export interface UseUploadStateResult extends UploaderEvents {
  * Hook that manages the upload state machine.
  * Tracks file states through the upload lifecycle: initial -> uploading -> finalizing -> success/error
  */
-export declare const useUploadState: ({ onBeforeUpload, onStartUpload, onSuccess, onError, onProgress, onAfterUpload, }: UploaderEvents) => UseUploadStateResult;
+export declare const useUploadState: ({ onBeforeUpload, onStartUpload, onSuccess, onError, onProgress, onAfterUpload, }: Partial<UploaderEvents>) => UseUploadStateResult;
 //# sourceMappingURL=useUploadState.d.ts.map

package/dist/internal/hooks/useUploadState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useUploadState.d.ts","sourceRoot":"","sources":["../../../src/internal/hooks/useUploadState.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAOX,cAAc,EAEd,aAAa,EACb,MAAM,gBAAgB,CAAA;AAEvB,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC3D,KAAK,EAAE,aAAa,CAAA;IACpB,UAAU,EAAE,MAAM,IAAI,CAAA;IACtB,QAAQ,EAAE,MAAM,IAAI,CAAA;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,mFAO5B,cAAc,KAAG,oBAgInB,CAAA"}
+{"version":3,"file":"useUploadState.d.ts","sourceRoot":"","sources":["../../../src/internal/hooks/useUploadState.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAOX,cAAc,EAEd,aAAa,EACb,MAAM,gBAAgB,CAAA;AAEvB,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC3D,KAAK,EAAE,aAAa,CAAA;IACpB,UAAU,EAAE,MAAM,IAAI,CAAA;IACtB,QAAQ,EAAE,MAAM,IAAI,CAAA;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,mFAO5B,OAAO,CAAC,cAAc,CAAC,KAAG,oBAgI5B,CAAA"}

package/dist/internal/hooks/useUploaderDoUpload.d.ts

@@ -1,7 +1,14 @@
 import type { UploaderEvents } from '../../types.js';
+export interface UseUploaderDoUploadArgs extends Partial<UploaderEvents> {
+    /**
+     * Runs once per batch with the files that passed validation, before any of them is
+     * uploaded or written to the target. Skipped when no file passed.
+     */
+    onPrepareUpload?: (files: File[]) => Promise<void> | void;
+}
 /**
  * Hook that orchestrates the file upload process.
  * Handles file preparation, validation, and upload execution.
  */
-export declare const useUploaderDoUpload: ({ onBeforeUpload, onError, onProgress, onSuccess, onStartUpload, onAfterUpload, }: UploaderEvents) => ((files: File[]) => Promise<void>);
+export declare const useUploaderDoUpload: ({ onBeforeUpload, onError, onProgress, onSuccess, onStartUpload, onAfterUpload, onPrepareUpload, }: UseUploaderDoUploadArgs) => ((files: File[]) => Promise<void>);
 //# sourceMappingURL=useUploaderDoUpload.d.ts.map

package/dist/internal/hooks/useUploaderDoUpload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useUploaderDoUpload.d.ts","sourceRoot":"","sources":["../../../src/internal/hooks/useUploaderDoUpload.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAgB,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAKlE;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,mFAOjC,cAAc,KAAG,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CA+GpD,CAAA"}
+{"version":3,"file":"useUploaderDoUpload.d.ts","sourceRoot":"","sources":["../../../src/internal/hooks/useUploaderDoUpload.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAgB,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAKlE,MAAM,WAAW,uBAAwB,SAAQ,OAAO,CAAC,cAAc,CAAC;IACvE;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CACzD;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,oGAQjC,uBAAuB,KAAG,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CA6H7D,CAAA"}

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { EntityRef } from '@contember/bindx';
+import type { EntityRef, HasOneRef } from '@contember/bindx';
 export interface UploadClient<Options = unknown, Result extends FileUploadResult = FileUploadResult> {
     upload: (args: UploadClientUploadArgs & Omit<Options, keyof UploadClientUploadArgs>) => Promise<Result>;
 }
@@ -77,6 +77,15 @@ export interface ErrorEvent {
     error: unknown;
     fileType?: FileType;
 }
+/**
+ * Fill target of a single-file uploader: an entity, or a has-one relation pointing at one.
+ */
+export type UploaderFillTarget<TEntity = Record<string, unknown>> = EntityRef<TEntity> | HasOneRef<TEntity>;
+/**
+ * Resolves the target of an upload batch after the files pass validation and before
+ * the target is written. Returning nothing keeps the target the uploader was given.
+ */
+export type PrepareUploadTarget<TTarget> = (files: File[]) => TTarget | undefined | Promise<TTarget | undefined>;
 export interface UploaderEvents {
     onBeforeUpload: (event: BeforeUploadEvent) => Promise<FileType | undefined>;
     onStartUpload: (event: StartUploadEvent) => void;

package/dist/types.d.ts.map

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

package/dist/uploadClient/S3UploadClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"S3UploadClient.d.ts","sourceRoot":"","sources":["../../src/uploadClient/S3UploadClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAuB,WAAW,EAAE,MAAM,YAAY,CAAA;AAGpF,MAAM,WAAW,qBAAqB;IACrC,OAAO,EAAE,WAAW,CAAA;IACpB,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;AAErD,qBAAa,cAAe,YAAW,YAAY,CAAC,aAAa,CAAC;aAI9B,OAAO,EAAE,qBAAqB;IAHjE,OAAO,CAAC,WAAW,CAAI;IACvB,OAAO,CAAC,aAAa,CAAwB;gBAEV,OAAO,EAAE,qBAAqB;IAEpD,MAAM,CAAC,EACnB,IAAI,EACJ,MAAM,EACN,UAAU,EACV,GAAG,OAAO,EACV,EAAE,sBAAsB,GAAG,aAAa,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;YAe5D,gBAAgB;CAgB9B"}
+{"version":3,"file":"S3UploadClient.d.ts","sourceRoot":"","sources":["../../src/uploadClient/S3UploadClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAuB,WAAW,EAAE,MAAM,YAAY,CAAA;AAGpF,MAAM,WAAW,qBAAqB;IACrC,OAAO,EAAE,WAAW,CAAA;IACpB,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;AAQrD,qBAAa,cAAe,YAAW,YAAY,CAAC,aAAa,CAAC;aAI9B,OAAO,EAAE,qBAAqB;IAHjE,OAAO,CAAC,WAAW,CAAI;IACvB,OAAO,CAAC,aAAa,CAAwB;gBAEV,OAAO,EAAE,qBAAqB;IAEpD,MAAM,CAAC,EACnB,IAAI,EACJ,MAAM,EACN,UAAU,EACV,GAAG,OAAO,EACV,EAAE,sBAAsB,GAAG,aAAa,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;YAgB5D,gBAAgB;CAgB9B"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@contember/bindx-uploader",
-	"version": "0.1.49",
+	"version": "0.1.50",
 	"description": "File upload components for bindx data binding",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -15,9 +15,9 @@
 		"react": ">=18.0.0"
 	},
 	"dependencies": {
-		"@contember/bindx": "0.1.49",
-		"@contember/bindx-react": "0.1.49",
-		"@contember/bindx-repeater": "0.1.49",
+		"@contember/bindx": "0.1.50",
+		"@contember/bindx-react": "0.1.50",
+		"@contember/bindx-repeater": "0.1.50",
 		"@radix-ui/react-slot": "^1.2.3",
 		"react-dropzone": "^14.3.8"
 	},

package/src/components/MultiUploader.tsx

@@ -15,7 +15,7 @@ import { resolveAcceptingSingleType } from '../internal/utils/resolveAccept.js'
 import { executeExtractors } from '../internal/utils/executeExtractors.js'
 import { uploaderErrorHandler } from '../internal/utils/uploaderErrorHandler.js'
 
-export interface MultiUploaderProps<TEntity = Record<string, unknown>> {
+export interface MultiUploaderProps<TEntity = Record<string, unknown>> extends Partial<UploaderEvents> {
 	/**
 	 * The has-many relation to add uploaded files to.
 	 */
@@ -53,6 +53,7 @@ export function MultiUploader<TEntity extends Record<string, unknown>>({
 	field,
 	fileType,
 	children,
+	...events
 }: MultiUploaderProps<TEntity>): ReactNode {
 	const fieldAccessor = useHasMany(field)
 	// Map file ID -> entity ID
@@ -71,7 +72,7 @@ export function MultiUploader<TEntity extends Record<string, unknown>>({
 
 	// Create entity for file and track mapping
 	const useCreateRepeaterEntityEvents = useCallback(
-		(events: UploaderEvents): UploaderEvents => ({
+		(events: Partial<UploaderEvents>): Partial<UploaderEvents> => ({
 			...events,
 			onBeforeUpload: async event => {
 				if (!(await resolveAcceptingSingleType(event.file, fileType as FileType))) {
@@ -115,19 +116,10 @@ export function MultiUploader<TEntity extends Record<string, unknown>>({
 		[field, fileType, getEntityForFile],
 	)
 
-	const baseEvents: UploaderEvents = useMemo(
-		() => ({
-			onError: uploaderErrorHandler,
-			onStartUpload: () => {},
-			onBeforeUpload: async () => undefined,
-			onProgress: () => {},
-			onAfterUpload: async () => {},
-			onSuccess: () => {},
-		}),
-		[],
-	)
-
-	const fillEntityEvents = useCreateRepeaterEntityEvents(baseEvents)
+	const fillEntityEvents = useCreateRepeaterEntityEvents({
+		...events,
+		onError: events.onError ?? uploaderErrorHandler,
+	})
 	const { files, ...stateEvents } = useUploadState(fillEntityEvents)
 	const onDrop = useUploaderDoUpload(stateEvents)
 

package/src/components/Uploader.tsx

@@ -1,8 +1,8 @@
 import { useMemo, type ReactNode } from 'react'
-import type { EntityRef, HasOneRef, SelectionFieldMeta, SelectionMeta } from '@contember/bindx'
+import type { SelectionFieldMeta, SelectionMeta } from '@contember/bindx'
 import { FIELD_REF_META } from '@contember/bindx'
 import { BINDX_COMPONENT, type SelectionProvider, createEmptySelection } from '@contember/bindx-react'
-import type { FileType } from '../types.js'
+import type { FileType, PrepareUploadTarget, UploaderEvents, UploaderFillTarget } from '../types.js'
 import {
 	UploaderOptionsContext,
 	UploaderStateContext,
@@ -13,25 +13,30 @@ import { useUploaderDoUpload } from '../internal/hooks/useUploaderDoUpload.js'
 import { useFillEntity } from '../internal/hooks/useFillEntity.js'
 import { uploaderErrorHandler } from '../internal/utils/uploaderErrorHandler.js'
 
-export interface UploaderProps<TEntity = Record<string, unknown>> {
+export interface UploaderProps<TEntity = Record<string, unknown>> extends Partial<UploaderEvents> {
 	/**
 	 * The entity to fill with uploaded file data.
 	 * Can be an EntityRef or HasOneRef.
 	 */
-	entity: EntityRef<TEntity> | HasOneRef<TEntity>
+	entity: UploaderFillTarget<TEntity>
 	/**
 	 * File type configuration defining accepted files and extractors.
 	 * Must be created with the same entity type as the entity prop.
 	 */
 	fileType: FileType<TEntity>
+	/**
+	 * Resolves the target of an upload batch: it runs once, after the files pass the accept
+	 * check and before the uploader disconnects or fills anything, and receives the accepted
+	 * files. A rejected batch never reaches it. Return another target to fork first
+	 * (copy-on-write); returning nothing keeps the entity prop.
+	 */
+	prepareTarget?: PrepareUploadTarget<UploaderFillTarget<TEntity>>
 	/**
 	 * Children to render within the uploader context.
 	 */
 	children?: ReactNode
 }
 
-const noop = (): Promise<undefined> => Promise.resolve(undefined)
-
 /**
  * Single file upload component for bindx.
  * Provides upload state and upload function to children via context.
@@ -63,25 +68,39 @@ const noop = (): Promise<undefined> => Promise.resolve(undefined)
  *   </UploaderEachFile>
  * </Uploader>
  * ```
+ *
+ * @example Copy-on-write: fork a shared asset so the upload lands on a fresh one
+ * ```tsx
+ * <Uploader
+ *   entity={block.asset.image}
+ *   fileType={imageFileType}
+ *   prepareTarget={() => {
+ *     block.asset.$disconnect()
+ *     block.asset.$create()
+ *     return block.asset.image
+ *   }}
+ * >
+ *   <DropZone />
+ * </Uploader>
+ * ```
  */
 export function Uploader<TEntity extends Record<string, unknown>>({
 	entity,
 	fileType,
+	prepareTarget,
 	children,
+	...events
 }: UploaderProps<TEntity>): ReactNode {
-	const fillEntityEvents = useFillEntity({
+	const { prepareUpload, ...fillEntityEvents } = useFillEntity({
 		entity,
 		fileType,
-		onError: uploaderErrorHandler,
-		onStartUpload: noop,
-		onBeforeUpload: noop,
-		onProgress: noop,
-		onAfterUpload: noop,
-		onSuccess: noop,
+		prepareTarget,
+		...events,
+		onError: events.onError ?? uploaderErrorHandler,
 	})
 
 	const { files, ...stateEvents } = useUploadState(fillEntityEvents)
-	const onDrop = useUploaderDoUpload(stateEvents)
+	const onDrop = useUploaderDoUpload({ ...stateEvents, onPrepareUpload: prepareUpload })
 
 	const options = useMemo(
 		() => ({

package/src/index.ts

@@ -23,6 +23,9 @@ export type {
 	AfterUploadEvent,
 	ErrorEvent,
 	UploaderEvents,
+	// Upload target
+	UploaderFillTarget,
+	PrepareUploadTarget,
 	// Extractors
 	FileDataExtractor,
 	FileDataExtractorPopulator,

package/src/internal/hooks/index.ts

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

package/src/internal/hooks/useFillEntity.ts

@@ -1,23 +1,33 @@
-import { useCallback } from 'react'
+import { useCallback, useRef } from 'react'
 import type { EntityRef, HasOneAccessor } from '@contember/bindx'
-import type { FileType, StartUploadEvent, UploaderEvents } from '../../types.js'
+import type { FileType, PrepareUploadTarget, 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 {
+type FillTarget<TEntity> = EntityRef<TEntity> | HasOneAccessor<TEntity>
+
+export interface UseFillEntityArgs<TEntity = Record<string, unknown>> extends Partial<UploaderEvents> {
 	/**
 	 * The entity to fill. Can be:
 	 * - EntityRef: fill the entity directly
 	 * - HasOneAccessor: fill the related entity (disconnect first on upload start)
 	 */
-	entity: EntityRef<TEntity> | HasOneAccessor<TEntity>
+	entity: FillTarget<TEntity>
 	fileType: FileType<TEntity>
+	/**
+	 * Resolves the target of a validated batch, before the upload disconnects or fills anything.
+	 */
+	prepareTarget?: PrepareUploadTarget<FillTarget<TEntity>>
+}
+
+export interface UseFillEntityResult extends Partial<UploaderEvents> {
+	prepareUpload: (files: File[]) => Promise<void>
 }
 
 /**
  * Checks if the entity is a HasOneRef (has $disconnect method)
  */
-const isHasOneAccessor = <TEntity>(entity: EntityRef<TEntity> | HasOneAccessor<TEntity>): entity is HasOneAccessor<TEntity> => {
+const isHasOneAccessor = <TEntity>(entity: FillTarget<TEntity>): entity is HasOneAccessor<TEntity> => {
 	return '$disconnect' in entity && typeof entity.$disconnect === 'function'
 }
 
@@ -25,7 +35,7 @@ const isHasOneAccessor = <TEntity>(entity: EntityRef<TEntity> | HasOneAccessor<T
  * Gets the target entity for filling.
  * For HasOneAccessor, returns the related entity. For EntityRef, returns the entity itself.
  */
-const getTargetEntity = <TEntity>(entity: EntityRef<TEntity> | HasOneAccessor<TEntity>): EntityRef<TEntity> => {
+const getTargetEntity = <TEntity>(entity: FillTarget<TEntity>): EntityRef<TEntity> => {
 	if (isHasOneAccessor(entity)) {
 		return entity.$entity
 	}
@@ -39,8 +49,20 @@ const getTargetEntity = <TEntity>(entity: EntityRef<TEntity> | HasOneAccessor<TE
 export const useFillEntity = <TEntity extends Record<string, unknown>>({
 	entity,
 	fileType,
+	prepareTarget,
 	...events
-}: UseFillEntityArgs<TEntity>): UploaderEvents => {
+}: UseFillEntityArgs<TEntity>): UseFillEntityResult => {
+	const preparedTargetRef = useRef<FillTarget<TEntity> | undefined>(undefined)
+
+	const prepareUpload = useCallback(
+		async (files: File[]): Promise<void> => {
+			preparedTargetRef.current = await prepareTarget?.(files)
+		},
+		[prepareTarget],
+	)
+
+	const getTarget = useCallback((): FillTarget<TEntity> => preparedTargetRef.current ?? entity, [entity])
+
 	const handleBeforeUpload = useCallback(
 		async (event: Parameters<UploaderEvents['onBeforeUpload']>[0]): Promise<FileType | undefined> => {
 			if (!(await resolveAcceptingSingleType(event.file, fileType as FileType))) {
@@ -54,19 +76,20 @@ export const useFillEntity = <TEntity extends Record<string, unknown>>({
 	const handleStartUpload = useCallback(
 		(event: StartUploadEvent) => {
 			// Disconnect existing relation before upload
-			if (isHasOneAccessor(entity)) {
-				entity.$disconnect()
+			const target = getTarget()
+			if (isHasOneAccessor(target)) {
+				target.$disconnect()
 			}
 			events.onStartUpload?.(event)
 		},
-		[entity, events],
+		[events, getTarget],
 	)
 
 	const handleAfterUpload = useCallback(
 		async (event: Parameters<UploaderEvents['onAfterUpload']>[0]) => {
 			await Promise.all([
 				(async () => {
-					const targetEntity = getTargetEntity(entity)
+					const targetEntity = getTargetEntity(getTarget())
 					const extractionResult = await executeExtractors({
 						fileType: fileType as FileType,
 						result: event.result,
@@ -77,11 +100,12 @@ export const useFillEntity = <TEntity extends Record<string, unknown>>({
 				events.onAfterUpload?.(event),
 			])
 		},
-		[entity, events, fileType],
+		[events, fileType, getTarget],
 	)
 
 	return {
 		...events,
+		prepareUpload,
 		onBeforeUpload: handleBeforeUpload,
 		onStartUpload: handleStartUpload,
 		onAfterUpload: handleAfterUpload,

package/src/internal/hooks/useUploadState.ts

@@ -28,7 +28,7 @@ export const useUploadState = ({
 	onError,
 	onProgress,
 	onAfterUpload,
-}: UploaderEvents): UseUploadStateResult => {
+}: Partial<UploaderEvents>): UseUploadStateResult => {
 	const [files, setFiles] = useState<Record<string, UploaderFileState>>({})
 
 	const purgeFinal = useCallback(() => {

package/src/internal/hooks/useUploaderDoUpload.ts

@@ -4,6 +4,14 @@ import { UploaderError } from '../../UploaderError.js'
 import { useUploaderClient } from '../../contexts.js'
 import { useGetPreviewUrls } from './useGetPreviewUrls.js'
 
+export interface UseUploaderDoUploadArgs extends Partial<UploaderEvents> {
+	/**
+	 * Runs once per batch with the files that passed validation, before any of them is
+	 * uploaded or written to the target. Skipped when no file passed.
+	 */
+	onPrepareUpload?: (files: File[]) => Promise<void> | void
+}
+
 /**
  * Hook that orchestrates the file upload process.
  * Handles file preparation, validation, and upload execution.
@@ -15,7 +23,8 @@ export const useUploaderDoUpload = ({
 	onSuccess,
 	onStartUpload,
 	onAfterUpload,
-}: UploaderEvents): ((files: File[]) => Promise<void>) => {
+	onPrepareUpload,
+}: UseUploaderDoUploadArgs): ((files: File[]) => Promise<void>) => {
 	const getPreviewUrl = useGetPreviewUrls()
 	const defaultUploader = useUploaderClient()
 
@@ -73,6 +82,19 @@ export const useUploaderDoUpload = ({
 				)
 				.map(p => p.value)
 
+			if (preparedFiles.length === 0) {
+				return
+			}
+
+			try {
+				await onPrepareUpload?.(preparedFiles.map(({ file }) => file.file))
+			} catch (error) {
+				for (const { file } of preparedFiles) {
+					onError?.({ file, error })
+				}
+				return
+			}
+
 			// Upload files
 			await Promise.allSettled(
 				preparedFiles.map(async ({ file, fileType }) => {
@@ -121,6 +143,7 @@ export const useUploaderDoUpload = ({
 			onAfterUpload,
 			onBeforeUpload,
 			onError,
+			onPrepareUpload,
 			onProgress,
 			onStartUpload,
 			onSuccess,

package/src/types.ts

@@ -120,6 +120,17 @@ export interface ErrorEvent {
 	fileType?: FileType
 }
 
+/**
+ * Fill target of a single-file uploader: an entity, or a has-one relation pointing at one.
+ */
+export type UploaderFillTarget<TEntity = Record<string, unknown>> = EntityRef<TEntity> | HasOneRef<TEntity>
+
+/**
+ * Resolves the target of an upload batch after the files pass validation and before
+ * the target is written. Returning nothing keeps the target the uploader was given.
+ */
+export type PrepareUploadTarget<TTarget> = (files: File[]) => TTarget | undefined | Promise<TTarget | undefined>
+
 export interface UploaderEvents {
 	onBeforeUpload: (event: BeforeUploadEvent) => Promise<FileType | undefined>
 	onStartUpload: (event: StartUploadEvent) => void

package/src/uploadClient/S3UploadClient.ts

@@ -10,6 +10,12 @@ export interface S3UploadClientOptions {
 
 export type S3FileOptions = Partial<S3FileParameters>
 
+// generateUploadUrl's `size` is a GraphQLInt (32-bit); larger files omit it rather than fail signing.
+const MAX_GRAPHQL_INT = 2_147_483_647
+
+const getDefaultSize = (file: File): number | undefined =>
+	file.size <= MAX_GRAPHQL_INT ? file.size : undefined
+
 export class S3UploadClient implements UploadClient<S3FileOptions> {
 	private activeCount = 0
 	private resolverQueue: Array<() => void> = []
@@ -24,6 +30,7 @@ export class S3UploadClient implements UploadClient<S3FileOptions> {
 	}: UploadClientUploadArgs & S3FileOptions): Promise<{ publicUrl: string }> {
 		const parameters: S3FileParameters = {
 			contentType: file.type,
+			size: getDefaultSize(file),
 			...this.options.getUploadOptions?.(file),
 			...options,
 		}

package/src/utils/urlSigner.ts

@@ -57,55 +57,24 @@ function buildGenerateUploadUrlMutation(
 		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 }
-			}`)
+		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 }
+		}`)
 		varIndex++
 	}