@insurup/table-adapter-core

Framework-agnostic TanStack Table adapter for @insurup/sdk.

This is the core package that provides the table adapter logic. For framework-specific bindings, see:

• @insurup/table-adapter-react - React bindings
• @insurup/table-adapter-vue - Vue bindings
• @insurup/table-adapter-svelte - Svelte bindings

Features

• 🚀 Framework agnostic - works with React, Vue, Svelte, Solid, or vanilla JS
• 🔄 Built-in caching via @tanstack/query-core
• 📝 Type-safe columns with SDK field autocompletion
• 📄 Cursor pagination handled internally

Installation

npm install @insurup/table-adapter-core @insurup/sdk

bun add @insurup/table-adapter-core @insurup/sdk

Quick Start

import { createCustomerTable } from '@insurup/table-adapter-core';
import { DefaultInsurUpClient } from '@insurup/sdk';

const client = new DefaultInsurUpClient({
  baseUrl: 'https://api.insurup.com',
  tokenProvider: () => token,
});

// Create table adapter with builder API
const customerTable = createCustomerTable({
  columns: (col) => [
    col.id({ header: 'ID' }),
    col.name({ header: 'Name', sortable: true }),
    col.primaryEmail('Email'),
    col.createdAt({ header: 'Created', sortable: true }),
  ],
  fetch: (options) => client.customers.getCustomers(options),
  pageSize: 10,
  autoFetch: true,
  // Sorting is managed by the consumer via tableOptions.state.sorting
  tableOptions: {
    state: {
      sorting: [{ id: 'createdAt', desc: true }],
    },
    onSortingChange: (updater) => {
      // Update your sorting state here
    },
  },
});

// Subscribe to state changes
const unsubscribe = customerTable.subscribe(() => {
  const state = customerTable.getSnapshot();
  console.log('Data:', state.rows);
});

// Get TanStack Table options
const tableOptions = customerTable.getTableOptions();

// Cleanup when done
customerTable.destroy();

API

createCustomerTable

Creates a customer table adapter with built-in caching and state management.

const customerTable = createCustomerTable({
  // Required
  columns: (col) => [...],            // Builder function for columns
  fetch: (options) => Promise,        // SDK fetch function

  // Optional
  pageSize?: number,                  // Items per page (default: 20)
  defaultFilter?: UnifiedFilterInput, // Initial filter (see "Filter and search" below)
  staleTime?: number,                 // Cache stale time in ms (default: 30000)
  gcTime?: number,                    // Garbage collection time in ms (default: 300000)
  autoFetch?: boolean,                // Fetch on creation (default: false)

  // Callbacks
  onError?: (error) => void,          // Called on fetch error
  onSuccess?: (data) => void,         // Called on fetch success
  onSettled?: (data, error) => void   // Called after fetch completes
});

Filter and search

The adapter exposes a single unified filter API. There is no separate setSearch — every field in setFilter is either a regular filter or, when carrying the $search: true marker, a server-side search clause.

table.setFilter({
  // Regular filter — routed to the server's `filter:` slot
  type: { eq: CustomerType.Individual },
  birthDate: { gte: '1990-01-01' },

  // Search — `$search: true` promotes the field to the server's `search:` slot
  // and unlocks the search-only operators (`textSearch`, `wildcard`, `autocomplete`)
  name: { $search: true, textSearch: 'ali' },

  // Long form with relevance score
  identityNumber: {
    $search: true,
    textSearch: { value: '123', score: { boost: 2 } },
  },
});

String shorthand is normalized by the SDK: textSearch: 'ali' is equivalent to textSearch: { value: 'ali' }. Likewise in: ['a','b'] becomes { values: ['a','b'] }.

and / or combinators are supported recursively. Each combinator item is split per-bucket — and semantics are preserved; an or whose items mix filter and search keys becomes an implicit AND at the wire (server combines its filter: and search: slots with AND). Keep each or item homogeneous if intent matters.

To introspect what's filterable / searchable on an entity at runtime, read the generated meta:

import { QueryCustomerModelMeta } from '@insurup/sdk';

QueryCustomerModelMeta.name.filterable; // true
QueryCustomerModelMeta.name.searchable; // true
QueryCustomerModelMeta.name.filterOperators; // ['eq','neq','contains','notContains', ...]
QueryCustomerModelMeta.name.searchOperators; // ['eq','neq','textSearch','wildcard', ...]

Column Builder

The columns option receives a builder with methods for each field:

columns: (col) => [
  // Simple - uses field name as header
  col.id(),

  // With custom header
  col.name('Customer Name'),

  // With full config
  col.type({
    header: 'Type',
    sortable: true,
    render: (value) => (value === 'Individual' ? '👤' : '🏢'),
  }),

  // Computed column using multiple fields
  col.computed({
    uses: ['cityText', 'districtText'] as const,
    header: 'Location',
    render: (row) => `${row.cityText}, ${row.districtText}`,
  }),
];

Adapter Methods

| Method | Description | | --------------------- | ------------------------------------------------------------------------- | | columns | TanStack ColumnDef[] (readonly) | | getState() | Current state: { rows, rowCount, pageCount, isLoading, error, ... } | | getTableOptions() | Complete TanStack Table options (includes data, columns, getCoreRowModel) | | subscribe(listener) | Subscribe to state changes (for useSyncExternalStore) | | getSnapshot() | Get current state snapshot (for useSyncExternalStore) | | getServerSnapshot() | Get server snapshot for SSR (for useSyncExternalStore) | | fetch() | Trigger a manual fetch | | invalidate() | Invalidate cache and refetch | | refetch({ force }) | Refetch with optional cache bypass | | destroy() | Clean up resources (call on unmount) | | setFilter(filter) | Set unified filter (filter + $search-marked entries) and refetch | | getFilter() | Return the current unified filter | | clearFilter() | Clear filter and refetch | | setPageSize(size) | Change page size |

AdapterState

State returned by getState() and getSnapshot().

interface AdapterState<TEntity> {
  rows: TEntity[]; // Current page data
  rowCount: number; // Total records
  pageCount: number; // Total pages
  isLoading: boolean; // Initial loading
  isFetching: boolean; // Any fetch in progress
  error: Error | null; // Error if any
  isError: boolean;
  isSuccess: boolean;
}

Pagination Limitations

This adapter uses cursor-based pagination, which only supports sequential navigation (previous/next). Jumping to arbitrary pages (e.g., page 1 → page 5) is not supported.

The getTableOptions() method returns paginationMode: 'cursor' to signal this limitation.

License

MIT