v2.0.0

Added

• Add configure() for configuring types parser globally.
• Allow to pass a custom parser as a second argument to all built-in types.
• Expose params kind ("pathname" | "search" | "hash") for custom parsers to use.
• Add pathless routes and route composition API.

// Instead of route(':id', { params: { id: number() }, searchParams: { page: number() } })
const fragment = route({ params: { id: number() }, searchParams: { page: number() } });

// Instead of types(FRAGMENT)({searchParams: { query: string() }})
const myRoute = route({
  path: "my-path/:id",
  compose: [fragment],
  searchParams: { query: string() },
});

const { id } = useTypedParams(fragment);
const [{ page }] = useTypedSearchParams(fragment);

Changed

• union() now accepts enums and readonly (as const) objects.
• union() now properly infers values from an inline array without as const.
• Pathname params without explicit types now use string() and string().defined() for optional and required params respectively instead of custom code.
• State can now optionally be typed as a whole, so non-object states can now be typed.
• Optional splats are now explicitly forbidden (they stopped working in React Router v6.9.0).
• Routes without pathname/search/state params now accept non-empty object as these params.
• Breaking: union() no longer accepts its values as multiple arguments.
• Breaking: Types for pathname params are now stricter and don't allow params which are not specified in the path pattern. This also fixes autocomplete for such params.
• Breaking: A $ is added to all fields of a route object, so now child routes can start with a lowercase character and use basically any naming scheme (unless they start with a $, which is forbidden).
• Breaking: The path and relativePath route fields were squashed into the $path() function. It returns an absolute path pattern by default or a relative path pattern if the relative option is set to true.
• Breaking: The types field is renamed to $spec, and it now also contains an unmodified path option of the route.
• Breaking: Naming scheme was changed from getPlain/getTyped to serialize/deserialize for clarity.
• Breaking: Path and state generation API is changed.
  • $buildPath (formerly buildPath) now accepts all params as a single argument. Signatures of all build* functions were updated accordingly.
  • $buildPathname is added.
  • buildRelativePath is removed, and instead $buildPath and $buildPathname now accept a relative option.
  • getUntypedParams, getUntypedSearchParams, and getUntypedState were removed. Instead, $buildPath, $buildSearch, $serializeSearchParams, and $buildState now accept untypedSearchParams or untypedState options where applicable. When provided, the corresponding untyped parts are added to the resulting path (the search part) or state. The corresponding option in useTypedSearchParams is also renamed.
  • $serializeSearchParams (formerly getPlainSearchParams) now returns a URLSearchParams instance for consistency with the rest of the API.
• Breaking: route API is changed. It now accepts a single argument with optional types, path, composed routes and children. By default, path is undefined (which means a pathless route).
• Breaking: Hash should now be specified as an array of strings or a type. Empty array now means "nothing" instead of "any string". For example:
  • hashValues('about', 'info') => ['about', 'info']
  • hashValues() => string()
  • Default: []
  • You can also use other types, like number().default(-1)
• Breaking: Array types like string().array() now filter undefined values upon parsing. The previous behavior broke a common pattern of changing a subset of search parameters:

const FRAGMENT = route({ searchParams: { pages: number().array(), query: string() } });

const [{ pages, query }, setTypedSearchParams] = useTypedSearchParams(FRAGMENT);

setTypedSearchParams((prevParams) => ({
  // Previously, prevParams.pages would be (number|undefined)[],
  // which is not assignable to number[].
  ...prevParams,
  query: "hi",
}));

• Breaking: Similarly, undefined keys are now omitted from all parsed params to match how there are no such keys in raw params from React Router. The reason this behavior was originally introduced is not relevant anymore.
• Breaking: $ no longer prevents pathname types inheritance.
• Breaking: Some types are changed for convenience and readability.
• Breaking: The minimal required version of TS is now v5.0 with strict mode enabled.
• Breaking: The minimal required version of React Router is now v7.0.
• Breaking: CommonJS is now used by default, similarly to React Router.

Removed

• Breaking: Removed /dom and /native entry points. Use the main entry point instead.
• Breaking: Removed all deprecated features.
• Breaking: Removed hashValues(). Pass an array of strings or a type instead.
• Breaking: Removed types(). Use composition API instead.

