@cloudflare/util-routes 5.2.36 → 5.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Change Log
 
+## 5.4.0
+
+### Minor Changes
+
+- 3f146fca1c: Add useMatchRoute hook; fix optional parameter handling in useRoute
+
+## 5.3.0
+
+### Minor Changes
+
+- a4dce672bb: Add support for optional params
+
 ## 5.2.36
 
 ### Patch Changes

package/README.md

@@ -30,3 +30,23 @@ const domainRoute = route`${domainsRoute}/${'domainName'}`
 // => /api/v4/accounts/123/domains/abc.com
 domainRoute.toUrl({ accountId: '123', domainName: 'abc.com' })
 ```
+
+### Optional Parameters
+
+Parameters can be marked optional with a `?` suffix. TypeScript will make them optional in the `toUrl` signature:
+
+```typescript
+const apiRoute = route`/api/${'filter?'}`
+
+// filter is optional in toUrl
+apiRoute.toUrl({}) // => /api
+apiRoute.toUrl({ filter: 'active' }) // => /api/active
+
+// Composing routes with optional params
+const accountsRoute = route`/accounts/${'accountId'}`
+const accountZonesRoute = route`${accountsRoute}/zones/${'filter?'}`
+
+// TypeScript knows filter is optional
+accountZonesRoute.toUrl({ accountId: '123' }) // => /accounts/123/zones
+accountZonesRoute.toUrl({ accountId: '123', filter: 'active' }) // => /accounts/123/zones/active
+```

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from './route';
 export * from './useRoute';
+export * from './useMatchRoute';

package/dist/route.d.ts

@@ -5,9 +5,7 @@ export declare class RoutePatternResult<Param extends string> {
     /**
      * Interperolate arguments into the route pattern
      */
-    readonly toUrl: (args: {
-        [K in Param]: string;
-    }, options?: pathToRegExp.PathFunctionOptions) => string;
+    readonly toUrl: (args: RouteParams<Param>, options?: pathToRegExp.PathFunctionOptions) => string;
     readonly keys: Key[];
     readonly expression: RegExp;
     constructor(pattern: string);
@@ -20,7 +18,17 @@ export declare type RoutePatternResultFromParams<Params extends Array<string | R
     returnResult: RoutePatternResult<ValueOfArray<Result>>;
     recurse: RoutePatternResultFromParams<Tail<Params>, Prepend<ExtractParam<Head<Params>>, Result>>;
 }[Head<Params> extends never ? 'returnResult' : 'recurse'];
+export declare type StripOptional<T extends string> = T extends `${infer Name}?` ? Name : T;
+export declare type IsOptionalParam<T extends string> = T extends `${string}?` ? true : false;
 export declare type ExtractParam<T extends string | RoutePatternResult<string>> = T extends RoutePatternResult<infer S> ? S : T;
 export declare type ExtractRouteParamsInterface<T extends string | RoutePatternResult<string>> = {
     [K in ExtractParam<T>]: string | undefined;
 };
+export declare type RequiredParams<Params extends string> = Params extends `${infer P}?` ? never : Params extends string ? Params : never;
+export declare type OptionalParams<Params extends string> = Params extends `${infer P}?` ? P : never;
+/** Maps route params to their resolved types: required params are `string`, optional params are `string | undefined`. */
+export declare type RouteParams<Params extends string> = {
+    [K in RequiredParams<Params>]: string;
+} & {
+    [K in OptionalParams<Params>]?: string;
+};

package/dist/useMatchRoute.d.ts

@@ -0,0 +1,43 @@
+import { ExtractParam, RouteParams, RoutePatternResult } from './route';
+export declare function useMatchRoute<T extends RoutePatternResult<any>>(route: T, useMatch: (str: string) => any): PathMatch<RouteParams<ExtractParam<T>>> | null;
+/**
+ * A PathMatch contains info about how a PathPattern matched on a URL pathname.
+ */
+export interface PathMatch<Params extends {}> {
+    /**
+     * The names and values of dynamic parameters in the URL.
+     */
+    params: Params;
+    /**
+     * The portion of the URL pathname that was matched.
+     */
+    pathname: string;
+    /**
+     * The portion of the URL pathname that was matched before child routes.
+     */
+    pathnameBase: string;
+    /**
+     * The pattern that was used to match.
+     */
+    pattern: PathPattern;
+}
+/**
+ * A PathPattern is used to match on some portion of a URL pathname.
+ */
+export interface PathPattern<Path extends string = string> {
+    /**
+     * A string to match against a URL pathname. May contain `:id`-style segments
+     * to indicate placeholders for dynamic parameters. May also end with `/*` to
+     * indicate matching the rest of the URL pathname.
+     */
+    path: Path;
+    /**
+     * Should be `true` if the static portions of the `path` should be matched in
+     * the same case.
+     */
+    caseSensitive?: boolean;
+    /**
+     * Should be `true` if this pattern should match the entire URL pathname.
+     */
+    end?: boolean;
+}

