FlexPath attempts to translate the concept of Python's *args and **kwargs into an alternative URL scheme, with the aim of enhancing functionality and flexibility on SPAs. It manages the history state machine and <a> tag interactions, while allowing for complete control over the current path, arguments and parameters.

• Getting Started
  • Usage
  • Naming & Scheme
  • Handling updates & events
  • React integration
  • Background & Motivation
• API Reference
• Patch Notes
• TODOs (aka. "plans for the future")

To start using the FlexPath library, you need to - for sure - import it first:

import FlexPath from 'flex-path';

From this point on, each <a>-tag will be routed through the FlexPath system, respecting the target attribute. From now on, you can easily use HTML <a> tags or the FlexPath API to navigate your page. Each modification to the FlexPath state machine will immediately update the URL accordingly.

/*** NAVIGATE SOMEWHERE ***/
FlexPath.args.Update("home", "info");
//   --> /home/info

// This can also be done by path strings...
FlexPath.raw = "/home/info"
// ...or by function call
FlexPath.NavigateTo("/home/info");



/*** UPDATE ARGUMENT 1 ***/
FlexPath.args.Set(1, "about");
//   --> /home/about

/*** UPDATE KWARG FOR SORTING ***/
FlexPath.kwargs.Set("sort", "name");
//   --> /home/about/sort:name

/*** GO TO HOME PAGE ***/
FlexPath.args.Clear();
//   --> /

/*** APPLY MULTIPLE CHANGES BY FREEZING ***/
FlexPath.Freeze();	  // <-- Everything after that won't be immediately applied
FlexPath.args.Update("shop", "items");
FlexPath.kwargs.Set("category", "pets");
FlexPath.kwargs.Set("sort", "relevant");
FlexPath.search.Set("view", "1");
FlexPath.Unfreeze();  // <-- Hereby any changes will be applied at once
//   --> /shop/items/category:pets/sort:relevant?view=1

⚠️ It is highly recommended NOT to use the standard APIs such as history.pushState or location.hash for changing the navigation along this, as they will likely collide with the FlexPath system.

FlexPath deconstructs any URL pathname by the following scheme:

   /arg1/arg2/kwarg1:x/kwarg2:y?query=stuff#hash/can:be?the=same
   |--ARGS---|-----KWARGS------|--SEARCH--|--------HASH---------|

• ARGS are the "traditional" positional arguments, handled by a positional stack controller. This can be used to dictate the basic structure of the current navigation position within the app.
• KWARGS are the new stuff. They come in a key:value representation, being a more readable and slightly more beautiful variant of traditional search query params. Kwargs are handled by a keyword stack controller
  • Multiple keyword arguments can be chained together, so paths like /x:12/x:abc are possible.
  • key literals must consist of alphanumeric symbols as well as _ and -. (same goes for search params)
• SEARCH is nothing new, just good old search queries. These fields are also handled by a keyword stack controller
• HASH represents an entirely seperate subsystem here. While the hash can still be used to e.g. navigate to ID anchors, FlexPath allows for a completely seperate "sub path" to be stored within the hash, itself again consisting of ARGS, KWARGS and SEARCH.

The order is important, so KWARGS cannot precede ARGS. Multiple slashes will be ignored, so //slash////path won't result in multiple empty arguments. The basic idea is to go from this

https://my-webpage.com/shop/items?category=523&filter=shower%20heads&sort=recent

to this

https://my-webpage.com/shop/items/category:523/filter:shower+heads/sort:recent

while still maintaining the ability to extend to search params and even the hash part if really needed. But the ultimate goal should be to prevent bloated URLs such as the above. Ideally, you should only be in need of ARGS and KWARGS.

To watch for any kind of path changes, FlexPath comes with a handful events to watch for updates in the path state machine. Events are provided by the stack controllers, allowing precise listening and flexible handling (see the API Reference for more detailed information).

function handleArg0Update(newArg: string | undefined) {
	// Do something with the new argument value
}

function handleSearchUpdate(newValues: string[]) {
	// keyword argument updates always provide an array
	// due to their ability of containing multiple values
	// for the same key
}

FlexPath.args.OnUpdate(0, handleArg0Update);
FlexPath.kwargs.OnUpdate("search", handleSearchUpdate);


// When you don't wish to receive updates anymore, simply unregister the event
FlexPath.args.OffUpdate(0, handleArg0Update);

To integrate with the React framework more easily, FlexPath optionally provides a set of hooks as well as an abstract class component derivate to simplify path state updates.

