@solidjs/router - npm Package Compare versions

Comparing version 0.15.1 to 0.15.2

dist/data/query.d.ts

 import type { CacheEntry, NarrowResponse } from "../types.js";
+/**
+ * Revalidates the given cache entry/entries.
+ */
 export declare function revalidate(key?: string | string[] | void, force?: boolean): Promise<void>;
@@ -3,0 +6,0 @@ export declare function cacheKeyOp(key: string | string[] | void, fn: (cacheEntry: CacheEntry) => void): void;

dist/data/query.js

@@ -27,2 +27,5 @@ import { createSignal, getListener, getOwner, onCleanup, sharedConfig, startTransition } from "solid-js";
 }
+/**
+ * Revalidates the given cache entry/entries.
+ */
 export function revalidate(key, force = true) {
@@ -29,0 +32,0 @@ return startTransition(() => {

dist/index.js

@@ -254,5 +254,64 @@ import { isServer, getRequestEvent, createComponent as createComponent$1, memo, delegateEvents, spread, mergeProps as mergeProps$1, template } from 'solid-js/web';
 };
+
+/**
+ * Retrieves method to do navigation. The method accepts a path to navigate to and an optional object with the following options:
+ * 
+ * - resolve (*boolean*, default `true`): resolve the path against the current route
+ * - replace (*boolean*, default `false`): replace the history entry
+ * - scroll (*boolean*, default `true`): scroll to top after navigation
+ * - state (*any*, default `undefined`): pass custom state to `location.state`
+ * 
+ * **Note**: The state is serialized using the structured clone algorithm which does not support all object types.
+ * 
+ * @example
+ * ```js
+ * const navigate = useNavigate();
+ * 
+ * if (unauthorized) {
+ *   navigate("/login", { replace: true });
+ * }
+ * ```
+ */
 const useNavigate = () => useRouter().navigatorFactory();
+
+/**
+ * Retrieves reactive `location` object useful for getting things like `pathname`.
+ * 
+ * @example
+ * ```js
+ * const location = useLocation();
+ * 
+ * const pathname = createMemo(() => parsePath(location.pathname));
+ * ```
+ */
 const useLocation = () => useRouter().location;
+
+/**
+ * Retrieves signal that indicates whether the route is currently in a *Transition*.
+ * Useful for showing stale/pending state when the route resolution is *Suspended* during concurrent rendering.
+ * 
+ * @example
+ * ```js
+ * const isRouting = useIsRouting();
+ * 
+ * return (
+ *   <div classList={{ "grey-out": isRouting() }}>
+ *     <MyAwesomeContent />
+ *   </div>
+ * );
+ * ```
+ */
 const useIsRouting = () => useRouter().isRouting;
+
+/**
+ * usePreloadRoute returns a function that can be used to preload a route manual.
+ * This is what happens automatically with link hovering and similar focus based behavior, but it is available here as an API.
+ * 
+ * @example
+ * ```js
+ * const preload = usePreloadRoute();
+ * 
+ * preload(`/users/settings`, { preloadData: true });
+ * ```
+ */
 const usePreloadRoute = () => {
@@ -262,2 +321,14 @@ const pre = useRouter().preloadRoute;
 };
+
+/**
+ * `useMatch` takes an accessor that returns the path and creates a `Memo` that returns match information if the current path matches the provided path.
+ * Useful for determining if a given path matches the current route.
+ * 
+ * @example
+ * ```js
+ * const match = useMatch(() => props.href);
+ * 
+ * return <div classList={{ active: Boolean(match()) }} />;
+ * ```
+ */
 const useMatch = (path, matchFilters) => {
@@ -273,4 +344,56 @@ const location = useLocation();
 };
+
+/**
+ * `useCurrentMatches` returns all the matches for the current matched route.
+ * Useful for getting all the route information.
+ * 
+ * @example
+ * ```js
+ * const matches = useCurrentMatches();
+ * 
+ * const breadcrumbs = createMemo(() => matches().map(m => m.route.info.breadcrumb))
+ * ```
+ */
 const useCurrentMatches = () => useRouter().matches;
+
+/**
+ * Retrieves a reactive, store-like object containing the current route path parameters as defined in the Route.
+ * 
+ * @example
+ * ```js
+ * const params = useParams();
+ * 
+ * // fetch user based on the id path parameter
+ * const [user] = createResource(() => params.id, fetchUser);
+ * ```
+ */
 const useParams = () => useRouter().params;
+
+/**
+ * Retrieves a tuple containing a reactive object to read the current location's query parameters and a method to update them.
+ * The object is a proxy so you must access properties to subscribe to reactive updates.
+ * **Note** that values will be strings and property names will retain their casing.
+ * 
+ * The setter method accepts an object whose entries will be merged into the current query string.
+ * Values `''`, `undefined` and `null` will remove the key from the resulting query string.
+ * Updates will behave just like a navigation and the setter accepts the same optional second parameter as `navigate` and auto-scrolling is disabled by default.
+ * 
+ * @examples
+ * ```js
+ * const [searchParams, setSearchParams] = useSearchParams();
+ * 
+ * return (
+ *   <div>
+ *     <span>Page: {searchParams.page}</span>
+ *     <button
+ *       onClick={() =>
+ *         setSearchParams({ page: (parseInt(searchParams.page) || 0) + 1 })
+ *       }
+ *     >
+ *       Next Page
+ *     </button>
+ *   </div>
+ * );
+ * ```
+ */
 const useSearchParams = () => {
@@ -289,2 +412,30 @@ const location = useLocation();
 };
+
+/**
+ * useBeforeLeave takes a function that will be called prior to leaving a route.
+ * The function will be called with:
+ * 
+ * - from (*Location*): current location (before change).
+ * - to (*string | number*): path passed to `navigate`.
+ * - options (*NavigateOptions*): options passed to navigate.
+ * - preventDefault (*function*): call to block the route change.
+ * - defaultPrevented (*readonly boolean*): `true` if any previously called leave handlers called `preventDefault`.
+ * - retry (*function*, force?: boolean ): call to retry the same navigation, perhaps after confirming with the user. Pass `true` to skip running the leave handlers again (i.e. force navigate without confirming).
+ * 
+ * @example
+ * ```js
+ * useBeforeLeave((e: BeforeLeaveEventArgs) => {
+ *   if (form.isDirty && !e.defaultPrevented) {
+ *     // preventDefault to block immediately and prompt user async
+ *     e.preventDefault();
+ *     setTimeout(() => {
+ *       if (window.confirm("Discard unsaved changes - are you sure?")) {
+ *         // user wants to proceed anyway so retry with force=true
+ *         e.retry(true);
+ *       }
+ *     }, 100);
+ *   }
+ * });
+ * ```
+ */
 const useBeforeLeave = listener => {
@@ -469,3 +620,3 @@ const s = useRouter().beforeLeave.subscribe({
       resetErrorBoundaries();
-      if (!isServer) submissions[1]([]);
+      if (!isServer) submissions[1](subs => subs.filter(s => s.pending));
     }).finally(() => {
@@ -840,3 +991,3 @@ if (lastTransitionTarget !== newTarget) return;
 function intercept([value, setValue], get, set) {
-  return [get ? () => get(value()) : value, set ? v => setValue(set(v)) : setValue];
+  return [value, set ? v => setValue(set(v)) : setValue];
 }
@@ -915,2 +1066,6 @@ function createRouter(config) {
 }
+
+/**
+ * Revalidates the given cache entry/entries.
+ */
 function revalidate(key, force = true) {
@@ -917,0 +1072,0 @@ return startTransition(() => {

dist/routing.d.ts

@@ -9,12 +9,154 @@ import { JSX, Accessor } from "solid-js";
 export declare const useHref: (to: () => string | undefined) => Accessor<string | undefined>;
+/**
+ * Retrieves method to do navigation. The method accepts a path to navigate to and an optional object with the following options:
+ *
+ * - resolve (*boolean*, default `true`): resolve the path against the current route
+ * - replace (*boolean*, default `false`): replace the history entry
+ * - scroll (*boolean*, default `true`): scroll to top after navigation
+ * - state (*any*, default `undefined`): pass custom state to `location.state`
+ *
+ * **Note**: The state is serialized using the structured clone algorithm which does not support all object types.
+ *
+ * @example
+ * ```js
+ * const navigate = useNavigate();
+ *
+ * if (unauthorized) {
+ *   navigate("/login", { replace: true });
+ * }
+ * ```
+ */
 export declare const useNavigate: () => Navigator;
+/**
+ * Retrieves reactive `location` object useful for getting things like `pathname`.
+ *
+ * @example
+ * ```js
+ * const location = useLocation();
+ *
+ * const pathname = createMemo(() => parsePath(location.pathname));
+ * ```
+ */
 export declare const useLocation: <S = unknown>() => Location<S>;
+/**
+ * Retrieves signal that indicates whether the route is currently in a *Transition*.
+ * Useful for showing stale/pending state when the route resolution is *Suspended* during concurrent rendering.
+ *
+ * @example
+ * ```js
+ * const isRouting = useIsRouting();
+ *
+ * return (
+ *   <div classList={{ "grey-out": isRouting() }}>
+ *     <MyAwesomeContent />
+ *   </div>
+ * );
+ * ```
+ */
 export declare const useIsRouting: () => () => boolean;
+/**
+ * usePreloadRoute returns a function that can be used to preload a route manual.
+ * This is what happens automatically with link hovering and similar focus based behavior, but it is available here as an API.
+ *
+ * @example
+ * ```js
+ * const preload = usePreloadRoute();
+ *
+ * preload(`/users/settings`, { preloadData: true });
+ * ```
+ */
 export declare const usePreloadRoute: () => (url: string | URL, options?: {
     preloadData?: boolean;
 }) => void;
-export declare const useMatch: <S extends string>(path: () => S, matchFilters?: MatchFilters<S> | undefined) => Accessor<import("./types.js").PathMatch | undefined>;
+/**
+ * `useMatch` takes an accessor that returns the path and creates a `Memo` that returns match information if the current path matches the provided path.
+ * Useful for determining if a given path matches the current route.
+ *
+ * @example
+ * ```js
+ * const match = useMatch(() => props.href);
+ *
+ * return <div classList={{ active: Boolean(match()) }} />;
+ * ```
+ */
+export declare const useMatch: <S extends string>(path: () => S, matchFilters?: MatchFilters<S>) => Accessor<import("./types.js").PathMatch | undefined>;
+/**
+ * `useCurrentMatches` returns all the matches for the current matched route.
+ * Useful for getting all the route information.
+ *
+ * @example
+ * ```js
+ * const matches = useCurrentMatches();
+ *
+ * const breadcrumbs = createMemo(() => matches().map(m => m.route.info.breadcrumb))
+ * ```
+ */
 export declare const useCurrentMatches: () => () => RouteMatch[];
+/**
+ * Retrieves a reactive, store-like object containing the current route path parameters as defined in the Route.
+ *
+ * @example
+ * ```js
+ * const params = useParams();
+ *
+ * // fetch user based on the id path parameter
+ * const [user] = createResource(() => params.id, fetchUser);
+ * ```
+ */
 export declare const useParams: <T extends Params>() => T;
+/**
+ * Retrieves a tuple containing a reactive object to read the current location's query parameters and a method to update them.
+ * The object is a proxy so you must access properties to subscribe to reactive updates.
+ * **Note** that values will be strings and property names will retain their casing.
+ *
+ * The setter method accepts an object whose entries will be merged into the current query string.
+ * Values `''`, `undefined` and `null` will remove the key from the resulting query string.
+ * Updates will behave just like a navigation and the setter accepts the same optional second parameter as `navigate` and auto-scrolling is disabled by default.
+ *
+ * @examples
+ * ```js
+ * const [searchParams, setSearchParams] = useSearchParams();
+ *
+ * return (
+ *   <div>
+ *     <span>Page: {searchParams.page}</span>
+ *     <button
+ *       onClick={() =>
+ *         setSearchParams({ page: (parseInt(searchParams.page) || 0) + 1 })
+ *       }
+ *     >
+ *       Next Page
+ *     </button>
+ *   </div>
+ * );
+ * ```
+ */
 export declare const useSearchParams: <T extends SearchParams>() => [Partial<T>, (params: SetSearchParams, options?: Partial<NavigateOptions>) => void];
+/**
+ * useBeforeLeave takes a function that will be called prior to leaving a route.
+ * The function will be called with:
+ *
+ * - from (*Location*): current location (before change).
+ * - to (*string | number*): path passed to `navigate`.
+ * - options (*NavigateOptions*): options passed to navigate.
+ * - preventDefault (*function*): call to block the route change.
+ * - defaultPrevented (*readonly boolean*): `true` if any previously called leave handlers called `preventDefault`.
+ * - retry (*function*, force?: boolean ): call to retry the same navigation, perhaps after confirming with the user. Pass `true` to skip running the leave handlers again (i.e. force navigate without confirming).
+ *
+ * @example
+ * ```js
+ * useBeforeLeave((e: BeforeLeaveEventArgs) => {
+ *   if (form.isDirty && !e.defaultPrevented) {
+ *     // preventDefault to block immediately and prompt user async
+ *     e.preventDefault();
+ *     setTimeout(() => {
+ *       if (window.confirm("Discard unsaved changes - are you sure?")) {
+ *         // user wants to proceed anyway so retry with force=true
+ *         e.retry(true);
+ *       }
+ *     }, 100);
+ *   }
+ * });
+ * ```
+ */
 export declare const useBeforeLeave: (listener: (e: BeforeLeaveEventArgs) => void) => void;
@@ -21,0 +163,0 @@ export declare function createRoutes(routeDef: RouteDefinition, base?: string): RouteDescription[];

dist/routing.js

@@ -23,5 +23,60 @@ import { runWithOwner, batch } from "solid-js";
 };
+/**
+ * Retrieves method to do navigation. The method accepts a path to navigate to and an optional object with the following options:
+ *
+ * - resolve (*boolean*, default `true`): resolve the path against the current route
+ * - replace (*boolean*, default `false`): replace the history entry
+ * - scroll (*boolean*, default `true`): scroll to top after navigation
+ * - state (*any*, default `undefined`): pass custom state to `location.state`
+ *
+ * **Note**: The state is serialized using the structured clone algorithm which does not support all object types.
+ *
+ * @example
+ * ```js
+ * const navigate = useNavigate();
+ *
+ * if (unauthorized) {
+ *   navigate("/login", { replace: true });
+ * }
+ * ```
+ */
 export const useNavigate = () => useRouter().navigatorFactory();
+/**
+ * Retrieves reactive `location` object useful for getting things like `pathname`.
+ *
+ * @example
+ * ```js
+ * const location = useLocation();
+ *
+ * const pathname = createMemo(() => parsePath(location.pathname));
+ * ```
+ */
 export const useLocation = () => useRouter().location;
+/**
+ * Retrieves signal that indicates whether the route is currently in a *Transition*.
+ * Useful for showing stale/pending state when the route resolution is *Suspended* during concurrent rendering.
+ *
+ * @example
+ * ```js
+ * const isRouting = useIsRouting();
+ *
+ * return (
+ *   <div classList={{ "grey-out": isRouting() }}>
+ *     <MyAwesomeContent />
+ *   </div>
+ * );
+ * ```
+ */
 export const useIsRouting = () => useRouter().isRouting;
+/**
+ * usePreloadRoute returns a function that can be used to preload a route manual.
+ * This is what happens automatically with link hovering and similar focus based behavior, but it is available here as an API.
+ *
+ * @example
+ * ```js
+ * const preload = usePreloadRoute();
+ *
+ * preload(`/users/settings`, { preloadData: true });
+ * ```
+ */
 export const usePreloadRoute = () => {
@@ -31,2 +86,13 @@ const pre = useRouter().preloadRoute;
 };
+/**
+ * `useMatch` takes an accessor that returns the path and creates a `Memo` that returns match information if the current path matches the provided path.
+ * Useful for determining if a given path matches the current route.
+ *
+ * @example
+ * ```js
+ * const match = useMatch(() => props.href);
+ *
+ * return <div classList={{ active: Boolean(match()) }} />;
+ * ```
+ */
 export const useMatch = (path, matchFilters) => {
@@ -43,4 +109,53 @@ const location = useLocation();
 };
+/**
+ * `useCurrentMatches` returns all the matches for the current matched route.
+ * Useful for getting all the route information.
+ *
+ * @example
+ * ```js
+ * const matches = useCurrentMatches();
+ *
+ * const breadcrumbs = createMemo(() => matches().map(m => m.route.info.breadcrumb))
+ * ```
+ */
 export const useCurrentMatches = () => useRouter().matches;
+/**
+ * Retrieves a reactive, store-like object containing the current route path parameters as defined in the Route.
+ *
+ * @example
+ * ```js
+ * const params = useParams();
+ *
+ * // fetch user based on the id path parameter
+ * const [user] = createResource(() => params.id, fetchUser);
+ * ```
+ */
 export const useParams = () => useRouter().params;
+/**
+ * Retrieves a tuple containing a reactive object to read the current location's query parameters and a method to update them.
+ * The object is a proxy so you must access properties to subscribe to reactive updates.
+ * **Note** that values will be strings and property names will retain their casing.
+ *
+ * The setter method accepts an object whose entries will be merged into the current query string.
+ * Values `''`, `undefined` and `null` will remove the key from the resulting query string.
+ * Updates will behave just like a navigation and the setter accepts the same optional second parameter as `navigate` and auto-scrolling is disabled by default.
+ *
+ * @examples
+ * ```js
+ * const [searchParams, setSearchParams] = useSearchParams();
+ *
+ * return (
+ *   <div>
+ *     <span>Page: {searchParams.page}</span>
+ *     <button
+ *       onClick={() =>
+ *         setSearchParams({ page: (parseInt(searchParams.page) || 0) + 1 })
+ *       }
+ *     >
+ *       Next Page
+ *     </button>
+ *   </div>
+ * );
+ * ```
+ */
 export const useSearchParams = () => {
@@ -59,2 +174,29 @@ const location = useLocation();
 };
+/**
+ * useBeforeLeave takes a function that will be called prior to leaving a route.
+ * The function will be called with:
+ *
+ * - from (*Location*): current location (before change).
+ * - to (*string | number*): path passed to `navigate`.
+ * - options (*NavigateOptions*): options passed to navigate.
+ * - preventDefault (*function*): call to block the route change.
+ * - defaultPrevented (*readonly boolean*): `true` if any previously called leave handlers called `preventDefault`.
+ * - retry (*function*, force?: boolean ): call to retry the same navigation, perhaps after confirming with the user. Pass `true` to skip running the leave handlers again (i.e. force navigate without confirming).
+ *
+ * @example
+ * ```js
+ * useBeforeLeave((e: BeforeLeaveEventArgs) => {
+ *   if (form.isDirty && !e.defaultPrevented) {
+ *     // preventDefault to block immediately and prompt user async
+ *     e.preventDefault();
+ *     setTimeout(() => {
+ *       if (window.confirm("Discard unsaved changes - are you sure?")) {
+ *         // user wants to proceed anyway so retry with force=true
+ *         e.retry(true);
+ *       }
+ *     }, 100);
+ *   }
+ * });
+ * ```
+ */
 export const useBeforeLeave = (listener) => {
@@ -234,3 +376,3 @@ const s = useRouter().beforeLeave.subscribe({
             if (!isServer)
-                submissions[1]([]);
+                submissions[1](subs => subs.filter(s => s.pending));
         }).finally(() => {
@@ -237,0 +379,0 @@ if (lastTransitionTarget !== newTarget)

package.json

@@ -9,3 +9,3 @@ {
   "license": "MIT",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "homepage": "https://github.com/solidjs/solid-router#readme",
@@ -33,19 +33,19 @@ "repository": {
   "devDependencies": {
-    "@babel/core": "^7.23.9",
-    "@babel/preset-typescript": "^7.23.3",
-    "@changesets/cli": "^2.27.1",
+    "@babel/core": "^7.26.0",
+    "@babel/preset-typescript": "^7.26.0",
+    "@changesets/cli": "^2.27.10",
     "@rollup/plugin-babel": "6.0.4",
-    "@rollup/plugin-node-resolve": "15.2.3",
+    "@rollup/plugin-node-resolve": "15.3.0",
     "@rollup/plugin-terser": "0.4.4",
-    "@types/jest": "^29.5.11",
-    "@types/node": "^20.11.14",
-    "babel-preset-solid": "^1.9.2",
-    "jsdom": "^24.0.0",
-    "prettier": "^2.7.0",
-    "rollup": "^4.9.6",
-    "solid-js": "^1.9.2",
-    "typescript": "^5.3.3",
-    "vite": "^5.4.8",
-    "vite-plugin-solid": "^2.9.1",
-    "vitest": "^2.1.2"
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.10.0",
+    "babel-preset-solid": "^1.9.3",
+    "jsdom": "^25.0.1",
+    "prettier": "^3.4.1",
+    "rollup": "^4.27.4",
+    "solid-js": "^1.9.3",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.0",
+    "vite-plugin-solid": "^2.11.0",
+    "vitest": "^2.1.6"
   },
@@ -52,0 +52,0 @@ "peerDependencies": {

README.md

@@ -821,3 +821,3 @@ <p>
 
-Retrieves reactive `location` object useful for getting things like `pathname`
+Retrieves reactive `location` object useful for getting things like `pathname`.
 
@@ -884,3 +884,4 @@ ```js
 const matches = useCurrentMatches();
-const breadcrumbs = createMemo(() => matches().map(m => m.route.info.breadcrumb))
+
+const breadcrumbs = createMemo(() => matches().map(m => m.route.info.breadcrumb));
 ```
@@ -903,7 +904,7 @@
 - from (_Location_): current location (before change).
-- to (_string | number_}: path passed to `navigate`.
-- options (_NavigateOptions_}: options passed to `navigate`.
-- preventDefault (_void function_): call to block the route change.
-- defaultPrevented (_readonly boolean_): true if any previously called leave handlers called preventDefault().
-- retry (_void function_, _force?: boolean_ ): call to retry the same navigation, perhaps after confirming with the user. Pass `true` to skip running the leave handlers again (ie force navigate without confirming).
+- to (_string | number_): path passed to `navigate`.
+- options (_NavigateOptions_): options passed to `navigate`.
+- preventDefault (_function_): call to block the route change.
+- defaultPrevented (_readonly boolean_): `true` if any previously called leave handlers called `preventDefault`.
+- retry (_function_, _force?: boolean_ ): call to retry the same navigation, perhaps after confirming with the user. Pass `true` to skip running the leave handlers again (i.e. force navigate without confirming).
 
@@ -910,0 +911,0 @@ Example usage:

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

198248

increased by7.96%

Lines of code

4545

increased by10.58%

Number of lines in readme file

1002

increased by0.1%

No dependency changes