@kitbag/router 0.9.0 → 0.10.1

package/dist/kitbag-router.d.ts

@@ -131,21 +131,27 @@ declare const builtInRejections: ['NotFound'];
 
 declare type BuiltInRejectionType = typeof builtInRejections[number];
 
+declare type CombineHash<TParent extends Hash, TChild extends Hash> = ToHash<TParent> extends {
+    value: infer TParentHash extends string;
+} ? ToHash<TChild> extends {
+    value: infer ChildHash extends string;
+} ? Hash<`${TParentHash}${ChildHash}`> : TParent : Hash;
+
 declare type CombineMeta<TParent extends Record<string, unknown>, TChild extends Record<string, unknown>> = TParent & TChild;
 
 declare type CombinePath<TParent extends Path, TChild extends Path> = ToPath<TParent> extends {
-    path: infer TParentPath extends string;
+    value: infer TParentPath extends string;
     params: infer TParentParams extends Record<string, unknown>;
 } ? ToPath<TChild> extends {
-    path: infer TChildPath extends string;
+    value: infer TChildPath extends string;
     params: infer TChildParams extends Record<string, unknown>;
 } ? RemoveLeadingQuestionMarkFromKeys<TParentParams> & RemoveLeadingQuestionMarkFromKeys<TChildParams> extends PathParamsWithParamNameExtracted<`${TParentPath}${TChildPath}`> ? Path<`${TParentPath}${TChildPath}`, RemoveLeadingQuestionMarkFromKeys<TParentParams> & RemoveLeadingQuestionMarkFromKeys<TChildParams>> : Path<'', {}> : Path<'', {}> : Path<'', {}>;
 
 declare type CombineQuery<TParent extends Query, TChild extends Query> = ToQuery<TParent> extends {
-    query: infer TParentQuery extends string;
+    value: infer TParentQuery extends string;
     params: infer TParentParams extends Record<string, unknown>;
 } ? ToQuery<TChild> extends {
-    query: infer TChildQuery extends string;
+    value: infer TChildQuery extends string;
     params: infer TChildParams extends Record<string, unknown>;
 } ? RemoveLeadingQuestionMarkFromKeys<TParentParams> & RemoveLeadingQuestionMarkFromKeys<TChildParams> extends QueryParamsWithParamNameExtracted<CombineQueryString<TParentQuery, TChildQuery>> ? Query<CombineQueryString<TParentQuery, TChildQuery>, RemoveLeadingQuestionMarkFromKeys<TParentParams> & RemoveLeadingQuestionMarkFromKeys<TChildParams>> : Query<'', {}> : Query<'', {}> : Query<'', {}>;
 
@@ -179,9 +185,9 @@ declare type ComponentPropsGetter<TComponent extends Component> = () => MaybePro
 
 declare type Constructor = new (...args: any) => any;
 
-export declare function createExternalRoute<const THost extends string | Host, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined>(options: CreateRouteOptions<TName, TPath, TQuery> & WithHost<THost> & WithoutParent): Route<ToName<TName>, ToHost<THost>, ToPath<TPath>, ToQuery<TQuery>>;
+export declare function createExternalRoute<const THost extends string | Host, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const THash extends string | Hash | undefined = undefined, const TMeta extends RouteMeta = RouteMeta>(options: CreateRouteOptions<TName, TPath, TQuery> & WithHost<THost> & WithoutParent): Route<ToName<TName>, ToHost<THost>, ToPath<TPath>, ToQuery<TQuery>, ToHash<THash>, TMeta>;
 
-export declare function createExternalRoute<const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined>(options: CreateRouteOptions<TName, TPath, TQuery> & WithoutHost & WithParent<TParent>): Route<ToName<TName>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>>;
+export declare function createExternalRoute<const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const THash extends string | Hash | undefined = undefined, const TMeta extends RouteMeta = RouteMeta>(options: CreateRouteOptions<TName, TPath, TQuery> & WithoutHost & WithParent<TParent>): Route<ToName<TName>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>, CombineHash<TParent['hash'], ToHash<THash>>, CombineMeta<TMeta, TParent['meta']>>;
 
 export declare function createParam<TParam extends ParamWithDefault>(param: TParam): TParam;
 
@@ -189,19 +195,19 @@ export declare function createParam<TParam extends Param>(param: TParam): ParamG
 
 export declare function createParam<TParam extends Param>(param: TParam, defaultValue: ExtractParamType<TParam>): ParamWithDefault<TParam>;
 
