Dwidge File Cache Expo

https://www.npmjs.com/package/%40dwidge/file-cache-expo
Admin
A React hooks-based file caching system that manages efficient local storage and remote...
Tokens:27,573
Snippets:240
Trust Score:9.6
Update:10 months ago
Show doc for...
Tokens:
Raw
### FileCacheProvider Configuration and Usage Example

Source: https://www.npmjs.com/package/%40dwidge/file-cache-expo/v/0.0_activeTab=dependencies

Demonstrates how to set up and use the `FileCacheProvider` in a React application. It includes example implementations for `getFileUrls`, `uploadFile`, and `downloadFile`, and shows how to configure various cache limits and online status. This setup is crucial for initializing the file caching system.

```typescript
import React from "react";
import {
  FileCacheProvider,
  useFileUri,
  useFileCacheSync,
} from "./fileCache/provider";
import App from "./App";

// Replace these with your actual implementations.
const getFileUrls = async ({ id }: { id: string }) => ({
  id,
  getUrl: `https://example.com/files/${id}`,
  putUrl: `https://example.com/files/${id}`,
  mime: "image/png",
  size: 12345,
  sha256: "abcdef1234567890",
  updatedAt: (Date.now() / 1000) | 0,
});
const uploadFile = async (id: string, dataUri: string) => {
  console.log(`Uploading file ${id} with data: ${dataUri}`);
};
const downloadFile = async (id: string) => {
  // Simulate download logic.
  return `data:image/png;base64,...`;
};

const Root = () => (
  <FileCacheProvider
    maxCache={50}
    maxPending={10}
    maxRecent={10}
    isOnline={true}
    getCacheableIds={async (max) => {
      // Example: Return a static list or fetch from API.
      return ["file-1", "file-2", "file-3", "file-4", "file-5"].slice(0, max);
    }}
    uploadFile={uploadFile}
    downloadFile={downloadFile}
  >
    <App />
  </FileCacheProvider>
);

export default Root;

```

--------------------------------

### Usage Example

Source: https://www.npmjs.com/package/%40dwidge/file-cache-expo/v/0.0_activeTab=code

A practical example demonstrating how to set up and use the `FileCacheProvider` in a React application.

```APIDOC
## File Cache Provider Usage Example

### Description
This example shows how to wrap your application with `FileCacheProvider` and configure its essential props, including custom upload and download functions.

### Code

```javascript
import React from "react";
import {
  FileCacheProvider,
  useFileUri, // Assumed hook from the package
  useFileCacheSync, // Assumed hook from the package
} from "./fileCache/provider"; // Adjust import path as needed
import App from "./App";

// Mock implementations for file operations
const getFileUrls = async ({ id }) => {
  // Replace with actual logic to get file URLs
  return {
    id,
    getUrl: `https://example.com/files/${id}`,
    putUrl: `https://example.com/files/${id}`,
    mime: "image/png",
    size: 12345,
    sha256: "abcdef1234567890",
    updatedAt: (Date.now() / 1000) | 0,
  };
};

const uploadFile = async (id, dataUri) => {
  console.log(`Uploading file ${id} with data: ${dataUri}`);
  // Implement actual file upload logic here
};

const downloadFile = async (id) => {
  console.log(`Downloading file ${id}`);
  // Simulate download logic, returning a Data URI
  return `data:image/png;base64,mockImageDataFor${id}`;
};

const Root = () => (
  <FileCacheProvider
    maxCache={50} // Max 50 items in cache
    maxPending={10} // Max 10 pending items
    maxRecent={10} // Max 10 recent items
    isOnline={true} // Assume online
    getCacheableIds={async (max) => {
      // Example: Return a static list or fetch from API.
      // This function should return file IDs that are eligible for caching.
      const allIds = ["file-1", "file-2", "file-3", "file-4", "file-5"];
      return allIds.slice(0, max);
    }}
    uploadFile={uploadFile}
    downloadFile={downloadFile}
  >
    <App />
  </FileCacheProvider>
);

export default Root;
```
```

--------------------------------

### FileCacheProvider Configuration and Usage Example

