@kitbag/router 0.17.2 → 0.17.3

package/dist/kitbag-router.d.ts

@@ -209,29 +209,27 @@ declare type CallbackSuccessResponse = {
     status: 'SUCCESS';
 };
 
-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 CombineHash<TParent extends WithParams, TChild extends WithParams> = CombinePath<TParent, TChild>;
 
 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 {
+declare type CombinePath<TParent extends WithParams, TChild extends WithParams> = ToWithParams<TParent> extends {
     value: infer TParentPath extends string;
     params: infer TParentParams extends Record<string, unknown>;
-} ? ToPath<TChild> extends {
+} ? ToWithParams<TChild> extends {
     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<'', {}>;
+} ? RemoveLeadingQuestionMarkFromKeys<TParentParams> & RemoveLeadingQuestionMarkFromKeys<TChildParams> extends ParamsWithParamNameExtracted<CombinePathString<TParentPath, TChildPath>> ? WithParams<CombinePathString<TParentPath, TChildPath>, RemoveLeadingQuestionMarkFromKeys<TParentParams> & RemoveLeadingQuestionMarkFromKeys<TChildParams>> : WithParams<'', {}> : WithParams<'', {}> : WithParams<'', {}>;
 
-declare type CombineQuery<TParent extends Query, TChild extends Query> = ToQuery<TParent> extends {
+declare type CombinePathString<TParent extends string, TChild extends string> = `${TParent}${TChild}`;
+
+declare type CombineQuery<TParent extends WithParams, TChild extends WithParams> = ToWithParams<TParent> extends {
     value: infer TParentQuery extends string;
     params: infer TParentParams extends Record<string, unknown>;
-} ? ToQuery<TChild> extends {
+} ? ToWithParams<TChild> extends {
     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<'', {}>;
+} ? RemoveLeadingQuestionMarkFromKeys<TParentParams> & RemoveLeadingQuestionMarkFromKeys<TChildParams> extends ParamsWithParamNameExtracted<CombineQueryString<TParentQuery, TChildQuery>> ? WithParams<CombineQueryString<TParentQuery, TChildQuery>, RemoveLeadingQuestionMarkFromKeys<TParentParams> & RemoveLeadingQuestionMarkFromKeys<TChildParams>> : WithParams<'', {}> : WithParams<'', {}> : WithParams<'', {}>;
 
 declare type CombineQueryString<TParent extends string | undefined, TChild extends string | undefined> = StringHasValue<TParent> extends true ? StringHasValue<TChild> extends true ? `${TParent}&${TChild}` : TParent : TChild;
 
@@ -251,9 +249,9 @@ export declare type CreatedRouteOptions = Omit<CreateRouteOptions, 'props'> & Wi
     props?: unknown;
 };
 
-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 THost extends string | WithParams, const TName extends string | undefined = undefined, const TPath extends string | WithParams | undefined = undefined, const TQuery extends string | WithParams | undefined = undefined, const THash extends string | WithParams | undefined = undefined, const TMeta extends RouteMeta = RouteMeta>(options: CreateRouteOptions<TName, TPath, TQuery> & WithHost<THost> & WithoutParent): Route<ToName<TName>, ToWithParams<THost>, ToWithParams<TPath>, ToWithParams<TQuery>, ToWithParams<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, 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 createExternalRoute<const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | WithParams | undefined = undefined, const TQuery extends string | WithParams | undefined = undefined, const THash extends string | WithParams | undefined = undefined, const TMeta extends RouteMeta = RouteMeta>(options: CreateRouteOptions<TName, TPath, TQuery> & WithoutHost & WithParent<TParent>): Route<ToName<TName>, WithParams<'', {}>, CombinePath<TParent['path'], ToWithParams<TPath>>, CombineQuery<TParent['query'], ToWithParams<TQuery>>, CombineHash<TParent['hash'], ToWithParams<THash>>, CombineMeta<TMeta, TParent['meta']>>;
 
 export declare function createParam<TParam extends ParamWithDefault>(param: TParam): TParam;
 
@@ -263,7 +261,7 @@ export declare function createParam<TParam extends Param>(param: TParam, default
 
 export declare function createRoute<const TOptions extends CreateRouteOptions, const TProps extends CreateRouteProps<TOptions>>(options: TOptions, ...args: CreateRouteWithProps<TOptions, TProps>): ToRoute<TOptions, CreateRouteProps<TOptions> extends TProps ? undefined : TProps>;
 
-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> = WithHooks & {
+export declare type CreateRouteOptions<TName extends string | undefined = string | undefined, TPath extends string | WithParams | undefined = string | WithParams | undefined, TQuery extends string | WithParams | undefined = string | WithParams | undefined, THash extends string | WithParams | undefined = string | WithParams | undefined, TMeta extends RouteMeta = RouteMeta> = WithHooks & {
     /**
      * Name for route, used to create route keys and in navigation.
      */
@@ -373,9 +371,7 @@ declare type EmptyRouterPlugin = {
  */
 declare type ExtractParamName<TParam extends PropertyKey> = TParam extends `?${infer Param}` ? Param extends '' ? never : Param : TParam extends '' ? never : TParam;
 
-declare type ExtractParamsFromHostString<THost extends string, TParams extends Record<string, Param | undefined> = Record<never, never>> = THost extends `${string}${ParamStart}${infer Param}${ParamEnd}${infer Rest}` ? Record<Param, ExtractPathParamType<Param, TParams>> & ExtractParamsFromHostString<Rest, TParams> : Record<never, never>;
-
-declare type ExtractParamsFromPathString<TPath extends string, TParams extends Record<string, Param | undefined> = Record<never, never>> = TPath extends `${string}${ParamStart}${infer Param}${ParamEnd}${infer Rest}` ? Record<Param, ExtractPathParamType<Param, TParams>> & ExtractParamsFromPathString<Rest, TParams> : Record<never, never>;
+declare type ExtractParamsFromString<TValue extends string, TParams extends Record<string, Param | undefined> = Record<never, never>> = TValue extends `${string}${ParamStart}${infer Param}${ParamEnd}${infer Rest}` ? Record<Param, ExtractWithParamsParamType<Param, TParams>> & ExtractParamsFromString<Rest, TParams> : Record<never, never>;
 
 /**
  * Extracts the actual type from a parameter type, handling getters, setters, and potential undefined values.
@@ -400,16 +396,6 @@ declare type ExtractParamTypesWithoutLosingOptional<TParams extends Record<strin
 
 declare type ExtractParamTypeWithoutLosingOptional<TParam extends Param, TParamKey extends PropertyKey> = TParam extends ParamGetSet<infer Type> ? TParamKey extends `?${string}` ? Type | undefined : Type : TParam extends ParamGetter ? TParamKey extends `?${string}` ? ReturnType<TParam> | undefined : ReturnType<TParam> : TParam extends ZodSchema<infer Type> ? TParamKey extends `?${string}` ? Type | undefined : Type : TParam extends LiteralParam ? TParamKey extends `?${string}` ? TParam | undefined : TParam : TParamKey extends `?${string}` ? string | undefined : 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.
- */
-declare type ExtractPathParamType<TParam extends string, TParams extends Record<string, Param | undefined>> = TParam extends `?${infer OptionalParam}` ? OptionalParam extends keyof TParams ? TParams[OptionalParam] : 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}` ? Record<Param, ExtractPathParamType<Param, TParams>> & ExtractQueryParamsFromQueryString<Rest, TParams> : Record<never, never>;
-
 /**
  * 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.
@@ -426,7 +412,10 @@ declare type ExtractRouteParamTypes<TRoute> = TRoute extends {
     host: {
         params: infer HostParams extends Record<string, Param>;
     };
-} ? ExtractParamTypes<HostParams & PathParams & QueryParams> : {};
+    hash: {
+        params: infer HashParams extends Record<string, Param>;
+    };
+} ? ExtractParamTypes<HostParams & PathParams & QueryParams & HashParams> : {};
 
 declare type ExtractRouteParamTypesWithoutLosingOptional<TRoute> = TRoute extends {
     host: {
@@ -438,7 +427,10 @@ declare type ExtractRouteParamTypesWithoutLosingOptional<TRoute> = TRoute extend
     query: {
         params: infer QueryParams extends Record<string, Param>;
     };
-} ? ExtractParamTypesWithoutLosingOptional<HostParams & PathParams & QueryParams> : Record<string, unknown>;
+    hash: {
+        params: infer HashParams extends Record<string, Param>;
+    };
+} ? ExtractParamTypesWithoutLosingOptional<HostParams & PathParams & QueryParams & HashParams> : Record<string, unknown>;
 
 declare type ExtractRouteStateParamsAsOptional<T extends Record<string, Param>> = ExtractParamTypes<{
     [K in keyof T as K extends string ? `?${K}` : never]: T[K];
@@ -448,22 +440,22 @@ declare type ExtractStateParams<TRoute> = TRoute extends {
     state: infer TState extends Record<string, Param>;
 } ? ExtractParamTypes<TState> : Record<string, unknown>;
 
+/**
+ * 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.
+ */
+declare type ExtractWithParamsParamType<TParam extends string, TParams extends Record<string, Param | undefined>> = TParam extends `?${infer OptionalParam}` ? OptionalParam extends keyof TParams ? TParams[OptionalParam] : StringConstructor : TParam extends keyof TParams ? TParams[TParam] : StringConstructor;
+
 declare type GetParentPropsReturnType<TParent extends Route | undefined = Route | undefined> = TParent extends Route ? TParent['matched']['props'] extends PropsGetter ? ReturnType<TParent['matched']['props']> : TParent['matched']['props'] extends Record<string, PropsGetter> ? {
     [K in keyof TParent['matched']['props']]: ReturnType<TParent['matched']['props'][K]>;
 } : undefined : undefined;
 
-declare type Hash<THash extends string | undefined = string | undefined> = {
-    value: THash;
-};
-
-declare type Host<THost extends string = string, TParams extends HostParamsWithParamNameExtracted<THost> = Record<string, Param | undefined>> = {
-    value: THost;
-    params: string extends THost ? Record<string, Param> : Identity<ExtractParamsFromHostString<THost, TParams>>;
-};
-
-declare type HostParamsWithParamNameExtracted<THost extends string> = {
-    [K in keyof ExtractParamsFromHostString<THost> as ExtractParamName<K>]?: Param;
-};
+/**
+ * @deprecated use `withParams` instead
+ */
+export declare const host: typeof withParams;
 
 declare type Identity<T> = T extends object ? {} & {
     [P in keyof T as T[P] extends never ? never : P]: T[P];
@@ -642,39 +634,16 @@ declare type ParamStart = typeof paramStart;
 
 declare const paramStart = "[";
 
-declare type ParamWithDefault<TParam extends Param = Param> = Required<ParamGetSet<ExtractParamType<TParam>>>;
-
-declare type Path<TPath extends string = string, TParams extends PathParamsWithParamNameExtracted<TPath> = Record<string, Param | undefined>> = {
-    value: TPath;
-    params: string extends TPath ? Record<string, Param> : Identity<ExtractParamsFromPathString<TPath, TParams>>;
+declare type ParamsWithParamNameExtracted<TValue extends string> = {
+    [K in keyof ExtractParamsFromString<TValue> as ExtractParamName<K>]?: Param;
 };
 
+declare type ParamWithDefault<TParam extends Param = Param> = Required<ParamGetSet<ExtractParamType<TParam>>>;
+
 /**
- * Constructs a Path object, which enables assigning types for params.
- *
- * @template TPath - The string literal type that represents the path.
- * @template TParams - The type of the path parameters associated with the path.
- * @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.
- *
- * @example
- * ```ts
- * import { createRoute, path } from '@kitbag/router'
- *
- * export const routes = createRoute({
- *   name: 'home',
- *   path: path('/[foo]', { foo: Number }),
- *   component: Home
- * })
- * ```
+ * @deprecated use `withParams` instead
  */
-export declare function path<const TPath extends string, const TParams extends PathParamsWithParamNameExtracted<TPath>>(value: TPath, params: TParams): Path<TPath, TParams>;
-
-declare type PathParamsWithParamNameExtracted<TPath extends string> = {
-    [K in keyof ExtractParamsFromPathString<TPath> as ExtractParamName<K>]?: Param;
-};
+export declare const path: typeof withParams;
 
 /**
  * Determines what assets are prefetched. A boolean enables or disables all prefetching.
@@ -721,37 +690,10 @@ declare type PropsCallbackParent<TParent extends Route | undefined = Route | und
 
 declare type PropsGetter<TOptions extends CreateRouteOptions = CreateRouteOptions, TComponent extends Component = Component> = (route: ResolvedRoute<ToRoute<TOptions, undefined>>, context: PropsCallbackContext<TOptions['parent']>) => MaybePromise<ComponentProps<TComponent>>;
 
-declare type Query<TQuery extends string = string, TQueryParams extends QueryParamsWithParamNameExtracted<TQuery> = Record<string, Param | undefined>> = {
-    value: TQuery;
-    params: string extends TQuery ? Record<string, Param> : Identity<ExtractQueryParamsFromQueryString<TQuery, TQueryParams>>;
-};
-
 /**
- * Constructs a Query object, which enables assigning types for params.
- *
- * @template TQuery - The string literal type that represents the query.
- * @template TParams - The type of the query parameters associated with the query.
- * @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.
- *
- * @example
- * ```ts
- * import { createRoute, query } from '@kitbag/router'
- *
- * export const routes = createRoute({
- *   name: 'home',
- *   query: query('bar=[bar]', { bar: Boolean }),
- *   component: Home
- * })
- * ```
+ * @deprecated use `withParams` instead
  */
-export declare function query<const TQuery extends string, const TParams extends QueryParamsWithParamNameExtracted<TQuery>>(value: TQuery, params: TParams): Query<TQuery, TParams>;
-
-declare type QueryParamsWithParamNameExtracted<T extends string> = {
-    [K in keyof ExtractQueryParamsFromQueryString<T> as ExtractParamName<K>]?: Param;
-};
+export declare const query: typeof withParams;
 
 export declare type QuerySource = ConstructorParameters<typeof URLSearchParams>[0];
 
@@ -879,7 +821,7 @@ export declare type ResolvedRoute<TRoute extends Route = Route> = Readonly<{
  * @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, THash extends Hash = Hash, TMeta extends RouteMeta = RouteMeta, TState extends Record<string, Param> = Record<string, Param>, TMatches extends CreatedRouteOptions[] = CreatedRouteOptions[]> = {
+export declare type Route<TName extends string = string, THost extends WithParams = WithParams, TPath extends WithParams = WithParams, TQuery extends WithParams = WithParams, THash extends WithParams = WithParams, TMeta extends RouteMeta = RouteMeta, TState extends Record<string, Param> = Record<string, Param>, TMatches extends CreatedRouteOptions[] = CreatedRouteOptions[]> = {
     /**
      * Unique identifier for the route, generated by router.
      */
@@ -1277,10 +1219,6 @@ declare type StringHasValue<T> = string extends T ? true : '' extends T ? false
 
 export declare type ToCallback = (resolve: RegisteredRouter['resolve']) => ResolvedRoute | Url | undefined;
 
-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 ToMatch<TOptions extends CreateRouteOptions, TProps extends CreateRouteProps<TOptions> | undefined> = Omit<TOptions, 'props'> & {
     id: string;
     props: TProps;
@@ -1294,16 +1232,14 @@ declare type ToMeta<TMeta extends RouteMeta | undefined> = TMeta extends undefin
 
 declare type ToName<T extends string | undefined> = T extends string ? T : '';
 
-declare type ToPath<T extends string | Path | undefined> = T extends string ? Path<T, {}> : T extends undefined ? Path<'', {}> : unknown extends T ? Path<'', {}> : T;
-
-declare type ToQuery<T extends string | Query | undefined> = T extends string ? Query<T, {}> : T extends undefined ? Query<'', {}> : unknown extends T ? Query<'', {}> : T;
-
 declare type ToRoute<TOptions extends CreateRouteOptions, TProps extends CreateRouteProps<TOptions> | undefined> = CreateRouteOptions extends TOptions ? Route : TOptions extends {
     parent: infer TParent extends Route;
-} ? Route<ToName<TOptions['name']>, Host<'', {}>, CombinePath<ToPath<TParent['path']>, ToPath<TOptions['path']>>, CombineQuery<ToQuery<TParent['query']>, ToQuery<TOptions['query']>>, CombineHash<ToHash<TParent['hash']>, ToHash<TOptions['hash']>>, CombineMeta<ToMeta<TParent['meta']>, ToMeta<TOptions['meta']>>, CombineState<ToState<TParent['state']>, ToState<TOptions['state']>>, ToMatches<TOptions, TProps>> : Route<ToName<TOptions['name']>, Host<'', {}>, ToPath<TOptions['path']>, ToQuery<TOptions['query']>, ToHash<TOptions['hash']>, ToMeta<TOptions['meta']>, ToState<TOptions['state']>, ToMatches<TOptions, TProps>>;
+} ? Route<ToName<TOptions['name']>, WithParams<'', {}>, CombinePath<ToWithParams<TParent['path']>, ToWithParams<TOptions['path']>>, CombineQuery<ToWithParams<TParent['query']>, ToWithParams<TOptions['query']>>, CombineHash<ToWithParams<TParent['hash']>, ToWithParams<TOptions['hash']>>, CombineMeta<ToMeta<TParent['meta']>, ToMeta<TOptions['meta']>>, CombineState<ToState<TParent['state']>, ToState<TOptions['state']>>, ToMatches<TOptions, TProps>> : Route<ToName<TOptions['name']>, WithParams<'', {}>, ToWithParams<TOptions['path']>, ToWithParams<TOptions['query']>, ToWithParams<TOptions['hash']>, ToMeta<TOptions['meta']>, ToState<TOptions['state']>, ToMatches<TOptions, TProps>>;
 
 declare type ToState<TState extends Record<string, Param> | undefined> = TState extends undefined ? Record<string, Param> : unknown extends TState ? {} : TState;
 
+declare type ToWithParams<T extends string | WithParams | undefined> = T extends string ? WithParams<T, {}> : T extends undefined ? WithParams<'', {}> : unknown extends T ? WithParams<'', {}> : T;
+
 declare type TupleOf<T extends Param[]> = {
     [K in keyof T]: ExtractParamType<T[K]>;
 };
@@ -1448,7 +1384,7 @@ export declare type WithHooks = {
     onAfterRouteLeave?: MaybeArray<AfterRouteHook>;
 };
 
-declare type WithHost<THost extends string | Host = string | Host> = {
+declare type WithHost<THost extends string | WithParams = string | WithParams> = {
     /**
      * Host part of URL.
      */
@@ -1467,6 +1403,15 @@ declare type WithoutParent = {
     parent?: never;
 };
 
+declare type WithParams<TValue extends string = string, TParams extends ParamsWithParamNameExtracted<TValue> = Record<string, Param | undefined>> = {
+    value: TValue;
+    params: string extends TValue ? Record<string, Param> : Identity<ExtractParamsFromString<TValue, TParams>>;
+};
+
+export declare function withParams<const TValue extends string, const TParams extends ParamsWithParamNameExtracted<TValue>>(value: TValue, params: TParams): WithParams<TValue, TParams>;
+
+export declare function withParams(): WithParams<'', {}>;
+
 declare type WithParent<TParent extends Route = Route> = {
     parent: TParent;
 };