@codeleap/web-navigation 6.2.3 → 6.8.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './navigation';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA"}

package/dist/navigation.d.ts

@@ -0,0 +1,80 @@
+import { Config, History, Navigator, RouteParams, RoutePath, Routes } from './types';
+export type { Navigator, Routes, };
+/**
+ * Type-safe navigation controller that wraps a platform-specific navigator
+ * (e.g. Next.js `router.push`) and enforces route param contracts at compile time.
+ *
+ * `R` is the routes definition object — nested keys map to `{{param}}`-bearing
+ * path strings. `O` is the navigator's option bag. `C` is the shared context
+ * forwarded to every navigator call so adapters can read app-level state without
+ * closure coupling.
+ *
+ * The class is SSR-safe: any method that touches `window` or `history` short-circuits
+ * when running outside a browser environment.
+ */
+export declare class Navigation<O extends object, R extends object = {}, C extends Record<string, any> = {}> {
+    private _history;
+    private config;
+    get history(): History;
+    context: C;
+    private putHistory;
+    private merge;
+    private navigator;
+    private routes;
+    /**
+     * @param routes Nested object whose leaf values are path strings with optional
+     *   `{{param}}` placeholders. Dot-notation keys derived from this object become
+     *   the typed route identifiers accepted by `navigate`, `getPath`, etc.
+     * @param navigator Platform adapter called for every navigation; receives the
+     *   resolved path, stripped options, and the current `context` value.
+     * @param config Optional behaviour flags. Merged with defaults, so partial
+     *   configs are safe.
+     */
+    constructor(routes: R, navigator: Navigator<O, C>, config?: Config);
+    /**
+     * Checks if the user is on a certain route based on the parameters passed
+     * @param route Route that will be used to direct
+     * @param routeParams Parameters that will be applied to the route
+     * @param exact Accurate path checking - default false
+     * @returns Is on the route - boolean
+     */
+    isCurrentRoute<T extends keyof Routes<R>>(route: T, routeParams?: Record<Routes<R>[T], string | number>, exact?: boolean): boolean;
+    /**
+     * Get the path from the route
+     * @param route Route that will be used to direct
+     * @returns Path - string
+     */
+    getPath(route: keyof Routes<R>): string;
+    /**
+     * Get the path from the route and route params
+     * @param route Route that will be used to direct
+     * @param routeParams Parameters that will be applied to the route
+     * @returns Path - string
+     */
+    getPathWithParams<T extends keyof Routes<R>>(route: T, routeParams?: Record<Routes<R>[T], string | number>): string;
+    /**
+     * Function to navigate to the previous page, if history is enabled, the penultimate record will be used,
+     * otherwise the browser's own api with "history.back()"
+     */
+    goBack(): void;
+    /**
+     * Main function to navigate between the app using the route system with dynamic parameters
+     * @param route Route that will be used to direct
+     * @param options Route parameters (marked by {{}}), which will be automatically shown if they exist, and navigator options and route queryParams can also be passed through the "params" property
+     */
+    navigate<T extends keyof Routes<R>>(route: T, options?: Record<Routes<R>[T], string | number> & O & {
+        params?: RouteParams;
+    }): void;
+    /**
+     * Calls the navigator to direct the user to a page
+     * @param path Path to which the user will be taken
+     * @param options Options that will be passed to the navigator
+     * @param info Information that will be added to the history
+     */
+    to(path: RoutePath, options?: O, info?: {}): void;
+    /**
+     * Clear history data
+     */
+    wipeHistory(): void;
+}
+//# sourceMappingURL=navigation.d.ts.map

