add command to dump expanded route config as JSON

Author: zth

.changeset/nervous-rivers-taste.md

@@ -0,0 +1,5 @@
+---
+"rescript-relay-router": minor
+---
+
+Add command to dump expanded routes as JSON.

packages/rescript-relay-router/README.md

@@ -609,6 +609,56 @@ switch Routes.Organization.Members.Route.parseRoute(link){
 let activeSubRoute = Routes.Organization.Route.useActiveSubRoute()
 ```
 
+## CLI utilities
+
+### Dumping routes
+
+You can dump all route URLs from your configured route tree:
+
+```bash
+yarn rescript-relay-router dump-routes
+```
+
+This prints a JSON array in route definition order:
+
+```json
+[
+  { "url": "/organization/:slug" },
+  { "url": "/organization/:slug/members" },
+  { "url": "/" }
+]
+```
+
+To sort alphabetically by `url`, pass `--sort alphabetic`.
+
+Use flags to include query params and route metadata:
+
+```bash
+yarn rescript-relay-router dump-routes \
+  --sort alphabetic \
+  --include-query-params \
+  --include-name \
+  --include-route-renderer-path \
+  --include-route-file-path
+```
+
+With metadata enabled, `url` is still emitted first:
+
+```json
+[
+  {
+    "url": "/organization/:slug/members",
+    "queryParams": {
+      "after": ":after",
+      "first": ":first"
+    },
+    "name": "Organization__Members",
+    "routeRendererPath": "src/routes/Organization__Members_route_renderer.res",
+    "routeFilePath": "src/routes/routes.json"
+  }
+]
+```
+
 ## FAQ
 
 - Check in or don't check in generated assets?

packages/rescript-relay-router/cli/RescriptRelayRouterCli__Bindings.res

@@ -36,6 +36,9 @@ module Path = {
   @module("path")
   external dirname: string => string = "dirname"
 
+  @module("path")
+  external relative: (string, string) => string = "relative"
+
   @module("path")
   external basename: string => string = "basename"
 

packages/rescript-relay-router/cli/RescriptRelayRouterCli__Bindings.resi

@@ -34,6 +34,9 @@ module Path: {
   @module("path")
   external dirname: string => string = "dirname"
 
+  @module("path")
+  external relative: (string, string) => string = "relative"
+
   @module("path")
   external basename: string => string = "basename"
 

packages/rescript-relay-router/cli/RescriptRelayRouterCli__Commands.res

@@ -2,6 +2,7 @@ module Codegen = RescriptRelayRouterCli__Codegen
 module Utils = RescriptRelayRouterCli__Utils
 module Types = RescriptRelayRouterCli__Types
 module Diagnostics = RescriptRelayRouterCli__Diagnostics
+module DumpRoutes = RescriptRelayRouterCli__DumpRoutes
 
 open RescriptRelayRouterCli__Bindings
 
@@ -239,8 +240,16 @@ let printRouteInfo = (~url, ~config) => {
   }
 }
 
-@val
-external stringifyFormatted: ('any, @as(json`null`) _, @as(json`2`) _) => string = "JSON.stringify"
+let rec dumpRoutesSortOrder = options => {
+  switch options {
+  | list{"--sort", "alphabetic", ..._}
+  | list{"--sort=alphabetic", ..._} => Types.Alphabetic
+  | list{"--sort", "definition", ..._}
+  | list{"--sort=definition", ..._} => Types.DefinitionOrder
+  | list{_, ...rest} => dumpRoutesSortOrder(rest)
+  | list{} => Types.DefinitionOrder
+  }
+}
 
 let init = () => {
   if !Utils.Config.exists() {
@@ -249,9 +258,9 @@ let init = () => {
 
     Fs.writeFileSync(
       path,
-      `module.exports = ${{
-          "routesFolderPath": "./src/routes",
-        }->stringifyFormatted}`,
+      `module.exports = ${JSON.Object(dict{
+          "routesFolderPath": JSON.String("./src/routes"),
+        })->JSON.stringify(~space=2)}`,
     )
 
     Console.log("[init] Config created at: " ++ path)
@@ -267,17 +276,17 @@ let init = () => {
       Console.log("[init] `routes.json` does not exist, creating...")
       Fs.writeFileSync(
         routesJsonPath,
-        (
-          {
-            "path": "/",
-            "name": "Root",
-            "children": [],
-          },
-          {
-            "path": "*",
-            "name": "FourOhFour",
-          },
-        )->stringifyFormatted,
+        JSON.Array([
+          JSON.Object(dict{
+            "path": JSON.String("/"),
+            "name": JSON.String("Root"),
+            "children": JSON.Array([]),
+          }),
+          JSON.Object(dict{
+            "path": JSON.String("*"),
+            "name": JSON.String("FourOhFour"),
+          }),
+        ])->JSON.stringify(~space=2),
       )
 
       Console.log("[init] Basic `routes.json` added at: " ++ routesJsonPath)
@@ -317,7 +326,14 @@ let runCli = args => {
                                                             |   have a route defined anymore.
 
   find-route <url>                                          | Shows what routes/components will render for a specific route.
-                                                            | Example: find-route /todos/123`)
+                                                            | Example: find-route /todos/123
+
+  dump-routes
+    [--sort definition|alphabetic]
+    [--include-query-params]
+    [--include-name]
+    [--include-route-renderer-path]
+    [--include-route-file-path]                             | Dumps all routes as JSON. Sorts by definition order by default.`)
     Done
   | list{"scaffold-route-renderers", ...options} =>
     let deleteRemoved = options->List.has("-delete-removed", String.equal)
@@ -384,6 +400,19 @@ let runCli = args => {
     let config = Utils.Config.load()
     printRouteInfo(~url=route, ~config)
     Done
+  | list{"dump-routes", ...options} =>
+    let config = Utils.Config.load()
+    DumpRoutes.run(
+      ~config,
+      ~options={
+        includeQueryParams: options->List.has("--include-query-params", String.equal),
+        includeName: options->List.has("--include-name", String.equal),
+        includeRouteRendererPath: options->List.has("--include-route-renderer-path", String.equal),
+        includeRouteFilePath: options->List.has("--include-route-file-path", String.equal),
+        sortOrder: dumpRoutesSortOrder(options),
+      },
+    )
+    Done
   | list{"init"} =>
     init()
     Done

packages/rescript-relay-router/cli/RescriptRelayRouterCli__DumpRoutes.res

@@ -0,0 +1,99 @@
+open RescriptRelayRouterCli__Types
+open RescriptRelayRouterCli__Bindings
+
+module Utils = RescriptRelayRouterCli__Utils
+
+let pathRelativeToCwd = path => Path.relative(Process.cwd(), path)
+
+let routeUrl = (route: printableRoute) => route.path->RoutePath.getFullRoutePath
+
+let queryParamsObject = (route: printableRoute) => {
+  let queryParams = Dict.make()
+  let queryParamKeys =
+    route.queryParams
+    ->Dict.toArray
+    ->Array.map(((key, _)) => key)
+  queryParamKeys->Array.sort(String.localeCompare)
+
+  queryParamKeys->Array.forEach(key => {
+    queryParams->Dict.set(key, JSON.String(`:${key}`))
+  })
+
+  queryParams
+}
+
+let routeRendererPath = (~config, route: printableRoute) =>
+  Utils.pathInRoutesFolder(~config, ~fileName=route.name->RouteName.getRouteRendererFileName)
+  ->pathRelativeToCwd
+
+let routeFilePath = (~config, route: printableRoute) =>
+  Utils.pathInRoutesFolder(~config, ~fileName=route.sourceFile)->pathRelativeToCwd
+
+let rec flattenRoutes = (routes: array<printableRoute>): array<printableRoute> => {
+  let allRoutes = []
+
+  routes->Array.forEach(route => {
+    allRoutes->Array.push(route)
+    route.children->flattenRoutes->Array.forEach(route => allRoutes->Array.push(route))
+  })
+
+  allRoutes
+}
+
+let urlFromDumpedRoute = route => {
+  switch route->Dict.get("url") {
+  | Some(JSON.String(url)) => url
+  | _ => ""
+  }
+}
+
+let sortRoutes = (routes, ~sortOrder) => {
+  switch sortOrder {
+  | DefinitionOrder => ()
+  | Alphabetic =>
+    routes->Array.sort((a, b) =>
+      String.localeCompare(a->urlFromDumpedRoute, b->urlFromDumpedRoute)
+    )
+  }
+}
+
+let dump = (~routes, ~config, ~options: dumpRoutesOptions) => {
+  let routes =
+    routes
+    ->flattenRoutes
+    ->Array.map(route => {
+      let item = Dict.make()
+      item->Dict.set("url", route->routeUrl->JSON.String)
+
+      if options.includeQueryParams {
+        item->Dict.set("queryParams", route->queryParamsObject->JSON.Object)
+      }
+
+      if options.includeName {
+        item->Dict.set("name", route.name->RouteName.getFullRouteName->JSON.String)
+      }
+
+      if options.includeRouteRendererPath {
+        item->Dict.set("routeRendererPath", route->routeRendererPath(~config)->JSON.String)
+      }
+
+      if options.includeRouteFilePath {
+        item->Dict.set("routeFilePath", route->routeFilePath(~config)->JSON.String)
+      }
+
+      item
+    })
+
+  routes->sortRoutes(~sortOrder=options.sortOrder)
+  routes
+}
+
+let run = (~options, ~config) => {
+  let (routes, _routeNamesDict) = Utils.readRouteStructure(config)
+  Console.log(
+    dump(~routes, ~config, ~options)
+    ->Array.map(route => JSON.Object(route))
+    ->JSON.Array
+    ->JSON.stringify(~space=2),
+  )
+}

packages/rescript-relay-router/cli/RescriptRelayRouterCli__Types.res

@@ -244,6 +244,16 @@ type config = {
   rescriptLibFolderPath: string,
 }
 
+type dumpRoutesSortOrder = DefinitionOrder | Alphabetic
+
+type dumpRoutesOptions = {
+  includeQueryParams: bool,
+  includeName: bool,
+  includeRouteRendererPath: bool,
+  includeRouteFilePath: bool,
+  sortOrder: dumpRoutesSortOrder,
+}
+
 type dependencyDeclaration = {
   dependsOn: Set.t<string>,
   dependents: Set.t<string>,