@mantis-core/nuqs

Reusable nuqs parsers and URL-state helpers for Mantis Core apps.

Docs

Full LLM-oriented documentation ships in the package tarball under docs/:

• docs/parsers.md — parseAsSuperJson, parseAsStringArray, createParseAsEnumArray.
• docs/use-data-table-query.md — useDataTableQuery: headless pagination/sorting/filtering state (local useState or nuqs URL sync), paired with PaginatedTable from @mantis-core/ui.

Scope

• Parser factories that can be shared across apps.
• Serialization/deserialization consistency via superjson.
• Headless table-state (pagination/sort/filters) with optional URL sync.

Out Of Scope

• Route-specific query contracts.
• Domain-specific URL semantics.
• Rendering — this package only owns state, not table/filter UI.

Public API

parseAsSuperJson: Parser<unknown>
parseAsStringArray: Parser<string[]>
createParseAsEnumArray<T extends string>(allowedValues: readonly T[]): Parser<T[]>

function useDataTableQuery<F extends Record<string, FilterDescriptor> = Record<string, never>>(
  options?: UseDataTableQueryOptions<F>,
): DataTableQuery<F>;

type FilterDescriptor =
  | { kind: "text"; default?: string }
  | { kind: "enum"; values: readonly string[]; default?: string[] }
  | { kind: "stringArray"; default?: string[] }
  | { kind: "json"; default?: unknown };

interface UseDataTableQueryOptions<F> {
  filters?: F;
  defaultPageSize?: number;   // default: 10
  defaultSort?: { field: string; order: 1 | -1 } | null; // default: null
  multiSort?: boolean;        // default: false
  urlSync?: boolean | { history?: "push" | "replace"; shallow?: boolean; keyPrefix?: string }; // default: false
}

See docs/use-data-table-query.md for the full DataTableQuery<F> return shape (page, sort, filters, setPage, toggleSort, queryParams, …).

Usage Example

import { parseAsStringArray, createParseAsEnumArray } from "@mantis-core/nuqs";

const parseStatusArray = createParseAsEnumArray(["draft", "published"] as const);

const tags = parseAsStringArray.parse('["house","blog"]');
const statuses = parseStatusArray.parse('["draft","invalid"]');
// statuses -> ["draft"]

"use client";

import { useDataTableQuery } from "@mantis-core/nuqs";

function Example() {
  const table = useDataTableQuery({
    filters: { search: { kind: "text", default: "" } },
    urlSync: true, // deep-linkable page/sort/filters
  });

  return (
    <input
      value={table.filters.search}
      onChange={(e) => table.setFilter("search", e.target.value)}
      placeholder="Search…"
    />
  );
}

Build

pnpm --filter @mantis-core/nuqs build
pnpm --filter @mantis-core/nuqs typecheck

Peer Dependencies

This package expects the consuming app to provide react. Pairing useDataTableQuery's output with a table component (e.g. PaginatedTable from @mantis-core/ui) additionally requires that package.