Getting Started

Overview

The Sort module provides schema-driven, multi-field sorting for Zod-typed data. It mirrors the architecture of the Filter module — define a Zod schema, provide compare functions, and let the library discover sortable fields automatically.

Here’s an interactive example:

Preview

Sort bynameagescore

AscDesc

name	age	score
Alice	30	88
Bob	25	95
Charlie	35	72
Diana	28	91
Eve	32	85
Frank	22	78
Grace	27	93
Henry	40	67

Code

import { createSorterSphere, presetSort } from "@fn-sphere/core";
import { useMemo, useState } from "react";
import { z } from "zod";
import { Table } from "../table";

const schema = z.object({
  name: z.string(),
  age: z.number(),
  score: z.number(),
});

type User = z.infer<typeof schema>;

const users: User[] = [
  { name: "Alice", age: 30, score: 88 },
  { name: "Bob", age: 25, score: 95 },
  { name: "Charlie", age: 35, score: 72 },
  { name: "Diana", age: 28, score: 91 },
  { name: "Eve", age: 32, score: 85 },
  { name: "Frank", age: 22, score: 78 },
  { name: "Grace", age: 27, score: 93 },
  { name: "Henry", age: 40, score: 67 },
];

const sphere = createSorterSphere(schema, presetSort);
const fields = sphere.findSortableField();
const fieldNames = fields.map((f) => f.path.join("."));

export function SortExample() {
  const [sortField, setSortField] = useState(fieldNames[0]);
  const [sortDir, setSortDir] = useState<"asc" | "desc">("asc");

  const sorted = useMemo(() => {
    const field = fields.find((f) => f.path.join(".") === sortField);
    if (!field) return users;
    const firstAvailableFn = field.sortFnList[0]!;
    const rule = [sphere.getSortRule(field, firstAvailableFn, sortDir)];
    return sphere.sortData(users, rule);
  }, [sortField, sortDir]);

  return (
    <div className="flex flex-col gap-3">
      <div className="flex items-center gap-2 flex-wrap">
        <label className="text-sm font-medium text-gray-700 dark:text-gray-300">
          Sort by
        </label>
        <select
          value={sortField}
          onChange={(e) => setSortField(e.target.value)}
          className="rounded-md border border-gray-300 bg-white px-3 py-1.5 text-sm shadow-sm dark:border-gray-600 dark:bg-gray-800 dark:text-gray-100"
        >
          {fieldNames.map((name) => (
            <option key={name} value={name}>
              {name}
            </option>
          ))}
        </select>
        <div className="flex rounded-md border border-gray-300 shadow-sm dark:border-gray-600">
          <button
            type="button"
            onClick={() => setSortDir("asc")}
            className={`px-3 py-1.5 text-sm cursor-pointer rounded-l-md transition-colors ${
              sortDir === "asc"
                ? "bg-blue-600 text-white"
                : "bg-white text-gray-700 hover:bg-gray-50 dark:bg-gray-800 dark:text-gray-300 dark:hover:bg-gray-700"
            }`}
          >
            Asc
          </button>
          <button
            type="button"
            onClick={() => setSortDir("desc")}
            className={`px-3 py-1.5 text-sm cursor-pointer rounded-r-md border-l border-gray-300 dark:border-gray-600 transition-colors ${
              sortDir === "desc"
                ? "bg-blue-600 text-white"
                : "bg-white text-gray-700 hover:bg-gray-50 dark:bg-gray-800 dark:text-gray-300 dark:hover:bg-gray-700"
            }`}
          >
            Desc
          </button>
        </div>
      </div>
      <Table data={sorted} schema={schema} className="max-h-75" />
    </div>
  );
}

export default SortExample;

Usage Summary

1. Install the core package using your favorite package manager:

   pnpm

   pnpm add @fn-sphere/core

   npm

   npm install @fn-sphere/core

   yarn

   yarn add @fn-sphere/core

2. If not installed, add zod:

   pnpm

   pnpm add zod

   npm

   npm install zod

   yarn

   yarn add zod

3. Define your data schema with Zod:

   import { z } from "zod";
   
   const schema = z.object({
     name: z.string(),
     age: z.number(),
   });

4. Create a sorter sphere and sort your data:

   import { createSorterSphere, presetSort } from "@fn-sphere/core";
   
   const sphere = createSorterSphere(schema, presetSort);
   
   // Discover which fields are sortable
   const fields = sphere.findSortableField();
   const ageField = fields.find((f) => f.path[0] === "age")!;
   const sortAgeFn = ageField.sortFnList[0]!;
   
   // Build a sort rule (multi-field supported)
   const rule = [sphere.getSortRule(ageField, sortAgeFn, "desc")];
   
   // Sort data (non-mutating — returns a new array)
   const sorted = sphere.sortData(users, rule);
   
   // Or get a reusable comparator
   const cmp = sphere.getSortComparator(rule);
   [...users].sort(cmp);

Preset Sort

The built-in presetSort provides a generic compare function that handles string, number, boolean, Date, and enum fields out of the box.

import { presetSort } from "@fn-sphere/core";

const sphere = createSorterSphere(schema, presetSort);

Next Steps

• Learn how to define custom compare functions for domain-specific sorting logic.