A JavaScript router that doesn't care how you render
@curi/router is a simple route configuration package for creating single page apps. Navigation is powered by hickory.
pshrmnnpm install --save @curi/routerFor more information, please check out the @curi/router page on the documentation website.
div inserted by announce sets top: 0; to prevent overflow on fixed size websites.Consolidated CHANGELOG for v2:
route.resolve is now a single function.decodeURIComponent if no param function exists for it.route.pathOptions is an object with match (for matching location) and compile (for generating pathnames) properties.route.response to route.respond.route.respond's return object includes an invalid property.prepareRoutes returns an object with match and route properties.methods property.router.route returns public data for the route with the given name.response and navigation are undefined until initial response is finalized.external value passed to createRouter options through external property.createRouter must be prepared using prepareRoutes.router.navigate sets default method.history instance for cancelling navigations.createRouter receives a history constructor function as its first argument.history option to curi options for history object configuration.automaticRedirects option. createReusable, from @hickory/in-memory, makes navigate a no-op and should be used for server rendering.emitRedirects (default true) to invisibleRedirects (default false).pathnameOptions from createRouter options.route option from createRoutes. Router interactions are no longer registered.router.url method for generating a URL string.router.url returns relative URL string when name is not provided.router.navigate takes a url string property, not name/params/query/hash.redirectTo property returned by a response function to redirect.redirect.url property is generated using history.href.title, status, and error types from response/settable response properties.meta property to response/settable response properties.meta, body, and data properties always exist on response objects. They are undefined if not set by a route's response() function.partials property from response objects.aria-live (now announce), scroll, and title side effects into package.pathname and once exports.@curi/router to @curi/types.router.navigate() returns a function that will clear the active navigation's callbacks.pathnames generated by pathname() interaction "get" calls.router.cancel() function, which let's a function know what the router is navigating and gives it the opportunity to cancel the navigation.external option when creating router. This value will be available to route.resolve functions and route.response().prepareRoutes() function to pre-build routes. Pre-building routes is encouraged and a warning message will be displayed to users who do not pre-build. In @curi/router v2, pre-building routes will be required.pathname() export.url property to response.redirectTo, which is the pathname, query and hash concatenated. Also adds the name and params to the redirectTo object.sideEffects: false hint for Webpack.once() export (moved to @curi/helpers).automaticRedirects option to router. When false, redirects will have to be triggered by the user. This is mostly useful for server-side rendering.router.respond() into router.once() for one time functions and router.observe() for observer functions.router.replaceRoutes() to router.refresh(). If called with no arguments, just re-emits a response. The emitted navigation.previous will re-use the last emitted navigation.previous.route.match to route.resolve.replaceRoutes().curi named export.once named export for match functions that should re-use their initial result.pathname named export to create a pathname route interaction.on.initial and on.every. Add match object for async functions. Keys are the values that are set on the resolved object passed to response().paths begin with a forward slash.router.respond(). Instead of registering them with an object, only the side effect observer function is passed.cancelled and finished properties to router.navigate(), which are functions to be called if the navigation is cancelled/when the navigation is finished.on.initial().Resolved typeresponse.key (still available as response.location.key).cache option from the router.on.initial() or on.every() are async. A router with a mix of synchronous and asynchronous routes will match sync routes synchronously.history.navigate() for navigation.name, params, partials, location, and key) are guaranteed to exist on a response. The other properties only exist if provided on a route.response() return object.on.initial() receives full matched route properties object.on.every() receives full matched route properties object.route interactions from route.response()name, params, and location with other matched route properties under match property passed to route.response().effect instead of fn.route.response() returns object with properties to update and removes set from the properties passed to the function. redirectTo will auto-generate the location from the provided name and params while all of the other properties will be copied directly.{ path: "(.*)" }) to handle these themselves.match.response to top level and group match.every and match.initial under on object (on.initial and on.every).initial and every resolved values with error under resolved object.router.refresh to router.replaceRoutes.match.initial or match.every function, the router will emit in synchronous mode. In synchronous mode, router.respond is not necessary for delaying the initial render.set.redirect to take an options object.once option with observe, which is false by default (reverses previous default behavior).Emitted object to response handlers. This object has response, navigation, and router properties.initial property to response handler options (default is true). When false, the response handler will not be called until a new response is emitted.Navigation object instead of an Action string. The Navigation contains properties related to a navigation but that aren't directly associated with the new Response. These are action (the navigation type) and previous (the previous Response).response and action through current function.options.emitRedirects (default true). When false, a response with a redirectTo property will not be emitted to subscribers. Instead, the automatic redirect will occur and the result of that navigation will emitted.CuriConfig is now CuriRouter, etc.).distset.title, remove route.title.match.response instead of match.finish.body function to response modifiers, removed the route.body property. This change allows the user to just reference the resolved value instead of keeping a store.set and renamed response modifier functions: setData to data, setStatus to status, and fail to errormatch property. The old preload function is now match.initial (since it is run the initial time that route matches) and load is now a mix between match.every (since it is run every time that route matches) and match.finish.config.subscribe to config.respond. This is mostly an aesthetic change, but it also makes more sense to respond once (config.respond(fn, { once: true })) than it does to subscribe once. Subscriber and UnsubscribeFn types are now ResponseHandler and RemoveResponseHandler.config.subscribe(fn, { once: true })) after regular subscribers. This allows for subscribers to be setup prior to registering the one time function. This also means that a subscriber registered after the one time function will be called before it. This should be fine because one time functions essentially serve as a ready check. If a subscriber shouldn't be called before the one time function, it should be registered in the one time function.config.subscribe an options object. There is now a once option. When once is true, the "subscriber" will only be called one time. Calling config.subscribe when { once: true } will not return an unsubscribe function. The initial argument has been removed.Action (instead of a string).route.load or route.preload has an uncaught error, the error will be set as the response's error property. Previously, Curi wouldn't emit a response. The user should still make sure to catch errors themselves, but at least now it should be more obvious what is happening.initial argument to subscribe. When false (default), the subscriber will not be called initially; when true, the subscriber will be immediately called. The default allows us to remove ready since the subscriber will not be called until a response has been resolved.ready function.createRoute now has a public property, which contains the route properties that are available to addons.Response type for TypeScript instead of AnyResponse, Response, and RedirectResponse.route.load params. The new signature is load(route, mods, addons) where route contains params, location, and name properties.AddonFactory type.params object, which is an object whose keys are params (from the path) and whose values are functions that will parse the parsed value. This can be used if any of the parsed values should not be strings. Any params that are not included in the params object will be kept as strings. Likewise, any params whose parsing function throws an error will be kept as strings.createConfig instead of addon factories. This allows addons to be configurable. The options passed to createConfig can now accept a pathnameOptions object. This can be used to change how the pathname addon encodes the generated pathname. If this is not provided, the default function (encodeURIComponent) will be used to encode pathnames. Addons now also expect a reset property, which is a function that should reset the addon to its initial state.PreloadFn and LoadFn types.Params type.route.redirect in favor of keeping everything in load. However, load now receives a fourth argument: addons. addons can be used to use any of your addons, but for redirects addons.pathname is particularly useful.redirect function. This function should return an object with two properties: to which is the string/location object to redirect to and status (optional) which is the status code number for the redirect type. redirect has been removed from the LoadModifiers so that redirecting is only done with route.redirect.RedirectResponse is created, Curi will automatically call history.replace with the string/location returned by calling route.redirect. Subscribers will still be called, so render functions should detect when the response has a redirectTo property and respond properly. Redirect responses now support the body property, so while a redirect render should be very short, you can render a redirect.SideEffect as an interface with two properties: fn which is a subscriber function and after which is a boolean. When after is false, the subscriber function will be run before any functions subscribed with config.subscribe. When after is true, the function will be called after any config.subscribe functions.createConfig(history, routes, {
sideEffects: [
// run before any subscribers
{ fn: PreSideEffect },
// run after any subscribers
{ fn: PostSideEffect, after: true }
]
});console.error). It is up to the user to make sure that their load/preload functions catch any errors.end=false would match non-exact paths.path-to-regexp v2. The changes can be seen here. Most significantly, instead of using * as a wildcard, you now need to use (.*).action type as second argument to subscriber function calls. This makes it so that subscribers and side effects both receive the same arguments.location object to route.load calls. This allows us to use the query and hash (or any other location properties) in our load function.@curi/core.Drop middleware, add sideEffects. The main reason for middleware was because history doesn't
support query parsing, but now that Curi uses Hickory, it is unnecessary. Most of the remaining use
cases seemed to be side effects, so just making that explicit. If there is a need for modifying the response, then that can be looked at, but for the time being there doesn't appear to be a good reason to add this.
Only pass a subset of the ResponseCreator methods to route load functions. These are the only ones that a developer should be using, so only pass these. The other ones could break the response, so don't give access to those.
route.title (either a string or a function).hickory package for history.path-to-regexp from the ES/CommonJS builds.config.ready function to always return the Promise that is generating (or generated) the most recent response.history@4.6.2 (no more automatic pathname encoding).response.body too early, which broke async body loading.ResponseCreator and not a response.value/call properties in favor of just one: body. This must be a function (whose return value will be set as a response's body property).setup method is called.undefined.Response to ResponseCreator (makes it easier to differentiate it from response objects).ResponseCreator.setData, which will set the data property on the response object it creates.