@kitbag/router 0.18.1 → 0.19.0

package/dist/kitbag-router.d.ts

@@ -74,7 +74,6 @@ export declare type AddGlobalRouteHooks = (hooks: RouteHooks) => void;
 export declare type AfterHookContext = {
     to: ResolvedRoute;
     from: ResolvedRoute | null;
-    app: App | null;
 };
 
 /**
@@ -109,7 +108,11 @@ export declare type AfterRouteHookResponse = CallbackSuccessResponse | CallbackP
 
 declare type AllPropertiesAreOptional<T> = Record<string, unknown> extends T ? true : IsEmptyObject<OnlyRequiredProperties<T>>;
 
-export declare function arrayOf<const T extends Param[]>(...params: T): ParamGetSet<ExtractParamType<T[number]>[]>;
+export declare function arrayOf<const T extends Param[]>(params: T, options?: ArrayOfOptions): ParamGetSet<ExtractParamType<T[number]>[]>;
+
+declare type ArrayOfOptions = {
+    separator?: string;
+};
 
 declare type AsNamedRoute<T extends Route> = IsRouteUnnamed<T> extends true ? never : T;
 
@@ -130,7 +133,6 @@ export declare function asUrl(value: string): Url;
 export declare type BeforeHookContext = {
     to: ResolvedRoute;
     from: ResolvedRoute | null;
-    app: App | null;
 };
 
 /**
@@ -220,7 +222,7 @@ declare type CombinePath<TParent extends WithParams, TChild extends WithParams>
 } ? ToWithParams<TChild> extends {
     value: infer TChildPath extends string;
     params: infer TChildParams extends Record<string, unknown>;
-} ? RemoveLeadingQuestionMarkFromKeys<TParentParams> & RemoveLeadingQuestionMarkFromKeys<TChildParams> extends Record<string, Param | undefined> ? WithParams<CombinePathString<TParentPath, TChildPath>, RemoveLeadingQuestionMarkFromKeys<TParentParams> & RemoveLeadingQuestionMarkFromKeys<TChildParams>> : WithParams<CombinePathString<TParentPath, TChildPath>, {}> : WithParams<'', {}> : WithParams<'', {}>;
+} ? TParentParams & TChildParams extends Record<string, Param | undefined> ? WithParams<CombinePathString<TParentPath, TChildPath>, TParentParams & TChildParams> : WithParams<CombinePathString<TParentPath, TChildPath>, {}> : WithParams<'', {}> : WithParams<'', {}>;
 
 declare type CombinePathString<TParent extends string, TChild extends string> = `${TParent}${TChild}`;
 
@@ -230,7 +232,7 @@ declare type CombineQuery<TParent extends WithParams, TChild extends WithParams>
 } ? ToWithParams<TChild> extends {
     value: infer TChildQuery extends string;
     params: infer TChildParams extends Record<string, unknown>;
-} ? RemoveLeadingQuestionMarkFromKeys<TParentParams> & RemoveLeadingQuestionMarkFromKeys<TChildParams> extends Record<string, Param | undefined> ? WithParams<CombineQueryString<TParentQuery, TChildQuery>, RemoveLeadingQuestionMarkFromKeys<TParentParams> & RemoveLeadingQuestionMarkFromKeys<TChildParams>> : WithParams<CombineQueryString<TParentQuery, TChildQuery>, {}> : WithParams<'', {}> : WithParams<'', {}>;
+} ? TParentParams & TChildParams extends Record<string, Param | undefined> ? WithParams<CombineQueryString<TParentQuery, TChildQuery>, TParentParams & TChildParams> : WithParams<CombineQueryString<TParentQuery, TChildQuery>, {}> : 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;
 
@@ -250,9 +252,9 @@ export declare type CreatedRouteOptions = Omit<CreateRouteOptions, 'props'> & Wi
     props?: unknown;
 };
 
-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 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, THash, TMeta> & 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 | 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 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, THash, TMeta> & 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;
 
@@ -370,7 +372,7 @@ declare type EmptyRouterPlugin = {
  * @template TParam - The string from which to extract the parameter name.
  * @returns The extracted parameter name, or never if the parameter string is empty.
  */
-declare type ExtractParamName<TParam extends PropertyKey> = TParam extends `?${infer Param}` ? Param extends '' ? never : Param : TParam extends '' ? never : TParam;
+declare type ExtractParamName<TParam extends PropertyKey> = TParam extends string ? TParam extends `?${infer Param}` ? Param extends '' ? never : Param : TParam extends '' ? never : TParam : never;
 
 /**
  * Extracts the actual type from a parameter type, handling getters and setters.
@@ -379,50 +381,43 @@ declare type ExtractParamName<TParam extends PropertyKey> = TParam extends `?${i
  */
 declare type ExtractParamType<TParam extends Param> = TParam extends ParamGetSet<infer Type> ? Type : TParam extends ParamGetter ? ReturnType<TParam> : TParam extends ZodSchemaLike<infer Type> ? Type : TParam extends LiteralParam ? 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.
