SpecnoRoutes

The official Routes library for Specno.

npm i @specno/routes

SpecnoRoutes assists in making routing within Angular more explicit and typesafe. It aims to provide a more conventionalized approach to declaring and interacting with Routes throughout your application

Example use

1// core/consts/paths.ts
2import { BuildPaths, Path, ParamPath } from '@specno/routes';
3
4// config is optional
5const config = {
6    shouldEncodeURIComponents: true,
7};
8export const PATHS = BuildPaths(
9    {
10        Home: Path('home', {
11            AboutUs: Path('about-us')
12        }),
13        Store: ParamPath('storeId')
14        Product: ParamPath('productId')
15    },
16    config
17);

1// app-routing.module.ts
2import { NgModule } from '@angular/core';
3import { RouterModule, Routes } from '@angular/router';
4import { PATHS } from './core/consts';
5
6const routes: Routes = [
7  {
8    path: PATHS.Home._RelativePath,
9    children: [
10      {
11        path: '',
12        component: HomeComponent,
13      },
14      {
15        path: PATHS.Home.AboutUs,
16        component: _RelativePath,
17      },
18    ],
19  },
20  {
21    path: PATHS.Store._RelativePath,
22    component: StoreComponent,
23  },
24  {
25    path: PATHS.Product._RelativePath,
26    component: ProductComponent,
27  },
28];
29
30@NgModule({
31  imports: [RouterModule.forRoot(routes)],
32  exports: [RouterModule],
33})
34export class AppRoutingModule {}

1// app.component.ts
2import { Component, OnInit } from '@angular/core';
3import { Router } from '@angular/router';
4import { PATHS } from './core/consts';
5
6@Component({
7  selector: 'app-root',
8  templateUrl: 'app.component.html',
9  styleUrls: ['app.component.scss'],
10})
11export class AppComponent implements OnInit {
12  constructor(private router: Router) {}
13
14  ngOnInit() {}
15
16  navigateToHome() {
17    this.router.navigateByUrl(PATHS.Home._Path);
18  }
19  navigateToAboutUs() {
20    this.router.navigateByUrl(PATHS.Home.AboutUs._Path);
21  }
22  navigateToStore(storeId: string) {
23    this.router.navigateByUrl(PATHS.Store._PathWithParams(storeId));
24  }
25  navigateToProduct(productId: string) {
26    this.router.navigateByUrl(PATHS.Product._PathWithParams(productId));
27  }
28}

Compatibility

Since this library has been built using only typescript - it should be compatible with most, if not all, other typescript based projects.

Having troubles?

Try get help on our Dev Slack Channel first. If your issue is still persisting and there's no assistance provided by our slack channel - then I would suggest submitting a ticket to our Jira Board.

NOTE: SpecnoRoutes is maintained by Specnites so any issue you can encounter, document and fix, is an issue another Specnite won't have deal with in the future - saving blood, sweat and potentially tears.

Developer Guide

Using SpecnoRoutes is really straight forward and shouldn't be difficult to interact with.

Path

Should be used when creating paths without any parameters.

1const home = Path('home');
2// path is set to "home"
3
4const parent = Path('parent', {
5  child: Path('child'),
6});
7// path is set to "parent" and "child" respectfully

ParamPath

Should be used when creating paths with parameters.

1const store = ParamPath('storeId');
2// path is set to ":storeId"
3// notice the ":" prefixing the provided path
4
5const parent = ParamPath('parent', {
6  child: ParamPath('child'),
7});
8// path is set to ":parent" and ":child" respectfully
9// notice the ":" prefixing the provided paths

NOTE: Path and ParamPath should not be used outside of BuildPaths as they provide no value outside of BuildPaths.

BuildPaths

This is where a majority of the work is done. BuildPaths essentially compiles your Paths and ParamPaths into a dictionary that provides some additional utility.

BuildPaths takes in two arguments:

1. Path Dictionary
2. Config

Path Dictionary

A simple key-value pair with the values being a Path or ParamPath. The keys will be used when interacting with the result of BuildPaths.

1const PathDictionary = {
2  Home: Path('home', {
3    AboutUs: Path('about-us', {
4      ContactUs: Path('contact-us'),
5    }),
6  }),
7};

Config

Currently only supports configuring shouldEncodeURIComponents.

1const config = {
2  shouldEncodeURIComponents: true,
3};

shouldEncodeURIComponents Indicates whether or not you wish to URI Encode the result of _PathWithParams and _RelativePathWithParams.

1const PATHS = BuildPaths({
2  Product: Path('product', {
3    ProductId: ParamPath('productId'),
4  }),
5});
6PATHS.Product.ProductId._Path;
7// 'product/:productId'
8
9// completely valid ShopifyId
10const productId = 'SomeIdThatEndsInEquals==';
11
12// NON-URI encoded: Unsafe as a URL
13// shouldEncodeURIComponents = FALSE
14PATHS.Product.ProductId._PathWithParams(productId);
15// 'product/SomeIdThatEndsInEquals=='
16// == is not a valid URL and will likely break your navigation
17
18// URI encoded: Completely safe as a URL
19// shouldEncodeURIComponents = TRUE
20PATHS.Product.ProductId._PathWithParams(productId);
21// 'product/SomeIdThatEndsInEquals%3D%3D'

Compiled Path Properties

Each path defined within BuildPaths has a number of default properties:

_Path:

Your path including its parent's path

1const PATHS = BuildPaths({
2  Home: Path('home', {
3    AboutUs: Path('about-us', {
4      ContactUs: Path('contact-us'),
5    }),
6  }),
7});
8
9PATHS.Home.AboutUs._Path;
10// home/about-us
11
12PATHS.Home.AboutUs.ContactUs._Path;
13// home/about-us/contact-us

_RelativePath:

Your path excluding its parent's path

1const PATHS = BuildPaths({
2  Home: Path('home', {
3    AboutUs: Path('about-us', {
4      ContactUs: Path('contact-us'),
5    }),
6  }),
7});
8
9PATHS.Home.AboutUs._RelativePath;
10// about-us
11
12PATHS.Home.AboutUs.ContactUs._RelativePath;
13// contact-us

_PathWithParams and _RelativePathWithParams:

Functions that return the appropriate path with the params swapped out with the provided values

1const PATHS = BuildPaths({
2  Store: ParamPath('storeId', {
3    Product: ParamPath('productId'),
4  }),
5});
6
7PATHS.Store._Path;
8// :storeId
9PATHS.Store._PathWithParams(1234);
10// 1234
11PATHS.Store.Product._Path;
12// :storeId/:productId
13PATHS.Store.Product._PathWithParams(1234, 5678);
14// 1234/5678

WARNING: You may notice all of the attributes are prefixed with _, this is purely to avoid any conflict between an attribute name and a child path. Writing paths that overlap with these attributes may result in unexpected problems.