refactor(workspaces): store workspace pins in pinned_item, not user settings

Workspace pins were a jsonb array on the settings row, replaced wholesale on
every toggle. That shape is what forced the write serialization in 53ee94f:
two overlapping toggles each sent the entire list, so the one that landed last
won regardless of which the user clicked last.

pinned_item is the canonical pinning table and its resource_type is plain text
precisely so kinds can be added without a migration, so `workspace` joins it as
a sixth kind. A pin is now one row: pinning inserts, unpinning deletes, and two
toggles touch different rows and cannot overwrite each other. The serialization,
the outstanding-write counter, the settings column, and its migration all go
away, and deleting a workspace now cascades its pins.

Reads stay on the /api/workspaces payload — the switcher needs the pins *of*
every workspace, not the pins *inside* one — so the sidebar prefetch still
hydrates them and pinned-first ordering is correct on first paint.

Author: waleedlatif1

apps/sim/app/workspace/[workspaceId]/w/components/sidebar/hooks/use-workspace-management.ts

@@ -117,19 +117,13 @@ export function useWorkspaceManagement({
   const pinnedWorkspaceIdsRef = useRef<Set<string>>(pinnedWorkspaceIds)
   pinnedWorkspaceIdsRef.current = pinnedWorkspaceIds
 
-  /**
-   * Reads the current pins through a ref so the callback identity stays stable for
-   * the memoized switcher, and derives the whole next list here — the settings
-   * endpoint replaces it wholesale, and this hook is the one place that already
-   * owns the set.
-   */
+  /** Reads the current pins through a ref so the callback identity stays stable for the memoized switcher. */
   const toggleWorkspacePin = useCallback(
     (workspaceId: string) => {
-      const current = pinnedWorkspaceIdsRef.current
-      const pinnedWorkspaceIds = current.has(workspaceId)
-        ? [...current].filter((id) => id !== workspaceId)
-        : [...current, workspaceId]
-      toggleWorkspacePinMutate({ pinnedWorkspaceIds })
+      toggleWorkspacePinMutate({
+        workspaceId,
+        pinned: !pinnedWorkspaceIdsRef.current.has(workspaceId),
+      })
     },
     [toggleWorkspacePinMutate]
   )

apps/sim/hooks/queries/workspace.test.tsx

@@ -15,6 +15,8 @@ vi.mock('@/lib/api/client/request', () => ({
   requestJson: mockRequestJson,
 }))
 
+import { ApiClientError } from '@/lib/api/client/errors'
+import { createPinnedItemContract, deletePinnedItemContract } from '@/lib/api/contracts'
 import { useToggleWorkspacePin, workspaceKeys } from '@/hooks/queries/workspace'
 
 /** Trees rendered by a test, torn down in afterEach so observers do not leak across tests. */
@@ -62,6 +64,20 @@ async function flush() {
   })
 }
 