package/dist/navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../src/navigation.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAY,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAU9F,YAAY,EACV,SAAS,EACT,MAAM,GACP,CAAA;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,EAAE,EAAE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,EAAE;IACjG,OAAO,CAAC,QAAQ,CAAc;IAE9B,OAAO,CAAC,MAAM,CAAwB;IAEtC,IAAI,OAAO,YAEV;IAEM,OAAO,EAAE,CAAC,CAAU;IAE3B,OAAO,CAAC,UAAU;IAkBlB,OAAO,CAAC,KAAK;IAOb,OAAO,CAAC,SAAS,CAAgD;IAEjE,OAAO,CAAC,MAAM,CAAa;IAE3B;;;;;;;;OAQG;gBAED,MAAM,EAAE,CAAC,EACT,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,MAAM,GAAE,MAAW;IAOrB;;;;;;OAMG;IACI,cAAc,CAAC,CAAC,SAAS,MAAM,MAAM,CAAC,CAAC,CAAC,EAC7C,KAAK,EAAE,CAAC,EAER,WAAW,GAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAa,EAC9D,KAAK,UAAQ;IA+Bf;;;;OAIG;IACI,OAAO,CAAC,KAAK,EAAE,MAAM,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM;IAmB9C;;;;;OAKG;IACI,iBAAiB,CAAC,CAAC,SAAS,MAAM,MAAM,CAAC,CAAC,CAAC,EAChD,KAAK,EAAE,CAAC,EAER,WAAW,GAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAa;IAyBhE;;;OAGG;IACI,MAAM;IAuBb;;;;OAIG;IACI,QAAQ,CAAC,CAAC,SAAS,MAAM,MAAM,CAAC,CAAC,CAAC,EACvC,KAAK,EAAE,CAAC,EAER,OAAO,GAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAc;IA6D3F;;;;;OAKG;IACI,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,CAAwB,EAAE,IAAI,KAAK;IAQvE;;OAEG;IACI,WAAW;CAGnB"}

