Supabase Cache Helpers

Supabase Cache Helpers is a collection of framework-specific utilities designed to bridge the gap between Supabase client libraries (postgrest-js, storage-js, and realtime-js) and popular frontend cache management solutions like SWR and React Query.

Key capabilities include:

• Automatic Cache Key Generation: Parses any query into a unique, definite key.
• Smart Mutations: Automatically populates the cache after insert, update, upsert, or delete operations using implicit schema knowledge.
• Cache Synchronization: Auto-expands mutation queries based on existing cache data to keep the application state up-to-date.
• Advanced Querying: Built-in support for pagination and infinite scroll.
• Storage Integration: One-liner utilities for uploading, downloading, and removing Supabase Storage objects.

PostgREST SWR is a collection of utilities designed to bridge the gap between Supabase client libraries (postgrest-js, storage-js, and realtime-js) and the SWR caching library.

It simplifies data management by providing:

• Automatic Cache Key Generation: Parses any query into a unique, definite key.
• Smart Cache Management: Automatically populates the cache after mutations or subscriptions and expands mutation queries based on existing cache data to keep the application state synchronized.
• Integrated Mutations: Simplifies insert, update, upsert, and delete operations.
• Advanced Querying: Built-in support for pagination and infinite scroll.
• Storage Support: One-liner utilities for uploading, downloading, and removing Supabase Storage objects.

PostgREST React Query is a collection of utilities designed to bridge the gap between Supabase client libraries (postgrest-js, storage-js, and realtime-js) and TanStack React Query.

It simplifies data management by providing:

• Automatic Cache Key Generation: Parses any query into a unique, definite query key.
• Automatic Cache Population: Uses implicit schema knowledge to populate the query cache automatically after mutations or subscriptions.
• Mutation Management: Handles insert, update, upsert, and delete operations with auto-expansion of mutation queries to keep the app state up-to-date.
• Storage Integration: Provides one-liner utilities for uploading, downloading, and removing Supabase Storage objects.
• Advanced Querying: Built-in support for pagination and infinite scroll queries.

The @supabase-cache-helpers/storage-react-query package provides a collection of React Query utilities specifically designed for working with Supabase Storage. It bridges the gap between the Supabase storage-js client and TanStack React Query, allowing you to manage storage objects (uploading, downloading, and removing) using React Query's powerful caching and mutation patterns.

Key capabilities include:

• One-liner operations: Simplify uploading, downloading, and removing Supabase Storage objects.
• Automatic cache management: Generates unique query keys for storage operations and automatically updates the cache after mutations.
• Seamless integration: Built to work out-of-the-box with TanStack React Query features.

The @supabase-cache-helpers/postgrest-server package provides server-side caching utilities for working with Supabase. It acts as a bridge between Supabase client libraries (postgrest-js, storage-js, and realtime-js) and popular frontend cache management solutions like SWR or React Query.

Key capabilities include:

• Server-Side Query Caching: Provides a simple abstraction to cache queries directed at the PostgREST API.
• Automatic Cache Key Generation: Parses any query into a unique and definite query key.
• Implicit Cache Population: Automatically populates the query cache during mutations using implicit knowledge of the schema.
• Mutation Synchronization: Automatically expands mutation queries based on existing cache data to ensure the application remains up-to-date.

PostgREST Core provides a collection of cache utilities specifically designed for working with the Supabase REST API.

Important Note: This package is not intended to be used as a standalone library. It is a foundational component meant to be used in conjunction with other specialized packages in the supabase-cache-helpers ecosystem (such as React Query, SWR, or Server-side implementations).

Supabase Cache Helpers is a collection of framework-specific utilities designed to bridge the gap between Supabase client libraries (postgrest-js, storage-js, and realtime-js) and popular frontend cache management solutions like SWR and React Query.

Instead of manually managing cache keys or implementing complex manual cache updates after mutations, these helpers automatically parse Supabase queries into unique, definite query keys. They also use implicit knowledge of your schema to automatically populate or expand your query cache following mutations or subscriptions, ensuring your UI remains reactive and up-to-date without repetitive boilerplate.

The @supabase-cache-helpers/storage-swr package provides SWR utilities designed to bridge the gap between the Supabase storage-js client and the SWR caching library. It allows you to simplify the logic for fetching, subscribing to updates, and mutating Supabase Storage objects (uploading, downloading, and removing) using a single line of code.

Key capabilities include:

• Automatic cache key generation: Every storage query is parsed into a unique and definite key.
• One-liner operations: Simplified methods to upload, download, and remove objects.
• Automatic cache population: The cache is automatically updated following mutations or subscriptions.
• Seamless SWR integration: Leverages SWR's built-in features like revalidation and caching.

To browse storage contents, use the following hooks:

• useDirectory: To list all files within a specific directory.
• useDirectoryUrls: To list all files in a directory along with their corresponding URLs.

In serverless environments, you often need to ensure background tasks (like cache updates) complete before the function returns. The QueryCache requires a Context object that implements the following interface:

export interface Context {
  waitUntil: (p: Promise<unknown>) => void;
}

If you are building a stateful application, you can use DefaultStatefulContext from @unkey/cache to satisfy this requirement.

import { DefaultStatefulContext } from "@unkey/cache";
const ctx = new DefaultStatefulContext();

The Storage cache helper hooks (like useFileUrl, useDirectory, and useDirectoryFileUrls) wrap the underlying data fetching hooks from the SWR or React Query libraries. They automatically generate cache keys and fetcher functions based on the provided Storage client and path.

For example, calling useFileUrl with a bucket named public_contact_files and a path postgrest-storage-file-url-94/1.jpg results in the following cache keys:

• SWR: storage$public_contact_files$postgrest-storage-file-url-94/1.jpg
• React Query: [ "storage", "public_contact_files", "postgrest-storage-file-url-94/1.jpg" ]