+function seedList(queryClient: QueryClient, pinnedWorkspaceIds: string[]) {
+  queryClient.setQueryData(workspaceKeys.list('active'), {
+    workspaces: [],
+    lastActiveWorkspaceId: null,
+    pinnedWorkspaceIds,
+    creationPolicy: null,
+  })
+}
+
+function readPins(queryClient: QueryClient): string[] | undefined {
+  return queryClient.getQueryData<{ pinnedWorkspaceIds: string[] }>(workspaceKeys.list('active'))
+    ?.pinnedWorkspaceIds
+}
+
 afterEach(() => {
   act(() => {
     for (const root of mountedRoots.splice(0)) root.unmount()
@@ -73,96 +89,98 @@ beforeEach(() => {
 })
 
 describe('useToggleWorkspacePin', () => {
-  /**
-   * Each request carries the whole pin list, so overlapping writes that the network
-   * delivers out of order would let the earlier click win. The hook chains them, so
-   * the second request must not be issued until the first has resolved.
-   */
-  it('serializes overlapping writes so the last click is what persists', async () => {
-    const resolvers: Array<() => void> = []
-    mockRequestJson.mockImplementation(
-      () =>
-        new Promise<{ success: true }>((resolve) => {
-          resolvers.push(() => resolve({ success: true }))
-        })
-    )
-
-    const { getResult } = renderHookWithClient(() => useToggleWorkspacePin())
+  it('pins by creating a row addressed to the workspace itself', async () => {
+    mockRequestJson.mockResolvedValue({ pinnedItem: {} })
+    const { getResult, queryClient } = renderHookWithClient(() => useToggleWorkspacePin())
+    seedList(queryClient, [])
 
     act(() => {
-      getResult().mutate({ pinnedWorkspaceIds: ['ws-a'] })
-      getResult().mutate({ pinnedWorkspaceIds: ['ws-a', 'ws-b'] })
+      getResult().mutate({ workspaceId: 'ws-a', pinned: true })
     })
     await flush()
 
-    // Only the first write is on the wire; the second is queued behind it.
-    expect(mockRequestJson).toHaveBeenCalledOnce()
-    expect(mockRequestJson.mock.calls[0][1]).toMatchObject({
-      body: { pinnedWorkspaceIds: ['ws-a'] },
+    expect(mockRequestJson).toHaveBeenCalledWith(createPinnedItemContract, {
+      body: { workspaceId: 'ws-a', resourceType: 'workspace', resourceId: 'ws-a' },
     })
+  })
+
+  it('unpins by deleting that row', async () => {
+    mockRequestJson.mockResolvedValue({ success: true })
+    const { getResult, queryClient } = renderHookWithClient(() => useToggleWorkspacePin())
+    seedList(queryClient, ['ws-a'])
 
-    act(() => resolvers[0]())
+    act(() => {
+      getResult().mutate({ workspaceId: 'ws-a', pinned: false })
+    })
     await flush()
 
-    expect(mockRequestJson).toHaveBeenCalledTimes(2)
-    expect(mockRequestJson.mock.calls[1][1]).toMatchObject({
-      body: { pinnedWorkspaceIds: ['ws-a', 'ws-b'] },
+    expect(mockRequestJson).toHaveBeenCalledWith(deletePinnedItemContract, {
+      params: { resourceType: 'workspace', resourceId: 'ws-a' },
     })
+    expect(readPins(queryClient)).toEqual([])
   })
 
   /**
-   * Refetching between two queued writes would render the server's pre-second-write
-   * state and visibly bounce the row out of the pinned group and back.
+   * Two rapid toggles write different rows, so neither can overwrite the other and
+   * both survive regardless of the order the requests land in.
    */
-  it('reconciles only after the last queued write settles', async () => {
+  it('keeps both pins when two toggles overlap', async () => {
     const resolvers: Array<() => void> = []
     mockRequestJson.mockImplementation(
-      () =>
-        new Promise<{ success: true }>((resolve) => {
-          resolvers.push(() => resolve({ success: true }))
-        })
+      () => new Promise((resolve) => resolvers.push(() => resolve({ pinnedItem: {} })))
     )
-
     const { getResult, queryClient } = renderHookWithClient(() => useToggleWorkspacePin())
-    const invalidateSpy = vi.spyOn(queryClient, 'invalidateQueries')
+    seedList(queryClient, [])
 
     act(() => {
-      getResult().mutate({ pinnedWorkspaceIds: ['ws-a'] })
-      getResult().mutate({ pinnedWorkspaceIds: ['ws-a', 'ws-b'] })
+      getResult().mutate({ workspaceId: 'ws-a', pinned: true })
+      getResult().mutate({ workspaceId: 'ws-b', pinned: true })
     })
     await flush()
 
-    act(() => resolvers[0]())
+    expect(readPins(queryClient)).toEqual(['ws-a', 'ws-b'])
+
+    // Resolve out of order — the older request landing last must not undo the newer.
+    act(() => {
+      resolvers[1]()
+      resolvers[0]()
+    })
     await flush()
 
-    // First write settled, second still outstanding — nothing reconciled yet.
-    expect(invalidateSpy).not.toHaveBeenCalled()
+    const bodies = mockRequestJson.mock.calls.map((call) => call[1].body.resourceId)
+    expect(bodies).toEqual(['ws-a', 'ws-b'])
+    expect(readPins(queryClient)).toEqual(['ws-a', 'ws-b'])
+  })
 
-    act(() => resolvers[1]())
+  /** Re-pinning an already-pinned workspace is the desired end state, not a failure. */
+  it('treats a 409 from a duplicate pin as success', async () => {
+    mockRequestJson.mockRejectedValue(
+      new ApiClientError({ status: 409, message: 'This item is already pinned', body: {} })
+    )
+    const { getResult, queryClient } = renderHookWithClient(() => useToggleWorkspacePin())
+    seedList(queryClient, [])
+
+    act(() => {
+      getResult().mutate({ workspaceId: 'ws-a', pinned: true })
+    })
     await flush()
 
-    expect(invalidateSpy).toHaveBeenCalledWith({ queryKey: workspaceKeys.lists() })
+    expect(getResult().isError).toBe(false)
+    expect(readPins(queryClient)).toEqual(['ws-a'])
   })
 
-  it('applies the pin optimistically before the request resolves', async () => {
-    mockRequestJson.mockImplementation(() => new Promise<{ success: true }>(() => {}))
-
+  it('rolls the optimistic pin back when the write fails', async () => {
+    mockRequestJson.mockRejectedValue(
+      new ApiClientError({ status: 500, message: 'boom', body: {} })
+    )
     const { getResult, queryClient } = renderHookWithClient(() => useToggleWorkspacePin())
-    queryClient.setQueryData(workspaceKeys.list('active'), {
-      workspaces: [],
-      lastActiveWorkspaceId: null,
-      pinnedWorkspaceIds: [],
-      creationPolicy: null,
-    })
+    seedList(queryClient, [])
 
     act(() => {
-      getResult().mutate({ pinnedWorkspaceIds: ['ws-a'] })
+      getResult().mutate({ workspaceId: 'ws-a', pinned: true })
     })
     await flush()
 
-    expect(
-      queryClient.getQueryData<{ pinnedWorkspaceIds: string[] }>(workspaceKeys.list('active'))
-        ?.pinnedWorkspaceIds
-    ).toEqual(['ws-a'])
+    expect(readPins(queryClient)).toEqual([])
   })
 })

apps/sim/hooks/queries/workspace.ts

@@ -1,17 +1,17 @@
-import { useRef } from 'react'
 import type { QueryClient } from '@tanstack/react-query'
 import { keepPreviousData, useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
 import { ApiClientError } from '@/lib/api/client/errors'
 import { requestJson } from '@/lib/api/client/request'
 import type { ContractBodyInput } from '@/lib/api/contracts'
 import {
+  createPinnedItemContract,
   createWorkspaceContract,
+  deletePinnedItemContract,
   deleteWorkspaceContract,
   getWorkspaceContract,
   getWorkspaceMembersContract,
   getWorkspacePermissionsContract,
   listWorkspacesContract,
-  updateUserSettingsContract,
   updateWorkspaceContract,
   type Workspace,
   type WorkspaceCreationPolicy,
@@ -20,6 +20,7 @@ import {
   type WorkspaceQueryScope,
   type WorkspacesResponse,
 } from '@/lib/api/contracts'
+import { pinnedItemKeys } from '@/hooks/queries/utils/pinned-item-keys'
 import {
   normalizeWorkspace,
   normalizeWorkspacesResponse,
@@ -119,62 +120,57 @@ export function usePinnedWorkspaceIds(enabled = true) {
 }
 
 /**
- * Persists the viewer's pinned workspaces.
+ * Pins or unpins a workspace in the switcher.
  *
- * The settings endpoint replaces the list wholesale, so the caller passes the full
- * set it wants rather than a delta. Optimistic because the pin re-sorts the list
- * under the user's cursor, where a round-trip delay reads as a dropped click.
+ * Writes one `pinned_item` row per pin, so a pin is an insert and an unpin is a
+ * delete. Two rapid toggles touch different rows and cannot overwrite each other,
+ * which is why nothing here serializes or debounces. Re-pinning an already-pinned
+ * workspace answers 409 and unpinning an absent pin is a no-op, so a duplicate
+ * click is idempotent rather than an error.
+ *
+ * Optimistic against the workspace list, because that is where the pins are read
+ * and the toggle re-sorts the row under the user's cursor.
  */
 export function useToggleWorkspacePin() {
   const queryClient = useQueryClient()
   const queryKey = workspaceKeys.list('active')
-  /**
-   * Tail of the in-flight write chain, and the count of toggles still outstanding.
-   * A burst of clicks is a burst of independent mutations, and this endpoint takes
-   * the whole list — so both are needed, for the two different ways that races.
-   */
-  const writeChainRef = useRef<Promise<unknown>>(Promise.resolve())
-  const outstandingRef = useRef(0)
 
   return useMutation({
-    /**
-     * Chained rather than fired concurrently: each request carries the complete
-     * list, so if two overlap and the network delivers them out of order the older
-     * one lands last and silently undoes the newer click. Serializing makes the
-     * final stored state the last one the user actually asked for.
-     */
-    mutationFn: ({ pinnedWorkspaceIds }: { pinnedWorkspaceIds: string[] }) => {
-      const send = writeChainRef.current
-        .catch(() => {})
-        .then(() => requestJson(updateUserSettingsContract, { body: { pinnedWorkspaceIds } }))
-      writeChainRef.current = send
-      return send
+    mutationFn: async ({ workspaceId, pinned }: { workspaceId: string; pinned: boolean }) => {
+      if (!pinned) {
+        await requestJson(deletePinnedItemContract, {
+          params: { resourceType: 'workspace', resourceId: workspaceId },
+        })
+        return
+      }
+      try {
+        await requestJson(createPinnedItemContract, {
+          body: { workspaceId, resourceType: 'workspace', resourceId: workspaceId },
+        })
+      } catch (error) {
+        /** Already pinned — the desired state, so not a failure to roll back. */
+        if (error instanceof ApiClientError && error.status === 409) return
+        throw error
+      }
     },
-    onMutate: async ({ pinnedWorkspaceIds }) => {
-      outstandingRef.current += 1
+    onMutate: async ({ workspaceId, pinned }) => {
       await queryClient.cancelQueries({ queryKey })
       const previous = queryClient.getQueryData<WorkspacesResponse>(queryKey)
-      queryClient.setQueryData<WorkspacesResponse>(queryKey, (old) =>
-        old ? { ...old, pinnedWorkspaceIds } : old
-      )
+      queryClient.setQueryData<WorkspacesResponse>(queryKey, (old) => {
+        if (!old) return old
+        const next = pinned
+          ? [...old.pinnedWorkspaceIds.filter((id) => id !== workspaceId), workspaceId]
+          : old.pinnedWorkspaceIds.filter((id) => id !== workspaceId)
+        return { ...old, pinnedWorkspaceIds: next }
+      })
       return { previous }
     },
     onError: (_error, _variables, context) => {
       if (context?.previous) queryClient.setQueryData(queryKey, context.previous)
     },
-    /**
-     * Reconciles only once the last queued write has settled. Refetching while
-     * another is still chained would render the server's pre-that-write state and
-     * visibly bounce the row out of the pinned group and back.
-     *
-     * Reconciling at all is not optional: the settings route answers
-     * `{ success: true }` even when the write throws, so a failed save never
-     * reaches `onError` and the optimistic list would otherwise stay wrong.
-     */
     onSettled: () => {
-      outstandingRef.current -= 1
-      if (outstandingRef.current > 0) return
       queryClient.invalidateQueries({ queryKey: workspaceKeys.lists() })
+      queryClient.invalidateQueries({ queryKey: pinnedItemKeys.all })
     },
   })
 }

apps/sim/lib/api/contracts/pinned-items.ts

@@ -11,13 +11,20 @@ import { defineRouteContract } from '@/lib/api/contracts/types'
  * namespace serves the file, knowledge-base, and table trees. It is separate from the
  * resource's own type, which is why a page listing folders alongside its resources resolves
  * two `usePinnedIds` sets.
+ *
+ * `workspace` pins the workspace itself, so its row stores `workspaceId === resourceId`.
+ * It is the one kind that is not read back through `GET /api/pinned-items`: the switcher
+ * needs every workspace the viewer pinned, not the pins inside one workspace, so those ids
+ * ride along on the `/api/workspaces` payload it already loads. Writes still go through the
+ * pin routes below, which is what keeps pin/unpin a per-row delta.
  */
 export const pinnedResourceTypeSchema = z.enum([
   'workflow',
   'file',
   'knowledge_base',
   'table',
   'folder',
+  'workspace',
 ])
 export type PinnedResourceType = z.output<typeof pinnedResourceTypeSchema>
 

apps/sim/lib/api/contracts/user.ts

@@ -114,16 +114,6 @@ export const updateUserSettingsBodySchema = z.object({
   timezone: ianaTimezoneSchema.nullable().optional(),
   /** Mirrors `userSettingsSchema.lastActiveWorkspaceId` so explicit `null` is accepted to clear the active workspace. */
   lastActiveWorkspaceId: z.string().nullable().optional(),
-  /**
-   * Replaces the pinned-workspace list wholesale — the client sends the full set
-   * it wants, so pinning and unpinning are the same write. Write-only: the list is
-   * read back on the `/api/workspaces` payload, alongside the workspaces it orders.
-   * Bounded because it is an unvalidated client-supplied array persisted verbatim.
-   */
-  pinnedWorkspaceIds: z
-    .array(z.string().min(1, 'Workspace ID cannot be empty').max(255, 'Workspace ID is too long'))
-    .max(200, 'Too many pinned workspaces')
-    .optional(),
 })
 
 export const getUserSettingsContract = defineRouteContract({

apps/sim/lib/api/contracts/workspaces.ts

@@ -193,10 +193,10 @@ export const listWorkspacesContract = defineRouteContract({
       workspaces: z.array(workspaceSchema),
       lastActiveWorkspaceId: z.string().nullable(),
       /**
-       * The viewer's pinned workspace ids as stored. May name workspaces absent
-       * from `workspaces` (archived, or access since removed) — clients look pins
-       * up per rendered workspace, so unmatched ids are inert, and preserving them
-       * is what keeps a pin from being dropped by the next wholesale write.
+       * Workspace ids the viewer pinned in the switcher, from `pinned_item`. May
+       * name workspaces absent from `workspaces` (archived, or access since
+       * removed); clients look pins up per rendered workspace, so unmatched ids
+       * are inert and the pin survives if access is restored.
        */
       pinnedWorkspaceIds: z.array(z.string()).default([]),
       creationPolicy: workspaceCreationPolicySchema.nullable(),