aurelia / path

Utilities for path manipulation.

Aurelia 2

This is the Aurelia 2 monorepo, containing core and plugin packages, examples, benchmarks, and documentation for the upcoming major version of everybody's favorite modern JavaScript framework, Aurelia.

Introduction

Aurelia is a modern, front-end JavaScript framework for building browser, mobile, and desktop applications. It focuses on aligning closely with web platform specifications, using convention over configuration, and having minimal framework intrusion. Basically, we want you to just write your code without the framework getting in your way. 😉

Aurelia applications are built by composing a series of simple components. By convention, components are made up of a vanilla JavaScript or Typescript class, with a corresponding HTML template.

//app.js
export class App {
  welcome = "Welcome to Aurelia";

  quests = [
    "To seek the holy grail",
    "To take the ring to Mordor",
    "To rescue princess Leia"
  ];
}

<!-- app.html -->
<form>
  <label>
    <span>What is your name?</span>
    <input value.bind="name & debounce:500">
  </label>

  <label>
    <span>What is your quest?</span>
    <select value.bind="quest">
      <option></option>
      <option repeat.for="q of quests">${q}</option>
    </select>
  </label>
</form>

<p if.bind="name">${welcome}, ${name}!</p>
<p if.bind="quest">Now set forth ${quest.toLowerCase()}!</p>

This example shows you some of the powerful features of the aurelia binding syntax. To learn further, please see our documentation.

Feeling excited? Check out how to use makes to get started in the next section.

Note: Please keep in mind that Aurelia 2 is still in beta. A number of features and use cases around the public API are still untested and there will be a few more breaking changes.

Getting Started

First, ensure that you have Node.js v8.9.0 or above installed on your system. Next, using npx, a tool distributed as part of Node.js, we'll create a new Aurelia 2 app. At a command prompt, run the following command:

npx makes aurelia

This will cause npx to download the makes scaffolding tool, along with the aurelia generator, which it will use to guide you through the setup process. Once complete, you'll have a new Aurelia 2 project ready to run. For more information on Aurelia's use of makes, see here. If you aren't interested in taking our preferred approach to generating a project, you can also see the examples folder in this repo for pure JIT setups (no conventions) with various loaders and bundlers.

Documentation

You can read the documentation on Aurelia 2 here. Our new docs are currently a work-in-progress, so the most complete documentation is available in our getting started section. If you've never used Aurelia before, you'll want to begin with our Quick Start Guide.

Contributing

If you are interested in contributing to Aurelia, please see our contributor documentation for more information. You'll learn how to build the code and run tests, how best to engage in our social channels, how to submit PRs, and even how to contribute to our documentation. We welcome you and thank you in advance for joining with us in this endeavor.

Staying Up-to-Date

To keep up to date on Aurelia, please visit and subscribe to the official blog and our email list. We also invite you to follow us on twitter. If you have questions, have a look around our Discourse forum. For chat on Aurelia 2, join our new Aurelia 2 community on Discord. If you'd like to join the growing list of Aurelia sponsors, please back us on Open Collective.

License

Aurelia is MIT licensed. You can find out more and read the license document here.

path's Issues

Relative paths starting with '../' are parsed incorrectly in join()

I'm submitting a bug report

• Library Version:
  1.1.1

Current behavior:

join('../other/app','/url')
// result: 'other/app/url'

Expected/desired behavior:

join('../other/app','/url')
// result: '../other/app/url'

When using parent path reference, join() removes the previous value from the path array. If the parent reference is at the start of the path, it gets removed and ignored:

https://github.com/aurelia/path/blob/1.1.1/src/index.js#L87-L88

This could be fixed by leaving the parent reference in the path if it is at the start of the path.

Pluses get replaced with spaces

I'm submitting a bug report

• Library Version:
  1.1.3

Please tell us about your environment:

• Operating System:
  Windows 10

• Node Version:
  8.9.4