v1.2.2

Fixed

• For routes without pathname/search/state params, non-empty objects are no longer accepted as these params.

v1.2.1

Fixed

• Fix path generation when the first segment is optional. Previously, route(":optional?/:required").buildPath({ required: "req" }) would be "//req".

v1.2.0

Added

• Add CommonJS support for environments that support the exports field in package.json.

v1.1.0

Added

• Introduce type objects that allow to fine-tune parsing and serialization logic for every route part.
• Add helpers for creating these type objects. They can generally be used instead of the old ones (see Migrating to Universal Types). The helpers are:
  • type() for creating any type;
  • parser() for accessing the built-in parser, most likely for building custom wrappers around type();
  • string(), number(), boolean(), and date() for creating types based on the corresponding primitives;
  • union() for creating unions of string, number, and boolean values;
  • zod() for creating types based on Zod Types;
  • yup() for creating types based on Yup Schemas.
• Route params input and output types are now much more readable in IDE hints.
• Specifying a path pattern with leading or trailing slashes or a child route starting with a lowercase letter will now lead to a human-readable error.

Fixed

• For types of parsed path params, search params, and state fields, keys that correspond to type objects that return undefined upon a parsing error are no longer optional.

Deprecated

• Deprecate old helpers for creating type objects: createType(), stringType(), numberType(), booleanType(), dateType(), oneOfType(), arrayOfType(), throwable, and all types that are exclusive to them.
• Deprecate assertIsString(), assertIsNumber(), assertIsBoolean(), assertIsArray(), and assertIsValidDate() because they are embedded in new helpers, which allow to run additional checks after these assertions.

v1.0.0

Added

• Add support for optional path segments.
• Add types() helper for route types composition.
• Add getUntypedParams() method to route object.

Fixed

• Intermediate splat (star) segments in absolute path patterns are now properly detected. Previously, their detection didn't work properly if dynamic segments were present. It means that such star params will now correctly appear in parsed (typed) path params.
• Multiple intermediate stars are now properly removed from relative path pattern. This also fixes building URL paths from such patterns.
• Upon building URL paths from patterns with only intermediate stars, the * parameter is not present anymore, because it doesn't actually do anything (intermediate stars are simply removed).

Changed

• Breaking: Fallbacks are now run through type functions to ensure fallbacks validity, and therefore TRetrieved was replaced with TOriginal in their type. This is technically a breaking change, but it only affects custom types where TRetrieved is not assignable to TOriginal, which should be extremely rare.
• Breaking: Minimal required React Router version is changed to 6.7.0 due to optional path segments support.
• Breaking: Rename ExtractRouteParams to PathParam for parity with React Router.
• Breaking: In route object, $ no longer contains undecorated child routes. Instead, it now contains routes that lack parent path pattern and path type objects, but inherit everything else.
• buildPath/buildRelativePath now accept additional arguments and behave exactly like buildUrl/buildRelativeUrl.
• setTypedSearchParams is switched to React Router implementation of functional updates.

Deprecated

• buildUrl/buildRelativeUrl now behave exactly like buildPath/buildRelativePath and are therefore deprecated.

Removed

• Remove all internal fields prefixed with __ from route objects.

v0.5.1

Added

• Add CONTRIBUTING.md

Fixed

• Sync node version requirements with react-router.

v0.5.0

Added

• Expose route types (previously existed as internal __options__).

Changed

• Renamed CreateRouteOptions and RouteOptions into RouteOptions and RouteTypes respectively.

v0.4.3

Added

• Add throwable fallback.

v0.4.2

Added

• Add CHANGELOG.md.
• Add preserveUntyped option to setTypedSearchParams from useTypedSearchParams hook.
• Add getUntypedSearchParams and getUntypedState methods to route object.

Fixed

• Return value of buildState method is now properly typed as Record<string, unknown> instead of unknown.
• Hook dependencies are now properly listed, which is checked by ESLint. This fixes useTypedSearchParams for dynamic routes.
• Prevent access to internal useUpdatingRef helper.