package/dist/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Recursively extracts the names of all `{{param}}` placeholders from a route
+ * string literal as a union of string literal types.
+ *
+ * Returns `never` when the string contains no placeholders, making it safe to
+ * use as a constraint — a route with no params produces an empty `Record<never, …>`.
+ */
+export type ExtractParams<T extends string> = T extends `${infer _Start}{{${infer Param}}}${infer Rest}` ? Param | ExtractParams<Rest> : never;
+type Params<T> = {
+    [K in keyof T]: T[K] extends string ? ExtractParams<T[K]> : Params<T[K]>;
+};
+type ExtractRoutes<T, PM, Prefix extends string = ''> = {
+    [K in keyof T & string]: T[K] extends string ? {
+        [P in `${Prefix}${Prefix extends '' ? '' : '.'}${K}`]: PM[K];
+    } : ExtractRoutes<T[K], PM[K], `${Prefix}${Prefix extends '' ? '' : '.'}${K}`>;
+}[keyof T];
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
+/**
+ * Flattens a nested route definition object into a single map of dot-separated
+ * route keys → union of their `{{param}}` placeholder names.
+ *
+ * The resulting intersection type is what `Navigation` uses to enforce that
+ * every call to `navigate` or `isCurrentRoute` supplies exactly the params
+ * declared in the corresponding route string — no more, no fewer.
+ */
+export type Routes<T> = UnionToIntersection<ExtractRoutes<T, Params<T>>>;
+/** An unresolved URL pathname string, before param substitution. */
+export type RoutePath = string;
+/** A map of query-string or URL segment key–value pairs, both typed as `string`. */
+export type RouteParams = {
+    [x: string]: string;
+};
+/**
+ * The function signature every platform-specific navigator adapter must satisfy.
+ *
+ * `O` carries platform options (e.g. Next.js router options, `replace` flag).
+ * `C` is the shared context object set on `Navigation.context`; pass it through
+ * to give the adapter access to auth state, locale, etc. without coupling the
+ * types to a specific app.
+ */
+export type Navigator<O extends object = {}, C extends Record<string, any> = {}> = (path: RoutePath, options: O, context?: C) => void;
+/** Escape hatch for untyped key–value bags used internally during deep-merge operations. */
+export type AnyValue = {
+    [key: string]: any;
+};
+/**
+ * A single entry appended to the internal navigation history.
+ *
+ * `origin` is `null` in SSR environments where `window` is unavailable.
+ * `metadata` is whatever `Config.getMetadata()` returns at the moment of
+ * navigation — use this to capture auth state, feature flags, etc.
+ * `info` is the merged options + caller-supplied info blob stored for `goBack`.
+ */
+export type HistoryData = {
+    origin: string;
+    date: Date;
+    path: RoutePath;
+    metadata: any;
+    info: any;
+};
+/**
+ * Indexed map of history entries keyed by insertion order (1-based).
+ * Only populated when `Config.historyEnabled` is `true`.
+ */
+export type History = Record<number, HistoryData>;
+export type Config = {
+    /**
+     * When `true`, every call to `Navigation.to` appends an entry to the internal
+     * history log and `goBack` uses that log instead of `window.history.back()`.
+     * Defaults to `false`.
+     */
+    historyEnabled?: boolean;
+    /**
+     * Called at navigation time to capture a snapshot of arbitrary app state
+     * (e.g. current user, locale). The return value is stored in `HistoryData.metadata`.
+     */
+    getMetadata?: () => any;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,MAAM,IACxC,CAAC,SAAS,GAAG,MAAM,MAAM,KAAK,MAAM,KAAK,KAAK,MAAM,IAAI,EAAE,GACxD,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,GAC3B,KAAK,CAAA;AAET,KAAK,MAAM,CAAC,CAAC,IAAI;KACd,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACzE,CAAA;AAGD,KAAK,aAAa,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,SAAS,MAAM,GAAG,EAAE,IAAI;KACrD,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,GACtB,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GACjB;SAEC,CAAC,IAAI,GAAG,MAAM,GAAG,MAAM,SAAS,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;KAC7D,GACC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,GAAG,MAAM,SAAS,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,CAAC,EAAE,CAAC;CAC7E,CAAC,MAAM,CAAC,CAAC,CAAA;AAEV,KAAK,mBAAmB,CAAC,CAAC,IACxB,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;AAErF;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,mBAAmB,CAAC,aAAa,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAIxE,oEAAoE;AACpE,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAE9B,oFAAoF;AACpF,MAAM,MAAM,WAAW,GAAG;IACxB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CACpB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,EAAE,EAAE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,KAAK,IAAI,CAAA;AAErI,4FAA4F;AAC5F,MAAM,MAAM,QAAQ,GAAG;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CACnB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,IAAI,CAAA;IACV,IAAI,EAAE,SAAS,CAAA;IACf,QAAQ,EAAE,GAAG,CAAA;IACb,IAAI,EAAE,GAAG,CAAA;CACV,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;AAEjD,MAAM,MAAM,MAAM,GAAG;IACnB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,CAAA;CACxB,CAAA"}

package/package.json

@@ -1,7 +1,20 @@
 {
   "name": "@codeleap/web-navigation",
-  "version": "6.2.3",
+  "version": "6.8.0",
   "main": "src/index.ts",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
   "license": "UNLICENSED",
   "repository": {
     "url": "https://github.com/codeleap-uk/internal-libs-monorepo.git",
@@ -12,10 +25,11 @@
     "ts-node-dev": "1.1.8"
   },
   "scripts": {
-    "build": "echo 'No build needed'"
+    "build": "tsc --build tsconfig.build.json",
+    "typecheck": "bun tsc --noEmit -p ./tsconfig.json"
   },
   "peerDependencies": {
-    "typescript": "5.5.2",
+    "typescript": "6.0.3",
     "@fastify/deepmerge": "3.1.0"
   }
-}
+}

package/src/navigation.tsx

@@ -13,6 +13,18 @@ export type {
   Routes,
 }
 
