@kitbag/router 0.3.0 → 0.4.0

package/README.md

@@ -7,6 +7,8 @@ Type safe router for Vue.js
 [![Discord chat][discord-badge]][discord-url]
 [![Open in StackBlitz][stackblitz-badge]][stackblitz-url]
 
+<img src="https://kitbag.dev/kitbag-logo.svg" width="20%" />
+
 ## Getting Started
 
 Get Started with our [documentation](https://kitbag-router.netlify.app/)
@@ -162,4 +164,4 @@ This component gives the router the power to change the URL without reloading th
 [discord-badge]: https://img.shields.io/discord/1079625926024900739?logo=discord&label=Discord
 [discord-url]: https://discord.gg/UT7JrAxU
 [stackblitz-badge]: https://developer.stackblitz.com/img/open_in_stackblitz_small.svg
-[stackblitz-url]: https://stackblitz.com/~/github.com/kitbagjs/router-preview
+[stackblitz-url]: https://stackblitz.com/~/github.com/kitbagjs/router-preview

package/dist/kitbag-router.d.ts

@@ -270,27 +270,34 @@ declare type ExtractParamsFromPathString<TPath extends string, TParams extends R
 
 /**
  * Extracts the actual type from a parameter type, handling getters, setters, and potential undefined values.
+ * This type also is responsible for narrowing possibly undefined values when the param has a default value.
  * @template TParam - The parameter type.
  * @returns The extracted type, or 'string' as a fallback.
  */
-export declare type ExtractParamType<TParam extends Param | undefined> = TParam extends ParamGetSet<infer Type> ? undefined extends TParam ? Type | undefined : Type : TParam extends ParamGetter ? undefined extends TParam ? ReturnType<TParam> | undefined : ReturnType<TParam> : undefined extends TParam ? undefined : string;
+export declare type ExtractParamType<TParam extends Param> = TParam extends ParamGetSet<infer Type> ? TParam extends IsOptionalParam ? TParam extends ParamWithDefault ? Type : Type | undefined : Type : TParam extends ParamGetter ? ReturnType<TParam> : string;
 
 /**
  * Transforms a record of parameter types into a type with optional properties where the original type allows undefined.
  * @template TParams - The record of parameter types, possibly including undefined.
  * @returns A new type with the appropriate properties marked as optional.
  */
-export declare type ExtractParamTypes<TParams extends Record<string, Param | undefined>> = Identity<MakeOptional<{
+export declare type ExtractParamTypes<TParams extends Record<string, Param>> = Identity<MakeOptional<{
     [K in keyof TParams]: ExtractParamType<TParams[K]>;
 }>>;
 
+declare type ExtractParamTypesWithoutLosingOptional<TParams extends Record<string, Param>> = Identity<MakeOptional<{
+    [K in keyof TParams]: ExtractParamTypeWithoutLosingOptional<TParams[K]>;
+}>>;
+
+declare type ExtractParamTypeWithoutLosingOptional<TParam extends Param> = TParam extends ParamGetSet<infer Type> ? TParam extends IsOptionalParam ? Type | undefined : Type : TParam extends ParamGetter ? ReturnType<TParam> : string;
+
 /**
  * Determines the type of a path parameter from a record of parameter types, considering optional parameters.
  * @template TParam - The parameter name string.
  * @template TParams - The record object mapping parameter names to their types.
  * @returns The type associated with the parameter, or StringConstructor if unspecified; may be undefined for optional parameters.
  */
-export declare type ExtractPathParamType<TParam extends string, TParams extends Record<string, Param | undefined>> = TParam extends `?${infer OptionalParam}` ? OptionalParam extends keyof TParams ? TParams[OptionalParam] | undefined : StringConstructor | undefined : TParam extends keyof TParams ? TParams[TParam] : StringConstructor;
+export declare type ExtractPathParamType<TParam extends string, TParams extends Record<string, Param | undefined>> = TParam extends `?${infer OptionalParam}` ? OptionalParam extends keyof TParams ? TParams[OptionalParam] extends Param ? OptionalParamGetSet<TParams[OptionalParam]> : OptionalParamGetSet<StringConstructor> : OptionalParamGetSet<StringConstructor> : TParam extends keyof TParams ? TParams[TParam] : StringConstructor;
 
 declare type ExtractQueryParamsFromQueryString<TQuery extends string, TParams extends Record<string, Param | undefined> = Record<never, never>> = TQuery extends `${string}=${ParamStart}${infer Param}${ParamEnd}${infer Rest}` ? MergeParams<{
     [P in ExtractParamName<Param>]: ExtractPathParamType<Param, TParams>;
@@ -300,24 +307,27 @@ declare type ExtractRouteChildren<TRoute extends RouteProps> = TRoute extends Pa
 
 /**
  * Extracts combined types of path and query parameters for a given route, creating a unified parameter object.
+ * This parameter object type represents the expected type when accessing params from router.route or useRoute.
  * @template TRoute - The route type from which to extract and merge parameter types.
  * @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 {
+export declare type ExtractRouteParamTypes<TRoute> = TRoute extends {
     path: {
-        params: Record<string, unknown>;
+        params: infer PathParams extends Record<string, Param>;
     };
     query: {
-        params: Record<string, unknown>;
+        params: infer QueryParams extends Record<string, Param>;
     };
-}> = TRoute extends {
+} ? ExtractParamTypes<MergeParams<PathParams, QueryParams>> : Record<string, unknown>;
+
+declare type ExtractRouteParamTypesWithoutLosingOptional<TRoute> = TRoute extends {
     path: {
-        params: infer PathParams extends Record<string, Param | undefined>;
+        params: infer PathParams extends Record<string, Param>;
     };
     query: {
-        params: infer QueryParams extends Record<string, Param | undefined>;
+        params: infer QueryParams extends Record<string, Param>;
     };
-} ? ExtractParamTypes<MergeParams<PathParams, QueryParams>> : Record<string, unknown>;
+} ? ExtractParamTypesWithoutLosingOptional<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>] : [];
 
@@ -340,6 +350,10 @@ declare type Identity<T> = T extends object ? {} & {
 
 declare type IsEmptyObject<T> = T extends Record<string, never> ? (keyof T extends never ? true : false) : false;
 
+declare type IsOptionalParam = {
+    [optionalParamKey]: true;
+};
+
 /**
  * Type guard to check if a value conforms to the ParamGetSet type.
  * @param value - The value to check.
@@ -354,6 +368,8 @@ export declare function isParamGetSet(value: Param): value is ParamGetSet;
  */
 export declare function isParamGetter(value: Param): value is ParamGetter;
 
+export declare function isParamWithDefault(param: Param): param is ParamWithDefault;
+
 /**
  * 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.
@@ -365,7 +381,7 @@ export declare function isParentRouteWithoutComponent(value: RouteProps): value
 
 export declare function isRoute(route: unknown): route is RouterRoute;
 
-export declare function isRoute<TRouteKey extends RegisteredRoutesKey>(route: unknown, routeKey: TRouteKey, options: IsRouteOptions): route is RouterRoute<ResolvedRoute<RegisteredRouteMap[TRouteKey]>>;
+export declare function isRoute<TRouteKey extends RegisteredRoutesKey>(route: unknown, routeKey: TRouteKey, options?: IsRouteOptions): route is RouterRoute<ResolvedRoute<RegisteredRouteMap[TRouteKey]>>;
 
 declare type IsRouteOptions = {
     exact?: boolean;
@@ -456,6 +472,10 @@ declare type OnlyRequiredProperties<T> = {
     [K in keyof T as Extract<T[K], undefined> extends never ? K : never]: T[K];
 };
 
+declare type OptionalParamGetSet<TParam extends Param> = TParam extends ParamGetSet ? TParam & IsOptionalParam : ParamGetSet<ExtractParamType<TParam>> & IsOptionalParam;
+
+declare const optionalParamKey: unique symbol;
+
 export declare type Param = ParamGetter | ParamGetSet | RegExp | BooleanConstructor | NumberConstructor | StringConstructor | DateConstructor | JSON;
 
 export declare type ParamEnd = typeof paramEnd;
@@ -469,6 +489,7 @@ export declare type ParamExtras = {
 export declare type ParamGetSet<T = any> = {
     get: ParamGetter<T>;
     set: ParamSetter<T>;
+    defaultValue?: T;
 };
 
 export declare type ParamGetter<T = any> = (value: string, extras: ParamExtras) => T;
@@ -479,6 +500,8 @@ export declare type ParamStart = typeof paramStart;
 
 export declare const paramStart = "[";
 
+export declare type ParamWithDefault<TParam extends Param = Param> = Required<ParamGetSet<ExtractParamType<TParam>>>;
+
 /**
  * Represents properties common to parent routes in a route configuration, including hooks, path, and optional query parameters.
  */
@@ -509,9 +532,9 @@ export declare type ParentRouteProps = Partial<WithComponent | WithComponents> &
     meta?: RouteMeta;
 };
 
-declare type Path<TPath extends string = any, TParams extends PathParams<TPath> = any> = {
+declare type Path<TPath extends string = string, TParams extends PathParams<TPath> = Record<string, Param | undefined>> = {
     path: TPath;
-    params: Identity<ExtractParamsFromPathString<TPath, TParams>>;
+    params: string extends TPath ? Record<string, Param> : Identity<ExtractParamsFromPathString<TPath, TParams>>;
     toString: () => string;
 };
 
@@ -548,9 +571,9 @@ declare type Props<TComponent extends Component> = TComponent extends Constructo
 
 declare type PropsGetter<TComponent extends Component> = () => MaybePromise<Props<TComponent>>;
 
-declare type Query<T extends string = any, P extends QueryParams<T> = any> = {
-    query: T;
-    params: Identity<ExtractQueryParamsFromQueryString<T, P>>;
+declare type Query<TQuery extends string = string, TQueryParams extends QueryParams<TQuery> = Record<string, Param | undefined>> = {
+    query: TQuery;
+    params: string extends TQuery ? Record<string, Param> : Identity<ExtractQueryParamsFromQueryString<TQuery, TQueryParams>>;
     toString: () => string;
 };
 
@@ -660,7 +683,7 @@ declare type ResolvedRoute<TRoute extends Route = BaseResolvedRoute> = DeepReado
      * 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[];
+    matches: TRoute['matches'];
     /**
      * Unique identifier for the route, generated by joining route `name` by period. Key is used for routing and for matching.
      */
@@ -672,7 +695,7 @@ declare type ResolvedRoute<TRoute extends Route = BaseResolvedRoute> = DeepReado
     /**
      * Key value pair for route params, values will be the user provided value from current browser location.
      */
-    params: ExtractRouteParamTypes<TRoute>;
+    params: BaseResolvedRoute extends TRoute ? Record<string, unknown> : ExtractRouteParamTypes<TRoute>;
 }>;
 
 declare type ResolvedRouteQuery = {
@@ -799,7 +822,7 @@ declare type RouteHookSuccessResponse = {
 export declare interface RouteMeta extends Record<string, unknown> {
 }
 
-declare type RouteParamsByKey<TRoutes extends Routes, TKey extends string> = ExtractRouteParamTypes<RouteGetByKey<TRoutes, TKey>>;
+declare type RouteParamsByKey<TRoutes extends Routes, TKey extends string> = ExtractRouteParamTypesWithoutLosingOptional<RouteGetByKey<TRoutes, TKey>>;
 
 /**
  * Unifies the properties of both parent and child routes, ensuring type safety and consistency across route configurations.
@@ -1159,6 +1182,8 @@ declare type WithComponents = {
     components: Record<string, Component>;
 };
 
+export declare function withDefault<TParam extends Param>(param: TParam, defaultValue: ExtractParamType<TParam>): ParamWithDefault<TParam>;
+
 /**
  * Defines route hooks that can be applied before entering, updating, or leaving a route, as well as after these events.
  */