@native-router/core 1.7.0 → 1.8.0

package/README.md

@@ -108,8 +108,9 @@ const router = create(
 );
 ```
 
-- `parseSearchInput(search)` degrades a query string into a plain object — single-valued keys are strings, keys repeated in the query are arrays — which is also the input every schema validates
-- `parseSearch(schema, search)` resolves the schema output (async validators are awaited); `parseSearchSync` is the render/guard-time flavor and rejects async validators with a clear error
+- `parseSearchInput(search)` degrades a query string into a plain object — single-valued keys are strings, keys repeated in the query string are arrays — which is also the input every schema validates
+- `parseSearch(schema, search)` resolves the schema output (async validators are awaited); `parseSearchSync` is the render-time flavor and rejects async validators with a clear error
+- Guards: `beforeLoad` receives the level's parsed search as `ctx.search` — the schema output (parsed with `parseSearch`, so async validators work), or the degraded input on schema-less levels; an invalid search fails the resolution through the `errorHandler` channel like a data-phase search error
 - A rejected validation throws `SearchError` (a `NativeRouterError`) carrying the raw `search` and the reported `issues` — route it through your `errorHandler` like any other resolve failure
 
 ## Design principles

package/dist/index.cjs

@@ -45,6 +45,84 @@ function formatIssuePath(path) {
   return `${keys.join('.')}: `;
 }
 
+/**
+ * Parse a raw search string(e.g. `?page=2&tag=a&tag=b`) into the plain
+ * input object consumed by {@link StandardSchemaV1 search schemas}:
+ * single-valued keys are strings, keys repeated in the query string are
+ * arrays of their values. An empty search is `{}`.
+ *
+ * This is also the degraded shape every search API falls back to when no
+ * schema is given.
+ * @group Methods
+ * @category Route
+ * @param search the raw `location.search` string, with or without `?`
+ * @returns the input object for schema validation
+ */
+function parseSearchInput(search) {
+  const input = {};
+  // eslint-disable-next-line compat/compat -- URLSearchParams support is the app's polyfill concern, not bundled
+  new URLSearchParams(search).forEach((value, key) => {
+    const prev = input[key];
+    if (prev === undefined) {
+      input[key] = value;
+    } else if (Array.isArray(prev)) {
+      prev.push(value);
+    } else {
+      input[key] = [prev, value];
+    }
+  });
+  return input;
+}
+
+/**
+ * Validate a search string with a {@link StandardSchemaV1} schema — any
+ * zod/valibot/arktype schema works, no hard dependency. The string is
+ * first degraded via {@link parseSearchInput}, then parsed by the schema,
+ * so schemas can coerce(`'2'` → `2`) and normalize along the way.
+ *
+ * Async schemas(`validate` returning a promise) are awaited.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the search schema
+ * @param search the raw `location.search` string
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {SearchError} when the schema reports issues
+ */
+async function parseSearch(schema, search) {
+  const result = await schema['~standard'].validate(parseSearchInput(search));
+  if (result.issues) throw new SearchError(search, result.issues);
+  // The schema's declared output; the loose `StandardSchemaV1` default
+  // degrades to `unknown`.
+  return result.value;
+}
+
+/**
+ * Synchronous flavor of {@link parseSearch}, for render-time reads(see
+ * `useSearch` of `@native-router/react`) and route guards.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the search schema — must validate synchronously
+ * @param search the raw `location.search` string
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {SearchError} when the schema reports issues
+ * @throws when the schema validates asynchronously; use {@link parseSearch}
+ * for async schemas instead
+ */
+function parseSearchSync(schema, search) {
+  const result = schema['~standard'].validate(parseSearchInput(search));
+  if (isThenable(result)) {
+    throw new Error('The search schema validates asynchronously; parse it during resolve ' + '(parseSearch) instead of synchronously');
+  }
+  if (result.issues) throw new SearchError(search, result.issues);
+  // See parseSearch for the cast rationale.
+  return result.value;
+}
+function isThenable(value) {
+  return typeof value?.then === 'function';
+}
+
 const DEFAULT_MAX_STACK_DEPTH = 100;
 
 /** Max redirects followed by {@link resolveEntry} before giving up. */
@@ -327,6 +405,11 @@ function resolveTo(router, to, state) {
  * aborts — their resolution may be shared, so cancelling it on behalf of
  * one consumer is not sound yet.
  *
+ * A guard's context also carries the level's parsed
+ * {@link GuardContext.search search}: the {@link BaseRoute.search schema}
+ * output(its validation failure rejects this resolution with a
+ * `SearchError`), or the degraded input without a schema.
+ *
  * @group Methods
  * @category Router
  * @param router router instance
@@ -364,14 +447,37 @@ async function resolveEntry(router, location, opts) {
       } = matched[i];
       // `redirect` wins over `beforeLoad`; a non-empty string target
       // restarts the resolution at the redirected location.
-      const target = route.redirect ?? (
-      // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
-      await route.beforeLoad?.({
-        router,
-        location,
-        params: mergeMatchedParams(matched, i),
-        signal
-      }));
+      let target = route.redirect;
+      if (!target && route.beforeLoad) {
+        // The level's search schema runs before its guard, so the guard
+        // sees the parsed output(degraded input without a schema). A
+        // validation failure fails the resolution through the task's
+        // errorHandler channel — the same route a data-phase search
+        // error takes — instead of rejecting this entry, which preload
+        // consumers share.
+        let search;
+        if (route.search) {
+          try {
+            // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
+            search = await parseSearch(route.search, location.search);
+          } catch (e) {
+            return {
+              location,
+              task: Promise.reject(e).catch(errorHandler)
+            };
+          }
+        } else {
+          search = parseSearchInput(location.search);
+        }
+        // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
+        target = await route.beforeLoad({
+          router,
+          location,
+          params: mergeMatchedParams(matched, i),
+          signal,
+          search
+        });
+      }
       if (target) {
         location = toLocation(router, target, location.state);
         redirected = true;
@@ -1076,84 +1182,6 @@ function getParams(router) {
   return mergeMatchedParams(match(router, location.pathname) ?? []);
 }
 
-/**
- * Parse a raw search string(e.g. `?page=2&tag=a&tag=b`) into the plain
- * input object consumed by {@link StandardSchemaV1 search schemas}:
- * single-valued keys are strings, keys repeated in the query string are
- * arrays of their values. An empty search is `{}`.
- *
- * This is also the degraded shape every search API falls back to when no
- * schema is given.
- * @group Methods
- * @category Route
- * @param search the raw `location.search` string, with or without `?`
- * @returns the input object for schema validation
- */
-function parseSearchInput(search) {
-  const input = {};
-  // eslint-disable-next-line compat/compat -- URLSearchParams support is the app's polyfill concern, not bundled
-  new URLSearchParams(search).forEach((value, key) => {
-    const prev = input[key];
-    if (prev === undefined) {
-      input[key] = value;
-    } else if (Array.isArray(prev)) {
-      prev.push(value);
-    } else {
-      input[key] = [prev, value];
-    }
-  });
-  return input;
-}
-
-/**
- * Validate a search string with a {@link StandardSchemaV1} schema — any
- * zod/valibot/arktype schema works, no hard dependency. The string is
- * first degraded via {@link parseSearchInput}, then parsed by the schema,
- * so schemas can coerce(`'2'` → `2`) and normalize along the way.
- *
- * Async schemas(`validate` returning a promise) are awaited.
- *
- * @group Methods
- * @category Route
- * @param schema the search schema
- * @param search the raw `location.search` string
- * @returns the parsed(and possibly coerced) output of the schema
- * @throws {SearchError} when the schema reports issues
- */
-async function parseSearch(schema, search) {
-  const result = await schema['~standard'].validate(parseSearchInput(search));
-  if (result.issues) throw new SearchError(search, result.issues);
-  // The schema's declared output; the loose `StandardSchemaV1` default
-  // degrades to `unknown`.
-  return result.value;
-}
-
-/**
- * Synchronous flavor of {@link parseSearch}, for render-time reads(see
- * `useSearch` of `@native-router/react`) and route guards.
- *
- * @group Methods
- * @category Route
- * @param schema the search schema — must validate synchronously
- * @param search the raw `location.search` string
- * @returns the parsed(and possibly coerced) output of the schema
- * @throws {SearchError} when the schema reports issues
- * @throws when the schema validates asynchronously; use {@link parseSearch}
- * for async schemas instead
- */
-function parseSearchSync(schema, search) {
-  const result = schema['~standard'].validate(parseSearchInput(search));
-  if (isThenable(result)) {
-    throw new Error('The search schema validates asynchronously; parse it during resolve ' + '(parseSearch) instead of synchronously');
-  }
-  if (result.issues) throw new SearchError(search, result.issues);
-  // See parseSearch for the cast rationale.
-  return result.value;
-}
-function isThenable(value) {
-  return typeof value?.then === 'function';
-}
-
 exports.NativeRouterError = NativeRouterError;
 exports.NotFoundError = NotFoundError;
 exports.RedirectLoopError = RedirectLoopError;

package/dist/index.mjs

@@ -43,6 +43,84 @@ function formatIssuePath(path) {
   return `${keys.join('.')}: `;
 }
 
+/**
+ * Parse a raw search string(e.g. `?page=2&tag=a&tag=b`) into the plain
+ * input object consumed by {@link StandardSchemaV1 search schemas}:
+ * single-valued keys are strings, keys repeated in the query string are
+ * arrays of their values. An empty search is `{}`.
+ *
+ * This is also the degraded shape every search API falls back to when no
+ * schema is given.
+ * @group Methods
+ * @category Route
+ * @param search the raw `location.search` string, with or without `?`
+ * @returns the input object for schema validation
+ */
+function parseSearchInput(search) {
+  const input = {};
+  // eslint-disable-next-line compat/compat -- URLSearchParams support is the app's polyfill concern, not bundled
+  new URLSearchParams(search).forEach((value, key) => {
+    const prev = input[key];
+    if (prev === undefined) {
+      input[key] = value;
+    } else if (Array.isArray(prev)) {
+      prev.push(value);
+    } else {
+      input[key] = [prev, value];
+    }
+  });
+  return input;
+}
+
+/**
+ * Validate a search string with a {@link StandardSchemaV1} schema — any
+ * zod/valibot/arktype schema works, no hard dependency. The string is
+ * first degraded via {@link parseSearchInput}, then parsed by the schema,
+ * so schemas can coerce(`'2'` → `2`) and normalize along the way.
+ *
+ * Async schemas(`validate` returning a promise) are awaited.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the search schema
+ * @param search the raw `location.search` string
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {SearchError} when the schema reports issues
+ */
+async function parseSearch(schema, search) {
+  const result = await schema['~standard'].validate(parseSearchInput(search));
+  if (result.issues) throw new SearchError(search, result.issues);
+  // The schema's declared output; the loose `StandardSchemaV1` default
+  // degrades to `unknown`.
+  return result.value;
+}
+
+/**
+ * Synchronous flavor of {@link parseSearch}, for render-time reads(see
+ * `useSearch` of `@native-router/react`) and route guards.
+ *
+ * @group Methods
+ * @category Route
+ * @param schema the search schema — must validate synchronously
+ * @param search the raw `location.search` string
+ * @returns the parsed(and possibly coerced) output of the schema
+ * @throws {SearchError} when the schema reports issues
+ * @throws when the schema validates asynchronously; use {@link parseSearch}
+ * for async schemas instead
+ */
+function parseSearchSync(schema, search) {
+  const result = schema['~standard'].validate(parseSearchInput(search));
+  if (isThenable(result)) {
+    throw new Error('The search schema validates asynchronously; parse it during resolve ' + '(parseSearch) instead of synchronously');
+  }
+  if (result.issues) throw new SearchError(search, result.issues);
+  // See parseSearch for the cast rationale.
+  return result.value;
+}
+function isThenable(value) {
+  return typeof value?.then === 'function';
+}
+
 const DEFAULT_MAX_STACK_DEPTH = 100;
 
 /** Max redirects followed by {@link resolveEntry} before giving up. */
@@ -325,6 +403,11 @@ function resolveTo(router, to, state) {
  * aborts — their resolution may be shared, so cancelling it on behalf of
  * one consumer is not sound yet.
  *
+ * A guard's context also carries the level's parsed
+ * {@link GuardContext.search search}: the {@link BaseRoute.search schema}
+ * output(its validation failure rejects this resolution with a
+ * `SearchError`), or the degraded input without a schema.
+ *
  * @group Methods
  * @category Router
  * @param router router instance
@@ -362,14 +445,37 @@ async function resolveEntry(router, location, opts) {
       } = matched[i];
       // `redirect` wins over `beforeLoad`; a non-empty string target
       // restarts the resolution at the redirected location.
-      const target = route.redirect ?? (
-      // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
-      await route.beforeLoad?.({
-        router,
-        location,
-        params: mergeMatchedParams(matched, i),
-        signal
-      }));
+      let target = route.redirect;
+      if (!target && route.beforeLoad) {
+        // The level's search schema runs before its guard, so the guard
+        // sees the parsed output(degraded input without a schema). A
+        // validation failure fails the resolution through the task's
+        // errorHandler channel — the same route a data-phase search
+        // error takes — instead of rejecting this entry, which preload
+        // consumers share.
+        let search;
+        if (route.search) {
+          try {
+            // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
+            search = await parseSearch(route.search, location.search);
+          } catch (e) {
+            return {
+              location,
+              task: Promise.reject(e).catch(errorHandler)
+            };
+          }
+        } else {
+          search = parseSearchInput(location.search);
+        }
+        // eslint-disable-next-line no-await-in-loop -- guards must run in declaration order, sequentially
+        target = await route.beforeLoad({
+          router,
+          location,
+          params: mergeMatchedParams(matched, i),
+          signal,
+          search
+        });
+      }
       if (target) {
         location = toLocation(router, target, location.state);
         redirected = true;
@@ -1074,82 +1180,4 @@ function getParams(router) {
   return mergeMatchedParams(match(router, location.pathname) ?? []);
 }
 
-/**
- * Parse a raw search string(e.g. `?page=2&tag=a&tag=b`) into the plain
- * input object consumed by {@link StandardSchemaV1 search schemas}:
- * single-valued keys are strings, keys repeated in the query string are
- * arrays of their values. An empty search is `{}`.
- *
- * This is also the degraded shape every search API falls back to when no
- * schema is given.
- * @group Methods
- * @category Route
- * @param search the raw `location.search` string, with or without `?`
- * @returns the input object for schema validation
- */
-function parseSearchInput(search) {
-  const input = {};
-  // eslint-disable-next-line compat/compat -- URLSearchParams support is the app's polyfill concern, not bundled
-  new URLSearchParams(search).forEach((value, key) => {
-    const prev = input[key];
-    if (prev === undefined) {
-      input[key] = value;
-    } else if (Array.isArray(prev)) {
-      prev.push(value);
-    } else {
-      input[key] = [prev, value];
-    }
-  });
-  return input;
-}
-
-/**
- * Validate a search string with a {@link StandardSchemaV1} schema — any
- * zod/valibot/arktype schema works, no hard dependency. The string is
- * first degraded via {@link parseSearchInput}, then parsed by the schema,
- * so schemas can coerce(`'2'` → `2`) and normalize along the way.
- *
- * Async schemas(`validate` returning a promise) are awaited.
- *
- * @group Methods
- * @category Route
- * @param schema the search schema
- * @param search the raw `location.search` string
- * @returns the parsed(and possibly coerced) output of the schema
- * @throws {SearchError} when the schema reports issues
- */
-async function parseSearch(schema, search) {
-  const result = await schema['~standard'].validate(parseSearchInput(search));
-  if (result.issues) throw new SearchError(search, result.issues);
-  // The schema's declared output; the loose `StandardSchemaV1` default
-  // degrades to `unknown`.
-  return result.value;
-}
-
-/**
- * Synchronous flavor of {@link parseSearch}, for render-time reads(see
- * `useSearch` of `@native-router/react`) and route guards.
- *
- * @group Methods
- * @category Route
- * @param schema the search schema — must validate synchronously
- * @param search the raw `location.search` string
- * @returns the parsed(and possibly coerced) output of the schema
- * @throws {SearchError} when the schema reports issues
- * @throws when the schema validates asynchronously; use {@link parseSearch}
- * for async schemas instead
- */
-function parseSearchSync(schema, search) {
-  const result = schema['~standard'].validate(parseSearchInput(search));
-  if (isThenable(result)) {
-    throw new Error('The search schema validates asynchronously; parse it during resolve ' + '(parseSearch) instead of synchronously');
-  }
-  if (result.issues) throw new SearchError(search, result.issues);
-  // See parseSearch for the cast rationale.
-  return result.value;
-}
-function isThenable(value) {
-  return typeof value?.then === 'function';
-}
-
 export { NativeRouterError, NotFoundError, RedirectLoopError, SearchError, back, cancel, commit, commitReplace, create, createHref, forward, getCurrentView, getLocation, getParams, go, initHistoryStack, invalidate, listen, match, mergeMatchedParams, navigate, parseSearch, parseSearchInput, parseSearchSync, preload, refresh, resolve, resolveEntry, resolveTo, setBlocker, setOptions, toLocation };

package/dist/types/router.d.ts

@@ -100,6 +100,11 @@ export declare function resolveTo<R extends BaseRoute = BaseRoute, V = any>(rout
  * aborts — their resolution may be shared, so cancelling it on behalf of
  * one consumer is not sound yet.
  *
+ * A guard's context also carries the level's parsed
+ * {@link GuardContext.search search}: the {@link BaseRoute.search schema}
+ * output(its validation failure rejects this resolution with a
+ * `SearchError`), or the degraded input without a schema.
+ *
  * @group Methods
  * @category Router
  * @param router router instance

package/dist/types/types.d.ts

@@ -143,10 +143,19 @@ export type ExtractPathParams<P extends string> = P extends `${infer Head}/${inf
  * `params` are accumulated from the root level down to the level that
  * owns the guard, so a guard only sees params of itself and its parents.
  */
-export type GuardContext<R extends BaseRoute = BaseRoute> = {
+export type GuardContext<R extends BaseRoute = BaseRoute, S = unknown> = {
     router: RouterInstance<R>;
     location: Location;
     params: Record<string, string>;
+    /**
+     * The search the guard sees: the route's {@link BaseRoute.search search
+     * schema} output(parsed and validated before the guard runs), or the
+     * degraded {@link SearchInput} when the route declares no schema. The
+     * loose default types it `unknown` — narrow it in the guard, or let a
+     * typed route table(see `createRoutes` of `@native-router/react`)
+     * derive it from the schema.
+     */
+    search: S;
     /**
      * Aborted when this navigation is superseded by a newer one or
      * cancelled(see {@link RouterInstance.cancelAll cancel}); pass it to
@@ -173,7 +182,11 @@ export type BaseRoute<T = any> = {
     search?: StandardSchemaV1;
     /**
      * Route guard invoked before the view resolves. Return a path string
-     * to redirect, or nothing(`undefined`) to continue.
+     * to redirect, or nothing(`undefined`) to continue. The guard's
+     * {@link GuardContext context} carries the level's parsed
+     * {@link GuardContext.search search}(schema output, or the degraded
+     * input without a schema); an invalid search fails the resolution at
+     * this phase like any other navigation error.
      */
     beforeLoad?(ctx: GuardContext<BaseRoute<T>>): Awaitable<string | void>;
 } & Omit<T, 'path' | 'children'>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@native-router/core",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",