@visulima/storage-client 1.0.0-alpha.3 → 1.0.0-alpha.4

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## @visulima/storage-client [1.0.0-alpha.4](https://github.com/visulima/visulima/compare/@visulima/storage-client@1.0.0-alpha.3...@visulima/storage-client@1.0.0-alpha.4) (2025-12-27)
+
+### Bug Fixes
+
+* **storage-client:** update @testing-library/svelte to version 5.3.1 and improve README for Svelte support ([43e8ea5](https://github.com/visulima/visulima/commit/43e8ea5b01399d5dd0f98882629bceedd411e710))
+* **storage-client:** update package files ([ba9d079](https://github.com/visulima/visulima/commit/ba9d079a5b25169e88836fd23af13796250452b1))
+
+### Miscellaneous Chores
+
+* **dependencies:** update file-type to version 21.2.0, hono to version 4.11.3, and improve README for storage-client with detailed usage examples ([90bebfa](https://github.com/visulima/visulima/commit/90bebfa9b732afd8d80c133ca0636192b8496801))
+* fixed project.json names and schema path ([964722f](https://github.com/visulima/visulima/commit/964722f691db205c7edb9aa6db29e849a647500b))
+
 ## @visulima/storage-client [1.0.0-alpha.3](https://github.com/visulima/visulima/compare/@visulima/storage-client@1.0.0-alpha.2...@visulima/storage-client@1.0.0-alpha.3) (2025-12-11)
 
 ### Bug Fixes

package/README.md

@@ -6,7 +6,7 @@
 
 </a>
 
-<h3 align="center">The upload client library. Simple and easy file uploads for React | Vue | Solid | .</h3>
+<h3 align="center">The upload client library. Simple and easy file uploads for React | Vue | Solid | Svelte</h3>
 
 <!-- END_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
@@ -48,10 +48,248 @@ yarn add @visulima/storage-client
 pnpm add @visulima/storage-client
 ```
 
+## Description
+
+The Visulima Storage Client is a powerful, framework-agnostic library for handling file uploads in modern web applications. It provides a unified API across React, Vue, Nuxt, Solid, and Svelte with support for multiple upload methods, progress tracking, retry mechanisms, and batch operations.
+
+## Features
+
+- **Framework Support** - First-class support for React, Vue/Nuxt, Solid, and Svelte
+- **Multiple Upload Methods** - Multipart (form-based), TUS (resumable), and chunked REST uploads
+- **Auto-detection** - Automatically selects the best upload method based on file size and available endpoints
+- **Progress Tracking** - Real-time upload progress with percentage and byte-level tracking
+- **Batch Operations** - Upload multiple files simultaneously with batch progress tracking
+- **Retry Mechanism** - Built-in retry with exponential backoff for failed uploads
+- **File Management** - Get, list, delete files with full metadata support
+- **TypeScript Ready** - Full TypeScript support with comprehensive type definitions
+- **TanStack Query Integration** - Built on TanStack Query for powerful caching and state management
+- **Drag & Drop Support** - Built-in file input hooks with drag & drop functionality
+- **Paste Upload** - Support for pasting images from clipboard
+- **Transform Support** - Transform files and metadata on upload
+- **Abort Control** - Cancel uploads at any time with abort functionality
+
+## Prerequisites
+
+The storage client requires TanStack Query (formerly React Query) for state management. You'll need to install the appropriate version for your framework:
+
+- **React**: `@tanstack/react-query` >= 5.90.10
+- **Vue**: `@tanstack/vue-query` >= 5.91.2
+- **Solid**: `@tanstack/solid-query` >= 5.90.13
+- **Svelte**: `@tanstack/svelte-query` >= 6.0.8
+
 ## Usage
 
+### React
+
+```tsx
+import { useUpload } from "@visulima/storage-client/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <UploadComponent />
+    </QueryClientProvider>
+  );
+}
+
+function UploadComponent() {
+  const { upload, progress, isUploading, error, result } = useUpload({
+    endpointMultipart: "/api/upload/multipart",
+    onSuccess: (result) => console.log("Upload successful:", result),
+  });
+
+  const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (file) {
+      await upload(file);
+    }
+  };
+
+  return (
+    <div>
+      <input type="file" onChange={handleFileChange} />
+      {isUploading && <div>Progress: {progress}%</div>}
+      {error && <div>Error: {error.message}</div>}
+      {result && <div>File ID: {result.id}</div>}
+    </div>
+  );
+}
+```
+
+### Vue / Nuxt
+
+```vue
+<template>
+  <div>
+    <input type="file" @change="handleFileChange" />
+    <div v-if="isUploading">Progress: {{ progress }}%</div>
+    <div v-if="error">Error: {{ error.message }}</div>
+    <div v-if="result">File ID: {{ result.id }}</div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { useUpload } from "@visulima/storage-client/vue";
+
+const { upload, progress, isUploading, error, result } = useUpload({
+  endpointMultipart: "/api/upload/multipart",
+});
+
+const handleFileChange = async (e: Event) => {
+  const target = e.target as HTMLInputElement;
+  const file = target.files?.[0];
+  if (file) {
+    await upload(file);
+  }
+};
+</script>
+```
+
+### Solid
+
+```tsx
+import { createUpload } from "@visulima/storage-client/solid";
+import { QueryClient, QueryClientProvider } from "@tanstack/solid-query";
+
+const queryClient = new QueryClient();
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <UploadComponent />
+    </QueryClientProvider>
+  );
+}
+
+function UploadComponent() {
+  const { upload, progress, isUploading, error, result } = createUpload({
+    endpointMultipart: "/api/upload/multipart",
+  });
+
+  const handleFileChange = async (e: Event) => {
+    const target = e.target as HTMLInputElement;
+    const file = target.files?.[0];
+    if (file) {
+      await upload(file);
+    }
+  };
+
+  return (
+    <div>
+      <input type="file" onChange={handleFileChange} />
+      {isUploading() && <div>Progress: {progress()}%</div>}
+      {error() && <div>Error: {error()?.message}</div>}
+      {result() && <div>File ID: {result()?.id}</div>}
+    </div>
+  );
+}
+```
+
+### Svelte
+
+```svelte
+<script lang="ts">
+  import { createUpload } from "@visulima/storage-client/svelte";
+  import { QueryClient, QueryClientProvider } from "@tanstack/svelte-query";
+
+  const queryClient = new QueryClient();
+
+  const { upload, progress, isUploading, error, result } = createUpload({
+    endpointMultipart: "/api/upload/multipart",
+  });
+
+  async function handleFileChange(e: Event) {
+    const target = e.target as HTMLInputElement;
+    const file = target.files?.[0];
+    if (file) {
+      await upload(file);
+    }
+  }
+</script>
+
+<QueryClientProvider client={queryClient}>
+  <div>
+    <input type="file" on:change={handleFileChange} />
+    {#if $isUploading}
+      <div>Progress: {$progress}%</div>
+    {/if}
+    {#if $error}
+      <div>Error: {$error.message}</div>
+    {/if}
+    {#if $result}
+      <div>File ID: {$result.id}</div>
+    {/if}
+  </div>
+</QueryClientProvider>
+```
+
+## Upload Methods
+
+### Multipart Upload
+
+Traditional `multipart/form-data` uploads, perfect for small to medium files and web forms.
+
+```tsx
+import { useMultipartUpload } from "@visulima/storage-client/react";
+
+const { upload, progress, isUploading } = useMultipartUpload({
+  endpoint: "/api/upload/multipart",
+});
+
+await upload(file);
+```
+
+### TUS Upload
+
+Resumable uploads using the TUS protocol, ideal for large files and unreliable networks.
+
+```tsx
+import { useTusUpload } from "@visulima/storage-client/react";
+
+const { upload, pause, resume, progress } = useTusUpload({
+  endpoint: "/api/upload/tus",
+});
+
+await upload(file);
+// Can pause and resume later
+pause();
+resume();
+```
+
+### Chunked REST Upload
+
+Client-side chunked uploads for large files without requiring TUS server support.
+
+```tsx
+import { useChunkedRestUpload } from "@visulima/storage-client/react";
+
+const { upload, progress } = useChunkedRestUpload({
+  endpoint: "/api/upload/chunked-rest",
+  chunkSize: 5 * 1024 * 1024, // 5MB chunks
+});
+
+await upload(file);
+```
+
+## Documentation
+
+For complete documentation and examples, visit:
+
+- [Installation Guide](https://visulima.com/docs/package/storage-client/installation)
+- [React Guide](https://visulima.com/docs/package/storage-client/react)
+- [Vue / Nuxt Guide](https://visulima.com/docs/package/storage-client/vue)
+- [Solid Guide](https://visulima.com/docs/package/storage-client/solid)
+- [Svelte Guide](https://visulima.com/docs/package/storage-client/svelte)
+- [Next.js Guide](https://visulima.com/docs/package/storage-client/nextjs)
+- [TanStack Start Guide](https://visulima.com/docs/package/storage-client/tanstack-start)
+
 ## Related
 
+- [@visulima/storage-server](../storage-server) - Server-side storage implementation
+
 ## Supported Node.js Versions
 
 Libraries in this ecosystem make the best effort to track [Node.js’ release schedule](https://github.com/nodejs/release#release-schedule).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visulima/storage-client",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.4",
   "description": "The upload client library. Simple and easy file uploads for React | Vue | Solid | .",
   "keywords": [
     "visulima",