aurelia / pal

Aurelia's Platform Abstraction Layer

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.

pal's Issues

aurelia-pal.d.ts is missing

aurelia-pal.d.ts is missing from module specific folders

.d.ts build

In some Aurelia libraries when build and generate .d.ts, sometimes observed duplicate comments.

like:
Line42 and Line45

Spelling error

Aurelia's Platfrom Platform Abstraction Layer

cancelAnimationFrame

Hi guys,
First of all, congratulations for the amazing job done.
I'd like to know as requestAnimationFrame is already available if it is possible to add cancelAnimationFrame.
Thank you very much

Missing d.ts file in jspm install

In beta.1.3.0 the .d.ts file is missing from the JSPM installation.

Error invoking SVGAnalyzer

SUPPORT REQUESTS/QUESTIONS:

I'm submitting a bug report

• Library Version:
  1.0.0

Please tell us about your environment:

• Operating System:
  Linux , Ubuntu(14.04)

• Node Version:
  7.0.0

• NPM Version:
  3.10.8

• JSPM OR Webpack AND Version
  Webpack 2.1.0-beta.22
  on Application, neither webpack nor jspm on the components library

• Browser:
  all | Chrome XX | Firefox XX | Edge XX | IE XX | Safari XX | Mobile Chrome XX | Android X.X Web Browser | iOS XX Safari | iOS XX UIWebView | iOS XX WKWebView

• Language:
  all | TypeScript X.X | ESNext

Current behavior:
I have my application running in one repository using webpack, and I have a reusable components library in a different repo that has neither jspm nor webpack. It is linked to the main application using npm link and being referenced as any node_module would.

Using bindable in my components however causes this error:

