fix: restore and deprecate $params helper for incremental migrations (#142)

* chore: restore and deprecate $params helper for incremental migrations

* update snapshots

Author: rossipedia

README.md

@@ -121,6 +121,31 @@ export const loader = async (request) => {
 }
 ```
 
+### Checking params
+
+> [!NOTE]
+> This function has been marked `@deprecated` in favor of React Router's
+> built-in type-safety, which provides strongly typed `params` to loaders,
+> actions, and components. This helper has been kept primarily to assist in
+> incremental migration.
+
+```typescript
+import { useParams } from "react-router";
+import { $params } from 'safe-routes'; // <-- Import $params helper.
+
+export const action = async ({ params }) => {
+  const { id } = $params("/posts/:id/update", params) // <-- It's type safe, try renaming `id` param.
+
+  // ...
+}
+
+export default function Component() {
+  const params = useParams();
+  const { id } = $params("/posts/:id/update", params);
+  ...
+}
+```
+
 ### Typed route ids
 
 safe-routes exports the `RouteId` type definition with the list of all valid route ids for your repository, and has a helper function `$routeId` that tells typescript to restrict the given string to one of the valid RouteId values.

src/index.ts

@@ -58,3 +58,11 @@ export function $path(route: string, ...paramsOrQuery: Array<any>) {
 export function $routeId(routeId: string) {
   return routeId;
 }
+
+/** @deprecated Prefer to use React Router's typegen features instead. */
+export function $params(
+  _route: string,
+  params: { readonly [key: string]: string | undefined },
+) {
+  return params;
+}

src/template.ts

@@ -70,5 +70,14 @@ export function template(ctx: Context) {
   ): string;
 
   export function $routeId(routeId: RouteId): RouteId;
+
+  /** @deprecated Prefer to use React Router's typegen features instead. */
+  export function $params<
+    Route extends keyof RoutesWithParams,
+    Params extends RoutesWithParams[Route]["params"]
+  >(
+      route: Route,
+      params: { readonly [key: string]: string | undefined }
+  ): {[K in keyof Params]: string};
 }`;
 };

tests/__snapshots__/build.test.ts.snap

@@ -186,5 +186,14 @@ exports[`gen route types 1`] = `
   ): string;
 
   export function $routeId(routeId: RouteId): RouteId;
+
+  /** @deprecated Prefer to use React Router's typegen features instead. */
+  export function $params<
+    Route extends keyof RoutesWithParams,
+    Params extends RoutesWithParams[Route]["params"]
+  >(
+      route: Route,
+      params: { readonly [key: string]: string | undefined }
+  ): {[K in keyof Params]: string};
 }"
 `;

tests/index.test.ts

@@ -1,5 +1,5 @@
 import { expect, test, vi } from 'vitest';
-import { $path } from '../src';
+import { $params, $path } from '../src';
 import * as basename from '../src/basename.ts';
 
 vi.mock(import('../src/basename.ts'));
@@ -53,6 +53,10 @@ test('optional segment', () => {
   expect($path('/tree?/:tree?', { tree: 'main' })).toBe('/tree/main');
 });
 
+test('$params', () => {
+  expect($params('/posts/:id', { id: '1' })).toStrictEqual({ id: '1' });
+});
+
 test('basename', async () => {
   vi.mocked(basename.resolveBasename).mockReturnValue('/blog');