• NPM Version:
  6.9.0

• JSPM OR Webpack AND Version
  webpack 4.30.0

• Browser:
  all

• Language:
  all

Current behavior:
Passing + in a url parameter results in an argument to activate function where + is replaced with [space]

Expected/desired behavior:

• What is the expected behavior?
  + is passed as is

• What is the motivation / use case for changing the behavior?
  Previously, a path would be passed unencoded which correctly translated to view parameters. Now, when the + appears in the path, the line

  path/src/index.js

  Line 229 in 0be13f7

  let pairs = query.replace(/\+/g, ' ').split('&');

  replaces it with a space.
  This breaks scenarios with Asp.Net Identity password reset codes for example.

Prototype Pollution

I'm submitting a bug report

parseQueryString of aurelia path is vulnerable to prototype pollution.

POC
aurelia blog is using parseQueryString to parse location.search, so it is vulnerable to prototype pollution

1. Open the following URL: https://aurelia.io/blog/?__proto__[asdf]=asdf
2. Open Devtools Console, and check the Object.prototype
3. You can notice Object being polluted with the "asdf" property.

Aurelia path 1.1.2 is a breaking change (and therefore should be a higher version bump)

I'm submitting a bug report

• Library Version:
  1.1.2

• Operating System:
  OSX 10.14.2

• Node Version:
  11.4.0

• NPM Version:
  6.5.0

• JSPM OR Webpack AND Version
  webpack 4.16.2

• Browser:
  IE 11

• Language:
  ESNext

Current behavior:

IE11 crashes on a syntax error caused by leaking ESNext statements.

Webpack supports both module as main as resolver and is, in many cases configured (due to performance) to ignore babel transpilation for "node_modules". Because of this many packages (including aurelia-path) ship transpiled versions listed in the main section of package.json.

Aurelia-path 1.1.2 adds a module key to package.json to supply an alternative es2015 build.

Webpack, by default, is configured to load resolve both module and main but the first has the highest priority. This means that previous aurelia-path 1.1.1 (e.g. as dependency of aurelia-http-client) worked fine in a webpack+babel environment, but 1.1.2 leaked ESNext code into the bundle introducing breaking changes. I noticed this as a package depending on aurelia-http-client started (depending on aurelia-path) started failing on IE11

• What is the expected behavior?

The behaviour I expect is either a non-breaking change or a major version bump leading to a clean migration path without any failing builds on existing packages/implementations. I can see the benefit of adding module in package.json but dealing with this requires work from the user's end.

• What is the motivation / use case for changing the behavior?

Semver is intended to avoid conflicts in upgraded between package. NPM's versioning system is designed to deal with this and will, automatically resolve the best suitable working version based on its version definition listed in package.json. Because 1.1.2 was listed as a patch release. NPM thinks it's OK to use it as dependency for aurelia-http-client where it actually introduced breaking changes for a lot of environments.

Builded query string doesn't match rfc standard

I'm submitting a bug report

• Library Version:
  1.0.0

Please tell us about your environment:

• Operating System:
  Ubuntu 16.10
• Node Version:
  6.3.1
• NPM Version:
  3.10.3
• JSPM OR Webpack AND Version
  JSPM 0.16.42
• Browser:
  all
• Language:
  all

Current behavior:
If you pass an object, which contains an array, to buildQueryString function, it returns a not standard conform query string.
Current result:
decodeURIComponent(buildQueryString({list: [1, 2, 3]})) === 'list[]=1&list[]=2&list[]=3'

Expected/desired behavior:
In the RFC 6570 standard for URI templates is written that an array parameter has no braces but is just repeated multiple times.
https://tools.ietf.org/html/rfc6570#section-3.2.8

