Skip to main content

Site hooks

Hooks for managing site data within the CDT platform. Sites represent physical locations that can contain multiple buildings. These hooks use SWR for data fetching with automatic caching and revalidation, and SWR Mutation for create, update, and delete operations. The hooks are created via a factory pattern (createSiteHooks) that accepts an API adapter, enabling dependency injection for testing.

Hooks​

HookDescription
useSitesFetches all sites
useSiteFetches a single site by ID and provides an update function
useCreateSiteCreates a new site
useDeleteSiteDeletes a site by ID

useSites​

Fetches all sites from the API adapter.

Signature​

function useSites(): {
  sites: Site[];
  isLoading: boolean;
  isError: Error | undefined;
}

Parameters​

None.

Returns​

FieldTypeDescription
sitesSite[]Array of sites, defaults to empty array
isLoadingbooleanSWR loading state
isErrorError | undefinedSWR error state

Example​

const { sites, isLoading, isError } = useSites();

if (isLoading) return <Skeleton />;
if (isError) return <ErrorMessage />;

return <SiteList sites={sites} />;

useSite​

Fetches a single site by ID and provides a mutation function to update it.

Signature​

function useSite(siteId: string): {
  site: Site | null;
  isLoading: boolean;
  isError: Error | undefined;
  updateSite: (arg: SiteUpdateInput) => Promise<Site>;
  isMutating: boolean;
  updateError: Error | undefined;
  updatedData: Site | undefined;
}

Parameters​

ParamTypeRequiredDescription
siteIdstringYesThe ID of the site to fetch

Returns​

FieldTypeDescription
siteSite | nullThe fetched site, or null if not loaded
isLoadingbooleanSWR loading state
isErrorError | undefinedSWR error state
updateSite(arg: SiteUpdateInput) => Promise<Site>Mutation trigger to update the site
isMutatingbooleanWhether an update is in progress
updateErrorError | undefinedError from the update mutation
updatedDataSite | undefinedThe site data returned after update

Example​

const { site, isLoading, updateSite, isMutating } = useSite(siteId);

const handleUpdate = async () => {
  await updateSite({ name: "Updated Site Name" });
};

const handleBuildingAssociation = async () => {
  await updateSite({
    siteBuildings: {
      connect: [{ id: 123 }],
      disconnect: [{ id: 456 }],
    },
  });
};

Notes​

On successful update, the hook revalidates the individual site cache, the sites list, and the buildings list (since buildings may be associated with the site).

useCreateSite​

Creates a new site.

Signature​

function useCreateSite(): {
  createSite: (arg: Partial<Site>) => Promise<Site>;
  isMutating: boolean;
  createError: Error | undefined;
  createdData: Site | undefined;
}

Parameters​

None.

Returns​

FieldTypeDescription
createSite(arg: Partial<Site>) => Promise<Site>Mutation trigger to create a site
isMutatingbooleanWhether creation is in progress
createErrorError | undefinedError from the create mutation
createdDataSite | undefinedThe site data returned after creation

Example​

const { createSite, isMutating, createError } = useCreateSite();

const handleSubmit = async (data: Partial<Site>) => {
  await createSite(data);
};

Notes​

On successful creation, the hook revalidates the sites list cache.

useDeleteSite​

Deletes a site by ID.

Signature​

function useDeleteSite(siteId?: number | string): {
  deleteSite: (id: string | number) => Promise<void>;
  isMutating: boolean;
  deleteError: Error | undefined;
  deletedData: unknown;
}

Parameters​

ParamTypeRequiredDescription
siteIdnumber | stringNoOptional site ID for the SWR mutation key

Returns​

FieldTypeDescription
deleteSite(id: string | number) => Promise<void>Function to delete a site by ID
isMutatingbooleanWhether deletion is in progress
deleteErrorError | undefinedError from the delete mutation
deletedDataunknownData returned from the delete operation

Example​

const { deleteSite, isMutating } = useDeleteSite();

const handleDelete = async (siteId: number) => {
  await deleteSite(siteId);
};

Notes​

After deletion, the hook revalidates both the sites list and buildings list (since buildings may have been associated with the deleted site).