@rebasepro/common 0.7.0 → 0.9.0

package/src/data/buildRoutedRebaseData.ts

@@ -1,24 +1,30 @@
-import { RebaseData, CollectionAccessor } from "@rebasepro/types";
+import { RebaseData, RebaseSdkData } from "@rebasepro/types";
 import { toSnakeCase } from "@rebasepro/utils";
 
+/**
+ * The two data-layer shapes that can be routed: the Entity-shaped admin
+ * {@link RebaseData} or the flat SDK {@link RebaseSdkData}. Both expose a
+ * `.collection(slug)` accessor, which is all the router needs.
+ */
+export type RoutableData = RebaseData | RebaseSdkData;
+
 /**
  * Parameters for {@link buildRoutedRebaseData}.
  */
-export interface RoutedRebaseDataParams {
+export interface RoutedRebaseDataParams<T extends RoutableData = RebaseData> {
     /**
      * The default data source. Handles every collection that does not
      * resolve to an entry in `sources` (i.e. server-transport collections,
      * which ride the Rebase client).
      */
-    defaultData: RebaseData;
+    defaultData: T;
 
     /**
-     * Per-data-source {@link RebaseData} instances for direct and custom
-     * transports, keyed by data-source key (e.g. `"analytics"`). Server-
-     * mediated sources are not listed here — they fall through to
-     * `defaultData`.
+     * Per-data-source instances for direct and custom transports, keyed by
+     * data-source key (e.g. `"analytics"`). Server-mediated sources are not
+     * listed here — they fall through to `defaultData`.
      */
-    sources: Record<string, RebaseData>;
+    sources: Record<string, T>;
 
     /**
      * Resolve the data-source key for a given collection slug or path.
@@ -55,11 +61,11 @@ export interface RoutedRebaseDataParams {
  * await data.products.find();        // → default (server / Postgres)
  * await data.events.find();          // → Firestore, if `events.dataSource === "analytics"`
  */
-export function buildRoutedRebaseData({
+export function buildRoutedRebaseData<T extends RoutableData = RebaseData>({
     defaultData,
     sources,
     resolveKey
-}: RoutedRebaseDataParams): RebaseData {
+}: RoutedRebaseDataParams<T>): T {
 
     // Fast path: nothing to route → return the default untouched (preserves
     // referential identity for effect dependencies).
@@ -67,21 +73,21 @@ export function buildRoutedRebaseData({
         return defaultData;
     }
 
-    function resolve(slugOrPath: string): RebaseData {
+    function resolve(slugOrPath: string): T {
         const key = resolveKey(slugOrPath);
         if (key && sources[key]) return sources[key];
         return defaultData;
     }
 
-    function getAccessor(slugOrPath: string): CollectionAccessor {
-        return resolve(slugOrPath).collection(slugOrPath);
+    function getAccessor(slugOrPath: string) {
+        return (resolve(slugOrPath) as RoutableData).collection(slugOrPath);
     }
 
     const target = {
         collection: getAccessor
-    } as RebaseData;
+    } as unknown as T;
 
-    return new Proxy(target, {
+    return new Proxy(target as object, {
         get(_target, prop: string | symbol) {
             if (prop === "collection") return getAccessor;
             // Ignore Symbol properties (e.g. Symbol.toPrimitive, Symbol.iterator)
@@ -93,5 +99,5 @@ export function buildRoutedRebaseData({
             // buildRebaseData so dynamic access routes consistently.
             return getAccessor(toSnakeCase(prop));
         }
-    });
+    }) as T;
 }

package/src/data/filter-dialect.ts

@@ -0,0 +1,403 @@
+/**
+ * REST wire-format adapter for the unified filter system.
+ *
+ * This module is the ONLY code in the entire codebase that knows about
+ * PostgREST-style dot-syntax strings (`eq.active`, `gt.18`, `in.(a,b)`).
+ * Everything else speaks `FilterValues` exclusively.
+ *
+ * Wire-format values are always strings — the wire format carries no type
+ * metadata, so type coercion is the responsibility of the server-side data
+ * driver which has access to the collection schema.
+ *
+ * Commas inside list values are backslash-escaped (`\,`), and literal
+ * backslashes are escaped as `\\`.
+ *
+ * @module
+ */
+
+import {
+    WhereFilterOp,
+    FilterValues,
+    CANONICAL_TO_REST,
+    REST_TO_CANONICAL,
+    RestFilterOp,
+    toCanonicalOp,
+    LogicalCondition,
+    FilterCondition,
+    NULL_OPS
+} from "@rebasepro/types";
+
+// ---------------------------------------------------------------------------
+// Value stringification
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize a JS value to its querystring representation.
+ * `null` is serialized as the literal string `"null"`.
+ */
+function stringifyValue(value: unknown): string {
+    if (value === null) return "null";
+    return String(value);
+}
+
+// ---------------------------------------------------------------------------
+// Comma escaping for list values
+// ---------------------------------------------------------------------------
+
+/**
+ * Escape a single list item for the wire format.
+ * `\` → `\\`, `,` → `\,`
+ */
+function escapeListItem(value: string): string {
+    return value.replace(/\\/g, "\\\\").replace(/,/g, "\\,");
+}
+
+/**
+ * Unescape a single list item from the wire format.
+ * `\\` → `\`, `\,` → `,`
+ */
+function unescapeListItem(value: string): string {
+    let result = "";
+    for (let i = 0; i < value.length; i++) {
+        if (value[i] === "\\" && i + 1 < value.length) {
+            result += value[i + 1];
+            i++; // skip next char
+        } else {
+            result += value[i];
+        }
+    }
+    return result;
+}
+
+/**
+ * Split a parenthesized list string on unescaped commas.
+ * Input is the content between `(` and `)`.
+ *
+ * @example
+ * splitListItems("admin,editor")          // ["admin", "editor"]
+ * splitListItems("hello\\, world,foo")    // ["hello, world", "foo"]
+ */
+function splitListItems(inner: string): string[] {
+    const items: string[] = [];
+    let current = "";
+    for (let i = 0; i < inner.length; i++) {
+        if (inner[i] === "\\" && i + 1 < inner.length) {
+            // Escaped character — consume both chars
+            current += inner[i] + inner[i + 1];
+            i++;
+        } else if (inner[i] === ",") {
+            items.push(unescapeListItem(current));
+            current = "";
+        } else {
+            current += inner[i];
+        }
+    }
+    items.push(unescapeListItem(current));
+    return items;
+}
+
+// ---------------------------------------------------------------------------
+// Typed operator map lookups (no `as any`)
+// ---------------------------------------------------------------------------
+
+const REST_OP_LOOKUP = REST_TO_CANONICAL as Readonly<Record<string, WhereFilterOp | undefined>>;
+const CANONICAL_OP_LOOKUP = CANONICAL_TO_REST as Readonly<Record<string, RestFilterOp | undefined>>;
+
+// ---------------------------------------------------------------------------
+// Serialize: FilterValues → REST querystring
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize a single canonical condition tuple to a PostgREST dot-string.
+ *
+ * Throws `TypeError` if the input is not a valid `[WhereFilterOp, unknown]` tuple.
+ *
+ * @example
+ * serializeTuple(["==", "active"])           // "eq.active"
+ * serializeTuple(["in", ["admin","editor"]]) // "in.(admin,editor)"
+ * serializeTuple([">=", 18])                 // "gte.18"
+ */
+function serializeTuple(tuple: [WhereFilterOp, unknown]): string {
+    if (!Array.isArray(tuple) || tuple.length !== 2) {
+        throw new TypeError(
+            `serializeTuple: expected a [WhereFilterOp, value] tuple, got ${JSON.stringify(tuple)}`
+        );
+    }
+
+    const [op, value] = tuple;
+
+    if (typeof op !== "string") {
+        throw new TypeError(
+            `serializeTuple: operator must be a string, got ${typeof op}`
+        );
+    }
+
+    const restOp = CANONICAL_OP_LOOKUP[op];
+    if (!restOp) {
+        throw new TypeError(
+            `serializeTuple: unknown operator "${op}". Valid operators: ${Object.keys(CANONICAL_TO_REST).join(", ")}`
+        );
+    }
+
+    if (Array.isArray(value)) {
+        const items = value.map(v => escapeListItem(stringifyValue(v))).join(",");
+        return `${restOp}.(${items})`;
+    }
+
+    return `${restOp}.${stringifyValue(value)}`;
+}
+
+/**
+ * Convert `FilterValues` (or `WireFilterValues`) to a PostgREST-style
+ * querystring record.
+ *
+ * - Canonical `[WhereFilterOp, value]` tuples are serialized strictly.
+ * - Pre-serialized PostgREST strings (e.g. `"eq.published"`) are passed through.
+ * - Single conditions produce a string value.
+ * - Multiple conditions on the same field produce a string array (repeated params).
+ *
+ * @example
+ * serializeFilter({ status: ["==", "active"] })
+ * // → { status: "eq.active" }
+ *
+ * serializeFilter({ age: [[">=", 18], ["<", 65]] })
+ * // → { age: ["gte.18", "lt.65"] }
+ *
+ * // Pre-serialized strings pass through unchanged:
+ * serializeFilter({ status: "eq.published" })
+ * // → { status: "eq.published" }
+ */
+export function serializeFilter(
+    filter: FilterValues<string> | Record<string, unknown>
+): Record<string, string | string[]> {
+    const result: Record<string, string | string[]> = {};
+
+    for (const [field, condition] of Object.entries(filter)) {
+        if (condition === undefined) continue;
+
+        // Pre-serialized PostgREST string — pass through unchanged.
+        // This supports WireFilterValues where values may already be
+        // serialized dot-strings like "eq.active" or raw strings like "true".
+        if (typeof condition === "string") {
+            result[field] = condition;
+            continue;
+        }
+
+        // Multiple conditions on the same field: array of tuples
+        // We detect this by checking if the first element is also an array.
+        if (Array.isArray(condition) && condition.length > 0 && Array.isArray(condition[0])) {
+            result[field] = (condition as [WhereFilterOp, unknown][]).map(serializeTuple);
+        } else {
+            // Single condition — must be a [WhereFilterOp, value] tuple
+            result[field] = serializeTuple(condition as [WhereFilterOp, unknown]);
+        }
+    }
+
+    return result;
+}
+
+// ---------------------------------------------------------------------------
+// Deserialize: REST querystring → FilterValues
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a single PostgREST dot-string into a `[WhereFilterOp, unknown]` tuple.
+ *
+ * All values are returned as strings — the wire format carries no type
+ * metadata, so coercion is the data driver's responsibility.
+ *
+ * If the string doesn't match a known operator prefix, it falls back to
+ * `["==", originalString]` (treating the whole string as an equality value).
+ * This intentional defense handles values like `"user@host.com"` or
+ * `"1.2.3"` that happen to contain dots.
+ */
+function deserializeSingle(raw: string): [WhereFilterOp, unknown] {
+    const dotIndex = raw.indexOf(".");
+    if (dotIndex === -1) {
+        // No dot → equality on the raw value (kept as string)
+        return ["==", raw];
+    }
+
+    const prefix = raw.substring(0, dotIndex);
+    const rest = raw.substring(dotIndex + 1);
+
+    // Check if the prefix is a known REST operator.
+    // This is the key defense against values like "eq.something" or "gt.foo"
+    // being misinterpreted — only known REST short-codes are treated as operators.
+    const canonicalOp = REST_OP_LOOKUP[prefix];
+    if (!canonicalOp) {
+        // Not a known operator (e.g., email "user@host.com" or version "1.2.3")
+        // Treat the entire string as an equality value
+        return ["==", raw];
+    }
+
+    // Null-testing operators ignore their serialized value — normalize to null
+    // so the tuple round-trips stably (`isnull.null` → ["is-null", null]).
+    if (NULL_OPS.has(canonicalOp)) {
+        return [canonicalOp, null];
+    }
+
+    // Parse list values: "(admin,editor)" → ["admin", "editor"]
+    if (rest.startsWith("(") && rest.endsWith(")")) {
+        const items = splitListItems(rest.slice(1, -1));
+        return [canonicalOp, items];
+    }
+
+    return [canonicalOp, rest];
+}
+
+/**
+ * Convert a PostgREST-style querystring record to `FilterValues`.
+ *
+ * - String values are parsed as single conditions.
+ * - String arrays (repeated query params) become multiple conditions on the same field.
+ *
+ * @example
+ * deserializeFilter({ status: "eq.active" })
+ * // → { status: ["==", "active"] }
+ *
+ * deserializeFilter({ age: ["gte.18", "lt.65"] })
+ * // → { age: [[">=", "18"], ["<", "65"]] }
+ */
+export function deserializeFilter(
+    query: Record<string, unknown>
+): FilterValues<string> {
+    const result: FilterValues<string> = {};
+
+    for (const [field, raw] of Object.entries(query)) {
+        if (raw === undefined) continue;
+
+        // If it's already a canonical tuple [op, value], keep it as is
+        if (Array.isArray(raw) && raw.length === 2 && typeof raw[0] === "string" && toCanonicalOp(raw[0]) === raw[0]) {
+            result[field] = raw as [WhereFilterOp, unknown];
+            continue;
+        }
+
+        if (Array.isArray(raw)) {
+            if (raw.length === 0) continue;
+            
+            // Check if it's an array of canonical tuples
+            if (Array.isArray(raw[0]) && raw[0].length === 2 && typeof raw[0][0] === "string" && toCanonicalOp(raw[0][0]) === raw[0][0]) {
+                result[field] = raw as [WhereFilterOp, unknown][];
+                continue;
+            }
+
+            if (raw.length === 1) {
+                result[field] = typeof raw[0] === "string" ? deserializeSingle(raw[0]) : ["==", raw[0]];
+            } else {
+                // If the elements are strings, they might be PostgREST dot-strings (repeated params)
+                if (typeof raw[0] === "string" && raw[0].includes(".")) {
+                    result[field] = raw.map(r => typeof r === "string" ? deserializeSingle(r) : (["==", r] as [WhereFilterOp, unknown])) as [WhereFilterOp, unknown][];
+                } else {
+                    // Otherwise assume it's a list of values for an implicit "in" or just multiple conditions
+                    result[field] = ["in", raw];
+                }
+            }
+        } else if (typeof raw === "string") {
+            result[field] = deserializeSingle(raw);
+        } else {
+            result[field] = ["==", raw];
+        }
+    }
+
+    return result;
+}
+
+// ---------------------------------------------------------------------------
+// Logical conditions: serialize / deserialize
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize a `LogicalCondition` or `FilterCondition` to its wire-format string.
+ *
+ * @example
+ * serializeLogicalCondition({ column: "status", operator: "==", value: "active" })
+ * // → "status.eq.active"
+ *
+ * serializeLogicalCondition({ type: "or", conditions: [...] })
+ * // → "or(status.eq.active,status.eq.pending)"
+ */
+export function serializeLogicalCondition(
+    cond: LogicalCondition | FilterCondition
+): string {
+    if ("type" in cond) {
+        // LogicalCondition (and/or)
+        const inner = (cond.conditions ?? [])
+            .map(serializeLogicalCondition)
+            .join(",");
+        return `${cond.type}(${inner})`;
+    }
+
+    // FilterCondition
+    const restOp = CANONICAL_OP_LOOKUP[cond.operator] ?? "eq";
+    if (Array.isArray(cond.value)) {
+        const items = cond.value.map(v => escapeListItem(stringifyValue(v))).join(",");
+        return `${cond.column}.${restOp}.(${items})`;
+    }
+    return `${cond.column}.${restOp}.${stringifyValue(cond.value)}`;
+}
+
+/**
+ * Parse a logical condition wire-format string back into a
+ * `LogicalCondition` or `FilterCondition`.
+ *
+ * @example
+ * deserializeLogicalCondition("status.eq.active")
+ * // → { column: "status", operator: "==", value: "active" }
+ *
+ * deserializeLogicalCondition("or(status.eq.active,age.gte.18)")
+ * // → { type: "or", conditions: [...] }
+ */
+export function deserializeLogicalCondition(
+    str: string
+): LogicalCondition | FilterCondition {
+    // Check for logical group: "and(...)" or "or(...)"
+    const logicalMatch = str.match(/^(and|or)\((.+)\)$/);
+    if (logicalMatch) {
+        const type = logicalMatch[1] as "and" | "or";
+        const innerStr = logicalMatch[2];
+
+        // Split on commas that are not inside parentheses
+        const conditions: (LogicalCondition | FilterCondition)[] = [];
+        let depth = 0;
+        let start = 0;
+        for (let i = 0; i < innerStr.length; i++) {
+            if (innerStr[i] === "(") depth++;
+            else if (innerStr[i] === ")") depth--;
+            else if (innerStr[i] === "," && depth === 0) {
+                conditions.push(deserializeLogicalCondition(innerStr.slice(start, i)));
+                start = i + 1;
+            }
+        }
+        conditions.push(deserializeLogicalCondition(innerStr.slice(start)));
+
+        return { type, conditions };
+    }
+
+    // FilterCondition: "column.op.value"
+    const firstDot = str.indexOf(".");
+    if (firstDot === -1) {
+        return { column: str, operator: "==", value: true };
+    }
+
+    const column = str.substring(0, firstDot);
+    const rest = str.substring(firstDot + 1);
+
+    const secondDot = rest.indexOf(".");
+    if (secondDot === -1) {
+        // "column.value" — treat as equality (value kept as string)
+        return { column, operator: "==", value: rest };
+    }
+
+    const opStr = rest.substring(0, secondDot);
+    const valueStr = rest.substring(secondDot + 1);
+    const operator = toCanonicalOp(opStr) ?? "==";
+
+    // Parse list values with escape-aware splitting
+    if (valueStr.startsWith("(") && valueStr.endsWith(")")) {
+        const items = splitListItems(valueStr.slice(1, -1));
+        return { column, operator, value: items };
+    }
+
+    return { column, operator, value: valueStr };
+}

package/src/data/query_builder.ts

@@ -1,4 +1,13 @@
-import { FindParams, Entity, FindResponse, CollectionAccessor, QueryBuilderInterface, FilterOperator, LogicalCondition, WhereValue, FilterCondition } from "@rebasepro/types";
+import {
+    CollectionAccessor,
+    FilterCondition,
+    FindParams,
+    FindResponse,
+    LogicalCondition,
+    QueryBuilderInterface,
+    WhereFilterOp,
+    WhereValue
+} from "@rebasepro/types";
 
 export function or(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition {
     return { type: "or",
@@ -10,7 +19,7 @@ export function and(...conditions: (FilterCondition | LogicalCondition)[]): Logi
 conditions };
 }
 
-export function cond(column: string, operator: FilterOperator, value: unknown): FilterCondition {
+export function cond(column: string, operator: WhereFilterOp, value: unknown): FilterCondition {
     return { column,
 operator,
 value };
@@ -26,9 +35,9 @@ export class QueryBuilder<M extends Record<string, unknown> = Record<string, unk
      * @example
      * client.collection('users').where('age', '>=', 18).find()
      */
-    where<K extends keyof M & string>(column: K, operator: FilterOperator, value: WhereValue<M[K]>): this;
+    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): this;
     where(logicalCondition: LogicalCondition): this;
-    where(columnOrCondition: string | LogicalCondition, operator?: FilterOperator, value?: unknown): this {
+    where(columnOrCondition: string | LogicalCondition, operator?: WhereFilterOp, value?: unknown): this {
         // Handle LogicalCondition signature
         if (typeof columnOrCondition === "object" && columnOrCondition !== null && "type" in columnOrCondition) {
             this.params.logical = columnOrCondition as LogicalCondition;
@@ -40,18 +49,18 @@ export class QueryBuilder<M extends Record<string, unknown> = Record<string, unk
         }
 
         const column = columnOrCondition as string;
-        const condition: [FilterOperator, unknown] = [operator!, value];
+        const condition: [WhereFilterOp, unknown] = [operator!, value];
         const existing = this.params.where[column];
 
         if (existing === undefined) {
             this.params.where[column] = condition;
         } else if (Array.isArray(existing) && existing.length > 0 && Array.isArray(existing[0])) {
-            (this.params.where[column] as [FilterOperator, unknown][]).push(condition);
+            (this.params.where[column] as [WhereFilterOp, unknown][]).push(condition);
         } else {
             // Convert existing single tuple/value into array of tuples
-            let firstCondition: [FilterOperator, unknown];
+            let firstCondition: [WhereFilterOp, unknown];
             if (Array.isArray(existing) && existing.length === 2 && typeof existing[0] === "string") {
-                firstCondition = existing as [FilterOperator, unknown];
+                firstCondition = existing as [WhereFilterOp, unknown];
             } else {
                 firstCondition = ["==", existing];
             }
@@ -66,8 +75,8 @@ export class QueryBuilder<M extends Record<string, unknown> = Record<string, unk
      * @example
      * client.collection('users').orderBy('createdAt', 'desc').find()
      */
-    orderBy(column: keyof M & string, ascending: "asc" | "desc" = "asc"): this {
-        this.params.orderBy = `${column}:${ascending}`;
+    orderBy(column: keyof M & string, direction: "asc" | "desc" = "asc"): this {
+        this.params.orderBy = [column, direction];
         return this;
     }
 

package/src/data/resolveDataSource.ts

@@ -7,15 +7,15 @@ import {
 
 /**
  * The subset of a collection needed to resolve its data source. Accepting a
- * structural type (rather than the full `EntityCollection`) keeps this usable
+ * structural type (rather than the full `CollectionConfig`) keeps this usable
  * from anywhere — frontend router, backend registry, editor — without coupling
  * to the collection union.
  */
 export interface DataSourceResolvable {
     /** Preferred routing key. */
     dataSource?: string;
-    /** Legacy engine hint / fallback routing key. */
-    driver?: string;
+    /** Engine type discriminant (set on variant collection types). */
+    engine?: string;
     /** Within-engine instance. */
     databaseId?: string;
 }
@@ -41,13 +41,13 @@ export function createDataSourceRegistry(definitions?: DataSourceDefinition[]):
  * editor's capability lookups.
  *
  * Resolution order:
- * 1. The routing **key** is `collection.dataSource`, else the legacy
- *    `collection.driver`, else {@link DEFAULT_DATA_SOURCE_KEY}.
+ * 1. The routing **key** is `collection.dataSource`, else
+ *    {@link DEFAULT_DATA_SOURCE_KEY}.
  * 2. If a definition is registered for that key, it provides `engine`,
  *    `transport`, and `databaseId`.
- * 3. Otherwise values are synthesized for backward compatibility: `engine`
- *    from the legacy `driver` (or the key, or `"postgres"`), `transport`
- *    defaults to `"server"`, and `databaseId` from the collection.
+ * 3. Otherwise values are synthesized: `engine` from `collection.engine`
+ *    (or the key, or `"postgres"`), `transport` defaults to `"server"`,
+ *    and `databaseId` from the collection.
  *
  * `capabilities` are always derived from the resolved `engine`, so two
  * data sources sharing an engine share capabilities.
@@ -59,11 +59,11 @@ export function resolveDataSource(
     collection: DataSourceResolvable | undefined,
     registry?: DataSourceRegistry
 ): ResolvedDataSource {
-    const key = collection?.dataSource ?? collection?.driver ?? DEFAULT_DATA_SOURCE_KEY;
+    const key = collection?.dataSource ?? DEFAULT_DATA_SOURCE_KEY;
     const def = registry?.[key];
 
     const engine = def?.engine
-        ?? collection?.driver
+        ?? collection?.engine
         ?? (key !== DEFAULT_DATA_SOURCE_KEY ? key : "postgres");
 
     const transport = def?.transport ?? "server";

package/src/data/sort-dialect.ts

@@ -0,0 +1,56 @@
+import type { OrderByTuple } from "@rebasepro/types";
+
+/**
+ * Sort-order wire codec.
+ *
+ * This is the ONLY module that knows about the colon-delimited wire format
+ * (`"field:direction"`) used in HTTP query parameters.
+ * Everything else speaks {@link OrderByTuple} exclusively.
+ *
+ * Mirrors the filter architecture in `filter-dialect.ts`.
+ *
+ * @module
+ */
+
+/**
+ * Serialize an {@link OrderByTuple} to the wire format `"field:direction"`.
+ *
+ * **Runtime tolerance:** if the input is already a well-formed wire string
+ * (from an untyped JS caller), it is returned unchanged.
+ * This is undocumented tolerance, not public API — don't rely on it.
+ *
+ * @param orderBy - A canonical `[field, direction]` tuple, or at runtime
+ *   possibly a pre-serialized string (undocumented tolerance).
+ * @returns The wire-format string, or `undefined` if the input is falsy.
+ *
+ * @remarks
+ * Field names containing `:` are representable in the tuple form but
+ * **not** on the wire — this is an inherent limitation of the colon-delimited
+ * encoding and is not resolved here.
+ */
+export function serializeOrderBy(orderBy?: OrderByTuple | string): string | undefined {
+    if (!orderBy) return undefined;
+    // Runtime tolerance: pass through a pre-serialized wire string unchanged.
+    if (typeof orderBy === "string") return orderBy;
+    return `${orderBy[0]}:${orderBy[1]}`;
+}
+
+/**
+ * Deserialize a wire-format `"field:direction"` string into an {@link OrderByTuple}.
+ *
+ * Lenient parsing (matches existing server behaviour):
+ * - Bare field name (no colon): `"name"` → `["name", "asc"]`
+ * - Unknown direction: `"name:foo"` → `["name", "asc"]`
+ * - Empty / falsy input: → `undefined`
+ *
+ * @param raw - The wire-format string from an HTTP query parameter.
+ * @returns The canonical tuple, or `undefined` if the input is empty/falsy.
+ */
+export function deserializeOrderBy(raw?: string): OrderByTuple | undefined {
+    if (!raw) return undefined;
+    const idx = raw.indexOf(":");
+    if (idx === -1) return [raw, "asc"];
+    const field = raw.slice(0, idx);
+    const dir = raw.slice(idx + 1);
+    return [field, dir === "desc" ? "desc" : "asc"];
+}

package/src/index.ts

@@ -4,4 +4,6 @@ export * from "./data/buildRebaseData";
 export * from "./data/buildRoutedRebaseData";
 export * from "./data/resolveDataSource";
 export * from "./data/query_builder";
+export * from "./data/filter-dialect";
+export * from "./data/sort-dialect";
 export * from "./table-classification";