Therefor the check in buildParam (https://github.com/aurelia/path/blob/master/src/index.js#L125)
for Arrays there should be a key without braces.
The correct result should be:
decodeURIComponent(buildQueryString({list: [1, 2, 3]})) === 'list=1&list=2&list=3'

Correct me if I'm wrong of if I misunderstood anything.

dates are ignored when building query strings

I'm submitting a bug report

• Library Version:
  1.0.0

Please tell us about your environment:

• Operating System:
  Windows 10
• Node Version:
  5.11.1
• NPM Version:
  3.10.5
• JSPM OR Webpack AND Version
  JSPM 0.16.39
• Browser:
  All probably. Chrome 52.0.2743.116 m (64-bit)
• Language:
  ESNext

Current behavior:
Dates are not made into parameters they are ignored. This is as a result of the if (typeof (value) === 'object') check on line 128 resolving true for dates.

Expected/desired behavior:
gist.run is down(??) so I can't show the behaviour currently.

• What is the expected behavior?
  I believe line 128 should also check that it is not a date and let it fall through into the else block so that the date is present in the query string.
• What is the motivation / use case for changing the behavior?
  I can't put dates directly in query strings, though I appreciate it's probably wise to format the date explicitly first into a string and will be my local work around/fix.

Objects seralization/deserialization with buildQueryString and parseQueryString

It's not a bug.
But it will be great if buildQueryString and parseQueryString methods will support objects serialization/deserialization like jQuery.param and jquery-deparam did.
Or at least possibility to overwrite this methods on framework level, because now it's impossible.

parseQueryString method parse array with one element as object

Can be easilly checked by following fixture:

expect(parse('a[0]=b')).toEqual({a: ['b']});

buildQueryString should not force to use brackets around nested properties

I'm submitting a feature request

• Library Version:
  aurelia-path 1.1.5

Please tell us about your environment:

• Operating System:
  Ubuntu

• Node Version:
  13.0.1

• NPM Version:
  6.12.0

• JSPM OR Webpack AND Version
  webpack 4.41.2

• Browser:
  all

• Language:
  all

Current behavior:

buildQueryString with complex object returns a query string where nested properties (example : author.lastname) are surrounded by square brackets. Exemple : author[lastname].

Expected/desired behavior:

For JS server I guess it is equal, since author.lastname and author["lastname"] are the same, but in Java (and probably in .NET), brackets are only use if the property is indexed (a Map or a List if a number is between the brackets).

• What is the expected behavior?

it would be nice to add a parameter to the buildQueryString method, so the caller can choose a strategy (dot, brackets). dot could even be the default strategy if it makes no difference for JS web servers.

• What is the motivation / use case for changing the behavior?

better compatibility with non JS web servers.

Latest v1.1.4 didnot update dist files.

I'm submitting a bug report
I'm submitting a feature request

• Library Version:
  1.1.4

Please tell us about your environment:

• Operating System:
  All

• Node Version:
  N/A

• NPM Version:
  N/A

• JSPM OR Webpack AND Version
  N/A

• Browser:
  all

• Language:
  all

Current behavior:

dist files are same as old 1.1.3.

Expected/desired behavior:

• What is the expected behavior?

To update dist files with 1.1.4 source changes.

• What is the motivation / use case for changing the behavior?

Query string parameters gets sorted

This isn't a bug, but what's the reasoning behind sorting the query string parameters when building it?
https://github.com/aurelia/path/blob/master/src/index.js#L118

Sorting them seems unnecessary to me. Is it just to make any test case happy? Object.keys return the keys in arbitrary order, so are they just sorted to make the assertions in tests easier to implement?

A guy in chat had a scenario, where he wanted to control the parameter ordering. He wanted the search query key to come first q=some-search. This should be possible, if the keys weren't being sorted. Usually the browsers will return the keys in the order they were declared on the object like:

//b will be printed before a
var obj = {b:1, a:2, c:3};

for (var prop in obj) {
  console.log("obj." + prop + " = " + obj[prop]);
}

I know you can't count on the browsers to act this way given the documentation.