import { useFpArg, useFpKwargs } from 'flex-path/react'

function AwesomePathReactiveComponent() {
	const mainPage = useFpArg(0);
	const [search] = useFpKwargs("search")

	return <></>
}

• useFpArgs(): string[]
  Entire positional argument stack
• useFpArg(index: number): string | undefined
  Specific positional argument
• useFpKwargs(key: string): string[]
  Keyword argument values
• useFpSearch(key: string): string[]
  Search param values
• useFpHashArgs(): string[]
  Entire positional argument stack on hash subpath
• useFpHashArg(index: number): string | undefined
  Specific positional argument on hash subpath
• useFpHashKwargs(key: string): string[]
  Keyword argument values on hash subpath
• useFpHashSearch(key: string): string[]
  Search param values on hash subpath

The FlexPathComponent class inherits directly from React's very own Component, so the core functionalities are the same. Other than that, a FlexPathComponent comes with a built-in listener management, so any registered listeners and handlers will only be active after mounting and the initial render call, and are safely unregistered once the component unmounts.

import { FlexPathComponent } from 'flex-path/react'

class AwesomePathReactiveComponent extends FlexPathComponent {
	constructor(props) {
		super(props);
		this.addFpArgListener(0, (newArg) => {...});
		
		// Listeners can also be added without a handler attached.
		// In this case, the event will only re-render the component.
		this.addFpKwargsListener("search");
	}
	
	render() {
		...
	}
}

Any handlers provided to the listener will receive the respective value types described as return types in the Hooks section. From within the class accessible methods are:

• addFpArgsListener(handler?, skipRendering?)
  Entire positional argument stack
• addFpArgListener(index: number, handler?, skipRendering?)
  Specific positional argument
• addFpKwargsListener(key: string, handler?, skipRendering?)
  Keyword argument values
• addFpSearchListener(key: string, handler?, skipRendering?)
  Search param values
• addFpHashArgsListener(handler?, skipRendering?)
  Entire positional argument stack on hash subpath
• addFpHashArgListener(index: number, handler?, skipRendering?)
  Specific positional argument on hash subpath
• addFpHashKwargsListener(key: string, handler?, skipRendering?)
  Keyword argument values on hash subpath
• addFpHashSearchListener(key: string, handler?, skipRendering?)
  Search param values on hash subpath

To prevent further bloatage, no more state storing is done by the class component. Instead, it simply forces a rerender once one of the active listeners is invoked. If you with to handle the values and updates with reacts built-in states instead of manually fetching the values from the FlexPath controller, you need to enable skipRendering and implement this functionality yourself.