-export declare function createRoute<const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta, const TState extends Record<string, Param> = Record<string, Param>>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithoutComponents & WithoutParent & (WithState<TState> | WithoutState)): Route<ToName<TName>, Host<'', {}>, ToPath<TPath>, ToQuery<TQuery>, TMeta, TState>;
+export declare function createRoute<const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const THash extends string | Hash | undefined = undefined, const TMeta extends RouteMeta = RouteMeta, const TState extends Record<string, Param> = Record<string, Param>>(options: CreateRouteOptions<TName, TPath, TQuery, THash, TMeta> & WithHooks & WithoutComponents & WithoutParent & (WithState<TState> | WithoutState)): Route<ToName<TName>, Host<'', {}>, ToPath<TPath>, ToQuery<TQuery>, ToHash<THash>, TMeta, TState>;
 
-export declare function createRoute<const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta, const TState extends Record<string, Param> = Record<string, Param>>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithoutComponents & WithParent<TParent> & (WithState<TState> | WithoutState)): Route<ToName<TName>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>, CombineMeta<TMeta, TParent['meta']>, CombineState<TState, TParent['state']>>;
+export declare function createRoute<const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const THash extends string | Hash | undefined = undefined, const TMeta extends RouteMeta = RouteMeta, const TState extends Record<string, Param> = Record<string, Param>>(options: CreateRouteOptions<TName, TPath, TQuery, THash, TMeta> & WithHooks & WithoutComponents & WithParent<TParent> & (WithState<TState> | WithoutState)): Route<ToName<TName>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>, CombineHash<TParent['hash'], ToHash<THash>>, CombineMeta<TMeta, TParent['meta']>, CombineState<TState, TParent['state']>>;
 
-export declare function createRoute<TComponent extends Component, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta, const TState extends Record<string, Param> = Record<string, Param>>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithComponent<TComponent, RouteParams<TPath, TQuery>> & WithoutParent & (WithState<TState> | WithoutState)): Route<ToName<TName>, Host<'', {}>, ToPath<TPath>, ToQuery<TQuery>, TMeta, TState>;
+export declare function createRoute<TComponent extends Component, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const THash extends string | Hash | undefined = undefined, const TMeta extends RouteMeta = RouteMeta, const TState extends Record<string, Param> = Record<string, Param>>(options: CreateRouteOptions<TName, TPath, TQuery, THash, TMeta> & WithHooks & WithComponent<TComponent, RouteParams<TPath, TQuery>> & WithoutParent & (WithState<TState> | WithoutState)): Route<ToName<TName>, Host<'', {}>, ToPath<TPath>, ToQuery<TQuery>, ToHash<THash>, TMeta, TState>;
 
-export declare function createRoute<TComponent extends Component, const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta, const TState extends Record<string, Param> = Record<string, Param>>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithComponent<TComponent, RouteParams<TPath, TQuery, TParent>> & WithParent<TParent> & (WithState<TState> | WithoutState)): Route<ToName<TName>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>, CombineMeta<TMeta, TParent['meta']>, CombineState<TState, TParent['state']>>;
+export declare function createRoute<TComponent extends Component, const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const THash extends string | Hash | undefined = undefined, const TMeta extends RouteMeta = RouteMeta, const TState extends Record<string, Param> = Record<string, Param>>(options: CreateRouteOptions<TName, TPath, TQuery, THash, TMeta> & WithHooks & WithComponent<TComponent, RouteParams<TPath, TQuery, TParent>> & WithParent<TParent> & (WithState<TState> | WithoutState)): Route<ToName<TName>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>, CombineHash<TParent['hash'], ToHash<THash>>, CombineMeta<TMeta, TParent['meta']>, CombineState<TState, TParent['state']>>;
 
-export declare function createRoute<TComponents extends Record<string, Component>, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta, const TState extends Record<string, Param> = Record<string, Param>>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithComponents<TComponents, RouteParams<TPath, TQuery>> & WithoutParent & (WithState<TState> | WithoutState)): Route<ToName<TName>, Host<'', {}>, ToPath<TPath>, ToQuery<TQuery>, TMeta, TState>;
+export declare function createRoute<TComponents extends Record<string, Component>, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const THash extends string | Hash | undefined = undefined, const TMeta extends RouteMeta = RouteMeta, const TState extends Record<string, Param> = Record<string, Param>>(options: CreateRouteOptions<TName, TPath, TQuery, THash, TMeta> & WithHooks & WithComponents<TComponents, RouteParams<TPath, TQuery>> & WithoutParent & (WithState<TState> | WithoutState)): Route<ToName<TName>, Host<'', {}>, ToPath<TPath>, ToQuery<TQuery>, ToHash<THash>, TMeta, TState>;
 