Source: https://www.npmjs.com/package/%40dwidge/file-cache-expo/v/0.0_activeTab=versions

Demonstrates how to set up the FileCacheProvider with various configuration options and integrate it within a React application. It includes placeholder functions for file upload, download, and fetching cacheable IDs.

```typescript
import React from "react";
import {
  FileCacheProvider,
  useFileUri,
  useFileCacheSync,
} from "./fileCache/provider";
import App from "./App";

// Replace these with your actual implementations.
const getFileUrls = async ({ id }: { id: string }) => ({
  id,
  getUrl: `https://example.com/files/${id}`,
  putUrl: `https://example.com/files/${id}`,
  mime: "image/png",
  size: 12345,
  sha256: "abcdef1234567890",
  updatedAt: (Date.now() / 1000) | 0,
});
const uploadFile = async (id: string, dataUri: string) => {
  console.log(`Uploading file ${id} with data: ${dataUri}`);
};
const downloadFile = async (id: string) => {
  // Simulate download logic.
  return `data:image/png;base64,...`;
};

const Root = () => (
  <FileCacheProvider
    maxCache={50}
    maxPending={10}
    maxRecent={10}
    isOnline={true}
    getCacheableIds={async (max) => {
      // Example: Return a static list or fetch from API.
      return ["file-1", "file-2", "file-3", "file-4", "file-5"].slice(0, max);
    }}
    uploadFile={uploadFile}
    downloadFile={downloadFile}
  >
    <App />
  </FileCacheProvider>
);

export default Root;
```

--------------------------------

### Package Installation Command

Source: https://www.npmjs.com/package/%40dwidge/file-cache-expo/index_activeTab=code

The standard npm command to install the @dwidge/file-cache-expo package into your project dependencies.

```bash
npm i @dwidge/file-cache-expo
```

--------------------------------

### React File Cache Demo using Hooks

Source: https://www.npmjs.com/package/%40dwidge/file-cache-expo/v/0.0_activeTab=dependencies

Demonstrates how to use the `useFileUri` and `useFileCacheSync` hooks from the file-cache-expo package in a React application. It includes components for displaying cached image files, handling file uploads, and triggering cache synchronization.

```typescript
import React from "react";
import { useFileUri, useFileCacheSync } from "./fileCache/provider";

const FileDisplay: React.FC<{ fileId: string }> = ({ fileId }) => {
  const [dataUri, setDataUri] = useFileUri(fileId);

  const handleFileChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    const file = event.target.files?.[0];
    if (file) {
      const reader = new FileReader();
      reader.onloadend = () => {
        setDataUri(reader.result as string);
      };
      reader.readAsDataURL(file);
    }
  };

  const handleDelete = () => {
    setDataUri(null);
  };

  return (
    <div>
      {dataUri ? (
        <>
          <img
            src={dataUri}
            alt="Cached file"
            style={{ maxWidth: "200px", maxHeight: "200px" }}
          />
          <button onClick={handleDelete}>🗑️ Delete</button>
        </>
      ) : (
        <>
          <p>Loading file...</p>
          <input type="file" accept="image/*" onChange={handleFileChange} />
        </>
      )}
    </div>
  );
};

const SyncButton: React.FC = () => {
  const sync = useFileCacheSync();

  return <button onClick={() => sync()}>🔄 Sync Files</button>;
};

export default function App() {
  return (
    <div>
      <h1>File Cache Demo</h1>
      <FileDisplay fileId="file-123" />
      <SyncButton />
    </div>
  );
}
```

--------------------------------

### File Prioritization

Source: https://www.npmjs.com/package/%40dwidge/file-cache-expo/v/0.0_activeTab=dependents

Explains the order in which files are prioritized for caching and retention within the file cache system.

```APIDOC
## File Prioritization & Pecking Order

### Description
Specifies the priority of files for caching and retention.