Message: _aureliaPal.DOM.createElement is not a function
Inner Error Stack:
TypeError: _aureliaPal.DOM.createElement is not a function
    at createElement (http://localhost:9000/app.bundle.js:104267:29)
    at new SVGAnalyzer (http://localhost:9000/app.bundle.js:104270:9)
    at Object.invoke (http://localhost:9000/aurelia-bootstrap.bundle.js:8470:12)
    at InvocationHandler.invoke (http://localhost:9000/aurelia-bootstrap.bundle.js:8447:166)
    at Container.invoke (http://localhost:9000/aurelia-bootstrap.bundle.js:8700:23)
    at StrategyResolver.get (http://localhost:9000/aurelia-bootstrap.bundle.js:8175:35)
    at Container.get (http://localhost:9000/aurelia-bootstrap.bundle.js:8633:39)
    at Object.invoke (http://localhost:9000/aurelia-bootstrap.bundle.js:8500:103)
    at InvocationHandler.invoke (http://localhost:9000/aurelia-bootstrap.bundle.js:8447:166)
    at Container.invoke (http://localhost:9000/aurelia-bootstrap.bundle.js:8700:23)
    at StrategyResolver.get (http://localhost:9000/aurelia-bootstrap.bundle.js:8175:35)
    at Container.get (http://localhost:9000/aurelia-bootstrap.bundle.js:8633:39)
    at HtmlBehaviorResource.initialize (http://localhost:9000/app.bundle.js:109356:106)
    at ResourceDescription.initialize (http://localhost:9000/aurelia-bootstrap.bundle.js:15373:19)
    at ResourceModule.initialize (http://localhost:9000/aurelia-bootstrap.bundle.js:15294:15)
    at http://localhost:9000/aurelia-bootstrap.bundle.js:15672:18
End Inner Error Stack

It seems that the components library is trying to use a separate aurelia instance than my main application as the components work fine when they are in the main application's repo.

Expected/desired behavior:

• What is the expected behavior?
  I would like the components imported from the external library to run as they would if they were in my application repo.

• What is the motivation / use case for changing the behavior?
  To keep my small reusable pieces separate from my larger specific pieces.

Dynamic Aurelia dependencies

This is a meta-issue to track progress across all Aurelia repos.

In #17 it was decided that using PLATFORM.moduleName(), exported from aurelia-pal was the way to document dynamic dependencies consumed by the aurelia loader.
The function has been added with da92298.

To follow up on that, it must now be used in every aurelia module that has dynamic imports.
Here's a checklist of all modules to track progress, most probably don't need any change at all:

• animator-css
• animator-velocity
• binding
• bootstrapper
• cache
• dependency-injection
• dialog
• event-aggregator
• fetch-client
• framework
• history
• history-browser
• hot-module-reload
• html-import-template-loader
• http-client
• i18n
• loader
• loader-default
• loader-nodejs
• loader-webpack
• logging
• logging-console
• metadata
• pal
• pal-browser
• pal-nodejs
• pal-worker
• protractor-plugin
• route-recognizer
• router
• skeleton-plugin
• task-queue
• templating
• templating-binding
• templating-resources
• templating-router
• testing
• ui-virtualization
• ux
• validation
• web-components

Question: was the work with aurelia.build.resources complete? I.e. if there is no such key in package.json, can I assume the library doesn't need to be modified?

For now I think it's better to keep the aurelia.build.resources in place, in order to not break existing tools. But once this is in place a deprecation is probably in order, with removal at a later stage.

CC: @niieani @EisenbergEffect

Proposal: PLATFORM.bundle / moduleIdFor

Currently, there is no way for tooling to statically generate a list of dynamically loaded modules (i.e. loaded through any of the aurelia-loaders). This means that to bundle properly we've got to maintain this list manually, outside of the source-code, and it's a different list for each bundler:

• the CLI has got the aurelia.json file
• JSPM has got the config.js generated from package.json combo
• System.JS requires the above config file to be maintained manually
• Webpack depends on the aurelia.build.resources listed in package.json and whatever else it is able to analyze from the <require>s inside .html templates

This is not ideal, and makes switching between loaders and bundlers a rather large task. I realize switching build systems is not something you'd do very often, but another compelling reason to do this is that currently it's impossible to lint the dynamically included imports, since they're not statically analyzable (you'd only find out in runtime that you misspelled a moduleId). Plus, who wouldn't want to generate or update these configuration files automatically via some sort of a lint task or a bundler plugin?

My proposal is to add some sort of statically analyzable indicator to the code that a given string is in fact a module name.

My original idea was to do this with comments prefixing the actual moduleId (like:
/* @import */ './my-module', since they're the easiest to strip out when the code is minified, but that has some downsides as pointed out by @atsu85 in this comment: aurelia/skeleton-navigation#714 (comment).

The other idea that I thought about and @atsu85 described and expanded on here, is to use a static function which returns the moduleId. To give an example from the router of the skeleton-navigation:

Currently:

configureRouter(config: RouterConfiguration, router: Router) {
  config.title = 'Aurelia';
  config.map([
    {
      route: ['', 'welcome'], 
      moduleId: './welcome', // <== just a string, no way to analyze this and know it is a moduleId
      name: 'welcome',
      nav: true,
      title: 'Welcome'
    }
  ]);

  this.router = router;
}

Proposal using a static function on PLATFORM:

import {PLATFORM} from 'aurelia-pal';

configureRouter(config: RouterConfiguration, router: Router) {
  config.title = 'Aurelia';
  config.map([
    {
      route: ['', 'welcome'], 
      moduleId: PLATFORM.bundle('./welcome'),
      name: 'welcome',
      nav: true,
      title: 'Welcome'
    }
  ]);

  this.router = router;
}

Here, PLATFORM.bundle could simply return the first parameter './welcome'. Furthermore, whether using Gulp or Webpack, in production builds that call could easily be stripped out altogether, leaving only the actual string from the first parameter, so runtime wouldn't be affected.

An additional, positive benefit of this addition is that could also open the door to the possibility of increased security by obfuscating real moduleId paths if the same logic is implemented in the given bundler. Minifying these moduleIds would then also be an option. This could get complicated if the parameter is an expression (i.e. when concatenating a string with a variable PLATFORM.bundle('./thing/' + someId), but even that's doable (we'd minify/obfuscate only the statically analyzable part, and we can replace variables by automatically globbing that missing part of the string).

This would obviously not be a breaking change, but an additional layer of compatibility and metadata for various bundlers. Metadata, because the bundlers could use data passed in as a second parameter to that PLATFORM.bundle('./my-module', { someOptionsHere }) method to change behavior of the bundler. E.g. to split a given module out to a separate file, or to load it asynchronously, on demand only.

The alternative proposal is my original idea with "abusing" the comments right before a string literal happens, and then parsing those. It's a bit simpler to implement (because you don't need to transform anything, just parse comments, plus I already have an implementation for this ready), and it could look something like:

configureRouter(config: RouterConfiguration, router: Router) {
  config.title = 'Aurelia';
  config.map([
    {
      route: ['', 'welcome'], 
      moduleId: /* @import */ './welcome',
      name: 'welcome', nav: true, title: 'Welcome'
    },
    {
      route: 'users',
      moduleId: /* @import @lazy @chunk('some-chunk') */ './users',
      name: 'users', nav: true, title: 'Github Users'
    },
  ]);

  this.router = router;
}

Notice that the second route uses additional "decorators" like @lazy, or @chunk(...). Technically we could put anything we like there -- it's a comment, so it's a matter of parsing it to our liking.

Some downsides of putting things into comments vs using a function are:

• might be hard to track bugs / typos, since there would be no linting capabilities without writing yet another linter for comments
• no intellisense / autocomplete / typedoc

In either case, I bet we could cover 99% of use-cases, because most of those paths will either be static, string literal moduleIds, or with a globbable part (i.e. './something' + thing) which we can resolve statically. The 1% of times, where the developer does things like importing modules based on input generated by the user we would not be able to automatically resolve the right file, and only in those cases manual configuration would be required.

Note that bundle() is just a proposed name for the function, it could be moduleIdFor() or something else.

I'd love to hear your thoughts on the problem, and if you'd like to vote one of the ideas, react to this issue with an emoji:

• 👍 : if you're for the static function version of the proposal
• 😄 : if you're for the comment version
• 👎 : If you're against the idea altogether (explanation would be great)
• if you have a different / better idea, please comment :)

pal implementation for web/service workers

Following this discussion you may want to consider a PAL implementation specifically for web workers.

The requirement came up while trying to decorate a worker's class as transient.

setTimeout / setInterval

binding and the task queue may use setTimeout in some fallback scenarios. Should we add these methods to the PAL? Also: http://stackoverflow.com/questions/34841734/how-to-abstract-away-the-usage-of-browsers-window-object/34842796

Phantom JS errors out on aureliaPal.PLATFORM.performance.now

Error Message:
phantom stdout: TypeError: 'undefined' is not an object (evaluating '_aureliaPal.PLATFORM.performance.now')

I'm trying to run prerender.io locally. Which I have for the most part figured out, and is almost working. Prerender.io spins up phantom.js instances to render the page. It actually gets pretty far, but then it always manages to fail here. In other situations like this, I just created polyfills for phantom.js. However I really can't even see what tricky thing aureliaPal is trying to do to create a polyfill for it.

You can see my other polyfills here:
https://github.com/davidbfrogman/DBPAurelia/blob/master/src/3rdParty/phantompolyfill.js

For instance when I saw other errors in phantom.js it turned out that it didn't have a implementation for window.requestAnimationFrame. Found a polyfill, and fixed it.

I wish I could put together a better defect description than this. I hope this makes sense.

TypeScript's emitDecoratorMetadata produces client-only globals

I'm submitting a bug report

• Library Version:
  1.5.0

Please tell us about your environment:

• Operating System:
  Linux F26

• Node Version:
  8.9.4

• NPM Version:
  5.6.0

• JSPM OR Webpack AND Version
  webpack 3.11.0

• Browser:
  all

• Language:
  TypeScript 2.7.2

Current behavior:
I am using the emitDecoratorMetadata compiler option in my TypeScript application to leverage the @autoinject decorator where appropriate. The emitDecoratorMetadata option is currently producing browser-only globals. In the custom element below I have explicitly avoided using autoinject and instead manually injected DOM.Element - however it is still producing some decorator metadata which references the Element type:

Source

@inject(DOM.Element)
@customAttribute('zoom')
export class Zoom {
    element: Element;

    constructor(element: Element) {
        this.element = element;
    }

Transpiled

e = i([o.inject(o.DOM.Element), o.customAttribute('zoom'), r('design:paramtypes', [Element])], e);

---

I have also tried typing the element field as follows:

@inject(DOM.Element)
@customAttribute('zoom')
export class Zoom {
    element: DOM.Element;

    constructor(element: DOM.Element) {
        this.element = element;
    }

However this produces the following TypeScript error:

TS2503: Cannot find namespace 'DOM'.

Expected/desired behavior:

• What is the expected behavior?

There should be some mechanism for using DOM.Element as an actual property type in TypeScript, as then the emitted decorator metadata would align with the DOM.Element type in PAL and not the Element type from the browser.

Possibility to take AggregateError to `aurelia-exception` or something more generic?

Hi @EisenbergEffect,

AggregateError is more generic than pal and I would suggest to put it further down to a lower level module.
dependency-injection currently depends on pal because of it.
While pal is fairly generic, it still comes with specific ideology such as those in the Dom interface.

I want to use the dependency-injection module for my application but want to avoid getting pal along with it.

I understand it is not the intended usage of aurelia to just using the DI module, but would you consider doing this?

Thanks,
Unional

Platform.global implementation breaks Chrome Apps CSP

I'm submitting a bug report

• Library Version:
  1.3.0

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:
  Chrome Web Apps

• Language:
  all

Current behavior:
According to paulmillr/es6-shim#301 and https://github.com/tc39/proposal-global, our current implementation for finding the global will fail when run in Chrome Web Apps due to a CSP issue.

Expected/desired behavior:
For it to work in all possible environments

es6-shim uses the following:
var getGlobal = function () {
// the only reliable means to get the global object is
// Function('return this')()
// However, this causes CSP violations in Chrome apps.
if (typeof self !== 'undefined') { return self; }
if (typeof window !== 'undefined') { return window; }
if (typeof global !== 'undefined') { return global; }
throw new Error('unable to locate global object');
};

(pulled from https://github.com/tc39/proposal-global )

• What is the motivation / use case for changing the behavior?
  Allow Aurelia to work everywhere possible

moduleName() vs feature()

From my discussion with @EisenbergEffect I realized .feature() won't play along nicely with PLATFORM.moduleName(). Copy-pasting my description of the problem:

---

The idea so far was to use PLATFORM.moduleName('frob') to denote that the literal string 'frob' in code is actually a module name that is a direct dependency from the current file.
This is what the webpack build uses to properly trace all dependencies.
For users moving to this new system, the natural translation of .feature('frob') is going to be .feature(PLATFORM.moduleName('frob')).
But little will they realize that this documents a frob module dependency, when actually aurelia-loader is going to try to load frob/index.
This inconsistency (1) will not work; (2) can't be fixed in a pleasing way, even if you understand what happens.

---

Thoughts?
/CC @niieani

Missing d.ts file in most libraries

I'm not sure where to post this issues, as it applies to most of the new distros, but since it first appeared in this module I'll post it here.
We've been through the drama about what happened to aurelia-pal.d.ts, but the problem exists in most of the new distros, and I think it's quite a simple fix.
I know Microsoft recommend adding the typings attribute to the package.json, and NPM changes its behavior based on the moduleResolution settings, but a catch-all (which works in every case I've experienced so far) is to do the following:

• A file name module_name.d.ts is defined at the root of the package - Yes, that's not all that important, but it's the most common method, and causes no issues
• A file named index.d.ts is also created, containing export * from './module_name.d.ts'; which should keep all the node resolution users happy.

If we really don't want the definitions at the root, let's have a stub pointer called module_name.d.ts containing export * from './dist/whatever/module_name.d.ts';.

The key thing seems to be that the type definition source resolution works differently in different development environments, and the current method just doesn't work for many people, and forcing people to specify a particular moduleResolution in their package file will break usage of other modules.
I'm no guru on this stuff, but I am being badly impacted by it. We've now pretty much given up on webpack, particularly after seeing the CLI using RequireJS, but even the CLI versions won't compile unless the current typings configuration changes.

How to remove npm and jspm from my system.

I want remove all npm and jspm from my system. so I reInstall it properly.