feat: implement sorting functionality with createSorterSphere and utilities (#207)

* feat: implement sorting functionality with createSorterSphere and related utilities

* refactor: move filter and sort fn

* refactor: streamline sorting and filtering utilities, remove unused functions

* fix: format

Author: lawvs

packages/core/src/filter/field.ts

@@ -1,44 +1,9 @@
 import { isSameType } from "zod-compare";
-import type { $ZodTuple, $ZodType, $ZodTypes } from "zod/v4/core";
-import { isGenericFilter } from "../fn-helpers.js";
+import type { $ZodTuple, $ZodType } from "zod/v4/core";
+import { isFilterFn, isGenericFilter } from "../fn-helpers.js";
 import type { FnSchema, StandardFnSchema } from "../types.js";
 import type { FilterField, FilterPath } from "./types.js";
-import { instantiateGenericFn } from "./utils.js";
-
-const bfsSchemaField = (
-  schema: $ZodType,
-  maxDeep: number,
-  walk: (field: $ZodType, path: FilterPath) => void,
-) => {
-  const queue = [
-    {
-      schema,
-      path: [] as FilterPath,
-      deep: 0,
-    },
-  ];
-  while (queue.length > 0) {
-    const current = queue.shift();
-    if (!current) break;
-    if (current.deep > maxDeep) break;
-
-    walk(current.schema, current.path);
-
-    const currentSchema = current.schema as $ZodTypes;
-    if (currentSchema._zod.def.type !== "object") continue;
-
-    const fields = currentSchema._zod.def.shape;
-    for (const key in fields) {
-      const field = fields[key];
-      if (!field) continue;
-      queue.push({
-        schema: field,
-        path: [...current.path, key] as FilterPath,
-        deep: current.deep + 1,
-      });
-    }
-  }
-};
+import { bfsSchemaField, instantiateGenericFn } from "./utils.js";
 
 /**
  * Find all fields that can be filtered based on the given schema and filterFnList.
@@ -64,7 +29,8 @@ export const findFilterableFields = <Data>({
         const genericFilter = fnSchema;
         return instantiateGenericFn(fieldSchema, genericFilter);
       })
-      .filter((fn): fn is StandardFnSchema => !!fn);
+      .filter((fn): fn is StandardFnSchema => !!fn)
+      .filter(isFilterFn);
 
     const availableFilter = instantiationFilter.filter((filter) => {
       const { define } = filter;

packages/core/src/filter/utils.test.ts

@@ -295,7 +295,7 @@ describe("instantiateGenericFn", () => {
     ).toBe(true);
   });
 
-  it("should return undefined if instantiated function is not a filter", () => {
+  it("should return instantiated function even if it is not a filter (caller validates)", () => {
     const schema = z.string(); // Example schema
     const genericFn = defineGenericFn({
       name: "Non-Filter Function",
@@ -305,7 +305,8 @@ describe("instantiateGenericFn", () => {
     });
 
     const result = instantiateGenericFn(schema, genericFn);
-    expect(result).toBeUndefined();
+    expect(result).toBeDefined();
+    expect(result?.name).toBe("Non-Filter Function");
   });
 
   it("should keep meta information when instantiating a function", () => {

packages/core/src/filter/utils.ts

@@ -4,7 +4,6 @@ import {
   type $ZodType,
   type $ZodTypes,
 } from "zod/v4/core";
-import { isFilterFn } from "../fn-helpers.js";
 import type { FnSchema, GenericFnSchema, StandardFnSchema } from "../types.js";
 import { unreachable } from "../utils.js";
 import type {
@@ -36,7 +35,7 @@ export const instantiateGenericFn = (
   if (!genericFn.genericLimit(schema as $ZodTypes)) {
     return;
   }
-  const instantiationFn: StandardFnSchema = {
+  return {
     name: genericFn.name,
     define: genericFn.define(schema),
     implement: genericFn.implement,
@@ -47,11 +46,6 @@ export const instantiateGenericFn = (
       genericFn: genericFn,
     },
   };
-  const isFilter = isFilterFn(instantiationFn);
-  if (!isFilter) {
-    return;
-  }
-  return instantiationFn;
 };
 
 export const getFirstParameters = (fnSchema: StandardFnSchema) => {
@@ -181,6 +175,41 @@ export const isEqualPath = (a: FilterPath, b: FilterPath): boolean => {
   return a.every((v, i) => v === b[i]);
 };
 
+export const bfsSchemaField = (
+  schema: $ZodType,
+  maxDeep: number,
+  walk: (field: $ZodType, path: FilterPath) => void,
+) => {
+  const queue = [
+    {
+      schema,
+      path: [] as FilterPath,
+      deep: 0,
+    },
+  ];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current) break;
+    if (current.deep > maxDeep) break;
+
+    walk(current.schema, current.path);
+
+    const currentSchema = current.schema as $ZodTypes;
+    if (currentSchema._zod.def.type !== "object") continue;
+
+    const fields = currentSchema._zod.def.shape;
+    for (const key in fields) {
+      const field = fields[key];
+      if (!field) continue;
+      queue.push({
+        schema: field,
+        path: [...current.path, key] as FilterPath,
+        deep: current.deep + 1,
+      });
+    }
+  }
+};
+
 /**
  * Simple get function
  * See https://gist.github.com/jeneg/9767afdcca45601ea44930ea03e0febf

packages/core/src/fn-sphere.ts

@@ -6,7 +6,8 @@ import type {
   $ZodUnknown,
 } from "zod/v4/core";
 import { createFilterSphere } from "./filter/index.js";
-import { isFilterFn } from "./fn-helpers.js";
+import { isCompareFn, isFilterFn } from "./fn-helpers.js";
+import { createSorterSphere } from "./sort/index.js";
 import type { GenericFnSchema, StandardFnSchema } from "./types.js";
 
 export const createFnSphere = () => {
@@ -75,6 +76,12 @@ export const createFnSphere = () => {
     return zFilter;
   };
 
+  const setupSort = <S>(schema: $ZodType<S>) => {
+    const compareFn = findFn(isCompareFn);
+    const zSort = createSorterSphere(schema, compareFn);
+    return zSort;
+  };
+
   return {
     _state: state,
 
@@ -85,5 +92,7 @@ export const createFnSphere = () => {
     findFn,
 
     setupFilter,
+
+    setupSort,
   };
 };