@kitbag/router 0.0.2 → 0.1.0

package/README.md

@@ -2,9 +2,8 @@
 
 A simple and versatile mapping utility for Typescript.
 
-[![Npm Version](https://img.shields.io/npm/v/@kitbag/router.svg)](https://www.npmjs.org/package/kitbag/router)
-[![Zip Size](https://img.badgesize.io/https:/unpkg.com/@kitbag/router/dist/kitbag-router?compression=gzip)](https:/unpkg.com/@kitbag/router/dist/kitbag-router)
-[![Netlify Status](https://api.netlify.com/api/v1/badges/d6033c76-88c3-4963-b24f-7a0bda20f271/deploy-status)](https://app.netlify.com/sites/kitbag-router/deploys)
+[![Npm Version](https://img.shields.io/npm/v/@kitbag/router.svg)](https://www.npmjs.org/package/@kitbag/router)
+[![Netlify Status](https://api.netlify.com/api/v1/badges/c12f79b8-49f9-4529-bc23-f8ffca8919a3/deploy-status)](https://app.netlify.com/sites/kitbag-router/deploys)
 
 Get started with the [documentation](https://kitbag-router.netlify.app/)
 
@@ -138,7 +137,7 @@ Give your route components a place to be mounted
 </div>
 ```
 
-This component can be mounted anywhere you want route components to be mounted. Nested routes can also have a nested `RouterView` which would be responsible for rendering any children that route may have. See more about [nested routes](https://kitbag-router.netlify.app/core-concepts/defining-routes#nested-routes).
+This component can be mounted anywhere you want route components to be mounted. Nested routes can also have a nested `RouterView` which would be responsible for rendering any children that route may have. Read more about [nested routes](https://kitbag-router.netlify.app/core-concepts/defining-routes#nested-routes).
 
 ## RouterLink
 

package/dist/kitbag-router.d.ts

@@ -74,15 +74,23 @@ export declare type AfterRouteHookResponse<TRoutes extends Routes> = RouteHookSu
 declare type AllPropertiesAreOptional<T> = Record<string, unknown> extends T ? true : IsEmptyObject<OnlyRequiredProperties<T>>;
 
 declare type BaseResolvedRoute = Route & {
-    pathParams: Record<string, unknown>;
-    queryParams: Record<string, unknown>;
+    path: {
+        params: Record<string, unknown>;
+    };
+    query: {
+        params: Record<string, unknown>;
+    };
 };
 
 declare type BaseRoute = {
     key: string;
     disabled: false;
-    pathParams: Record<string, unknown>;
-    queryParams: Record<string, unknown>;
+    path: {
+        params: Record<string, unknown>;
+    };
+    query: {
+        params: Record<string, unknown>;
+    };
 };
 
 /**
@@ -119,12 +127,30 @@ declare type BuiltInRejectionType = typeof builtInRejections[number];
 /**
  * Represents properties for child routes, including required component, name, and path.
  */
-declare type ChildRouteProps = WithHooks & {
+export declare type ChildRouteProps = WithHooks & {
+    /**
+     * Name for route, used to create route keys and in navigation.
+     */
     name: string;
+    /**
+     * Children routes, expected type comes from `createRoutes()`
+     */
     disabled?: boolean;
+    /**
+     * Path part of URL.
+     */
     path: string | Path;
+    /**
+     * Query (aka search) part of URL.
+     */
     query?: string | Query;
+    /**
+     * Type alias for Vue components, which can be either synchronous or asynchronous components.
+     */
     component: RouteComponent;
+    /**
+     * Represents additional metadata associated with a route, customizable via declaration merging.
+     */
     meta?: RouteMeta;
 };
 
@@ -144,7 +170,9 @@ declare type CombineQuery<TParent extends Query | undefined, TChild extends Quer
 } ? ToQuery<TChild> extends {
     query: infer TChildQuery extends string;
     params: infer TChildParams extends Record<string, unknown>;
-} ? MergeParams<TParentParams, TChildParams> extends QueryParams<`${TParentQuery}${TChildQuery}`> ? Query<`${TParentQuery}${TChildQuery}`, MergeParams<TParentParams, TChildParams>> : Query<'', {}> : Query<'', {}> : Query<'', {}>;
+} ? MergeParams<TParentParams, TChildParams> extends QueryParams<CombineQueryString<TParentQuery, TChildQuery>> ? Query<CombineQueryString<TParentQuery, TChildQuery>, MergeParams<TParentParams, TChildParams>> : Query<'', {}> : Query<'', {}> : Query<'', {}>;
+
+declare type CombineQueryString<TParent extends string | undefined, TChild extends string | undefined> = StringHasValue<TParent> extends true ? StringHasValue<TChild> extends true ? `${TParent}&${TChild}` : TParent : TChild;
 
 /**
  * Creates a router instance for a Vue application, equipped with methods for route handling, lifecycle hooks, and state management.
@@ -172,7 +200,7 @@ declare type CombineQuery<TParent extends Query | undefined, TChild extends Quer
 export declare function createRouter<const T extends Routes>(routes: T, options?: RouterOptions): Router<T>;
 
 /**
- * Creates an array of Route instances from a defined set of route properties, handling hierarchical route combinations.
+ * Creates an array of routes from a defined set of route properties, handling hierarchical route combinations.
  * This function also validates for duplicate parameter keys across the combined routes.
  *
  * @param routesProps - An array of route properties used to configure and create routes.
@@ -244,11 +272,19 @@ declare type ExtractRouteChildren<TRoute extends RouteProps> = TRoute extends Pa
  * @returns A record of parameter names to their respective types, extracted and merged from both path and query parameters.
  */
 export declare type ExtractRouteParamTypes<TRoute extends {
-    pathParams: Record<string, unknown>;
-    queryParams: Record<string, unknown>;
+    path: {
+        params: Record<string, unknown>;
+    };
+    query: {
+        params: Record<string, unknown>;
+    };
 }> = TRoute extends {
-    pathParams: infer PathParams extends Record<string, Param | undefined>;
-    queryParams: infer QueryParams extends Record<string, Param | undefined>;
+    path: {
+        params: infer PathParams extends Record<string, Param | undefined>;
+    };
+    query: {
+        params: infer QueryParams extends Record<string, Param | undefined>;
+    };
 } ? ExtractParamTypes<MergeParams<PathParams, QueryParams>> : Record<string, unknown>;
 
 declare type Flatten<T extends any[]> = T extends [infer First, ...infer Rest] ? First extends unknown[] ? Flatten<[...First, ...Flatten<Rest>]> : [First, ...Flatten<Rest>] : [];
@@ -286,6 +322,13 @@ export declare function isParamGetSet(value: Param): value is ParamGetSet;
  */
 export declare function isParamGetter(value: Param): value is ParamGetter;
 
+/**
+ * Type guard function to determine if a given route configuration is a parent route, based on the presence of children.
+ * @param value - The route configuration to check.
+ * @returns True if the route configuration has children, indicating it is a parent route.
+ */
+export declare function isParentRoute(value: RouteProps): value is ParentRouteProps;
+
 declare type MakeOptional<T> = {
     [P in WithOptionalProperties<T>]?: T[P];
 } & {
@@ -357,33 +400,54 @@ declare type OnlyRequiredProperties<T> = {
     [K in keyof T as Extract<T[K], undefined> extends never ? K : never]: T[K];
 };
 
-declare type Param = ParamGetter | ParamGetSet | RegExp | BooleanConstructor | NumberConstructor | StringConstructor;
+export declare type Param = ParamGetter | ParamGetSet | RegExp | BooleanConstructor | NumberConstructor | StringConstructor;
 
 declare type ParamEnd = '/';
 
-declare type ParamExtras = {
+export declare type ParamExtras = {
     invalid: (message?: string) => never;
 };
 
-declare type ParamGetSet<T = any> = {
+export declare type ParamGetSet<T = any> = {
     get: ParamGetter<T>;
     set: ParamSetter<T>;
 };
 
-declare type ParamGetter<T = any> = (value: string, extras: ParamExtras) => T;
+export declare type ParamGetter<T = any> = (value: string, extras: ParamExtras) => T;
 
-declare type ParamSetter<T = any> = (value: T, extras: ParamExtras) => string;
+export declare type ParamSetter<T = any> = (value: T, extras: ParamExtras) => string;
 
 /**
  * Represents properties common to parent routes in a route configuration, including hooks, path, and optional query parameters.
  */
-declare type ParentRouteProps = WithHooks & {
+export declare type ParentRouteProps = WithHooks & {
+    /**
+     * Name for route, used to create route keys and in navigation.
+     */
     name?: string;
+    /**
+     * Path part of URL.
+     */
     path: string | Path;
+    /**
+     * Query (aka search) part of URL.
+     */
     query?: string | Query;
+    /**
+     * Disabled routes will not ever match but can still provide physical structure, nested children behave normally.
+     */
     disabled?: boolean;
+    /**
+     * Children routes, expected type comes from `createRoutes()`
+     */
     children: Routes;
+    /**
+     * Type alias for Vue components, which can be either synchronous or asynchronous components.
+     */
     component?: RouteComponent;
+    /**
+     * Represents additional metadata associated with a route, customizable via declaration merging.
+     */
     meta?: RouteMeta;
 };
 
@@ -521,11 +585,31 @@ export declare type RegisteredRoutes = Register extends {
  */
 export declare type RegisteredRoutesKey = RoutesKey<RegisteredRoutes>;
 
+/**
+ * Represents a route that the router has matched to current browser location.
+ * @template TRoute - Underlying Route that has been resolved.
+ */
 declare type ResolvedRoute<TRoute extends Route = BaseResolvedRoute> = DeepReadonly<{
+    /**
+     * The specific route properties that were matched in the current route.
+     */
     matched: TRoute['matched'];
+    /**
+     * The specific route properties that were matched in the current route, including any ancestors.
+     * Order of routes will be from greatest ancestor to narrowest matched.
+     */
     matches: RouteProps[];
+    /**
+     * Unique identifier for the route, generated by joining route `name` by period. Key is used for routing and for matching.
+     */
     key: TRoute['key'];
+    /**
+     * Accessor for query string values from user in the current browser location.
+     */
     query: ResolvedRouteQuery;
+    /**
+     * Key value pair for route params, values will be the user provided value from current browser location.
+     */
     params: ExtractRouteParamTypes<TRoute>;
 }>;
 
@@ -535,7 +619,7 @@ declare type ResolvedRouteQuery = {
 };
 
 /**
- * Represents the structure of a route within the application.
+ * Represents the structure of a route within the application. Return value of `createRoutes`
  * @template TKey - Represents the unique key identifying the route, typically a string.
  * @template TPath - The type or structure of the route's path.
  * @template TQuery - The type or structure of the query parameters associated with the route.
@@ -563,17 +647,6 @@ export declare type Route<TKey extends string | undefined = any, TPath extends s
      * Represents the structured query of the route, including query params.
      */
     query: ToQuery<TQuery>;
-    /**
-     * Extracted path params based on the route's path type.
-     */
-    pathParams: ToPath<TPath>['params'];
-    /**
-     * Extracted query params based on the route's query type.
-     */
-    queryParams: ToQuery<TQuery>['params'];
-    /**
-     * Represents the depth of the route in the route hierarchy.
-     */
     depth: number;
     /**
      * Indicates if the route is disabled.
@@ -584,7 +657,7 @@ export declare type Route<TKey extends string | undefined = any, TPath extends s
 /**
  * Type alias for Vue components, which can be either synchronous or asynchronous components.
  */
-declare type RouteComponent = Component | DefineComponent | AsyncComponentLoader;
+export declare type RouteComponent = Component | DefineComponent | AsyncComponentLoader;
 
 declare type RouteGetByKey<TRoutes extends Routes, TKey extends RoutesKey<TRoutes>> = RoutesMap<TRoutes>[TKey];
 
@@ -656,7 +729,7 @@ declare type RouteHookSuccessResponse = {
 };
 
 /**
- * Represents additional metadata associated with a route, customizable via extensions.
+ * Represents additional metadata associated with a route, customizable via declaration merging.
  * @example
  * ```ts
  * declare module '@kitbag/router' {
@@ -666,7 +739,7 @@ declare type RouteHookSuccessResponse = {
  * }
  * ```
  */
-declare interface RouteMeta extends Record<string, unknown> {
+export declare interface RouteMeta extends Record<string, unknown> {
 }
 
 declare type RouteParamsByKey<TRoutes extends Routes, TKey extends string> = ExtractRouteParamTypes<RouteGetByKey<TRoutes, TKey>>;
@@ -674,7 +747,7 @@ declare type RouteParamsByKey<TRoutes extends Routes, TKey extends string> = Ext
 /**
  * Unifies the properties of both parent and child routes, ensuring type safety and consistency across route configurations.
  */
-declare type RouteProps = Readonly<ParentRouteProps | ChildRouteProps>;
+export declare type RouteProps = Readonly<ParentRouteProps | ChildRouteProps>;
 
 /**
  * The Route properties originally provided to `createRoutes`. The only change is normalizing meta to always default to an empty object.
@@ -786,7 +859,7 @@ to: Url | ToCallback;
 }>;
 
 /**
- * Represents an error thrown when an attempt is made to use routing functionality before the router has been installed.
+ * An error thrown when an attempt is made to use routing functionality before the router has been installed.
  */
 export declare class RouterNotInstalledError extends Error {
     constructor();
@@ -890,6 +963,8 @@ declare type RouteUpdate<TRoute extends ResolvedRoute = ResolvedRoute> = {
     (params: Partial<TRoute['params']>, options?: RouterPushOptions): Promise<void>;
 };
 
+declare type StringHasValue<T extends string | undefined> = T extends undefined ? false : '' extends T ? false : true;
+
 declare type ToCallback = (resolve: RegisteredRouter['resolve']) => string;
 
 declare type ToPath<T extends string | Path> = T extends string ? Path<T, {}> : T;
@@ -927,7 +1002,7 @@ export declare function useRoute<TRouteKey extends string & keyof RegisteredRout
 export declare function useRoute(): RouterRoute;
 
 /**
- * Represents an error thrown when there is a mismatch between an expected route and the one actually used.
+ * An error thrown when there is a mismatch between an expected route and the one actually used.
  */
 export declare class UseRouteInvalidError extends Error {
     /**