package/dist/useRoute.d.ts

@@ -1,4 +1,2 @@
-import { ExtractParam, RoutePatternResult } from './route';
-export declare function useRoute<T extends RoutePatternResult<any>>(route: T, useParams: () => any): {
-    [K in ExtractParam<T>]: string;
-};
+import { ExtractParam, RouteParams, RoutePatternResult } from './route';
+export declare function useRoute<T extends RoutePatternResult<any>>(route: T, useParams: () => any): RouteParams<ExtractParam<T>>;

package/es/index.js

@@ -1,2 +1,3 @@
 export * from './route';
-export * from './useRoute';
+export * from './useRoute';
+export * from './useMatchRoute';

package/es/route.js

@@ -30,7 +30,9 @@ export function route(strings) {
     if (paramName instanceof RoutePatternResult) {
       result += paramName.pattern;
     } else if (typeof paramName === 'string') {
-      result += ':' + paramName;
+      var isOptional = paramName.endsWith('?');
+      var cleanName = isOptional ? paramName.slice(0, -1) : paramName;
+      result += ':' + cleanName + (isOptional ? '?' : '');
     }
 
     return result;

package/es/useMatchRoute.js

@@ -0,0 +1,6 @@
+export function useMatchRoute(route, useMatch) {
+  return useMatch(route.pattern);
+}
+/**
+ * A PathMatch contains info about how a PathPattern matched on a URL pathname.
+ */

package/es/useRoute.js

@@ -3,9 +3,10 @@ export function useRoute(route, useParams) {
   var params = useParams();
 
   for (var {
-    name
+    name,
+    optional
   } of route.keys) {
-    if (typeof params[name] !== 'string') {
+    if (!optional && typeof params[name] !== 'string') {
       throw new Error("useRoute did not find the required parameters for this route: ".concat(route.pattern, ". Missing parameter: ").concat(name));
     }
 

package/lib/index.js

@@ -28,4 +28,17 @@ Object.keys(_useRoute).forEach(function (key) {
       return _useRoute[key];
     }
   });
+});
+
+var _useMatchRoute = require("./useMatchRoute");
+
+Object.keys(_useMatchRoute).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _useMatchRoute[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _useMatchRoute[key];
+    }
+  });
 });

package/lib/route.js

@@ -50,7 +50,9 @@ function route(strings) {
     if (paramName instanceof RoutePatternResult) {
       result += paramName.pattern;
     } else if (typeof paramName === 'string') {
-      result += ':' + paramName;
+      var isOptional = paramName.endsWith('?');
+      var cleanName = isOptional ? paramName.slice(0, -1) : paramName;
+      result += ':' + cleanName + (isOptional ? '?' : '');
     }
 
     return result;

package/lib/useMatchRoute.js

@@ -0,0 +1,13 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useMatchRoute = useMatchRoute;
+
+function useMatchRoute(route, useMatch) {
+  return useMatch(route.pattern);
+}
+/**
+ * A PathMatch contains info about how a PathPattern matched on a URL pathname.
+ */

package/lib/useRoute.js

@@ -20,9 +20,11 @@ function useRoute(route, useParams) {
 
   try {
     for (_iterator.s(); !(_step = _iterator.n()).done;) {
-      var name = _step.value.name;
+      var _step$value = _step.value,
+          name = _step$value.name,
+          optional = _step$value.optional;
 
-      if (typeof params[name] !== 'string') {
+      if (!optional && typeof params[name] !== 'string') {
         throw new Error("useRoute did not find the required parameters for this route: ".concat(route.pattern, ". Missing parameter: ").concat(name));
       }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cloudflare/util-routes",
   "description": "Wraps path-to-regexp with a convenient, type-safe tagged template function",
-  "version": "5.2.36",
+  "version": "5.4.0",
   "main": "lib/index.js",
   "module": "es/index.js",
   "author": "Frontend Team <frontend@cloudflare.com>",