feat(tables): add row TTL expiration

Author: j15z

apps/docs/content/docs/en/tables/index.mdx

@@ -24,13 +24,16 @@ Every column has a type, which decides how its values are stored and validated.
 | **Currency** | An amount in a currency you pick per column | `$1,234.56` |
 | **Boolean** | `true` or `false` | `true` |
 | **Date** | A date | `2026-03-16` |
+| **TTL** | A row expiration date, stored as Unix epoch seconds | `2026-03-16 2:30 PM` |
 | **JSON** | An object or array | `{ "tier": "pro" }` |
 | **Select** | One of a fixed set of options, or several | `Pro` |
 
 Types are enforced as you enter values, so a Number column only takes numbers.
 
 A Currency column stores a plain number and renders it in the currency you choose for that column, so filters, sorts, and exports all see the amount itself. Changing a column's currency relabels it — it does not convert the amounts.
 
+A table can have one TTL column. Adding it enables row expiration; rows with a non-empty TTL value are deleted after that time passes. Deleting the TTL column disables expiration for the table. TTL cells use the date editor, while APIs and workflows read and write integer Unix epoch seconds, matching DynamoDB TTL.
+
 ## Editing a table
 
 Open the **Tables** section in the sidebar and click **New table** to create one. Add columns from the column header, type into a cell to edit it, and paste rows from a spreadsheet to bulk-load. Filter and sort from the toolbar without changing the underlying data. The editor has full keyboard support; see [keyboard shortcuts](/keyboard-shortcuts).

apps/sim/app/api/cron/cleanup-table-row-ttl/route.test.ts

@@ -0,0 +1,88 @@
+/**
+ * @vitest-environment node
+ */
+import { createMockRequest } from '@sim/testing'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockEnqueue, mockGetJobQueue, mockVerifyCronAuth } = vi.hoisted(() => ({
+  mockEnqueue: vi.fn(),
+  mockGetJobQueue: vi.fn(),
+  mockVerifyCronAuth: vi.fn(),
+}))
+
+vi.mock('@/lib/auth/internal', () => ({ verifyCronAuth: mockVerifyCronAuth }))
+vi.mock('@/lib/core/async-jobs', () => ({ getJobQueue: mockGetJobQueue }))
+
+import { GET } from '@/app/api/cron/cleanup-table-row-ttl/route'
+
+describe('table row TTL cleanup route', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-08-22T17:12:00Z'))
+    mockVerifyCronAuth.mockReturnValue(null)
+    mockEnqueue.mockResolvedValue('job-ttl-1')
+    mockGetJobQueue.mockResolvedValue({ enqueue: mockEnqueue })
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('enqueues one serialized cleanup job', async () => {
+    const response = await GET(
+      createMockRequest(
+        'GET',
+        undefined,
+        {},
+        'http://localhost:3000/api/cron/cleanup-table-row-ttl'
+      )
+    )
+
+    expect(response.status).toBe(200)
+    await expect(response.json()).resolves.toEqual({ triggered: true, jobId: 'job-ttl-1' })
+    expect(mockEnqueue).toHaveBeenCalledWith(
+      'cleanup-table-row-ttl',
+      {},
+      expect.objectContaining({
+        maxAttempts: 1,
+        jobId: 'cleanup-table-row-ttl:5958062',
+        concurrencyKey: 'cleanup:table-row-ttl',
+        concurrencyLimit: 1,
+        runner: expect.any(Function),
+      })
+    )
+  })
+
+  it('deduplicates retries within the same five-minute schedule window', async () => {
+    const request = () =>
+      createMockRequest(
+        'GET',
+        undefined,
+        {},
+        'http://localhost:3000/api/cron/cleanup-table-row-ttl'
+      )
+
+    await GET(request())
+    vi.advanceTimersByTime(2 * 60 * 1000)
+    await GET(request())
+
+    expect(mockEnqueue.mock.calls[0]?.[2]?.jobId).toBe(mockEnqueue.mock.calls[1]?.[2]?.jobId)
+  })
+
+  it('returns the cron auth refusal without touching the queue', async () => {
+    mockVerifyCronAuth.mockReturnValue(new Response(null, { status: 401 }))
+
+    const response = await GET(
+      createMockRequest(
+        'GET',
+        undefined,
+        {},
+        'http://localhost:3000/api/cron/cleanup-table-row-ttl'
+      )
+    )
+
+    expect(response.status).toBe(401)
+    expect(mockGetJobQueue).not.toHaveBeenCalled()
+  })
+})

