@plugable-io/react 0.0.3 → 0.0.5

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 {
@@ -106,6 +116,7 @@ interface UseFilesOptions {
     autoLoad?: boolean;
     orderBy?: 'created_at' | 'name' | 'byte_size';
     orderDirection?: 'asc' | 'desc';
+    staleTime?: number;
 }
 interface UseFilesResult {
     files: FileObject[];
@@ -120,6 +131,6 @@ interface UseFilesResult {
     setPage: (page: number) => void;
     refresh: () => Promise<void>;
 }
-declare function useFiles({ metadata, startPage, perPage, mediaType, autoLoad, orderBy, orderDirection, }?: 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 {
@@ -106,6 +116,7 @@ interface UseFilesOptions {
     autoLoad?: boolean;
     orderBy?: 'created_at' | 'name' | 'byte_size';
     orderDirection?: 'asc' | 'desc';
+    staleTime?: number;
 }
 interface UseFilesResult {
     files: FileObject[];
@@ -120,6 +131,6 @@ interface UseFilesResult {
     setPage: (page: number) => void;
     refresh: () => Promise<void>;
 }
-declare function useFiles({ metadata, startPage, perPage, mediaType, autoLoad, orderBy, orderDirection, }?: 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 });
 }
@@ -371,16 +406,19 @@ function useFiles({
   mediaType,
   autoLoad = true,
   orderBy,
-  orderDirection
+  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 previousParamsRef = (0, import_react3.useRef)(null);
+  const isInitialMountRef = (0, import_react3.useRef)(true);
+  const effectiveStaleTime = staleTime ?? providerStaleTime;
   const metadataKey = JSON.stringify(metadata);
   const stableMetadata = (0, import_react3.useMemo)(() => metadata, [metadataKey]);
-  const loadedParamsRef = (0, import_react3.useRef)(null);
   const paramsKeyWithPage = (0, import_react3.useMemo)(() => JSON.stringify({
     metadata: stableMetadata,
     mediaType,
@@ -389,7 +427,27 @@ function useFiles({
     orderDirection,
     page
   }), [stableMetadata, mediaType, perPage, orderBy, orderDirection, page]);
-  const fetchFiles = (0, import_react3.useCallback)(async (pageNum) => {
+  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 = {
@@ -398,13 +456,11 @@ function useFiles({
         page: pageNum,
         per_page: perPage,
         with_download_url: true,
-        order_by: orderBy,
-        order_direction: orderDirection
+        ...orderBy && { order_by: orderBy },
+        ...orderDirection && { order_direction: orderDirection }
       };
       const response = await client.list(options);
-      setFiles(response.files);
-      setHasNext(response.paging.has_next_page);
-      const currentParamsKey = JSON.stringify({
+      const cacheKey = JSON.stringify({
         metadata: stableMetadata,
         mediaType,
         perPage,
@@ -412,7 +468,13 @@ function useFiles({
         orderDirection,
         page: pageNum
       });
-      loadedParamsRef.current = currentParamsKey;
+      setCache(cacheKey, {
+        files: response.files,
+        paging: response.paging,
+        timestamp: Date.now()
+      });
+      setFiles(response.files);
+      setHasNext(response.paging.has_next_page);
     } catch (err) {
       console.error("Failed to load files:", err);
       setFiles([]);
@@ -420,17 +482,31 @@ function useFiles({
     } finally {
       setIsLoading(false);
     }
-  }, [client, stableMetadata, mediaType, perPage, orderBy, orderDirection]);
+  }, [client, stableMetadata, mediaType, perPage, orderBy, orderDirection, getCache, setCache, effectiveStaleTime]);
   (0, import_react3.useEffect)(() => {
-    const hasLoadedForParams = loadedParamsRef.current === paramsKeyWithPage;
-    const shouldLoad = autoLoad || !hasLoadedForParams && files.length === 0 && !isLoading;
-    if (shouldLoad) {
-      fetchFiles(page);
+    const paramsChanged = previousParamsRef.current !== null && previousParamsRef.current !== paramsKeyWithPage;
+    const isInitialMount = isInitialMountRef.current;
+    previousParamsRef.current = paramsKeyWithPage;
+    if (isInitialMount) {
+      isInitialMountRef.current = false;
+    }
+    const cachedEntry = getCache(paramsKeyWithPage);
+    const shouldFetch = paramsChanged || isInitialMount && autoLoad;
+    if (cachedEntry) {
+      const age = Date.now() - cachedEntry.timestamp;
+      const isStale = age > effectiveStaleTime;
+      setFiles(cachedEntry.files);
+      setHasNext(cachedEntry.paging.has_next_page);
+      if (paramsChanged || isStale && shouldFetch) {
+        fetchFiles(page, true);
+      }
+    } else if (shouldFetch) {
+      fetchFiles(page, true);
     }
-  }, [fetchFiles, page, autoLoad, paramsKeyWithPage, isLoading]);
+  }, [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]);
@@ -443,7 +519,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,7 +355,7 @@ function Dropzone({
 }
 
 // src/hooks/useFiles.ts
-import { useState as useState2, useCallback as useCallback3, useEffect, useMemo as useMemo2, useRef as useRef2 } from "react";
+import { useState as useState3, useCallback as useCallback3, useEffect, useMemo as useMemo2, useRef as useRef2 } from "react";
 function useFiles({
   metadata,
   startPage = 1,
@@ -328,16 +363,19 @@ function useFiles({
   mediaType,
   autoLoad = true,
   orderBy,
-  orderDirection
+  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 previousParamsRef = useRef2(null);
+  const isInitialMountRef = useRef2(true);
+  const effectiveStaleTime = staleTime ?? providerStaleTime;
   const metadataKey = JSON.stringify(metadata);
   const stableMetadata = useMemo2(() => metadata, [metadataKey]);
-  const loadedParamsRef = useRef2(null);
   const paramsKeyWithPage = useMemo2(() => JSON.stringify({
     metadata: stableMetadata,
     mediaType,
@@ -346,7 +384,27 @@ function useFiles({
     orderDirection,
     page
   }), [stableMetadata, mediaType, perPage, orderBy, orderDirection, page]);
-  const fetchFiles = useCallback3(async (pageNum) => {
+  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 = {
@@ -355,13 +413,11 @@ function useFiles({
         page: pageNum,
         per_page: perPage,
         with_download_url: true,
-        order_by: orderBy,
-        order_direction: orderDirection
+        ...orderBy && { order_by: orderBy },
+        ...orderDirection && { order_direction: orderDirection }
       };
       const response = await client.list(options);
-      setFiles(response.files);
-      setHasNext(response.paging.has_next_page);
-      const currentParamsKey = JSON.stringify({
+      const cacheKey = JSON.stringify({
         metadata: stableMetadata,
         mediaType,
         perPage,
@@ -369,7 +425,13 @@ function useFiles({
         orderDirection,
         page: pageNum
       });
-      loadedParamsRef.current = currentParamsKey;
+      setCache(cacheKey, {
+        files: response.files,
+        paging: response.paging,
+        timestamp: Date.now()
+      });
+      setFiles(response.files);
+      setHasNext(response.paging.has_next_page);
     } catch (err) {
       console.error("Failed to load files:", err);
       setFiles([]);
@@ -377,17 +439,31 @@ function useFiles({
     } finally {
       setIsLoading(false);
     }
-  }, [client, stableMetadata, mediaType, perPage, orderBy, orderDirection]);
+  }, [client, stableMetadata, mediaType, perPage, orderBy, orderDirection, getCache, setCache, effectiveStaleTime]);
   useEffect(() => {
-    const hasLoadedForParams = loadedParamsRef.current === paramsKeyWithPage;
-    const shouldLoad = autoLoad || !hasLoadedForParams && files.length === 0 && !isLoading;
-    if (shouldLoad) {
-      fetchFiles(page);
+    const paramsChanged = previousParamsRef.current !== null && previousParamsRef.current !== paramsKeyWithPage;
+    const isInitialMount = isInitialMountRef.current;
+    previousParamsRef.current = paramsKeyWithPage;
+    if (isInitialMount) {
+      isInitialMountRef.current = false;
+    }
+    const cachedEntry = getCache(paramsKeyWithPage);
+    const shouldFetch = paramsChanged || isInitialMount && autoLoad;
+    if (cachedEntry) {
+      const age = Date.now() - cachedEntry.timestamp;
+      const isStale = age > effectiveStaleTime;
+      setFiles(cachedEntry.files);
+      setHasNext(cachedEntry.paging.has_next_page);
+      if (paramsChanged || isStale && shouldFetch) {
+        fetchFiles(page, true);
+      }
+    } else if (shouldFetch) {
+      fetchFiles(page, true);
     }
-  }, [fetchFiles, page, autoLoad, paramsKeyWithPage, isLoading]);
+  }, [paramsKeyWithPage, autoLoad, getCache, effectiveStaleTime, fetchFiles, page]);
   useEffect(() => {
     const unsubscribe = on("file.uploaded", () => {
-      fetchFiles(page);
+      fetchFiles(page, true);
     });
     return unsubscribe;
   }, [on, fetchFiles, page]);
@@ -400,7 +476,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,
@@ -447,7 +523,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({
@@ -462,9 +538,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.3",
+    "version": "0.0.5",
     "description": "React components and hooks for Plugable File Management API",
     "main": "dist/index.js",
     "module": "dist/index.mjs",