kewl

Author: juliusmarminge

packages/uploadthing/src/client-future.ts

@@ -9,16 +9,22 @@ import type { AnyFileRoute } from "./types";
 
 /**
  * Error indicating the XHR request failed
+ * @public
  */
 export class XHRError extends Micro.TaggedError("XHRError")<{
   message: string;
   xhr: unknown;
 }> {}
 
+/**
+ * Error indicating the network request failed
+ * @public
+ */
 export type NetworkError = XHRError | FetchError;
 
 /**
  * Error indicating the upload was rejected during upload to the storage provider
+ * @public
  */
 export class UTStorageError extends Micro.TaggedError("UTStorageError")<{
   message: string;
@@ -27,6 +33,7 @@ export class UTStorageError extends Micro.TaggedError("UTStorageError")<{
 
 /**
  * Error indicating the request to your UploadThing server failed
+ * @public
  */
 export class UTServerError<T> extends Micro.TaggedError("UTServerError")<{
   message: string;
@@ -37,6 +44,10 @@ export class UTServerError<T> extends Micro.TaggedError("UTServerError")<{
   data: T;
 }> {}
 
+/**
+ * Error indicating the upload failed
+ * @public
+ */
 export type UploadThingClientError<TErrorShape> =
   | NetworkError
   | UTStorageError
@@ -45,7 +56,8 @@ export type UploadThingClientError<TErrorShape> =
 /**
  * A file that has not started uploading yet.
  * Can either be pending for the presigned request to resolve,
- * or pending for the browser to upload the file to the storage provider.
+ * or pending for the browser to schedule the network request.
+ * @public
  */
 export interface PendingFile extends File {
   status: "pending";
@@ -62,6 +74,7 @@ export interface PendingFile extends File {
 
 /**
  * A file that is currently uploading.
+ * @public
  */
 export interface UploadingFile extends File {
   status: "uploading";
@@ -78,6 +91,7 @@ export interface UploadingFile extends File {
 
 /**
  * A file that failed to upload.
+ * @public
  */
 export interface FailedFile<TRoute extends AnyFileRoute> extends File {
   status: "failed";
@@ -98,6 +112,7 @@ export interface FailedFile<TRoute extends AnyFileRoute> extends File {
 
 /**
  * A file that has been uploaded successfully.
+ * @public
  */
 export interface UploadedFile<TRoute extends AnyFileRoute> extends File {
   status: "uploaded";
@@ -126,6 +141,10 @@ export interface UploadedFile<TRoute extends AnyFileRoute> extends File {
   hash: string;
 }
 
+/**
+ * A web file with additional state properties
+ * @public
+ */
 export type AnyFile<TFileRoute extends AnyFileRoute> =
   | PendingFile
   | UploadingFile
@@ -134,6 +153,7 @@ export type AnyFile<TFileRoute extends AnyFileRoute> =
 
 /**
  * Predicate function to check if a file is pending
+ * @public
  */
 export function isPendingFile<TRoute extends AnyFileRoute = AnyFileRoute>(
   file: AnyFile<TRoute>,
@@ -143,6 +163,7 @@ export function isPendingFile<TRoute extends AnyFileRoute = AnyFileRoute>(
 
 /**
  * Predicate function to check if a file is uploading
+ * @public
  */
 export function isUploadingFile<TRoute extends AnyFileRoute = AnyFileRoute>(
   file: AnyFile<TRoute>,
@@ -152,6 +173,7 @@ export function isUploadingFile<TRoute extends AnyFileRoute = AnyFileRoute>(
 
 /**
  * Predicate function to check if a file is failed
+ * @public
  */
 export function isFailedFile<TRoute extends AnyFileRoute = AnyFileRoute>(
   file: AnyFile<TRoute>,
@@ -161,6 +183,7 @@ export function isFailedFile<TRoute extends AnyFileRoute = AnyFileRoute>(
 
 /**
  * Predicate function to check if a file is uploaded
+ * @public
  */
 export function isUploadedFile<TRoute extends AnyFileRoute = AnyFileRoute>(
   file: AnyFile<TRoute>,
@@ -170,6 +193,7 @@ export function isUploadedFile<TRoute extends AnyFileRoute = AnyFileRoute>(
 
 /**
  * Modifies a pending file to an uploading file in place
+ * @internal
  */
 function transitionToUploading(
   file: PendingFile,
@@ -183,6 +207,7 @@ function transitionToUploading(
 
 /**
  * Modifies an uploading file to an uploaded file in place
+ * @internal
  */
 function transitionToUploaded<TRoute extends AnyFileRoute>(
   file: UploadingFile,
@@ -198,6 +223,7 @@ function transitionToUploaded<TRoute extends AnyFileRoute>(
 
 /**
  * Modifies a pending or uploading file to a failed file in place
+ * @internal
  */
 function transitionToFailed<TRoute extends AnyFileRoute>(
   file: PendingFile | UploadingFile,
@@ -209,6 +235,10 @@ function transitionToFailed<TRoute extends AnyFileRoute>(
   return failedFile;
 }
 
+/**
+ * Event emitted when the presigned URLs have been retrieved from your server
+ * @public
+ */
 export interface PresignedReceivedEvent<TRoute extends AnyFileRoute> {
   type: "presigned-received";
   /**
@@ -217,6 +247,10 @@ export interface PresignedReceivedEvent<TRoute extends AnyFileRoute> {
   files: AnyFile<TRoute>[];
 }
 
+/**
+ * Event emitted when a file starts uploading
+ * @public
+ */
 export interface UploadStartedEvent<TRoute extends AnyFileRoute> {
   type: "upload-started";
   /**
@@ -229,10 +263,14 @@ export interface UploadStartedEvent<TRoute extends AnyFileRoute> {
   files: AnyFile<TRoute>[];
 }
 
+/**
+ * Event emitted when a file is uploading and received a progress update
+ * @public
+ */
 export interface UploadProgressEvent<TRoute extends AnyFileRoute> {
   type: "upload-progress";
   /**
-   * The file that is currently uploading.
+   * The file that is currently uploading and received a progress update.
    */
   file: UploadingFile;
   /**
@@ -241,6 +279,10 @@ export interface UploadProgressEvent<TRoute extends AnyFileRoute> {
   files: AnyFile<TRoute>[];
 }
 
+/**
+ * Event emitted when a file has finished uploading
+ * @public
+ */
 export interface UploadCompletedEvent<TRoute extends AnyFileRoute> {
   type: "upload-completed";
   /**
@@ -253,6 +295,10 @@ export interface UploadCompletedEvent<TRoute extends AnyFileRoute> {
   files: AnyFile<TRoute>[];
 }
 
+/**
+ * Event emitted when a file failed to upload
+ * @public
+ */
 export interface UploadFailedEvent<TRoute extends AnyFileRoute> {
   type: "upload-failed";
   /**
@@ -265,6 +311,10 @@ export interface UploadFailedEvent<TRoute extends AnyFileRoute> {
   files: AnyFile<TRoute>[];
 }
 
+/**
+ * Event emitted throughout the upload process
+ * @public
+ */
 export type UploadEvent<TRoute extends AnyFileRoute> =
   | PresignedReceivedEvent<TRoute>
   | UploadStartedEvent<TRoute>