apps/sim/app/api/cron/cleanup-table-row-ttl/route.ts

@@ -0,0 +1,41 @@
+import { createLogger } from '@sim/logger'
+import { type NextRequest, NextResponse } from 'next/server'
+import { verifyCronAuth } from '@/lib/auth/internal'
+import { getJobQueue } from '@/lib/core/async-jobs'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+
+export const dynamic = 'force-dynamic'
+
+const logger = createLogger('CleanupTableRowTtlApi')
+const TTL_CLEANUP_INTERVAL_MS = 5 * 60 * 1000
+
+export const GET = withRouteHandler(async (request: NextRequest) => {
+  try {
+    const authError = verifyCronAuth(request, 'table row TTL cleanup')
+    if (authError) return authError
+
+    const queue = await getJobQueue()
+    const scheduleWindow = Math.floor(Date.now() / TTL_CLEANUP_INTERVAL_MS)
+    const jobId = await queue.enqueue(
+      'cleanup-table-row-ttl',
+      {},
+      {
+        maxAttempts: 1,
+        jobId: `cleanup-table-row-ttl:${scheduleWindow}`,
+        name: 'Table row TTL cleanup',
+        concurrencyKey: 'cleanup:table-row-ttl',
+        concurrencyLimit: 1,
+        runner: async (_payload, signal) => {
+          const { runCleanupTableRowTtl } = await import('@/background/cleanup-table-row-ttl')
+          return runCleanupTableRowTtl(signal)
+        },
+      }
+    )
+
+    logger.info('Table row TTL cleanup dispatched', { jobId })
+    return NextResponse.json({ triggered: true, jobId })
+  } catch (error) {
+    logger.error('Failed to dispatch table row TTL cleanup', { error })
+    return NextResponse.json({ error: 'Failed to dispatch table row TTL cleanup' }, { status: 500 })
+  }
+})

apps/sim/app/workspace/[workspaceId]/tables/[tableId]/components/column-config-sidebar/column-types.test.ts

@@ -0,0 +1,30 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import type { ColumnDefinition } from '@/lib/table'
+import { columnTypeOptionsForTable } from './column-types'
+
+describe('columnTypeOptionsForTable', () => {
+  const ttlColumn: ColumnDefinition = { name: 'expires_at', type: 'ttl' }
+
+  it('disables TTL with an explanation when the table already has one', () => {
+    const availableTtl = columnTypeOptionsForTable([{ name: 'name', type: 'string' }]).find(
+      (option) => option.type === 'ttl'
+    )
+    const unavailableTtl = columnTypeOptionsForTable([ttlColumn]).find(
+      (option) => option.type === 'ttl'
+    )
+
+    expect(availableTtl?.disabledReason).toBeUndefined()
+    expect(unavailableTtl?.disabledReason).toBe('Only one TTL column allowed per table')
+  })
+
+  it('keeps TTL enabled while editing the existing TTL column', () => {
+    const ttlOption = columnTypeOptionsForTable([ttlColumn], ttlColumn).find(
+      (option) => option.type === 'ttl'
+    )
+
+    expect(ttlOption?.disabledReason).toBeUndefined()
+  })
+})

apps/sim/app/workspace/[workspaceId]/tables/[tableId]/components/row-modal/row-modal.tsx