+/**
+ * Type-safe navigation controller that wraps a platform-specific navigator
+ * (e.g. Next.js `router.push`) and enforces route param contracts at compile time.
+ *
+ * `R` is the routes definition object — nested keys map to `{{param}}`-bearing
+ * path strings. `O` is the navigator's option bag. `C` is the shared context
+ * forwarded to every navigator call so adapters can read app-level state without
+ * closure coupling.
+ *
+ * The class is SSR-safe: any method that touches `window` or `history` short-circuits
+ * when running outside a browser environment.
+ */
 export class Navigation<O extends object, R extends object = {}, C extends Record<string, any> = {}> {
   private _history: History = {}
 
@@ -29,7 +41,7 @@ export class Navigation<O extends object, R extends object = {}, C extends Recor
 
     const origin = IS_SSR ? null : window?.location?.origin
 
-    const value: History = {
+    const value = {
       [idx]: {
         origin,
         date: new Date(),
@@ -37,7 +49,7 @@ export class Navigation<O extends object, R extends object = {}, C extends Recor
         metadata: this.config?.getMetadata?.(),
         info,
       },
-    }
+    } as unknown as History
 
     this._history = this.merge(this._history, value)
   }
@@ -49,16 +61,25 @@ export class Navigation<O extends object, R extends object = {}, C extends Recor
     )
   }
 
-  private navigator: Navigator<O> = null
+  private navigator: Navigator<O> = null as unknown as Navigator<O>
 
   private routes: R = {} as R
 
+  /**
+   * @param routes Nested object whose leaf values are path strings with optional
+   *   `{{param}}` placeholders. Dot-notation keys derived from this object become
+   *   the typed route identifiers accepted by `navigate`, `getPath`, etc.
+   * @param navigator Platform adapter called for every navigation; receives the
+   *   resolved path, stripped options, and the current `context` value.
+   * @param config Optional behaviour flags. Merged with defaults, so partial
+   *   configs are safe.
+   */
   constructor(
     routes: R,
     navigator: Navigator<O, C>,
     config: Config = {},
   ) {
-    this.navigator = navigator
+    this.navigator = navigator as unknown as Navigator<O>
     this.routes = routes
     this.config = this.merge(this.config, config)
   }