-export declare function createRoute<TComponents extends Record<string, Component>, const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta, const TState extends Record<string, Param> = Record<string, Param>>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithComponents<TComponents, RouteParams<TPath, TQuery, TParent>> & WithParent<TParent> & (WithState<TState> | WithoutState)): Route<ToName<TName>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>, CombineMeta<TMeta, TParent['meta']>, CombineState<TState, TParent['state']>>;
+export declare function createRoute<TComponents extends Record<string, Component>, const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const THash extends string | Hash | undefined = undefined, const TMeta extends RouteMeta = RouteMeta, const TState extends Record<string, Param> = Record<string, Param>>(options: CreateRouteOptions<TName, TPath, TQuery, THash, TMeta> & WithHooks & WithComponents<TComponents, RouteParams<TPath, TQuery, TParent>> & WithParent<TParent> & (WithState<TState> | WithoutState)): Route<ToName<TName>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>, CombineHash<TParent['hash'], ToHash<THash>>, CombineMeta<TMeta, TParent['meta']>, CombineState<TState, TParent['state']>>;
 
-export declare type CreateRouteOptions<TName extends string | undefined = string | undefined, TPath extends string | Path | undefined = string | Path | undefined, TQuery extends string | Query | undefined = string | Query | undefined, TMeta extends RouteMeta = RouteMeta> = {
+export declare type CreateRouteOptions<TName extends string | undefined = string | undefined, TPath extends string | Path | undefined = string | Path | undefined, TQuery extends string | Query | undefined = string | Query | undefined, THash extends string | Hash | undefined = string | Hash | undefined, TMeta extends RouteMeta = RouteMeta> = {
     /**
      * Name for route, used to create route keys and in navigation.
      */
@@ -214,6 +220,10 @@ export declare type CreateRouteOptions<TName extends string | undefined = string
      * Query (aka search) part of URL.
      */
     query?: TQuery;
+    /**
+     * Hash part of URL.
+     */
+    hash?: THash;
     /**
      * Represents additional metadata associated with a route, customizable via declaration merging.
      */
@@ -359,8 +369,14 @@ declare type ExtractStateParams<TRoute> = TRoute extends {
     state: infer TState extends Record<string, Param>;
 } ? ExtractParamTypes<TState> : Record<string, unknown>;
 
+declare type Hash<THash extends string | undefined = string | undefined> = {
+    value: THash;
+    hasValue: () => boolean;
+    toString: () => string;
+};
+
 declare type Host<THost extends string = string, TParams extends HostParamsWithParamNameExtracted<THost> = Record<string, Param | undefined>> = {
-    host: THost;
+    value: THost;
     params: string extends THost ? Record<string, Param> : Identity<ExtractParamsFromHostString<THost, TParams>>;
     toString: () => string;
 };
@@ -497,7 +513,7 @@ declare type ParentPath<TParent extends Route | undefined> = TParent extends Rou
 declare type ParentQuery<TParent extends Route | undefined> = TParent extends Route ? TParent['query'] : Query<'', {}>;
 
 declare type Path<TPath extends string = string, TParams extends PathParamsWithParamNameExtracted<TPath> = Record<string, Param | undefined>> = {
-    path: TPath;
+    value: TPath;
     params: string extends TPath ? Record<string, Param> : Identity<ExtractParamsFromPathString<TPath, TParams>>;
     toString: () => string;
 };
@@ -507,7 +523,7 @@ declare type Path<TPath extends string = string, TParams extends PathParamsWithP
  *
  * @template TPath - The string literal type that represents the path.
  * @template TParams - The type of the path parameters associated with the path.
- * @param path - The path string.
+ * @param value - The path string.
  * @param params - The parameters associated with the path, typically as key-value pairs.
  * @returns An object representing the path which includes the path string, its parameters,
  *          and a toString method for getting the path as a string.
@@ -523,7 +539,7 @@ declare type Path<TPath extends string = string, TParams extends PathParamsWithP
  * })
  * ```
  */
-export declare function path<TPath extends string, TParams extends PathParamsWithParamNameExtracted<TPath>>(path: TPath, params: Identity<TParams>): Path<TPath, TParams>;
+export declare function path<TPath extends string, TParams extends PathParamsWithParamNameExtracted<TPath>>(value: TPath, params: Identity<TParams>): Path<TPath, TParams>;
 
 declare type PathParamsWithParamNameExtracted<TPath extends string> = {
     [K in keyof ExtractParamsFromPathString<TPath> as ExtractParamName<K>]?: Param;
@@ -543,7 +559,7 @@ declare type PrefetchConfigOptions = {
 };
 
 declare type Query<TQuery extends string = string, TQueryParams extends QueryParamsWithParamNameExtracted<TQuery> = Record<string, Param | undefined>> = {
-    query: TQuery;
+    value: TQuery;
     params: string extends TQuery ? Record<string, Param> : Identity<ExtractQueryParamsFromQueryString<TQuery, TQueryParams>>;
     toString: () => string;
 };
@@ -553,7 +569,7 @@ declare type Query<TQuery extends string = string, TQueryParams extends QueryPar
  *
  * @template TQuery - The string literal type that represents the query.
  * @template TParams - The type of the query parameters associated with the query.
- * @param query - The query string.
+ * @param value - The query string.
  * @param params - The parameters associated with the query, typically as key-value pairs.
  * @returns An object representing the query which includes the query string, its parameters,
  *          and a toString method for getting the query as a string.
@@ -569,7 +585,7 @@ declare type Query<TQuery extends string = string, TQueryParams extends QueryPar
  * })
  * ```
  */
