Subscription Types

Purpose

Subscription Types define the TypeScript contracts that specify how external real-time data sources integrate with the subscription middleware in this project. They establish the shape and behavior of subscription options, callback signatures, and the response structure returned by subscription hooks. This typing layer ensures type safety, consistency, and clear developer guidance when implementing or consuming subscription hooks, which are crucial for managing real-time updates with proper lifecycle handling.

While the parent topic explains subscription middleware and lifecycle management, Subscription Types focus specifically on formalizing the interfaces and generics that govern subscription interactions, enabling flexible, typed subscription implementations that can adapt to various data shapes and error handling strategies.

Functionality

The key components defined here include:

• SWRSubscriptionOptions:
  Represents the options passed to a subscription callback, primarily exposing a next function. This function acts as a callback to deliver new data or errors back into the SWR system, supporting both direct data and mutator callback patterns for advanced cache updates.

• SWRSubscription:
  A generic type describing the subscription function signature. It adapts dynamically based on the shape of the subscription key (SWRSubKey), which can be a function, a falsy value, or a direct key. This flexibility allows subscriptions to handle parameterized keys or conditional subscriptions gracefully.

• SWRSubscriptionResponse:
  Defines the shape of the data and error returned from the subscription hook, matching SWR’s convention of optional data and error properties.

• SWRSubscriptionHook:
  Typing for the subscription hook itself. It accepts a key, a subscription function, and optional SWR configuration, returning a typed response object. This abstraction allows the implementation of the useSWRSubscription hook or similar variants with strict typing.

Critical Interaction Example

The next callback within SWRSubscriptionOptions enables the subscription function to push updates or errors asynchronously into SWR’s state management:

type SWRSubscriptionOptions<Data, Error> = {
  next: (err?: Error | null, data?: Data | MutatorCallback<Data>) => void
}

The subscription function type adapts if the key is a function returning parameters or a static key:

type SWRSubscription<SWRSubKey, Data, Error> =
  SWRSubKey extends () => infer Arg | null | undefined | false
    ? (key: Arg, { next }: SWRSubscriptionOptions<Data, Error>) => void
    : SWRSubKey extends null | undefined | false
    ? never
    : SWRSubKey extends infer Arg
    ? (key: Arg, { next }: SWRSubscriptionOptions<Data, Error>) => void
    : never

This conditional typing ensures that subscription implementations receive the correct key argument shape, promoting both flexibility and type safety.

Relationship

Subscription Types serve as the foundation for the Subscription Middleware by:

• Providing the precise typings that middleware implementations rely on for function signatures and option objects.

• Enabling the subscription hook to enforce consistent inputs and outputs, which integrate with SWR’s caching and revalidation mechanisms.

• Supporting other subtopics like Middleware Architecture by ensuring middleware layers manipulating subscription hooks maintain type correctness.

• Complementing Core Data Fetching and Error Handling and Retry Logic by typing how subscription data/error updates flow into the SWR state lifecycle.

By defining these types separately, the system supports extensible subscription implementations, facilitates code reuse, and improves developer experience with robust autocomplete and compile-time checks.

Diagram

classDiagram
    class SWRSubscriptionOptions {
        +next(err?: Error|null, data?: Data|MutatorCallback<Data>): void
    }

    class SWRSubscription {
        <<type>>
        +invoke(key: Arg, options: SWRSubscriptionOptions): void
    }

    class SWRSubscriptionResponse {
        +data: Data
        +error: Error
    }

    class SWRSubscriptionHook {
        <<type>>
        +invoke(key: SWRSubKey, subscribe: SWRSubscription, config?: SWRConfiguration): SWRSubscriptionResponse
    }

    SWRSubscriptionOptions <.. SWRSubscription : uses
    SWRSubscription --> SWRSubscriptionHook : parameter
    SWRSubscriptionResponse <-- SWRSubscriptionHook : returns

This class diagram illustrates the core types and their relationships that define the subscription contract in the system. It highlights how the subscription function uses options including the next callback to push updates, and how the subscription hook returns a typed response containing data and error states.