Skip to main content

useFolderOperations Hook

The useFolderOperations hook provides a comprehensive set of operations for managing folders and files, including moving, deleting, starring, and updating permissions.

Usage​

import { useFolderOperations } from '@hooks/useFolderOperations'

function MyComponent() {
  const {
    moveToFolder,
    moveToProject,
    deleteFolder,
    updatePermissions,
    starItem,
    unstarItem,
    renameItem,
    deleteItem,
    createFolder
  } = useFolderOperations()

  const handleMove = async () => {
    try {
      await moveToFolder({
        fileId: 'file-id',
        folderId: 'target-folder-id',
        fileType: 'canvas'
      })
    } catch (error) {
      console.error('Failed to move:', error)
    }
  }
}

API Reference​

moveToFolder​

Moves a file or folder to a target folder.

const moveToFolder: ({
  fileId,
  fileType,
  folderId
}: {
  fileId: string
  fileType: string
  folderId: string
}) => Promise<void>

moveToProject​

Moves a file or folder to a different project.

const moveToProject: ({
  fileId,
  fileType,
  folderId
}: {
  fileId: string
  fileType: string
  folderId: string
}) => Promise<void>

createFolder​

Creates a new folder.

const createFolder: ({
  name,
  parent,
  project
}: CreateFolderParams) => Promise<void>

interface CreateFolderParams {
  name: string
  parent?: string | null
  project: string
}

deleteFolder​

Deletes a folder and optionally its contents.

const deleteFolder: (folderId: string) => Promise<void>

updatePermissions​

Updates folder permissions.

const updatePermissions: ({
  id,
  permissions
}: {
  id: string
  permissions: UpdateFolderPermissionsRequest
}) => Promise<void>

interface UpdateFolderPermissionsRequest {
  users: { user: string; role: FolderRole }[]
  teams: { team: string; role: FolderRole }[]
  inheritPermissions: boolean
}

starItem/unstarItem​

Manage starred items.

const starItem: ({
  itemId,
  itemType
}: {
  itemId: string
  itemType: StarredItemType
}) => Promise<void>

const unstarItem: ({
  itemId,
  itemType
}: {
  itemId: string
  itemType: StarredItemType
}) => Promise<void>

renameItem​

Rename a file or folder.

const renameItem: (
  file: { _id: string; type: string },
  newName: string
) => Promise<void>

deleteItem​

Delete a file or folder.

const deleteItem: (
  file: { _id: string; type: string }
) => Promise<void>

Implementation Details​

The hook uses React Query's useMutation for managing server state and cache invalidation:

const moveToFolderMutation = useMutation({
  mutationFn: ({
    fileId,
    fileType,
    folderId
  }: {
    fileId: string
    fileType: string
    folderId: string
  }) => moveFolder({ id: fileId, newParentId: folderId, itemType: fileType }),
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: [FOLDER_QUERY_KEY] })
    queryClient.invalidateQueries({ queryKey: ['folder'] })
  },
  onError: (error) => {
    showError({
      title: 'Failed to Move',
      message: error instanceof Error ? error.message : 'Failed to move item'
    })
  }
})

Error Handling​

All operations include proper error handling with descriptive error messages:

try {
  await starItem({ itemId: 'file-id', itemType: 'canvas' })
} catch (error) {
  showError({
    title: 'Failed to Star',
    message: error instanceof Error ? error.message : 'Failed to star item'
  })
}

Cache Management​

The hook automatically manages the cache for:

  • Folder tree data
  • Individual folder data
  • Starred items
  • Project data

Each mutation includes appropriate cache invalidation to ensure UI consistency.

Example with Multiple Operations​

function FolderManager() {
  const {
    moveToFolder,
    moveToProject,
    deleteFolder,
    updatePermissions,
    starItem,
    unstarItem,
    renameItem,
    deleteItem,
    createFolder
  } = useFolderOperations()

  const handleFileOperations = async () => {
    try {
      // Move file to a folder
      await moveToFolder({
        fileId: 'file-1',
        folderId: 'folder-1',
        fileType: 'canvas'
      })

      // Update permissions
      await updatePermissions('folder-1', {
        users: ['user-1'],
        permissions: ['read', 'write']
      })
    } catch (error) {
      console.error('Failed to perform operations:', error)
    }
  }

  return <button onClick={handleFileOperations}>Manage Files</button>
}