- */
 declare type ExtractParamTypes<TParams extends Record<string, Param>> = Identity<MakeOptional<{
     [K in keyof TParams as ExtractParamName<K>]: ExtractParamType<TParams[K]>;
 }>>;
 
 /**
- * Does everything that ExtractParamTypes does, but takes into consideration optional properties.
- * Differs from ExtractParamTypes in that it also reads the string `value` from WithParams to determine what should be optional.
+ * Extracts combined types of path and query parameters for a given route, creating a unified parameter object.
  * @template TParams - The record of parameter types, possibly including undefined.
  * @returns A new type with the appropriate properties marked as optional.
  */
-declare type ExtractParamTypesOptionalReading<TParams extends Record<string, Param>> = {
-    [K in keyof TParams as ExtractParamName<K>]: K extends `?${string}` ? TParams[K] extends Required<ParamGetSet> ? ExtractParamType<TParams[K]> : ExtractParamType<TParams[K]> | undefined : ExtractParamType<TParams[K]>;
+declare type ExtractParamTypesReading<TWithParams extends WithParams> = {
+    [K in keyof TWithParams['params']]: TWithParams['value'] extends `${string}${ParamStart}?${K & string}${ParamEnd}${string}` ? TWithParams['params'][K] extends Required<ParamGetSet> ? ExtractParamType<TWithParams['params'][K]> : ExtractParamType<TWithParams['params'][K]> | undefined : ExtractParamType<TWithParams['params'][K]>;
 };
 
 /**
- * Does everything that ExtractParamTypes does, but takes into consideration optional properties.
- * Differs from ExtractParamTypesOptionalReading in that optional params with defaults will remain optional.
+ * Extracts combined types of path and query parameters for a given route, creating a unified parameter object.
+ * Differs from ExtractParamTypesReading in that optional params with defaults will remain optional.
  * @template TParams - The record of parameter types, possibly including undefined.
  * @returns A new type with the appropriate properties marked as optional.
  */
-declare type ExtractParamTypesOptionalWriting<TParams extends Record<string, Param>> = {
-    [K in keyof TParams as ExtractParamName<K>]: K extends `?${string}` ? ExtractParamType<TParams[K]> | undefined : ExtractParamType<TParams[K]>;
+declare type ExtractParamTypesWriting<TWithParams extends WithParams> = {
+    [K in keyof TWithParams['params']]: TWithParams['value'] extends `${string}${ParamStart}?${K & string}${ParamEnd}${string}` ? ExtractParamType<TWithParams['params'][K]> | undefined : ExtractParamType<TWithParams['params'][K]>;
 };
 
 /**
- * Does everything that ExtractRouteParamTypes does, but takes into consideration optional properties.
- * Differs from ExtractRouteParamTypes in that it also reads the string `value` from WithParams to determine what should be optional.
+ * Extracts combined types of path and query parameters for a given route, creating a unified parameter object.
  * @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.
  */
-declare type ExtractRouteParamTypesOptionalReading<TRoute extends Route> = Identity<MakeOptional<ExtractParamTypesOptionalReading<TRoute['host']['params']> & ExtractParamTypesOptionalReading<TRoute['path']['params']> & ExtractParamTypesOptionalReading<TRoute['query']['params']> & ExtractParamTypesOptionalReading<TRoute['hash']['params']>>>;
+declare type ExtractRouteParamTypesReading<TRoute extends Route> = Identity<MakeOptional<ExtractParamTypesReading<TRoute['host']> & ExtractParamTypesReading<TRoute['path']> & ExtractParamTypesReading<TRoute['query']> & ExtractParamTypesReading<TRoute['hash']>>>;
 
 /**
- * Does everything that ExtractRouteParamTypes does, but takes into consideration optional properties.
- * Differs from ExtractRouteParamTypesOptionalReading in that optional params with defaults will remain optional.
+ * Extracts combined types of path and query parameters for a given route, creating a unified parameter object.
+ * Differs from ExtractRouteParamTypesReading in that optional params with defaults will remain optional.
  * @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.
  */
-declare type ExtractRouteParamTypesOptionalWriting<TRoute extends Route> = Identity<MakeOptional<ExtractParamTypesOptionalWriting<TRoute['host']['params']> & ExtractParamTypesOptionalWriting<TRoute['path']['params']> & ExtractParamTypesOptionalWriting<TRoute['query']['params']> & ExtractParamTypesOptionalWriting<TRoute['hash']['params']>>>;
+declare type ExtractRouteParamTypesWriting<TRoute extends Route> = Identity<MakeOptional<ExtractParamTypesWriting<TRoute['host']> & ExtractParamTypesWriting<TRoute['path']> & ExtractParamTypesWriting<TRoute['query']> & ExtractParamTypesWriting<TRoute['hash']>>>;
 
 declare type ExtractRouteStateParamsAsOptional<TParams extends Record<string, Param>> = {
     [K in keyof TParams]: ExtractParamType<TParams[K]> | undefined;
@@ -432,14 +427,6 @@ 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;
@@ -753,12 +740,6 @@ export declare type RegisteredRoutes<T = Register> = T extends {
  */
 export declare type RegisteredRoutesName = RoutesName<RegisteredRoutes>;
 
-declare type RemoveLeadingQuestionMark<T extends PropertyKey> = T extends `?${infer TRest extends string}` ? TRest : T;
-
-declare type RemoveLeadingQuestionMarkFromKeys<T extends Record<string, unknown>> = {
-    [K in keyof T as RemoveLeadingQuestionMark<K>]: T[K];
-};
-
 /**
  * Represents a route that the router has matched to current browser location.
  * @template TRoute - Underlying Route that has been resolved.
@@ -792,7 +773,7 @@ export declare type ResolvedRoute<TRoute extends Route = Route> = Readonly<{
     /**
      * Key value pair for route params, values will be the user provided value from current browser location.
      */
-    params: ExtractRouteParamTypesOptionalReading<TRoute>;
+    params: ExtractRouteParamTypesReading<TRoute>;
     /**
      * Type for additional data intended to be stored in history state.
      */
@@ -913,7 +894,7 @@ export declare type RouteMeta<T = Register> = T extends {
     routeMeta: infer RouteMeta extends Record<string, unknown>;
 } ? RouteMeta : Record<string, unknown>;
 
-declare type RouteParamsByKey<TRoutes extends Routes, TKey extends string> = RouteGetByKey<TRoutes, TKey> extends Route ? ExtractRouteParamTypesOptionalWriting<RouteGetByKey<TRoutes, TKey>> : Record<string, unknown>;
+declare type RouteParamsByKey<TRoutes extends Routes, TKey extends string> = RouteGetByKey<TRoutes, TKey> extends Route ? ExtractRouteParamTypesWriting<RouteGetByKey<TRoutes, TKey>> : Record<string, unknown>;
 
 declare type RoutePropsRecord<TOptions extends CreateRouteOptions = CreateRouteOptions, TComponents extends Record<string, Component> = Record<string, Component>> = {
     [K in keyof TComponents as ComponentPropsAreOptional<TComponents[K]> extends true ? K : never]?: PropsGetter<TOptions, TComponents[K]>;
@@ -1232,9 +1213,13 @@ declare type TupleOf<T extends Param[]> = {
     [K in keyof T]: ExtractParamType<T[K]>;
 };
 
-export declare function tupleOf<const T extends Param[]>(...params: T): ParamGetSet<TupleOf<T>>;
+export declare function tupleOf<const T extends Param[]>(params: T, options?: TupleOfOptions): ParamGetSet<TupleOf<T>>;
+
+declare type TupleOfOptions = {
+    separator?: string;
+};
 
-export declare function unionOf<const T extends Param[]>(...params: T): ParamGetSet<ExtractParamType<T[number]>>;
+export declare function unionOf<const T extends Param[]>(params: T): ParamGetSet<ExtractParamType<T[number]>>;
 
 export declare type Url = `http://${string}` | `https://${string}` | `/${string}`;
 
@@ -1402,7 +1387,7 @@ export declare function withParams(): WithParams<'', {}>;
 
 declare type WithParamsParamsInput<TValue extends string> = TValue extends `${string}${ParamStart}${infer TParam}${ParamEnd}${infer Rest}` ? Record<ExtractParamName<TParam>, Param | undefined> & WithParamsParamsInput<Rest> : {};
 
-declare type WithParamsParamsOutput<TValue extends string, TParams extends Record<string, Param | undefined> = Record<never, never>> = TValue extends `${string}${ParamStart}${infer TParam}${ParamEnd}${infer Rest}` ? Record<TParam, ExtractWithParamsParamType<TParam, TParams>> & WithParamsParamsOutput<Rest, TParams> : {};
+declare type WithParamsParamsOutput<TValue extends string, TParams extends Record<string, Param | undefined> = Record<never, never>> = TValue extends `${string}${ParamStart}${infer TParam}${ParamEnd}${infer Rest}` ? ExtractParamName<TParam> extends keyof TParams ? Record<ExtractParamName<TParam>, TParams[ExtractParamName<TParam>]> & WithParamsParamsOutput<Rest, TParams> : Record<ExtractParamName<TParam>, StringConstructor> & WithParamsParamsOutput<Rest, TParams> : {};
 
 declare type WithParent<TParent extends Route = Route> = {
     parent: TParent;