### Prioritization Order
1.  **Pending Items:** Always kept due to unsynchronized changes. These represent the only copy in existence, so must be protected until uploaded.
2.  **Mounted Items (Active Hooks):** Files actively used via `useFileUri` hooks.
3.  **Recent Items:** Files recently accessed, tracked to improve cache hit rate.
4.  **Cacheable List:** Files from a remotely provided list, ordered by recency, filling remaining cache space.
```

--------------------------------

### File Prioritization

Source: https://www.npmjs.com/package/%40dwidge/file-cache-expo/v/0.0_activeTab=code

Explains the order in which files are prioritized for storage within the cache.

```APIDOC
## File Prioritization & Pecking Order

### Description
Specifies the order of importance for files managed by the cache, determining which files are kept when storage is limited.

### Prioritization Order

1.  **Pending Items:** These files are always retained in the cache because they represent unsynchronized changes and are the only existing copy. They are protected until they are successfully uploaded.
2.  **Mounted Items (Active Hooks):** Files that are actively being used via `useFileUri` hooks are given high priority.
3.  **Recent Items:** Files that have been accessed recently are prioritized to improve cache hit rates for frequently used data.
4.  **Cacheable List:** Files obtained from a provided `getCacheableIds` function, ordered by recency. These files are used to fill any remaining space in the cache after higher-priority items have been accommodated.
```

--------------------------------

### Cache Eviction Strategy

Source: https://www.npmjs.com/package/%40dwidge/file-cache-expo/v/0.0_activeTab=code

Details the rules and logic the system uses to remove files from the cache when storage limits are reached.

```APIDOC
## Cache Eviction Strategy

### Description
Defines how files are removed from the cache when the `maxCache` limit is approached or exceeded.

### Eviction Trigger

- When a new file is added to the cache, the system first checks if the current cache size exceeds the configured `maxCache` limit.

### Eviction Rules

1.  **Non-Pending Items Only:** Only files that are not currently in the 'pending' state (i.e., not awaiting upload) are considered eligible for eviction.
2.  **Oldest First:** Eviction targets the oldest file currently in the cache.
3.  **Pending Items Overload:** If all files currently in the cache are marked as 'pending' and cannot be evicted, attempting to add a new file will result in an error. This prevents the cache from exceeding its defined limit when all items are critical.

### Dynamic Cache Management

- The system continuously monitors changes to `maxCache` and the list of cacheable items.
- Files that are no longer considered cacheable or whose presence would cause the cache to exceed the dynamic threshold (`maxCache` minus the number of pending items) are removed.
```

--------------------------------

### File Cache Hooks API Overview

Source: https://www.npmjs.com/package/%40dwidge/file-cache-expo/index_activeTab=code

Provides a brief description of the core hooks available in the file cache library. These hooks abstract the complexities of local and remote file synchronization, cache management, and status monitoring.

```typescript
// Hook: useFileUri
// Provides access to a file's DataURI from the cache.
// Returns null if the file is not cached.
// Utilizes local and remote synchronization.
// Returns an async state tuple [dataUri, setDataUri].
```

```typescript
// Hook: useFileCacheSync
// Returns the sync function.
// Calling sync() triggers upload of pending files and cache refresh.
```

```typescript
// Hook: useCacheList
// Returns an array of file IDs currently in the cache.
```

```typescript
// Hook: usePendingList
// Returns an array of file IDs that are pending upload.
```

```typescript
// Hook: useRecentList
// Returns an array of file IDs that have been recently accessed.
```

```typescript
// Hook: useFileCacheReset
// Returns the reset function.
// Calling reset() clears the entire file cache.
```

--------------------------------

### usePendingList Hook for Monitoring Pending Uploads

Source: https://www.npmjs.com/package/%40dwidge/file-cache-expo/index_activeTab=dependents

The `usePendingList` hook returns an array of file IDs that are currently queued for upload. This allows developers to monitor the status of pending uploads and implement any necessary management logic.

```typescript
const pendingFiles = usePendingList();
```

--------------------------------

### React Component: File Display and Sync

Source: https://www.npmjs.com/package/%40dwidge/file-cache-expo/v/0.0

This React component demonstrates how to use the `useFileUri` hook to display cached files and the `useFileCacheSync` hook to synchronize the file cache. It handles file selection, display, and deletion, along with a sync button for cache updates.  It utilizes a file input to allow users to select images and the cache management hooks to display, delete, and synchronize files.

```typescript
import React from "react";
import {
  useFileUri,
  useFileCacheSync,
} from "./fileCache/provider";