@@ -119,7 +140,7 @@ export class Navigation<O extends object, R extends object = {}, C extends Recor
       const indexesAccess = route?.split('.')
 
       for (const index of indexesAccess) {
-        path = path?.[index]
+        path = (path as Record<string, any>)?.[index]
       }
     } else {
       // @ts-ignore
@@ -143,7 +164,7 @@ export class Navigation<O extends object, R extends object = {}, C extends Recor
     let path = this.getPath(route)
 
     for (const key in routeParams) {
-      const value = String(routeParams?.[key])
+      const value = String((routeParams as Record<string, any>)?.[key])
 
       const searchPartial = `{{${key}}}`
 
@@ -210,7 +231,7 @@ export class Navigation<O extends object, R extends object = {}, C extends Recor
     const queryParamsKey = 'params'
 
     for (const key in options) {
-      const value = options?.[key]
+      const value = (options as Record<string, any>)?.[key]
 
       const searchPartial = `{{${key}}}`
 
@@ -230,12 +251,12 @@ export class Navigation<O extends object, R extends object = {}, C extends Recor
     }
 
     if (typeof params === 'object') {
-      let searchParams = null
+      let searchParams: string | null = null
 
       for (const paramKey in (params ?? {})) {
         const value = params?.[paramKey]
         const param = `${paramKey}=${encodeURIComponent(value)}`
-        const separator = searchParams == null ? '' : '&'
+        const separator: string = searchParams == null ? '' : '&'
 
         searchParams = `${searchParams ?? ''}${separator}${param}`
       }
@@ -265,7 +286,7 @@ export class Navigation<O extends object, R extends object = {}, C extends Recor
    * @param options Options that will be passed to the navigator
    * @param info Information that will be added to the history
    */
-  public to(path: RoutePath, options: O = null as O, info = {}) {
+  public to(path: RoutePath, options: O = null as unknown as O, info = {}) {
     if (this.config.historyEnabled) {
       this.putHistory(path, this.merge(options, info))
     }

package/src/types.ts

@@ -1,3 +1,10 @@
+/**
+ * Recursively extracts the names of all `{{param}}` placeholders from a route
+ * string literal as a union of string literal types.
+ *
+ * Returns `never` when the string contains no placeholders, making it safe to
+ * use as a constraint — a route with no params produces an empty `Record<never, …>`.
+ */
 export type ExtractParams<T extends string> =
   T extends `${infer _Start}{{${infer Param}}}${infer Rest}`
   ? Param | ExtractParams<Rest>
@@ -21,22 +28,49 @@ type ExtractRoutes<T, PM, Prefix extends string = ''> = {
 type UnionToIntersection<U> =
   (U extends any ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never
 
+/**
+ * Flattens a nested route definition object into a single map of dot-separated
+ * route keys → union of their `{{param}}` placeholder names.
+ *
+ * The resulting intersection type is what `Navigation` uses to enforce that
+ * every call to `navigate` or `isCurrentRoute` supplies exactly the params
+ * declared in the corresponding route string — no more, no fewer.
+ */
 export type Routes<T> = UnionToIntersection<ExtractRoutes<T, Params<T>>>
 
 // Navigation types
 
+/** An unresolved URL pathname string, before param substitution. */
 export type RoutePath = string
 
+/** A map of query-string or URL segment key–value pairs, both typed as `string`. */
 export type RouteParams = {
   [x: string]: string
 }
 
+/**
+ * The function signature every platform-specific navigator adapter must satisfy.
+ *
+ * `O` carries platform options (e.g. Next.js router options, `replace` flag).
+ * `C` is the shared context object set on `Navigation.context`; pass it through
+ * to give the adapter access to auth state, locale, etc. without coupling the
+ * types to a specific app.
+ */
 export type Navigator<O extends object = {}, C extends Record<string, any> = {}> = (path: RoutePath, options: O, context?: C) => void
 
+/** Escape hatch for untyped key–value bags used internally during deep-merge operations. */
 export type AnyValue = {
   [key: string]: any
 }
 
+/**
+ * A single entry appended to the internal navigation history.
+ *
+ * `origin` is `null` in SSR environments where `window` is unavailable.
+ * `metadata` is whatever `Config.getMetadata()` returns at the moment of
+ * navigation — use this to capture auth state, feature flags, etc.
+ * `info` is the merged options + caller-supplied info blob stored for `goBack`.
+ */
 export type HistoryData = {
   origin: string
   date: Date
@@ -45,9 +79,22 @@ export type HistoryData = {
   info: any
 }
 
+/**
+ * Indexed map of history entries keyed by insertion order (1-based).
+ * Only populated when `Config.historyEnabled` is `true`.
+ */
 export type History = Record<number, HistoryData>
 
 export type Config = {
+  /**
+   * When `true`, every call to `Navigation.to` appends an entry to the internal
+   * history log and `goBack` uses that log instead of `window.history.back()`.
+   * Defaults to `false`.
+   */
   historyEnabled?: boolean
+  /**
+   * Called at navigation time to capture a snapshot of arbitrary app state
+   * (e.g. current user, locale). The return value is stored in `HistoryData.metadata`.
+   */
   getMetadata?: () => any
 }

package/package.json.bak

@@ -1,21 +0,0 @@
-{
-  "name": "@codeleap/web-navigation",
-  "version": "6.2.3",
-  "main": "src/index.ts",
-  "license": "UNLICENSED",
-  "repository": {
-    "url": "https://github.com/codeleap-uk/internal-libs-monorepo.git",
-    "type": "git",
-    "directory": "packages/web-navigation"
-  },
-  "devDependencies": {
-    "ts-node-dev": "1.1.8"
-  },
-  "scripts": {
-    "build": "echo 'No build needed'"
-  },
-  "peerDependencies": {
-    "typescript": "5.5.2",
-    "@fastify/deepmerge": "3.1.0"
-  }
-}