Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

3.6 KB
Raw Blame
import { parseSearchWith } from "@tanstack/react-router";

/**
 * Reading a search parameter that is TEXT, when the router has already decided it was something
 * else.
 *
 * THE ROUTER JSON-PARSES EVERY SEARCH VALUE. `?connected=notion` stays the string it looks like
 * only because `notion` is not valid JSON; `?flow_id=12345` arrives as the number 12345 and
 * `?flow_id={"a":1}` as an object, because both of those are. Nothing in the URL said so — whether
 * a value survives as text depends entirely on what characters the sender's id generator happened
 * to emit, which is why a `typeof value === "string"` guard works for every handle in testing and
 * silently drops a fraction of the real ones.
 *
 * SO NOTHING HERE GUARDS ON THE PARSED TYPE; it renders whatever came back to the text it was in
 * the URL. There is no shape a sender can choose that falls through to "no parameter", so the
 * wrong case is gone by construction rather than by a list of types to also accept — the same
 * answer the notice table on the connected-accounts screen gives for keys off a URL.
 */

/**
 * The text a search value was in the URL, or undefined when the parameter was not there at all.
 *
 * Exact for everything `parseSearchText` lets through: a string is itself, a number is one it
 * round-trips through (see below), and an object or array is re-rendered as the JSON it was parsed
 * from. The empty string is a value, not an absence — a parameter present and empty is passed on as
 * such, for whoever reads it to call unusable.
 */
export function searchText(value: unknown): string | undefined {
  if (value === undefined) return undefined;
  if (typeof value === "string") return value;
  if (typeof value === "number" || typeof value === "boolean" || value === null)
    return String(value);
  /*
   * An object or array can only have got here by having been JSON in the URL, so stringifying it is
   * reading that JSON back. `JSON.stringify` answers undefined rather than text for values it
   * cannot render; none of those can come out of `JSON.parse`, and the check is here so that a
   * future parser which can is a missing parameter rather than the string "undefined".
   */
  const text = JSON.stringify(value);
  return typeof text === "string" ? text : undefined;
}

/**
 * That text under its key, or nothing — ready to spread into what `validateSearch` returns.
 *
 * The key is OMITTED rather than set to undefined, for the reason the routes using this give:
 * present-but-undefined makes `search` a required prop on every Link to the route, which is a lot
 * of ripple for a parameter only a callback sets.
 */
export function searchTextEntry<Key extends string>(
  key: Key,
  value: unknown,
): Partial<Record<Key, string>> {
  const text = searchText(value);
  return text === undefined ? {} : ({ [key]: text } as Record<Key, string>);
}

/**
 * The router's own parser, with the one case `searchText` could not have rendered back taken away.
 *
 * `JSON.parse` turns `12345678901234567890` into a double, and no amount of care downstream can
 * recover the digits that rounding threw away — a handle like that would come back out of
 * `searchText` as a DIFFERENT handle, which is worse than dropping it. So a number whose text form
 * is not the text it was parsed from is left as that text, and every number that does reach a route
 * is one `String` renders back exactly. `1e3` keeps its spelling for the same reason.
 */
export const parseSearchText: (searchStr: string) => Record<string, unknown> =
  parseSearchWith((value: string) => {
    const parsed: unknown = JSON.parse(value);
    return typeof parsed === "number" && String(parsed) !== value
      ? value
      : parsed;
  });