const FileDisplay: React.FC<{ fileId: string }> = ({ fileId }) => {
  const [dataUri, setDataUri] = useFileUri(fileId);

  const handleFileChange = (
    event: React.ChangeEvent<HTMLInputElement>
  ) => {
    const file = event.target.files?.[0];
    if (file) {
      const reader = new FileReader();
      reader.onloadend = () => {
        setDataUri(reader.result as string);
      };
      reader.readAsDataURL(file);
    }
  };

  const handleDelete = () => {
    setDataUri(null);
  };

  return (
    <div>
      {dataUri ? (
        <>
          <img
            src={dataUri}
            alt="Cached file"
            style={{ maxWidth: "200px", maxHeight: "200px" }}
          />
          <button onClick={handleDelete}>🗑️ Delete</button>
        </>
      ) : (
        <>
          <p>Loading file...</p>
          <input
            type="file"
            accept="image/*"
            onChange={handleFileChange}
          />
        </>
      )}
    </div>
  );
};

const SyncButton: React.FC = () => {
  const sync = useFileCacheSync();

  return <button onClick={() => sync()}>🔄 Sync Files</button>;
};

export default function App() {
  return (
    <div>
      <h1>File Cache Demo</h1>
      <FileDisplay fileId="file-123" />
      <SyncButton />
    </div>
  );
}

```

--------------------------------

### Cache Eviction Strategy

Source: https://www.npmjs.com/package/%40dwidge/file-cache-expo/v/0.0_activeTab=dependents

Details the logic for removing items from the cache when it reaches its maximum capacity. It prioritizes non-pending items and targets the oldest files first.

```APIDOC
## Cache Eviction Strategy

### Description
Defines how the file cache manages its size and evicts old items.

### Eviction Trigger
- When a new file is added, the system checks if the cache size exceeds `maxCache`.

### Eviction Rules
1.  **Non-Pending Items:** Only files not in the pending list are considered for eviction.
2.  **Order:** Eviction targets the oldest file in the cache.
3.  **Pending Items Overload:** If all cached items are pending upload and cannot be evicted, adding a new file results in an error to prevent exceeding the cache limit.

### Dynamic Cache Management
- The system monitors changes in `maxCache` and the cacheable list, removing files that are no longer cacheable or exceed the dynamic threshold (`maxCache - pendingCount`).
```

--------------------------------

### React File Cache Demo App using Hooks

Source: https://www.npmjs.com/package/%40dwidge/file-cache-expo/v/0.0_activeTab=versions

A React Native component demonstrating file caching with hooks. It includes functionality to display cached images, upload new files, and synchronize the cache. It utilizes `useFileUri` for displaying cached file data and `useFileCacheSync` for triggering cache synchronization.

```typescript
import React from "react";
import { useFileUri, useFileCacheSync } from "./fileCache/provider";

const FileDisplay: React.FC<{ fileId: string }> = ({ fileId }) => {
  const [dataUri, setDataUri] = useFileUri(fileId);

  const handleFileChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    const file = event.target.files?.[0];
    if (file) {
      const reader = new FileReader();
      reader.onloadend = () => {
        setDataUri(reader.result as string);
      };
      reader.readAsDataURL(file);
    }
  };

  const handleDelete = () => {
    setDataUri(null);
  };

  return (
    <div>
      {dataUri ? (
        <>
          <img
            src={dataUri}
            alt="Cached file"
            style={{ maxWidth: "200px", maxHeight: "200px" }}
          />
          <button onClick={handleDelete}>🗑️ Delete</button>
        </>
      ) : (
        <>
          <p>Loading file...</p>
          <input type="file" accept="image/*" onChange={handleFileChange} />
        </>
      )}
    </div>
  );
};

const SyncButton: React.FC = () => {
  const sync = useFileCacheSync();

  return <button onClick={() => sync()}>🔄 Sync Files</button>;
};

export default function App() {
  return (
    <div>
      <h1>File Cache Demo</h1>
      <FileDisplay fileId="file-123" />
      <SyncButton />
    </div>
  );
}