Dealing with the traditional URL scheme is fine and all, but with all the different layers, levels, subsystems, and complex structures that an SPA can take on, it can be pretty tough to navigate using classic linear-parametric URL path arguments. Not only can it be a hassle to worry about reliable and comprehensive handling of history events and link clicks, but the linear /one/argument/chase/that/other structure can also get pretty tedious. While it does a great job of representing a directory-like structure (that's where it comes from after all), it doesn't reflect the complexity of SPAs that is sometimes required in an equally useful way.

Search queries should definitely attempt to solve this problem, but they now raise a more aesthetic problem. Sending and receiving completely overloaded links in the style of https://my-page.org/path/to/shop?view=article&filter=advanced%20socks%20with%20ears&orderby=name&ordermd=desc immediately deconstructs any intentions of even trying to understand what the heck is going on there. This method cannot be called visually appealing.

So with that and Python's *args and **kwargs parameter system in mind, FlexPath attempts to union the traditional URL path scheme with a more sleak, modular approach.

Fetches the positional argument value at the given index, if existing.
This version is case insensitive, always returning lowercase.
Returns: string.

Same as above, but includes target specification

Same as above, but allows easy "new tab"-behaviour by targeting to _blank if target is set to true

Freezes the history state machine. This allows multiple updates without invoking a history state call each time.

NOTICE: Remember to Unfreeze() the engine again once you're done!

Unfreezes the history state machine and applys all intermediate updates.

Adds a custom middleware for any navigation events attempting to open an external URL.

Positional stack controllers support direct numeric indexing, just like arrays. This is equivalent to the use of .Get and .Set. The following example displays the analogy of indexing and method usage:

const value = FlexPath.args[0];
//          = FlexPath.args.Get(0);

FlexPath.args[0] = "value";
//      .args.Set(0, "value");

Fetches a complete array of all positional path arguments.
Returns: string[].

Fetches the positional argument value at the given index, if existing.
This version is case insensitive, always returning lowercase.
Returns: string.

This method implements a case sensitive alternative: .GetCase(index)

Updates the positional argument value at the given index. This is possible for any index from 0 to length, which allows updating the "next empty argument".
This version is case insensitive, always updating to lowercase values.

This method implements a case sensitive alternative: .SetCase(index, argument, keepKwargs?, keepSearch?)

Clears the current positional argument stack, essentially navigating to /.

Pops and returns the rightmost argument value from the positional argument stack.
Returns: string.

Pops and returns the amount rightmost argument values.
Returns: string[].

Pushes (inserts) one or more values to the positional argument stack.

This method implements a case sensitive alternative: .PushCase(...arguments)

Updates the entire positional argument stack as a whole, essentially "navigating the path".

This method implements a case sensitive alternative: .UpdateCase(...arguments)

Tests the current stack for the expected length.
Throws otherwise.

Tests the argument at the provided index.
Throws otherwise.

This method implements a case sensitive alternative: .ValidateIndexCase(index, targetValue)

Tests the current stack to match the test pattern.
Throws otherwise.

This method implements a case sensitive alternative: .ValidatePathCase(index, targetValue)

Unregisters a handler function for functional argument update at specified position. This will call for any argument update.

Registers a handler function for functional argument path updates.
Event values will always be returned case sensitive

Unregisters provided handler function if registered.
Signatures are identical to .OnUpdate.

Similar to .OnUpdate equivalents, but registers the provided handler only once, being unregistered right after invocation.
Signatures are identical to .OnUpdate.

Similar to .OnUpdate equivalents, but creates and returns a new CallbackEmitterListener.
Signatures are identical to .OnUpdate.

Keyword stack controllers support direct string literal indexing, just like objects. This is equivalent to the use of .Get and .Set. The following example displays the analogy of indexing and method usage:

const value = FlexPath.args["sort"];
//          = FlexPath.args.Get("sort");

FlexPath.args["sort"] = "value";
//      .args.Set("sort", "value");

Fetches first value for the provided key, if existing.
This version is case insensitive, always returning lowercase.
Returns: string | undefined.

This method implements a case sensitive alternative: .GetCase(key)

Fetches all values for the provided key.
This version is case insensitive, always returning lowercase.
Returns: string[].

This method implements a case sensitive alternative: .GetAllCase(key)

Sets the value(s) for a given key literal. This is overloaded for either working with one string[] argument or multiple string arguments, replacing values with ...values in this case.
This version is case insensitive, always inserting lowercase values.

This method implements a case sensitive alternative: .SetCase(key, values)

Works similar to .Set, but adds the provided values to the key literal instead of replacing them. Duplicate values will be filtered.
This version is case insensitive, always adding lowercase values.

This method implements a case sensitive alternative: .AddCase(key, ...values)

Inversion of .Add, thus removing provided value(s) from the key literal.
This call is always case sensitive

Radical edition of the above, removing the entire key literal and all of it's values from the controller.

Clears all fields of this container.

Validates the existance of any values on the provided key literal.
Throws otherwise.

Validates the existence of all provided values on the provided key literal.
This version is case insensitive, always comparing lowercase values.
Throws otherwise.

This method implements a case sensitive alternative: .ValidateValuesCase(key, ...values)

Registers a handler function for value changes on the provided key.
Event values will always be returned case sensitive

Unregisters provided handler function if registered.
Signatures are identical to .OnUpdate.

Similar to .OnUpdate equivalents, but registers the provided handler only once, being unregistered right after invocation.
Signatures are identical to .OnUpdate.

Similar to .OnUpdate equivalents, but creates and returns a new CallbackEmitterListener.
Signatures are identical to .OnUpdate.

A custom function receiving the following arguments:

A function provided to ExternalUrlMiddleware with the following parameters

(accepted: boolean, options?: ExternalUrlOptions) => void

A partial object that can be passed to EUM$Resolver consisting of following fields:

(newArg: string | undefined) =>  void;

(...args: string[]) =>  void;

(newValues: string[]) =>  void;

• Fixed an issue that caused Vite and rollup to bundle some dependencies in the wrong order, resulting in undefined constructors.
• Singleton class instance will now be initialized at the first getter call by the FlexPath proxy.

• Nothing changed yet, because this is the first version. Yayy!

• Implement logical BACK functionality to e.g. navigate "back to the menu" without the need of manually keeping track of anything
• Optimize quick access usage