@plugable-io/react 0.0.2 → 0.0.4

package/README.md

@@ -238,6 +238,37 @@ function ImageGallery() {
 }
 ```
 
+### Ordering Files
+
+```tsx
+function SortedFileList() {
+  const [orderBy, setOrderBy] = useState<'created_at' | 'name' | 'byte_size'>('created_at');
+  const [orderDirection, setOrderDirection] = useState<'asc' | 'desc'>('desc');
+
+  const { files, isLoading } = useFiles({
+    orderBy,
+    orderDirection,
+    perPage: 20,
+  });
+
+  return (
+    <div>
+      <select value={orderBy} onChange={(e) => setOrderBy(e.target.value as any)}>
+        <option value="created_at">Date</option>
+        <option value="name">Name</option>
+        <option value="byte_size">Size</option>
+      </select>
+      <button onClick={() => setOrderDirection(orderDirection === 'asc' ? 'desc' : 'asc')}>
+        {orderDirection === 'asc' ? '↑' : '↓'}
+      </button>
+      {files.map((file) => (
+        <div key={file.id}>{file.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+
 ### Manual Loading
 
 ```tsx
@@ -268,6 +299,8 @@ function LazyFileList() {
 | `perPage` | `number` | `20` | Files per page |
 | `startPage` | `number` | `1` | Initial page number |
 | `autoLoad` | `boolean` | `true` | Fetch on mount |
+| `orderBy` | `'created_at' \| 'name' \| 'byte_size'` | `'created_at'` | Field to order by |
+| `orderDirection` | `'asc' \| 'desc'` | `'desc'` | Sort direction |
 
 ### Return Value
 

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React, { ReactNode, CSSProperties } from 'react';
-import { BucketClient, FileObject } from '@plugable-io/js';
+import { BucketClient, FileObject, ListResponse } from '@plugable-io/js';
 export { FileObject, SearchOptions, UpdateOptions } from '@plugable-io/js';
 
 type AuthProvider = 'clerk' | 'supabase' | 'firebase';
@@ -11,9 +11,15 @@ interface PlugableProviderProps {
     authProvider?: AuthProvider;
     clerkJWTTemplate?: string;
     baseUrl?: string;
+    staleTime?: number;
 }
 type PlugableEventType = 'file.uploaded' | 'file.deleted';
 type EventHandler = (data?: any) => void;
+interface CacheEntry {
+    files: FileObject[];
+    paging: ListResponse['paging'];
+    timestamp: number;
+}
 interface PlugableContextValue {
     client: BucketClient;
     bucketId: string;
@@ -21,8 +27,12 @@ interface PlugableContextValue {
     emit: (event: PlugableEventType, data?: any) => void;
     getToken: () => Promise<string> | string;
     baseUrl?: string;
+    staleTime: number;
+    getCache: (key: string) => CacheEntry | undefined;
+    setCache: (key: string, entry: CacheEntry) => void;
+    invalidateCache: (pattern?: string) => void;
 }
-declare function PlugableProvider({ bucketId, children, getToken, authProvider, clerkJWTTemplate, baseUrl, }: PlugableProviderProps): react_jsx_runtime.JSX.Element;
+declare function PlugableProvider({ bucketId, children, getToken, authProvider, clerkJWTTemplate, baseUrl, staleTime, }: PlugableProviderProps): react_jsx_runtime.JSX.Element;
 declare function usePlugable(): PlugableContextValue;
 
 interface DropzoneProps {
@@ -104,6 +114,9 @@ interface UseFilesOptions {
     perPage?: number;
     mediaType?: string;
     autoLoad?: boolean;
+    orderBy?: 'created_at' | 'name' | 'byte_size';
+    orderDirection?: 'asc' | 'desc';
+    staleTime?: number;
 }
 interface UseFilesResult {
     files: FileObject[];
@@ -118,6 +131,6 @@ interface UseFilesResult {
     setPage: (page: number) => void;
     refresh: () => Promise<void>;
 }
-declare function useFiles({ metadata, startPage, perPage, mediaType, autoLoad, }?: UseFilesOptions): UseFilesResult;
+declare function useFiles({ metadata, startPage, perPage, mediaType, autoLoad, orderBy, orderDirection, staleTime, }?: UseFilesOptions): UseFilesResult;
 
 export { type AuthProvider, Dropzone, type DropzoneProps, type DropzoneRenderProps, FileImage, type FileImageProps, FileList, type FileListProps, type FileListRenderProps, FilePreview, type FilePreviewProps, PlugableProvider, type PlugableProviderProps, type UseFilesOptions, type UseFilesResult, clearImageCache, useFiles, usePlugable };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React, { ReactNode, CSSProperties } from 'react';
-import { BucketClient, FileObject } from '@plugable-io/js';
+import { BucketClient, FileObject, ListResponse } from '@plugable-io/js';
 export { FileObject, SearchOptions, UpdateOptions } from '@plugable-io/js';
 
 type AuthProvider = 'clerk' | 'supabase' | 'firebase';
@@ -11,9 +11,15 @@ interface PlugableProviderProps {
     authProvider?: AuthProvider;
     clerkJWTTemplate?: string;
     baseUrl?: string;
+    staleTime?: number;
 }
 type PlugableEventType = 'file.uploaded' | 'file.deleted';
 type EventHandler = (data?: any) => void;
+interface CacheEntry {
+    files: FileObject[];
+    paging: ListResponse['paging'];
+    timestamp: number;
+}
 interface PlugableContextValue {
     client: BucketClient;
     bucketId: string;
@@ -21,8 +27,12 @@ interface PlugableContextValue {
     emit: (event: PlugableEventType, data?: any) => void;
     getToken: () => Promise<string> | string;
     baseUrl?: string;
+    staleTime: number;
+    getCache: (key: string) => CacheEntry | undefined;
+    setCache: (key: string, entry: CacheEntry) => void;
+    invalidateCache: (pattern?: string) => void;
 }
-declare function PlugableProvider({ bucketId, children, getToken, authProvider, clerkJWTTemplate, baseUrl, }: PlugableProviderProps): react_jsx_runtime.JSX.Element;
+declare function PlugableProvider({ bucketId, children, getToken, authProvider, clerkJWTTemplate, baseUrl, staleTime, }: PlugableProviderProps): react_jsx_runtime.JSX.Element;
 declare function usePlugable(): PlugableContextValue;
 
 interface DropzoneProps {
@@ -104,6 +114,9 @@ interface UseFilesOptions {
     perPage?: number;
     mediaType?: string;
     autoLoad?: boolean;
+    orderBy?: 'created_at' | 'name' | 'byte_size';
+    orderDirection?: 'asc' | 'desc';
+    staleTime?: number;
 }
 interface UseFilesResult {
     files: FileObject[];
@@ -118,6 +131,6 @@ interface UseFilesResult {
     setPage: (page: number) => void;
     refresh: () => Promise<void>;
 }
-declare function useFiles({ metadata, startPage, perPage, mediaType, autoLoad, }?: UseFilesOptions): UseFilesResult;
+declare function useFiles({ metadata, startPage, perPage, mediaType, autoLoad, orderBy, orderDirection, staleTime, }?: UseFilesOptions): UseFilesResult;
 
 export { type AuthProvider, Dropzone, type DropzoneProps, type DropzoneRenderProps, FileImage, type FileImageProps, FileList, type FileListProps, type FileListRenderProps, FilePreview, type FilePreviewProps, PlugableProvider, type PlugableProviderProps, type UseFilesOptions, type UseFilesResult, clearImageCache, useFiles, usePlugable };

package/dist/index.js

@@ -100,9 +100,12 @@ function PlugableProvider({
   getToken,
   authProvider,
   clerkJWTTemplate,
-  baseUrl
+  baseUrl,
+  staleTime = 5 * 60 * 1e3
+  // Default 5 minutes
 }) {
   const listenersRef = (0, import_react.useRef)({});
+  const [cache, setCacheState] = (0, import_react.useState)(/* @__PURE__ */ new Map());
   const client = (0, import_react.useMemo)(() => {
     if (!getToken && !authProvider) {
       throw new Error(
@@ -128,6 +131,34 @@ function PlugableProvider({
   }, []);
   const emit = (0, import_react.useCallback)((event, data) => {
     listenersRef.current[event]?.forEach((handler) => handler(data));
+    if (event === "file.uploaded" || event === "file.deleted") {
+      setCacheState(/* @__PURE__ */ new Map());
+    }
+  }, []);
+  const getCache = (0, import_react.useCallback)((key) => {
+    return cache.get(key);
+  }, [cache]);
+  const setCache = (0, import_react.useCallback)((key, entry) => {
+    setCacheState((prev) => {
+      const next = new Map(prev);
+      next.set(key, entry);
+      return next;
+    });
+  }, []);
+  const invalidateCache = (0, import_react.useCallback)((pattern) => {
+    if (!pattern) {
+      setCacheState(/* @__PURE__ */ new Map());
+      return;
+    }
+    setCacheState((prev) => {
+      const next = new Map(prev);
+      for (const key of prev.keys()) {
+        if (key.includes(pattern)) {
+          next.delete(key);
+        }
+      }
+      return next;
+    });
   }, []);
   const value = (0, import_react.useMemo)(
     () => ({
@@ -136,9 +167,13 @@ function PlugableProvider({
       on,
       emit,
       getToken: client.tokenGetter,
-      baseUrl
+      baseUrl,
+      staleTime,
+      getCache,
+      setCache,
+      invalidateCache
     }),
-    [client, bucketId, on, emit, baseUrl]
+    [client, bucketId, on, emit, baseUrl, staleTime, getCache, setCache, invalidateCache]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(PlugableContext.Provider, { value, children });
 }
@@ -369,16 +404,48 @@ function useFiles({
   startPage = 1,
   perPage = 20,
   mediaType,
-  autoLoad = true
+  autoLoad = true,
+  orderBy,
+  orderDirection,
+  staleTime
 } = {}) {
-  const { client, on } = usePlugable();
+  const { client, on, getCache, setCache, staleTime: providerStaleTime } = usePlugable();
   const [files, setFiles] = (0, import_react3.useState)([]);
   const [isLoading, setIsLoading] = (0, import_react3.useState)(false);
   const [page, setPage] = (0, import_react3.useState)(startPage);
   const [hasNext, setHasNext] = (0, import_react3.useState)(false);
+  const effectiveStaleTime = staleTime ?? providerStaleTime;
   const metadataKey = JSON.stringify(metadata);
   const stableMetadata = (0, import_react3.useMemo)(() => metadata, [metadataKey]);
-  const fetchFiles = (0, import_react3.useCallback)(async (pageNum) => {
+  const paramsKeyWithPage = (0, import_react3.useMemo)(() => JSON.stringify({
+    metadata: stableMetadata,
+    mediaType,
+    perPage,
+    orderBy,
+    orderDirection,
+    page
+  }), [stableMetadata, mediaType, perPage, orderBy, orderDirection, page]);
+  const fetchFiles = (0, import_react3.useCallback)(async (pageNum, skipCache = false) => {
+    if (!skipCache) {
+      const cacheKey = JSON.stringify({
+        metadata: stableMetadata,
+        mediaType,
+        perPage,
+        orderBy,
+        orderDirection,
+        page: pageNum
+      });
+      const cachedEntry = getCache(cacheKey);
+      if (cachedEntry) {
+        const age = Date.now() - cachedEntry.timestamp;
+        const isStale = age > effectiveStaleTime;
+        if (!isStale) {
+          setFiles(cachedEntry.files);
+          setHasNext(cachedEntry.paging.has_next_page);
+          return;
+        }
+      }
+    }
     setIsLoading(true);
     try {
       const options = {
@@ -386,9 +453,24 @@ function useFiles({
         media_type: mediaType,
         page: pageNum,
         per_page: perPage,
-        with_download_url: true
+        with_download_url: true,
+        ...orderBy && { order_by: orderBy },
+        ...orderDirection && { order_direction: orderDirection }
       };
       const response = await client.list(options);
+      const cacheKey = JSON.stringify({
+        metadata: stableMetadata,
+        mediaType,
+        perPage,
+        orderBy,
+        orderDirection,
+        page: pageNum
+      });
+      setCache(cacheKey, {
+        files: response.files,
+        paging: response.paging,
+        timestamp: Date.now()
+      });
       setFiles(response.files);
       setHasNext(response.paging.has_next_page);
     } catch (err) {
@@ -398,15 +480,24 @@ function useFiles({
     } finally {
       setIsLoading(false);
     }
-  }, [client, stableMetadata, mediaType, perPage]);
+  }, [client, stableMetadata, mediaType, perPage, orderBy, orderDirection, getCache, setCache, effectiveStaleTime]);
   (0, import_react3.useEffect)(() => {
-    if (autoLoad) {
-      fetchFiles(page);
+    const cachedEntry = getCache(paramsKeyWithPage);
+    if (cachedEntry) {
+      const age = Date.now() - cachedEntry.timestamp;
+      const isStale = age > effectiveStaleTime;
+      setFiles(cachedEntry.files);
+      setHasNext(cachedEntry.paging.has_next_page);
+      if (isStale && autoLoad) {
+        fetchFiles(page, true);
+      }
+    } else if (autoLoad) {
+      fetchFiles(page, true);
     }
-  }, [fetchFiles, page, autoLoad]);
+  }, [paramsKeyWithPage, autoLoad, getCache, effectiveStaleTime, fetchFiles, page]);
   (0, import_react3.useEffect)(() => {
     const unsubscribe = on("file.uploaded", () => {
-      fetchFiles(page);
+      fetchFiles(page, true);
     });
     return unsubscribe;
   }, [on, fetchFiles, page]);
@@ -419,7 +510,7 @@ function useFiles({
     setPage((p) => Math.max(1, p - 1));
   }, []);
   const refresh = (0, import_react3.useCallback)(async () => {
-    await fetchFiles(page);
+    await fetchFiles(page, true);
   }, [fetchFiles, page]);
   return {
     files,

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/PlugableProvider.tsx
-import { createContext, useContext, useMemo, useCallback, useRef } from "react";
+import { createContext, useContext, useMemo, useCallback, useRef, useState } from "react";
 import { BucketClient } from "@plugable-io/js";
 import { jsx } from "react/jsx-runtime";
 var PlugableContext = createContext(null);
@@ -57,9 +57,12 @@ function PlugableProvider({
   getToken,
   authProvider,
   clerkJWTTemplate,
-  baseUrl
+  baseUrl,
+  staleTime = 5 * 60 * 1e3
+  // Default 5 minutes
 }) {
   const listenersRef = useRef({});
+  const [cache, setCacheState] = useState(/* @__PURE__ */ new Map());
   const client = useMemo(() => {
     if (!getToken && !authProvider) {
       throw new Error(
@@ -85,6 +88,34 @@ function PlugableProvider({
   }, []);
   const emit = useCallback((event, data) => {
     listenersRef.current[event]?.forEach((handler) => handler(data));
+    if (event === "file.uploaded" || event === "file.deleted") {
+      setCacheState(/* @__PURE__ */ new Map());
+    }
+  }, []);
+  const getCache = useCallback((key) => {
+    return cache.get(key);
+  }, [cache]);
+  const setCache = useCallback((key, entry) => {
+    setCacheState((prev) => {
+      const next = new Map(prev);
+      next.set(key, entry);
+      return next;
+    });
+  }, []);
+  const invalidateCache = useCallback((pattern) => {
+    if (!pattern) {
+      setCacheState(/* @__PURE__ */ new Map());
+      return;
+    }
+    setCacheState((prev) => {
+      const next = new Map(prev);
+      for (const key of prev.keys()) {
+        if (key.includes(pattern)) {
+          next.delete(key);
+        }
+      }
+      return next;
+    });
   }, []);
   const value = useMemo(
     () => ({
@@ -93,9 +124,13 @@ function PlugableProvider({
       on,
       emit,
       getToken: client.tokenGetter,
-      baseUrl
+      baseUrl,
+      staleTime,
+      getCache,
+      setCache,
+      invalidateCache
     }),
-    [client, bucketId, on, emit, baseUrl]
+    [client, bucketId, on, emit, baseUrl, staleTime, getCache, setCache, invalidateCache]
   );
   return /* @__PURE__ */ jsx(PlugableContext.Provider, { value, children });
 }
@@ -108,7 +143,7 @@ function usePlugable() {
 }
 
 // src/components/Dropzone.tsx
-import React, { useCallback as useCallback2, useState } from "react";
+import React, { useCallback as useCallback2, useState as useState2 } from "react";
 import { BucketClient as BucketClient2 } from "@plugable-io/js";
 import { jsx as jsx2, jsxs } from "react/jsx-runtime";
 function Dropzone({
@@ -134,10 +169,10 @@ function Dropzone({
     }
     return defaultClient;
   }, [_bucketId, defaultClient, getToken, baseUrl]);
-  const [isDragActive, setIsDragActive] = useState(false);
-  const [isUploading, setIsUploading] = useState(false);
-  const [uploadProgress, setUploadProgress] = useState({});
-  const [uploadedFiles, setUploadedFiles] = useState([]);
+  const [isDragActive, setIsDragActive] = useState2(false);
+  const [isUploading, setIsUploading] = useState2(false);
+  const [uploadProgress, setUploadProgress] = useState2({});
+  const [uploadedFiles, setUploadedFiles] = useState2([]);
   const fileInputRef = React.useRef(null);
   const uploadFiles = useCallback2(
     async (files) => {
@@ -320,22 +355,54 @@ function Dropzone({
 }
 
 // src/hooks/useFiles.ts
-import { useState as useState2, useCallback as useCallback3, useEffect, useMemo as useMemo2 } from "react";
+import { useState as useState3, useCallback as useCallback3, useEffect, useMemo as useMemo2 } from "react";
 function useFiles({
   metadata,
   startPage = 1,
   perPage = 20,
   mediaType,
-  autoLoad = true
+  autoLoad = true,
+  orderBy,
+  orderDirection,
+  staleTime
 } = {}) {
-  const { client, on } = usePlugable();
-  const [files, setFiles] = useState2([]);
-  const [isLoading, setIsLoading] = useState2(false);
-  const [page, setPage] = useState2(startPage);
-  const [hasNext, setHasNext] = useState2(false);
+  const { client, on, getCache, setCache, staleTime: providerStaleTime } = usePlugable();
+  const [files, setFiles] = useState3([]);
+  const [isLoading, setIsLoading] = useState3(false);
+  const [page, setPage] = useState3(startPage);
+  const [hasNext, setHasNext] = useState3(false);
+  const effectiveStaleTime = staleTime ?? providerStaleTime;
   const metadataKey = JSON.stringify(metadata);
   const stableMetadata = useMemo2(() => metadata, [metadataKey]);
-  const fetchFiles = useCallback3(async (pageNum) => {
+  const paramsKeyWithPage = useMemo2(() => JSON.stringify({
+    metadata: stableMetadata,
+    mediaType,
+    perPage,
+    orderBy,
+    orderDirection,
+    page
+  }), [stableMetadata, mediaType, perPage, orderBy, orderDirection, page]);
+  const fetchFiles = useCallback3(async (pageNum, skipCache = false) => {
+    if (!skipCache) {
+      const cacheKey = JSON.stringify({
+        metadata: stableMetadata,
+        mediaType,
+        perPage,
+        orderBy,
+        orderDirection,
+        page: pageNum
+      });
+      const cachedEntry = getCache(cacheKey);
+      if (cachedEntry) {
+        const age = Date.now() - cachedEntry.timestamp;
+        const isStale = age > effectiveStaleTime;
+        if (!isStale) {
+          setFiles(cachedEntry.files);
+          setHasNext(cachedEntry.paging.has_next_page);
+          return;
+        }
+      }
+    }
     setIsLoading(true);
     try {
       const options = {
@@ -343,9 +410,24 @@ function useFiles({
         media_type: mediaType,
         page: pageNum,
         per_page: perPage,
-        with_download_url: true
+        with_download_url: true,
+        ...orderBy && { order_by: orderBy },
+        ...orderDirection && { order_direction: orderDirection }
       };
       const response = await client.list(options);
+      const cacheKey = JSON.stringify({
+        metadata: stableMetadata,
+        mediaType,
+        perPage,
+        orderBy,
+        orderDirection,
+        page: pageNum
+      });
+      setCache(cacheKey, {
+        files: response.files,
+        paging: response.paging,
+        timestamp: Date.now()
+      });
       setFiles(response.files);
       setHasNext(response.paging.has_next_page);
     } catch (err) {
@@ -355,15 +437,24 @@ function useFiles({
     } finally {
       setIsLoading(false);
     }
-  }, [client, stableMetadata, mediaType, perPage]);
+  }, [client, stableMetadata, mediaType, perPage, orderBy, orderDirection, getCache, setCache, effectiveStaleTime]);
   useEffect(() => {
-    if (autoLoad) {
-      fetchFiles(page);
+    const cachedEntry = getCache(paramsKeyWithPage);
+    if (cachedEntry) {
+      const age = Date.now() - cachedEntry.timestamp;
+      const isStale = age > effectiveStaleTime;
+      setFiles(cachedEntry.files);
+      setHasNext(cachedEntry.paging.has_next_page);
+      if (isStale && autoLoad) {
+        fetchFiles(page, true);
+      }
+    } else if (autoLoad) {
+      fetchFiles(page, true);
     }
-  }, [fetchFiles, page, autoLoad]);
+  }, [paramsKeyWithPage, autoLoad, getCache, effectiveStaleTime, fetchFiles, page]);
   useEffect(() => {
     const unsubscribe = on("file.uploaded", () => {
-      fetchFiles(page);
+      fetchFiles(page, true);
     });
     return unsubscribe;
   }, [on, fetchFiles, page]);
@@ -376,7 +467,7 @@ function useFiles({
     setPage((p) => Math.max(1, p - 1));
   }, []);
   const refresh = useCallback3(async () => {
-    await fetchFiles(page);
+    await fetchFiles(page, true);
   }, [fetchFiles, page]);
   return {
     files,
@@ -423,7 +514,7 @@ function FileList({
 }
 
 // src/components/FileImage.tsx
-import { useEffect as useEffect2, useState as useState3 } from "react";
+import { useEffect as useEffect2, useState as useState4 } from "react";
 import { jsx as jsx4, jsxs as jsxs2 } from "react/jsx-runtime";
 var imageCache = /* @__PURE__ */ new Map();
 function FileImage({
@@ -438,9 +529,9 @@ function FileImage({
   onLoad,
   onError
 }) {
-  const [imageSrc, setImageSrc] = useState3(null);
-  const [isLoading, setIsLoading] = useState3(true);
-  const [error, setError] = useState3(null);
+  const [imageSrc, setImageSrc] = useState4(null);
+  const [isLoading, setIsLoading] = useState4(true);
+  const [error, setError] = useState4(null);
   useEffect2(() => {
     let isMounted = true;
     let objectUrl = null;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@plugable-io/react",
-    "version": "0.0.2",
+    "version": "0.0.4",
     "description": "React components and hooks for Plugable File Management API",
     "main": "dist/index.js",
     "module": "dist/index.mjs",
@@ -43,7 +43,7 @@
         "react-dom": ">=16.8.0"
     },
     "dependencies": {
-        "@plugable-io/js": "^0.0.8"
+        "@plugable-io/js": "^0.0.9"
     },
     "devDependencies": {
         "@types/node": "^20.0.0",