```

--------------------------------

### FileCacheProvider Configuration

Source: https://www.npmjs.com/package/%40dwidge/file-cache-expo/v/0.0_activeTab=dependents

The `FileCacheProvider` component configures and manages the file cache. It accepts several props to customize cache behavior, including size limits, online status, and custom functions for fetching cacheable IDs, uploading, and downloading files.

```APIDOC
## FileCacheProvider Props

### Description
Configuration options for the `FileCacheProvider`.

### Parameters

#### Props
- **`maxCache`** (number) - Required - Maximum total items to cache.
- **`maxPending`** (number) - Optional - Maximum pending items to cache.
- **`maxMounted`** (number) - Optional - Maximum mounted items to auto-fetch when online.
- **`maxRecent`** (number) - Required - Maximum recent items to keep in cache.
- **`isOnline`** (boolean) - Required - Flag indicating online status, enabling auto-fetching of mounted ids.
- **`getCacheableIds`** ((`maxItemsToCache`: `number`) => `Promise<FileId[] | undefined>`) - Optional - Function to fetch cacheable file IDs, ordered by recency.
- **`uploadFile`** ((`id`: `FileId`, `data`: `DataUri | Deleted`) => `Promise<void>`) - Optional - Function to upload a file.
- **`downloadFile`** ((`id`: `FileId`) => `Promise<DataUri | Deleted>`) - Optional - Function to download a file.
- **`cacheStorage`** (`ManagedUriStorage`) - Optional - Custom storage implementation.
- **`pendingIds`** (`AsyncState<FileId[]>`) - Optional - Custom pending IDs state.

### Request Example
```javascript
<FileCacheProvider
  maxCache={50}
  maxPending={10}
  maxRecent={10}
  isOnline={true}
  getCacheableIds={async (max) => {
    return ["file-1", "file-2", "file-3", "file-4", "file-5"].slice(0, max);
  }}
  uploadFile={uploadFile}
  downloadFile={downloadFile}
>
  {/* App content */}
</FileCacheProvider>
```
```

--------------------------------

### React Component Using File Cache Hooks

Source: https://www.npmjs.com/package/%40dwidge/file-cache-expo/v/0.0_activeTab=dependents

This React component demonstrates how to use the useFileUri hook to display cached file content and upload new files, and the useFileCacheSync hook to trigger a cache synchronization. It handles file selection, display, deletion, and synchronization.

```typescript
import React from "react";
import { useFileUri, useFileCacheSync } from "./fileCache/provider";

const FileDisplay: React.FC<{ fileId: string }> = ({ fileId }) => {
  const [dataUri, setDataUri] = useFileUri(fileId);

  const handleFileChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    const file = event.target.files?.[0];
    if (file) {
      const reader = new FileReader();
      reader.onloadend = () => {
        setDataUri(reader.result as string);
      };
      reader.readAsDataURL(file);
    }
  };

  const handleDelete = () => {
    setDataUri(null);
  };

  return (
    <div>
      {dataUri ? (
        <>
          <img
            src={dataUri}
            alt="Cached file"
            style={{ maxWidth: "200px", maxHeight: "200px" }}
          />
          <button onClick={handleDelete}>🗑️ Delete</button>
        </>
      ) : (
        <>
          <p>Loading file...</p>
          <input type="file" accept="image/*" onChange={handleFileChange} />
        </>
      )<bos>}
    </div>
  );
};

const SyncButton: React.FC = () => {
  const sync = useFileCacheSync();

  return <button onClick={() => sync()}>🔄 Sync Files</button>;
};

export default function App() {
  return (
    <div>
      <h1>File Cache Demo</h1>
      <FileDisplay fileId="file-123" />
      <SyncButton />
    </div>
  );
}
```

--------------------------------

### useRecentList Hook for Accessing Recently Accessed Files

Source: https://www.npmjs.com/package/%40dwidge/file-cache-expo/index_activeTab=dependents

This hook, `useRecentList`, provides an array of file IDs that have been recently accessed. It helps in understanding file usage patterns and can inform cache prioritization strategies.

```typescript
const recentFiles = useRecentList();
```
Tokens:
Raw