React

pnpm add @dudousxd/nestjs-filter-react @dudousxd/nestjs-filter-client

// src/user.filter.ts
import { Injectable } from '@nestjs/common';
import { Filterable } from '@dudousxd/nestjs-filter';
import { MikroOrmFilter } from '@dudousxd/nestjs-filter-mikro-orm';
import { User } from './user.entity.js';

// Auto-fields is on by default, so `name`, `email`, `role.name`, and
// `status` are queryable with zero @FilterFor methods — see Filter Classes.
@Injectable()
@Filterable({ entity: User })
export class UserFilter extends MikroOrmFilter<User> {}

// src/users.controller.ts
import { Controller, Post } from '@nestjs/common';
import { ApplyFilter } from '@dudousxd/nestjs-filter';
import type { QueryBuilder } from '@mikro-orm/core';
import { UserFilter } from './user.filter.js';
import { User } from './user.entity.js';

@Controller('users')
export class UsersController {
  @Post('search')
  search(@ApplyFilter(UserFilter, { source: 'body' }) qb: QueryBuilder<User>) {
    return qb.getResultList();
  }
}

// generated/api.ts (excerpt, emitted by nestjs-codegen)
import { api } from './generated/api.js';

// api.users.search.filterQuery() returns a TypedFilterQueryBuilder restricted
// to this endpoint's fields ('name' | 'email' | 'role.name' | 'status' | ...)

// src/UsersTable.tsx
import { useFilterTable } from '@dudousxd/nestjs-filter-react/nuqs';
import { useQuery } from '@tanstack/react-query';
import { api } from './generated/api.js';

export function UsersTable() {
  const t = useFilterTable(api.users.search, {
    include: ['role'],
    sort: { email: 'asc' },
    pageSize: 20,
    search: { fields: ['name', 'email'], op: 'iContains', debounce: 300 },
    filters: { role: 'role.name', status: { field: 'status', op: 'equals' } },
  });

  const { data, isLoading } = useQuery(t.queryOptions());

  return (
    <div>
      <input
        placeholder="Search name or email…"
        value={t.search}
        onChange={(e) => t.setSearch(e.target.value)}
      />

      <select
        value={t.filters.status ?? ''}
        onChange={(e) => t.setFilter('status', e.target.value || null)}
      >
        <option value="">All statuses</option>
        <option value="active">Active</option>
        <option value="suspended">Suspended</option>
      </select>

      <button onClick={t.reset}>Clear filters</button>

      {isLoading ? (
        <p>Loading…</p>
      ) : (
        <table>
          <thead>
            <tr>
              <th>Name</th>
              <th>Email</th>
              <th>Role</th>
              <th>Status</th>
            </tr>
          </thead>
          <tbody>
            {data?.items.map((user) => (
              <tr key={user.id}>
                <td>{user.name}</td>
                <td>{user.email}</td>
                <td>{user.role.name}</td>
                <td>{user.status}</td>
              </tr>
            ))}
          </tbody>
        </table>
      )}

      <button disabled={t.page <= 1} onClick={() => t.setPage(t.page - 1)}>
        Previous
      </button>
      <span>Page {t.page}</span>
      <button onClick={() => t.setPage(t.page + 1)}>Next</button>
    </div>
  );
}

import { useFilterTable } from '@dudousxd/nestjs-filter-react/nuqs';

function useFilterTable<Fields extends string, Body, QueryOpts>(
  route: {
    filterQuery: () => TypedFilterQueryBuilder<Fields>;
    queryOptions: (body: Body) => QueryOpts;
  },
  config: FilterTableConfig<Fields>,
): FilterTable<QueryOpts>;

import { useFilterQuery } from '@dudousxd/nestjs-filter-react';

function useFilterQuery<Builder extends ReactiveFilterBuilder>(
  factory: () => Builder,
  init?: (builder: Builder) => void,
): readonly [Builder, FilterQueryResult];

interface ReactiveFilterBuilder {
  subscribe(listener: () => void): () => void;
  getSnapshot(): FilterQueryResult;
}

import { useFilterQuery } from '@dudousxd/nestjs-filter-react';
import { useQuery } from '@tanstack/react-query';
import { api } from './generated/api.js';

function RoleFilterableTable() {
  const [qb, body] = useFilterQuery(api.users.search.filterQuery, (builder) => {
    builder.include('role').sort('email', 'asc').page(0, 20);
  });

  const { data } = useQuery(api.users.search.queryOptions(body));

  return (
    <select onChange={(e) => qb.where('role.name', 'equals', e.target.value)}>
      <option value="ADMIN">Admin</option>
      <option value="EDITOR">Editor</option>
    </select>
  );
}

const [qb, body] = useFilterQuery(api.users.search.filterQuery);

// `route.queryOptions(body)` (codegen) already threads `body` into the queryKey —
// spread it straight into useQuery:
const { data } = useQuery(api.users.search.queryOptions(body));

// Hand-rolled, without codegen:
const { data } = useQuery({
  queryKey: ['users', 'search', body] as const,
  queryFn: () => fetchUsers(body),
});

import { useFilterQueryUrl } from '@dudousxd/nestjs-filter-react/nuqs';

function useFilterQueryUrl<Builder extends ResettableFilterBuilder, KeyMap extends UseQueryStatesKeysMap>(
  factory: () => Builder,
  config: UseFilterQueryUrlConfig<Builder, KeyMap>,
): readonly [Builder, FilterQueryResult, Values<KeyMap>, SetValues<KeyMap>];

import { useFilterQueryUrl } from '@dudousxd/nestjs-filter-react/nuqs';
import { parseAsInteger, parseAsString } from 'nuqs';
import { api } from './generated/api.js';

function UsersTable() {
  const [qb, body, values, setValues] = useFilterQueryUrl(api.users.search.filterQuery, {
    parsers: {
      q: parseAsString.withDefault(''),
      role: parseAsString,
      page: parseAsInteger.withDefault(1),
    },
    apply: (builder, { q, role, page }) => {
      builder.include('role').sort('email', 'asc').page(page - 1, 20);
      if (role) builder.where('role.name', 'equals', role);
      const term = q.trim();
      if (term) {
        builder.or((group) => {
          group.where('name', 'iContains', term);
          group.where('email', 'iContains', term);
        });
      }
    },
  });

  const { data } = useQuery(api.users.search.queryOptions(body));

  return (
    <input value={values.q} onChange={(e) => setValues({ q: e.target.value, page: 1 })} />
  );
}

import { filterQuery } from '@dudousxd/nestjs-filter-client';
import { applyTanstackTableState } from '@dudousxd/nestjs-filter-client/tanstack';
import { useFilterQuery } from '@dudousxd/nestjs-filter-react';
import { useQuery } from '@tanstack/react-query';
import { getCoreRowModel, useReactTable } from '@tanstack/react-table';

function TanstackDrivenTable({ users, columns }: { users: User[]; columns: ColumnDef<User>[] }) {
  const [qb] = useFilterQuery(filterQuery);
  const table = useReactTable({
    data: users,
    columns,
    getCoreRowModel: getCoreRowModel(),
    manualFiltering: true,
    manualSorting: true,
    manualPagination: true,
  });

  const body = applyTanstackTableState(qb, {
    columnFilters: table.getState().columnFilters,
    sorting: table.getState().sorting,
    pagination: table.getState().pagination,
  }).build();

  const { data } = useQuery({ queryKey: ['table', body] as const, queryFn: () => fetchUsers(body) });
}