@@ -251,7 +251,7 @@ function ColumnField({ column, value, onChange }: ColumnFieldProps) {
         required={column.required}
         hint={hint}
         mono
-        value={formatValueForInput(value, column.type)}
+        value={formatValueForInput(value, column.type, timeZone)}
         onChange={onChange}
         placeholder='{"key": "value"}'
         rows={4}
@@ -260,7 +260,7 @@ function ColumnField({ column, value, onChange }: ColumnFieldProps) {
   }
 
   if (definition.editor === 'date') {
-    const parts = dateValueToLocalParts(formatValueForInput(value, 'date'))
+    const parts = dateValueToLocalParts(formatValueForInput(value, column.type, timeZone))
     return (
       <ChipModalField type='custom' title={title} required={column.required} hint={hint}>
         <div className='flex items-center gap-2'>
@@ -306,7 +306,7 @@ function ColumnField({ column, value, onChange }: ColumnFieldProps) {
       inputType={
         definition.inputMode === 'decimal' && !definition.acceptsFormattedInput ? 'number' : 'text'
       }
-      value={formatValueForInput(value, column.type)}
+      value={formatValueForInput(value, column.type, timeZone)}
       onChange={onChange}
       placeholder={`Enter ${column.name}`}
     />

apps/sim/app/workspace/[workspaceId]/tables/[tableId]/components/table-grid/cells/cell-content.tsx

@@ -13,6 +13,7 @@ interface CellContentProps {
   /** Current workspace id — lets string cells holding an in-workspace resource
    *  URL render as a tagged-resource chip instead of a plain external link. */
   workspaceId: string
+  timeZone: string
   isEditing: boolean
   initialCharacter?: string | null
   onSave: (value: unknown, reason: SaveReason) => void
@@ -38,6 +39,7 @@ export function CellContent({
   exec,
   column,
   workspaceId,
+  timeZone,
   isEditing,
   initialCharacter,
   onSave,
@@ -52,6 +54,7 @@ export function CellContent({
     waitingOnLabels,
     isEnrichmentOutput,
     currentWorkspaceId: workspaceId,
+    timeZone,
   })
 
   return (

apps/sim/app/workspace/[workspaceId]/tables/[tableId]/components/table-grid/cells/cell-render.test.ts

@@ -0,0 +1,32 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { resolveCellRender } from '@/app/workspace/[workspaceId]/tables/[tableId]/components/table-grid/cells/cell-render'
+import type { DisplayColumn } from '@/app/workspace/[workspaceId]/tables/[tableId]/components/table-grid/types'
+
+function column(type: DisplayColumn['type']): DisplayColumn {
+  return {
+    key: 'expires_at',
+    name: 'expires_at',
+    type,
+    groupSize: 1,
+    groupStartColIndex: 0,
+    headerLabel: 'expires_at',
+    isGroupStart: true,
+  }
+}
+
+describe('resolveCellRender', () => {
+  it('renders TTL epoch seconds through the date presentation', () => {
+    expect(
+      resolveCellRender({
+        value: 1_700_000_000,
+        exec: undefined,
+        column: column('ttl'),
+        waitingOnLabels: undefined,
+        timeZone: 'America/New_York',
+      })
+    ).toEqual({ kind: 'date', text: '2023-11-14T17:13:20-05:00' })
+  })
+})

apps/sim/app/workspace/[workspaceId]/tables/[tableId]/components/table-grid/cells/cell-render.tsx

@@ -53,6 +53,8 @@ interface ResolveCellRenderInput {
   /** Current workspace id — a URL pointing to a resource in this workspace
    *  renders as a tagged-resource chip rather than a plain external link. */
   currentWorkspaceId?: string
+  /** Effective viewer timezone for instant-like column presentations. */
+  timeZone?: string
 }
 
 export function resolveCellRender({
@@ -62,6 +64,7 @@ export function resolveCellRender({
   waitingOnLabels,
   isEnrichmentOutput,
   currentWorkspaceId,
+  timeZone,
 }: ResolveCellRenderInput): CellRenderKind {
   const isNull = value === null || value === undefined
   const isEmpty = isNull || value === ''
@@ -137,7 +140,10 @@ export function resolveCellRender({
     return { kind: 'text', text: columnTypeOf(column).formatForDisplay(value, column) }
   }
   if (column.type === 'json') return { kind: 'json', text: JSON.stringify(value) }
-  if (column.type === 'date') return { kind: 'date', text: String(value) }
+  const definition = columnTypeOf(column)
+  if (definition.editor === 'date') {
+    return { kind: 'date', text: definition.formatForInput(value, column, { timezone: timeZone }) }
+  }
   if (column.type === 'string') {
     const text = stringifyValue(value)
     return resolveLinkKind(text, currentWorkspaceId) ?? { kind: 'text', text }

apps/sim/app/workspace/[workspaceId]/tables/[tableId]/components/table-grid/cells/inline-editors.tsx

@@ -70,7 +70,7 @@ function InlineDateEditor({
   const popoverPointerAtRef = useRef(0)
   const timeZone = useTimezone()
 
-  const storedValue = formatValueForInput(value, column.type)
+  const storedValue = formatValueForInput(value, column.type, timeZone)
   const initialDraft =
     initialCharacter !== undefined
       ? initialCharacter
@@ -115,7 +115,7 @@ function InlineDateEditor({
       // silently shifting the instant of a value someone else wrote.
       if (storageVal === undefined && initialCharacter === undefined && current === initialDraft) {
         doneRef.current = true
-        onSave(storedValue || null, reason)
+        onSave(storedValue ? cleanCellValue(storedValue, column, timeZone) : null, reason)
         return
       }
       const raw = storageVal ?? displayToStorage(current, timeZone) ?? current
@@ -132,9 +132,9 @@ function InlineDateEditor({
         return
       }
       doneRef.current = true
-      onSave(raw || null, reason)
+      onSave(raw ? cleanCellValue(raw, column, timeZone) : null, reason)
     },
-    [invalid, onSave, onCancel, timeZone, initialDraft, initialCharacter, storedValue]
+    [invalid, onSave, onCancel, timeZone, initialDraft, initialCharacter, storedValue, column]
   )
 
   const handleKeyDown = useCallback(

apps/sim/app/workspace/[workspaceId]/tables/[tableId]/components/table-grid/data-row.tsx

@@ -26,6 +26,8 @@ export interface DataRowProps {
   /** Current workspace id — forwarded to cells so in-workspace resource URLs
    *  render as tagged-resource chips. */
   workspaceId: string
+  /** Effective viewer timezone used to render TTL instants. */
+  timeZone: string
   rowIndex: number
   isFirstRow: boolean
   editingColumnName: string | null
@@ -114,6 +116,7 @@ function dataRowPropsAreEqual(prev: DataRowProps, next: DataRowProps): boolean {
     prev.row !== next.row ||
     prev.columns !== next.columns ||
     prev.workspaceId !== next.workspaceId ||
+    prev.timeZone !== next.timeZone ||
     prev.rowIndex !== next.rowIndex ||
     prev.isFirstRow !== next.isFirstRow ||
     prev.editingColumnName !== next.editingColumnName ||
@@ -161,6 +164,7 @@ export const DataRow = React.memo(function DataRow({
   row,
   columns,
   workspaceId,
+  timeZone,
   rowIndex,
   isFirstRow,
   editingColumnName,
@@ -396,6 +400,7 @@ export const DataRow = React.memo(function DataRow({
             <div className={CELL_CONTENT}>
               <CellContent
                 workspaceId={workspaceId}
+                timeZone={timeZone}
                 value={
                   pendingCellValue && column.key in pendingCellValue
                     ? pendingCellValue[column.key]