-export declare function query<TQuery extends string, TParams extends QueryParamsWithParamNameExtracted<TQuery>>(query: TQuery, params: Identity<TParams>): Query<TQuery, TParams>;
+export declare function query<TQuery extends string, TParams extends QueryParamsWithParamNameExtracted<TQuery>>(value: TQuery, params: Identity<TParams>): Query<TQuery, TParams>;
 
 declare type QueryParamsWithParamNameExtracted<T extends string> = {
     [K in keyof ExtractQueryParamsFromQueryString<T> as ExtractParamName<K>]?: Param;
@@ -691,7 +707,11 @@ declare type ResolvedRouteQuery = {
  * @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.
  */
-export declare type Route<TName extends string = string, THost extends Host = Host, TPath extends Path = Path, TQuery extends Query = Query, TMeta extends RouteMeta = RouteMeta, TState extends Record<string, Param> = Record<string, Param>> = {
+export declare type Route<TName extends string = string, THost extends Host = Host, TPath extends Path = Path, TQuery extends Query = Query, THash extends Hash = Hash, TMeta extends RouteMeta = RouteMeta, TState extends Record<string, Param> = Record<string, Param>> = {
+    /**
+     * Unique identifier for the route, generated by router.
+     */
+    id: string;
     /**
      * The specific route properties that were matched in the current route.
      */
@@ -702,7 +722,7 @@ export declare type Route<TName extends string = string, THost extends Host = Ho
      */
     matches: CreateRouteOptionsMatched[];
     /**
-     * Unique identifier for the route. Name is used for routing and for matching.
+     * Identifier for the route as defined by user. Name must be unique among named routes. Name is used for routing and for matching.
      */
     name: TName;
     /**
@@ -717,6 +737,10 @@ export declare type Route<TName extends string = string, THost extends Host = Ho
      * Represents the structured query of the route, including query params.
      */
     query: TQuery;
+    /**
+     * Represents the hash of the route.
+     */
+    hash: THash;
     /**
      * Represents additional metadata associated with a route, combined with any parents.
      */
@@ -1142,6 +1166,8 @@ declare type StringHasValue<T> = string extends T ? true : '' extends T ? false
 
 declare type ToCallback = (resolve: RegisteredRouter['resolve']) => string;
 
+declare type ToHash<T extends string | Hash | undefined> = T extends string ? Hash<T> : T extends undefined ? Hash<''> : unknown extends T ? Hash<''> : T;
+
 declare type ToHost<T extends string | Host | undefined> = T extends string ? Host<T, {}> : T extends undefined ? Host<'', {}> : unknown extends T ? Host<'', {}> : T;
 
 declare type ToName<T extends string | undefined> = T extends string ? T : '';