Catalog

This is a full-featured composable to fetch and display long lists of entries. It can be used to display synchronous and asynchronous lists with many options and APIs to load, manage, filter, and select entries.

Check out t-catalog component to help you display the results of a catalog.

Get Started

To create a new catalog instance, call the createCatalog function. It will provide your app with an instance that all child components will be able to access. Then, inside a child component, call the useCatalog function which will access the nearest catalog instance.

import { createCatalog, useCatalog } from "@dija/tohama-use";
import { defineComponent, onBeforeMount } from "vue";

const Parent = defineComponent({
  setup() {
    // Create a new instance
    createCatalog({
      /// options
    });

    return () => (
      <div>
        <Child />
      </div>
    );
  },
});

const Child = defineComponent({
  setup() {
    // Use the nearest instance
    const catalog = useCatalog();

    // Auto initialize instance on component mount
    onBeforeMount(() => catalog.init());

    // Display the entries
    return () => <div>
        {catalog.entries.value.map((entry) => (
           // display catalog results
        ))}
    </div>;
  },
});

How it Works

When you use createCatalog, you have to provide a onFetch callback. This callback will be executed on several occasions to initialize, refresh, load additional pages, and filter results.

It provides a aggregates parameter where you can read the current page, limit, and any applied filters. This will help you build your query and return the exact results.

createCatalog({
  /// options
  onFetch: async (aggregates) => {
    // Fetch from server based on the current aggregates
    const response = await fetchFromServer(aggregates.page);
    return {
      success: true,
      value: {
        entries: response,
      },
    };
  },
});

It expects a synchronous or asynchronous return value that consists of the following:

type UseCatalogResponse<T, F> = {
  success?: boolean;
  error?: string;
  value?: {
    entries: T[];
    total?: number;
    aggregates?: {
      limit: number;
      page: number;
      filter?: F;
    };
  };
};

success

Indicates if the operation was successful or not.

error

An error code or message that you want to display to users.

value.entries

A list of new items from your source.

value.total

This is an optional parameter. It is used to calculate the number of available pages when using pages as the mode.

value.aggregates

This is an optional parameter. It is used to update the stored aggregates in the catalog.

Typescript

Both createCatalog and useCatalog provide an option to pass two generic types which allows you to display and filter results in a fully type-safe way.

createCatalog<City, Filters>({
  /// options
});

Type T

The type of the entry you will be displaying.

export type City = { id: string; city: string; country: string };

Type F

The type of the aggregates.filter object that you would like to maintain when filtering results.

export type Filters = { country?: string };